@popcraft/kit 0.26.0 → 0.26.1

package/dist/chunks/chunk-SOHOKD4X.js

@@ -0,0 +1,1221 @@
+import { createRequire as __popcraftRequire } from 'node:module';
+import { fileURLToPath as __popcraftPath } from 'node:url';
+import { dirname as __popcraftDirname } from 'node:path';
+const require = __popcraftRequire(import.meta.url);
+const __filename = __popcraftPath(import.meta.url);
+const __dirname = __popcraftDirname(__filename);
+import {
+  settleMeasuredLayout
+} from "./chunk-STDKBPBH.js";
+import {
+  magicResize,
+  resizeMotion,
+  resizeTargetFromPreset
+} from "./chunk-ELFNBWSX.js";
+import {
+  templateTextMeasurer
+} from "./chunk-IYETCGF3.js";
+import {
+  applyPresetToDocument
+} from "./chunk-VTQNFI7N.js";
+import {
+  setDotTangent
+} from "./chunk-NCKWKNZM.js";
+import {
+  setKeysBinding
+} from "./chunk-HNOSQ4DO.js";
+import {
+  interactionFor
+} from "./chunk-Z5YN5STZ.js";
+import {
+  createTextStyle,
+  resolveTextNodeStyles
+} from "./chunk-VG6DGRSQ.js";
+import {
+  foldVariant
+} from "./chunk-D27VWWNN.js";
+import {
+  makePhotoFrame
+} from "./chunk-3M3BD7NP.js";
+import {
+  hexToColor
+} from "./chunk-U4LTVSLE.js";
+import {
+  animate,
+  animateShaderParam,
+  behave,
+  delay,
+  ease,
+  sceneSequence,
+  stagger
+} from "./chunk-NKAPBBXH.js";
+import {
+  COUNTER_PATH,
+  animatorPath,
+  withAnimator,
+  withCounter
+} from "./chunk-HRDPBECW.js";
+import {
+  defaultTransitionDuration,
+  is3DTransition
+} from "./chunk-Q5FICCEE.js";
+import {
+  addNode,
+  assignMaster,
+  createComponent,
+  createComponentSet,
+  createEllipse,
+  createFrame,
+  createGroup,
+  createImage,
+  createInstanceOf,
+  createMasterPage,
+  createPage,
+  createPixelGrid,
+  createPrintPage,
+  createRectangle,
+  createStar,
+  createText,
+  createVector,
+  documentFromPreset,
+  foldGuides,
+  init_print_pages,
+  init_scene_graph
+} from "./chunk-PEAXERBE.js";
+import {
+  PAGE_PRESETS,
+  init_page_presets,
+  presetById,
+  presetPx
+} from "./chunk-I3NUEMNB.js";
+import {
+  encodeCels,
+  init_cells
+} from "./chunk-SZSJX54N.js";
+import {
+  componentDefinitions,
+  init_instances,
+  owningComponent
+} from "./chunk-NIHPNDDJ.js";
+import {
+  asPath,
+  bindPath,
+  init_properties
+} from "./chunk-TZHWIVE5.js";
+import {
+  init_time,
+  timeShift
+} from "./chunk-AYZ32MGJ.js";
+import {
+  init_shader_params,
+  reflectShader
+} from "./chunk-D3K35HSL.js";
+import {
+  init_dist_node,
+  v4_default
+} from "./chunk-CQPFKV2N.js";
+import {
+  createSolidPaint,
+  init_types
+} from "./chunk-CVWCFBOJ.js";
+import {
+  presetPaint,
+  shaderPreset
+} from "./chunk-E6EMPOWS.js";
+import {
+  init_define_POPCRAFT_COMPONENT_IDS
+} from "./chunk-6VMOKHMF.js";
+
+// templates/src/kit.ts
+init_define_POPCRAFT_COMPONENT_IDS();
+init_dist_node();
+init_types();
+init_scene_graph();
+init_instances();
+init_print_pages();
+init_page_presets();
+init_cells();
+init_shader_params();
+init_properties();
+init_time();
+var hex = (h, a = 1) => {
+  const c = hexToColor(h, a);
+  if (!c) throw new Error(`"${h}" is not a hex colour`);
+  return c;
+};
+var geom = (v) => Math.round(v * 1e3) / 1e3 + 0;
+var quantizePoint = (p) => ({ ...p, x: geom(p.x), y: geom(p.y), ...p.handleIn ? { handleIn: { x: geom(p.handleIn.x), y: geom(p.handleIn.y) } } : {}, ...p.handleOut ? { handleOut: { x: geom(p.handleOut.x), y: geom(p.handleOut.y) } } : {} });
+var quantizePath = (p) => ({ ...p, points: p.points.map(quantizePoint), ...p.data ? { data: p.data.map((d) => typeof d === "number" ? geom(d) : d) } : {} });
+var NUMERIC = ["x", "y", "width", "height", "rotation", "opacity", "itemSpacing", "counterAxisSpacing", "cornerRadius", "minWidth", "maxWidth", "minHeight", "maxHeight", "paddingTop", "paddingRight", "paddingBottom", "paddingLeft"];
+var shown = (v) => {
+  try {
+    return JSON.stringify(v) ?? String(v);
+  } catch {
+    return String(v);
+  }
+};
+function assertGeometry(node) {
+  const n = node;
+  const bad = (key, v) => {
+    throw new Error(`Layer "${node.name}": ${key} must be a number (got ${shown(v)})`);
+  };
+  const finite = (v) => typeof v === "number" && Number.isFinite(v);
+  for (const key of NUMERIC) {
+    const v = n[key];
+    if (v === void 0 || v === null || finite(v)) continue;
+    if (key === "cornerRadius" && Array.isArray(v) && v.length === 4 && v.every(finite)) continue;
+    bad(key, v);
+  }
+  const pad2 = n.padding;
+  if (pad2 && typeof pad2 === "object") {
+    for (const [side, v] of Object.entries(pad2)) if (!finite(v)) bad(`padding.${side}`, v);
+  }
+}
+var placed = (at) => at ? { layoutPositioning: "ABSOLUTE", x: at.x, y: at.y } : {};
+var masking = (o) => o.mask ? { isMask: true, maskType: "ALPHA" } : {};
+var list = (v) => Array.isArray(v) ? [...v] : [v];
+var pad = (p) => typeof p === "number" ? { top: p, right: p, bottom: p, left: p } : p ?? { top: 0, right: 0, bottom: 0, left: 0 };
+var LOGO_PLACEHOLDERS = { mark: "/templates/logo-mark.svg", tile: "/templates/logo-tile.svg" };
+function swapTimes(s) {
+  const out = [];
+  const tailOf = (word) => ((s.unit === "word" ? word.split(/\s+/).filter(Boolean).length : word.replace(/\s/g, "").length) - 1) * s.stagger;
+  let t = s.at;
+  s.words.forEach((word, i) => {
+    const tail = tailOf(word);
+    const landed = t + s.in + tail, leaves = landed + s.hold, gone = leaves + s.out + tail;
+    out.push({ word, enters: t, landed, leaves, gone });
+    const next = s.words[i + 1];
+    t = next === void 0 ? gone : Math.max(gone, leaves + s.out + tailOf(next));
+  });
+  return out;
+}
+var COUNT_EASE = ease.out("cubic");
+function countKeys(c, local) {
+  const { from, to } = c.counter;
+  if (c.tick) return [{ t: local, v: from, ease: ease.linear }, { t: local + c.duration, v: to }];
+  return [{ t: local, v: from, ease: c.ease ?? COUNT_EASE }, { t: local + c.duration, v: to }];
+}
+function countCounter(c) {
+  if (!c.tick) return c.counter;
+  const steps = Math.max(1, Math.round(c.duration / c.tick));
+  return { ...c.counter, step: Math.abs(c.counter.to - c.counter.from) / steps };
+}
+var Kit = class {
+  constructor(name, preset2) {
+    this.vars = /* @__PURE__ */ new Map();
+    this.styles = /* @__PURE__ */ new Map();
+    this.components = /* @__PURE__ */ new Map();
+    this.componentsPage = null;
+    /**
+     * Hold vector geometry to a thousandth of a px, so a template drawing arcs, rings and curves with Math.sin / cos builds
+     * byte for byte the same on macOS and on Linux (V8's maths library can differ in the last bit between them). On for
+     * templates made since (the Game UI kit sets it); older sources keep their committed fixtures.
+     */
+    this.quantizeGeometry = false;
+    // ── Prototype variables ──
+    this.collections = /* @__PURE__ */ new Map();
+    this.doc = documentFromPreset(name, preset2);
+  }
+  get pageId() {
+    return this.doc.pages[0];
+  }
+  /** The last sheet on the first canvas page: a print page for fixed-page kinds, the starter frame for web / app. */
+  get sheet() {
+    const frames = this.doc.nodes[this.pageId].childIds.filter((id) => {
+      const n = this.doc.nodes[id];
+      return n.type === "FRAME" && !n.print?.isMaster;
+    });
+    const sheets = frames.filter((id) => this.doc.nodes[id].print?.isPrintPage);
+    const list2 = sheets.length ? sheets : frames;
+    return list2[list2.length - 1];
+  }
+  node(id) {
+    return this.doc.nodes[id];
+  }
+  /** Replace one node (the kit's only mutation primitive after `add`). */
+  put(id, node) {
+    assertGeometry(node);
+    this.doc = { ...this.doc, nodes: { ...this.doc.nodes, [id]: node } };
+  }
+  patch(id, props) {
+    const p = { ...props };
+    for (const key of ["fills", "strokes", "effects"]) if (p[key] && !Array.isArray(p[key])) p[key] = [p[key]];
+    this.put(id, { ...this.doc.nodes[id], ...p });
+  }
+  // ── Brand variables ──
+  /** A "Brand" collection: colours (hex, or a colour) as `brand/<role>` COLOR variables, fields as `brand/<name>` strings. */
+  brand(colors, fields = {}) {
+    const cid = v4_default();
+    const collection = { id: cid, name: "Brand", modes: [{ id: "Mode 1", name: "Mode 1" }], defaultModeId: "Mode 1" };
+    const variables = { ...this.doc.variables };
+    for (const [role, h] of Object.entries(colors)) {
+      const id = v4_default();
+      this.vars.set(role, id);
+      variables[id] = { id, name: `brand/${role}`, type: "COLOR", variableCollectionId: cid, valuesByMode: { "Mode 1": typeof h === "string" ? hex(h) : h }, scopes: ["ALL_FILLS", "STROKE_COLOR"] };
+    }
+    for (const [name, v] of Object.entries(fields)) {
+      const id = v4_default();
+      this.vars.set(name, id);
+      variables[id] = { id, name: `brand/${name}`, type: "STRING", variableCollectionId: cid, valuesByMode: { "Mode 1": v }, scopes: ["TEXT_CONTENT"] };
+    }
+    this.doc = { ...this.doc, variables, variableCollections: { ...this.doc.variableCollections, [cid]: collection } };
+    return this;
+  }
+  /**
+   * Scenery colours: roles a template paints with that are no part of its brand (a farm's soil, a fen's water) — a
+   * "Palette" collection of `palette/<role>` COLOR variables, bound and edited like brand roles, but not offered as
+   * brand slots, so a template with a rich illustration keeps its brand to the colours a kit should swap.
+   */
+  palette(colors) {
+    const cid = v4_default();
+    const variables = { ...this.doc.variables };
+    for (const [role, h] of Object.entries(colors)) {
+      const id = v4_default();
+      this.vars.set(role, id);
+      variables[id] = { id, name: `palette/${role}`, type: "COLOR", variableCollectionId: cid, valuesByMode: { "Mode 1": typeof h === "string" ? hex(h) : h }, scopes: ["ALL_FILLS", "STROKE_COLOR"] };
+    }
+    this.doc = { ...this.doc, variables, variableCollections: { ...this.doc.variableCollections, [cid]: { id: cid, name: "Palette", modes: [{ id: "Mode 1", name: "Mode 1" }], defaultModeId: "Mode 1" } } };
+    return this;
+  }
+  /** The literal value of a brand colour role (what a gradient stop, which cannot bind, is resolved to). */
+  color(role, a) {
+    const id = this.vars.get(role);
+    const c = id ? this.doc.variables?.[id]?.valuesByMode["Mode 1"] : void 0;
+    if (!c) throw new Error(`No brand colour "${role}"`);
+    return a === void 0 ? c : { ...c, a };
+  }
+  /** A solid paint bound to a brand colour. An unknown role is an authoring error: every solid fill binds. */
+  paint(role) {
+    const id = this.vars.get(role);
+    if (!id) throw new Error(`No brand colour "${role}"`);
+    return [{ ...createSolidPaint(this.color(role)), boundVariables: { color: id } }];
+  }
+  fillOf(c) {
+    return typeof c === "string" ? this.paint(c) : list(c);
+  }
+  /**
+   * A gradient between two brand colour roles. The stops are resolved to literal colours: `boundVariables`
+   * binds a SOLID paint's single colour and has nowhere to put a stop list, so a kit swap leaves gradients as
+   * they were — which is why a gradient here is always a glow over a bound solid, never the only ground.
+   */
+  gradient(o) {
+    const rad = (o.angle ?? 90) * Math.PI / 180;
+    const dx = Math.cos(rad) / 2, dy = Math.sin(rad) / 2;
+    return {
+      type: o.kind === "RADIAL" ? "GRADIENT_RADIAL" : "GRADIENT_LINEAR",
+      gradientStops: [{ position: 0, color: this.color(o.from, o.fromOpacity) }, { position: 1, color: this.color(o.to, o.toOpacity) }],
+      gradientHandlePositions: o.handles ?? [{ x: 0.5 - dx, y: 0.5 - dy }, { x: 0.5 + dx, y: 0.5 + dy }, { x: 0.5 - dy, y: 0.5 + dx }],
+      opacity: o.opacity ?? 1,
+      visible: true
+    };
+  }
+  /**
+   * A live shader fill (lib/engine/shader-fill.ts): one of the presets by name (lib/engine/shader-presets.ts: a node
+   * graph, so the file can open it in the node editor), or WGSL of the template's own when `code` is given, with
+   * values for its params — a preset's by their plain names (`speed`, `colorA`) or knob fields (`mesh_speed`). The
+   * fill's id is `f1`, so its params key as `fills[@f1].shaderParams.<field>` — what `animateShader` writes and the
+   * fill panel's diamonds edit. A param the shader does not have is an authoring error, not a silent no-op. Colours
+   * cannot bind to brand variables (a param is not a paint), so pass the brand's literal colours (`k.color(role)`)
+   * and keep text on a bound ground or tint.
+   */
+  shader(name, params, code) {
+    if (code) {
+      const declared = new Set(reflectShader(code).params.map((q) => q.name));
+      const stray = Object.keys(params).filter((q) => !declared.has(q));
+      if (stray.length) throw new Error(`shader "${name}" has no param ${stray.join(", ")}`);
+      return [{ id: "f1", type: "SHADER", shaderCode: code, shaderName: name, shaderParams: params, opacity: 1, visible: true }];
+    }
+    const preset2 = shaderPreset(name);
+    if (!preset2) throw new Error(`no shader preset "${name}"`);
+    return [presetPaint({ id: "f1", type: "SHADER", opacity: 1, visible: true }, preset2, params)];
+  }
+  /** Key a param of `id`'s shader fill (a number, or a colour / vector per component) by its name: `fills[@f1].shaderParams.<field>`. */
+  animateShader(id, param, keys) {
+    this.put(id, animateShaderParam(this.doc.nodes[id], "fills[@f1]", param, keys));
+  }
+  // ── Text styles ──
+  /** A named text style; defining the same name again returns the existing style (page builders share). */
+  textStyle(name, s) {
+    const existing = this.styles.get(name);
+    if (existing) return existing;
+    const id = v4_default();
+    const { size, ...rest } = s;
+    const style = createTextStyle(id, name, { fontSize: size, ...rest });
+    this.doc = { ...this.doc, styles: { ...this.doc.styles, [id]: style } };
+    this.styles.set(name, id);
+    return id;
+  }
+  /** The name of the text style `id` (what a variant's overrides restyle by). */
+  styleName(id) {
+    for (const [name, sid] of this.styles) if (sid === id) return name;
+    return void 0;
+  }
+  styleOf(name) {
+    const id = name ? this.styles.get(name) : void 0;
+    if (name && !id) throw new Error(`No text style "${name}"`);
+    return id ? this.doc.styles?.[id] : void 0;
+  }
+  // ── Nodes ──
+  add(node, parent) {
+    assertGeometry(node);
+    this.doc = addNode(this.doc, node, parent);
+    return node;
+  }
+  width(parent, w) {
+    const p = this.doc.nodes[parent];
+    if (typeof w === "number") return w;
+    return Math.max(1, p.width - (p.padding?.left ?? 0) - (p.padding?.right ?? 0));
+  }
+  text(parent, characters, o = {}) {
+    const n = this.styled(createText({
+      name: o.name ?? (characters.split("\n")[0].replace(/\{\{.*?\}\}/g, "").trim().slice(0, 40) || "Text"),
+      x: 0,
+      y: 0,
+      width: this.width(parent, o.width),
+      characters,
+      textAlign: o.align ?? "LEFT",
+      fills: this.paint(o.color ?? "text"),
+      textAutoResize: o.autoWidth ? "WIDTH_AND_HEIGHT" : "HEIGHT",
+      ...o.list ? { list: o.list } : {},
+      ...o.tabStops ? { tabStops: o.tabStops } : {},
+      layoutSizingHorizontal: o.autoWidth ? "HUG" : o.width === "FILL" || o.width === void 0 ? "FILL" : "FIXED",
+      layoutSizingVertical: "HUG",
+      ...o.effects ? { effects: list(o.effects) } : {},
+      ...placed(o.absolute)
+    }), o.style);
+    const box = templateTextMeasurer(n);
+    return this.add(box ? { ...n, width: box.width, height: box.height } : n, parent).id;
+  }
+  /** `n` set in the text style `name` (lib/document/text-styles.ts: the style's fields, as the renderer applies them). */
+  styled(n, name) {
+    const st = this.styleOf(name);
+    return st ? resolveTextNodeStyles({ ...n, textStyleId: st.id }, this.doc.styles) : n;
+  }
+  rect(parent, w, h, color, o = {}) {
+    const n = createRectangle({
+      name: o.name ?? "Shape",
+      x: 0,
+      y: 0,
+      width: this.width(parent, w),
+      height: h,
+      fills: this.fillOf(color),
+      strokes: o.stroke ? this.brandStroke(o.stroke) : [],
+      cornerRadius: o.radius ?? 0,
+      layoutSizingHorizontal: w === "FILL" ? "FILL" : "FIXED",
+      layoutSizingVertical: "FIXED",
+      ...o.opacity !== void 0 ? { opacity: o.opacity } : {},
+      ...o.effects ? { effects: list(o.effects) } : {},
+      ...masking(o),
+      ...placed(o.absolute)
+    });
+    return this.add(n, parent).id;
+  }
+  ellipse(parent, size, color, o = {}) {
+    const n = createEllipse({
+      name: o.name ?? "Ellipse",
+      x: 0,
+      y: 0,
+      width: size,
+      height: size,
+      fills: this.fillOf(color),
+      strokes: o.stroke ? this.brandStroke(o.stroke) : [],
+      layoutSizingHorizontal: "FIXED",
+      layoutSizingVertical: "FIXED",
+      ...o.opacity !== void 0 ? { opacity: o.opacity } : {},
+      ...o.effects ? { effects: list(o.effects) } : {},
+      ...masking(o),
+      ...placed(o.absolute)
+    });
+    return this.add(n, parent).id;
+  }
+  /**
+   * A picture from the app's own public files (`/screenshots/x.png`): a shape filled with the image, cover-fit
+   * (`fit: 'FIT'` contains it), clipped to its corners — so a card's radius and shadow are the shape's own.
+   */
+  picture(parent, url, w, h, o = {}) {
+    const fills = [{ type: "IMAGE", imageUrl: url, scaleMode: o.fit ?? "FILL", opacity: 1, visible: true }];
+    return this.rect(parent, w, h, fills, { name: "Picture", ...o });
+  }
+  /**
+   * A video clip from the shipped media (public/templates/media/<hash>), cover-fit (`fit: 'FIT'` contains it). It is a
+   * clip on its sheet's timeline: it plays from the sheet's start, `speed` source ms a timeline ms, from `from` ms in.
+   * The hash is what makes the clip part of the template's media (lib/storage/media-refs.ts).
+   */
+  video(parent, hash, w, h, o = {}) {
+    const { fit, speed, from, loop, ...shape } = o;
+    const fills = [{
+      type: "VIDEO",
+      videoHash: hash,
+      scaleMode: fit ?? "FILL",
+      videoPlayback: "AUTO",
+      videoLoop: loop ?? false,
+      videoIn: from ?? 0,
+      videoSpeed: speed ?? 1,
+      videoSound: { muted: true },
+      opacity: 1,
+      visible: true
+    }];
+    return this.rect(parent, w, h, fills, { name: "Video", ...shape });
+  }
+  /** A solid paint bound to a brand colour, drawn at `opacity` (a translucent panel over what is behind it). */
+  tint(role, opacity) {
+    return [{ ...this.paint(role)[0], opacity }];
+  }
+  /** A five-point star in a brand colour (a rating mark drawn as a shape, so it needs no glyph from the font). */
+  star(parent, size, color, o = {}) {
+    const n = createStar({
+      name: o.name ?? "Star",
+      x: 0,
+      y: 0,
+      width: size,
+      height: size,
+      innerRadius: 0.45,
+      fills: this.fillOf(color),
+      strokes: [],
+      layoutSizingHorizontal: "FIXED",
+      layoutSizingVertical: "FIXED",
+      ...o.opacity !== void 0 ? { opacity: o.opacity } : {},
+      ...placed(o.absolute)
+    });
+    return this.add(n, parent).id;
+  }
+  /**
+   * A vector shape in a brand colour (a chart's line or a donut's slice): `paths` in the layer's own px, inside a
+   * `width` × `height` box. `stroke` draws the paths as lines instead of filling them.
+   */
+  vector(parent, width, height, paths, color, o = {}) {
+    const line = o.strokeWidth !== void 0;
+    if (this.quantizeGeometry) {
+      width = geom(width);
+      height = geom(height);
+      paths = paths.map(quantizePath);
+      if (o.absolute) o = { ...o, absolute: { x: geom(o.absolute.x), y: geom(o.absolute.y) } };
+    }
+    const n = createVector({
+      name: o.name ?? "Vector",
+      x: 0,
+      y: 0,
+      width,
+      height,
+      paths,
+      fills: line ? [] : this.fillOf(color),
+      strokes: line && typeof color === "string" ? this.brandStroke({ color, width: o.strokeWidth }) : o.stroke ? this.brandStroke(o.stroke) : [],
+      layoutSizingHorizontal: "FIXED",
+      layoutSizingVertical: "FIXED",
+      ...o.opacity !== void 0 ? { opacity: o.opacity } : {},
+      ...o.effects ? { effects: list(o.effects) } : {},
+      ...masking(o),
+      ...placed(o.absolute)
+    });
+    return this.add(n, parent).id;
+  }
+  /** A stroke in a brand colour. */
+  brandStroke(stroke) {
+    const paint = this.paint(stroke.color)[0];
+    return [{ color: paint.color, width: stroke.width, alignment: stroke.align ?? "CENTER", cap: stroke.cap ?? "ROUND", join: stroke.join ?? "ROUND", dashPattern: stroke.dash ? [...stroke.dash] : [], boundVariables: paint.boundVariables }];
+  }
+  /**
+   * The brand logo: an IMAGE layer named `{{brand.logo}}`, which is what lib/brand/apply.ts fills from a kit
+   * and what `detectBrandSlots` advertises as the template's logo slot. Contain-fit, so any logo's aspect
+   * survives the swap.
+   */
+  logo(parent, width, height, o = {}) {
+    const image = createImage(LOGO_PLACEHOLDERS[o.placeholder ?? "mark"], { name: "{{brand.logo}}", x: 0, y: 0, width, height, strokes: [], scaleMode: "FIT", layoutSizingHorizontal: "FIXED", layoutSizingVertical: "FIXED", ...o.opacity !== void 0 ? { opacity: o.opacity } : {}, ...placed(o.absolute) });
+    return this.add(image, parent).id;
+  }
+  /**
+   * A photo frame: a mask group of [shape as mask, placeholder] — what `makePhotoFrame` builds in the editor,
+   * except that the placeholder's ground is a brand colour (every solid paint in a template binds). Drop a
+   * picture on it and it fills, cover-fit to the mask. FIXED size: auto layout moves a group as a leaf.
+   */
+  photo(parent, width, height, o = {}) {
+    const ground = this.paint(o.ground ?? "muted");
+    const shape = this.add(createRectangle({ name: "Mask", x: 0, y: 0, width, height, cornerRadius: o.radius ?? 0, fills: ground, strokes: [], layoutSizingHorizontal: "FIXED", layoutSizingVertical: "FIXED" }), parent);
+    const r = makePhotoFrame(this.doc, shape.id);
+    if (!r.id) throw new Error("photo: could not make a photo frame");
+    this.doc = r.document;
+    const placeholder = this.doc.nodes[r.id].childIds[1];
+    this.patch(placeholder, { fills: ground, layoutSizingHorizontal: "FIXED", layoutSizingVertical: "FIXED" });
+    this.patch(r.id, { name: o.name ?? "Photo frame", ...placed(o.absolute) });
+    return r.id;
+  }
+  /**
+   * A group at a hand-picked box: a 3D scene, or a group of layers inside one (lib/document/scene3d.ts), where
+   * layers are placed in 3D (x, y, z, tilts) rather than by a layout. `absolute` inside an auto-layout parent.
+   */
+  group(parent, box, o = {}) {
+    const g = createGroup([]);
+    Object.assign(g, { name: o.name ?? "Group", ...box, ...o.absolute ? { layoutPositioning: "ABSOLUTE" } : {} });
+    return this.add(g, parent).id;
+  }
+  /** A picture, cover-fit to its box (a template's own art: a data URL or a file in public/). */
+  image(parent, url, width, height, o = {}) {
+    return this.add(createImage(url, { name: o.name ?? "Picture", x: 0, y: 0, width, height, strokes: [], cornerRadius: o.radius ?? 0, layoutSizingHorizontal: "FIXED", layoutSizingVertical: "FIXED" }), parent).id;
+  }
+  /**
+   * Pixel art, as a real pixel canvas (an indexed PIXEL_GRID the pixel tools edit): `frames` are drawn as rows of
+   * characters, each a colour from `key` ('.' and ' ' are transparent), every row of every frame the same width.
+   * Several frames are an animation, playing `ms` a frame wherever the file plays (lib/engine/pixel/pixel-texture.ts).
+   * `cell` is the world size of one pixel.
+   */
+  pixels(parent, frames, key, o) {
+    const h = frames[0].length, w = frames[0][0].length;
+    const chars = Object.keys(key);
+    const palette = ["#00000000", ...chars.map((c) => (key[c].length === 7 ? `${key[c]}ff` : key[c]).toLowerCase())];
+    const index = new Map(chars.map((c, i) => [c, i + 1]));
+    const cels = frames.map((rows, f) => {
+      if (rows.length !== h || rows.some((r) => r.length !== w)) throw new Error(`pixels "${o.name ?? "Pixels"}": frame ${f + 1} is not ${w}\xD7${h}`);
+      const cells = new Uint32Array(w * h);
+      rows.forEach((row, y) => [...row].forEach((ch, x) => {
+        if (ch === "." || ch === " ") return;
+        const i = index.get(ch);
+        if (i === void 0) throw new Error(`pixels "${o.name ?? "Pixels"}": no colour for "${ch}"`);
+        cells[y * w + x] = i;
+      }));
+      return encodeCels(cells);
+    });
+    const ms = (f) => Array.isArray(o.ms) ? o.ms[f] ?? 100 : o.ms ?? 100;
+    const grid = createPixelGrid({
+      name: o.name ?? "Pixels",
+      pixelWidth: w,
+      pixelHeight: h,
+      cellSize: o.cell,
+      colorMode: "INDEXED",
+      palette,
+      transparentIndex: 0,
+      frames: cels.map((c, f) => ({ id: `${o.name ?? "px"}-${f + 1}`.replace(/\W+/g, "-"), cels: c, duration: ms(f) })),
+      ...o.opacity !== void 0 ? { opacity: o.opacity } : {},
+      layoutSizingHorizontal: "FIXED",
+      layoutSizingVertical: "FIXED",
+      ...placed(o.absolute)
+    });
+    return this.add(grid, parent).id;
+  }
+  /** Make a group or frame a 3D scene: its layers are placed in 3D and seen through `scene`'s camera and lights. */
+  scene3d(id, scene) {
+    this.patch(id, { scene3d: scene });
+  }
+  /**
+   * A frame at a hand-picked box, placed out of its parent's flow: a world a prototype's camera flies over, a layer of
+   * it scaled about its corner, a stage for layers placed by hand. It is an auto-layout frame of a fixed size whose
+   * children are placed the same way (give each `absolute`): a layout never moves them, and the editor still offers
+   * them as a stack.
+   */
+  frame(parent, box, o = {}) {
+    const n = createFrame({
+      name: o.name ?? "Frame",
+      ...box,
+      fills: o.fill ? this.fillOf(o.fill) : [],
+      strokes: o.stroke ? this.brandStroke(o.stroke) : [],
+      clipsContent: o.clip ?? false,
+      cornerRadius: o.radius ?? 0,
+      ...o.effects ? { effects: list(o.effects) } : {},
+      ...o.opacity !== void 0 ? { opacity: o.opacity } : {},
+      ...o.visible === false ? { visible: false } : {},
+      layoutMode: "VERTICAL",
+      padding: pad(0),
+      itemSpacing: 0,
+      counterAxisSpacing: 0,
+      primaryAxisAlignItems: "MIN",
+      counterAxisAlignItems: "MIN",
+      layoutPositioning: "ABSOLUTE",
+      layoutSizingHorizontal: "FIXED",
+      layoutSizingVertical: "FIXED"
+    });
+    return this.add(n, parent).id;
+  }
+  /** An auto-layout frame. Width defaults to filling the parent; height hugs its children. */
+  stack(parent, o = {}) {
+    const dir = o.direction ?? "VERTICAL";
+    const w = o.width === "HUG" ? 1 : this.width(parent, o.width === "FILL" ? void 0 : o.width);
+    const n = createFrame({
+      name: o.name ?? (dir === "VERTICAL" ? "Stack" : "Row"),
+      x: 0,
+      y: 0,
+      width: w,
+      height: typeof o.height === "number" ? o.height : 1,
+      fills: o.fill ? this.fillOf(o.fill) : [],
+      strokes: o.stroke ? this.brandStroke(o.stroke) : [],
+      clipsContent: o.clip ?? false,
+      cornerRadius: o.radius ?? 0,
+      ...o.effects ? { effects: list(o.effects) } : {},
+      ...placed(o.absolute),
+      layoutMode: dir,
+      padding: pad(o.padding),
+      itemSpacing: o.gap ?? 0,
+      counterAxisSpacing: o.gap ?? 0,
+      primaryAxisAlignItems: o.justify ?? "MIN",
+      counterAxisAlignItems: o.align ?? "MIN",
+      layoutSizingHorizontal: o.width === "HUG" ? "HUG" : typeof o.width === "number" ? "FIXED" : "FILL",
+      layoutSizingVertical: o.height === "FILL" ? "FILL" : typeof o.height === "number" ? "FIXED" : "HUG",
+      ...o.wrap ? { layoutWrap: "WRAP" } : {}
+    });
+    return this.add(n, parent).id;
+  }
+  /**
+   * Make the sheet itself an auto-layout column: its own fill (a brand variable, so a dark kit darkens the
+   * page), padding and spacing. `justify` spaces the sheet's children — a badge pinned top, a CTA bottom.
+   */
+  flowSheet(sheetId, gap, padding, paper = "paper", justify = "MIN", align = "MIN") {
+    const m = this.doc.settings?.margins;
+    const p = padding !== void 0 ? pad(padding) : m ? { top: m.top, right: m.right, bottom: m.bottom, left: m.left } : pad(72);
+    this.patch(sheetId, { fills: this.paint(paper), layoutMode: "VERTICAL", padding: p, itemSpacing: gap, counterAxisSpacing: gap, primaryAxisAlignItems: justify, counterAxisAlignItems: align, layoutSizingHorizontal: "FIXED", layoutSizingVertical: "FIXED" });
+  }
+  // ── Pages and masters ──
+  addSheet(preset2, name) {
+    const f = createPrintPage(this.doc, this.pageId, { preset: preset2, ...name ? { name } : {} });
+    if (preset2 && f.print && preset2.id !== this.doc.settings?.pageSize?.presetId && PAGE_PRESETS.find((p2) => {
+      const px = presetPx(p2);
+      return px.width === f.width && px.height === f.height;
+    })?.id !== preset2.id) f.print = { ...f.print, presetId: preset2.id };
+    this.doc = addNode(this.doc, f, this.pageId);
+    const p = preset2 ?? presetById(this.doc.settings?.pageSize?.presetId);
+    const folds = p ? foldGuides(p, f.width, f.height).map((g) => ({ ...g, pos: g.pos + (g.axis === "X" ? f.x : f.y) })) : [];
+    if (folds.length) {
+      const page = this.doc.nodes[this.pageId];
+      this.patch(this.pageId, { guides: [...page.guides ?? [], ...folds] });
+    }
+    return f.id;
+  }
+  /** The page that represents the whole file in the browser (Figma's "set as thumbnail"). */
+  setCover(nodeId) {
+    this.doc = { ...this.doc, thumbnailNodeId: nodeId };
+  }
+  nameSheet(sheetId, name) {
+    this.patch(sheetId, { name });
+  }
+  /** A canvas page (web / app screens live on any page; components keep their own). */
+  addPage(name) {
+    const page = { ...createPage(name), backgroundColor: this.doc.nodes[this.pageId].backgroundColor };
+    this.doc = { ...this.doc, pages: [...this.doc.pages, page.id], nodes: { ...this.doc.nodes, [page.id]: page } };
+    return page.id;
+  }
+  /** Another screen of a web / app template: a preset-sized frame beside the last one on `page`. */
+  addScreen(name, page = this.pageId) {
+    const preset2 = presetById(this.doc.settings?.pageSize?.presetId);
+    const siblings = this.doc.nodes[page].childIds.map((id) => this.doc.nodes[id]).filter((n) => n.type === "FRAME");
+    const f = createPrintPage(this.doc, page, { preset: preset2, name });
+    delete f.print;
+    const last = siblings[siblings.length - 1];
+    f.x = last ? last.x + last.width + 120 : 0;
+    f.y = last ? last.y : 0;
+    this.doc = addNode(this.doc, f, page);
+    return f.id;
+  }
+  /** The frame a prototype starts on (shown in the flows list). */
+  flowStart(frameId, name) {
+    this.patch(frameId, { isFlowStartingPoint: true, flowName: name });
+  }
+  /** A prototype link: clicking `from` goes to `to` with `transition` (BACK returns to the previous screen). */
+  link(from, to, transition = "PUSH_FROM_RIGHT", o = {}) {
+    const ix = interactionFor(to, v4_default(), {
+      trigger: o.key ? "KEY_DOWN" : o.trigger,
+      delay: o.delay,
+      navigation: o.navigation,
+      action: o.overlay,
+      transition: {
+        type: transition,
+        duration: o.duration ?? (transition === "INSTANT" ? 0 : defaultTransitionDuration(transition)),
+        easing: o.easing ?? (transition === "SMART_ANIMATE" || is3DTransition(transition) ? "EASE_IN_OUT" : "EASE_OUT"),
+        ...o.spring ? { spring: o.spring } : {},
+        ...o.stagger ? { stagger: o.stagger } : {},
+        ...o.origin ? { origin: o.origin } : {}
+      }
+    });
+    this.interact(from, { ...ix, ...o.direction ? { dragDirection: o.direction } : {}, ...o.key && o.key !== "*" ? { triggerKey: o.key } : {} });
+  }
+  /**
+   * Any prototype action on `id` (a Set variable to an expression, a Conditional, a Change to…), on `trigger`, or on
+   * the key `key` (a KEY_DOWN; `'*'` for any key). What the Prototype panel's interaction card writes.
+   */
+  on(id, action, o = {}) {
+    const trigger = o.key ? "KEY_DOWN" : o.trigger ?? "ON_CLICK";
+    this.interact(id, { id: v4_default(), trigger, action, ...o.key && o.key !== "*" ? { triggerKey: o.key } : {}, ...o.delay !== void 0 ? { triggerDelay: o.delay } : {} });
+  }
+  /**
+   * A TIMELINE action on layer `id` (lib/motion/timeline-control.ts): a drag (ON_DRAG) or a scroll (ON_SCROLL) scrubs a
+   * timeline, a click plays, pauses or seeks it — the frame's, or (`target: 'INSTANCE'`) the motion instance's.
+   */
+  timelineControl(id, trigger, timeline, o = {}) {
+    const ix = interactionFor(null, v4_default(), { trigger, navigation: "TIMELINE", transition: { type: "INSTANT", duration: 0, easing: "LINEAR" }, action: { timeline } });
+    this.interact(id, o.direction ? { ...ix, dragDirection: o.direction } : ix);
+  }
+  /** Make `id` a shared element: smart animate hands it to the layer with the same key on the other frame, wherever that sits. */
+  share(id, key) {
+    this.patch(id, { sharedElement: key });
+  }
+  /** Dragging `from` orbits `target` (a pass-through group in a 3D scene) live, by the drag (ORBIT_3D). */
+  orbit(from, target, orbit = {}) {
+    this.interact(from, interactionFor(target, v4_default(), { trigger: "ON_DRAG", navigation: "ORBIT_3D", transition: { type: "INSTANT", duration: 0, easing: "LINEAR" }, action: { orbit } }));
+  }
+  /** Add `interaction` to layer `id` (made by lib/editor/prototype-connect.ts `interactionFor`, as a drag-to-link is). */
+  interact(id, interaction) {
+    const n = this.doc.nodes[id];
+    this.patch(id, { interactions: [...n.interactions ?? [], interaction] });
+  }
+  /** A master draws only its children on the pages that use it, so it carries no fill of its own. */
+  addMaster() {
+    const m = createMasterPage(this.doc, this.pageId);
+    this.doc = addNode(this.doc, { ...m, fills: [] }, this.pageId);
+    return m.id;
+  }
+  useMaster(sheetIds, masterId) {
+    const patches = assignMaster(this.doc, sheetIds, masterId);
+    const nodes = { ...this.doc.nodes };
+    for (const id in patches) nodes[id] = { ...nodes[id], ...patches[id] };
+    this.doc = { ...this.doc, nodes };
+  }
+  // ── Components ──
+  ensureComponentsPage() {
+    this.componentsPage ??= this.addPage("Components");
+    return this.componentsPage;
+  }
+  definitions(props) {
+    return Object.fromEntries(Object.entries(props ?? {}).map(([k, v]) => {
+      if (typeof v === "string") return [k, { type: "TEXT", defaultValue: v }];
+      if ("swap" in v) return [k, { type: "INSTANCE_SWAP", defaultValue: this.componentId(v.swap) }];
+      if ("image" in v) return [k, { type: "IMAGE", defaultValue: v.image }];
+      if ("number" in v) return [k, { type: "NUMBER", defaultValue: v.number, ...v.min !== void 0 ? { min: v.min } : {}, ...v.max !== void 0 ? { max: v.max } : {}, ...v.step !== void 0 ? { step: v.step } : {} }];
+      if ("color" in v) return [k, { type: "COLOR", defaultValue: this.color(v.color) }];
+      return [k, { type: "MOTION", binds: v.motion, defaultValue: v.value }];
+    }));
+  }
+  /** A component's auto-layout box (the parts `component` and each variant of `variantSet` share). */
+  componentNode(name, o, defs, y) {
+    const dir = o.direction ?? "VERTICAL";
+    return createComponent({
+      name,
+      x: 0,
+      y,
+      width: typeof o.width === "number" ? o.width : 600,
+      height: typeof o.height === "number" ? o.height : 40,
+      fills: o.fill ? this.fillOf(o.fill) : [],
+      strokes: o.stroke ? this.brandStroke(o.stroke) : [],
+      cornerRadius: o.radius ?? 0,
+      ...o.clip ? { clipsContent: true } : {},
+      ...o.effects ? { effects: list(o.effects) } : {},
+      layoutMode: dir,
+      padding: pad(o.padding),
+      itemSpacing: o.gap ?? 0,
+      primaryAxisAlignItems: o.justify ?? "MIN",
+      counterAxisAlignItems: o.align ?? "MIN",
+      layoutSizingHorizontal: o.width === "HUG" ? "HUG" : "FIXED",
+      layoutSizingVertical: typeof o.height === "number" ? "FIXED" : "HUG",
+      componentPropertyDefinitions: defs,
+      ...o.description ? { description: o.description } : {},
+      // A motion component: its own timeline, which every instance plays on its own clock (lib/motion/instances.ts).
+      ...o.timeline ? { timeline: { fps: o.timeline.fps ?? 30, duration: o.timeline.duration, ...o.timeline.markers ? { markers: o.timeline.markers } : {} } } : {}
+    });
+  }
+  /**
+   * A component on the "Components" page; `build` adds its children. Text properties bind by name; NUMBER and
+   * COLOR inputs reach layers through `bindPath` / `bindKey`, MOTION properties set each instance's playback.
+   * With `timeline` it is a motion component: presets (`cues` on its id) and keys play on its own clock.
+   */
+  component(name, o, build) {
+    const page = this.ensureComponentsPage();
+    const c = this.componentNode(name, o, this.definitions(o.props), this.components.size * 160);
+    this.add(c, page);
+    this.components.set(name, c.id);
+    build(c.id);
+    return c.id;
+  }
+  /**
+   * A variant set: one component per state of `axis` (`State=Idle`, `State=Hover`…), side by side in a set that
+   * holds the properties they share. The states are animation states: `changeTo` wires how an instance moves
+   * between them (present mode glides over the layers they share by name, then plays the new state's timeline).
+   * `build` fills each state; `each` gives a state its own box options (a fill, a timeline). Named
+   * `<set>/<state>` for `instance` and `changeTo`; the set's name alone is its first state.
+   */
+  variantSet(name, axis, states, o, build, each = () => ({})) {
+    const page = this.ensureComponentsPage();
+    const set = createComponentSet({
+      name,
+      x: 0,
+      y: this.components.size * 160,
+      layoutMode: "HORIZONTAL",
+      itemSpacing: 32,
+      padding: { top: 24, right: 24, bottom: 24, left: 24 },
+      fills: [],
+      strokes: [],
+      layoutSizingHorizontal: "HUG",
+      layoutSizingVertical: "HUG",
+      primaryAxisAlignItems: "MIN",
+      counterAxisAlignItems: "MIN",
+      componentPropertyDefinitions: { [axis]: { type: "TEXT", defaultValue: states[0] }, ...this.definitions(o.props) },
+      ...o.description ? { description: o.description } : {}
+    });
+    this.add(set, page);
+    const out = {};
+    for (const state of states) {
+      const c = this.componentNode(`${axis}=${state}`, { ...o, ...each(state) }, {}, 0);
+      c.variantProperties = { [axis]: state };
+      this.add(c, set.id);
+      this.components.set(`${name}/${state}`, c.id);
+      if (!this.components.has(name)) this.components.set(name, c.id);
+      out[state] = c.id;
+      build(state, c.id);
+    }
+    return out;
+  }
+  /**
+   * An interactive component's state change: on `trigger`, an instance showing `from` shows `to` instead,
+   * gliding (smart animate) for `duration` ms. ON_HOVER / ON_PRESS last while hovered or pressed.
+   */
+  changeTo(from, trigger, to, duration = 200, easing = "EASE_OUT", on) {
+    this.interact(on ?? this.componentId(from), interactionFor(this.componentId(to), v4_default(), { trigger, navigation: "CHANGE_TO", transition: { type: "SMART_ANIMATE", duration, easing } }));
+  }
+  /** Whether a component named `name` has been made (parts shared by several sizes are made once). */
+  hasComponent(name) {
+    return this.components.has(name);
+  }
+  /** The id of the component named `name` (a variant as `<set>/<state>`): what cues on its timeline land on. */
+  componentIdOf(name) {
+    return this.componentId(name);
+  }
+  componentId(name) {
+    const id = this.components.get(name);
+    if (!id) throw new Error(`No component "${name}"`);
+    return id;
+  }
+  /** The definitions a layer's component answers with: its set's, for a variant (lib/document/instances.ts). */
+  defsOf(id) {
+    const c = owningComponent(this.doc.nodes, id);
+    return c ? componentDefinitions(this.doc.nodes, c.id) : {};
+  }
+  /** A text inside a component whose characters come from the property `prop`. */
+  propText(parent, prop, o = {}) {
+    const def = this.defsOf(parent)[prop];
+    const id = this.text(parent, String(def?.defaultValue ?? prop), { name: prop, ...o });
+    this.patch(id, { componentPropertyReferences: { characters: prop } });
+    return id;
+  }
+  /** Whether a component named `name` has been made. */
+  has(name) {
+    return this.components.has(name);
+  }
+  /** A picture inside a component that shows the IMAGE prop `prop`: each instance's own (a product card's photo). */
+  propImage(parent, prop, width, height, o = {}) {
+    const def = this.defsOf(parent)[prop];
+    if (def?.type !== "IMAGE") throw new Error(`propImage: no IMAGE property "${prop}"`);
+    const id = this.image(parent, String(def.defaultValue), width, height, { name: o.name ?? prop, ...o });
+    this.patch(id, { componentPropertyPaths: { imageUrl: prop } });
+    return id;
+  }
+  /**
+   * Instance `id`'s properties follow fields of the record it is about (its list's, its page's, or one picked with
+   * `record`): `bindProps(card, { Title: 'title', Image: 'image' })`, by field key.
+   */
+  bindProps(id, fields) {
+    const n = this.doc.nodes[id];
+    this.patch(id, { boundExpressions: { ...n.boundExpressions, ...Object.fromEntries(Object.entries(fields).map(([prop, key]) => [`prop:${prop}`, `item_${key}`])) } });
+  }
+  /** A nested instance inside a component whose main component comes from the INSTANCE_SWAP prop `prop`. */
+  propInstance(parent, prop, o = {}) {
+    const def = this.defsOf(parent)[prop];
+    const name = [...this.components].find(([, cid]) => cid === String(def?.defaultValue))?.[0];
+    if (!name) throw new Error(`No swap default for "${prop}"`);
+    const id = this.instance(parent, name, {}, { name: o.name ?? prop });
+    this.patch(id, { componentPropertyReferences: { mainComponent: prop } });
+    return id;
+  }
+  /**
+   * Layer `id` (inside a component) takes `path` from the NUMBER / COLOR property `prop`: `bindPath(bg,
+   * 'fills[#0].color', 'Accent')`. The item the path addresses gets a stable id, as a key's would.
+   */
+  bindPath(id, path, prop) {
+    if (!this.defsOf(id)[prop]) throw new Error(`bindPath: no property "${prop}"`);
+    const bound = bindPath(this.doc.nodes[id], asPath(path));
+    if (!bound) throw new Error(`bindPath: ${this.doc.nodes[id].name} has no "${path}"`);
+    this.put(id, { ...bound.node, componentPropertyPaths: { ...bound.node.componentPropertyPaths, [bound.path]: prop } });
+  }
+  /** The key of `path` at `t` on layer `id` takes its value from a property (`value · mul + add`): "fill to Percent". */
+  bindKey(id, path, t, bind) {
+    const n = this.doc.nodes[id];
+    const bound = bindPath(n, asPath(path));
+    const key = bound && n.motion?.tracks[bound.path]?.keys.find((k) => Math.abs(k.t - t) < 1);
+    if (!bound || !key) throw new Error(`bindKey: ${n.name} has no key on ${path} at ${t}`);
+    const edit = setKeysBinding(this.doc.nodes, [{ nodeId: id, path: bound.path, keyId: key.id }], bind);
+    this.put(id, { ...n, motion: edit[id] });
+  }
+  /** An instance of a named component with property values, and (for a motion component) its own playback. */
+  instance(parent, component, props = {}, o = {}) {
+    const cid = this.componentId(component);
+    const c = this.doc.nodes[cid];
+    const n = createInstanceOf(c, {
+      name: o.name ?? component.split("/")[0],
+      x: 0,
+      y: 0,
+      width: o.width === "FILL" ? this.width(parent, void 0) : o.width ?? c.width,
+      height: c.height,
+      componentProperties: Object.fromEntries(Object.entries(props).map(([k, v]) => [k, typeof v === "object" && "swap" in v ? this.componentId(v.swap) : v])),
+      ...c.clipsContent ? { clipsContent: true } : {},
+      ...o.playback ? { playback: o.playback } : {},
+      layoutSizingHorizontal: o.width === "FILL" ? "FILL" : c.layoutSizingHorizontal === "HUG" ? "HUG" : "FIXED",
+      layoutSizingVertical: "FIXED",
+      ...placed(o.absolute)
+    });
+    return this.add(n, parent).id;
+  }
+  /**
+   * A variable in the collection `collection` (created on first use, one mode) — prototype state a layer binds
+   * to and a SET_VARIABLE interaction changes, like the pricing page's `billing/yearly`.
+   */
+  variable(collection, name, type, value) {
+    let cid = this.collections.get(collection);
+    if (!cid) {
+      cid = v4_default();
+      this.collections.set(collection, cid);
+      this.doc = { ...this.doc, variableCollections: { ...this.doc.variableCollections, [cid]: { id: cid, name: collection, modes: [{ id: "Mode 1", name: "Mode 1" }], defaultModeId: "Mode 1" } } };
+    }
+    const id = v4_default();
+    this.doc = { ...this.doc, variables: { ...this.doc.variables, [id]: { id, name: `${collection.toLowerCase()}/${name}`, type, variableCollectionId: cid, valuesByMode: { "Mode 1": value } } } };
+    return id;
+  }
+  /**
+   * `prop` of layer `id` follows an expression over the variables, live (`boundExpressions`, lib/document/variables.ts):
+   * `bindExpression(bar, 'width', 'health / maxHealth * 320')`.
+   */
+  bindExpression(id, prop, expression) {
+    const n = this.doc.nodes[id];
+    this.patch(id, { boundExpressions: { ...n.boundExpressions, [prop]: expression } });
+  }
+  /** `prop` of layer `id` (`visible`, `opacity`…) reads the variable `variableId` live. */
+  bindVariable(id, prop, variableId) {
+    const n = this.doc.nodes[id];
+    this.patch(id, { boundVariables: { ...n.boundVariables, [prop]: variableId } });
+  }
+  /** On `trigger`, `id` sets the variable (or flips a boolean one): a SET_VARIABLE action. */
+  setVariable(id, variableId, o = {}) {
+    this.interact(id, interactionFor(null, v4_default(), {
+      trigger: o.trigger,
+      navigation: "SET_VARIABLE",
+      transition: { type: "INSTANT", duration: 0, easing: "LINEAR" },
+      action: { variableId, ...o.toggle ? { variableToggle: true } : { variableValue: o.value } }
+    }));
+  }
+  /** A Set variable action (not yet on a layer): to `value`, or to `expression` worked out when it runs, gliding over `glide` ms. */
+  static set(variableId, v) {
+    return {
+      navigationType: "SET_VARIABLE",
+      destinationId: null,
+      variableId,
+      transition: v.glide ? { type: "DISSOLVE", duration: v.glide, easing: v.easing ?? "EASE_OUT" } : { type: "INSTANT", duration: 0, easing: "LINEAR" },
+      ...v.toggle ? { variableToggle: true } : v.expression !== void 0 ? { variableExpression: v.expression } : { variableValue: v.value }
+    };
+  }
+  /** A Conditional action: the first branch whose condition holds runs its actions (a branch with no `if` is the else). */
+  static when(branches) {
+    return { navigationType: "CONDITIONAL", destinationId: null, transition: { type: "INSTANT", duration: 0, easing: "LINEAR" }, branches: branches.map((b) => ({ ...b.if !== void 0 ? { condition: b.if } : {}, actions: [...b.then] })) };
+  }
+  /** A Navigate (or overlay, back, close) action, for a Conditional's branch. */
+  static go(to, transition = "DISSOLVE", o = {}) {
+    return { navigationType: o.navigation ?? "NAVIGATE", destinationId: to, transition: { type: transition, duration: o.duration ?? (transition === "INSTANT" ? 0 : defaultTransitionDuration(transition)), easing: transition === "SMART_ANIMATE" || is3DTransition(transition) ? "EASE_IN_OUT" : "EASE_OUT" }, ...o.overlay };
+  }
+  /** A Change to action: the instance it fires on shows the variant `to` (by name), gliding over `duration` ms. */
+  changeAction(to, duration = 200, easing = "EASE_OUT") {
+    return { navigationType: "CHANGE_TO", destinationId: this.componentId(to), transition: { type: "SMART_ANIMATE", duration, easing } };
+  }
+  // ── Motion (lib/motion/author.ts, lib/motion/presets.ts) ──
+  /**
+   * Apply `cues` to the layers under `sheetId`, in order, through the one preset system. The layout is baked
+   * first, since a preset measures the layer it lands on (a rise travels half the layer's smaller side).
+   */
+  cues(sheetId, cues) {
+    this.layout();
+    for (const c of cues) {
+      const ids = cueLayers(this.doc, sheetId, c);
+      if (!c.stagger && ids.length > 1) throw new Error(`cue ${c.preset}: ${ids.length} layers named "${c.layer}" and no stagger`);
+      const r = applyPresetToDocument(this.doc, ids, c.preset, { ...c.params, at: c.at, ...c.stagger ? { stagger: c.stagger } : {}, ...c.onClick ? { onClick: true } : {} });
+      if (r.skipped.length) throw new Error(`cue ${c.preset} on "${c.layer}": ${r.skipped.map((x) => x.reason).join("; ")}`);
+      this.doc = r.document;
+    }
+  }
+  /**
+   * How present mode brings a slide on (`print.transition`: what the slide panel's Transition row sets, the show
+   * plays, and the PPTX export writes as the slide's `<p:transition>`).
+   */
+  transition(sheetId, type, duration = 400) {
+    const f = this.doc.nodes[sheetId];
+    if (!f.print) throw new Error(`${f.name} is not a slide`);
+    this.patch(sheetId, { print: { ...f.print, ...type === "INSTANT" ? {} : { transition: { type, duration, easing: "EASE_IN_OUT" } } } });
+  }
+  /**
+   * Make each text `counts` names count (lib/motion/text-animators.ts `withCounter`: the text rests at the
+   * finished figure, formatted), keyed on `text.counter` in its own layer time. Layout is baked again after,
+   * since the figure a text rests at is what it is measured with.
+   */
+  counts(sheetId, counts) {
+    for (const c of counts) {
+      const ids = cueLayers(this.doc, sheetId, { layer: c.layer, preset: "fade-in", at: c.at });
+      if (ids.length !== 1) throw new Error(`count on "${c.layer}": ${ids.length} layers of that name`);
+      const n = this.doc.nodes[ids[0]];
+      if (n.type !== "TEXT") throw new Error(`count on "${c.layer}": not a text`);
+      const counted = withCounter(n, countCounter(c));
+      const local = c.at - timeShift(this.doc.nodes, n.id, sheetId);
+      this.put(n.id, animate(counted, COUNTER_PATH, countKeys(c, local)));
+    }
+    this.layout();
+    const tl = this.doc.nodes[sheetId].timeline;
+    const end = Math.max(...counts.map((c) => c.at + c.duration));
+    if (tl && tl.duration < end) throw new Error(`a count runs to ${end} ms, past the ${tl.duration} ms timeline`);
+  }
+  /** Make each text `swaps` names a word swap (see `Swap`), keyed in its own layer time. */
+  swaps(sheetId, swaps) {
+    for (const sw of swaps) {
+      const ids = cueLayers(this.doc, sheetId, { layer: sw.layer, preset: "fade-in", at: sw.at });
+      const n = this.doc.nodes[ids[0]];
+      if (ids.length !== 1 || n.type !== "TEXT") throw new Error(`swap on "${sw.layer}": one text layer of that name wanted`);
+      const shift = timeShift(this.doc.nodes, n.id, sheetId);
+      let t = withAnimator({ ...n, characters: sw.words[0] }, { id: "swap", name: "Word swap", unit: sw.unit ?? "letter", range: { start: 0, end: 1, offset: 0 }, amount: 0, order: "forward", stagger: sw.stagger, props: { opacity: 0, translateY: sw.rise } });
+      const times = swapTimes(sw);
+      t = animate(t, "text.content", times.map((w) => ({ t: w.enters - shift, v: w.word, ease: ease.hold })));
+      t = animate(t, animatorPath("swap", "amount"), times.flatMap((w) => [
+        { t: w.enters - shift, v: 1, ease: ease.out("expo") },
+        { t: w.enters + sw.in - shift, v: 0, ease: ease.hold },
+        { t: w.leaves - shift, v: 0, ease: ease.named("expo", "in") },
+        { t: w.leaves + sw.out - shift, v: 1, ease: ease.hold }
+      ]));
+      this.put(n.id, t);
+    }
+    this.layout();
+  }
+  /**
+   * Sequence `sheetIds` as the scenes of one composition (id `compId`): each plays its whole timeline, and
+   * `transitions[i]` brings in scene i + 1 (lib/motion/author.ts `sceneSequence`). Behind the scenes, `ground`.
+   */
+  scenes(compId, name, sheetIds, transitions, ground) {
+    const fps = this.doc.nodes[sheetIds[0]].timeline?.fps;
+    if (!fps) throw new Error(`${name}: the first scene has no timeline`);
+    const comp = sceneSequence(this.doc.nodes, { id: compId, name, frames: sheetIds, fps, transitions: transitions.map((t) => t ?? null), ...ground ? { background: this.color(ground) } : {} });
+    this.doc = { ...this.doc, compositions: { ...this.doc.compositions, [compId]: comp } };
+    return comp;
+  }
+  /** A top-level frame's timeline: duration, frame rate, markers. */
+  timeline(sheetId, tl) {
+    this.patch(sheetId, { timeline: tl });
+  }
+  /** Key `path` on `id` (see `animate` in lib/motion/author.ts). */
+  animate(id, path, keys) {
+    this.put(id, animate(this.doc.nodes[id], path, keys));
+  }
+  /**
+   * The tangent of the motion path at the position key at `t` (px from the key, broken: the other side is left as
+   * it is) — what dragging a dot's handle on the canvas writes (lib/motion/spatial.ts `setDotTangent`).
+   */
+  pathTangent(id, t, side, vec) {
+    const n = this.doc.nodes[id];
+    this.put(id, { ...n, motion: setDotTangent(n, n.parentId ? this.doc.nodes[n.parentId] : void 0, t, side, vec, true) });
+  }
+  /** Behaviours on `path` (spin, sine, wiggle…): see `behave` in lib/motion/author.ts. */
+  behave(id, path, modifiers) {
+    this.put(id, behave(this.doc.nodes[id], path, modifiers));
+  }
+  /** Replace `id` with what `fn` makes of it (a preset from lib/motion/presets.ts, say). */
+  apply(id, fn) {
+    this.put(id, fn(this.doc.nodes[id]));
+  }
+  /** `id` and its subtree start `ms` later (a layer start). */
+  delay(id, ms) {
+    this.put(id, delay(this.doc.nodes[id], ms));
+  }
+  /** `id` staggers its children `ms` apart. */
+  stagger(id, ms, order = "index", more = {}) {
+    this.put(id, stagger(this.doc.nodes[id], ms, order, more));
+  }
+  /** `id` set in the text style `name` instead (a variant's smaller headline: same style system, another step). */
+  restyle(id, name) {
+    this.put(id, this.styled(this.doc.nodes[id], name));
+  }
+  /** The nodes under `rootId` (inclusive) named `name`, in tree order — how a variant's overrides find things. */
+  named(rootId, name) {
+    return layersNamed(this.doc, rootId, name);
+  }
+  // ── Master → variants ──
+  /**
+   * Lay the finished master out again at each of `specs`' sizes, beside it, through the same motion-aware
+   * magic resize the editor offers (lib/templates/resize.ts): auto layout reflows, off-frame entrances stay
+   * off-frame, and each copy's `adjust` then makes the per-size changes by hand. Positions are baked first,
+   * so the copies start from what the master really looks like.
+   */
+  variants(masterId, specs) {
+    this.layout();
+    const master = this.doc;
+    const out = [];
+    for (const spec of specs) {
+      const target = resizeTargetFromPreset(spec.preset);
+      if (!target) throw new Error(`Unknown preset ${spec.preset}`);
+      const r = magicResize(this.doc, masterId, target, void 0, { motion: false });
+      if (!r.id) throw new Error(`Could not resize ${masterId} to ${spec.preset}`);
+      this.doc = r.document;
+      const sheets = this.doc.nodes[this.pageId].childIds.filter((id) => this.doc.nodes[id].print?.isPrintPage);
+      const src = this.doc.nodes[r.id];
+      const last = out.length ? this.doc.nodes[out[out.length - 1]] : this.doc.nodes[masterId];
+      this.patch(r.id, { x: last.x + last.width + 120, y: 0, ...src.print ? { print: { ...src.print, index: sheets.indexOf(r.id) } } : {} });
+      spec.adjust?.(this, r.id);
+      this.layout();
+      this.doc = resizeMotion(master, masterId, this.doc, r.id, r.content, r.offset);
+      out.push(r.id);
+    }
+    return out;
+  }
+  /**
+   * Make `masterId` responsive from its narrower copies (see `variants`): at each breakpoint the master's layers take
+   * what their twins in that copy set differently (lib/document/breakpoints.ts `foldVariant`), so a file made from
+   * the widest size reflows in a narrow window and in the web preview. `copies` is breakpoint id → copy, widest first.
+   */
+  responsive(masterId, copies) {
+    this.layout();
+    for (const [breakpoint, copy] of Object.entries(copies)) this.doc = foldVariant(this.doc, masterId, copy, breakpoint);
+  }
+  /** Bake auto-layout positions and settle instance sizes (lib/templates/layout.ts). */
+  finish() {
+    this.layout();
+    return this.doc;
+  }
+  /**
+   * Bake the layout, re-measuring text as it will read (lib/templates/layout.ts `settleMeasuredLayout`): `{{brand.x}}`
+   * tokens stand for the brand field's words (what the canvas draws), and a text whose box width the layout changed
+   * wraps again at that width, until no text changes size.
+   */
+  layout() {
+    this.doc = settleMeasuredLayout(this.doc);
+  }
+};
+function cueLayers(doc, rootId, cue) {
+  const names = typeof cue.layer === "string" ? [cue.layer] : cue.layer;
+  return names.flatMap((name) => {
+    const ids = layersNamed(doc, rootId, name);
+    if (!ids.length) throw new Error(`cue ${cue.preset}: no layer "${name}"`);
+    return ids;
+  });
+}
+function layersNamed(doc, rootId, name) {
+  const out = [];
+  const walk = (id) => {
+    const n = doc.nodes[id];
+    if (!n) return;
+    if (n.name === name) out.push(id);
+    for (const c of n.childIds) walk(c);
+  };
+  walk(rootId);
+  return out;
+}
+var preset = (id) => {
+  const p = presetById(id);
+  if (!p) throw new Error(`Unknown preset ${id}`);
+  return p;
+};
+
+export {
+  hex,
+  LOGO_PLACEHOLDERS,
+  swapTimes,
+  COUNT_EASE,
+  countKeys,
+  countCounter,
+  Kit,
+  cueLayers,
+  layersNamed,
+  preset
+};