Skip to content

Phase 31 slice D: desktop-app realisations and their gate - #248

Merged
vicmaster merged 7 commits into
masterfrom
phase-31-slice-d
Nov 15, 2026
Merged

vicmaster merged 7 commits into
masterfrom
phase-31-slice-d

Conversation

@vicmaster

Copy link
Copy Markdown
Owner

Slice D of Phase 31 (docs/specs/PHASE-31-SPEC.md, FR-D1 to FR-D3): starting points for application screens. On a desktop-app canvas, apply_structure now stamps a desktop-app layout built from the app primitives, held to a stricter gate than the web and mobile sets. The spec's "Slice D — contracts pinned before build" block records what the gate covers and four spec changes (S4 to S7); the "Slice D — as built" block records every decision the spec left open.

What changes

  • Six desktop-app realisations. Each is built only from primitives and tokens and fills the window: a sidebar of nav-items and panes that scroll on their own.
    • split-workbench-app: a header with a pane toggle, a work area and a detail panel.
    • list-detail-app: a searchable list and a detail pane with a designed "nothing selected" placeholder.
    • editor-inspector-app: a work area with a tool strip beside a 70/30 inspector of tabs and property rows.
    • browser-app: a filter bar over an adaptive grid of item cards whose titles are links.
    • dashboard-app: stat tiles, a trend chart and a table.
    • settings-app: grouped property rows, a danger zone and Cancel / Save.
    • list-detail, editor-inspector and browser exist only on desktop-app; on a web or phone canvas they are refused with the parameter that forces them.
  • Two desktop-app components. data-table-app keeps its toolbar, header, rows and pager at 32px, and skeleton-table-app is its loading state. On a desktop-app canvas, data-table and skeleton-table resolve to them, and the coverage hint for a missing loading state names skeleton-table-app.
  • A page stamp can set props on the root. The desktop-app realisations set the root's overflow to "hidden", which keeps the root at the window's height so long content scrolls inside its pane. A later page stamp with replace removes it again, unless the author changed it.
  • Stress reads a scrolling frame as scrolling, on every type. A frame with overflow: "auto" is now treated like a sheet panel: its vertical overflow is scrolling, not a clip. Its horizontal overflow still clips.
  • Stress lengthens app lists. On a desktop-app canvas, many and empty also act on runs of nav-items, tree rows, menu rows and property rows, and on card grids. Before, they touched nothing on an app screen, so it passed by default. A tripled list keeps one active row.
  • A property-row's label names its control. The "control has no text label" warning ignored the row's label, so every inspector toggle warned. With a blank label, only text inside the row itself counts, never a neighbouring row's text. This applies on every type.
  • Stamping a desktop-app primitive no longer seeds $accent-tint. Presets carry no tint, so a dark seed survived a later light preset and drew the active nav-item as a dark chip on a light page. Without the token, the renderer mixes the accent into whatever surface is applied.
  • Agent surfaces updated:
    • the server instructions and a new gotcha for application screens
    • the apply_structure, list_structures, canvas_create, canvas_stress and batch_design docstrings
    • docs/GUIDELINES.md: a new "Starting an application screen" section with what each stamp's coverage asks for
    • the README and VISION.md

Decisions worth a look

  1. The gate is stricter than the spec's text. A realisation must stamp with no warning, no error, no cliché tell and no desktop-app finding of any severity. That means canvas_evaluate says it is ready right after a stamp, unless coverage asks for a state variant. The web patterns already meet that bar. The inputs are the ones the docs promise an agent:
    • the five themes, with presets applied after the stamp as apply_preset does
    • every personality on three seeds, plus a design system inherited from the workspace
    • detailed mode, as stamped and with every list tripled
    • a clean stress run at 1440, 1280 and 1024 wide
    • data-table stamped into each realisation's wide pane at three widths
  2. Spec change S4 changes a web verdict. A frame with overflow: "auto" that overflows vertically used to be a stress warning on web. It now reads as scrolling, which is correct, but a static screenshot still shows it cut off. No web or mobile scaffold uses overflow: "auto", and the importer never produces it.
  3. Spec change S7. Five components that stamp on every type raise desktop-app infos, which never block, on an app canvas. A delta pill and an icon tile beside a label read as small buttons. These are held to warnings and errors, as FR-D3 says, rather than the any-severity rule the realisations meet.
  4. The scaffold token constants moved to src/structure-tokens.ts, so the desktop-app structures live in their own file without an import cycle. The values are unchanged.
  5. Known limits, left as found:
    • A labelled property-row whose control sits inside a wrapper frame still warns. This predates the slice and happens on every type.
    • data-table-app stamped into a 300px side panel or the inspector clips. The description and the docs say to put it in a wide pane.

Testing

  • test-patterns.ts (fast): the desktop-app gate. That is 8 structures × 18 inputs, each structure's coverage asks pinned, and twins that must fail on each part of the pass rule:
    • a second active nav-item
    • an unnamed icon button
    • a dark tint under the light preset
    • an info-level desktop-app finding
    • a cliché tell
  • New test-patterns-desktop.ts (Chrome) covers detailed mode and stress under every personality. After tripling, the root keeps its height, no row squashes, and content tripled twice scrolls inside a pane. It also checks the 1024×768 stamp. Twins cover a pane with overflow: "hidden", a root without the overflow prop, and a table that clips.
  • New test-patterns-desktop-window.ts (Chrome) covers stress at 1024 and 1280 wide and data-table in every wide pane.
  • New test-desktop-structures.ts (fast) covers the stress runs with their twins, the property-row label cases and the coverage hint.
  • Updated tests:
    • test-structures.ts: resolution on three types, root props, and the values the realisations must keep (pane width floors, 32px rows, the 240px grid minimum)
    • test-structures-mcp.ts: listing and stamping through the MCP handlers
    • test-scaffold-system.ts, test-discoverability.ts and test-desktop-primitives.ts
  • Verification, before the build: one agent tried to break the pinned gate on paper. It found 12 problems, including the false stress premise behind S4, list tripling that touched nothing on an app screen, and presets applied differently from apply_preset. All 12 were folded into the spec before the build.
  • Verification, first round: five agents on the first build.
    • Spec conformance found the inspector missing the button its user story names.
    • Mutation testing found every survivor that mattered in the gate's predicates and in values nothing pinned. Each now has an assertion.
    • Gate coverage found stress failing at 1280 and 1024 wide, and a table stamped into a pane tripping the depth advisory.
    • The docs audit found nine stale doc spots.
    • The cold reading found gaps in how a component is stamped into a state variant.
  • Second round: the fix diff confirmed every fix with no regression. It found one more gap, a table in a mid-width pane clipping, which was fixed and proved red before the fix and green after. No agent re-verified that last fix.
  • Full tier: 128/128 on the final commit.

Six desktop-app page realisations (split-workbench, list-detail,
editor-inspector, browser, dashboard, settings) plus data-table-app and
skeleton-table-app, gated in fast and detailed mode, under stress and at 1024px.
Scrolling frames read as scrolling under stress, app rows and card grids are
tripled on desktop-app, and a property-row's label names its control.
Realisations stay clean at 1280 and 1024 wide and with data-table stamped into
a pane, a blank property-row label falls back to text in the row, and the gate
gains twins for its predicates and the values it never pinned.
Its search sits in a shrinkable slot and the row count truncates, and the
window gate stamps the table into each pane at 1440, 1100 and 1024 wide.
Linux fonts wrap its column names in list-detail's 422px detail pane at 1024
wide, so the header outgrew its rows. The window gate stamps the table only
into panes at least 480px wide and pins the one pane it skips.
@vicmaster
vicmaster merged commit 95256d0 into master Nov 15, 2026
3 checks passed
@vicmaster
vicmaster deleted the phase-31-slice-d branch November 15, 2026 18:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant