docs(sdk): document attachSync, variable CRUD, and getRootElements/getAllAnimationIds

[vanceingalls]

What

Fills in three SDK reference-doc gaps that had fallen behind the actual public API:

• docs/sdk/reference/composition.mdx: adds getVariableValue, listVariables, declareVariable, removeVariable (Typed edit methods) and getRootElements, getAllAnimationIds (Query section).
• docs/sdk/reference/adapters.mdx: adds attachSync to the PreviewAdapter interface listing, plus a ParamField documenting its contract — immediate override sync on attach, ongoing patch-event mirroring (including undo/redo), the /script/* exclusion, and detach semantics.
• docs/sdk/reference/edit-operations.mdx: adds declareVariable/removeVariable rows and dispatch examples to the ## Variables op table (previously only setVariableValue was listed).

Why

Every doc-facing API this stack shipped was undocumented:

• attachSync (this stack, feat(sdk): attachSync mirrors composition edits onto a live document #2100) had zero mentions anywhere in the docs — the entire feature was invisible to anyone reading the SDK reference.
• declareVariable, removeVariable, getVariableValue, listVariables (feat(sdk): variable CRUD (declare/remove/get/list) + export gaps #2098) were real public Composition methods with no corresponding reference entries.
• getRootElements (feat(sdk): export getRootElements/isNewHostBoundary/bareId, fix relative data-start #2092) was missing from the Query section.
• getAllAnimationIds was also missing — a pre-existing gap unrelated to this stack, filled in while touching the same section.

How

Matched each file's existing conventions exactly rather than introducing new patterns:

• composition.mdx: same ### \methodName`` + signature code block + prose + example pattern as every other method in the file.
• adapters.mdx: same <ParamField> block style already used for elementAtPoint/applyDraft/etc.
• edit-operations.mdx: same table-row + dispatch-example pattern as the existing setVariableValue entry.

No code changes — docs only.

Test plan

• Verified code-fence balance across all three edited files (no broken/unclosed blocks)
• Cross-checked every documented signature against the current packages/sdk/src/types.ts Composition/PreviewAdapter interfaces to ensure accuracy
• Documentation updated (this PR is the documentation update)

[vanceingalls]

• docs(sdk): document attachSync, variable CRUD, and getRootElements/getAllAnimationIds #2108 👈 (View in Graphite)
• feat(sdk): attachSync mirrors composition edits onto a live document #2100
• feat(sdk): variable CRUD (declare/remove/get/list) + export gaps #2098
• fix(studio-server): previewAdapter getElementTimings ignores relative data-start refs #2097
• fix(core): applyPositionEdits fails silently across iframe realms #2096
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[miga-heygen]

LGTM — thorough and accurate docs update.

I cross-checked every documented signature against the current source:

• Composition methods (getVariableValue, listVariables, declareVariable, removeVariable, getRootElements, getAllAnimationIds): all match packages/sdk/src/types.ts.
• PreviewAdapter.attachSync: signature matches adapters/types.ts, behavioral description matches adapters/iframe.ts implementation (immediate override sync → patch subscription → /script/* exclusion).
• CompositionVariable union in types.mdx: all seven variants match packages/parsers/src/types.ts field-for-field, including FontVariable's default_name/default_source.
• EditOp additions: declareVariable/removeVariable match the source union.
• Utility functions: all six verified exported from sdk/src/index.ts with matching signatures.
• readVariableDefault: correctly typed as unknown (the raw document-level return), with appropriate guidance to prefer the typed Composition method in session code.

Convention adherence is clean — each file follows its own existing patterns. The canvas-integration.mdx guide section contextualizes attachSync well without duplicating the reference docs.

No accuracy issues, no missing fields, no broken references.

— Miga

[james-russo-rames-d-jusso]

Reviewed at f76eeb5.

Docs-only, catching up the reference to what the SDK-gap stack shipped. Verified every documented signature/type/export against HEAD — this reads correctly:

• 6 Composition methods (getVariableValue, listVariables, declareVariable, removeVariable, getRootElements, getAllAnimationIds) match packages/sdk/src/types.ts:397-533 verbatim (names, params, return types, JSDoc intent).
• PreviewAdapter.attachSync(comp: Composition): () => void matches packages/sdk/src/adapters/types.ts:57-87; the guide-side note that it also handles undo/redo (both flow through the same patch event) and swap-composition (auto-detach previous) is accurate against iframe.ts:752-786. The docs' broader /script/* phrasing is actually ahead of the interface's own docstring (which only mentions /script/gsap) — the runtime filter is p.path.startsWith("/script/") at iframe.ts:776, so types.ts's docstring is the one that's slightly stale, not this PR.
• EditOp variants declareVariable / removeVariable match the union at packages/sdk/src/types.ts:120-121.
• CompositionVariable union in types.mdx is a verbatim copy of packages/parsers/src/types.ts:153-233 (all 7 variants + type-specific fields).
• Utility imports all resolve at HEAD: resolveScoped, findById, bareId, escapeHfId, isNewHostBoundary root-exported from packages/sdk/src/index.ts:29; readVariableDefault root-exported at :31. No subpath-imports in code samples to check.
• removeVariable's data-var-* DOM-refs untouched claim in composition.mdx is lifted verbatim from mutate.ts:924-925's handler docstring — matches semantics.

Nits

• 🟡 PR body scope understates the diff. The "What" section calls out 3 files (composition.mdx / adapters.mdx / edit-operations.mdx) but the PR also touches types.mdx (+101, adds the CompositionVariable type reference), utilities.mdx (+66, adds id/scope utils + readVariableDefault), and guides/canvas-integration.mdx (+17, adds the attachSync guide section) — all good additions, worth naming in the body so future-you / follow-up reviewers know the full surface without re-reading the diff.

Questions

• 🟡 findById framing. Docs describe it as "thin alias for resolveScoped kept for call-site clarity where 'find' reads better than 'resolve.' Identical behavior." — accurate on behavior, but engine/model.ts:31-37's own comment frames the reason it's kept as a shared surface: patch-replay (undo/redo, override-set apply) and forward dispatch have to resolve ids the SAME way, or they disagree on which duplicate a bare id targets and undo reverts the wrong element. Optional whether that belongs in public-API docs vs. internal comments — flagging in case you want to promote it, since it's the load-bearing invariant behind having two names for the same behavior.

What I didn't verify

• Rendered Mintlify output — verified against source markup only.
• Doc-typecheck harness (if any) that would catch a signature-drift between the docs and the SDK at CI time. If there isn't one, the doc drift that #1817's rubric catches is still a manual-review problem.

CI green. Ready from where I sit.

— Review by Rames D Jusso

[jrusso1020]

Docs-only, verified at head f169d5fa. Independently checked every documented signature against source (the SDK stack I just reviewed at HEAD):

• getVariableValue(id): string | number | boolean | FontValue | ImageValue | undefined — matches session.ts (the tightened union, not unknown).
• listVariables(): CompositionVariable[], declareVariable(decl: CompositionVariable): void, removeVariable(id: string): void — match.
• attachSync(comp: Composition): () => void — matches the PreviewAdapter interface; the /script/* "any future path" phrasing is correct against the runtime's startsWith("/script/") (more precise than the interface's own docstring).
• Both EditOp variants + the 6 root exports (incl. readVariableDefault(...): unknown) — match index.ts.

CI clean (Preflight skips as docs-only; only Graphite mergeability pending). RDJ's two nits (PR body scope, findById framing) are optional. LGTM.

The base branch was changed.