@field/cascade 0.10.0 → 0.11.0

package/dist/image.d.ts

@@ -0,0 +1,141 @@
+/**
+ * `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;
+}
+/** Install the headless host's font door. Returns the disposer. */
+export declare function installImageHost(host: ImageHost | null): () => void;
+/** Whether this host can draw. Never throws. */
+export declare function canvasAvailable(): boolean;
+/** A drawing surface of whole pixels, at least 1x1. */
+export declare function createCanvas(width: number, height: number): OffscreenCanvas;
+/**
+ * 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 declare function context2d(canvas: OffscreenCanvas): OffscreenCanvasRenderingContext2D;
+/** `createCanvas` and `context2d` in one: `const { canvas, context } = surface(w, h)`. */
+export declare function surface(width: number, height: number): {
+    canvas: OffscreenCanvas;
+    context: OffscreenCanvasRenderingContext2D;
+};
+/** Encoded bytes (PNG, JPEG, WebP) to something `drawImage` accepts. */
+export declare function decodeImage(bytes: Uint8Array | ArrayBuffer | Blob): Promise<ImageBitmap>;
+/** A canvas's pixels as encoded bytes, PNG unless asked otherwise. */
+export declare function encodeImage(canvas: OffscreenCanvas, options?: {
+    type?: ImageType;
+    quality?: number;
+}): Promise<Uint8Array>;
+/**
+ * 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 declare function registerFont(family: string, bytes: Uint8Array | ArrayBuffer, descriptors?: FontDescriptors): Promise<void>;
+/** A stored file's bytes through the node's `assets` capability: an image, a font, anything. */
+export declare function readBytes(context: ImageNodeContext, ref: ImageSourceRef): Promise<Uint8Array>;
+/** Read and decode an image input, an asset, or a project file. */
+export declare function readImage(context: ImageNodeContext, ref: ImageSourceRef): Promise<ImageBitmap>;
+/**
+ * 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 declare function writeImage(context: ImageNodeContext, canvas: OffscreenCanvas, name: string, options?: {
+    type?: ImageType;
+    quality?: number;
+    space?: 'srgb' | 'linear';
+}): Promise<ImageRef>;

package/dist/image.js

@@ -0,0 +1,127 @@
+// server/src/runtime/image.ts
+var HOST_KEY = "__cascadeImageHost";
+var 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).';
+function installImageHost(host) {
+  const globals = globalThis;
+  const previous = globals[HOST_KEY];
+  globals[HOST_KEY] = host ?? void 0;
+  return () => {
+    globals[HOST_KEY] = previous;
+  };
+}
+function installedHost() {
+  const host = globalThis[HOST_KEY];
+  return host && typeof host.registerFont === "function" ? host : null;
+}
+function canvasConstructor() {
+  return globalThis.OffscreenCanvas;
+}
+function canvasAvailable() {
+  return typeof canvasConstructor() === "function";
+}
+function createCanvas(width, height) {
+  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)));
+}
+function context2d(canvas) {
+  const context = canvas.getContext("2d", { willReadFrequently: true });
+  if (!context) throw new Error("cascade/image: the canvas has no 2D context");
+  return context;
+}
+function surface(width, height) {
+  const canvas = createCanvas(width, height);
+  return { canvas, context: context2d(canvas) };
+}
+async function decodeImage(bytes) {
+  const create = globalThis.createImageBitmap;
+  if (typeof create !== "function") throw new Error(NO_CANVAS);
+  const blob = bytes instanceof Blob ? bytes : new Blob([bytes]);
+  const image = await create(blob);
+  if (!image?.width || !image?.height) throw new Error("cascade/image: could not decode the image data");
+  return image;
+}
+async function encodeImage(canvas, options = {}) {
+  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 === void 0 ? {} : { quality: options.quality } });
+  return new Uint8Array(await blob.arrayBuffer());
+}
+var registered = /* @__PURE__ */ new Map();
+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 registerFont(family, bytes, descriptors = {}) {
+  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;
+  const fonts = host ? null : globals.fonts ?? globals.document?.fonts;
+  const realm = host ? `headless:${host.renderer}` : fonts ?? globalThis;
+  const key = `${family}\0${descriptors.weight ?? ""}\0${descriptors.style ?? ""}\0${fingerprint(data)}`;
+  const seen = registered.get(realm) ?? /* @__PURE__ */ new Set();
+  if (seen.has(key)) return;
+  if (host) {
+    await host.registerFont(family, data, descriptors);
+  } else if (typeof globals.FontFace === "function" && fonts) {
+    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) {
+  const assets = context.capabilities.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) {
+  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 };
+}
+var NEVER = { aborted: false, addEventListener() {
+}, removeEventListener() {
+} };
+async function readBytes(context, ref) {
+  return assetsOf(context).read(refOf(ref), { signal: context.signal ?? NEVER });
+}
+async function readImage(context, ref) {
+  return decodeImage(await readBytes(context, ref));
+}
+async function writeImage(context, canvas, name, options = {}) {
+  const type = options.type ?? "image/png";
+  const bytes = await encodeImage(canvas, { type, ...options.quality === void 0 ? {} : { 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"
+  };
+}
+export {
+  canvasAvailable,
+  context2d,
+  createCanvas,
+  decodeImage,
+  encodeImage,
+  installImageHost,
+  readBytes,
+  readImage,
+  registerFont,
+  surface,
+  writeImage
+};
+//# sourceMappingURL=image.js.map

package/dist/index.html

@@ -6,7 +6,7 @@
   <!-- Pinterest browser extension: no Save buttons over canvases and previews -->
   <meta name="pinterest" content="nopin">
   <title>Cascade</title>
-  <script type="module" crossorigin src="/assets/index-DyvDC6pS.js"></script>
+  <script type="module" crossorigin src="/assets/index-5ZtDAuy2.js"></script>
   <link rel="modulepreload" crossorigin href="/assets/legacy-CTEeXeqF.js">
   <link rel="modulepreload" crossorigin href="/assets/index-client-DqYmKstU.js">
   <link rel="modulepreload" crossorigin href="/assets/nodeTypeUtils-BDJsc2Ks.js">

package/dist/player/editor.js

@@ -564,6 +564,12 @@ function stepValue(value, direction, step, min, max) {
 function notch(value, min, max) {
   return max > min ? Math.round((value - min) / (max - min) * 10) : 0;
 }
+function capture(element, pointerId) {
+  try {
+    element.setPointerCapture?.(pointerId);
+  } catch {
+  }
+}
 function clamp(value, min, max) {
   return Math.min(max, Math.max(min, value));
 }
@@ -594,7 +600,7 @@ function attachZoom(surface, layer, enabled) {
   };
   surface.addEventListener("pointerdown", (event) => {
     if (!enabled()) return;
-    surface.setPointerCapture?.(event.pointerId);
+    capture(surface, event.pointerId);
     pointers.set(event.pointerId, local(event));
     moved = false;
     begin();
@@ -637,7 +643,7 @@ function attachSheet(grip, options) {
   grip.addEventListener("pointerdown", (event) => {
     if (!options.enabled()) return;
     if (event.target?.closest?.("input,select,textarea,button")) return;
-    grip.setPointerCapture?.(event.pointerId);
+    capture(grip, event.pointerId);
     drag = { id: event.pointerId, y: event.clientY, height: options.height(), time: performance.now(), velocity: 0, last: event.clientY, moved: false };
   });
   grip.addEventListener("pointermove", (event) => {
@@ -737,8 +743,11 @@ button.primary{background:var(--accent);color:var(--bg);border-color:var(--accen
 
 /* Phones (.m, set from a media query): the preview on top, controls in a bottom sheet, one-row header. */
 .ce-grip,.ce-more,.ce-menu,.ce-busy,.ce-step,.ce-toast{display:none}
-.ce.m{overflow:hidden;padding:0 env(safe-area-inset-right) 0 env(safe-area-inset-left)}
-.ce.m .ce-bar{flex-wrap:nowrap;gap:4px;min-height:52px;padding:calc(4px + env(safe-area-inset-top)) 4px 4px 16px}
+html.ce-phone,html.ce-phone body{overflow-x:hidden;max-width:100%;overscroll-behavior:none;touch-action:pan-x pan-y}
+.ce.m{overflow:hidden;max-width:100vw;padding:0 env(safe-area-inset-right) 0 env(safe-area-inset-left)}
+.ce.m,.ce.m button,.ce.m select,.ce.m input,.ce.m textarea,.ce.m summary,.ce.m label,.ce.m a{touch-action:manipulation}
+.ce.m .ce-bar>*{min-width:0;max-width:100%}
+.ce.m .ce-bar{flex-wrap:nowrap;overflow:hidden;max-width:100vw;gap:4px;min-height:52px;padding:calc(4px + env(safe-area-inset-top)) 4px 4px 16px}
 .ce.m .ce-bar>*:not(h1):not(.ce-more):not(.ce-busy){display:none}
 .ce.m .ce-bar h1{flex:1;min-width:0;font-size:17px;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
 .ce.m .ce-more{display:inline-grid;place-items:center;width:44px;height:44px;padding:0;border:0;background:transparent;font-size:24px;line-height:1;letter-spacing:1px}
@@ -801,6 +810,7 @@ button.primary{background:var(--accent);color:var(--bg);border-color:var(--accen
 .ce.m .ce-toast button[hidden]{display:none}
 `;
 var PHONE = "(max-width: 760px), (pointer: coarse) and (max-height: 540px)";
+var VIEWPORT = "width=device-width,initial-scale=1,viewport-fit=cover,maximum-scale=1";
 async function startEditor(options) {
   const document = options.document;
   const editor = document.editor;
@@ -1049,9 +1059,13 @@ var EditorController = class {
     toast.append(toastText, toastAction);
     shell.append(bar, main, menu, toast);
     this.root.replaceChildren(shell);
-    const viewport = d.querySelector('meta[name="viewport"]');
-    if (viewport && !/viewport-fit/.test(viewport.getAttribute("content") ?? ""))
-      viewport.setAttribute("content", `${viewport.getAttribute("content")},viewport-fit=cover`);
+    let viewport = d.querySelector('meta[name="viewport"]');
+    if (!viewport) {
+      viewport = d.createElement("meta");
+      viewport.setAttribute("name", "viewport");
+      d.head.append(viewport);
+    }
+    viewport.setAttribute("content", VIEWPORT);
     viewer.addEventListener("dragover", (event) => event.preventDefault());
     viewer.addEventListener("drop", (event) => {
       event.preventDefault();
@@ -1671,6 +1685,15 @@ var EditorController = class {
     query?.addEventListener?.("change", update);
     win?.addEventListener("resize", update);
     attachZoom(this.ui.surface, this.ui.output, () => this.mobile);
+    const d = this.root.ownerDocument;
+    const onPreview = (target) => target instanceof Node && this.ui.surface.contains(target);
+    for (const type of ["gesturestart", "gesturechange", "gestureend"])
+      d.addEventListener(type, (event) => {
+        if (this.mobile) event.preventDefault();
+      }, { passive: false });
+    d.addEventListener("touchmove", (event) => {
+      if (this.mobile && event.touches.length > 1 && !onPreview(event.target)) event.preventDefault();
+    }, { passive: false });
     attachSheet(this.ui.head, {
       enabled: () => this.mobile && !this.landscape,
       height: () => this.sheetHeight,
@@ -1688,6 +1711,7 @@ var EditorController = class {
     this.mobile = mobile;
     this.landscape = mobile && landscape;
     this.ui.shell.classList.toggle("m", mobile);
+    this.root.ownerDocument.documentElement.classList.toggle("ce-phone", mobile);
     this.ui.shell.classList.toggle("land", this.landscape);
     if (changed) {
       this.placePeek(mobile);
@@ -1890,5 +1914,6 @@ async function recallFile(editor, id) {
 }
 export {
   EditorController,
+  VIEWPORT,
   startEditor
 };

package/dist/runtime/builtins/headless.d.ts

@@ -0,0 +1,19 @@
+import type { DefinitionNodeRegistration } from "../types.js";
+/**
+ * Built-ins the headless host knows and Studio does not yet: today only
+ * `cascade.image.ContactSheet`.
+ *
+ * A separate list rather than a line in `builtinNodeRegistrations` because
+ * that list is in Studio's first-paint bundle (the runtime and the Definition
+ * panel both import it), and the bundle budget has no room for a node Studio
+ * does not register. The CLI passes these to the runtime as ordinary
+ * registrations. When Studio registers the image nodes, they move into
+ * `index.ts` and this file goes.
+ */
+export declare const headlessOnlyNodeRegistrations: readonly DefinitionNodeRegistration[];
+/** Every built-in the headless host can run. */
+export declare const headlessNodeRegistrations: readonly DefinitionNodeRegistration[];
+/** A headless-only built-in, which the runtime does not know unless it is passed in. */
+export declare function headlessOnlyNodeRegistration(moduleId: string): DefinitionNodeRegistration | undefined;
+export declare function headlessNodeRegistration(moduleId: string): DefinitionNodeRegistration | undefined;
+//# sourceMappingURL=headless.d.ts.map

package/dist/runtime/builtins/headless.js

@@ -0,0 +1,25 @@
+import { builtinNodeRegistration, builtinNodeRegistrations } from "./index.js";
+import { imageNodeRegistrations } from "./image/index.js";
+/**
+ * Built-ins the headless host knows and Studio does not yet: today only
+ * `cascade.image.ContactSheet`.
+ *
+ * A separate list rather than a line in `builtinNodeRegistrations` because
+ * that list is in Studio's first-paint bundle (the runtime and the Definition
+ * panel both import it), and the bundle budget has no room for a node Studio
+ * does not register. The CLI passes these to the runtime as ordinary
+ * registrations. When Studio registers the image nodes, they move into
+ * `index.ts` and this file goes.
+ */
+export const headlessOnlyNodeRegistrations = Object.freeze([...imageNodeRegistrations]);
+/** Every built-in the headless host can run. */
+export const headlessNodeRegistrations = Object.freeze([...builtinNodeRegistrations, ...headlessOnlyNodeRegistrations]);
+const headlessOnlyById = new Map(headlessOnlyNodeRegistrations.map((registration) => [registration.moduleId, registration]));
+/** A headless-only built-in, which the runtime does not know unless it is passed in. */
+export function headlessOnlyNodeRegistration(moduleId) {
+    return headlessOnlyById.get(moduleId);
+}
+export function headlessNodeRegistration(moduleId) {
+    return builtinNodeRegistration(moduleId) ?? headlessOnlyById.get(moduleId);
+}
+//# sourceMappingURL=headless.js.map

package/dist/runtime/builtins/image/contactSheet.d.ts

@@ -0,0 +1,226 @@
+import type { NodeExecutionContext } from "@field/cascade/contracts";
+/**
+ * `cascade.image.ContactSheet` — several images as one labelled grid.
+ *
+ * The selection loop is a ladder of three to five options and a pick, and the
+ * pick is made by looking at them side by side. So the sheet is a node rather
+ * than a script beside the graph: a graph can end in one, and `cascade ladder`
+ * lays out its variants with the same layout and drawing code below.
+ *
+ * `portable` with `assets`, like `cascade.geo.Render`: it reads each image
+ * through the asset capability, decodes it with `createImageBitmap` and draws
+ * on an `OffscreenCanvas`, which both hosts supply (the headless one through
+ * @napi-rs/canvas). It lives in `cascade.image.*` beside Studio's image
+ * library, as the first definition-v1 node there; Studio does not register it
+ * yet, so today it runs headless and is listed in `../headless.ts` rather
+ * than in the built-ins Studio bundles.
+ */
+export declare const contactSheetDefinition: {
+    readonly apiVersion: 1;
+    readonly label: "Contact Sheet";
+    readonly description: "Lay images out as one labelled grid.";
+    readonly icon: "LayoutGrid";
+    readonly runsOn: "portable";
+    readonly capabilities: readonly ["assets"];
+    readonly inputs: {
+        readonly images: {
+            readonly kind: "data";
+            readonly type: "image";
+            readonly variadic: true;
+        };
+        /** More images after the wired ones: image values or project-relative paths. */
+        readonly list: {
+            readonly kind: "data";
+            readonly type: "array";
+        };
+    };
+    readonly outputs: {
+        readonly image: {
+            readonly kind: "data";
+            readonly type: "image";
+        };
+        readonly asset: {
+            readonly kind: "data";
+            readonly type: "asset";
+        };
+    };
+    readonly props: {
+        readonly columns: {
+            readonly type: "int";
+            readonly default: 0;
+            readonly min: 0;
+            readonly max: 64;
+            readonly description: "0: as square as the count allows.";
+        };
+        readonly gap: {
+            readonly type: "int";
+            readonly default: 16;
+            readonly min: 0;
+            readonly max: 512;
+        };
+        readonly background: {
+            readonly type: "color";
+            readonly default: readonly [1, 1, 1, 1];
+            readonly label: "Background";
+        };
+        readonly cellWidth: {
+            readonly type: "int";
+            readonly default: 0;
+            readonly min: 0;
+            readonly max: 8192;
+            readonly description: "0: images at their own size. Otherwise each is scaled to fit this width.";
+        };
+        readonly labels: {
+            readonly type: "string";
+            readonly default: "";
+            readonly description: "One label per line, in image order.";
+        };
+        readonly labelSize: {
+            readonly type: "int";
+            readonly default: 14;
+            readonly min: 6;
+            readonly max: 128;
+        };
+        readonly labelColor: {
+            readonly type: "color";
+            readonly default: readonly [0.1, 0.1, 0.1, 1];
+            readonly label: "Label Colour";
+        };
+        readonly filename: {
+            readonly type: "string";
+            readonly default: "contact-sheet.png";
+            readonly label: "Filename";
+        };
+    };
+};
+export interface ContactSheetOptions {
+    readonly columns?: number;
+    readonly gap?: number;
+    readonly cellWidth?: number;
+    readonly labels?: readonly string[];
+    readonly labelSize?: number;
+    /** RGBA, 0 to 1. */
+    readonly background?: readonly number[];
+    readonly labelColor?: readonly number[];
+}
+export interface SheetCell {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+    /** Top-left of the label line. */
+    readonly labelX: number;
+    readonly labelY: number;
+}
+export interface SheetLayout {
+    readonly width: number;
+    readonly height: number;
+    readonly columns: number;
+    readonly rows: number;
+    readonly cell: readonly [number, number];
+    readonly labelHeight: number;
+    readonly cells: readonly SheetCell[];
+}
+/**
+ * Where each image goes. By default every cell is as wide as the widest image
+ * and as tall as the tallest, and images keep their size. With `cellWidth`,
+ * cells are that wide and as tall as the tallest image needs at that width,
+ * and each image is scaled to fit. Either way an image is centred in its cell
+ * and never cropped, in whole pixels, so a sheet is the same bytes every run.
+ */
+export declare function contactSheetLayout(sizes: readonly (readonly [number, number])[], options?: {
+    columns?: number;
+    gap?: number;
+    cellWidth?: number;
+    labelHeight?: number;
+}): SheetLayout;
+/** Encoded images (PNG, JPEG, WebP) in, one PNG sheet out. */
+export declare function composeContactSheet(images: readonly Uint8Array[], options?: ContactSheetOptions): Promise<{
+    bytes: Uint8Array;
+    layout: SheetLayout;
+}>;
+export declare function executeContactSheet(context: NodeExecutionContext<typeof contactSheetDefinition>): Promise<void>;
+export declare const contactSheetRegistration: {
+    kind: "definition-v1";
+    moduleId: string;
+    definition: {
+        readonly apiVersion: 1;
+        readonly label: "Contact Sheet";
+        readonly description: "Lay images out as one labelled grid.";
+        readonly icon: "LayoutGrid";
+        readonly runsOn: "portable";
+        readonly capabilities: readonly ["assets"];
+        readonly inputs: {
+            readonly images: {
+                readonly kind: "data";
+                readonly type: "image";
+                readonly variadic: true;
+            };
+            /** More images after the wired ones: image values or project-relative paths. */
+            readonly list: {
+                readonly kind: "data";
+                readonly type: "array";
+            };
+        };
+        readonly outputs: {
+            readonly image: {
+                readonly kind: "data";
+                readonly type: "image";
+            };
+            readonly asset: {
+                readonly kind: "data";
+                readonly type: "asset";
+            };
+        };
+        readonly props: {
+            readonly columns: {
+                readonly type: "int";
+                readonly default: 0;
+                readonly min: 0;
+                readonly max: 64;
+                readonly description: "0: as square as the count allows.";
+            };
+            readonly gap: {
+                readonly type: "int";
+                readonly default: 16;
+                readonly min: 0;
+                readonly max: 512;
+            };
+            readonly background: {
+                readonly type: "color";
+                readonly default: readonly [1, 1, 1, 1];
+                readonly label: "Background";
+            };
+            readonly cellWidth: {
+                readonly type: "int";
+                readonly default: 0;
+                readonly min: 0;
+                readonly max: 8192;
+                readonly description: "0: images at their own size. Otherwise each is scaled to fit this width.";
+            };
+            readonly labels: {
+                readonly type: "string";
+                readonly default: "";
+                readonly description: "One label per line, in image order.";
+            };
+            readonly labelSize: {
+                readonly type: "int";
+                readonly default: 14;
+                readonly min: 6;
+                readonly max: 128;
+            };
+            readonly labelColor: {
+                readonly type: "color";
+                readonly default: readonly [0.1, 0.1, 0.1, 1];
+                readonly label: "Label Colour";
+            };
+            readonly filename: {
+                readonly type: "string";
+                readonly default: "contact-sheet.png";
+                readonly label: "Filename";
+            };
+        };
+    };
+    loadExecute: () => Promise<typeof executeContactSheet>;
+};
+//# sourceMappingURL=contactSheet.d.ts.map