feat(sdk): stage 6 — sub-composition scoped ids (F9)#1434
Open
vanceingalls wants to merge 1 commit into
Open
Conversation
Adds fully-qualified scoped ids for addressing elements inside inlined sub-compositions, so callers can target "hf-HOST/hf-LEAF" unambiguously even when bare hf-ids collide across sub-composition boundaries. Changes: - model.ts: resolveScoped() traverses id segments through nested subtrees; isNewHostBoundary() detects host boundaries (dcf ≠ parent dcf handles outerHTML innerRoot edge case) - types.ts: HyperFramesElement gains scopedId field - document.ts: buildElement carries scopePrefix, propagates childPrefix at host boundaries; buildRoots starts with "" - patches.ts: RFC 6902 escapeIdForPath / decodePathSegment for scoped ids containing "/"; all path builders and pathToKey/keyToPath updated - session.ts: getElement() matches by scopedId; find() returns scopedIds; orphan cleanup decodes RFC 6902 before key comparison, preserves removal markers, purges property sub-keys for both bare and scoped ids - mutate.ts: all element handlers use resolveScoped instead of findById; handleRemoveElement collects full subtree hf-ids before removal for complete GSAP animation cascade (Q3 fix); validateOp uses resolveScoped 20 new contract tests in session.subcomp.test.ts covering resolveScoped, scopedId propagation, dispatch to scoped targets, RFC 6902 patch encoding, override-set key format, orphan purge, and serialize stability. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This was referenced Jun 14, 2026
Collaborator
Author
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Implements F9: sub-composition scoped ids — a fully-qualified addressing scheme that lets callers target elements inside inlined sub-compositions unambiguously, even when bare
data-hf-idvalues collide across sub-comp boundaries.Design
After
inlineSubCompositionsflattens the tree, the DOM containsdata-composition-fileattributes that mark where each sub-composition's content begins. The SDK uses this to assign each element a scopedId: a/-joined chain of host ids ending in the bare leaf id.scopedId === id"hf-HOST/hf-LEAF"(any depth:"hf-A/hf-B/hf-LEAF")Host boundary detection (
isNewHostBoundary): an element is a new scope when it hasdata-composition-fileAND its value differs from its parent's. This correctly handles the outerHTML innerRoot edge case where both host and innerRoot share the same dcf value — only the HOST counts as the boundary.Changes
engine/model.tsresolveScoped()+isNewHostBoundary()types.tsHyperFramesElement.scopedId: stringdocument.tsbuildElementcarriesscopePrefix, detects host boundariesengine/patches.tsescapeIdForPath/decodePathSegmentfor scoped ids containing/; all path builders +pathToKey/keyToPathupdatedsession.tsgetElementmatches byscopedId;find()returnsscopedId; orphan cleanup decodes RFC 6902 before key compare; preserves removal markers, purges property sub-keysengine/mutate.tsresolveScopedinstead offindById;handleRemoveElementcollects full subtree hf-ids for GSAP cascade (Q3 fix);validateOpusesresolveScopedsession.subcomp.test.tsTest coverage (20 tests)
resolveScoped: bare id, scoped id, collision prevention, 3-level, null casesElementSnapshot.scopedId: top-level, sub-comp, host itself, 3-level, same sub-comp twice, outerHTML innerRootgetElementby scopedId,find()returns scopedIdsremoveElementserialize+re-openStack position
Stacked on PR #1432 (stage 5 — adapter exports), which is stacked on PR #1429.