@field/cascade 0.8.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

@@ -17,12 +17,52 @@
  * carries a project-relative path, never pixels.
  */
 
+export interface StageCallOptions {
+  /**
+   * Abandons the stage. In Studio the request is withdrawn — dropped if it is
+   * still queued for the worker, interrupted if it is running — and the call
+   * rejects at once, so a superseded cook stops costing anything the moment it
+   * is superseded rather than when the stage happens to finish.
+   *
+   * Optional: when it is absent the signal of the cook in flight is used (see
+   * `COOK_SIGNAL_KEY`), so a node that never heard of this still cancels.
+   */
+  readonly signal?: AbortSignal;
+}
+
 export interface StageBridge {
-  (stage: string, args: Record<string, unknown>): Promise<unknown>;
+  (stage: string, args: Record<string, unknown>, options?: StageCallOptions): Promise<unknown>;
 }
 
 const BRIDGE_KEY = '__cascadeStageBridge';
 
+/**
+ * Where the scheduler publishes the signal of the interactive cook in flight.
+ *
+ * On `globalThis` for the same reason as the bridge: every project module is
+ * compiled with its own copy of this file, so module state would not be shared
+ * with the scheduler that sets it. The interactive lane runs one node at a
+ * time, which is what makes a single ambient value correct: a stage started
+ * while node N cooks belongs to node N's cook. Read at call time, never later.
+ */
+export const COOK_SIGNAL_KEY = '__cascadeCookSignal';
+
+function ambientCookSignal(): AbortSignal | undefined {
+  const read = (globalThis as Record<string, unknown>)[COOK_SIGNAL_KEY];
+  if (typeof read !== 'function') return undefined;
+  const signal = (read as () => AbortSignal | null | undefined)();
+  return signal ?? undefined;
+}
+
+/** The rejection a withdrawn stage produces, recognisable without importing a
+ *  class across module copies. */
+function cancelledError(stage: string, signal: AbortSignal): Error {
+  const reason = signal.reason instanceof Error ? signal.reason.message : 'superseded';
+  const error = new Error(`stage "${stage}" was cancelled: ${reason}`);
+  error.name = 'AbortError';
+  return error;
+}
+
 /**
  * Install the local transport. Called by a host that can reach the filesystem —
  * the CLI does this before running a graph. Returns a disposer so a host can
@@ -71,20 +111,30 @@ async function capability(): Promise<string> {
   return token;
 }
 
-async function overHttp<T>(stage: string, args: Record<string, unknown>): Promise<T> {
+async function overHttp<T>(stage: string, args: Record<string, unknown>, signal?: AbortSignal): Promise<T> {
   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,
   });
 
-  let response = await postStage();
-  if (response.status === 403) {
-    capabilityPromise = undefined;
+  let response: Response;
+  let body: { ok?: boolean; stdout?: string; stderr?: string; error?: string };
+  try {
     response = await postStage();
+    if (response.status === 403) {
+      capabilityPromise = undefined;
+      response = await postStage();
+    }
+    body = await response.json() as typeof body;
+  } catch (error) {
+    if (signal?.aborted) throw cancelledError(stage, signal);
+    throw error;
   }
-
-  const body = await response.json() as { ok?: boolean; stdout?: string; stderr?: string; error?: string };
   if (!response.ok || !body.ok) {
     throw new Error(`stage "${stage}" failed: ${body.stderr || body.error || 'unknown error'}`);
   }
@@ -113,16 +163,29 @@ export async function stageAvailable(): Promise<boolean> {
  * rather than a URL parse error from a fetch that was never going to work —
  * which is what this whole file exists to stop happening.
  */
-export async function runStage<T = unknown>(stage: string, args: Record<string, unknown> = {}): Promise<T> {
+export async function runStage<T = unknown>(
+  stage: string,
+  args: Record<string, unknown> = {},
+  options: StageCallOptions = {},
+): Promise<T> {
+  const signal = options.signal ?? ambientCookSignal();
+  if (signal?.aborted) throw cancelledError(stage, signal);
   const bridge = localBridge();
-  if (bridge) return await bridge(stage, args) as T;
+  if (bridge) {
+    try {
+      return await bridge(stage, args, signal ? { signal } : undefined) as T;
+    } catch (error) {
+      if (signal?.aborted) throw cancelledError(stage, signal);
+      throw error;
+    }
+  }
   if (typeof document === 'undefined') {
     throw new Error(
       `Cannot run stage "${stage}": no host bridge is installed and there is no page to post from. ` +
       'A headless host must call installStageBridge() from cascade/stage before executing the graph.',
     );
   }
-  return overHttp<T>(stage, args);
+  return overHttp<T>(stage, args, signal);
 }
 
 /** A scratch path for a node's output, scoped by node id so re-running a graph

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/bundle.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Bundles: one port carrying a set of named fields.
+ *
+ * Marcus, 2026-10-10, looking at a graph where one node fanned out a dozen
+ * outputs wired everywhere: *"Instead of having these nodes with many different
+ * outputs (more than 3 or 4 outputs), can we just export some kind of JSON
+ * object, a sort of multi-object, instead of outputting 12 different outputs?"*
+ *
+ * A bundle value is a plain object of fields. Each field is any ordinary
+ * Cascade value; an image or a cache entry travels as its reference (an
+ * `ImageRef`, an `AssetRef`), never as pixels, so a bundle is as cheap to pass
+ * as the fields it names.
+ *
+ * What makes it more than `object`:
+ *
+ *   - a producer declares its fields (`fields: { dpi: "float", ... }`), so a
+ *     checker can name an unknown field and suggest the right one;
+ *   - an optional `schema` name (`format`, `signals`, `marks`) keeps two
+ *     unrelated bundles from being wired together;
+ *   - a consumer may declare the fields it reads (`fields: ["dpi"]`). It then
+ *     sees only those, and Studio re-cooks it only when one of them changed;
+ *   - expressions read a wired bundle's fields: `ch("format.dpi")`.
+ *
+ * Everything here is pure and dependency-free so the runtime, Studio and the
+ * CLI checker share one reading of the rules.
+ */
+import type { CascadeType } from "./values.js";
+/** A declared field: its type, or its type with words for whoever reads it. */
+export type BundleFieldDefinition = CascadeType | Readonly<{
+    type: CascadeType;
+    description?: string;
+}>;
+/** A producer's declaration: field name to type. */
+export type BundleFieldDefinitions = Readonly<Record<string, BundleFieldDefinition>>;
+export type Bundle = Readonly<Record<string, unknown>>;
+/** The type a field declaration names. */
+export declare function bundleFieldType(definition: BundleFieldDefinition | undefined): string;
+/** The description a field declaration carries, if any. */
+export declare function bundleFieldDescription(definition: BundleFieldDefinition | undefined): string | undefined;
+/**
+ * Whether two bundle ports may be wired. A port without a schema is generic and
+ * takes any bundle; two named schemas must agree.
+ */
+export declare function bundleSchemasCompatible(output: string | undefined, input: string | undefined): boolean;
+/** True for a value a bundle port can carry: a plain, non-array object. */
+export declare function isBundleValue(value: unknown): value is Bundle;
+/**
+ * A field path as an expression writes it: `format.dpi` is field `dpi` of the
+ * port `format`. Only the first dot splits, so a field name never needs
+ * escaping. Null when there is no dot to split on.
+ */
+export declare function splitBundlePath(name: string): {
+    port: string;
+    field: string;
+} | null;
+/**
+ * A bundle narrowed to the fields a consumer declared. A field the producer
+ * did not set is absent rather than `undefined`, the same as on the full value.
+ */
+export declare function selectBundleFields(value: unknown, fields: readonly string[]): Bundle | undefined;
+/**
+ * The closest candidate to a misspelt name, for "did you mean". Edit distance
+ * with a threshold that scales with the length, so `dpu` finds `dpi` and
+ * `colour` does not find `count`.
+ */
+export declare function suggestName(name: string, candidates: Iterable<string>): string | undefined;
+/** "unknown field X — did you mean Y? (fields: a, b, c)" */
+export declare function unknownFieldMessage(field: string, known: readonly string[], where: string): string;
+/**
+ * What is wrong with a value a producer committed to a bundle port, or null.
+ * With declared fields, every key must be declared; a declared field may be
+ * absent. Field types are not checked here; the runtime does that per type.
+ */
+export declare function bundleValueProblem(value: unknown, fields: BundleFieldDefinitions | undefined): string | null;
+//# sourceMappingURL=bundle.d.ts.map

package/dist/contracts/bundle.js

@@ -0,0 +1,112 @@
+/** The type a field declaration names. */
+export function bundleFieldType(definition) {
+    if (!definition)
+        return "any";
+    return typeof definition === "string" ? definition : definition.type;
+}
+/** The description a field declaration carries, if any. */
+export function bundleFieldDescription(definition) {
+    return typeof definition === "object" && definition ? definition.description : undefined;
+}
+/**
+ * Whether two bundle ports may be wired. A port without a schema is generic and
+ * takes any bundle; two named schemas must agree.
+ */
+export function bundleSchemasCompatible(output, input) {
+    return !output || !input || output === input;
+}
+/** True for a value a bundle port can carry: a plain, non-array object. */
+export function isBundleValue(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+/**
+ * A field path as an expression writes it: `format.dpi` is field `dpi` of the
+ * port `format`. Only the first dot splits, so a field name never needs
+ * escaping. Null when there is no dot to split on.
+ */
+export function splitBundlePath(name) {
+    const dot = name.indexOf(".");
+    if (dot <= 0 || dot === name.length - 1)
+        return null;
+    return { port: name.slice(0, dot), field: name.slice(dot + 1) };
+}
+/**
+ * A bundle narrowed to the fields a consumer declared. A field the producer
+ * did not set is absent rather than `undefined`, the same as on the full value.
+ */
+export function selectBundleFields(value, fields) {
+    if (!isBundleValue(value))
+        return value;
+    const selected = {};
+    for (const field of fields)
+        if (Object.prototype.hasOwnProperty.call(value, field))
+            selected[field] = value[field];
+    return Object.freeze(selected);
+}
+/**
+ * The closest candidate to a misspelt name, for "did you mean". Edit distance
+ * with a threshold that scales with the length, so `dpu` finds `dpi` and
+ * `colour` does not find `count`.
+ */
+export function suggestName(name, candidates) {
+    let best;
+    let bestDistance = Infinity;
+    const lower = name.toLowerCase();
+    for (const candidate of candidates) {
+        const distance = editDistance(lower, candidate.toLowerCase());
+        if (distance < bestDistance) {
+            best = candidate;
+            bestDistance = distance;
+        }
+    }
+    if (best === undefined)
+        return undefined;
+    const limit = Math.max(1, Math.floor(Math.max(name.length, best.length) / 3));
+    return bestDistance <= limit ? best : undefined;
+}
+/** "unknown field X — did you mean Y? (fields: a, b, c)" */
+export function unknownFieldMessage(field, known, where) {
+    const suggestion = suggestName(field, known);
+    return `${where} reads unknown bundle field "${field}"`
+        + (suggestion ? ` — did you mean "${suggestion}"?` : "")
+        + (known.length ? ` (fields: ${known.join(", ")})` : " (the bundle declares no fields)");
+}
+/**
+ * What is wrong with a value a producer committed to a bundle port, or null.
+ * With declared fields, every key must be declared; a declared field may be
+ * absent. Field types are not checked here; the runtime does that per type.
+ */
+export function bundleValueProblem(value, fields) {
+    if (value === undefined || value === null)
+        return null;
+    if (!isBundleValue(value))
+        return "a bundle must be a plain object of fields";
+    if (!fields)
+        return null;
+    const known = Object.keys(fields);
+    for (const key of Object.keys(value))
+        if (!Object.prototype.hasOwnProperty.call(fields, key)) {
+            const suggestion = suggestName(key, known);
+            return `sets undeclared bundle field "${key}"`
+                + (suggestion ? ` — did you mean "${suggestion}"?` : "")
+                + ` (declared: ${known.join(", ") || "none"})`;
+        }
+    return null;
+}
+function editDistance(a, b) {
+    const previous = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        let diagonal = previous[0];
+        previous[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const above = previous[j];
+            previous[j] = Math.min(previous[j] + 1, previous[j - 1] + 1, diagonal + (a[i - 1] === b[j - 1] ? 0 : 1));
+            diagonal = above;
+        }
+    }
+    return previous[b.length];
+}
+//# sourceMappingURL=bundle.js.map