feat(sdk,studio): editable template sub-compositions + promote sub-comp element properties

2026-09-04 07:19:52 +00:00 · 2026-07-09 13:31:04 -07:00
parent 7c144ecc30
commit 8de80bf369
19 changed files with 603 additions and 146 deletions
@@ -13,6 +13,7 @@ import type { ParsedDocument } from "./model.js";
 import {
  findById,
  findRoot,
+  declarationElement,
  setElementStyles,
  setOwnText,
  setGsapScript,
@@ -105,11 +106,11 @@ function parsePath(path: string): ParsedPath | null {
 * the matching declaration's `default`. No-ops when the attr/decl is absent.
 * Shares the model logic with mutate.ts via ./variableModel.ts.
 */
-function applyVariableDefault(document: Document, id: string, newDefault: unknown): void {
+function applyVariableDefault(declEl: Element | null, id: string, newDefault: unknown): void {
  if (newDefault === null) {
-    clearVariableDefault(document, id);
+    clearVariableDefault(declEl, id);
  } else {
-    writeVariableDefault(document, id, newDefault);
+    writeVariableDefault(declEl, id, newDefault);
  }
 }

@@ -263,13 +264,13 @@ function applyOne(parsed: ParsedDocument, patch: JsonPatchOp, p: ParsedPath): vo
    case "variableDeclaration": {
      if (!p.id) return;
      if (patch.op === "remove") {
-        removeVariableDeclarationEntry(parsed.document, p.id);
+        removeVariableDeclarationEntry(declarationElement(parsed.document, parsed.wrapped), p.id);
      } else if (isRawDeclarationEntry(patch.value)) {
        // Replay is faithful, not strict: inverse patches capture raw entries
        // (loose hand-authored declarations included) and undo must restore
        // them verbatim — gating on isCompositionVariable here would make
        // undo of a remove/update on a loose entry silently no-op.
-        writeVariableDeclaration(parsed.document, patch.value);
+        writeVariableDeclaration(declarationElement(parsed.document, parsed.wrapped), patch.value);
      }
      break;
    }
@@ -280,7 +281,11 @@ function applyOne(parsed: ParsedDocument, patch: JsonPatchOp, p: ParsedPath): vo
      // getVariables() returns the correct value in both preview and render.
      // CSS compat is handled by explicit style-path patches emitted by mutate.ts,
      // so we do NOT write CSS here — the style case above handles those patches.
-      applyVariableDefault(parsed.document, p.id, patch.op === "remove" ? null : patch.value);
+      applyVariableDefault(
+        declarationElement(parsed.document, parsed.wrapped),
+        p.id,
+        patch.op === "remove" ? null : patch.value,
+      );
      break;
    }

@@ -6,7 +6,7 @@
 */

 import { parseHTML } from "linkedom";
-import { ensureHfIds } from "@hyperframes/core/hf-ids";
+import { ensureHfIds, isCompositionTemplate } from "@hyperframes/core/hf-ids";

 export interface ParsedDocument {
  document: Document;
@@ -62,7 +62,7 @@ export function querySelectorAllDeep(root: Document | Element, selector: string)
  const walk = (parent: Element): void => {
    for (const child of Array.from(parent.children)) {
      if (child.tagName.toLowerCase() === "template") {
-        if (child.getAttribute("data-composition-id") !== null) walk(child);
+        if (isCompositionTemplate(child)) walk(child);
        continue;
      }
      if (child.matches(selector)) out.push(child);
@@ -164,10 +164,25 @@ export function isNewHostBoundary(el: Element): boolean {
  return dcf !== parentDcf;
 }

+/**
+ * The element that carries composition-level declarations
+ * (`data-composition-variables`). Full-document comps use `<html>`; a wrapped
+ * template/fragment comp has a synthetic `<html>` that serialize() strips, so
+ * its declarations must live on the composition root div (where values/metadata
+ * already live) to survive save.
+ */
+export function declarationElement(document: Document, wrapped: boolean): Element | null {
+  if (wrapped) return findRoot(document);
+  return (document as Document & { documentElement?: Element }).documentElement ?? null;
+}
+
 export function findRoot(document: Document): Element | null {
  return (
    document.querySelector("[data-hf-root]") ??
    document.getElementById("stage") ??
+    // Descend into a composition <template> so a wrapped template sub-comp
+    // resolves to its inner [data-composition-id] root, not the <template> shell.
+    querySelectorAllDeep(document, "[data-composition-id]")[0] ??
    document.body?.firstElementChild ??
    null
  );
@@ -21,6 +21,7 @@ import {
  resolveScoped,
  escapeHfId,
  findRoot,
+  declarationElement,
  getElementStyles,
  setElementStyles,
  toCamel,
@@ -869,9 +870,10 @@ function handleSetVariableValue(
 ): MutationResult {
  const root = findRoot(parsed.document);
  if (!root) return EMPTY;
+  const declEl = declarationElement(parsed.document, parsed.wrapped);

  const modelPath = variablePath(id);
-  const oldVarDefault = readVariableDefault(parsed.document, id);
+  const oldVarDefault = readVariableDefault(declEl, id);

  // Update the JSON model (B1 — drives the runtime) and keep the CSS custom
  // prop as secondary / compat for compositions that CSS-bind directly to
@@ -879,7 +881,7 @@ function handleSetVariableValue(
  // values (LOCKED §7) — cssCompatChange clears any stale scalar prop instead.
  // Emitting separate model + style patches keeps apply-patches.ts pure per
  // path type, so inverse patches restore the exact pre-call state.
-  writeVariableDefault(parsed.document, id, value);
+  writeVariableDefault(declEl, id, value);
  const modelP = valueChange(modelPath, oldVarDefault ?? null, value);
  const forward: JsonPatchOp[] = [modelP.forward];
  const inverse: JsonPatchOp[] = [modelP.inverse];
@@ -920,16 +922,18 @@ function cssCompatChange(
 }

 /**
- * Declaration ops require a real `<html>` in the source: fragment inputs get
- * a synthetic wrapper that serialize() strips, so a declaration written there
- * would silently vanish on save.
+ * Declaration ops need an element that survives serialize() to carry
+ * `data-composition-variables`. Full-document comps use `<html>`; wrapped
+ * template/fragment comps use their composition root div (the synthetic
+ * `<html>` is stripped on save). Only a wrapped input with no root element at
+ * all (an empty body) has nowhere durable to write.
 */
 function fragmentCompositionErr(parsed: ParsedDocument): CanResult | null {
-  if (!parsed.wrapped) return null;
+  if (declarationElement(parsed.document, parsed.wrapped)) return null;
  return canErr(
    "E_FRAGMENT_COMPOSITION",
    "Fragment compositions cannot carry variable declarations.",
-    "data-composition-variables lives on the <html> element — convert the composition to a full HTML document first.",
+    "The composition has no root element to hold data-composition-variables — add a composition root or convert to a full HTML document.",
  );
 }

@@ -982,13 +986,15 @@ function handleDeclareVariable(
  declaration: CompositionVariable,
 ): MutationResult {
  // Defensive re-check of can(): never write an invalid or duplicate
-  // declaration into the schema. Fragment sources have no <html> of their
-  // own — writing to the synthetic wrapper would be lost on serialize.
-  if (parsed.wrapped) return EMPTY;
+  // declaration into the schema. Resolve the element that survives serialize
+  // (root div for wrapped template comps, <html> otherwise); no element = a
+  // bare fragment where a declaration would be lost on save.
+  const declEl = declarationElement(parsed.document, parsed.wrapped);
+  if (!declEl) return EMPTY;
  if (!isCompositionVariable(declaration)) return EMPTY;
  if (!isValidVariableId(declaration.id)) return EMPTY;
-  if (findVariableDeclaration(parsed.document, declaration.id) !== undefined) return EMPTY;
-  if (!writeVariableDeclaration(parsed.document, declaration)) return EMPTY;
+  if (findVariableDeclaration(declEl, declaration.id) !== undefined) return EMPTY;
+  if (!writeVariableDeclaration(declEl, declaration)) return EMPTY;
  const path = variableDeclPath(declaration.id);
  const result: MutationResult = {
    forward: [patchAdd(path, declaration)],
@@ -1011,11 +1017,12 @@ function handleUpdateVariableDeclaration(
  id: string,
  declaration: CompositionVariable,
 ): MutationResult {
-  if (parsed.wrapped) return EMPTY;
+  const declEl = declarationElement(parsed.document, parsed.wrapped);
+  if (!declEl) return EMPTY;
  if (!isCompositionVariable(declaration) || declaration.id !== id) return EMPTY;
-  const old = findVariableDeclaration(parsed.document, id);
+  const old = findVariableDeclaration(declEl, id);
  if (old === undefined) return EMPTY;
-  writeVariableDeclaration(parsed.document, declaration);
+  writeVariableDeclaration(declEl, declaration);
  const p = valueChange(variableDeclPath(id), old, declaration);
  const result: MutationResult = { forward: [p.forward], inverse: [p.inverse] };

@@ -1039,10 +1046,11 @@ function handleUpdateVariableDeclaration(
 }

 function handleRemoveVariableDeclaration(parsed: ParsedDocument, id: string): MutationResult {
-  if (parsed.wrapped) return EMPTY;
-  const old = findVariableDeclaration(parsed.document, id);
+  const declEl = declarationElement(parsed.document, parsed.wrapped);
+  if (!declEl) return EMPTY;
+  const old = findVariableDeclaration(declEl, id);
  if (old === undefined) return EMPTY;
-  removeVariableDeclarationEntry(parsed.document, id);
+  removeVariableDeclarationEntry(declEl, id);
  const path = variableDeclPath(id);
  const result: MutationResult = {
    forward: [patchRemove(path)],
@@ -1671,7 +1679,12 @@ export function validateOp(parsed: ParsedDocument, op: EditOp): CanResult {
    case "declareVariable": {
      const preErr = declarationPreconditionErr(parsed, op.declaration);
      if (preErr) return preErr;
-      if (findVariableDeclaration(parsed.document, op.declaration.id) !== undefined)
+      if (
+        findVariableDeclaration(
+          declarationElement(parsed.document, parsed.wrapped),
+          op.declaration.id,
+        ) !== undefined
+      )
        return canErr(
          "E_DUPLICATE_VARIABLE",
          `Variable "${op.declaration.id}" is already declared.`,
@@ -1688,7 +1701,10 @@ export function validateOp(parsed: ParsedDocument, op: EditOp): CanResult {
          `declaration.id ("${op.declaration.id}") must match id ("${op.id}").`,
          "Variable ids are immutable — rename via removeVariableDeclaration + declareVariable.",
        );
-      if (findVariableDeclaration(parsed.document, op.id) === undefined)
+      if (
+        findVariableDeclaration(declarationElement(parsed.document, parsed.wrapped), op.id) ===
+        undefined
+      )
        return canErr(
          "E_VARIABLE_NOT_FOUND",
          `Variable "${op.id}" is not declared.`,
@@ -1699,7 +1715,10 @@ export function validateOp(parsed: ParsedDocument, op: EditOp): CanResult {
    case "removeVariableDeclaration": {
      const fragmentErr = fragmentCompositionErr(parsed);
      if (fragmentErr) return fragmentErr;
-      if (findVariableDeclaration(parsed.document, op.id) === undefined)
+      if (
+        findVariableDeclaration(declarationElement(parsed.document, parsed.wrapped), op.id) ===
+        undefined
+      )
        return canErr(
          "E_VARIABLE_NOT_FOUND",
          `Variable "${op.id}" is not declared.`,
@@ -1,6 +1,8 @@
 /**
 * Shared helpers for the composition variable JSON model
- * (`data-composition-variables` on `document.documentElement`).
+ * (`data-composition-variables`). The declaration-carrying element is resolved
+ * by the caller (`declarationElement` in model.ts): `<html>` for full-document
+ * comps, the composition root div for wrapped template/fragment comps.
 *
 * Single source for the parse → find-by-id → read/write/clear logic so the
 * forward-mutation path (engine/mutate.ts) and the patch-replay path
@@ -15,15 +17,10 @@ import type { CompositionVariable } from "@hyperframes/core/variables";
 // Exported so the SDK index can re-export it (kept from #2098's surface).
 export type VariableDecl = { id: string; default?: unknown; [key: string]: unknown };

-function getHtmlEl(document: Document): Element | null {
-  return (document as Document & { documentElement?: Element }).documentElement ?? null;
-}
-
 /** Parse the variable declaration array, or null when absent/invalid. */
-function readDecls(document: Document): { htmlEl: Element; arr: VariableDecl[] } | null {
-  const htmlEl = getHtmlEl(document);
-  if (!htmlEl) return null;
-  const raw = htmlEl.getAttribute("data-composition-variables");
+function readDecls(declEl: Element | null): { declEl: Element; arr: VariableDecl[] } | null {
+  if (!declEl) return null;
+  const raw = declEl.getAttribute("data-composition-variables");
  if (!raw) return null;
  let parsed: unknown;
  try {
@@ -32,7 +29,7 @@ function readDecls(document: Document): { htmlEl: Element; arr: VariableDecl[] }
    return null;
  }
  if (!Array.isArray(parsed)) return null;
-  return { htmlEl, arr: parsed as VariableDecl[] };
+  return { declEl, arr: parsed as VariableDecl[] };
 }

 function indexOfId(arr: VariableDecl[], id: string): number {
@@ -43,12 +40,11 @@ function indexOfId(arr: VariableDecl[], id: string): number {
 * Read the typed variable declarations from `data-composition-variables`.
 * Delegates to the canonical parser (same filter the render pipeline uses),
 * so malformed entries are dropped rather than surfaced. Returns `[]` when
- * the document has no root element or no declarations.
+ * the declaration element is absent or has no declarations.
 */
-export function readVariableDeclarations(document: Document): CompositionVariable[] {
-  const htmlEl = getHtmlEl(document);
-  if (!htmlEl) return [];
-  return parseCompositionVariables(htmlEl);
+export function readVariableDeclarations(declEl: Element | null): CompositionVariable[] {
+  if (!declEl) return [];
+  return parseCompositionVariables(declEl);
 }

 /**
@@ -56,8 +52,11 @@ export function readVariableDeclarations(document: Document): CompositionVariabl
 * Returns undefined when the attribute is absent, the JSON is invalid, or no
 * entry matches the id.
 */
-export function findVariableDeclaration(document: Document, id: string): VariableDecl | undefined {
-  const decls = readDecls(document);
+export function findVariableDeclaration(
+  declEl: Element | null,
+  id: string,
+): VariableDecl | undefined {
+  const decls = readDecls(declEl);
  if (!decls) return undefined;
  const idx = indexOfId(decls.arr, id);
  return idx < 0 ? undefined : decls.arr[idx];
@@ -67,7 +66,7 @@ export function findVariableDeclaration(document: Document, id: string): Variabl
 * Upsert a whole variable declaration by its id. Creates the
 * `data-composition-variables` attribute when absent; replaces an unparseable
 * attribute with a fresh single-entry array (the prior content was invisible
- * to every reader anyway). Returns false only when the document has no root
+ * to every reader anyway). Returns false only when there is no declaration
 * element to carry the attribute.
 *
 * Accepts raw (unvalidated) entries as well as typed declarations: the patch
@@ -76,12 +75,11 @@ export function findVariableDeclaration(document: Document, id: string): Variabl
 * would drop — or undo silently diverges from history.
 */
 export function writeVariableDeclaration(
-  document: Document,
+  declEl: Element | null,
  declaration: CompositionVariable | ({ id: string } & Record<string, unknown>),
 ): boolean {
-  const htmlEl = getHtmlEl(document);
-  if (!htmlEl) return false;
-  const decls = readDecls(document);
+  if (!declEl) return false;
+  const decls = readDecls(declEl);
  const arr = decls?.arr ?? [];
  const idx = indexOfId(arr, declaration.id);
  const entry: VariableDecl = { ...declaration };
@@ -90,7 +88,7 @@ export function writeVariableDeclaration(
  } else {
    arr[idx] = entry;
  }
-  (decls?.htmlEl ?? htmlEl).setAttribute("data-composition-variables", JSON.stringify(arr));
+  declEl.setAttribute("data-composition-variables", JSON.stringify(arr));
  return true;
 }

@@ -99,16 +97,16 @@ export function writeVariableDeclaration(
 * last declaration is removed (an empty `[]` is noise in authored HTML).
 * No-ops (returns false) when the attribute or the entry is absent.
 */
-export function removeVariableDeclarationEntry(document: Document, id: string): boolean {
-  const decls = readDecls(document);
+export function removeVariableDeclarationEntry(declEl: Element | null, id: string): boolean {
+  const decls = readDecls(declEl);
  if (!decls) return false;
  const idx = indexOfId(decls.arr, id);
  if (idx < 0) return false;
  decls.arr.splice(idx, 1);
  if (decls.arr.length === 0) {
-    decls.htmlEl.removeAttribute("data-composition-variables");
+    decls.declEl.removeAttribute("data-composition-variables");
  } else {
-    decls.htmlEl.setAttribute("data-composition-variables", JSON.stringify(decls.arr));
+    decls.declEl.setAttribute("data-composition-variables", JSON.stringify(decls.arr));
  }
  return true;
 }
@@ -117,8 +115,8 @@ export function removeVariableDeclarationEntry(document: Document, id: string):
 * Read the current `default` value for a variable id. Returns undefined when
 * the attribute is absent, the JSON is invalid, or no entry matches the id.
 */
-export function readVariableDefault(document: Document, id: string): unknown {
-  const decls = readDecls(document);
+export function readVariableDefault(declEl: Element | null, id: string): unknown {
+  const decls = readDecls(declEl);
  if (!decls) return undefined;
  const idx = indexOfId(decls.arr, id);
  return idx < 0 ? undefined : decls.arr[idx]?.default;
@@ -130,13 +128,17 @@ export function readVariableDefault(document: Document, id: string): unknown {
 * for undeclared variables, keeping the schema authoritative. Returns true when
 * the attribute was updated.
 */
-export function writeVariableDefault(document: Document, id: string, newDefault: unknown): boolean {
-  const decls = readDecls(document);
+export function writeVariableDefault(
+  declEl: Element | null,
+  id: string,
+  newDefault: unknown,
+): boolean {
+  const decls = readDecls(declEl);
  if (!decls) return false;
  const idx = indexOfId(decls.arr, id);
  if (idx < 0) return false; // variable not declared — don't auto-add
  decls.arr[idx] = { ...decls.arr[idx]!, default: newDefault };
-  decls.htmlEl.setAttribute("data-composition-variables", JSON.stringify(decls.arr));
+  decls.declEl.setAttribute("data-composition-variables", JSON.stringify(decls.arr));
  return true;
 }

@@ -147,22 +149,20 @@ export function writeVariableDefault(document: Document, id: string, newDefault:
 * default-less variable round-trips. No-ops when the decl or key is absent.
 * Returns true when the attribute was updated.
 */
-export function clearVariableDefault(document: Document, id: string): boolean {
-  const decls = readDecls(document);
+export function clearVariableDefault(declEl: Element | null, id: string): boolean {
+  const decls = readDecls(declEl);
  if (!decls) return false;
  const idx = indexOfId(decls.arr, id);
  if (idx < 0 || !(decls.arr[idx]! && "default" in decls.arr[idx]!)) return false;
  const { default: _drop, ...rest } = decls.arr[idx]!;
  decls.arr[idx] = rest as VariableDecl;
-  decls.htmlEl.setAttribute("data-composition-variables", JSON.stringify(decls.arr));
+  decls.declEl.setAttribute("data-composition-variables", JSON.stringify(decls.arr));
  return true;
 }

-/** All declared variables, or [] when the attribute is absent/invalid. */
-export function listVariableDecls(document: Document): VariableDecl[] {
-  return readDecls(document)?.arr ?? [];
-}
-
-// #2098's declareVariableDecl / removeVariableDecl removed in the #2098
-// reconciliation — the canonical writeVariableDeclaration / removeVariableDeclarationEntry
-// above are the single source; the edit ops route through those.
+// NOTE: #2098's Document-based helpers (listVariableDecls / declareVariableDecl /
+// removeVariableDecl) were removed in the #2098-reconciliation — they duplicated
+// the canonical declEl-based readVariableDeclarations / writeVariableDeclaration /
+// removeVariableDeclarationEntry below and predate template/fragment declaration
+// scope. The session conveniences (listVariables / removeVariable) delegate to
+// the canonical methods instead.
@@ -79,3 +79,48 @@ describe("template-based sub-comp compositions", () => {
    expect(comp.getElement("hf-dup")?.text).toBe("tpl");
  });
 });
+
+// The authored sub-comp form `hyperframes add` scaffolds: the composition id is
+// on the wrapped root div, and the <template> is keyed by `id="X-template"`.
+const AUTHORED_TEMPLATE_HTML = `
+<template id="card-template">
+  <div data-composition-id="card" data-width="1280" data-height="720" data-duration="5">
+    <h1 class="title" style="color: rgb(255, 0, 0)">Headline</h1>
+  </div>
+</template>
+`.trim();
+
+describe("authored template sub-comps (id on the wrapped root div)", () => {
+  it("enumerates and resolves inner elements", async () => {
+    const comp = await openComposition(AUTHORED_TEMPLATE_HTML);
+    const title = comp.getElements().find((e) => e.classNames.includes("title"));
+    expect(title).toBeTruthy();
+    expect(comp.getElement(title!.id)?.text).toBe("Headline");
+  });
+
+  it("declares a variable on the root div and round-trips through serialize", async () => {
+    const comp = await openComposition(AUTHORED_TEMPLATE_HTML);
+    comp.declareVariable({
+      id: "title-color",
+      type: "color",
+      label: "Title color",
+      default: "#ff0000",
+    });
+    expect(comp.getVariableDeclarations().map((d) => d.id)).toEqual(["title-color"]);
+    const serialized = comp.serialize();
+    expect(serialized).toContain("data-composition-variables");
+    // Survives a re-open (declaration is on the root div, not a stripped <html>).
+    const reopened = await openComposition(serialized);
+    expect(reopened.getVariableDeclarations().map((d) => d.id)).toEqual(["title-color"]);
+  });
+
+  it("does not treat a plain clone-source template as a composition", async () => {
+    const comp = await openComposition(
+      `<div data-composition-id="c" data-width="100" data-height="100" data-duration="1" data-start="0">` +
+        `<template id="particle"><span class="dot">·</span></template></div>`,
+    );
+    // The particle template's inner <span> must NOT be enumerated (it is cloned
+    // N times at runtime; a persisted inner id would duplicate across clones).
+    expect(comp.getElements().some((e) => e.classNames.includes("dot"))).toBe(false);
+  });
+});
@@ -35,8 +35,7 @@ import type { PersistAdapter, PreviewAdapter } from "./adapters/types.js";
 import { parseMutable } from "./engine/model.js";
 import type { ParsedDocument } from "./engine/model.js";
 import { applyOp, validateOp, type MutationResult } from "./engine/mutate.js";
-import { getGsapScript, resolveScoped } from "./engine/model.js";
-import { readVariableDefault, listVariableDecls } from "./engine/variableModel.js";
+import { getGsapScript, resolveScoped, declarationElement } from "./engine/model.js";
 import { extractGsapLabels } from "@hyperframes/core/gsap-parser-acorn";
 import { stripEmbeddedRuntimeScripts } from "@hyperframes/core/compiler/html-document";
 import { parseStartExpression } from "@hyperframes/core/runtime/start-expression";
@@ -167,12 +166,11 @@ class CompositionImpl implements Composition {
    this.dispatch({ type: "setVariableValue", id, value });
  }

-  // ── #2098 CRUD conveniences (coexist with the canonical surface below) ──
+  // ── #2098 CRUD conveniences — thin aliases over the canonical surface below.
+  // They delegate so the per-file declaration-element scope (template/fragment
+  // sub-comps included) is resolved in exactly one place.
  getVariableValue(id: string): string | number | boolean | FontValue | ImageValue | undefined {
-    // readVariableDefault genuinely can't narrow beyond unknown — the schema
-    // isn't validated at read time — so the cast lives here at the SDK
-    // boundary rather than pushing it onto every caller of getVariableValue.
-    return readVariableDefault(this.parsed.document, id) as
+    return this.getVariableValues()[id] as
      | string
      | number
      | boolean
@@ -182,10 +180,7 @@ class CompositionImpl implements Composition {
  }

  listVariables(): CompositionVariable[] {
-    // Same VariableDecl (index-signature) -> CompositionVariable (closed union)
-    // boundary cast as handleDeclareVariable — the model trusts the schema is
-    // well-formed rather than validating each decl's shape at read time.
-    return listVariableDecls(this.parsed.document) as unknown as CompositionVariable[];
+    return this.getVariableDeclarations();
  }

  removeVariable(id: string): void {
@@ -208,7 +203,7 @@ class CompositionImpl implements Composition {
  }

  getVariableDeclarations(): CompositionVariable[] {
-    return readVariableDeclarations(this.parsed.document);
+    return readVariableDeclarations(declarationElement(this.parsed.document, this.parsed.wrapped));
  }

  getVariableValues(overrides?: Record<string, unknown>): Record<string, unknown> {
@@ -220,9 +215,9 @@ class CompositionImpl implements Composition {
    // (core/runtime/getVariables.ts) additionally walks inlined sub-composition
    // declarers because it operates on the bundled multi-composition document;
    // the SDK models one composition file, so per-file scope is intended.
-    const documentEl =
-      (this.parsed.document as Document & { documentElement?: Element }).documentElement ?? null;
-    const defaults = readDeclaredDefaults(documentEl);
+    const defaults = readDeclaredDefaults(
+      declarationElement(this.parsed.document, this.parsed.wrapped),
+    );
    return { ...defaults, ...(overrides ?? {}) };
  }

@@ -107,14 +107,27 @@ describe("declareVariable", () => {
    expect(comp.getVariableDeclarations()).toEqual([TITLE_DECL]);
  });

-  it("refuses fragment compositions (no <html> to carry the schema)", async () => {
+  // fallow-ignore-next-line code-duplication
+  it("supports fragment compositions with a root element (schema on the root div)", async () => {
+    // A fragment (no <html>) still has a composition root; declarations live on
+    // that root div, which survives serialize — so template/sub-comp files are
+    // first-class editable, not refused.
    const comp = await openComposition(BARE_HTML);
+    expect(comp.can({ type: "declareVariable", declaration: TITLE_DECL })).toMatchObject({
+      ok: true,
+    });
+    comp.declareVariable(TITLE_DECL);
+    expect(comp.getVariableDeclarations()).toEqual([TITLE_DECL]);
+    expect(comp.serialize()).toContain("data-composition-variables");
+  });
+
+  it("refuses a fragment with no root element (nowhere durable to write)", async () => {
+    const comp = await openComposition("just text, no element");
    expect(comp.can({ type: "declareVariable", declaration: TITLE_DECL })).toMatchObject({
      ok: false,
      code: "E_FRAGMENT_COMPOSITION",
    });
    comp.declareVariable(TITLE_DECL);
-    // Nothing written, nothing lost on serialize.
    expect(comp.getVariableDeclarations()).toEqual([]);
    expect(comp.serialize()).not.toContain("data-composition-variables");
  });
@@ -329,6 +329,8 @@ describe("engine helper exports (resolveScoped, findById, escapeHfId, readVariab
    expect(findById(document as unknown as Document, "hf-title")).not.toBeNull();
    expect(resolveScoped(document as unknown as Document, "hf-title")).not.toBeNull();
    expect(escapeHfId('hf-"quoted"')).toBe('hf-\\"quoted\\"');
-    expect(readVariableDefault(document as unknown as Document, "never-declared")).toBeUndefined();
+    // readVariableDefault takes the declaration element (the <html>/root), not the Document.
+    const declEl = (document as unknown as Document).documentElement;
+    expect(readVariableDefault(declEl, "never-declared")).toBeUndefined();
  });
 });