@snowcone-app/canvas 0.16.0 → 0.17.0

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

@@ -69,11 +69,52 @@ export interface ShapeOptions extends NamedOption {
     sides?: number;
     padding?: number;
 }
+/** The bindable layer kinds. Shapes are not bindable in v1. */
+export type LayerKind = 'text' | 'image';
+/**
+ * Any design builder, regardless of its compile-time layer-name unions.
+ * CONSUMERS of a builder (props, context) must use this — `DesignBuilder`
+ * (= `DesignBuilder<string, string>`) is not a supertype of a statically
+ * typed builder because `layer()`'s name constraint narrows with the design.
+ */
+export type AnyDesign = DesignBuilder<any, any>;
+declare const LAYER_TOKEN_BRAND: unique symbol;
+/**
+ * A validated claim that layer `N` of kind `K` exists in the design that
+ * minted it. The ONLY currency `Editor.TextField` (and future `ImageField`)
+ * accepts — bare strings are rejected (`E_LAYER_TOKEN_REQUIRED`). Mint with
+ * {@link DesignBuilder.layer}; not constructible by hand (branded).
+ *
+ * @experimental ADR-0085; subject to change until the P4 gate.
+ */
+export interface LayerToken<K extends LayerKind = LayerKind, N extends string = string> {
+    readonly kind: K;
+    readonly name: N;
+    /** @internal */
+    readonly [LAYER_TOKEN_BRAND]: true;
+}
+/** Runtime check used by parts before trusting a `layer` prop. */
+export declare function isLayerToken(value: unknown): value is LayerToken;
+/** 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
+ *  runtime validation in `layer()` is the net that still fires (0G#2). */
+type InferKind<N extends string, TText extends string, TImage extends string> = [
+    N
+] extends [TText] ? ([N] extends [TImage] ? LayerKind : 'text') : 'image';
 /**
  * A composed design. Add elements by intent, then emit it for the editor or the
  * render path. Methods are chainable.
+ *
+ * The two type parameters accumulate the design's NAMED layer literals per
+ * kind (ADR-0085 §1): naming a layer in `.text()` / `.image()` /
+ * `.background()` widens the corresponding union, so `design.layer("naem")`
+ * is a compile error listing the valid names. Designs loaded from JSON
+ * ({@link DesignBuilder.fromState}) degrade both unions to `string` — same
+ * API, runtime-validated instead (the degradation is deliberate and LOUD in
+ * docs; never block the dynamic case).
  */
-export declare class DesignBuilder {
+export declare class DesignBuilder<out TText extends string = string, out TImage extends string = string> {
     private readonly artboard;
     private readonly els;
     private idCounter;
@@ -101,13 +142,41 @@ export declare class DesignBuilder {
     private nextId;
     /** 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. */
-    background(imageUrl: string, opts?: BackgroundOptions): this;
+     *  stack regardless of call order. The default layer name `'Background'`
+     *  joins the IMAGE-layer token union (auto-injected names are deliberately
+     *  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'>;
     /** An anchored image element (not full-bleed). */
-    image(imageUrl: string, opts?: ImageOptions): this;
+    image<const N extends string>(imageUrl: string, opts: ImageOptions & {
+        name: N;
+    }): DesignBuilder<TText, TImage | N>;
+    image(imageUrl: string, opts?: ImageOptions): DesignBuilder<TText, TImage>;
     /** An anchored text layer. Horizontal centring is exact (textAlign); vertical
      *  anchoring uses the font size as the line-height estimate. */
-    text(text: string, opts?: TextOptions): this;
+    text<const N extends string>(text: string, opts: TextOptions & {
+        name: N;
+    }): DesignBuilder<TText | N, TImage>;
+    text(text: string, opts?: TextOptions): DesignBuilder<TText, TImage>;
+    /**
+     * 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).
+     * @experimental ADR-0085; subject to change until the P4 gate.
+     */
+    layer<N extends TText | TImage>(name: N): LayerToken<InferKind<N, TText, TImage>, N>;
+    /** Names of bindable layers of one kind, in stack order. @internal */
+    layerNamesOfKind(kind: LayerKind): string[];
     /** An anchored vector shape. */
     shape(kind: ShapeKind, opts?: ShapeOptions): this;
     /** The composed elements, in render order (background first). Editor shape. */
@@ -142,5 +211,11 @@ export declare class DesignBuilder {
  * // …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;
+export declare function design(artboard: DesignArtboard): DesignBuilder<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
+ * mounted Root's design state is the authority). @internal
+ */
+export declare function layerKindOfConfig(el: AnyElementConfig): LayerKind | null;
 export {};

package/dist/editorError-DMENTZ-3.js

@@ -0,0 +1,19 @@
+import { y as t } from "./HybridHistoryManager-Bht98XRv.js";
+class e extends Error {
+  constructor(o, i, s = {}) {
+    super(`[Editor] ${o}: ${i}`), this.name = "EditorError", this.code = o, this.data = { code: o, ...s };
+  }
+}
+function E(r) {
+  return r instanceof Error && r.name === "EditorError" && "code" in r;
+}
+function a() {
+  var r;
+  return typeof t < "u" && ((r = t.env) == null ? void 0 : r.NODE_ENV) !== "production";
+}
+export {
+  e as E,
+  E as a,
+  a as i
+};
+//# sourceMappingURL=editorError-DMENTZ-3.js.map

package/dist/editorError-DMENTZ-3.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"editorError-DMENTZ-3.js","sources":["../src/errors/editorError.ts"],"sourcesContent":["/**\n * Structured error contract for the `Editor.*` composable primitives (ADR-0085,\n * decision E3): every public throw carries a stable machine-readable code plus\n * an `error.data` payload, with the human/agent message RENDERED from that\n * data. Tests assert on `code` + `data` fields, never on prose substrings.\n *\n * Message style (E2): verifiable facts from data in hand only — name the\n * violated contract, the offending part, the valid alternatives, and the exact\n * corrective code. Never heuristic guesses.\n */\n\n/** Stable codes for composition/runtime violations. ADR-0085 catalog. */\nexport type EditorErrorCode =\n  /** An `Editor.*` part mounted outside `<Editor.Root>`. */\n  | 'E_OUTSIDE_ROOT'\n  /** A layer token (or its name) matches no layer in the mounted design. */\n  | 'E_LAYER_NOT_FOUND'\n  /** The layer exists but is not the kind the part binds (e.g. an image\n   *  layer passed to `Editor.TextField`). */\n  | 'E_LAYER_WRONG_KIND'\n  /** `Editor.TextField` received a bare string (or other non-token) — layers\n   *  bind by `design.layer(\"name\")` token only (ADR-0085 §1). */\n  | 'E_LAYER_TOKEN_REQUIRED'\n  /** Programmatic rename/delete of a layer a mounted TextField is bound to. */\n  | 'E_BOUND_LAYER_MUTATION'\n  /** Two `Editor.Canvas` parts mounted under one Root. */\n  | 'E_DUPLICATE_CANVAS'\n  /** A part that needs a mounted `Editor.Canvas` found none under this Root. */\n  | 'E_REQUIRES_CANVAS'\n  /** `Editor.Buy` mounted without product context. */\n  | 'E_BUY_NO_PRODUCT'\n  /** The lazy renderer chunk failed to load (network/CDN). Retryable. */\n  | 'E_CHUNK_LOAD_FAILED'\n  /** Embed wiring invalid at mount (missing grant/mockupIds, variant or\n   *  placement mismatch) — the throw-mode upgrade of `validateEmbed` (F3). */\n  | 'E_EMBED_CONFIG';\n\nexport interface EditorErrorData {\n  code: EditorErrorCode;\n  /** Slug under https://developers.snowcone.app/ for the violated contract. */\n  docSlug?: string;\n  /** Valid alternatives when the violation is a bad identifier. */\n  validNames?: readonly string[];\n  /** Structured facts about the offending values. */\n  [key: string]: unknown;\n}\n\n/**\n * The one error class every `Editor.*` invariant throws. `code` is the stable\n * test/agent contract; `message` is rendered from `data` and may be reworded.\n */\nexport class EditorError extends Error {\n  readonly code: EditorErrorCode;\n  readonly data: EditorErrorData;\n\n  constructor(code: EditorErrorCode, message: string, data: Omit<EditorErrorData, 'code'> = {}) {\n    super(`[Editor] ${code}: ${message}`);\n    this.name = 'EditorError';\n    this.code = code;\n    this.data = { code, ...data };\n  }\n}\n\nexport function isEditorError(err: unknown): err is EditorError {\n  return err instanceof Error && err.name === 'EditorError' && 'code' in err;\n}\n\n/** True outside production bundles — mirrors the embed's existing typeof-guarded\n *  pattern (non-Node bundlers may not define `process`). */\nexport function isDevOrTest(): boolean {\n  return typeof process !== 'undefined' && process.env?.NODE_ENV !== 'production';\n}\n"],"names":["EditorError","code","message","data","isEditorError","err","isDevOrTest","process"],"mappings":";AAmDO,MAAMA,UAAoB,MAAM;AAAA,EAIrC,YAAYC,GAAuBC,GAAiBC,IAAsC,CAAA,GAAI;AAC5F,UAAM,YAAYF,CAAI,KAAKC,CAAO,EAAE,GACpC,KAAK,OAAO,eACZ,KAAK,OAAOD,GACZ,KAAK,OAAO,EAAE,MAAAA,GAAM,GAAGE,EAAA;AAAA,EACzB;AACF;AAEO,SAASC,EAAcC,GAAkC;AAC9D,SAAOA,aAAe,SAASA,EAAI,SAAS,iBAAiB,UAAUA;AACzE;AAIO,SAASC,IAAuB;;AACrC,SAAO,OAAOC,IAAY,SAAeA,IAAAA,EAAQ,QAARA,gBAAAA,EAAa,cAAa;AACrE;"}

package/dist/editorErrors-DbIEtCTt.js

@@ -0,0 +1,29 @@
+import { a as n, i as t } from "./editorError-DMENTZ-3.js";
+const r = [];
+function i(e) {
+  t() && r.push(e);
+}
+function d() {
+  return [...r];
+}
+function a() {
+  r.length = 0;
+}
+function c() {
+  if (r.length === 0) return;
+  const e = r.map((o) => n(o) ? `${o.code}: ${o.message}` : `${o.name}: ${o.message}`).join(`
+  - `);
+  throw r.length = 0, new Error(
+    `expectNoEditorErrors: ${e.includes(`
+`) ? "errors were" : "an error was"} contained by <Editor.Root>'s boundary during this test:
+  - ${e}
+A contained error renders an error card in prod — this composition is broken even if the test rendered "successfully".`
+  );
+}
+export {
+  a,
+  c as e,
+  d as g,
+  i as r
+};
+//# sourceMappingURL=editorErrors-DbIEtCTt.js.map

package/dist/editorErrors-DbIEtCTt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"editorErrors-DbIEtCTt.js","sources":["../src/testing/editorErrors.ts"],"sourcesContent":["/**\n * Test-side hooks into the `Editor.*` error contract (ADR-0085 / D11).\n *\n * Containment is a PROD feature: under `NODE_ENV=test`, Root's boundary\n * rethrows render-time composition errors, so a broken composition fails the\n * test naturally. The remaining blind spot is the NON-throwing channel —\n * runtime failures routed straight to the error card (e.g. the lazy renderer\n * chunk failing to load, `E_CHUNK_LOAD_FAILED`) and prod-routed handler\n * invariants. Those are recorded here in test envs so\n * {@link expectNoEditorErrors} can fail a green-looking test that actually\n * rendered an error card.\n *\n * ```ts\n * import { expectNoEditorErrors } from '@snowcone-app/canvas/testing';\n *\n * afterEach(() => expectNoEditorErrors());\n * ```\n */\n\nimport { isEditorError, isDevOrTest } from '../errors/editorError.js';\n\nconst recorded: Error[] = [];\n\n/** Record a contained editor error (test/dev envs only). @internal */\nexport function recordContainedEditorError(error: Error): void {\n  if (isDevOrTest()) recorded.push(error);\n}\n\n/** Errors contained since the last drain, without draining. */\nexport function getContainedEditorErrors(): readonly Error[] {\n  return [...recorded];\n}\n\n/** Drop all recorded errors (e.g. after asserting an EXPECTED failure). */\nexport function resetContainedEditorErrors(): void {\n  recorded.length = 0;\n}\n\n/**\n * Assert that no editor error was contained (rendered as an error card)\n * since the last reset/call. Drains the record either way so one leaked\n * error doesn't fail every later test in the file.\n */\nexport function expectNoEditorErrors(): void {\n  if (recorded.length === 0) return;\n  const summary = recorded\n    .map((e) => (isEditorError(e) ? `${e.code}: ${e.message}` : `${e.name}: ${e.message}`))\n    .join('\\n  - ');\n  recorded.length = 0;\n  throw new Error(\n    `expectNoEditorErrors: ${summary.includes('\\n') ? 'errors were' : 'an error was'} contained by ` +\n      `<Editor.Root>'s boundary during this test:\\n  - ${summary}\\n` +\n      'A contained error renders an error card in prod — this composition is broken even if the test rendered \"successfully\".',\n  );\n}\n"],"names":["recorded","recordContainedEditorError","error","isDevOrTest","getContainedEditorErrors","resetContainedEditorErrors","expectNoEditorErrors","summary","e","isEditorError"],"mappings":";AAqBA,MAAMA,IAAoB,CAAA;AAGnB,SAASC,EAA2BC,GAAoB;AAC7D,EAAIC,EAAA,KAAeH,EAAS,KAAKE,CAAK;AACxC;AAGO,SAASE,IAA6C;AAC3D,SAAO,CAAC,GAAGJ,CAAQ;AACrB;AAGO,SAASK,IAAmC;AACjD,EAAAL,EAAS,SAAS;AACpB;AAOO,SAASM,IAA6B;AAC3C,MAAIN,EAAS,WAAW,EAAG;AAC3B,QAAMO,IAAUP,EACb,IAAI,CAACQ,MAAOC,EAAcD,CAAC,IAAI,GAAGA,EAAE,IAAI,KAAKA,EAAE,OAAO,KAAK,GAAGA,EAAE,IAAI,KAAKA,EAAE,OAAO,EAAG,EACrF,KAAK;AAAA,KAAQ;AAChB,QAAAR,EAAS,SAAS,GACZ,IAAI;AAAA,IACR,yBAAyBO,EAAQ,SAAS;AAAA,CAAI,IAAI,gBAAgB,cAAc;AAAA,MAC3BA,CAAO;AAAA;AAAA,EAAA;AAGhE;"}