diff --git a/packages/core/src/variables.ts b/packages/core/src/variables.ts
index 1eb1ebd71..da4f382fb 100644
--- a/packages/core/src/variables.ts
+++ b/packages/core/src/variables.ts
@@ -21,6 +21,7 @@ export type {
 export {
   COMPOSITION_VARIABLE_TYPES,
   parseCompositionVariables,
+  isCompositionVariable,
   isScalarVariableValue,
 } from "@hyperframes/parsers/composition";
 
diff --git a/packages/parsers/src/composition.ts b/packages/parsers/src/composition.ts
index 933f69683..e4cef33e6 100644
--- a/packages/parsers/src/composition.ts
+++ b/packages/parsers/src/composition.ts
@@ -10,4 +10,8 @@ export {
   resolveAliasDisplayName,
 } from "./fontAliases.js";
 export { decodeUrlPathVariants } from "./utils/urlPath.js";
-export { parseCompositionVariables, isScalarVariableValue } from "./compositionVariables.js";
+export {
+  parseCompositionVariables,
+  isCompositionVariable,
+  isScalarVariableValue,
+} from "./compositionVariables.js";
diff --git a/packages/parsers/src/compositionVariables.ts b/packages/parsers/src/compositionVariables.ts
index fa09d3ef8..2bf9960ad 100644
--- a/packages/parsers/src/compositionVariables.ts
+++ b/packages/parsers/src/compositionVariables.ts
@@ -40,7 +40,13 @@ function isVariableType(t: unknown): t is CompositionVariableType {
   return typeof t === "string" && t in DEFAULT_TYPEOF;
 }
 
-function isCompositionVariable(v: unknown): v is CompositionVariable {
+/**
+ * True when the value is a structurally valid variable declaration: id, label,
+ * a known type, a default matching that type, and options[] for enums. The
+ * same predicate parseCompositionVariables filters with — exported so writers
+ * (SDK declaration ops, Studio forms) can validate before persisting.
+ */
+export function isCompositionVariable(v: unknown): v is CompositionVariable {
   if (!isRecord(v)) return false;
   if (typeof v.id !== "string" || typeof v.label !== "string") return false;
   if (!isVariableType(v.type)) return false;
diff --git a/packages/sdk/src/engine/apply-patches.ts b/packages/sdk/src/engine/apply-patches.ts
index b975f94b4..57df576bb 100644
--- a/packages/sdk/src/engine/apply-patches.ts
+++ b/packages/sdk/src/engine/apply-patches.ts
@@ -19,7 +19,21 @@ import {
   setStyleSheet,
 } from "./model.js";
 import { keyToPath, stylePath } from "./patches.js";
-import { writeVariableDefault, clearVariableDefault } from "./variableModel.js";
+import {
+  writeVariableDefault,
+  clearVariableDefault,
+  writeVariableDeclaration,
+  removeVariableDeclarationEntry,
+} from "./variableModel.js";
+
+function isRawDeclarationEntry(value: unknown): value is { id: string } & Record<string, unknown> {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    !Array.isArray(value) &&
+    typeof (value as { id?: unknown }).id === "string"
+  );
+}
 
 // ─── Path parser ────────────────────────────────────────────────────────────
 
@@ -32,6 +46,7 @@ interface ParsedPath {
     | "hold"
     | "element"
     | "variable"
+    | "variableDeclaration"
     | "metadata"
     | "script"
     | "stylesheet";
@@ -65,6 +80,9 @@ function parsePath(path: string): ParsedPath | null {
   const elemM = /^\/elements\/([^/]+)$/.exec(path);
   if (elemM) return { type: "element", id: elemM[1] };
 
+  const varDeclM = /^\/variableDeclarations\/(.+)$/.exec(path);
+  if (varDeclM) return { type: "variableDeclaration", id: varDeclM[1] };
+
   const varM = /^\/variables\/(.+)$/.exec(path);
   if (varM) return { type: "variable", id: varM[1] };
 
@@ -229,6 +247,20 @@ function applyOne(parsed: ParsedDocument, patch: JsonPatchOp, p: ParsedPath): vo
       break;
     }
 
+    case "variableDeclaration": {
+      if (!p.id) return;
+      if (patch.op === "remove") {
+        removeVariableDeclarationEntry(parsed.document, 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);
+      }
+      break;
+    }
+
     case "variable": {
       if (!p.id) return;
       // B1: update the JSON model (data-composition-variables) so
diff --git a/packages/sdk/src/engine/mutate.ts b/packages/sdk/src/engine/mutate.ts
index 3f2c5c69f..15ee6398a 100644
--- a/packages/sdk/src/engine/mutate.ts
+++ b/packages/sdk/src/engine/mutate.ts
@@ -40,6 +40,7 @@ import {
   holdPath,
   elementPath,
   variablePath,
+  variableDeclPath,
   metaPath,
   gsapScriptPath,
   styleSheetPath,
@@ -76,7 +77,18 @@ import {
   unrollDynamicAnimations,
 } from "@hyperframes/core/gsap-writer-acorn";
 import { deriveKeyframeBackfillDefaults } from "./keyframeBackfill.js";
-import { readVariableDefault, writeVariableDefault } from "./variableModel.js";
+import {
+  readVariableDefault,
+  writeVariableDefault,
+  findVariableDeclaration,
+  writeVariableDeclaration,
+  removeVariableDeclarationEntry,
+} from "./variableModel.js";
+import {
+  isCompositionVariable,
+  isScalarVariableValue as isScalar,
+} from "@hyperframes/core/variables";
+import type { CompositionVariable } from "@hyperframes/core/variables";
 import {
   URI_BEARING_ATTRS,
   DANGEROUS_URI_SCHEMES,
@@ -288,6 +300,12 @@ export function applyOp(parsed: ParsedDocument, op: EditOp): MutationResult {
       return handleSetCompositionMetadata(parsed, op);
     case "setVariableValue":
       return handleSetVariableValue(parsed, op.id, op.value);
+    case "declareVariable":
+      return handleDeclareVariable(parsed, op.declaration);
+    case "updateVariableDeclaration":
+      return handleUpdateVariableDeclaration(parsed, op.id, op.declaration);
+    case "removeVariableDeclaration":
+      return handleRemoveVariableDeclaration(parsed, op.id);
     case "setClassStyle":
       return handleSetClassStyle(parsed, op.selector, op.styles);
     case "addLabel":
@@ -885,6 +903,132 @@ function handleSetVariableValue(
   return { forward, inverse };
 }
 
+/**
+ * Keep the `--{id}` CSS compat custom property on the root in sync with a
+ * scalar default (same secondary channel handleSetVariableValue maintains).
+ * Pass null to clear. Returns the patch pair, or null when there is no root
+ * or nothing to change.
+ */
+function cssCompatChange(
+  parsed: ParsedDocument,
+  id: string,
+  newVal: string | null,
+): { forward: JsonPatchOp; inverse: JsonPatchOp } | null {
+  const root = findRoot(parsed.document);
+  const rootId = root?.getAttribute("data-hf-id");
+  if (!root || !rootId) return null;
+  const cssVar = `--${id}`;
+  const oldCssValue = getElementStyles(root)[cssVar] ?? null;
+  if (newVal !== null) {
+    if (oldCssValue === newVal) return null;
+    setElementStyles(root, { [cssVar]: newVal });
+    return scalarChange(stylePath(rootId, cssVar), oldCssValue, newVal);
+  }
+  if (oldCssValue === null) return null;
+  setElementStyles(root, { [cssVar]: null });
+  return scalarDelete(stylePath(rootId, cssVar), oldCssValue);
+}
+
+/**
+ * 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.
+ */
+function fragmentCompositionErr(parsed: ParsedDocument): CanResult | null {
+  if (!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.",
+  );
+}
+
+function invalidDeclarationErr(): CanResult {
+  return canErr(
+    "E_INVALID_ARGS",
+    "Not a valid variable declaration.",
+    "Requires id, label, type (string|number|color|boolean|enum|font|image), and a default matching the type; enum also requires options[].",
+  );
+}
+
+function handleDeclareVariable(
+  parsed: ParsedDocument,
+  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;
+  if (!isCompositionVariable(declaration)) return EMPTY;
+  if (findVariableDeclaration(parsed.document, declaration.id) !== undefined) return EMPTY;
+  if (!writeVariableDeclaration(parsed.document, declaration)) return EMPTY;
+  const path = variableDeclPath(declaration.id);
+  const result: MutationResult = {
+    forward: [patchAdd(path, declaration)],
+    inverse: [patchRemove(path)],
+  };
+  // Same CSS compat channel every other variable op maintains — a composition
+  // CSS-bound to var(--id) must resolve regardless of which op set the value.
+  if (isScalar(declaration.default)) {
+    const css = cssCompatChange(parsed, declaration.id, String(declaration.default));
+    if (css) {
+      result.forward.push(css.forward);
+      result.inverse.push(css.inverse);
+    }
+  }
+  return result;
+}
+
+function handleUpdateVariableDeclaration(
+  parsed: ParsedDocument,
+  id: string,
+  declaration: CompositionVariable,
+): MutationResult {
+  if (parsed.wrapped) return EMPTY;
+  if (!isCompositionVariable(declaration) || declaration.id !== id) return EMPTY;
+  const old = findVariableDeclaration(parsed.document, id);
+  if (old === undefined) return EMPTY;
+  writeVariableDeclaration(parsed.document, declaration);
+  const p = valueChange(variableDeclPath(id), old, declaration);
+  const result: MutationResult = { forward: [p.forward], inverse: [p.inverse] };
+
+  // Default changed → keep the CSS compat prop in sync (set for scalars,
+  // clear when the new default is object-valued font/image), and emit the
+  // paired /variables value patch so the T3 override-set's var.{id} entry
+  // agrees with the varDecl.{id} snapshot regardless of replay order.
+  const oldDefault = old.default;
+  const newDefault = declaration.default;
+  if (JSON.stringify(oldDefault) !== JSON.stringify(newDefault)) {
+    const valueP = valueChange(variablePath(id), oldDefault ?? null, newDefault);
+    result.forward.push(valueP.forward);
+    result.inverse.push(valueP.inverse);
+    const css = cssCompatChange(parsed, id, isScalar(newDefault) ? String(newDefault) : null);
+    if (css) {
+      result.forward.push(css.forward);
+      result.inverse.push(css.inverse);
+    }
+  }
+  return result;
+}
+
+function handleRemoveVariableDeclaration(parsed: ParsedDocument, id: string): MutationResult {
+  if (parsed.wrapped) return EMPTY;
+  const old = findVariableDeclaration(parsed.document, id);
+  if (old === undefined) return EMPTY;
+  removeVariableDeclarationEntry(parsed.document, id);
+  const path = variableDeclPath(id);
+  const result: MutationResult = {
+    forward: [patchRemove(path)],
+    inverse: [patchAdd(path, old)],
+  };
+  const css = cssCompatChange(parsed, id, null);
+  if (css) {
+    result.forward.push(css.forward);
+    result.inverse.push(css.inverse);
+  }
+  return result;
+}
+
 // ─── GSAP selector helpers ───────────────────────────────────────────────────
 
 function selectorMatchesId(selector: string, id: HfId): boolean {
@@ -1494,6 +1638,49 @@ export function validateOp(parsed: ParsedDocument, op: EditOp): CanResult {
       if (findRoot(parsed.document) === null)
         return canErr("E_NO_ROOT", "Composition root element not found.");
       return CAN_OK;
+    case "declareVariable": {
+      const fragmentErr = fragmentCompositionErr(parsed);
+      if (fragmentErr) return fragmentErr;
+      if (!isCompositionVariable(op.declaration)) return invalidDeclarationErr();
+      if (findVariableDeclaration(parsed.document, op.declaration.id) !== undefined)
+        return canErr(
+          "E_DUPLICATE_VARIABLE",
+          `Variable "${op.declaration.id}" is already declared.`,
+          "Use updateVariableDeclaration to change it, or setVariableValue to change its default.",
+        );
+      return CAN_OK;
+    }
+    case "updateVariableDeclaration": {
+      const fragmentErr = fragmentCompositionErr(parsed);
+      if (fragmentErr) return fragmentErr;
+      // Shape check FIRST — a null/non-object declaration must yield a
+      // CanResult, not a TypeError from the id access below.
+      if (!isCompositionVariable(op.declaration)) return invalidDeclarationErr();
+      if (op.declaration.id !== op.id)
+        return canErr(
+          "E_INVALID_ARGS",
+          `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)
+        return canErr(
+          "E_VARIABLE_NOT_FOUND",
+          `Variable "${op.id}" is not declared.`,
+          "Check comp.getVariableDeclarations(), or add it with declareVariable.",
+        );
+      return CAN_OK;
+    }
+    case "removeVariableDeclaration": {
+      const fragmentErr = fragmentCompositionErr(parsed);
+      if (fragmentErr) return fragmentErr;
+      if (findVariableDeclaration(parsed.document, op.id) === undefined)
+        return canErr(
+          "E_VARIABLE_NOT_FOUND",
+          `Variable "${op.id}" is not declared.`,
+          "Check comp.getVariableDeclarations().",
+        );
+      return CAN_OK;
+    }
     case "setCompositionMetadata":
     case "setClassStyle":
       return CAN_OK;
diff --git a/packages/sdk/src/engine/patches.ts b/packages/sdk/src/engine/patches.ts
index 96c095602..46a76418f 100644
--- a/packages/sdk/src/engine/patches.ts
+++ b/packages/sdk/src/engine/patches.ts
@@ -8,7 +8,8 @@
  *   /elements/{hfId}/timing/{start|end|duration|trackIndex}   ← end = computed absolute data-end
  *   /elements/{hfId}/hold/{start|end|fill}
  *   /elements/{hfId}                        ← whole subtree (removeElement)
- *   /variables/{variableId}
+ *   /variables/{variableId}                 ← declaration's default value
+ *   /variableDeclarations/{variableId}      ← whole declaration object
  *   /metadata/{width|height|duration}
  *   /script/gsap                            ← GSAP inline script textContent
  *   /style/css                              ← <style> element textContent
@@ -21,6 +22,7 @@
  *   /elements/hf-x/hold/start               → "hf-x.hold.start"
  *   /elements/hf-x                          → "hf-x"  (null = removal marker)
  *   /variables/brand-color-primary          → "var.brand-color-primary"
+ *   /variableDeclarations/brand-color-primary → "varDecl.brand-color-primary"
  *   /metadata/width                         → "meta.width"
  *   /script/gsap                            → "script.gsap"
  *   /style/css                              → "style.css"
@@ -75,6 +77,11 @@ export function variablePath(id: string): string {
   return `/variables/${id}`;
 }
 
+/** Whole-declaration path — distinct from /variables/{id}, which is the default *value*. */
+export function variableDeclPath(id: string): string {
+  return `/variableDeclarations/${id}`;
+}
+
 export function metaPath(field: "width" | "height" | "duration"): string {
   return `/metadata/${field}`;
 }
@@ -120,6 +127,10 @@ export function pathToKey(path: string): string | null {
   const elemMatch = /^\/elements\/([^/]+)$/.exec(path);
   if (elemMatch) return decodePathSegment(elemMatch[1]!);
 
+  // /variableDeclarations/{id} → "varDecl.{id}" (checked before /variables/)
+  const varDeclMatch = /^\/variableDeclarations\/(.+)$/.exec(path);
+  if (varDeclMatch) return `varDecl.${varDeclMatch[1]}`;
+
   // /variables/{id} → "var.{id}"
   const varMatch = /^\/variables\/(.+)$/.exec(path);
   if (varMatch) return `var.${varMatch[1]}`;
@@ -141,6 +152,8 @@ export function pathToKey(path: string): string | null {
  * Inverse of pathToKey — maps an override-set key back to its RFC 6902 path.
  * Used to replay a stored override-set onto a fresh base document (T3 init).
  */
+// Exhaustive key-family dispatcher — same shape as apply-patches.ts parsePath.
+// fallow-ignore-next-line complexity
 export function keyToPath(key: string): string | null {
   const style = /^([^.]+)\.style\.(.+)$/.exec(key);
   if (style?.[1] && style[2]) return stylePath(style[1], style[2]);
@@ -161,6 +174,9 @@ export function keyToPath(key: string): string | null {
   const hold = /^([^.]+)\.hold\.(start|end|fill)$/.exec(key);
   if (hold?.[1]) return holdPath(hold[1], hold[2] as "start" | "end" | "fill");
 
+  const varDecl = /^varDecl\.(.+)$/.exec(key);
+  if (varDecl?.[1]) return variableDeclPath(varDecl[1]);
+
   const variable = /^var\.(.+)$/.exec(key);
   if (variable?.[1]) return variablePath(variable[1]);
 
diff --git a/packages/sdk/src/engine/variableModel.ts b/packages/sdk/src/engine/variableModel.ts
index 1276f0c83..084e4a7d6 100644
--- a/packages/sdk/src/engine/variableModel.ts
+++ b/packages/sdk/src/engine/variableModel.ts
@@ -50,6 +50,68 @@ export function readVariableDeclarations(document: Document): CompositionVariabl
   return parseCompositionVariables(htmlEl);
 }
 
+/**
+ * Find the raw declaration entry for a variable id, verbatim (unvalidated).
+ * 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);
+  if (!decls) return undefined;
+  const idx = indexOfId(decls.arr, id);
+  return idx < 0 ? undefined : decls.arr[idx];
+}
+
+/**
+ * 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
+ * element to carry the attribute.
+ *
+ * Accepts raw (unvalidated) entries as well as typed declarations: the patch
+ * REPLAY path must faithfully restore whatever entry the inverse patch
+ * captured — including loose hand-authored declarations the strict parser
+ * would drop — or undo silently diverges from history.
+ */
+export function writeVariableDeclaration(
+  document: Document,
+  declaration: CompositionVariable | ({ id: string } & Record<string, unknown>),
+): boolean {
+  const htmlEl = getHtmlEl(document);
+  if (!htmlEl) return false;
+  const decls = readDecls(document);
+  const arr = decls?.arr ?? [];
+  const idx = indexOfId(arr, declaration.id);
+  const entry: VariableDecl = { ...declaration };
+  if (idx < 0) {
+    arr.push(entry);
+  } else {
+    arr[idx] = entry;
+  }
+  (decls?.htmlEl ?? htmlEl).setAttribute("data-composition-variables", JSON.stringify(arr));
+  return true;
+}
+
+/**
+ * Remove a variable declaration by id. Drops the whole attribute when the
+ * 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);
+  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");
+  } else {
+    decls.htmlEl.setAttribute("data-composition-variables", JSON.stringify(decls.arr));
+  }
+  return true;
+}
+
 /**
  * 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.
diff --git a/packages/sdk/src/session.ts b/packages/sdk/src/session.ts
index 0c644c770..25402938f 100644
--- a/packages/sdk/src/session.ts
+++ b/packages/sdk/src/session.ts
@@ -152,6 +152,18 @@ class CompositionImpl implements Composition {
     this.dispatch({ type: "setVariableValue", id, value });
   }
 
+  declareVariable(declaration: CompositionVariable): void {
+    this.dispatch({ type: "declareVariable", declaration });
+  }
+
+  updateVariableDeclaration(id: string, declaration: CompositionVariable): void {
+    this.dispatch({ type: "updateVariableDeclaration", id, declaration });
+  }
+
+  removeVariableDeclaration(id: string): void {
+    this.dispatch({ type: "removeVariableDeclaration", id });
+  }
+
   getVariableDeclarations(): CompositionVariable[] {
     return readVariableDeclarations(this.parsed.document);
   }
diff --git a/packages/sdk/src/session.variabledecls.test.ts b/packages/sdk/src/session.variabledecls.test.ts
new file mode 100644
index 000000000..886fe450e
--- /dev/null
+++ b/packages/sdk/src/session.variabledecls.test.ts
@@ -0,0 +1,218 @@
+/**
+ * Variable declaration edit ops: declareVariable / updateVariableDeclaration /
+ * removeVariableDeclaration. Covers dispatch semantics, can() validation,
+ * CSS compat sync, patch grammar, and undo round-trips.
+ */
+
+import { describe, it, expect } from "vitest";
+import { openComposition } from "./session.js";
+import { variableDeclPath, pathToKey, keyToPath } from "./engine/patches.js";
+import type { CompositionVariable } from "@hyperframes/core/variables";
+
+const TITLE_DECL: CompositionVariable = {
+  id: "title",
+  type: "string",
+  label: "Title",
+  default: "Hello",
+};
+
+const COUNT_DECL: CompositionVariable = {
+  id: "count",
+  type: "number",
+  label: "Count",
+  default: 3,
+  min: 0,
+  max: 10,
+};
+
+const BARE_HTML = `
+<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>
+`.trim();
+
+const DECLARED_HTML = `<!DOCTYPE html>
+<html data-composition-variables='${JSON.stringify([TITLE_DECL, COUNT_DECL])}'>
+<body>${BARE_HTML}</body>
+</html>`;
+
+const UNDECLARED_HTML = `<!DOCTYPE html>
+<html>
+<body>${BARE_HTML}</body>
+</html>`;
+
+describe("declareVariable", () => {
+  it("creates the attribute on a composition with no declarations", async () => {
+    const comp = await openComposition(UNDECLARED_HTML);
+    expect(comp.getVariableDeclarations()).toEqual([]);
+    comp.declareVariable(TITLE_DECL);
+    expect(comp.getVariableDeclarations()).toEqual([TITLE_DECL]);
+    expect(comp.serialize()).toContain("data-composition-variables");
+  });
+
+  it("appends to existing declarations and survives serialize round-trip", async () => {
+    const comp = await openComposition(DECLARED_HTML);
+    comp.declareVariable({ id: "dark", type: "boolean", label: "Dark", default: false });
+    expect(comp.getVariableDeclarations().map((d) => d.id)).toEqual(["title", "count", "dark"]);
+
+    const reopened = await openComposition(comp.serialize());
+    expect(reopened.getVariableDeclarations().map((d) => d.id)).toEqual(["title", "count", "dark"]);
+  });
+
+  it("no-ops on duplicate ids and can() reports E_DUPLICATE_VARIABLE", async () => {
+    const comp = await openComposition(DECLARED_HTML);
+    const dup = comp.can({ type: "declareVariable", declaration: TITLE_DECL });
+    expect(dup).toMatchObject({ ok: false, code: "E_DUPLICATE_VARIABLE" });
+    comp.declareVariable({ ...TITLE_DECL, default: "clobbered" });
+    expect(comp.getVariableDeclarations().find((d) => d.id === "title")?.default).toBe("Hello");
+  });
+
+  it("rejects structurally invalid declarations", async () => {
+    const comp = await openComposition(UNDECLARED_HTML);
+    const invalid = {
+      id: "broken",
+      type: "number",
+      label: "Broken",
+      default: "not-a-number",
+    } as unknown as CompositionVariable;
+    expect(comp.can({ type: "declareVariable", declaration: invalid })).toMatchObject({
+      ok: false,
+      code: "E_INVALID_ARGS",
+    });
+    comp.declareVariable(invalid);
+    expect(comp.getVariableDeclarations()).toEqual([]);
+  });
+
+  it("undo removes the declaration again", async () => {
+    const comp = await openComposition(UNDECLARED_HTML);
+    comp.declareVariable(TITLE_DECL);
+    comp.undo();
+    expect(comp.getVariableDeclarations()).toEqual([]);
+    expect(comp.serialize()).not.toContain("data-composition-variables");
+    comp.redo();
+    expect(comp.getVariableDeclarations()).toEqual([TITLE_DECL]);
+  });
+
+  it("refuses fragment compositions (no <html> to carry the schema)", async () => {
+    const comp = await openComposition(BARE_HTML);
+    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");
+  });
+});
+
+describe("updateVariableDeclaration", () => {
+  it("replaces the declaration wholesale", async () => {
+    const comp = await openComposition(DECLARED_HTML);
+    comp.updateVariableDeclaration("count", { ...COUNT_DECL, label: "Item count", max: 20 });
+    const decl = comp.getVariableDeclarations().find((d) => d.id === "count");
+    expect(decl).toMatchObject({ label: "Item count", max: 20, default: 3 });
+  });
+
+  it("syncs the CSS compat prop when a scalar default changes", async () => {
+    const comp = await openComposition(DECLARED_HTML);
+    comp.updateVariableDeclaration("count", { ...COUNT_DECL, default: 7 });
+    const root = comp.getElements().find((e) => e.id === "hf-stage");
+    expect(root?.inlineStyles["--count"]).toBe("7");
+  });
+
+  it("keeps CSS untouched when the default is unchanged", async () => {
+    const comp = await openComposition(DECLARED_HTML);
+    comp.updateVariableDeclaration("count", { ...COUNT_DECL, label: "Renamed only" });
+    const root = comp.getElements().find((e) => e.id === "hf-stage");
+    expect(root?.inlineStyles["--count"]).toBeUndefined();
+  });
+
+  it("validates id immutability and existence via can()", async () => {
+    const comp = await openComposition(DECLARED_HTML);
+    expect(
+      comp.can({ type: "updateVariableDeclaration", id: "count", declaration: TITLE_DECL }),
+    ).toMatchObject({ ok: false, code: "E_INVALID_ARGS" });
+    expect(
+      comp.can({
+        type: "updateVariableDeclaration",
+        id: "ghost",
+        declaration: { ...TITLE_DECL, id: "ghost" },
+      }),
+    ).toMatchObject({ ok: false, code: "E_VARIABLE_NOT_FOUND" });
+  });
+
+  it("undo restores the previous declaration", async () => {
+    const comp = await openComposition(DECLARED_HTML);
+    comp.updateVariableDeclaration("title", { ...TITLE_DECL, label: "Headline" });
+    comp.undo();
+    expect(comp.getVariableDeclarations().find((d) => d.id === "title")?.label).toBe("Title");
+  });
+});
+
+describe("removeVariableDeclaration", () => {
+  it("removes the entry and drops the attribute with the last one", async () => {
+    const comp = await openComposition(DECLARED_HTML);
+    comp.removeVariableDeclaration("count");
+    expect(comp.getVariableDeclarations().map((d) => d.id)).toEqual(["title"]);
+    comp.removeVariableDeclaration("title");
+    expect(comp.getVariableDeclarations()).toEqual([]);
+    expect(comp.serialize()).not.toContain("data-composition-variables");
+  });
+
+  it("clears the CSS compat prop and undo restores declaration + CSS", async () => {
+    const comp = await openComposition(DECLARED_HTML);
+    comp.setVariableValue("count", 5);
+    const rootBefore = comp.getElements().find((e) => e.id === "hf-stage");
+    expect(rootBefore?.inlineStyles["--count"]).toBe("5");
+
+    comp.removeVariableDeclaration("count");
+    const rootAfter = comp.getElements().find((e) => e.id === "hf-stage");
+    expect(rootAfter?.inlineStyles["--count"]).toBeUndefined();
+    expect(comp.getVariableDeclarations().map((d) => d.id)).toEqual(["title"]);
+
+    comp.undo();
+    const rootRestored = comp.getElements().find((e) => e.id === "hf-stage");
+    expect(rootRestored?.inlineStyles["--count"]).toBe("5");
+    expect(comp.getVariableDeclarations().find((d) => d.id === "count")?.default).toBe(5);
+  });
+
+  it("no-ops on unknown ids and can() reports E_VARIABLE_NOT_FOUND", async () => {
+    const comp = await openComposition(DECLARED_HTML);
+    expect(comp.can({ type: "removeVariableDeclaration", id: "ghost" })).toMatchObject({
+      ok: false,
+      code: "E_VARIABLE_NOT_FOUND",
+    });
+    comp.removeVariableDeclaration("ghost");
+    expect(comp.getVariableDeclarations().map((d) => d.id)).toEqual(["title", "count"]);
+  });
+});
+
+describe("patch grammar", () => {
+  it("maps /variableDeclarations/{id} ↔ varDecl.{id} without colliding with /variables/", () => {
+    const path = variableDeclPath("brand-color");
+    expect(path).toBe("/variableDeclarations/brand-color");
+    expect(pathToKey(path)).toBe("varDecl.brand-color");
+    expect(keyToPath("varDecl.brand-color")).toBe(path);
+    // The value path family must stay untouched.
+    expect(pathToKey("/variables/brand-color")).toBe("var.brand-color");
+    expect(keyToPath("var.brand-color")).toBe("/variables/brand-color");
+  });
+
+  it("emits declaration patches on dispatch", async () => {
+    const comp = await openComposition(UNDECLARED_HTML);
+    const events: string[] = [];
+    comp.on("patch", (e) => {
+      for (const p of e.patches) events.push(`${p.op} ${p.path}`);
+    });
+    comp.declareVariable(TITLE_DECL);
+    comp.removeVariableDeclaration("title");
+    // Declaration ops also maintain the --{id} CSS compat prop (scalar defaults).
+    expect(events).toEqual([
+      "add /variableDeclarations/title",
+      "add /elements/hf-stage/inlineStyles/--title",
+      "remove /variableDeclarations/title",
+      "remove /elements/hf-stage/inlineStyles/--title",
+    ]);
+  });
+});
diff --git a/packages/sdk/src/types.ts b/packages/sdk/src/types.ts
index 490715dd1..136fd7b7b 100644
--- a/packages/sdk/src/types.ts
+++ b/packages/sdk/src/types.ts
@@ -112,6 +112,9 @@ export type EditOp =
     }
   | { type: "setClassStyle"; selector: string; styles: Record<string, string | null> }
   | { type: "setCompositionMetadata"; width?: number; height?: number; duration?: number }
+  | { type: "declareVariable"; declaration: CompositionVariable }
+  | { type: "updateVariableDeclaration"; id: string; declaration: CompositionVariable }
+  | { type: "removeVariableDeclaration"; id: string }
   | {
       type: "setVariableValue";
       id: string;
@@ -407,6 +410,24 @@ export interface Composition {
    */
   addElement(parent: HfId | null, index: number, html: string): HfId;
   setVariableValue(id: string, value: string | number | boolean | FontValue | ImageValue): void;
+  /**
+   * Declare a new variable in `data-composition-variables`. No-ops when the
+   * id is already declared (see can() for the E_DUPLICATE_VARIABLE check);
+   * creates the attribute when the composition has none yet.
+   */
+  declareVariable(declaration: CompositionVariable): void;
+  /**
+   * Replace an existing declaration wholesale (label, type, constraints,
+   * default — the id itself is immutable; rename = remove + declare). When
+   * the default changes to/from a scalar, the `--{id}` CSS compat custom
+   * property on the root is kept in sync, mirroring setVariableValue.
+   */
+  updateVariableDeclaration(id: string, declaration: CompositionVariable): void;
+  /**
+   * Remove a declaration (and the last one removes the whole attribute).
+   * Also clears the `--{id}` CSS compat custom property if present.
+   */
+  removeVariableDeclaration(id: string): void;
   /**
    * Read the typed variable declarations from `data-composition-variables`
    * (the canonical schema — same filter the render pipeline uses; malformed