ARCADIA-Studio/harness/state-label-layout-contract.md

State transition label layout

Derived presentation contract for issue #36, based on source 715036e132677dd2bc2fb37ed316d93dc9987aec. This follow-up is separate from the frozen September 24 prerelease. Implementation at 70bdcdf8fec1728e971cd90ad7f79a1df99777ff has scoped Windows test/build and native Save/reopen evidence, including an explicit restored-window input limitation. Integration status belongs to the issue.

Scope and decision

The reproduced external transition title Ready\nfor review occupies two lines, while the old painter reserved only one line before its summary External · Completion [request_ready]. Routing sized the box from the summary alone. The correction is one derived title/summary layout on routed labels in dedicated State projections. Other projections, State headers, action rows and internal-transition rows retain their existing layout.

The layout is prepared before label placement, so painting, collision avoidance, hit bounds, focus, previews and SVG share it. Core accepts a line-width measurement callback without a font dependency. Desktop consumers use the same Iced Paragraph font, size, shaping and line-height configuration as their canvas text. Core-only callers retain an explicitly approximate deterministic width fallback. No semantic model or serialized layout field is introduced.

Flattening line breaks would lose the authored presentation. Enlarging only the paint background would leave focus and selection inconsistent. A scalar-width estimate is insufficient for a width-dominating title such as 40 W characters. Dynamic node/row layout is outside this reproduced defect and would change unrelated State placement and group-editing contracts.

Excerpts and display lines

Keep the existing summary excerpt: at most 48 Unicode scalars of the original summary, taking 47 and an ellipsis when longer. EdgeLabelGeometry.text retains this raw excerpt. Typed usage visibility compares this original prefix with the original summary; normalization must never change the field offsets or expose text after the cutoff.

For compatibility, the title budget is fixed from the old summary width, before new measurement: floor((7*N+6)/6), where N is the retained raw summary's scalar count. Apply the existing whole-prefix-and-ellipsis rule to the raw title. This is a bounded excerpt, not a promise to retain breaks beyond its cutoff.

In each retained excerpt, CRLF is one display break; LF, bare CR, NEL, Unicode line separator and paragraph separator are also breaks. Tabs display as four spaces. These transformations do not modify source or raw usage provenance. Empty blocks have zero lines. Nonempty trailing and blank lines are preserved: A\n and \n each have two cells. A CR at an excerpt boundary is a break even if its LF was truncated.

Each line uses font size 10 and an explicit 12-unit line cell, without wrapping. The summary begins after all title cells. Width is the maximum measured displayed-line advance plus five units of padding on each side. Height is at least 24 units and otherwise 12 times the total line count. Lines start at (5, 12*index) relative to the shared box. Authored fraction, offset, center, attachments and waypoints remain unchanged. Automatic label positions may change because their obstacles are now accurate.

Hit ownership and consumers

The dedicated State canvas paints opaque label backgrounds after nodes and rows. Its ordinary hit test therefore checks those same rectangles before nodes/rows, in reverse label paint order. Padding and blank cells belong to the rectangle. Existing selected endpoint/bend handling remains earlier; path-distance ties, group admission and (placement, relation) row identities remain unchanged. Exposed adjacent row pixels still select that exact row. This deliberately does not model every crossing route-stroke pixel.

Scene routing, edge/group previews, usage/focus queries, generic canvas paths receiving a State plan and SVG all consume the measured plan. SVG emits explicit positions for each line and the same font-size declaration; exact appearance under an external viewer's substituted font is not guaranteed.

Acceptance

• Exact peer fixture: two title cells followed by one summary cell, readable and selectable at its last line, with full Project/source conservation.
• Bounds falsifiers: 40 W title characters and a fallback/combining-text case, plus blank lines and separators. Inspect actual native glyph containment; Paragraph advance alone is not a universal ink-overhang proof.
• Raw-prefix provenance across CRLF and multibyte text, typed fields at/after the cutoff, and duplicate names in unrelated prose.
• Label over node selects the Edge; adjacent exposed row keeps its StateRow identity; overlapping labels choose the last painted. Shift selection, mixed-group refusal and existing handles keep their contracts.
• Preview and settled scene bounds agree after movement; nonzero pan/zoom has no stale hit rectangle. Save/reopen and Undo/Redo preserve the independently declared source/model oracles.

Use meaningful automated checks and the actual Windows GUI. Linux is excluded by the user's current instructions. Publish verification and limitations with the implementation before closing #36.