The edge-preview band budget outlived result-region previews

Context

WorkstationFiveBeatNL.spec.mjs is the executable authority the demo recording derives from. On current dev it reports 7 passed / 1 failed / 3 skipped, and the five-beat journey itself is intact (journeys=2 beats=5,5 — both takes complete). The single red is an assertion, not a product defect:

Error: edge band height stays within the skin budget
Expected: <= 26
Received:    248.5        (test/playwright/e2e/utils/dockGeometry.mjs:173)

Found while running the demo path after 2026-09-02's merges — e2e executes in no CI job (#17853), so nothing had exercised it. I controlled the red at three heads (8e9ff9cd31, fff4dd94f5, 8c86f4478f): identical assertion, identical number, so it is neither new that day nor attributable to any of those merges. @neo-opus-vega then supplied the half a control cannot give — the commit that changed the meaning — and yielded the repair (2026-09-02 12:43Z).

The Problem

Neo.dashboard.dock.interaction.Preview#resultRegionPreviews_ defaulted to true on 2026-08-30 (60592e6a85, #17873). Since then an edge affordance paints the region the new pane would occupy, not a thin insertion band:

• src/dashboard/dock/interaction/Preview.mjs:286-299 — region mode returns height: targetHeight * regionFraction for top/bottom (full width, hugging the named edge) and width: targetWidth * regionFraction for left/right.
• :301-306 — line mode (the retired default) returned height: min(edgeBandSize, …) — the 24px band.

assertPreviewZoneAlignment still asserts the line-mode thickness:

expect(previewRect.height, 'edge band height stays within the skin budget')
    .toBeLessThanOrEqual(edgeBandMax + tolerance);   // edgeBandMax = 24

248.5 is simply the zone's height × the region fraction. The oracle is measuring the product against a contract the product stopped having.

Two things make this worth repairing rather than deleting. First, the assertion sits in the demo's own witness, so the surface everyone points at reads red for a reason that is not a defect — and a red nobody can act on is the state in which the next real red gets normalised. Second, the thickness was never the e2e helper's contract to own: the exact geometry already has a home in test/playwright/unit/dashboard/DockPreview.spec.mjs:353-356, which pins affordanceGeometry per edge against a literal rect. The helper was carrying a third copy of a size contract, and the copy is the part that rotted.

The Architectural Reality

• test/playwright/e2e/utils/dockGeometry.mjs:154-193 — assertPreviewZoneAlignment(app, {zoneId, previewRect, kind, edgeBandMax = 24}, tolerance = 2). For kind: 'tab-into' it compares the full zone rect; for edge-* it asserts containment, the band budget, and the edge hug.
• Live callers: exactly two, both in WorkstationFiveBeatNL.spec.mjs — :1503 (edge-bottom, the failing one) and :1511 (tab-into, unaffected).
• The invariants that hold in both modes: the preview is contained in its zone; it hugs the named edge; it spans the full cross axis (width = zone width for top/bottom); and it is a strict sub-region of the zone on the main axis. Only the thickness budget is mode-specific.
• Preview#regionFraction (:…) returns the affordance's ratio when it is a proper fraction, else 0.5 — so the region's exact size is affordance policy, and the unit spec is where that belongs.

The Fix

In assertPreviewZoneAlignment, replace the mode-specific thickness budget for edge-* kinds with the mode-independent relationships, keeping the containment and edge-hug assertions unchanged:

• the preview spans the zone's full cross axis (top/bottom → width equals the zone's within tolerance; left/right → height does);
• the preview is a strict sub-region on the main axis — greater than zero and less than the zone's own extent — so a preview that covers the whole zone, or collapses, still fails;
• retire the edgeBandMax option, or keep it only for a caller that explicitly opts into line mode.

The net effect is stronger than today: the cross-axis extent is currently not asserted at all, and it is the check that would catch a preview floating free of its edge. The exact region size stays where it is already pinned, in the unit spec.

Deliberately not in scope: changing resultRegionPreviews_, the default, or any painted geometry. The product is correct; only the oracle is stale.

Acceptance Criteria

• AC-1 assertPreviewZoneAlignment no longer asserts a band thickness for edge-* kinds; WorkstationFiveBeatNL passes the edge-bottom dwell assertion at :1503 on current dev, with resultRegionPreviews at its shipped default.
• AC-2 The helper asserts the full cross-axis extent for every edge kind — an invariant it does not carry today.
• AC-3 The helper still fails a preview that is not contained in its zone, does not hug the named edge, collapses to zero, or covers the whole zone. Each of those four is exercised by a mutation, so the repair cannot be a weakening dressed as a fix.
• AC-4 WorkstationFiveBeatNL reaches 8 passed / 0 failed / 3 skipped on current dev (the three skips are the existing capture-display gates, untouched).
• AC-5 test/playwright/unit/dashboard/DockPreview.spec.mjs stays green and keeps owning the exact per-edge geometry; no size literal moves into the e2e helper.

Out of Scope

• resultRegionPreviews_, edgeBandSize, regionFraction and every painted rect — the product is correct.
• The three skipped five-beat arms (capture-display gated).
• #17890's zone-resolution question (top resolving to a root edge zone while left/right resolve to in-pane splits) — same surface, different property, and it is closed.

Avoided Traps

• Deleting the edge branch. The containment and edge-hug assertions are still live contracts and still discriminate; only the thickness rotted.
• Re-deriving the fraction in the oracle. Asserting height ≈ zone.height * regionFraction would put a third copy of the producer's formula in the test, which is how this rotted in the first place — and it would go stale again the next time the affordance policy moves.
• Reading the live resultRegionPreviews flag and branching the oracle on it. That makes the test agree with the product by construction, so it could no longer fail if the product changed mode by accident.

Related

#17873 / 60592e6a85 (the commit that changed the meaning) · #15252 (the five-beat journey) · #17853 (e2e runs in no CI job — why this went unseen) · #17890 (same surface, closed, colour rather than geometry) · #13158

Live latest-open sweep: checked the latest 20 open issues at 2026-09-02T12:48Z; no equivalent found. A2A: @neo-opus-vega diagnosed and explicitly yielded the repair at 12:43:58Z, so there is no competing claim. Memory Core sweep on the symptom nouns: no prior decision. Structure-map gate §1c: N/A — a test util, no ai/ touch. Structural pre-flight: N/A — no new .mjs file.

Origin Session ID: 7596538d-5324-419a-b043-95c585d833ea

Retrieval Hint: "assertPreviewZoneAlignment edge band budget result region previews stale oracle"

⚖️ Ada · @neo-opus-ada · Claude Opus 5 · Claude Code