Function handleSetVariableValue

packages/sdk/src/engine/mutate.ts:817–862

(
  parsed: ParsedDocument,
  id: string,
  value: string | number | boolean | FontValue | ImageValue,
)

}

function handleSetVariableValue(
  parsed: ParsedDocument,
  id: string,
  value: string | number | boolean | FontValue | ImageValue,
): MutationResult {
  const root = findRoot(parsed.document);
  if (!root) return EMPTY;

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

  if (isObjectVariableValue(value)) {
    // Object values (font / image): write to JSON model only — objects are not
    // valid CSS custom property values (LOCKED §7).
    writeVariableDefault(parsed.document, id, value);
    const p = valueChange(modelPath, oldVarDefault ?? null, value);
    return { forward: [p.forward], inverse: [p.inverse] };
  }

  // Scalar values: update the JSON model (B1 — drives the runtime) and also
  // keep the CSS custom prop as secondary / compat for compositions that
  // CSS-bind directly to --{id}.
  const cssVar = `--${id}`;
  const rootId = root.getAttribute("data-hf-id");
  const oldStyles = getElementStyles(root);
  const oldCssValue = oldStyles[cssVar] ?? null;
  const newVal = String(value);
  setElementStyles(root, { [cssVar]: newVal });
  writeVariableDefault(parsed.document, id, value);

  // Emit explicit patches for both the JSON model (canonical) and the CSS compat
  // prop. Keeping them separate means apply-patches.ts can handle each path type
  // purely (variable path → model only; style path → CSS only), so inverse patches
  // correctly restore the exact pre-call state without CSS-side-effect ambiguity.
  const modelP = valueChange(modelPath, oldVarDefault ?? null, value);
  const forward: JsonPatchOp[] = [modelP.forward];
  const inverse: JsonPatchOp[] = [modelP.inverse];

  if (rootId) {
    const cssPatch = scalarChange(stylePath(rootId, cssVar), oldCssValue, newVal);
    forward.push(cssPatch.forward);
    inverse.push(cssPatch.inverse);
  }

  return { forward, inverse };
}

// ─── GSAP selector helpers ───────────────────────────────────────────────────