@field/cascade 0.2.22

package/dist/cli/runtime/io.ts

@@ -0,0 +1,445 @@
+/**
+ * `cascade/io` — the runtime a BROWSER-side node imports.
+ *
+ * The interop rests on one rule: an image port carries a project-relative PATH,
+ * never pixels. A Python node writes a file and emits its path; a WebGL node
+ * reads that path as a texture, renders, writes its result back, and emits a
+ * path of the same kind. Neither knows or cares which side produced its input,
+ * which is what makes the two interchangeable — and it lets the heavy stages
+ * stay in Python while the interactive ones run in the page.
+ *
+ * The counterpart on the server side is the project's own exec bridge
+ * (`runStage`), which is per-project because the stages are.
+ *
+ * This file is compiled into any node module that imports 'cascade/io'; it is
+ * not published to npm and has no dependencies.
+ */
+
+export interface MediaOptions {
+  /** Ask for a resized copy. Never upscales past the file's own resolution. */
+  width?: number;
+  /** 'webp' | 'png' | 'jpeg' | 'avif'. Defaults to WebP, which is what you want
+   *  for anything being looked at rather than processed. */
+  format?: string;
+  /** The original bytes, unresized and unconverted. Use this when the pixels
+   *  matter — reading a render back for further processing, not previewing it. */
+  raw?: boolean;
+  quality?: number;
+}
+
+/** Build the URL that serves a project file to the page. */
+export function mediaUrl(path: string, options: MediaOptions = {}): string {
+  if (/^(https?:|data:|blob:)/.test(path)) return path;
+  const clean = path.replace(/^\.?\//, '');
+  const encoded = clean.split('/').map(encodeURIComponent).join('/');
+  const params = new URLSearchParams();
+  if (options.raw) params.set('raw', '1');
+  else {
+    if (options.width) params.set('w', String(options.width));
+    if (options.format) params.set('fmt', options.format);
+    if (options.quality) params.set('q', String(options.quality));
+  }
+  const query = params.toString();
+  return `/api/media/${encoded}${query ? `?${query}` : ''}`;
+}
+
+/**
+ * Load a project image as an <img>. Defaults to `raw` — a node is processing
+ * these pixels, not showing them, so a re-encoded copy would be the wrong thing
+ * to hand it. Pass a width explicitly to work at a smaller size on purpose.
+ */
+export async function loadImage(path: string, options: MediaOptions = { raw: true }): Promise<HTMLImageElement> {
+  const image = new Image();
+  image.crossOrigin = 'anonymous';
+  image.src = mediaUrl(path, options);
+  await image.decode();
+  return image;
+}
+
+/** Same, as an ImageBitmap — the right input for `texImage2D`. */
+export async function loadBitmap(path: string, options: MediaOptions = { raw: true }): Promise<ImageBitmap> {
+  const response = await fetch(mediaUrl(path, options));
+  if (!response.ok) throw new Error(`cascade/io: cannot load ${path} (${response.status})`);
+  return createImageBitmap(await response.blob());
+}
+
+/**
+ * A .npy field (a mask, a signal, a height or density field) rendered to
+ * greyscale, ready to upload as a texture. The numeric array itself stays on
+ * the server side for now; this is the visual form of it.
+ */
+export async function loadFieldBitmap(path: string, options: MediaOptions = {}): Promise<ImageBitmap> {
+  return loadBitmap(path, { ...options, raw: false });
+}
+
+export interface SaveOptions {
+  /** 'png' (default), 'webp' or 'jpeg'. PNG is the default because the usual
+   *  consumer of a node's output is another node, and a lossy intermediate
+   *  compounds down a pipeline. Choose webp when the output is a preview. */
+  format?: 'png' | 'webp' | 'jpeg';
+  quality?: number;
+}
+
+/**
+ * Write pixels into the project and get back the path to hand downstream.
+ * Confined to the cache directory, like every other node output.
+ *
+ *   const out = await saveImage(canvas, cachePath(node.id, '.png'));
+ *   node.out('path').setValue(out);
+ */
+export async function saveImage(
+  source: HTMLCanvasElement | OffscreenCanvas | Blob,
+  path: string,
+  options: SaveOptions = {}
+): Promise<string> {
+  const format = options.format ?? 'png';
+  const type = `image/${format}`;
+  let blob: Blob;
+
+  if (source instanceof Blob) {
+    blob = source;
+  } else if ('convertToBlob' in source) {
+    blob = await (source as OffscreenCanvas).convertToBlob({ type, quality: options.quality });
+  } else {
+    blob = await new Promise<Blob>((resolve, reject) => {
+      (source as HTMLCanvasElement).toBlob(
+        (result) => (result ? resolve(result) : reject(new Error('cascade/io: canvas produced no data'))),
+        type,
+        options.quality
+      );
+    });
+  }
+
+  return saveBytes(blob, path);
+}
+
+/** Write any bytes into the project cache and return the path. */
+export async function saveBytes(data: Blob | ArrayBuffer | Uint8Array, path: string): Promise<string> {
+  const clean = path.replace(/^\.?\//, '');
+  const response = await fetch(`/api/media/${clean.split('/').map(encodeURIComponent).join('/')}`, {
+    method: 'PUT',
+    headers: { 'Content-Type': 'application/octet-stream' },
+    body: data as BodyInit,
+  });
+  if (!response.ok) {
+    throw new Error(`cascade/io: cannot write ${path} — ${await response.text()}`);
+  }
+  const result = await response.json();
+  return result.path as string;
+}
+
+/**
+ * The output path convention, shared with the Python side: scoped by node id so
+ * one node's scratch file never lands on a sibling's. The server puts the cache
+ * key into the filename when it writes, so different inputs keep separate files.
+ */
+export function cachePath(nodeId: string, suffix: string): string {
+  const safe = nodeId.replace(/[^a-zA-Z0-9_-]/g, '_');
+  return `.cascade-cache/${safe}${suffix}`;
+}
+
+// ---------------------------------------------------------------- float data
+
+/**
+ * Float pixel data, shared between Python and JavaScript with no conversion.
+ *
+ * This works because a `.npy` file holding little-endian float32 in C order IS
+ * a Float32Array with a header in front of it. numpy pads that header so the
+ * data begins on a 64-byte boundary — measured on this project's own files, it
+ * starts at byte 128 every time — which means a typed array can be constructed
+ * as a VIEW onto the fetched buffer rather than a copy of it. A 10 MB density
+ * field costs one fetch and no marshalling.
+ *
+ * From there it goes straight where you need it: into `texImage2D` as an R32F
+ * or RGBA32F texture, into a compute pass, or through `toImageData` for
+ * Canvas2D. And `saveFloats` writes the same layout back, so `np.load` on the
+ * Python side reads it as an ordinary array.
+ */
+export interface FloatImage {
+  data: Float32Array;
+  /** [width, height] */
+  size: [number, number];
+  /** 1 for a mask or signal, 3 for RGB, 4 for RGBA. */
+  channels: number;
+}
+
+interface NpyHeader {
+  dtype: string;
+  shape: number[];
+  dataOffset: number;
+  fortran: boolean;
+}
+
+function parseNpyHeader(buffer: ArrayBuffer): NpyHeader {
+  const bytes = new Uint8Array(buffer);
+  const magic = String.fromCharCode(...bytes.subarray(0, 6));
+  if (magic !== '\x93NUMPY') throw new Error('cascade/io: not a .npy file');
+
+  const view = new DataView(buffer);
+  const major = bytes[6];
+  const headerLength = major >= 2 ? view.getUint32(8, true) : view.getUint16(8, true);
+  const headerStart = major >= 2 ? 12 : 10;
+  const header = String.fromCharCode(...bytes.subarray(headerStart, headerStart + headerLength));
+
+  const dtype = header.match(/'descr':\s*'([^']+)'/)?.[1];
+  if (!dtype) throw new Error('cascade/io: .npy header has no dtype');
+
+  const shape = (header.match(/'shape':\s*\(([^)]*)\)/)?.[1] ?? '')
+    .split(',')
+    .map(part => part.trim())
+    .filter(Boolean)
+    .map(Number);
+
+  return {
+    dtype,
+    shape,
+    dataOffset: headerStart + headerLength,
+    fortran: /'fortran_order':\s*True/.test(header),
+  };
+}
+
+/**
+ * Read a float image as a zero-copy Float32Array view. Non-float and
+ * non-native-endian arrays are converted rather than refused, so a uint8 mask
+ * still loads — it just costs a pass.
+ */
+export async function loadFloats(path: string): Promise<FloatImage> {
+  const response = await fetch(mediaUrl(path, { raw: true }));
+  if (!response.ok) throw new Error(`cascade/io: cannot load ${path} (${response.status})`);
+  const buffer = await response.arrayBuffer();
+  const header = parseNpyHeader(buffer);
+
+  if (header.fortran) throw new Error('cascade/io: Fortran-ordered .npy is not supported');
+  if (header.shape.length < 2) throw new Error(`cascade/io: expected an image-shaped array, got ${header.shape.length}D`);
+
+  const [height, width] = header.shape;
+  const channels = header.shape.length > 2 ? header.shape.slice(2).reduce((a, b) => a * b, 1) : 1;
+  const count = width * height * channels;
+
+  let data: Float32Array;
+  if (header.dtype === '<f4' || header.dtype === '=f4') {
+    // The whole point: a view, not a copy.
+    data = new Float32Array(buffer, header.dataOffset, count);
+  } else {
+    const source = readAs(buffer, header.dataOffset, header.dtype, count);
+    data = source instanceof Float32Array ? source : Float32Array.from(source);
+  }
+
+  return { data, size: [width, height], channels };
+}
+
+function readAs(buffer: ArrayBuffer, offset: number, dtype: string, count: number): ArrayLike<number> {
+  switch (dtype) {
+    case '<f8': case '=f8': return new Float64Array(buffer, offset, count);
+    case '|u1': case '<u1': case '=u1': case '|b1': return new Uint8Array(buffer, offset, count);
+    case '|i1': return new Int8Array(buffer, offset, count);
+    case '<i2': return new Int16Array(buffer, offset, count);
+    case '<u2': return new Uint16Array(buffer, offset, count);
+    case '<i4': return new Int32Array(buffer, offset, count);
+    case '<u4': return new Uint32Array(buffer, offset, count);
+    default: throw new Error(`cascade/io: .npy dtype ${dtype} is not supported`);
+  }
+}
+
+/** Build the .npy container around raw float32 bytes, laid out exactly as
+ *  numpy expects so `np.load` reads it with no special handling. */
+function encodeNpy(data: Float32Array, shape: number[]): Uint8Array {
+  const dict = `{'descr': '<f4', 'fortran_order': False, 'shape': (${shape.join(', ')}${shape.length === 1 ? ',' : ''}), }`;
+  // numpy pads so magic + version + length + header is a multiple of 64, which
+  // is what keeps the data 4-byte aligned for a zero-copy read on the way back.
+  const unpadded = 10 + dict.length + 1;
+  const padding = (64 - (unpadded % 64)) % 64;
+  const header = dict + ' '.repeat(padding) + '\n';
+
+  const out = new Uint8Array(10 + header.length + data.byteLength);
+  const view = new DataView(out.buffer);
+  out.set([0x93, 0x4e, 0x55, 0x4d, 0x50, 0x59, 1, 0], 0);   // \x93NUMPY v1.0
+  view.setUint16(8, header.length, true);
+  for (let i = 0; i < header.length; i++) out[10 + i] = header.charCodeAt(i);
+  out.set(new Uint8Array(data.buffer, data.byteOffset, data.byteLength), 10 + header.length);
+  return out;
+}
+
+/** Write float pixels back into the project. Python reads the result with a
+ *  plain `np.load`. Returns the stored path. */
+export async function saveFloats(image: FloatImage, path: string): Promise<string> {
+  const [width, height] = image.size;
+  const shape = image.channels > 1 ? [height, width, image.channels] : [height, width];
+  return saveBytes(encodeNpy(image.data, shape), path);
+}
+
+/**
+ * Float pixels -> ImageData for Canvas2D. Values are assumed to be 0..1 unless
+ * a range is given; pass the field's actual range to see it the way the viewer
+ * does rather than clipped.
+ */
+export function toImageData(image: FloatImage, range: [number, number] = [0, 1]): ImageData {
+  const [width, height] = image.size;
+  const [low, high] = range;
+  const span = high - low || 1;
+  const out = new Uint8ClampedArray(width * height * 4);
+
+  for (let i = 0; i < width * height; i++) {
+    const base = i * image.channels;
+    const r = ((image.data[base] - low) / span) * 255;
+    const g = image.channels > 1 ? ((image.data[base + 1] - low) / span) * 255 : r;
+    const b = image.channels > 2 ? ((image.data[base + 2] - low) / span) * 255 : r;
+    const a = image.channels > 3 ? image.data[base + 3] * 255 : 255;
+    out[i * 4] = r;
+    out[i * 4 + 1] = g;
+    out[i * 4 + 2] = b;
+    out[i * 4 + 3] = a;
+  }
+  return new ImageData(out, width, height);
+}
+
+/**
+ * Upload float pixels as a GPU texture, no conversion on the way. Needs the
+ * EXT_color_buffer_float extension to render INTO one; sampling works without.
+ */
+export function uploadFloatTexture(gl: WebGL2RenderingContext, image: FloatImage): WebGLTexture {
+  const [width, height] = image.size;
+  const formats: Record<number, [number, number]> = {
+    1: [gl.R32F, gl.RED],
+    2: [gl.RG32F, gl.RG],
+    3: [gl.RGB32F, gl.RGB],
+    4: [gl.RGBA32F, gl.RGBA],
+  };
+  const pair = formats[image.channels];
+  if (!pair) throw new Error(`cascade/io: ${image.channels} channels has no texture format`);
+  const [internalFormat, format] = pair;
+
+  const texture = gl.createTexture()!;
+  gl.bindTexture(gl.TEXTURE_2D, texture);
+  gl.pixelStorei(gl.UNPACK_ALIGNMENT, 1);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+  gl.texImage2D(gl.TEXTURE_2D, 0, internalFormat, width, height, 0, format, gl.FLOAT, image.data);
+  return texture;
+}
+
+// ------------------------------------------------------------------ textures
+
+/**
+ * A live GPU texture, passed between browser nodes.
+ *
+ * Separate from `image` on purpose, and the distinction is about cost rather
+ * than taste. An `image` is file-backed: durable, portable, readable by Python,
+ * and it costs a write and a read every time it is handed on. A `texture` never
+ * leaves the page — a chain of WebGL nodes passes one along with no round trip
+ * at all, which is what makes an interactive shader chain feel immediate.
+ *
+ * Because it is session-bound it cannot be cached, cannot be inspected after a
+ * reload, and cannot be read by a Python stage. So the conversions are explicit:
+ * `toImage` is a GPU readback and a file write, and it should be visible in the
+ * graph rather than happening silently on a connection.
+ */
+export interface TextureRef {
+  gl: WebGL2RenderingContext;
+  texture: WebGLTexture;
+  /** [width, height] */
+  size: [number, number];
+  channels: number;
+  /** True when the texture holds float data rather than 8-bit. */
+  float: boolean;
+}
+
+/** Upload an image file to the GPU. The integer path for `uploadFloatTexture`. */
+export async function textureFromImage(
+  gl: WebGL2RenderingContext,
+  image: string | { path: string },
+  options: MediaOptions = { raw: true }
+): Promise<TextureRef> {
+  const path = typeof image === 'string' ? image : image.path;
+
+  if (path.endsWith('.npy')) {
+    const floats = await loadFloats(path);
+    return {
+      gl,
+      texture: uploadFloatTexture(gl, floats),
+      size: floats.size,
+      channels: floats.channels,
+      float: true,
+    };
+  }
+
+  const bitmap = await loadBitmap(path, options);
+  const texture = gl.createTexture()!;
+  gl.bindTexture(gl.TEXTURE_2D, texture);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+  gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, bitmap);
+  const size: [number, number] = [bitmap.width, bitmap.height];
+  bitmap.close();
+  return { gl, texture, size, channels: 4, float: false };
+}
+
+/** Allocate an empty texture to render into. */
+export function createTexture(
+  gl: WebGL2RenderingContext,
+  size: [number, number],
+  options: { float?: boolean; channels?: number } = {}
+): TextureRef {
+  const [width, height] = size;
+  const float = options.float ?? false;
+  const channels = options.channels ?? 4;
+  const texture = gl.createTexture()!;
+  gl.bindTexture(gl.TEXTURE_2D, texture);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+  gl.texStorage2D(gl.TEXTURE_2D, 1, float ? gl.RGBA32F : gl.RGBA8, width, height);
+  return { gl, texture, size, channels, float };
+}
+
+/**
+ * Read a texture back off the GPU and write it into the project as an image.
+ * The one place a texture becomes durable — deliberately a named step, because
+ * a readback stalls the pipeline and a write costs a file.
+ */
+export async function textureToImage(
+  ref: TextureRef,
+  path: string,
+  options: { format?: 'png' | 'webp'; space?: 'srgb' | 'linear' } = {}
+): Promise<ImageRef> {
+  const { gl, size } = ref;
+  const [width, height] = size;
+
+  const framebuffer = gl.createFramebuffer();
+  gl.bindFramebuffer(gl.FRAMEBUFFER, framebuffer);
+  gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, ref.texture, 0);
+
+  try {
+    if (ref.float) {
+      const pixels = new Float32Array(width * height * 4);
+      gl.readPixels(0, 0, width, height, gl.RGBA, gl.FLOAT, pixels);
+      const stored = await saveFloats({ data: pixels, size, channels: 4 }, path.replace(/\.[^.]+$/, '') + '.npy');
+      return { path: stored, size, channels: 'rgba', depth: 'f32', space: options.space ?? 'linear' };
+    }
+
+    const pixels = new Uint8ClampedArray(width * height * 4);
+    gl.readPixels(0, 0, width, height, gl.RGBA, gl.UNSIGNED_BYTE, pixels);
+    const canvas = new OffscreenCanvas(width, height);
+    canvas.getContext('2d')!.putImageData(new ImageData(pixels, width, height), 0, 0);
+    const format = options.format ?? 'png';
+    const stored = await saveImage(canvas, path, { format });
+    return { path: stored, size, channels: 'rgba', depth: 'u8', space: options.space ?? 'srgb' };
+  } finally {
+    gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+    gl.deleteFramebuffer(framebuffer);
+  }
+}
+
+/** The value on an `image` port. 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';
+}

package/dist/cli/runtime/net.ts

@@ -0,0 +1,19 @@
+let capability: Promise<string> | null = null;
+
+export async function authorizedFetch(credential: string, url: string, init: RequestInit = {}): Promise<Response> {
+  capability ??= fetch('/api/net/capability').then(async (response) => {
+    if (!response.ok) throw new Error(`Authorized fetch capability failed: HTTP ${response.status}`);
+    return (await response.json()).capability as string;
+  });
+  const headers = Object.fromEntries(new Headers(init.headers).entries());
+  const response = await fetch('/api/net', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', 'X-Cascade-Net-Capability': await capability },
+    body: JSON.stringify({ credential, url, method: init.method ?? 'GET', headers,
+      ...(typeof init.body === 'string' ? { body: init.body } : {}) }),
+    signal: init.signal,
+  });
+  const result = await response.json();
+  if (!response.ok || !result.ok) throw new Error(result.error ?? `Authorized fetch failed: HTTP ${response.status}`);
+  return new Response(result.body, { status: result.status, statusText: result.statusText, headers: result.headers });
+}

package/dist/cli/runtime/shell.ts

@@ -0,0 +1,46 @@
+import {
+  ShellProcessError,
+  type ShellProcessErrorKind,
+  type ShellRunOptions,
+  type ShellRunResult,
+} from '@cascade/contracts';
+
+export { ShellProcessError } from '@cascade/contracts';
+export type { ShellProcessErrorKind, ShellRunOptions, ShellRunResult } from '@cascade/contracts';
+
+let capabilityPromise: Promise<string> | undefined;
+
+export async function run(command: string, args: readonly string[] = [], options: ShellRunOptions = {}): Promise<ShellRunResult> {
+  capabilityPromise ??= fetch('/api/shell/capability', { cache: 'no-store' })
+    .then(async (response) => {
+      if (!response.ok) throw new Error('Cascade shell capability is unavailable');
+      return (await response.json() as { capability: string }).capability;
+    })
+    .catch((error) => {
+      capabilityPromise = undefined;
+      throw error;
+    });
+  const capability = await capabilityPromise;
+  const response = await fetch('/api/shell', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', 'X-Cascade-Shell-Capability': capability },
+    body: JSON.stringify({ command, args, cwd: options.cwd, timeout: options.timeout, stdin: options.stdin, env: options.env }),
+    signal: options.signal as AbortSignal | undefined,
+  });
+  const payload = await response.json() as ({ ok: true } & ShellRunResult) | ({ ok: false; error: string; kind?: ShellProcessErrorKind } & Partial<ShellRunResult>);
+  if (payload.ok) return payload;
+  if (payload.kind === 'nonzero') return toResult(payload);
+  if (payload.kind) throw new ShellProcessError(payload.kind, toResult(payload), payload.error);
+  throw new Error(payload.error);
+}
+
+export async function runJson<T = unknown>(command: string, args: readonly string[] = [], options: ShellRunOptions = {}): Promise<T> {
+  const result = await run(command, args, options);
+  if (result.code !== 0) throw new ShellProcessError('nonzero', result, result.stderr || `Command exited with code ${result.code}`);
+  const line = result.stdout.split(/\r?\n/).filter((value) => value.trim()).at(-1) ?? '';
+  try { return JSON.parse(line) as T; } catch { throw new ShellProcessError('invalid-json', result, 'Command output was not valid JSON'); }
+}
+
+function toResult(value: Partial<ShellRunResult>): ShellRunResult {
+  return { stdout: value.stdout ?? '', stderr: value.stderr ?? '', code: value.code ?? null, timedOut: value.timedOut ?? false, cancelled: value.cancelled ?? false, outputLimited: value.outputLimited ?? false };
+}

package/dist/cli/runtime/stage.ts

@@ -0,0 +1,132 @@
+/**
+ * `cascade/stage` — call a project's Python stage from either host.
+ *
+ * A project's heavy work lives in Python stages, and until now every project
+ * hand-rolled its own bridge to them by posting to `/api/exec`. That works in
+ * Studio and fails everywhere else: `cascade run` has no server to post to and
+ * no origin to resolve a relative URL against, so any graph with a Python node
+ * could not be rendered offline. Each project reimplementing the same fetch
+ * also meant each project reimplementing the same response unwrapping, and
+ * getting it subtly wrong.
+ *
+ * So the bridge belongs to Cascade, with one transport per host: the page posts
+ * to the server, and a headless host installs `installStageBridge` before it
+ * executes the graph. A node imports `runStage` and never learns which it got.
+ *
+ * The counterpart for files is `cascade/io`, which keeps the same rule: a port
+ * carries a project-relative path, never pixels.
+ */
+
+export interface StageBridge {
+  (stage: string, args: Record<string, unknown>): Promise<unknown>;
+}
+
+const BRIDGE_KEY = '__cascadeStageBridge';
+
+/**
+ * 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
+ * take it back down, which matters for tests more than for a one-shot run.
+ */
+export function installStageBridge(bridge: StageBridge | null): () => void {
+  const globals = globalThis as Record<string, unknown>;
+  const previous = globals[BRIDGE_KEY];
+  globals[BRIDGE_KEY] = bridge ?? undefined;
+  return () => {
+    globals[BRIDGE_KEY] = previous;
+  };
+}
+
+function localBridge(): StageBridge | null {
+  const bridge = (globalThis as Record<string, unknown>)[BRIDGE_KEY];
+  return typeof bridge === 'function' ? (bridge as StageBridge) : null;
+}
+
+let capabilityPromise: Promise<string | null> | undefined;
+
+async function discoverCapability(): Promise<string | null> {
+  capabilityPromise ??= fetch('/api/exec/capability', { cache: 'no-store' })
+    .then(async (response) => {
+      if (response.status === 404) {
+        capabilityPromise = undefined;
+        return null;
+      }
+      if (!response.ok) throw new Error(`Cascade exec capability is unavailable (${response.status})`);
+      const token = (await response.json() as { capability?: unknown }).capability;
+      if (typeof token !== 'string' || !token) {
+        throw new Error('Cascade exec capability response did not contain a capability');
+      }
+      return token;
+    })
+    .catch((error) => {
+      capabilityPromise = undefined;
+      throw error;
+    });
+  return capabilityPromise;
+}
+
+async function capability(): Promise<string> {
+  const token = await discoverCapability();
+  if (token === null) throw new Error('Cascade exec capability is unavailable (404)');
+  return token;
+}
+
+async function overHttp<T>(stage: string, args: Record<string, unknown>): 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 }),
+  });
+
+  let response = await postStage();
+  if (response.status === 403) {
+    capabilityPromise = undefined;
+    response = await postStage();
+  }
+
+  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'}`);
+  }
+  if (typeof body.stdout !== 'string') {
+    throw new Error(`stage "${stage}" returned an invalid response`);
+  }
+  // The dispatcher's result is the last line it printed, so a stage that logs
+  // on its way through does not corrupt its own return value.
+  const lastLine = body.stdout.trim().split('\n').pop() || '{}';
+  return JSON.parse(lastLine) as T;
+}
+
+/** Whether this host has a local stage bridge or a browser-accessible stage
+ * endpoint. A missing browser route is a supported "not available" result;
+ * authorization and transport failures remain errors. */
+export async function stageAvailable(): Promise<boolean> {
+  if (localBridge()) return true;
+  if (typeof document === 'undefined') return false;
+  return (await discoverCapability()) !== null;
+}
+
+/**
+ * Run a stage and return its parsed result.
+ *
+ * A headless host without a bridge installed gets a message that says so,
+ * 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> {
+  const bridge = localBridge();
+  if (bridge) return await bridge(stage, args) as T;
+  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);
+}
+
+/** A scratch path for a node's output, scoped by node id so re-running a graph
+ *  does not clobber a sibling's file. */
+export function cachePath(nodeId: string, suffix: string): string {
+  return `.cascade-cache/${nodeId.replace(/[^a-zA-Z0-9_-]/g, '_')}${suffix}`;
+}