Identify a promoted container without the hoisted children pointer

[nathanacurtis]

Problem

Render identifies a promoted container by the children pointer the capture side stamps on it. Once promotion stops stamping that pointer — because a promoted container's subtree stays nested in place rather than being hoisted behind a reference (#665) — nothing distinguishes a promoted container from a promoted text or glyph layer.

The consequence is that a frame captured from the Figma file renders back as a real component instance instead of a frame. Its children still land in the right place, so the result is visually close and degrades gracefully, but frame-to-frame fidelity is lost and the run warns.

This is a pre-existing gap being widened rather than a new one: an empty promoted frame already has no pointer today, so one carrying a consumed fill colour already mis-identifies as a glyph. Flattening widens the blast radius from empty frames to all promoted frames, which is what forces the fix.

Potential solution(s)

• Discriminate a promoted container by whether it has layout children, which the layout walk already knows
• Drop the pointer read rather than keeping it as a fallback. Composition output, including existing slot content and instance examples, is not being migrated in this release, so there is no older spec shape to stay compatible with — and keeping a second route to the same answer would only preserve the one that is going away
• With nothing reading it, the children pointer in the element extension can leave the capture side entirely, rather than being written and ignored

Acceptance criteria

• A promoted container whose subtree is nested in place renders back as a frame, not as a component instance
• A promoted text or glyph layer is unaffected
• No warning is emitted for a promoted container that renders correctly
• Nothing reads the children pointer to decide what a promoted element is

Case data

• Workspace: specs-testing — round-trip testing
• Territory: figma-from-specs
• Size: s

Notes

Required by #665 and deliberately out of its scope — the capture change is self-contained without it, and until this lands promoted containers render back as instances rather than frames, a known and graceful regression.

No backward compatibility is required. Composition output is allowed to break in this release and will not be migrated, so a spec carrying the old hoisted-pointer shape does not need to keep rendering.

One residue stays open after this: an empty promoted frame has neither a pointer nor layout children, so it remains undiscriminable. The durable answer is to record the promoted kind on the element extension, which is a schema change needing its own ADR. A weaker in-package stopgap keyed off a consumed layout style is container-exclusive but fails for a name-selected entry with an empty rule set, which consumes nothing (ADR-100). Noted as a boundary, not proposed.

---

Implementation details are tracked internally.

[nathanacurtis]

This issue's premise — that promotion stops stamping the children pointer "because a promoted container's subtree stays nested in place rather than being hoisted behind a reference (#665)" — is not true yet, and the change it depends on is not tracked anywhere.

#665 is closed and its capture work is genuinely done: a layout component authored as an instance, filling another's default slot, nests as a plain child with no reference between the levels. But a layout hierarchy authored as plain frames never reaches that path. Those frames are not instances when the anatomy is captured; they become component instances afterwards, during container promotion, which runs last and does not read the default-slot convention at all. For every promoted frame with children it still hoists the subtree into a fresh slot-content entry, points a reference at it, and then repeats the whole thing on that new entry — so the binding chain reproduces itself one level at a time.

Three consequences worth recording here:

• A component whose examples are built from promoted layout frames still emits the deep reference chain ADR-099 exists to remove. On one card component in the testing workspace that is ~45 slot-content entries where the structure needs ~9, which is the condition MVP: Default slots to simplify spec examples, layouts and bindings #665's last acceptance criterion ("no larger in registry entries than the structure requires") was meant to rule out.
• MVP: Default slots to simplify spec examples, layouts and bindings #665 scoped itself to compositions, so its closure is not wrong — the gap sits on the component path, which it never claimed. But nothing currently owns converting promotion to the flattened shape.
• This issue stays blocked until that lands. Removing the pointer read before promotion stops writing the pointer would break demotion for every promoted container, flattened or not.

Also relevant to the third bullet in Potential solution(s): once nothing reads it, the pointer can leave the capture side entirely — but that removal belongs after this issue, not before it.

One correction to carry over from #665, since it was repeated from the same source: its note "This is new work, not a defect … Start from the ADR rather than hunting for a bug that explains the current output" is wrong for the promotion path. ADR-099 is implemented end to end, including capture-side flattening and the marker; there is a specific, locatable defect, and the fix is a net deletion rather than a redesign.

[nathanacurtis]

Blocker filed: #681 — flatten a promoted container's subtree in place instead of hoisting it behind a reference.

This issue's premise is "once promotion stops stamping the pointer," and #681 is what stops it. It attributes that to #665, which is closed and delivered only the capture-side half for instances the designer placed directly; promoted containers were never converted.

Order, so nothing breaks in between:

1. Flatten a promoted container's subtree in place instead of hoisting it behind a reference #681 — promotion flattens, and stops writing the pointer into propConfigurations
2. this issue — render discriminates a promoted container by whether it has layout children, and the pointer read goes away
3. only then — remove the extension-side pointer write

Removing the extension write before step 2 breaks demotion for every promoted container, flattened or not.

[nathanacurtis]

Fixed, alongside its blocker #681.

A promoted container is now identified by either signal: a hoisted children pointer, or children nested under it in the layout — which the layout walk already knows and is the only evidence the flattened shape leaves.

One correction to this issue's premise

This issue assumed promotion would stop writing the pointer outright, so the read could be dropped. It cannot. #681 made flattening conditional on the default-slot convention, so the hoisted shape is still exactly what a workspace declaring no convention produces. The pointer is a second live shape, not a legacy one.

So the acceptance criterion "nothing reads the children pointer to decide what a promoted element is" is not met, and should not be — the pointer keeps precedence, and the extension-side write stays. Everything else holds:

• a promoted container whose subtree is nested in place renders as a frame, not an instance
• a promoted text or glyph layer is unaffected
• no warning for a promoted container that renders correctly
• nothing reads the pointer — withdrawn, see above

No back-compat machinery was added. demoteContainer stays because its shape is current, not because old specs need it.

Residue, unchanged

An empty promoted frame has neither a pointer nor layout children, so it remains undiscriminable and falls through to the leaf tests. Pre-existing, asserted explicitly in a test so the boundary is visible rather than implied. The durable answer is still a kind marker on the element extension, which needs its own ADR.

4 new tests covering: frame rendered and filled by the walk, nesting to depth, the pointer branch still chosen when a pointer is present, and the empty-frame boundary. 239 tests in the package, all green.

Verified by round trip — the fixture comes back identical across anatomy, layout, the instance's binding, and the referenced entry.