feat(sdk): variable declaration read apis + browser-safe variables entry (#2046)

packages/sdk/src/engine/variableModel.ts

@@ -7,6 +7,12 @@
  * (engine/apply-patches.ts) can never disagree on the model's shape.
  */
 
+// Browser-safe subpath — the core/parsers root entries pull Node-only modules
+// and would break browser bundles that include the SDK (e.g. Studio).
+import { parseCompositionVariables } from "@hyperframes/core/variables";
+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 {
@@ -33,6 +39,18 @@ function indexOfId(arr: VariableDecl[], id: string): number {
   return arr.findIndex((v) => typeof v === "object" && v !== null && v.id === id);
 }
 
+/**
+ * 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.
+ */
+export function readVariableDeclarations(document: Document): CompositionVariable[] {
+  const htmlEl = getHtmlEl(document);
+  if (!htmlEl) return [];
+  return parseCompositionVariables(htmlEl);
+}
+
 /**
  * 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.

packages/sdk/src/index.ts

@@ -20,10 +20,16 @@ export type {
   CanResult,
 } from "./types.js";
 
-export type { CompositionVariable } from "@hyperframes/core";
-
 export { ORIGIN_APPLY_PATCHES, ORIGIN_LOCAL } from "./types.js";
 
+// Variable schema types — re-exported so SDK consumers (Studio, embedders)
+// can type declarations without a direct @hyperframes/core dependency.
+export type {
+  CompositionVariable,
+  CompositionVariableType,
+  VariableValidationIssue,
+} from "@hyperframes/core/variables";
+
 export { UnsupportedOpError } from "./engine/mutate.js";
 
 export { buildDocument, buildRoots, flatElements } from "./document.js";

packages/sdk/src/session.ts

@@ -36,10 +36,12 @@ 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 type { CompositionVariable } from "@hyperframes/core";
 import { extractGsapLabels } from "@hyperframes/core/gsap-parser-acorn";
 import { stripEmbeddedRuntimeScripts } from "@hyperframes/core/compiler/html-document";
 import { parseStartExpression } from "@hyperframes/core/runtime/start-expression";
+import { readDeclaredDefaults, validateVariables } from "@hyperframes/core/variables";
+import type { CompositionVariable, VariableValidationIssue } from "@hyperframes/core/variables";
+import { readVariableDeclarations } from "./engine/variableModel.js";
 import { serializeDocument } from "./engine/serialize.js";
 import { applyPatchesToDocument, applyOverrideSet } from "./engine/apply-patches.js";
 import { buildPatchEvent, pathToKey } from "./engine/patches.js";
@@ -155,6 +157,7 @@ class CompositionImpl implements Composition {
     this.dispatch({ type: "setVariableValue", id, value });
   }
 
+  // ── #2098 CRUD surface (kept; superseded by the richer API below in #2047+) ──
   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
@@ -183,6 +186,30 @@ class CompositionImpl implements Composition {
     this.dispatch({ type: "removeVariable", id });
   }
 
+  // ── Canonical read surface (this stack) ──
+  getVariableDeclarations(): CompositionVariable[] {
+    return readVariableDeclarations(this.parsed.document);
+  }
+
+  getVariableValues(overrides?: Record<string, unknown>): Record<string, unknown> {
+    // THIS composition's own declared defaults (loose extraction: any entry with
+    // a string id + a `default` key, even ones the strict declaration parser
+    // drops) spread under the overrides. Scope note: this reads the composition's
+    // single declaration element only — NOT a union of every `[data-composition-
+    // variables]` in the document. The runtime's getVariables()
+    // (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);
+    return { ...defaults, ...(overrides ?? {}) };
+  }
+
+  validateVariableValues(values: Record<string, unknown>): VariableValidationIssue[] {
+    return validateVariables(values, this.getVariableDeclarations());
+  }
+
   // ── WS-C: timing accessors + typed setHold ───────────────────────────────────
 
   /**

packages/sdk/src/session.variables.test.ts

@@ -0,0 +1,140 @@
+/**
+ * Variable read APIs: getVariableDeclarations / getVariableValues /
+ * validateVariableValues. Semantics contract: declarations use the strict
+ * canonical parser; values mirror the runtime's loose defaults + overrides
+ * merge; validation matches --strict-variables.
+ */
+
+import { describe, it, expect } from "vitest";
+import { openComposition } from "./session.js";
+
+const DECLS = [
+  { id: "title", type: "string", label: "Title", default: "Hello" },
+  { id: "accent", type: "color", label: "Accent", default: "#00C3FF" },
+  { id: "count", type: "number", label: "Count", default: 3, min: 0, max: 10 },
+  { id: "dark", type: "boolean", label: "Dark mode", default: false },
+  {
+    id: "layout",
+    type: "enum",
+    label: "Layout",
+    default: "wide",
+    options: [
+      { value: "wide", label: "Wide" },
+      { value: "tall", label: "Tall" },
+    ],
+  },
+];
+
+function htmlWithVariables(attr: string): string {
+  return `<!DOCTYPE html>
+<html data-composition-variables='${attr}'>
+<body>
+<div data-hf-id="hf-stage" data-hf-root style="width: 1280px; height: 720px" data-duration="5">
+  <h1 data-hf-id="hf-title" data-start="0" data-end="3">Hello</h1>
+</div>
+</body>
+</html>`;
+}
+
+const BASE_HTML = htmlWithVariables(JSON.stringify(DECLS));
+
+describe("getVariableDeclarations", () => {
+  it("returns the declared schema with per-type metadata intact", async () => {
+    const comp = await openComposition(BASE_HTML);
+    const decls = comp.getVariableDeclarations();
+    expect(decls.map((d) => d.id)).toEqual(["title", "accent", "count", "dark", "layout"]);
+    const count = decls.find((d) => d.id === "count");
+    expect(count).toMatchObject({ type: "number", min: 0, max: 10, default: 3 });
+    const layout = decls.find((d) => d.id === "layout");
+    expect(layout).toMatchObject({ type: "enum", default: "wide" });
+  });
+
+  it("returns [] when the attribute is absent", async () => {
+    const comp = await openComposition(
+      `<div data-hf-id="hf-stage" data-hf-root data-duration="5"><p data-hf-id="hf-p">x</p></div>`,
+    );
+    expect(comp.getVariableDeclarations()).toEqual([]);
+  });
+
+  it("returns [] for invalid JSON and drops malformed entries", async () => {
+    const invalid = await openComposition(htmlWithVariables("{not json"));
+    expect(invalid.getVariableDeclarations()).toEqual([]);
+
+    const mixed = JSON.stringify([
+      { id: "ok", type: "string", label: "Ok", default: "yes" },
+      { id: "bad-type", type: "gradient", label: "Nope", default: "x" },
+      { id: "bad-default", type: "number", label: "Nope", default: "not-a-number" },
+      "not-an-object",
+    ]);
+    const mixedComp = await openComposition(htmlWithVariables(mixed));
+    const decls = mixedComp.getVariableDeclarations();
+    expect(decls.map((d) => d.id)).toEqual(["ok"]);
+  });
+});
+
+describe("getVariableValues", () => {
+  it("returns declared defaults when no overrides given", async () => {
+    const comp = await openComposition(BASE_HTML);
+    expect(comp.getVariableValues()).toEqual({
+      title: "Hello",
+      accent: "#00C3FF",
+      count: 3,
+      dark: false,
+      layout: "wide",
+    });
+  });
+
+  it("overrides win and undeclared override keys pass through (runtime parity)", async () => {
+    const comp = await openComposition(BASE_HTML);
+    const values = comp.getVariableValues({ title: "Custom", extra: 42 });
+    expect(values.title).toBe("Custom");
+    expect(values.accent).toBe("#00C3FF");
+    expect(values.extra).toBe(42);
+  });
+
+  it("uses the loose runtime defaults filter, not the strict declaration parser", async () => {
+    // A number variable with a string default is dropped by the strict parser
+    // but its default still flows through the runtime's readDeclaredDefaults —
+    // getVariableValues must match what a composition script actually reads.
+    const attr = JSON.stringify([
+      { id: "loose", type: "number", label: "Loose", default: "not-a-number" },
+    ]);
+    const comp = await openComposition(htmlWithVariables(attr));
+    expect(comp.getVariableDeclarations()).toEqual([]);
+    expect(comp.getVariableValues()).toEqual({ loose: "not-a-number" });
+  });
+
+  it("returns {} for a composition with no declarations", async () => {
+    const comp = await openComposition(
+      `<div data-hf-id="hf-stage" data-hf-root data-duration="5"><p data-hf-id="hf-p">x</p></div>`,
+    );
+    expect(comp.getVariableValues()).toEqual({});
+    expect(comp.getVariableValues({ a: 1 })).toEqual({ a: 1 });
+  });
+});
+
+describe("validateVariableValues", () => {
+  it("returns [] for values conforming to the schema", async () => {
+    const comp = await openComposition(BASE_HTML);
+    expect(comp.validateVariableValues({ title: "x", count: 5, dark: true })).toEqual([]);
+  });
+
+  it("flags undeclared keys, type mismatches, and enum violations", async () => {
+    const comp = await openComposition(BASE_HTML);
+    const issues = comp.validateVariableValues({
+      ghost: "boo",
+      count: "five",
+      layout: "diagonal",
+    });
+    const kinds = issues.map((i) => `${i.kind}:${i.variableId}`).sort();
+    expect(kinds).toEqual(["enum-out-of-range:layout", "type-mismatch:count", "undeclared:ghost"]);
+  });
+
+  it("stays consistent after setVariableValue edits the default", async () => {
+    const comp = await openComposition(BASE_HTML);
+    comp.setVariableValue("title", "Edited");
+    expect(comp.getVariableValues().title).toBe("Edited");
+    expect(comp.getVariableDeclarations().find((d) => d.id === "title")?.default).toBe("Edited");
+    expect(comp.validateVariableValues({ title: "still-a-string" })).toEqual([]);
+  });
+});

packages/sdk/src/types.ts

@@ -1,4 +1,4 @@
-import type { CompositionVariable } from "@hyperframes/core";
+import type { CompositionVariable, VariableValidationIssue } from "@hyperframes/core/variables";
 
 // ─── Document model ───────────────────────────────────────────────────────────
 
@@ -422,6 +422,33 @@ export interface Composition {
   declareVariable(decl: CompositionVariable): void;
   /** Remove a variable's declaration. Live `var.{id}` overrides are untouched. */
   removeVariable(id: string): void;
+  /**
+   * Read the typed variable declarations from `data-composition-variables`
+   * (the canonical schema — same filter the render pipeline uses; malformed
+   * entries are dropped). Read-only — does not dispatch.
+   */
+  getVariableDeclarations(): CompositionVariable[];
+  /**
+   * Resolve this composition's variable values: its declared defaults merged
+   * with `overrides` (overrides win, undeclared override keys pass through).
+   * Read-only — does not dispatch.
+   *
+   * Scope: reads THIS composition file's own declaration element, not a union of
+   * every `[data-composition-variables]` in a bundled document. The runtime's
+   * `getVariables()` additionally walks inlined sub-composition declarers because
+   * it runs on the fully-bundled document; the SDK models one composition file,
+   * so per-file scope is intentional (and is what Studio needs to predict a
+   * single file's `--variables` payload). For the common single-`<html>`
+   * composition the two agree; they diverge only when sub-comp declarers are
+   * inlined into one document.
+   */
+  getVariableValues(overrides?: Record<string, unknown>): Record<string, unknown>;
+  /**
+   * Validate a values map against the declared schema. Returns undeclared /
+   * type-mismatch / enum-out-of-range issues (same checks as the CLI's
+   * `--strict-variables`). Read-only — does not dispatch.
+   */
+  validateVariableValues(values: Record<string, unknown>): VariableValidationIssue[];
   /**
    * Read enter/exit times and GSAP labels for every timed element (WS-C).
    * Derives enterAt/exitAt using the same data-duration vs data-end preference