@hyperframes/parsers 0.7.45 → 0.7.47

package/dist/hfIds.d.ts

@@ -14,12 +14,16 @@ declare const EXCLUDED_TAGS: Set<string>;
  */
 declare function mintHfId(el: Element, assigned: Set<string>): string;
 /**
- * True for a `<template data-composition-id>` — the sub-composition authoring
- * pattern whose content the studio preview unwraps into the served body. Only
- * these templates are treated as transparent containers for hf-id purposes.
- * A plain `<template>` (runtime clone-source: list item, particle, etc.) must
- * NOT get inner ids: its content is cloned N times into the live DOM, so a
- * persisted inner id would be duplicated across every clone.
+ * True for a sub-composition authoring template whose content the studio preview
+ * unwraps into the served body. Two accepted forms:
+ *   A) `<template data-composition-id="X">…` — the id on the template itself.
+ *   B) `<template id="X-template"><div data-composition-id="X">…` — the id on the
+ *      wrapped root div (the form `hyperframes add` scaffolds and registry blocks use).
+ * Only these are treated as transparent containers for hf-id purposes. A plain
+ * `<template>` (runtime clone-source: list item, particle, etc.) must NOT get
+ * inner ids — its content is cloned N times into the live DOM, so a persisted
+ * inner id would be duplicated across every clone. Form B is distinguished from
+ * a clone-source by the presence of a direct `[data-composition-id]` child.
  */
 declare function isCompositionTemplate(el: Element): boolean;
 declare function ensureHfIds(html: string): string;

package/dist/hfIds.js

@@ -49,7 +49,12 @@ function mintHfId(el, assigned) {
   return id;
 }
 function isCompositionTemplate(el) {
-  return el.tagName.toLowerCase() === "template" && el.getAttribute("data-composition-id") !== null;
+  if (el.tagName.toLowerCase() !== "template") return false;
+  if (el.getAttribute("data-composition-id") !== null) return true;
+  for (const child of Array.from(el.children)) {
+    if (child.getAttribute("data-composition-id") !== null) return true;
+  }
+  return false;
 }
 function walkElements(root, visit) {
   for (const child of Array.from(root.children)) {

package/dist/hfIds.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/hfIds.ts"],"sourcesContent":["/**\n * Stable hf- element id minting (R1). Node-safe (linkedom only, not browser DOM).\n *\n * Two surfaces share these helpers:\n *  - ensureHfIds(html): node-id surface — mints data-hf-id on every element.\n *  - mintHfId(el, assigned): shared by htmlParser for clip ids.\n *\n * Hash is CONTENT ONLY (tag + sorted attrs + own text) — no sibling position,\n * so inserting a non-identical sibling never shifts another element's id.\n */\nimport { parseHTML } from \"linkedom\";\n\n// Non-editable / non-visual elements that should never receive a stable id.\nexport const EXCLUDED_TAGS = new Set([\n  \"script\",\n  \"style\",\n  \"template\",\n  \"meta\",\n  \"link\",\n  \"noscript\",\n  \"base\",\n]);\n\n// 32-bit FNV-1a. Pure, deterministic, no crypto, no Math.random.\nfunction fnv1a(str: string): number {\n  let h = 0x811c9dc5;\n  for (let i = 0; i < str.length; i++) {\n    h ^= str.charCodeAt(i);\n    h = Math.imul(h, 0x01000193);\n  }\n  return h >>> 0;\n}\n\n// 4 base-36 chars · 36^4 ≈ 1.68M ids per document. Birthday-paradox collision\n// ≈ N²/(2·36^4): well under 1% per document after dup rehash at realistic\n// clip-model sizes (≤ a few hundred elements). The dup-rehash in mintHfId\n// resolves the rare collision; width is deliberately small for readable ids.\nfunction toHfId(hash: number): string {\n  const s = (hash >>> 0).toString(36);\n  // Use suffix (most-avalanched bits) for better distribution within the 4-char window.\n  const four = s.length >= 4 ? s.slice(-4) : s.padStart(4, \"0\");\n  return `hf-${four}`;\n}\n\n// Element's own direct text (TEXT_NODE children), not descendants'.\nfunction ownText(el: Element): string {\n  let text = \"\";\n  el.childNodes.forEach((n) => {\n    if (n.nodeType === 3) text += (n as Text).nodeValue ?? \"\";\n  });\n  return text.trim();\n}\n\nfunction contentKey(el: Element): string {\n  // Exclude all data-hf-* attrs (ids, studio state) — they must not influence the hash.\n  // Use \\x00 / \\x01 separators (invalid in HTML attrs) to prevent ambiguous serialization.\n  const attrs = Array.from(el.attributes)\n    .filter((a) => !a.name.startsWith(\"data-hf-\"))\n    .map((a) => `${a.name}\\x00${a.value}`)\n    .sort()\n    .join(\"\\x01\");\n  return `${el.tagName.toLowerCase()}|${attrs}|${ownText(el)}`;\n}\n\n/**\n * Collision tiebreak for byte-identical siblings: document-order dup counter\n * (`hash(key#N)`). This IS order-dependent — two identical `<span></span>`\n * get different ids based on which comes first in the DOM. This is unavoidable:\n * unique ids for byte-identical elements require a positional signal.\n *\n * Why this is safe in practice: once `ensureHfIds` write-back persists\n * `data-hf-id` to source the attribute is physically bound to its element.\n * Reordering identical siblings carries the attribute along → zero\n * order-dependence post-persist. `ensureHfIds` skips pinned elements\n * (`if (el.getAttribute(\"data-hf-id\")) continue`), so normal operation\n * never re-exposes the ordering after first persist.\n */\n// WIRE CONTRACT: id minting is content-keyed (FNV1a of innerHTML + tag). R7's\n// preview route relies on mintHfId producing identical ids across mint contexts\n// (disk-persist pass vs. in-memory bundle pass) — see preview.test.ts\n// \"bundle returning untagged HTML gets same ids as disk\". Any change that adds\n// positional, session, or random input to the hash breaks that invariant and\n// makes hf- ids diverge between disk and served HTML, silently corrupting\n// drag-to-edit targeting.\nexport function mintHfId(el: Element, assigned: Set<string>): string {\n  const key = contentKey(el);\n  let id = toHfId(fnv1a(key));\n  let dup = 0;\n  while (assigned.has(id)) {\n    dup += 1;\n    // Graceful fallback instead of a hard throw: rehashing only fails to find a\n    // free 4-char slot in a pathological document (~1.6M identical elements).\n    // Rather than crash the whole parse, widen the id with the dup counter —\n    // still deterministic and unique, just longer than the 4-char norm.\n    if (dup > 10000) {\n      id = `hf-${(fnv1a(key) >>> 0).toString(36)}-${dup}`;\n      break;\n    }\n    id = toHfId(fnv1a(`${key}#${dup}`));\n  }\n  assigned.add(id);\n  return id;\n}\n\n/**\n * True for a `<template data-composition-id>` — the sub-composition authoring\n * pattern whose content the studio preview unwraps into the served body. Only\n * these templates are treated as transparent containers for hf-id purposes.\n * A plain `<template>` (runtime clone-source: list item, particle, etc.) must\n * NOT get inner ids: its content is cloned N times into the live DOM, so a\n * persisted inner id would be duplicated across every clone.\n */\nexport function isCompositionTemplate(el: Element): boolean {\n  return el.tagName.toLowerCase() === \"template\" && el.getAttribute(\"data-composition-id\") !== null;\n}\n\n/**\n * Document-order walk of every element under `root`, descending into\n * composition `<template>` subtrees — linkedom's querySelectorAll does not, so\n * template-based sub-comps would otherwise never get inner ids (the preview\n * unwraps the template and stamps the SAME content, so skipping here splits\n * the id space between the served DOM and the raw file). Plain templates are\n * skipped entirely (see isCompositionTemplate).\n */\nfunction walkElements(root: Element, visit: (el: Element) => void): void {\n  for (const child of Array.from(root.children)) {\n    const isTemplate = child.tagName.toLowerCase() === \"template\";\n    if (isTemplate && !isCompositionTemplate(child)) continue;\n    visit(child);\n    walkElements(child, visit);\n  }\n}\n\nexport function ensureHfIds(html: string): string {\n  // Mirror parseSourceDocument's fragment-wrapping so bare fragments don't land\n  // outside <body> in linkedom, which would cause body.querySelectorAll to return [].\n  const hasDocumentShell = /<!doctype|<html[\\s>]/i.test(html);\n  const wrapped = !hasDocumentShell;\n  const { document } = wrapped\n    ? parseHTML(`<!DOCTYPE html><html><head></head><body>${html}</body></html>`)\n    : parseHTML(html);\n  const body = document.body;\n  if (!body) return html;\n\n  const assigned = new Set<string>();\n  // Seed with already-present ids (pin) so fresh mints never collide with them.\n  // Scope to <body> to match the mint walk below — a stray data-hf-id in <head>\n  // must not pin an id into the set that a body element would then be bumped off.\n  walkElements(body, (el) => {\n    const existing = el.getAttribute(\"data-hf-id\");\n    if (existing) assigned.add(existing);\n  });\n\n  walkElements(body, (el) => {\n    if (EXCLUDED_TAGS.has(el.tagName.toLowerCase())) return;\n    if (el.getAttribute(\"data-hf-id\")) return; // pinned\n    el.setAttribute(\"data-hf-id\", mintHfId(el, assigned));\n  });\n\n  return wrapped ? document.body.innerHTML || \"\" : document.toString();\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/hfIds.ts"],"sourcesContent":["/**\n * Stable hf- element id minting (R1). Node-safe (linkedom only, not browser DOM).\n *\n * Two surfaces share these helpers:\n *  - ensureHfIds(html): node-id surface — mints data-hf-id on every element.\n *  - mintHfId(el, assigned): shared by htmlParser for clip ids.\n *\n * Hash is CONTENT ONLY (tag + sorted attrs + own text) — no sibling position,\n * so inserting a non-identical sibling never shifts another element's id.\n */\nimport { parseHTML } from \"linkedom\";\n\n// Non-editable / non-visual elements that should never receive a stable id.\nexport const EXCLUDED_TAGS = new Set([\n  \"script\",\n  \"style\",\n  \"template\",\n  \"meta\",\n  \"link\",\n  \"noscript\",\n  \"base\",\n]);\n\n// 32-bit FNV-1a. Pure, deterministic, no crypto, no Math.random.\nfunction fnv1a(str: string): number {\n  let h = 0x811c9dc5;\n  for (let i = 0; i < str.length; i++) {\n    h ^= str.charCodeAt(i);\n    h = Math.imul(h, 0x01000193);\n  }\n  return h >>> 0;\n}\n\n// 4 base-36 chars · 36^4 ≈ 1.68M ids per document. Birthday-paradox collision\n// ≈ N²/(2·36^4): well under 1% per document after dup rehash at realistic\n// clip-model sizes (≤ a few hundred elements). The dup-rehash in mintHfId\n// resolves the rare collision; width is deliberately small for readable ids.\nfunction toHfId(hash: number): string {\n  const s = (hash >>> 0).toString(36);\n  // Use suffix (most-avalanched bits) for better distribution within the 4-char window.\n  const four = s.length >= 4 ? s.slice(-4) : s.padStart(4, \"0\");\n  return `hf-${four}`;\n}\n\n// Element's own direct text (TEXT_NODE children), not descendants'.\nfunction ownText(el: Element): string {\n  let text = \"\";\n  el.childNodes.forEach((n) => {\n    if (n.nodeType === 3) text += (n as Text).nodeValue ?? \"\";\n  });\n  return text.trim();\n}\n\nfunction contentKey(el: Element): string {\n  // Exclude all data-hf-* attrs (ids, studio state) — they must not influence the hash.\n  // Use \\x00 / \\x01 separators (invalid in HTML attrs) to prevent ambiguous serialization.\n  const attrs = Array.from(el.attributes)\n    .filter((a) => !a.name.startsWith(\"data-hf-\"))\n    .map((a) => `${a.name}\\x00${a.value}`)\n    .sort()\n    .join(\"\\x01\");\n  return `${el.tagName.toLowerCase()}|${attrs}|${ownText(el)}`;\n}\n\n/**\n * Collision tiebreak for byte-identical siblings: document-order dup counter\n * (`hash(key#N)`). This IS order-dependent — two identical `<span></span>`\n * get different ids based on which comes first in the DOM. This is unavoidable:\n * unique ids for byte-identical elements require a positional signal.\n *\n * Why this is safe in practice: once `ensureHfIds` write-back persists\n * `data-hf-id` to source the attribute is physically bound to its element.\n * Reordering identical siblings carries the attribute along → zero\n * order-dependence post-persist. `ensureHfIds` skips pinned elements\n * (`if (el.getAttribute(\"data-hf-id\")) continue`), so normal operation\n * never re-exposes the ordering after first persist.\n */\n// WIRE CONTRACT: id minting is content-keyed (FNV1a of innerHTML + tag). R7's\n// preview route relies on mintHfId producing identical ids across mint contexts\n// (disk-persist pass vs. in-memory bundle pass) — see preview.test.ts\n// \"bundle returning untagged HTML gets same ids as disk\". Any change that adds\n// positional, session, or random input to the hash breaks that invariant and\n// makes hf- ids diverge between disk and served HTML, silently corrupting\n// drag-to-edit targeting.\nexport function mintHfId(el: Element, assigned: Set<string>): string {\n  const key = contentKey(el);\n  let id = toHfId(fnv1a(key));\n  let dup = 0;\n  while (assigned.has(id)) {\n    dup += 1;\n    // Graceful fallback instead of a hard throw: rehashing only fails to find a\n    // free 4-char slot in a pathological document (~1.6M identical elements).\n    // Rather than crash the whole parse, widen the id with the dup counter —\n    // still deterministic and unique, just longer than the 4-char norm.\n    if (dup > 10000) {\n      id = `hf-${(fnv1a(key) >>> 0).toString(36)}-${dup}`;\n      break;\n    }\n    id = toHfId(fnv1a(`${key}#${dup}`));\n  }\n  assigned.add(id);\n  return id;\n}\n\n/**\n * True for a sub-composition authoring template whose content the studio preview\n * unwraps into the served body. Two accepted forms:\n *   A) `<template data-composition-id=\"X\">…` — the id on the template itself.\n *   B) `<template id=\"X-template\"><div data-composition-id=\"X\">…` — the id on the\n *      wrapped root div (the form `hyperframes add` scaffolds and registry blocks use).\n * Only these are treated as transparent containers for hf-id purposes. A plain\n * `<template>` (runtime clone-source: list item, particle, etc.) must NOT get\n * inner ids — its content is cloned N times into the live DOM, so a persisted\n * inner id would be duplicated across every clone. Form B is distinguished from\n * a clone-source by the presence of a direct `[data-composition-id]` child.\n */\nexport function isCompositionTemplate(el: Element): boolean {\n  if (el.tagName.toLowerCase() !== \"template\") return false;\n  if (el.getAttribute(\"data-composition-id\") !== null) return true;\n  for (const child of Array.from(el.children)) {\n    if (child.getAttribute(\"data-composition-id\") !== null) return true;\n  }\n  return false;\n}\n\n/**\n * Document-order walk of every element under `root`, descending into\n * composition `<template>` subtrees — linkedom's querySelectorAll does not, so\n * template-based sub-comps would otherwise never get inner ids (the preview\n * unwraps the template and stamps the SAME content, so skipping here splits\n * the id space between the served DOM and the raw file). Plain templates are\n * skipped entirely (see isCompositionTemplate).\n */\nfunction walkElements(root: Element, visit: (el: Element) => void): void {\n  for (const child of Array.from(root.children)) {\n    const isTemplate = child.tagName.toLowerCase() === \"template\";\n    if (isTemplate && !isCompositionTemplate(child)) continue;\n    visit(child);\n    walkElements(child, visit);\n  }\n}\n\nexport function ensureHfIds(html: string): string {\n  // Mirror parseSourceDocument's fragment-wrapping so bare fragments don't land\n  // outside <body> in linkedom, which would cause body.querySelectorAll to return [].\n  const hasDocumentShell = /<!doctype|<html[\\s>]/i.test(html);\n  const wrapped = !hasDocumentShell;\n  const { document } = wrapped\n    ? parseHTML(`<!DOCTYPE html><html><head></head><body>${html}</body></html>`)\n    : parseHTML(html);\n  const body = document.body;\n  if (!body) return html;\n\n  const assigned = new Set<string>();\n  // Seed with already-present ids (pin) so fresh mints never collide with them.\n  // Scope to <body> to match the mint walk below — a stray data-hf-id in <head>\n  // must not pin an id into the set that a body element would then be bumped off.\n  walkElements(body, (el) => {\n    const existing = el.getAttribute(\"data-hf-id\");\n    if (existing) assigned.add(existing);\n  });\n\n  walkElements(body, (el) => {\n    if (EXCLUDED_TAGS.has(el.tagName.toLowerCase())) return;\n    if (el.getAttribute(\"data-hf-id\")) return; // pinned\n    el.setAttribute(\"data-hf-id\", mintHfId(el, assigned));\n  });\n\n  return wrapped ? document.body.innerHTML || \"\" : document.toString();\n}\n"],"mappings":";AAUA,SAAS,iBAAiB;AAGnB,IAAM,gBAAgB,oBAAI,IAAI;AAAA,EACnC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,CAAC;AAGD,SAAS,MAAM,KAAqB;AAClC,MAAI,IAAI;AACR,WAAS,IAAI,GAAG,IAAI,IAAI,QAAQ,KAAK;AACnC,SAAK,IAAI,WAAW,CAAC;AACrB,QAAI,KAAK,KAAK,GAAG,QAAU;AAAA,EAC7B;AACA,SAAO,MAAM;AACf;AAMA,SAAS,OAAO,MAAsB;AACpC,QAAM,KAAK,SAAS,GAAG,SAAS,EAAE;AAElC,QAAM,OAAO,EAAE,UAAU,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,GAAG;AAC5D,SAAO,MAAM,IAAI;AACnB;AAGA,SAAS,QAAQ,IAAqB;AACpC,MAAI,OAAO;AACX,KAAG,WAAW,QAAQ,CAAC,MAAM;AAC3B,QAAI,EAAE,aAAa,EAAG,SAAS,EAAW,aAAa;AAAA,EACzD,CAAC;AACD,SAAO,KAAK,KAAK;AACnB;AAEA,SAAS,WAAW,IAAqB;AAGvC,QAAM,QAAQ,MAAM,KAAK,GAAG,UAAU,EACnC,OAAO,CAAC,MAAM,CAAC,EAAE,KAAK,WAAW,UAAU,CAAC,EAC5C,IAAI,CAAC,MAAM,GAAG,EAAE,IAAI,KAAO,EAAE,KAAK,EAAE,EACpC,KAAK,EACL,KAAK,GAAM;AACd,SAAO,GAAG,GAAG,QAAQ,YAAY,CAAC,IAAI,KAAK,IAAI,QAAQ,EAAE,CAAC;AAC5D;AAsBO,SAAS,SAAS,IAAa,UAA+B;AACnE,QAAM,MAAM,WAAW,EAAE;AACzB,MAAI,KAAK,OAAO,MAAM,GAAG,CAAC;AAC1B,MAAI,MAAM;AACV,SAAO,SAAS,IAAI,EAAE,GAAG;AACvB,WAAO;AAKP,QAAI,MAAM,KAAO;AACf,WAAK,OAAO,MAAM,GAAG,MAAM,GAAG,SAAS,EAAE,CAAC,IAAI,GAAG;AACjD;AAAA,IACF;AACA,SAAK,OAAO,MAAM,GAAG,GAAG,IAAI,GAAG,EAAE,CAAC;AAAA,EACpC;AACA,WAAS,IAAI,EAAE;AACf,SAAO;AACT;AAcO,SAAS,sBAAsB,IAAsB;AAC1D,MAAI,GAAG,QAAQ,YAAY,MAAM,WAAY,QAAO;AACpD,MAAI,GAAG,aAAa,qBAAqB,MAAM,KAAM,QAAO;AAC5D,aAAW,SAAS,MAAM,KAAK,GAAG,QAAQ,GAAG;AAC3C,QAAI,MAAM,aAAa,qBAAqB,MAAM,KAAM,QAAO;AAAA,EACjE;AACA,SAAO;AACT;AAUA,SAAS,aAAa,MAAe,OAAoC;AACvE,aAAW,SAAS,MAAM,KAAK,KAAK,QAAQ,GAAG;AAC7C,UAAM,aAAa,MAAM,QAAQ,YAAY,MAAM;AACnD,QAAI,cAAc,CAAC,sBAAsB,KAAK,EAAG;AACjD,UAAM,KAAK;AACX,iBAAa,OAAO,KAAK;AAAA,EAC3B;AACF;AAEO,SAAS,YAAY,MAAsB;AAGhD,QAAM,mBAAmB,wBAAwB,KAAK,IAAI;AAC1D,QAAM,UAAU,CAAC;AACjB,QAAM,EAAE,SAAS,IAAI,UACjB,UAAU,2CAA2C,IAAI,gBAAgB,IACzE,UAAU,IAAI;AAClB,QAAM,OAAO,SAAS;AACtB,MAAI,CAAC,KAAM,QAAO;AAElB,QAAM,WAAW,oBAAI,IAAY;AAIjC,eAAa,MAAM,CAAC,OAAO;AACzB,UAAM,WAAW,GAAG,aAAa,YAAY;AAC7C,QAAI,SAAU,UAAS,IAAI,QAAQ;AAAA,EACrC,CAAC;AAED,eAAa,MAAM,CAAC,OAAO;AACzB,QAAI,cAAc,IAAI,GAAG,QAAQ,YAAY,CAAC,EAAG;AACjD,QAAI,GAAG,aAAa,YAAY,EAAG;AACnC,OAAG,aAAa,cAAc,SAAS,IAAI,QAAQ,CAAC;AAAA,EACtD,CAAC;AAED,SAAO,UAAU,SAAS,KAAK,aAAa,KAAK,SAAS,SAAS;AACrE;","names":[]}

package/dist/index.d.ts

@@ -7,7 +7,7 @@ export { SPRING_PRESETS, SpringPreset, generateSpringEaseData } from './springEa
 export { parseGsapScriptAcorn as parseGsapScript } from './gsapParserAcorn.js';
 export { EXCLUDED_TAGS, ensureHfIds, isCompositionTemplate, mintHfId } from './hfIds.js';
 export { ParsableDocumentLike, SubCompositionValidity, SubCompositionValidityReason, checkSubCompositionUsability } from './subCompositionValidity.js';
-export { CANONICAL_FONT_DISPLAY_NAMES, FONT_ALIAS_KEYS, FONT_ALIAS_MAP, decodeUrlPathVariants, resolveAliasDisplayName } from './composition.js';
+export { CANONICAL_FONT_DISPLAY_NAMES, FONT_ALIAS_KEYS, FONT_ALIAS_MAP, VariableUsageScan, decodeUrlPathVariants, parseCompositionVariables, resolveAliasDisplayName, scanVariableUsage } from './composition.js';
 
 /**
  * Thrown by htmlParser functions when the input HTML is empty or does not
@@ -44,6 +44,7 @@ interface CompositionMetadata {
     variables: CompositionVariable[];
 }
 declare function extractCompositionMetadata(html: string): CompositionMetadata;
+
 declare function validateCompositionHtml(html: string): ValidationResult;
 
 /**

package/dist/index.js

@@ -1936,6 +1936,46 @@ function parseGsapScriptAcorn(script) {
   }
 }
 
+// src/compositionVariables.ts
+var DEFAULT_TYPEOF = {
+  string: "string",
+  number: "number",
+  color: "string",
+  boolean: "boolean",
+  enum: "string",
+  font: "string",
+  image: "string"
+};
+function isRecord(v) {
+  return typeof v === "object" && v !== null;
+}
+function isVariableType(t) {
+  return typeof t === "string" && t in DEFAULT_TYPEOF;
+}
+function isCompositionVariable(v) {
+  if (!isRecord(v)) return false;
+  if (typeof v.id !== "string" || typeof v.label !== "string") return false;
+  if (!isVariableType(v.type)) return false;
+  if (typeof v.default !== DEFAULT_TYPEOF[v.type]) return false;
+  if (v.type === "enum" && !Array.isArray(v.options)) return false;
+  return true;
+}
+function parseCompositionVariables(htmlEl) {
+  const variablesAttr = htmlEl.getAttribute("data-composition-variables");
+  if (!variablesAttr) {
+    return [];
+  }
+  try {
+    const parsed = JSON.parse(variablesAttr);
+    if (!Array.isArray(parsed)) {
+      return [];
+    }
+    return parsed.filter(isCompositionVariable);
+  } catch {
+    return [];
+  }
+}
+
 // src/hfIds.ts
 import { parseHTML } from "linkedom";
 var EXCLUDED_TAGS = /* @__PURE__ */ new Set([
@@ -1987,7 +2027,12 @@ function mintHfId(el, assigned) {
   return id;
 }
 function isCompositionTemplate(el) {
-  return el.tagName.toLowerCase() === "template" && el.getAttribute("data-composition-id") !== null;
+  if (el.tagName.toLowerCase() !== "template") return false;
+  if (el.getAttribute("data-composition-id") !== null) return true;
+  for (const child of Array.from(el.children)) {
+    if (child.getAttribute("data-composition-id") !== null) return true;
+  }
+  return false;
 }
 function walkElements(root, visit) {
   for (const child of Array.from(root.children)) {
@@ -2615,44 +2660,6 @@ function extractCompositionMetadata(html) {
     variables
   };
 }
-function parseCompositionVariables(htmlEl) {
-  const variablesAttr = htmlEl.getAttribute("data-composition-variables");
-  if (!variablesAttr) {
-    return [];
-  }
-  try {
-    const parsed = JSON.parse(variablesAttr);
-    if (!Array.isArray(parsed)) {
-      return [];
-    }
-    return parsed.filter((v) => {
-      if (typeof v !== "object" || v === null) return false;
-      if (typeof v.id !== "string" || typeof v.label !== "string") return false;
-      if (!["string", "number", "color", "boolean", "enum", "font", "image"].includes(v.type))
-        return false;
-      switch (v.type) {
-        case "string":
-          return typeof v.default === "string";
-        case "number":
-          return typeof v.default === "number";
-        case "color":
-          return typeof v.default === "string";
-        case "boolean":
-          return typeof v.default === "boolean";
-        case "enum":
-          return typeof v.default === "string" && Array.isArray(v.options);
-        case "font":
-          return typeof v.default === "string";
-        case "image":
-          return typeof v.default === "string";
-        default:
-          return false;
-      }
-    });
-  } catch {
-    return [];
-  }
-}
 function validateCompositionHtml(html) {
   const errors = [];
   const warnings = [];
@@ -2936,6 +2943,110 @@ function decodeUrlPathVariants(path) {
   return variants;
 }
 
+// src/variableUsage.ts
+import * as acorn3 from "acorn";
+import * as acornWalk3 from "acorn-walk";
+function isGetVariablesCallee(callee) {
+  if (callee?.type === "Identifier") return callee.name === "getVariables";
+  if (callee?.type === "MemberExpression" && !callee.computed) {
+    return callee.property?.type === "Identifier" && callee.property.name === "getVariables";
+  }
+  return false;
+}
+function collectFromObjectPattern(pattern, out) {
+  for (const prop of pattern.properties ?? []) {
+    if (prop?.type === "RestElement") {
+      out.incomplete();
+      continue;
+    }
+    if (prop?.type !== "Property") continue;
+    if (prop.computed === true) {
+      out.incomplete();
+    } else if (prop.key?.type === "Identifier") {
+      out.use(String(prop.key.name));
+    } else if (prop.key?.type === "Literal" && typeof prop.key.value === "string") {
+      out.use(prop.key.value);
+    } else {
+      out.incomplete();
+    }
+  }
+}
+function collectFromMemberAccess(member, out) {
+  if (member.computed !== true && member.property?.type === "Identifier") {
+    out.use(String(member.property.name));
+  } else if (member.computed === true && member.property?.type === "Literal" && typeof member.property.value === "string") {
+    out.use(member.property.value);
+  } else {
+    out.incomplete();
+  }
+}
+function classifyValueRead(parent, valueNode, out) {
+  if (!parent || parent.type === "ExpressionStatement") {
+    return null;
+  }
+  if (parent.type === "MemberExpression" && parent.object === valueNode) {
+    collectFromMemberAccess(parent, out);
+    return null;
+  }
+  if (parent.type === "VariableDeclarator" && parent.init === valueNode) {
+    if (parent.id?.type === "ObjectPattern") {
+      collectFromObjectPattern(parent.id, out);
+      return null;
+    }
+    if (parent.id?.type === "Identifier") return String(parent.id.name);
+    out.incomplete();
+    return null;
+  }
+  out.incomplete();
+  return null;
+}
+function scanVariableUsage(scriptText) {
+  const usedIds = [];
+  const seen = /* @__PURE__ */ new Set();
+  let scanIncomplete = false;
+  const sink = {
+    use(id) {
+      if (!seen.has(id)) {
+        seen.add(id);
+        usedIds.push(id);
+      }
+    },
+    incomplete() {
+      scanIncomplete = true;
+    }
+  };
+  let ast;
+  try {
+    ast = acorn3.parse(scriptText, { ecmaVersion: "latest", sourceType: "script" });
+  } catch {
+    return { usedIds: [], scanIncomplete: true };
+  }
+  const aliases = /* @__PURE__ */ new Set();
+  acornWalk3.ancestor(ast, {
+    CallExpression(node, _, ancestors) {
+      if (!isGetVariablesCallee(node.callee)) return;
+      const parent = ancestors[ancestors.length - 2];
+      const alias = classifyValueRead(parent, node, sink);
+      if (alias) aliases.add(alias);
+    }
+  });
+  if (aliases.size > 0) {
+    acornWalk3.ancestor(ast, {
+      // fallow-ignore-next-line complexity
+      Identifier(node, _, ancestors) {
+        if (!aliases.has(String(node.name))) return;
+        const parent = ancestors[ancestors.length - 2];
+        if (!parent) return;
+        if (parent.type === "VariableDeclarator" && parent.id === node) return;
+        if (parent.type === "MemberExpression" && parent.property === node) return;
+        if (parent.type === "Property" && parent.key === node && parent.computed !== true) return;
+        if (classifyValueRead(parent, node, sink)) sink.incomplete();
+      }
+    });
+  }
+  return { usedIds, scanIncomplete };
+}
+
 // src/fontAliases.ts
 var FONT_ALIAS_MAP = {
   // ── Canonical bundled fonts (self-referencing) ────────────────────────
@@ -3077,11 +3188,13 @@ export {
   keyframesToGsapAnimations,
   mintHfId,
   normalizeResolutionFlag,
+  parseCompositionVariables,
   parseGsapScriptAcorn as parseGsapScript,
   parseHtml,
   queryByAttr,
   removeElementFromHtml,
   resolveAliasDisplayName,
+  scanVariableUsage,
   serializeGsapAnimations,
   unrollComputedTimeline,
   updateElementInHtml,