@field/cascade 0.10.0 → 0.11.0

package/dist/cli/runtime/image.ts

@@ -0,0 +1,277 @@
+/**
+ * `cascade/image` — the one image API a node body uses, in every host.
+ *
+ * A node that draws used to have two honest choices and one dishonest one.
+ * `new OffscreenCanvas` worked in Studio and under `cascade run` (the CLI
+ * installs Skia's canvas as that global), but the bytes in and out went
+ * through `cascade/io`'s project paths, and fonts had no portable door at all.
+ * So the nodes that needed fonts or files reached for `@napi-rs/canvas` and
+ * `node:fs` directly, declared `runsOn: 'server'`, and could never be exported
+ * as a browser editor — the commons plotter-social job was blocked on exactly
+ * that ("Cascade has no browser image contract").
+ *
+ * The contract, in full:
+ *
+ *  - **Surface.** `createCanvas(w, h)` is an `OffscreenCanvas`: the browser's
+ *    own in a page or a worker, Skia's (`@napi-rs/canvas`, installed by the
+ *    headless host) under `cascade run`/`render`/MCP. `context2d(canvas)` asks
+ *    for a CPU-backed 2D context (`willReadFrequently`), which is what keeps
+ *    Chrome on the same software Skia rasteriser the headless host uses, and
+ *    is the right hint anyway for nodes that read pixels back.
+ *  - **Pixels in.** `readImage(context, ref)` reads an `ImageRef`, `AssetRef`
+ *    or project path through the node's declared `assets` capability and
+ *    decodes it with `decodeImage` (`createImageBitmap` in both hosts).
+ *  - **Pixels out.** `writeImage(context, canvas, name)` encodes PNG through
+ *    `encodeImage` and stores it with `assets.write`, returning the `ImageRef`
+ *    to set on an `image` output. The host decides where it lands
+ *    (`.cascade-cache/<name>.<hash>.png` headless, an in-memory generated
+ *    asset in an exported editor), so a node never names a path.
+ *  - **Fonts.** `registerFont(family, bytes)` makes a face drawable by
+ *    `ctx.font` in this host: `FontFace` added to the page's or worker's font
+ *    set in a browser, Skia's `GlobalFonts` headless. Bytes come from the same
+ *    `assets` capability, so a font is a project file like any other.
+ *  - **Refusal, not fallback.** No canvas in this host, or no `assets`
+ *    capability declared, is an error with one sentence saying which, never a
+ *    silent blank image.
+ *
+ * A node using it declares `runsOn: 'portable'` and `capabilities: ['assets']`
+ * and imports nothing host-specific (`node:*`, `@napi-rs/canvas`, `document`).
+ * Then the same body cooks in Studio, in `cascade run`, and in an exported
+ * editor's worker.
+ *
+ * The headless host installs its font door under a global key, like
+ * `cascade/io`'s bridge, because the node's copy of this module and the CLI's
+ * copy are not always the same module instance.
+ */
+
+/** An image port value. Mirrors Cascade's core `ImageRef`. */
+export interface ImageRef {
+  path: string;
+  size: [number, number];
+  channels: 'r' | 'a' | 'rg' | 'rgb' | 'rgba';
+  depth: 'u8' | 'u16' | 'f16' | 'f32';
+  space: 'srgb' | 'linear';
+}
+
+/** Anything naming stored bytes: an `ImageRef`, an `AssetRef`, or a project path. */
+export type ImageSourceRef = string | { readonly path: string };
+
+/** The part of the `assets` capability these helpers use. */
+export interface ImageAssets {
+  read(ref: { path: string }, options: { signal: unknown }): Promise<Uint8Array>;
+  write(
+    data: Uint8Array,
+    metadata: { mediaType?: string; suggestedName?: string },
+    options: { signal: unknown },
+  ): Promise<{ path: string; mediaType?: string }>;
+}
+
+/**
+ * The slice of a definition-v1 `NodeExecutionContext` these helpers need, so
+ * a node passes its own `context`. Typed loosely on purpose: a node that did
+ * not declare `assets` still type-checks here and gets a sentence at run time
+ * naming the missing declaration rather than a type error about generics.
+ */
+export interface ImageNodeContext {
+  readonly capabilities: object;
+  readonly signal?: unknown;
+}
+
+export type ImageType = 'image/png' | 'image/webp' | 'image/jpeg';
+
+/** What a host gives `registerFont`. A browser realm needs none. */
+export interface ImageHost {
+  /** For a `--verbose` line and for errors. */
+  readonly renderer: string;
+  registerFont(family: string, bytes: Uint8Array, descriptors: FontDescriptors): void | Promise<void>;
+}
+
+export interface FontDescriptors {
+  /** CSS weight, `'400'`, `'bold'`. Headless reads the weight from the file. */
+  weight?: string;
+  /** `'normal'` or `'italic'`. Headless reads the style from the file. */
+  style?: string;
+}
+
+const HOST_KEY = '__cascadeImageHost';
+
+const NO_CANVAS =
+  'cascade/image: this host has no canvas. In a browser this needs OffscreenCanvas; headless, Cascade installs ' +
+  '@napi-rs/canvas before a run (install it with "npm install @napi-rs/canvas" if it is missing).';
+
+/** Install the headless host's font door. Returns the disposer. */
+export function installImageHost(host: ImageHost | null): () => void {
+  const globals = globalThis as Record<string, unknown>;
+  const previous = globals[HOST_KEY];
+  globals[HOST_KEY] = host ?? undefined;
+  return () => {
+    globals[HOST_KEY] = previous;
+  };
+}
+
+function installedHost(): ImageHost | null {
+  const host = (globalThis as Record<string, unknown>)[HOST_KEY] as ImageHost | undefined;
+  return host && typeof host.registerFont === 'function' ? host : null;
+}
+
+type CanvasConstructor = new (width: number, height: number) => OffscreenCanvas;
+
+function canvasConstructor(): CanvasConstructor | undefined {
+  return (globalThis as { OffscreenCanvas?: CanvasConstructor }).OffscreenCanvas;
+}
+
+/** Whether this host can draw. Never throws. */
+export function canvasAvailable(): boolean {
+  return typeof canvasConstructor() === 'function';
+}
+
+/** A drawing surface of whole pixels, at least 1x1. */
+export function createCanvas(width: number, height: number): OffscreenCanvas {
+  const Canvas = canvasConstructor();
+  if (!Canvas) throw new Error(NO_CANVAS);
+  return new Canvas(Math.max(1, Math.round(width)), Math.max(1, Math.round(height)));
+}
+
+/**
+ * The canvas's 2D context, CPU-backed. `willReadFrequently` keeps a browser
+ * off the GPU rasteriser, so a node draws with the same software Skia in Chrome
+ * as headless, and `getImageData` does not stall on a readback.
+ */
+export function context2d(canvas: OffscreenCanvas): OffscreenCanvasRenderingContext2D {
+  const context = canvas.getContext('2d', { willReadFrequently: true }) as OffscreenCanvasRenderingContext2D | null;
+  if (!context) throw new Error('cascade/image: the canvas has no 2D context');
+  return context;
+}
+
+/** `createCanvas` and `context2d` in one: `const { canvas, context } = surface(w, h)`. */
+export function surface(width: number, height: number): {
+  canvas: OffscreenCanvas;
+  context: OffscreenCanvasRenderingContext2D;
+} {
+  const canvas = createCanvas(width, height);
+  return { canvas, context: context2d(canvas) };
+}
+
+/** Encoded bytes (PNG, JPEG, WebP) to something `drawImage` accepts. */
+export async function decodeImage(bytes: Uint8Array | ArrayBuffer | Blob): Promise<ImageBitmap> {
+  const create = (globalThis as { createImageBitmap?: (source: Blob) => Promise<ImageBitmap> }).createImageBitmap;
+  if (typeof create !== 'function') throw new Error(NO_CANVAS);
+  const blob = bytes instanceof Blob ? bytes : new Blob([bytes as BlobPart]);
+  const image = await create(blob);
+  if (!image?.width || !image?.height) throw new Error('cascade/image: could not decode the image data');
+  return image;
+}
+
+/** A canvas's pixels as encoded bytes, PNG unless asked otherwise. */
+export async function encodeImage(
+  canvas: OffscreenCanvas,
+  options: { type?: ImageType; quality?: number } = {},
+): Promise<Uint8Array> {
+  const type = options.type ?? 'image/png';
+  if (typeof canvas.convertToBlob !== 'function') throw new Error('cascade/image: this canvas cannot encode (no convertToBlob)');
+  const blob = await canvas.convertToBlob({ type, ...(options.quality === undefined ? {} : { quality: options.quality }) });
+  return new Uint8Array(await blob.arrayBuffer());
+}
+
+// One record per realm, so a font registered once is not added again on every
+// cook. Keyed by family and content: new bytes under a family name register.
+// The headless realm is keyed by its renderer name rather than the host
+// object, because a long-lived process (MCP) installs a fresh host per run
+// while Skia's font registry lives for the whole process.
+const registered = new Map<unknown, Set<string>>();
+
+function fingerprint(bytes: Uint8Array): string {
+  let hash = 0x811c9dc5;
+  for (let index = 0; index < bytes.length; index += 1) {
+    hash ^= bytes[index]!;
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return `${bytes.length}:${(hash >>> 0).toString(16)}`;
+}
+
+interface BrowserFontSet { add(face: unknown): unknown }
+type FontFaceConstructor = new (family: string, source: ArrayBuffer | Uint8Array, descriptors?: FontDescriptors) => {
+  load(): Promise<unknown>;
+};
+
+/**
+ * Make `family` drawable by `ctx.font` here. Idempotent per family and bytes.
+ * A browser realm (page or worker) uses `FontFace`; the headless host
+ * registers with Skia. A host with neither refuses.
+ */
+export async function registerFont(
+  family: string,
+  bytes: Uint8Array | ArrayBuffer,
+  descriptors: FontDescriptors = {},
+): Promise<void> {
+  if (!family.trim()) throw new Error('cascade/image: registerFont needs a family name');
+  const data = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+  if (!data.byteLength) throw new Error(`cascade/image: the font for ${family} is empty`);
+  const host = installedHost();
+  const globals = globalThis as { FontFace?: FontFaceConstructor; fonts?: BrowserFontSet; document?: { fonts?: BrowserFontSet } };
+  const fonts = host ? null : globals.fonts ?? globals.document?.fonts;
+  const realm: unknown = host ? `headless:${host.renderer}` : fonts ?? globalThis;
+  const key = `${family}\u0000${descriptors.weight ?? ''}\u0000${descriptors.style ?? ''}\u0000${fingerprint(data)}`;
+  const seen = registered.get(realm) ?? new Set<string>();
+  if (seen.has(key)) return;
+  if (host) {
+    await host.registerFont(family, data, descriptors);
+  } else if (typeof globals.FontFace === 'function' && fonts) {
+    // A copy: FontFace may detach or keep the buffer it is given.
+    const face = new globals.FontFace(family, data.slice().buffer, descriptors);
+    fonts.add(await face.load());
+  } else {
+    throw new Error('cascade/image: this host cannot register fonts (no FontFace and no headless canvas host)');
+  }
+  seen.add(key);
+  registered.set(realm, seen);
+}
+
+function assetsOf(context: ImageNodeContext): ImageAssets {
+  const assets = (context.capabilities as { assets?: ImageAssets }).assets;
+  if (!assets || typeof assets.read !== 'function' || typeof assets.write !== 'function') {
+    throw new Error("cascade/image: this node reads or writes images, so its definition must declare capabilities: ['assets']");
+  }
+  return assets;
+}
+
+function refOf(ref: ImageSourceRef): { path: string } {
+  const path = typeof ref === 'string' ? ref : ref?.path;
+  if (typeof path !== 'string' || !path) throw new Error('cascade/image: no image to read (an empty path or an unset image input)');
+  return { path };
+}
+
+const NEVER = { aborted: false, addEventListener() {}, removeEventListener() {} };
+
+/** A stored file's bytes through the node's `assets` capability: an image, a font, anything. */
+export async function readBytes(context: ImageNodeContext, ref: ImageSourceRef): Promise<Uint8Array> {
+  return assetsOf(context).read(refOf(ref), { signal: context.signal ?? NEVER });
+}
+
+/** Read and decode an image input, an asset, or a project file. */
+export async function readImage(context: ImageNodeContext, ref: ImageSourceRef): Promise<ImageBitmap> {
+  return decodeImage(await readBytes(context, ref));
+}
+
+/**
+ * Encode a canvas and store it; set the result on an `image` output. `name`
+ * is a suggestion (`context.nodeId + '.png'` keeps instances apart); the host
+ * picks the stored path.
+ */
+export async function writeImage(
+  context: ImageNodeContext,
+  canvas: OffscreenCanvas,
+  name: string,
+  options: { type?: ImageType; quality?: number; space?: 'srgb' | 'linear' } = {},
+): Promise<ImageRef> {
+  const type = options.type ?? 'image/png';
+  const bytes = await encodeImage(canvas, { type, ...(options.quality === undefined ? {} : { quality: options.quality }) });
+  const stored = await assetsOf(context).write(bytes, { mediaType: type, suggestedName: name }, { signal: context.signal ?? NEVER });
+  return {
+    path: stored.path,
+    size: [canvas.width, canvas.height],
+    channels: 'rgba',
+    depth: 'u8',
+    space: options.space ?? 'srgb',
+  };
+}

package/dist/cli/runtime/stage.ts

@@ -115,7 +115,10 @@ async function overHttp<T>(stage: string, args: Record<string, unknown>, signal?
   const postStage = async () => fetch('/api/exec', {
     method: 'POST',
     headers: { 'Content-Type': 'application/json', 'X-Cascade-Exec-Capability': await capability() },
-    body: JSON.stringify({ stage, args }),
+    // `cook`: a node's cook is a pure function of its inputs, so the server's
+    // default stage cache may serve it (see StageCachePolicy). A panel posts
+    // through its own api.runStage, without this, and is never cached unasked.
+    body: JSON.stringify({ stage, args, caller: 'cook' }),
     signal,
   });
 

package/dist/cli/stageRunner-KUNIMQKJ.js

@@ -0,0 +1,10 @@
+import {
+  readStageConfig,
+  runProjectStage
+} from "./chunk-VVGSLVSF.js";
+import "./chunk-WD62JIP6.js";
+export {
+  readStageConfig,
+  runProjectStage
+};
+//# sourceMappingURL=stageRunner-KUNIMQKJ.js.map

package/dist/cli/verbs-RCE3K4VQ.js

@@ -0,0 +1,19 @@
+import {
+  VERBS,
+  graphCommandsHelp,
+  graphOptions,
+  isGraphCommand,
+  mainHelp,
+  mcpTools,
+  verbFor
+} from "./chunk-POMMNKZZ.js";
+export {
+  VERBS,
+  graphCommandsHelp,
+  graphOptions,
+  isGraphCommand,
+  mainHelp,
+  mcpTools,
+  verbFor
+};
+//# sourceMappingURL=verbs-RCE3K4VQ.js.map

package/dist/cli/webBuild-GT4PZT5D.js

@@ -0,0 +1,37 @@
+import {
+  buildPlayer,
+  canonicalFuturePath,
+  exists,
+  inside,
+  installRoot,
+  playerFile,
+  staticRuntimePlugin
+} from "./chunk-3JTJHF7V.js";
+import "./chunk-EUIAC3U3.js";
+import "./chunk-36P5K3SD.js";
+import "./chunk-D6BUOHUG.js";
+import "./chunk-RXDIMXN5.js";
+import "./chunk-QQPA2ZHH.js";
+import "./chunk-KH4MUBKF.js";
+import "./chunk-35D343DC.js";
+import "./chunk-DEQSEFFH.js";
+import "./chunk-HSNOBIVT.js";
+import "./chunk-ICH7N5PN.js";
+import "./chunk-GFS6W3C5.js";
+import "./chunk-HFHWYL55.js";
+import "./chunk-CO22XHNG.js";
+import "./chunk-RQZ4SX5R.js";
+import "./chunk-A4OAMOZH.js";
+import "./chunk-J7VK7MNF.js";
+import "./chunk-XWDSKG7N.js";
+import "./chunk-BIJO5OFS.js";
+export {
+  buildPlayer,
+  canonicalFuturePath,
+  exists,
+  inside,
+  installRoot,
+  playerFile,
+  staticRuntimePlugin
+};
+//# sourceMappingURL=webBuild-GT4PZT5D.js.map

package/dist/contracts/documentFormat.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Compact-array JSON formatting for .cascade files — ported unchanged
+ * from the original routes/projects.ts (real design work: keeps small
+ * arrays like [x, y] coordinates and [from, to] connections on one line
+ * instead of exploding them across many, so a saved graph stays readable
+ * and diffable in git — which matters now that every save is a commit.
+ *
+ * The one copy: Studio's save and download (src/utils/fileSystem.ts), the
+ * server's graph route and the CLI's graph edits all write through it, so a
+ * file saved by any of them diffs cleanly against the others.
+ */
+/**
+ * Format JSON string with compact arrays (keeps small arrays on single lines)
+ * This function finds multi-line arrays with 2-4 elements and compacts them
+ * Handles both numeric arrays and arrays containing small arrays (like connections)
+ */
+export declare function formatCompactJSON(jsonString: string, indent?: number): string;
+//# sourceMappingURL=documentFormat.d.ts.map

package/dist/contracts/documentFormat.js

@@ -0,0 +1,195 @@
+/**
+ * Compact-array JSON formatting for .cascade files — ported unchanged
+ * from the original routes/projects.ts (real design work: keeps small
+ * arrays like [x, y] coordinates and [from, to] connections on one line
+ * instead of exploding them across many, so a saved graph stays readable
+ * and diffable in git — which matters now that every save is a commit.
+ *
+ * The one copy: Studio's save and download (src/utils/fileSystem.ts), the
+ * server's graph route and the CLI's graph edits all write through it, so a
+ * file saved by any of them diffs cleanly against the others.
+ */
+/**
+ * Format JSON string with compact arrays (keeps small arrays on single lines)
+ * This function finds multi-line arrays with 2-4 elements and compacts them
+ * Handles both numeric arrays and arrays containing small arrays (like connections)
+ */
+export function formatCompactJSON(jsonString, indent = 2) {
+    // Process multiple passes to handle nested arrays
+    let result = jsonString;
+    let previousResult = '';
+    // Keep processing until no more changes (handles nested arrays)
+    while (result !== previousResult) {
+        previousResult = result;
+        result = formatCompactJSONPass(result, indent);
+    }
+    return result;
+}
+/**
+ * Single pass of compact formatting
+ */
+function formatCompactJSONPass(jsonString, indent = 2) {
+    const lines = jsonString.split('\n');
+    const result = [];
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        const trimmed = line.trim();
+        // Check if this line starts an array (pattern: "key": [ or just [)
+        if (trimmed.endsWith('[') && (trimmed.includes(':') || trimmed === '[')) {
+            // Collect lines until we find the closing bracket
+            let arrayLines = [line];
+            let bracketDepth = 1;
+            let j = i + 1;
+            while (j < lines.length && bracketDepth > 0) {
+                const currentLine = lines[j];
+                arrayLines.push(currentLine);
+                // Count bracket depth
+                for (const char of currentLine) {
+                    if (char === '[')
+                        bracketDepth++;
+                    if (char === ']')
+                        bracketDepth--;
+                }
+                j++;
+            }
+            // Extract array content (lines between opening and closing brackets)
+            // Handle nested arrays by extracting complete array elements
+            const arrayContent = [];
+            let k = 1;
+            while (k < arrayLines.length - 1) {
+                const currentLine = arrayLines[k].trim();
+                // Check if this line starts a nested array
+                if (currentLine.endsWith('[') || (currentLine.startsWith('[') && !currentLine.endsWith(']'))) {
+                    // Extract the complete nested array
+                    let nestedArrayLines = [arrayLines[k]];
+                    let nestedDepth = 1;
+                    let m = k + 1;
+                    while (m < arrayLines.length - 1 && nestedDepth > 0) {
+                        nestedArrayLines.push(arrayLines[m]);
+                        for (const char of arrayLines[m]) {
+                            if (char === '[')
+                                nestedDepth++;
+                            if (char === ']')
+                                nestedDepth--;
+                        }
+                        m++;
+                    }
+                    // Join nested array lines into a single compact representation
+                    const nestedContent = [];
+                    for (let n = 1; n < nestedArrayLines.length - 1; n++) {
+                        const nestedLine = nestedArrayLines[n].trim().replace(/,$/, '').trim();
+                        if (nestedLine) {
+                            nestedContent.push(nestedLine);
+                        }
+                    }
+                    // Create compact nested array string
+                    const nestedArray = '[' + nestedContent.map(c => c.trim()).join(', ') + ']';
+                    arrayContent.push(nestedArray);
+                    k = m;
+                }
+                else {
+                    // Simple element
+                    const content = currentLine.replace(/,$/, '').trim();
+                    if (content) {
+                        arrayContent.push(content);
+                    }
+                    k++;
+                }
+            }
+            // Check if it's a small numeric array (2-4 elements)
+            const isSmallNumericArray = arrayContent.length >= 2 &&
+                arrayContent.length <= 4 &&
+                arrayContent.every(item => {
+                    const trimmed = item.trim();
+                    return /^-?\d+(\.\d+)?([eE][+-]?\d+)?$/.test(trimmed);
+                });
+            // Check if it's an array containing small arrays (like connections: [[a, b], [c, d]])
+            // Look for patterns where each element is a small array (2-4 elements)
+            // This handles both already-compacted arrays and multi-line nested arrays
+            let isArrayOfSmallArrays = false;
+            if (arrayContent.length >= 2 && arrayContent.length <= 20) { // Reasonable limit for connections
+                // Check if elements are arrays (either compact or multi-line)
+                const allAreArrays = arrayContent.every(item => {
+                    const trimmed = item.trim();
+                    // Already compact array like [a, b] or ["a", 0]
+                    if (trimmed.startsWith('[') && trimmed.endsWith(']')) {
+                        const inner = trimmed.slice(1, -1).trim();
+                        const parts = inner.split(',').map(p => p.trim()).filter(p => p);
+                        return parts.length >= 2 && parts.length <= 4;
+                    }
+                    // Multi-line array - check if this line starts an array
+                    if (trimmed.endsWith('[')) {
+                        return true; // This will be handled in a later pass
+                    }
+                    return false;
+                });
+                if (allAreArrays) {
+                    // Check if inner arrays are small (2-4 elements each)
+                    // For multi-line arrays, we'll need to extract their content
+                    let allSmall = true;
+                    for (const item of arrayContent) {
+                        const trimmed = item.trim();
+                        if (trimmed.startsWith('[') && trimmed.endsWith(']')) {
+                            // Already compact - check size
+                            const inner = trimmed.slice(1, -1).trim();
+                            const parts = inner.split(',').map(p => p.trim()).filter(p => p);
+                            if (parts.length < 2 || parts.length > 4) {
+                                allSmall = false;
+                                break;
+                            }
+                        }
+                        else if (trimmed.endsWith('[')) {
+                            // Multi-line array - will be compacted in next pass, assume it's small for now
+                            // We'll handle this in the multi-pass approach
+                        }
+                        else {
+                            allSmall = false;
+                            break;
+                        }
+                    }
+                    isArrayOfSmallArrays = allSmall;
+                }
+            }
+            if (isSmallNumericArray || isArrayOfSmallArrays) {
+                // Compact format: put entire array on one line
+                const indentLevel = (line.match(/^(\s*)/)?.[1] || '').length;
+                // Extract the key part (everything before the opening bracket)
+                const keyMatch = trimmed.match(/^(.+?)\s*\[\s*$/);
+                const keyPart = keyMatch ? keyMatch[1] : '';
+                // Check if the closing bracket line has a comma (last line in arrayLines)
+                const closingLine = arrayLines[arrayLines.length - 1];
+                const hasComma = closingLine.trim().endsWith(',');
+                // Format array content
+                let formattedContent;
+                if (isArrayOfSmallArrays) {
+                    // For arrays of arrays, each element should be compact
+                    // If an element is a multi-line array (ends with [), we can't compact it yet
+                    // Otherwise, use the already-compact form
+                    formattedContent = arrayContent.map(c => {
+                        const trimmed = c.trim();
+                        // If it's already compact, use it as-is
+                        if (trimmed.startsWith('[') && trimmed.endsWith(']')) {
+                            return trimmed;
+                        }
+                        // If it's a multi-line array start, we'll need another pass
+                        // For now, return as-is (will be handled in next pass)
+                        return trimmed;
+                    }).join(', ');
+                }
+                else {
+                    // Simple numeric array
+                    formattedContent = arrayContent.map(c => c.trim()).join(', ');
+                }
+                const compactArray = keyPart + ' [' + formattedContent + ']' + (hasComma ? ',' : '');
+                result.push(' '.repeat(indentLevel) + compactArray);
+                i = j; // Skip the processed lines
+                continue;
+            }
+        }
+        result.push(line);
+        i++;
+    }
+    return result.join('\n');
+}
+//# sourceMappingURL=documentFormat.js.map

package/dist/contracts/editor.d.ts

@@ -42,6 +42,13 @@ export interface EditorDeclaration {
     readonly panel?: EditorPanelDeclaration;
     /** The read-only stage view. On unless the author turns it off. */
     readonly inspect?: boolean;
+    /**
+     * Fonts the exported editor ships and loads, in the page and in the engine
+     * worker, so a panel or a canvas that names the family draws with it rather
+     * than the system fallback. Open-licensed only: each one states its licence
+     * (`OFL-1.1`), and a file under `licensed/` is refused like any other asset.
+     */
+    readonly fonts?: readonly EditorFont[];
     /**
      * Parameter ids a phone keeps in reach at the bottom sheet's lowest snap
      * point (the text, a Reroll). Defaults to the first text and seed parameters.
@@ -54,6 +61,16 @@ export interface EditorDeclaration {
      */
     readonly draft?: Readonly<Record<string, JsonValue>>;
 }
+export interface EditorFont {
+    /** The CSS family name the project's code uses (`DM Mono`). */
+    readonly family: string;
+    /** Project-relative font file: `.woff2`, `.woff`, `.ttf` or `.otf`. */
+    readonly file: string;
+    /** SIL Open Font License. Anything else is refused at export. */
+    readonly license: "OFL-1.1";
+    readonly weight?: string | number;
+    readonly style?: "normal" | "italic";
+}
 export type PublishedControl = "number" | "slider" | "int" | "bool" | "select" | "text" | "textarea" | "color" | "file" | "seed" | "vec2";
 export interface PublishedParameter {
     /** Scene key. Stable across renames of the node or the prop it targets. */

package/dist/contracts/index.d.ts

@@ -5,6 +5,7 @@ export * from "./capabilities.js";
 export * from "./color.js";
 export * from "./definition.js";
 export * from "./document.js";
+export * from "./documentFormat.js";
 export * from "./editor.js";
 export * from "./geometry.js";
 export * from "./particles.js";

package/dist/contracts/index.js

@@ -5,6 +5,7 @@ export * from "./capabilities.js";
 export * from "./color.js";
 export * from "./definition.js";
 export * from "./document.js";
+export * from "./documentFormat.js";
 export * from "./editor.js";
 export * from "./geometry.js";
 export * from "./particles.js";