Skip to content

Phase 32 slice B: one tree for render and every rule - #256

Merged
vicmaster merged 6 commits into
masterfrom
phase-32-slice-b
Nov 20, 2026
Merged

vicmaster merged 6 commits into
masterfrom
phase-32-slice-b

Conversation

@vicmaster

Copy link
Copy Markdown
Owner

Phase 32 slice B (docs/specs/PHASE-32-SPEC.md, FR-B1 to FR-B4, with the contracts pinned in the spec's K1 to K7 block and the as-built notes L1 to L3).

The problem

A component instance used to be drawn without the design system. Variables were resolved first and instances were expanded afterwards, so a component's own nodes never got their $tokens, their control defaults or their state styles. A disabled button inside an instance rendered at full strength in the fallback blue. The checks were split three ways. Contrast, spacing, typography and cliché never looked inside instances at all, so faint text in a component raised nothing. The type rules and state checks did look inside, but at the unresolved tree. Icons and coverage used a third expander with a different id scheme.

What changed

  • One tree. A new src/expand.ts expandTree expands every instance (the instance's props and overrides applied) and then resolves tokens over the whole tree. The renderer, every canvas_evaluate category, canvas_stress, snapshot_layout, structural drift, the CLI and the viewer read it. The three old expanders are gone. renderToHtml still accepts a raw tree: when the tree still holds an instance, it expands the tree through the helper with the canvas's tokens and a new theme render option.
  • Ids inside instances. A node inside an instance renders and lays out as <instanceId>/<childId>, so two instances of one component never share an id, and detailed-mode rects match the findings. The instance root keeps its own id. Stored ids never contain /.
  • Findings inside an instance name it. One pass at the end of canvas_evaluate covers every category. A finding on a node inside an instance reports the instance in nodeId, the inner node in the new innerNodeId, and the instance and component in its message. It carries no fix, so canvas_autofix never emits an op for an id batch_design cannot address. The old advice saying "the design system never reaches" a component is gone, because now it does.
  • Comments. A viewer comment, or addFeedback, on a node inside an instance anchors on the instance.
  • Unknown icons stay one per origin. One bad icon in a component shown by two instances is still one finding, on the first instance.
  • Verify-round fixes. A stored icon no longer hides behind a component child with the same id. A comment on a made-up id under a real node still throws. export of a node inside an instance writes a flat file name. A component that holds an instance of itself now expands one level instead of overflowing the stack, which master also did.

Verdicts that moved

No pattern gate moved: test-patterns.ts, test-patterns-mobile.ts and test-patterns-desktop.ts pass at their existing bars. These pins moved, each to the behaviour this slice specifies:

Test Before Now
test-state-checks.ts R2 A focus ring inside a component used the #2563EB fallback and failed. The ring is the canvas's $focus-ring. It fails when that token fails, with a twin that passes.
test-state-checks.ts V4 and 3b A checkbox inside an instance warned, with advice that the tokens never reach it. It draws $border-strong and passes. A failing instance root is reported on its own id, and an info names the instance.
test-state-checks.ts grouped finding Old message wording New message, naming the instance and its component
test-mobile-rules-detailed.ts Detailed mode read a component's $space-* spacer as unresolved, so its content sat in the top inset. The spacer resolves to 60px and the content clears the inset. A 4px twin still fails.
test-components.ts Promotion rendered byte-identical HTML. Identical once the <instance>/ id prefix is removed: the look is unchanged and inner ids are expanded.
test-unknown-icons.ts "fix it in the component definition" Names the instance and the component, still one finding
test-element-states.ts, test-overlays.ts Labels said the fallbacks serve "a node inside a component". Relabelled: the fallbacks now serve only a raw, unresolved tree.

Tests

  • New test/unit/test-one-tree.ts holds FR-B1's render clause and FR-B2. The render clause: a disabled button inside an instance renders with the same markup and style as one outside, with and without state tokens. FR-B2: faint text inside an instance is one error with nodeId the instance, innerNodeId the text, and no fix; no fix op names an expanded id; feedback lands on the instance. The file also covers the verify-round edges.
  • New test/browser/test-one-tree-layout.ts: snapshot_layout gives the same child two ids in two instances, and canvas_stress names it the same way.
  • test/unit/test-discoverability.ts now checks that innerNodeId and the expanded-id form are documented on all three agent-facing surfaces.
  • Full tier: 145/145 locally. Type check of the tests is clean.
  • One verify round (an adversarial verifier on the spec and contracts) found nothing that breaks FR-B1 to FR-B4 or K1 to K7. It found three low-severity edges, fixed above. The docs-steward's proposals are applied.

Docs

The canvas_evaluate, snapshot_layout, canvas_stress, get_feedback and element-state docstrings, the INSTRUCTIONS, GUIDELINES (element states, components, the state rules, stress), README (the evaluate result, snapshot_layout, stress, feedback) and VISION (slice B ticked, plus the Phase 31 follow-up it closes).

@vicmaster
vicmaster merged commit a9cde03 into master Nov 20, 2026
3 checks passed
@vicmaster
vicmaster deleted the phase-32-slice-b branch November 20, 2026 18:45
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