@field/cascade 0.10.0 → 0.12.0

package/dist/cli/text-MB3EKR4H.js

@@ -0,0 +1,126 @@
+import {
+  colorToCss,
+  normalizeColor,
+  readPixelsFromCanvas,
+  surface,
+  writePixels
+} from "./chunk-WGKPJZDY.js";
+
+// packages/runtime/src/builtins/image/text.ts
+var FONT_FILE = /\.(otf|ttf|woff2?)$/i;
+var HOST_KEY = "__cascadeImageHost";
+var registered = /* @__PURE__ */ new Set();
+function fingerprint(bytes) {
+  let hash = 2166136261;
+  for (let index = 0; index < bytes.length; index += 1) {
+    hash ^= bytes[index];
+    hash = Math.imul(hash, 16777619);
+  }
+  return `${bytes.length}-${(hash >>> 0).toString(16)}`;
+}
+async function fontFamily(context, font) {
+  const path = font.trim();
+  if (!FONT_FILE.test(path)) return font;
+  let bytes;
+  try {
+    const assets = context.capabilities.assets;
+    if (!assets) throw new Error("no assets");
+    bytes = await assets.read({ path }, { signal: context.signal });
+  } catch {
+    return "sans-serif";
+  }
+  const family = `cascade-font-${fingerprint(bytes)}`;
+  const globals = globalThis;
+  const host = globals[HOST_KEY];
+  const fonts = host ? null : globals.fonts ?? globals.document?.fonts;
+  const key = `${host ? `headless:${host.renderer}` : "browser"}:${family}`;
+  if (registered.has(key)) return family;
+  if (host && typeof host.registerFont === "function") {
+    await host.registerFont(family, bytes, {});
+  } else if (typeof globals.FontFace === "function" && fonts) {
+    const face = new globals.FontFace(family, bytes.slice().buffer);
+    fonts.add(await face.load());
+  } else {
+    return "sans-serif";
+  }
+  registered.add(key);
+  return family;
+}
+async function executeText(context) {
+  const { props } = context;
+  const [width, height] = [props.resolution[0], props.resolution[1]];
+  const color = normalizeColor(props.color);
+  const background = normalizeColor(props.backgroundColor);
+  const [offsetX, offsetY] = props.offset;
+  const { fontSize, alignH, alignV, rotation, letterSpacing } = props;
+  const family = await fontFamily(context, props.font);
+  const { canvas, context: ctx } = surface(width, height);
+  if (background.a > 0) {
+    ctx.fillStyle = colorToCss(background);
+    ctx.fillRect(0, 0, width, height);
+  } else {
+    ctx.clearRect(0, 0, width, height);
+  }
+  ctx.save();
+  ctx.globalAlpha = props.opacity;
+  ctx.font = `${props.fontStyle} ${props.fontWeight} ${fontSize}px ${family}`;
+  ctx.fillStyle = colorToCss(color);
+  const lines = props.text.split("\n");
+  const lineHeightPx = fontSize * props.lineHeight;
+  const totalTextHeight = lines.length * lineHeightPx;
+  let anchorX;
+  let anchorY;
+  switch (alignH) {
+    case "left":
+      ctx.textAlign = "left";
+      anchorX = 0;
+      break;
+    case "right":
+      ctx.textAlign = "right";
+      anchorX = width;
+      break;
+    default:
+      ctx.textAlign = "center";
+      anchorX = width / 2;
+  }
+  switch (alignV) {
+    case "top":
+      anchorY = fontSize;
+      break;
+    case "bottom":
+      anchorY = height - totalTextHeight + fontSize;
+      break;
+    default:
+      anchorY = (height - totalTextHeight) / 2 + fontSize;
+  }
+  anchorX += offsetX;
+  anchorY += offsetY;
+  if (rotation !== 0) {
+    const pivotY = anchorY - fontSize / 2 + totalTextHeight / 2;
+    ctx.translate(anchorX, pivotY);
+    ctx.rotate(rotation * Math.PI / 180);
+    ctx.translate(-anchorX, -pivotY);
+  }
+  if (letterSpacing !== 0) {
+    ctx.textAlign = "left";
+    lines.forEach((line, index) => {
+      const y = anchorY + index * lineHeightPx;
+      let lineWidth = 0;
+      for (const char of line) lineWidth += ctx.measureText(char).width + letterSpacing;
+      lineWidth -= letterSpacing;
+      let x = alignH === "left" ? anchorX : alignH === "right" ? anchorX - lineWidth : anchorX - lineWidth / 2;
+      for (const char of line) {
+        ctx.fillText(char, x, y);
+        x += ctx.measureText(char).width + letterSpacing;
+      }
+    });
+  } else {
+    lines.forEach((line, index) => ctx.fillText(line, anchorX, anchorY + index * lineHeightPx));
+  }
+  ctx.restore();
+  context.outputs.image.set(await writePixels(context, readPixelsFromCanvas(canvas)));
+}
+export {
+  executeText
+};
+//# sourceMappingURL=text-MB3EKR4H.js.map

package/dist/cli/verbs-PI2JH5FI.js

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

package/dist/cli/webBuild-WPPMGGW7.js

@@ -0,0 +1,44 @@
+import {
+  buildPlayer,
+  canonicalFuturePath,
+  exists,
+  inside,
+  installRoot,
+  playerFile,
+  staticRuntimePlugin
+} from "./chunk-OM6BEME6.js";
+import "./chunk-MP653A5O.js";
+import "./chunk-MI5JLQYA.js";
+import "./chunk-GRIN2DDP.js";
+import "./chunk-X4WKAOQP.js";
+import "./chunk-DEQSEFFH.js";
+import "./chunk-RXDIMXN5.js";
+import "./chunk-QQPA2ZHH.js";
+import "./chunk-KH4MUBKF.js";
+import "./chunk-HSNOBIVT.js";
+import "./chunk-L6B6FUQP.js";
+import "./chunk-HFHWYL55.js";
+import "./chunk-KBGUO27Q.js";
+import "./chunk-ICH7N5PN.js";
+import "./chunk-CO22XHNG.js";
+import "./chunk-LTXWBXOM.js";
+import "./chunk-BZ63XQ3I.js";
+import "./chunk-YH637PDL.js";
+import "./chunk-X566FWBV.js";
+import "./chunk-WD62JIP6.js";
+import "./chunk-5ORUQ6ES.js";
+import "./chunk-2JEU3MGB.js";
+import "./chunk-NJFMDXHR.js";
+import "./chunk-J7VK7MNF.js";
+import "./chunk-FWMSGKEH.js";
+import "./chunk-JVOCK5W4.js";
+export {
+  buildPlayer,
+  canonicalFuturePath,
+  exists,
+  inside,
+  installRoot,
+  playerFile,
+  staticRuntimePlugin
+};
+//# sourceMappingURL=webBuild-WPPMGGW7.js.map

package/dist/contracts/capabilities.d.ts

@@ -1,4 +1,4 @@
-import type { AssetRef, ImageRef, JsonValue } from "./values.js";
+import type { AssetRef, ImagePixels, ImageRef, JsonValue } from "./values.js";
 export interface CascadeAbortSignal {
     readonly aborted: boolean;
     readonly reason?: unknown;
@@ -46,6 +46,23 @@ export interface AssetCapability {
         signal: CascadeAbortSignal;
     }): Promise<AssetRef>;
     resolveUrl?(ref: AssetRef | ImageRef): Promise<ResourceLease<string>>;
+    /**
+     * Store an intermediate image from its pixels. Optional; a host without it
+     * gets encoded bytes through `write`. The host chooses how: the headless
+     * host holds the pixels in memory and writes a fast lossless PNG behind
+     * (zlib level 1), or encodes that PNG at once when the run does not keep
+     * pixels. The returned path is content-addressed like `write`'s and is a
+     * whole file before anything reads it from disk. Finals are not encoded
+     * here: a run's saved outputs are encoded at full compression when copied.
+     */
+    keepImage?(pixels: ImagePixels, metadata: {
+        suggestedName?: string;
+    }, options: {
+        signal: CascadeAbortSignal;
+    }): Promise<AssetRef>;
+    /** The pixels behind a stored image while the host still holds them in
+     *  memory, so a reader skips the read and the decode. */
+    imagePixels?(ref: AssetRef | ImageRef): ImagePixels | undefined;
 }
 export interface MediaCapability {
     decodeImage(ref: ImageRef | AssetRef, options: {

package/dist/contracts/color.d.ts

@@ -57,6 +57,14 @@ export declare const Color: Readonly<{
     alpha(color: Color): number;
     /** The same colour at full alpha. */
     opaque(color: Color): Color;
+    /**
+     * A colour saved in an older shape, as the one colour: `{ r, g, b, a? }`
+     * (the class-based image nodes stored that until 2026-11-07) or three
+     * components, with alpha 1. Components above 1 are read as 0–255, the way
+     * those nodes read them. Anything else comes back unchanged, so a reader can
+     * apply this to every stored `color` value and validate the result.
+     */
+    upgrade(value: unknown): unknown;
     /**
      * Four unit components from anything indexable, clamping and defaulting a
      * missing alpha to 1. The reader for a `Cd` attribute's flat array, and the

package/dist/contracts/color.js

@@ -70,6 +70,29 @@ export const Color = Object.freeze({
     opaque(color) {
         return [clamp(color[0]), clamp(color[1]), clamp(color[2]), 1];
     },
+    /**
+     * A colour saved in an older shape, as the one colour: `{ r, g, b, a? }`
+     * (the class-based image nodes stored that until 2026-11-07) or three
+     * components, with alpha 1. Components above 1 are read as 0–255, the way
+     * those nodes read them. Anything else comes back unchanged, so a reader can
+     * apply this to every stored `color` value and validate the result.
+     */
+    upgrade(value) {
+        const legacy = value !== null && typeof value === "object" && !Array.isArray(value) && "r" in value && "g" in value && "b" in value
+            ? value
+            : Array.isArray(value) && value.length === 3
+                ? { r: value[0], g: value[1], b: value[2] }
+                : null;
+        if (!legacy)
+            return value;
+        const parts = [legacy.r, legacy.g, legacy.b, legacy.a ?? 1];
+        if (!parts.every((part) => typeof part === "number" && Number.isFinite(part)))
+            return value;
+        const numbers = parts;
+        const unit = numbers.slice(0, 3).every((part) => part <= 1);
+        const read = (part) => (unit ? part : part / 255);
+        return [read(numbers[0]), read(numbers[1]), read(numbers[2]), legacy.a === undefined ? 1 : read(numbers[3])];
+    },
     /**
      * Four unit components from anything indexable, clamping and defaulting a
      * missing alpha to 1. The reader for a `Cd` attribute's flat array, and the

package/dist/contracts/definition.d.ts

@@ -190,6 +190,16 @@ export interface NodeDefinitionForEnvironment<E extends RuntimeEnvironment> {
      */
     readonly container?: "subnet" | "feedback";
     readonly capabilities?: readonly CapabilityForEnvironment<E>[];
+    /**
+     * GPU limits this node cannot run without, by WebGPU name, for a node that
+     * declares `gpu`: `{ maxStorageBufferBindingSize: 512 * 2 ** 20 }`. The host
+     * already asks for everything the adapter allows; this makes a GPU that
+     * allows less fail before the cook, naming the limit, instead of with a
+     * validation error from inside it. `max*` limits are minimums to reach,
+     * `min*Alignment` ones maximums. Read `context.capabilities.gpu.limits` for
+     * what the device actually gives.
+     */
+    readonly gpuLimits?: Readonly<Record<string, number>>;
     /**
      * `live` marks a node that reads data from outside the graph — an archive,
      * a CLI, a cache, body data, the filesystem or a network. `cascade export`

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";

package/dist/contracts/schema.d.ts

@@ -1,6 +1,6 @@
 export declare const nodeDefinitionSchema: {
-    readonly allOf: readonly [Readonly<Record<string, unknown>>, Readonly<Record<string, unknown>>, Readonly<Record<string, unknown>>];
     readonly $schema: "https://json-schema.org/draft/2020-12/schema";
     readonly $id: "https://cascade.dev/schema/node-definition-v1.json";
+    readonly allOf: readonly [Readonly<Record<string, unknown>>, Readonly<Record<string, unknown>>, Readonly<Record<string, unknown>>];
 };
 //# sourceMappingURL=schema.d.ts.map

package/dist/contracts/schema.js

@@ -88,6 +88,7 @@ export const nodeDefinitionSchema = {
             items: { type: "string" },
             uniqueItems: true,
         },
+        gpuLimits: record({ type: "number", minimum: 0 }),
         label: description,
         description,
         icon: description,

package/dist/contracts/validate.js

@@ -19,7 +19,7 @@ export const CAPABILITIES_BY_ENVIRONMENT = {
 };
 const ALLOWED = CAPABILITIES_BY_ENVIRONMENT;
 const fields = (names) => new Set(names.split(" "));
-const TOP_FIELDS = fields("apiVersion runsOn container capabilities source label description icon inputs outputs props");
+const TOP_FIELDS = fields("apiVersion runsOn container capabilities gpuLimits source label description icon inputs outputs props");
 const DATA_FIELDS = fields("kind type default description variadic min max step accept control options schema fields");
 const OUTPUT_FIELDS = fields("kind type description schema fields");
 const PROP_FIELDS = fields("type default label description min max step accept control options expression action");
@@ -111,6 +111,16 @@ export function validateNodeDefinition(value) {
             add("duplicate-capability", `${String(capability)} is duplicated`, path);
         seen.add(capability);
     }
+    if (value.gpuLimits !== undefined) {
+        if (!seen.has("gpu"))
+            add("gpu-limits-without-gpu", "gpuLimits needs the gpu capability", "gpuLimits");
+        if (!isRecord(value.gpuLimits))
+            add("invalid-gpu-limits", "gpuLimits must be an object of WebGPU limit names to numbers", "gpuLimits");
+        else
+            for (const [name, limit] of Object.entries(value.gpuLimits))
+                if (typeof limit !== "number" || !Number.isFinite(limit) || limit < 0)
+                    add("invalid-gpu-limits", `gpuLimits.${name} must be a non-negative number`, `gpuLimits.${name}`);
+    }
     // Two namespaces, not one. An output is addressed in the other direction from
     // an input, so `geometry` in and `geometry` out is not ambiguous anywhere: the
     // document format names the two endpoints of a connection separately, the

package/dist/contracts/values.d.ts

@@ -51,6 +51,18 @@ export type Mat4 = readonly [
     number,
     number
 ];
+/**
+ * The value on an `image` port: a path naming stored pixels, plus what they
+ * are. The port carries the reference, never the pixels, so a value stays
+ * small to snapshot, hash, trace and send to a Python stage.
+ *
+ * The path is always readable as a file by whoever needs a file. A host may
+ * still hold the pixels in memory and write the file behind (see
+ * {@link ImagePixels} and `AssetCapability.keepImage`): a reader in the same
+ * process gets the pixels without a decode, and the host makes the file whole
+ * before anything reads it from disk (a final copy, a Python stage, the end of
+ * a run).
+ */
 export interface ImageRef {
     readonly path: string;
     readonly size: Vec2i;
@@ -58,6 +70,18 @@ export interface ImageRef {
     readonly depth: "u8" | "u16" | "f16" | "f32";
     readonly space: "srgb" | "linear";
 }
+/**
+ * An image's pixels in memory: 8-bit RGBA, sRGB, unpremultiplied, row-major
+ * with the top row first. This is the layout of `ImageData` and of a PNG's
+ * decoded rows, so handing pixels on in memory and handing them on through a
+ * PNG give the next node the same numbers.
+ */
+export interface ImagePixels {
+    readonly width: number;
+    readonly height: number;
+    /** `width * height * 4` bytes. Owned by the host once kept: never mutate. */
+    readonly data: Uint8ClampedArray;
+}
 declare const textureHandleBrand: unique symbol;
 export interface TextureHandle {
     readonly [textureHandleBrand]: true;