@snowcone-app/canvas 0.22.0 → 0.26.0

package/dist/design/design-builder.d.ts

@@ -12,8 +12,18 @@ export interface DesignArtboard {
     width: number;
     height: number;
     /** Optional solid background fill behind all elements. Rendered everywhere
-     *  the design is — editor, exports, and server renders (realtime mockups). */
-    backgroundColor?: string;
+     *  the design is — editor, exports, and server renders (realtime mockups).
+     *  NOTE: the background is not an element, so it is NOT repaintable by
+     *  `useColorBinding` — designs that want a rebindable backdrop paint a
+     *  full-bleed `shape('rectangle', { fill: … })` instead. */
+    backgroundColor?: string | ColorToken;
+    /** Named color ROLES for value-matched rebinding (`useColorBinding`).
+     *  Mint tokens with `design.color('role')`; use them as `fill`/`color`
+     *  values so role and element can never drift. Validated at mint:
+     *  duplicate values across roles throw `E_COLOR_ROLE_COLLISION` (a
+     *  value-matched binding can't tell colliding roles apart), non-hex
+     *  values throw `E_COLOR_ROLE_INVALID`. */
+    colors?: Record<string, string>;
     /** Pacing role in a multi-page template (ADR-0086 albums). Template
      *  metadata only — never sent on the server render wire. */
     role?: ArtboardRole;
@@ -71,7 +81,8 @@ export interface TextOptions extends NamedOption {
     anchor?: Anchor;
     fontSize?: number;
     fontFamily?: string;
-    color?: string;
+    /** Hex string, or a `design.color('role')` token (resolved at build). */
+    color?: string | ColorToken;
     /** Horizontal text alignment. Named `textAlign` to match the canvas editor's
      *  element field (not `align`), so the builder and the editor read the same. */
     textAlign?: 'left' | 'center' | 'right';
@@ -87,7 +98,8 @@ export interface ShapeOptions extends NamedOption {
         width: number;
         height: number;
     };
-    fill?: string;
+    /** Hex string, or a `design.color('role')` token (resolved at build). */
+    fill?: string | ColorToken;
     rotation?: number;
     opacity?: number;
     /** star points / polygon sides. */
@@ -122,6 +134,30 @@ export interface LayerToken<K extends LayerKind = LayerKind, N extends string =
 }
 /** Runtime check used by parts before trusting a `layer` prop. */
 export declare function isLayerToken(value: unknown): value is LayerToken;
+declare const COLOR_TOKEN_BRAND: unique symbol;
+/**
+ * A validated claim that color role `N` exists in the design that minted it,
+ * carrying the role's (normalized) hex value. `useColorBinding` accepts it in
+ * place of a bare hex, so the chip and the painted elements can never drift —
+ * and `design({ colors })` rejects role-value collisions at mint time, which a
+ * value-matched binding cannot survive (one role's repaint would capture the
+ * other role's elements). Mint with {@link DesignBuilder.color}; not
+ * constructible by hand (branded).
+ */
+export interface ColorToken<N extends string = string> {
+    readonly name: N;
+    /** Normalized uppercase `#RRGGBB`. */
+    readonly value: string;
+    /** @internal */
+    readonly [COLOR_TOKEN_BRAND]: true;
+}
+/** Runtime check used by `useColorBinding` (and the builder's value slots)
+ *  before trusting a color value. */
+export declare function isColorToken(value: unknown): value is ColorToken;
+/** Normalize `#RGB`/`#RRGGBB` (any case) to uppercase `#RRGGBB` — the same
+ *  normalization `useColorBinding` matches with. Returns null when the value
+ *  is not a parsable hex color. */
+export declare function normalizeRoleHex(color: string): string | null;
 /** The token kind inferred for name `N` against the builder's accumulated
  *  per-kind name unions. A dynamically-loaded design (both unions degraded to
  *  `string`) yields the full `'text' | 'image'` union — typing degrades, the
@@ -141,12 +177,21 @@ type InferKind<N extends string, TText extends string, TImage extends string> =
  * API, runtime-validated instead (the degradation is deliberate and LOUD in
  * docs; never block the dynamic case).
  */
-export declare class DesignBuilder<out TText extends string = string, out TImage extends string = string> {
-    private readonly artboard;
+export declare class DesignBuilder<out TText extends string = string, out TImage extends string = string, out TColor extends string = string> {
+    /** The CURRENT authoring artboard — anchor math and new elements target it.
+     *  Reassigned by {@link DesignBuilder.artboard}; the initially-active
+     *  placement stays {@link activeName}. */
+    private current;
+    /** The placement that is active when the design mounts — always the FIRST
+     *  artboard (or the saved state's active one), never moved by `.artboard()`. */
+    private readonly activeName;
     private readonly els;
+    /** Declared color roles, name → normalized uppercase `#RRGGBB`. */
+    private readonly colorRoles;
     private idCounter;
-    /** Every artboard of a multi-page state (fromState `{ artboards: 'all' }`);
-     *  unset for single-artboard builders. */
+    /** Every artboard of a multi-artboard design — set by `fromState({ artboards:
+     *  'all' })` or the first `.artboard()` call; unset for single-artboard
+     *  builders. */
     private allArtboards?;
     constructor(artboard: DesignArtboard);
     /**
@@ -170,6 +215,37 @@ export declare class DesignBuilder<out TText extends string = string, out TImage
         activeArtboard: string;
     }, options?: FromStateOptions): DesignBuilder;
     private nextId;
+    /** A wire-shape snapshot of an authoring artboard, applying the same
+     *  background-export rule everywhere (a design background is part of the
+     *  design — exports and server renders paint it). */
+    private static snapshotArtboard;
+    /**
+     * Open a NEW artboard (placement) and make it the authoring context: layer
+     * calls after this target the new artboard — anchor math uses its
+     * dimensions, and the elements carry its membership tag (the public
+     * `artboard` field, PR #482). The FIRST artboard (from `design({ name })`)
+     * remains the initially-active placement when the design mounts; switch at
+     * runtime with `usePlacements()` / `<Editor.Placements/>` (ADR-0088).
+     *
+     * `label` must be the product's placement label (case-sensitive) — the same
+     * artboard-name-is-placement-label rule as `design({ name })`.
+     *
+     * ```ts
+     * const seed = design({ name: 'Front', width: 1480, height: 2328 })
+     *   .text('YOUR NAME', { anchor: 'top', name: 'headline' })
+     *   .artboard('Back', { width: 1480, height: 2328 })
+     *   .text('EST. 2026', { anchor: 'center', name: 'backline' });
+     * ```
+     *
+     * @throws EditorError `E_DUPLICATE_ARTBOARD` — the design already has an
+     *   artboard with this label.
+     */
+    artboard(label: string, dims: {
+        width: number;
+        height: number;
+        backgroundColor?: string | ColorToken;
+        role?: ArtboardRole;
+    }): this;
     /** Full-bleed background image (fills the whole artboard). Cover-fit (no
      *  distortion) when `aspectRatio` is supplied. Inserted at the bottom of the
      *  stack regardless of call order. The default layer name `'Background'`
@@ -177,19 +253,19 @@ export declare class DesignBuilder<out TText extends string = string, out TImage
      *  not one union with text — ADR-0085 §1). */
     background<const N extends string>(imageUrl: string, opts: BackgroundOptions & {
         name: N;
-    }): DesignBuilder<TText, TImage | N>;
-    background(imageUrl: string, opts?: BackgroundOptions): DesignBuilder<TText, TImage | 'Background'>;
+    }): DesignBuilder<TText, TImage | N, TColor>;
+    background(imageUrl: string, opts?: BackgroundOptions): DesignBuilder<TText, TImage | 'Background', TColor>;
     /** An anchored image element (not full-bleed). */
     image<const N extends string>(imageUrl: string, opts: ImageOptions & {
         name: N;
-    }): DesignBuilder<TText, TImage | N>;
-    image(imageUrl: string, opts?: ImageOptions): DesignBuilder<TText, TImage>;
+    }): DesignBuilder<TText, TImage | N, TColor>;
+    image(imageUrl: string, opts?: ImageOptions): DesignBuilder<TText, TImage, TColor>;
     /** An anchored text layer. Horizontal centring is exact (textAlign); vertical
      *  anchoring uses the font size as the line-height estimate. */
     text<const N extends string>(text: string, opts: TextOptions & {
         name: N;
-    }): DesignBuilder<TText | N, TImage>;
-    text(text: string, opts?: TextOptions): DesignBuilder<TText, TImage>;
+    }): DesignBuilder<TText | N, TImage, TColor>;
+    text(text: string, opts?: TextOptions): DesignBuilder<TText, TImage, TColor>;
     /**
      * Mint a {@link LayerToken} for a named layer — the only currency
      * `Editor.TextField` accepts (ADR-0085 §1). Compile time: `name` is
@@ -204,6 +280,20 @@ export declare class DesignBuilder<out TText extends string = string, out TImage
      *   is not bindable (shape/group/path).
      */
     layer<N extends TText | TImage>(name: N): LayerToken<InferKind<N, TText, TImage>, N>;
+    /**
+     * Mint a {@link ColorToken} for a declared color role. Compile time: `name`
+     * is constrained to the roles declared in `design({ colors })`. Runtime:
+     * validated against the declared roles (CMS/JSON-built designs degrade to
+     * `string` typing and rely on this throw).
+     *
+     * Use the token wherever the design paints the role (`fill`, `color`) AND
+     * as the `useColorBinding` argument — one source of truth, no hand-synced
+     * hex pairs.
+     *
+     * @throws EditorError `E_COLOR_ROLE_NOT_FOUND` — no role with this name;
+     *   lists the declared roles.
+     */
+    color<N extends TColor>(name: N): ColorToken<N>;
     /** Names of bindable layers of one kind, in stack order. @internal */
     layerNamesOfKind(kind: LayerKind): string[];
     /** An anchored vector shape. */
@@ -236,7 +326,10 @@ export declare class DesignBuilder<out TText extends string = string, out TImage
  * // …or hand d.toJSON() to <SnowconeCanvas/> for interactive editing — the
  * // `name`s let you bind layers with useImageBinding('art') / useTextBinding('headline').
  */
-export declare function design(artboard: DesignArtboard): DesignBuilder<never, never>;
+export declare function design<const C extends Record<string, string>>(artboard: DesignArtboard & {
+    colors: C;
+}): DesignBuilder<never, never, Extract<keyof C, string>>;
+export declare function design(artboard: DesignArtboard): DesignBuilder<never, never, never>;
 /**
  * Resolve a layer's kind against a live element/config list — the mount-time
  * revalidation `Editor.TextField` runs (the token is a validated claim; the

package/dist/design/product-config.d.ts

@@ -23,6 +23,16 @@ export interface ProductRenderConfig {
     };
     /** Every editable (non-color) placement label — placement pickers. */
     placementLabels: string[];
+    /** Geometry of EVERY renderable image placement, in catalog order — seed a
+     *  multi-placement design mechanically (ADR-0088):
+     *  `config.placements.reduce((d, p) => d.artboard(p.label, p), …)`. The
+     *  entry matching `placement` is the same object shape. */
+    placements: Array<{
+        label: string;
+        width: number;
+        height: number;
+        aspectRatio: number;
+    }>;
     /** First mockup scene that photographs the rendered variant — the default
      *  `<Editor.Preview mockupId>`. */
     primaryMockupId: string;

package/dist/design-builder-U7Su9MMC.js

@@ -0,0 +1,470 @@
+import { g as l } from "./editorErrors-B2mb1sVN.js";
+const x = 1;
+function d(e) {
+  return typeof e == "number" && Number.isFinite(e) ? Math.round(e * 100) / 100 : e;
+}
+function b(e) {
+  return {
+    ...e,
+    ...e.x !== void 0 && { x: d(e.x) },
+    ...e.y !== void 0 && { y: d(e.y) },
+    ...e.width !== void 0 && { width: d(e.width) },
+    ...e.height !== void 0 && { height: d(e.height) },
+    ...e.rotation !== void 0 && { rotation: d(e.rotation) }
+  };
+}
+function O(e) {
+  var n;
+  const t = (n = e.artboards) != null && n.length ? e.artboards : [{ name: "Front", width: 800, height: 800 }], r = t.map(() => []);
+  for (const i of e.elements || []) {
+    const o = i == null ? void 0 : i.artboard, s = typeof o == "string" ? t.findIndex((a) => (a.name || "Front") === o) : -1;
+    r[s >= 0 ? s : 0].push(A(i));
+  }
+  return {
+    schemaVersion: x,
+    artboards: t.map((i, o) => ({
+      id: `artboard-${o + 1}`,
+      name: i.name || "Front",
+      x: 0,
+      y: 0,
+      width: d(i.width || 800),
+      height: d(i.height || 800),
+      backgroundColor: i.backgroundColor || "transparent",
+      // Pass the artboard's flag through — the server worker only paints the
+      // background when this is true. Hardcoding `false` here silently dropped
+      // explicitly-set artboard backgrounds from every realtime mockup while
+      // the editor kept showing them (WYSIWYG drift).
+      exportBackground: i.exportBackground ?? !1,
+      elements: r[o],
+      distressTexture: i.distressTexture,
+      imageMask: i.imageMask
+    }))
+  };
+}
+function A(e) {
+  const t = e.type || e.transformType;
+  if (t === "image")
+    return N(e);
+  const { artboard: r, ...n } = e;
+  return b({
+    ...n,
+    type: t
+  });
+}
+function N(e) {
+  var c;
+  const t = e.transformData || {}, r = e.masks && e.masks.length > 0, n = t.width || 0, i = t.height || 0, o = r ? n : n * (t.cropWidth ?? 1), s = r ? i : i * (t.cropHeight ?? 1), a = {
+    id: e.id,
+    type: "image",
+    x: e.x || 0,
+    y: e.y || 0,
+    width: o,
+    height: s,
+    rotation: e.rotation || 0,
+    imageUrl: e.imageUrl,
+    imageAspectRatio: e.imageAspectRatio
+  };
+  return !r && (t.cropX !== 0 || t.cropY !== 0 || t.cropWidth !== 1 || t.cropHeight !== 1) && (a.cropX = t.cropX, a.cropY = t.cropY, a.cropWidth = t.cropWidth, a.cropHeight = t.cropHeight, a.needsCropPixelConversion = !0), t.flipHorizontal && (a.flipHorizontal = t.flipHorizontal), t.flipVertical && (a.flipVertical = t.flipVertical), t.borderRadius && (a.borderRadius = t.borderRadius), e.opacity !== void 0 && (a.opacity = e.opacity), e.distressEffect && (a.distressEffect = e.distressEffect), ((c = e.masks) == null ? void 0 : c.length) > 0 && (a.masks = e.masks), e.blendMode && (a.blendMode = e.blendMode), e.knockoutParts && (a.knockoutParts = e.knockoutParts), e.stroke && (a.stroke = e.stroke), b(a);
+}
+const p = "center", y = Symbol.for("snowcone.canvas.layerToken");
+function z(e) {
+  return typeof e == "object" && e !== null && e[y] === !0 && typeof e.name == "string" && (e.kind === "text" || e.kind === "image");
+}
+function C(e, t) {
+  return Object.freeze({ kind: e, name: t, [y]: !0 });
+}
+const w = Symbol.for("snowcone.canvas.colorToken");
+function E(e) {
+  return typeof e == "object" && e !== null && e[w] === !0 && typeof e.name == "string" && typeof e.value == "string";
+}
+function T(e, t) {
+  return Object.freeze({ name: e, value: t, [w]: !0 });
+}
+function S(e) {
+  let t = e.trim().toUpperCase();
+  return /^#[0-9A-F]{3}$/.test(t) && (t = "#" + t[1] + t[1] + t[2] + t[2] + t[3] + t[3]), /^#[0-9A-F]{6}$/.test(t) ? t : null;
+}
+function m(e) {
+  return E(e) ? e.value : e;
+}
+function g(e) {
+  const t = e.transformType;
+  return t === "image" ? "image" : t === "shape" || t === "group" || t === "path" ? null : "text";
+}
+function v(e) {
+  return e === "top-left" || e === "left" || e === "bottom-left" ? "left" : e === "top-right" || e === "right" || e === "bottom-right" ? "right" : "center";
+}
+function _(e) {
+  return e === "top-left" || e === "top" || e === "top-right" ? "top" : e === "bottom-left" || e === "bottom" || e === "bottom-right" ? "bottom" : "middle";
+}
+function u(e, t, r, n, i, o) {
+  const s = v(e), a = _(e), h = s === "left" ? t / 2 + o : s === "right" ? n - t / 2 - o : n / 2, c = a === "top" ? r / 2 + o : a === "bottom" ? i - r / 2 - o : i / 2;
+  return { x: h, y: c };
+}
+function $(e, t, r) {
+  const n = t / r;
+  if (e >= n) {
+    const s = r * e, a = t / s;
+    return {
+      width: s,
+      height: r,
+      cropX: (1 - a) / 2,
+      cropY: 0,
+      cropWidth: a,
+      cropHeight: 1
+    };
+  }
+  const i = t / e, o = r / i;
+  return {
+    width: t,
+    height: i,
+    cropX: 0,
+    cropY: (1 - o) / 2,
+    cropWidth: 1,
+    cropHeight: o
+  };
+}
+class f {
+  constructor(t) {
+    if (this.els = [], this.colorRoles = /* @__PURE__ */ new Map(), this.idCounter = 0, !(t.width > 0) || !(t.height > 0))
+      throw new Error("design(): artboard width and height must be positive numbers");
+    for (const [r, n] of Object.entries(t.colors ?? {})) {
+      const i = S(n);
+      if (i === null)
+        throw new l(
+          "E_COLOR_ROLE_INVALID",
+          `color role "${r}" is ${JSON.stringify(n)} — roles must be #RGB/#RRGGBB hex (useColorBinding matches by normalized hex value; other syntaxes can't bind).`,
+          { roleName: r, value: n, docSlug: "embed-mode" }
+        );
+      const o = [...this.colorRoles.entries()].find(([, s]) => s === i);
+      if (o)
+        throw new l(
+          "E_COLOR_ROLE_COLLISION",
+          `color roles "${o[0]}" and "${r}" both normalize to ${i}. useColorBinding matches elements by VALUE, so colliding roles would repaint each other's elements — give every role a distinct hex.`,
+          { roles: [o[0], r], value: i, docSlug: "embed-mode" }
+        );
+      this.colorRoles.set(r, i);
+    }
+    this.current = {
+      name: t.name || "Front",
+      width: t.width,
+      height: t.height,
+      backgroundColor: m(t.backgroundColor),
+      role: t.role
+    }, this.activeName = this.current.name;
+  }
+  /**
+   * Seed a builder from a previously saved canvas state — the editor shape
+   * `<SnowconeCanvas onChange>` emits (and `toJSON()` produces).
+   *
+   * This is how a saved editable template re-enters the turnkey embed path:
+   * load the template's state JSON, lift it back into a `DesignBuilder`, and
+   * hand it to `<RealtimeEmbed design={…}>`. By default the active artboard
+   * becomes the builder's artboard; elements tagged for other artboards are
+   * skipped (untagged elements are assumed to belong to the active one).
+   *
+   * Pass `{ artboards: 'all' }` to load a multi-page template (ADR-0086)
+   * whole: every artboard (with its pacing `role`) and every element are
+   * kept, membership tags preserved, so `toJSON()` / `toServerRequest()`
+   * emit all pages and `TemplateField.artboard` can scope fields per page.
+   */
+  static fromState(t, r = {}) {
+    const n = t.artboards.find((o) => o.name === t.activeArtboard) ?? t.artboards[0];
+    if (!n)
+      throw new Error("DesignBuilder.fromState(): state has no artboards");
+    const i = new f({
+      name: n.name,
+      width: n.width,
+      height: n.height,
+      backgroundColor: n.backgroundColor,
+      role: n.role
+    });
+    if (r.artboards === "all") {
+      i.allArtboards = t.artboards.map((o) => ({ ...o }));
+      for (const o of t.elements)
+        i.els.push(o.artboard ? { ...o } : { ...o, artboard: n.name });
+      return i;
+    }
+    for (const o of t.elements)
+      o.artboard && o.artboard !== n.name || i.els.push({ ...o });
+    return i;
+  }
+  nextId(t) {
+    return `${t}-${++this.idCounter}`;
+  }
+  /** A wire-shape snapshot of an authoring artboard, applying the same
+   *  background-export rule everywhere (a design background is part of the
+   *  design — exports and server renders paint it). */
+  static snapshotArtboard(t) {
+    return {
+      name: t.name,
+      width: t.width,
+      height: t.height,
+      ...t.backgroundColor ? {
+        backgroundColor: t.backgroundColor,
+        exportBackground: t.backgroundColor !== "transparent"
+      } : {},
+      ...t.role ? { role: t.role } : {}
+    };
+  }
+  /**
+   * Open a NEW artboard (placement) and make it the authoring context: layer
+   * calls after this target the new artboard — anchor math uses its
+   * dimensions, and the elements carry its membership tag (the public
+   * `artboard` field, PR #482). The FIRST artboard (from `design({ name })`)
+   * remains the initially-active placement when the design mounts; switch at
+   * runtime with `usePlacements()` / `<Editor.Placements/>` (ADR-0088).
+   *
+   * `label` must be the product's placement label (case-sensitive) — the same
+   * artboard-name-is-placement-label rule as `design({ name })`.
+   *
+   * ```ts
+   * const seed = design({ name: 'Front', width: 1480, height: 2328 })
+   *   .text('YOUR NAME', { anchor: 'top', name: 'headline' })
+   *   .artboard('Back', { width: 1480, height: 2328 })
+   *   .text('EST. 2026', { anchor: 'center', name: 'backline' });
+   * ```
+   *
+   * @throws EditorError `E_DUPLICATE_ARTBOARD` — the design already has an
+   *   artboard with this label.
+   */
+  artboard(t, r) {
+    if (!(r.width > 0) || !(r.height > 0))
+      throw new Error("design().artboard(): width and height must be positive numbers");
+    if (this.allArtboards || (this.allArtboards = [f.snapshotArtboard(this.current)]), this.allArtboards.some((n) => n.name === t))
+      throw new l(
+        "E_DUPLICATE_ARTBOARD",
+        `the design already has an artboard "${t}" — artboard names are placement labels and must be unique. Existing: ${JSON.stringify(this.allArtboards.map((n) => n.name))}.`,
+        { artboardName: t, validNames: this.allArtboards.map((n) => n.name), docSlug: "embed-mode" }
+      );
+    for (const n of this.els)
+      n.artboard || (n.artboard = this.current.name);
+    return this.current = {
+      name: t,
+      width: r.width,
+      height: r.height,
+      backgroundColor: m(r.backgroundColor),
+      role: r.role
+    }, this.allArtboards.push(f.snapshotArtboard(this.current)), this;
+  }
+  background(t, r = {}) {
+    const { width: n, height: i } = this.current;
+    let o;
+    if (r.aspectRatio && r.aspectRatio > 0) {
+      const a = $(r.aspectRatio, n, i);
+      o = {
+        type: "image",
+        width: a.width,
+        height: a.height,
+        cropX: a.cropX,
+        cropY: a.cropY,
+        cropWidth: a.cropWidth,
+        cropHeight: a.cropHeight,
+        flipHorizontal: !1,
+        flipVertical: !1,
+        borderRadius: 0
+      };
+    } else
+      o = {
+        type: "image",
+        width: n,
+        height: i,
+        cropX: 0,
+        cropY: 0,
+        cropWidth: 1,
+        cropHeight: 1,
+        flipHorizontal: !1,
+        flipVertical: !1,
+        borderRadius: 0
+      };
+    const s = {
+      id: this.nextId("bg"),
+      transformType: "image",
+      x: n / 2,
+      y: i / 2,
+      rotation: 0,
+      opacity: r.opacity ?? 1,
+      imageUrl: t,
+      imageAspectRatio: r.aspectRatio,
+      transformData: o,
+      name: r.name ?? "Background"
+    };
+    return this.els.unshift(s), this;
+  }
+  image(t, r = {}) {
+    const { width: n, height: i } = this.current, o = r.width ?? Math.round(n / 3), s = r.height ?? (r.aspectRatio ? Math.round(o / r.aspectRatio) : o), { x: a, y: h } = u(r.anchor ?? p, o, s, n, i, r.padding ?? 0), c = {
+      id: this.nextId("img"),
+      transformType: "image",
+      x: a,
+      y: h,
+      rotation: r.rotation ?? 0,
+      opacity: r.opacity ?? 1,
+      imageUrl: t,
+      imageAspectRatio: r.aspectRatio,
+      transformData: {
+        type: "image",
+        width: o,
+        height: s,
+        cropX: 0,
+        cropY: 0,
+        cropWidth: 1,
+        cropHeight: 1,
+        flipHorizontal: !1,
+        flipVertical: !1,
+        borderRadius: 0
+      },
+      ...r.name ? { name: r.name } : {}
+    };
+    return this.els.push(c), this;
+  }
+  text(t, r = {}) {
+    const { width: n, height: i } = this.current, o = r.fontSize ?? Math.round(this.current.height / 12), { x: s, y: a } = u(r.anchor ?? "top", 0, o, n, i, r.padding ?? Math.round(i / 20)), h = {
+      id: this.nextId("text"),
+      transformType: "custom",
+      x: s,
+      y: a,
+      rotation: r.rotation ?? 0,
+      text: t,
+      fontSize: o,
+      fontFamily: r.fontFamily ?? "Anton",
+      color: m(r.color) ?? "#ffffff",
+      textAlign: r.textAlign ?? "center",
+      bold: r.bold ?? !1,
+      italic: r.italic ?? !1,
+      transformData: { type: "custom" },
+      ...r.name ? { name: r.name } : {}
+    };
+    return this.els.push(h), this;
+  }
+  /**
+   * Mint a {@link LayerToken} for a named layer — the only currency
+   * `Editor.TextField` accepts (ADR-0085 §1). Compile time: `name` is
+   * constrained to this design's declared layer names, kind inferred from
+   * which per-kind union it falls in. Runtime: validated EAGERLY against the
+   * built elements (nearest the mistake), so CMS/JSON-loaded designs get the
+   * same protection with `string` typing.
+   *
+   * @throws EditorError `E_LAYER_NOT_FOUND` — no layer with this name; lists
+   *   the valid names per kind.
+   * @throws EditorError `E_LAYER_WRONG_KIND` — the name matches a layer that
+   *   is not bindable (shape/group/path).
+   */
+  layer(t) {
+    const r = this.els.find((i) => i.name === t);
+    if (!r) {
+      const i = this.layerNamesOfKind("text"), o = this.layerNamesOfKind("image");
+      throw new l(
+        "E_LAYER_NOT_FOUND",
+        `no layer "${t}" in this design. Text layers: ${JSON.stringify(i)}; image layers: ${JSON.stringify(o)}. Fix the name, or add the layer first — e.g. design(…).text('…', { name: '${t}' }).`,
+        { layerName: t, validNames: [...i, ...o], textNames: i, imageNames: o, docSlug: "embed-mode" }
+      );
+    }
+    const n = g(r);
+    if (!n)
+      throw new l(
+        "E_LAYER_WRONG_KIND",
+        `layer "${t}" is a ${r.transformType} element — only text and image layers are bindable. Bindable layers: ${JSON.stringify([...this.layerNamesOfKind("text"), ...this.layerNamesOfKind("image")])}.`,
+        { layerName: t, actualType: r.transformType, docSlug: "embed-mode" }
+      );
+    return C(n, t);
+  }
+  /**
+   * Mint a {@link ColorToken} for a declared color role. Compile time: `name`
+   * is constrained to the roles declared in `design({ colors })`. Runtime:
+   * validated against the declared roles (CMS/JSON-built designs degrade to
+   * `string` typing and rely on this throw).
+   *
+   * Use the token wherever the design paints the role (`fill`, `color`) AND
+   * as the `useColorBinding` argument — one source of truth, no hand-synced
+   * hex pairs.
+   *
+   * @throws EditorError `E_COLOR_ROLE_NOT_FOUND` — no role with this name;
+   *   lists the declared roles.
+   */
+  color(t) {
+    const r = this.colorRoles.get(t);
+    if (r === void 0)
+      throw new l(
+        "E_COLOR_ROLE_NOT_FOUND",
+        `no color role "${t}" in this design. Declared roles: ${JSON.stringify([...this.colorRoles.keys()])}. Declare roles up front — design({ …, colors: { ${t}: '#FF2D8A' } }).`,
+        { roleName: t, validNames: [...this.colorRoles.keys()], docSlug: "embed-mode" }
+      );
+    return T(t, r);
+  }
+  /** Names of bindable layers of one kind, in stack order. @internal */
+  layerNamesOfKind(t) {
+    return this.els.filter((r) => g(r) === t).map((r) => r.name).filter((r) => !!r);
+  }
+  /** An anchored vector shape. */
+  shape(t, r = {}) {
+    const { width: n, height: i } = this.current, o = r.size ?? Math.round(n / 6), s = typeof o == "number" ? o : o.width, a = typeof o == "number" ? o : o.height, { x: h, y: c } = u(r.anchor ?? p, s, a, n, i, r.padding ?? 0), R = {
+      type: "shape",
+      shapeType: t,
+      width: s,
+      height: a,
+      fillColor: m(r.fill) ?? "#000000",
+      fillOpacity: r.opacity ?? 1,
+      ...r.points !== void 0 ? { points: r.points } : {},
+      ...r.sides !== void 0 ? { sides: r.sides } : {}
+    }, k = {
+      id: this.nextId("shape"),
+      transformType: "shape",
+      x: h,
+      y: c,
+      rotation: r.rotation ?? 0,
+      transformData: R,
+      ...r.name ? { name: r.name } : {}
+    };
+    return this.els.push(k), this;
+  }
+  /** The composed elements, in render order (background first). Editor shape. */
+  get elements() {
+    return this.els.map((t) => ({ ...t }));
+  }
+  /** Editor-shape canvas state for `<SnowconeCanvas initialElements=… />` and
+   *  `serializeStateForServer`. `activeArtboard` is the artboard name. A
+   *  builder loaded with `fromState(…, { artboards: 'all' })` emits every
+   *  page (artboard `role`s and element membership tags included). */
+  toJSON() {
+    return this.allArtboards ? {
+      // Elements added via builder methods since the last context switch are
+      // untagged — they belong to the CURRENT authoring artboard; stamp them
+      // so the multi-artboard state groups them correctly.
+      elements: this.els.map(
+        (t) => t.artboard ? { ...t } : { ...t, artboard: this.current.name }
+      ),
+      artboards: this.allArtboards.map((t) => ({ ...t })),
+      // The initially-active placement (first artboard / saved state's
+      // active) — NOT the last `.artboard()` authoring context.
+      activeArtboard: this.activeName
+    } : {
+      elements: this.elements,
+      // A background set on a design is part of the design: flag it renderable
+      // so exports and server renders paint it, matching the editor (the
+      // export worker skips it without `exportBackground`) — see snapshotArtboard.
+      artboards: [f.snapshotArtboard(this.current)],
+      activeArtboard: this.current.name
+    };
+  }
+  /** Server-render payload for `RenderSession.renderState(placement, …)`.
+   *  Equivalent to `serializeStateForServer(design.toJSON())`. */
+  toServerRequest() {
+    return O(this.toJSON());
+  }
+}
+function L(e) {
+  return new f(e);
+}
+function F(e) {
+  return g(e);
+}
+export {
+  x as C,
+  f as D,
+  E as a,
+  L as d,
+  z as i,
+  F as l,
+  O as s
+};
+//# sourceMappingURL=design-builder-U7Su9MMC.js.map