@field/cascade 0.3.1 → 0.5.1

package/dist/contracts/scene.d.ts

@@ -0,0 +1,129 @@
+import type { Camera } from "./camera.js";
+import type { Geometry } from "./geometry.js";
+import type { Vec3, Vec4 } from "./values.js";
+/**
+ * A scene: geometry, an optional camera, and lights.
+ *
+ * Marcus asked for this on 2026-09-09, and it arrived as a correction to a
+ * worse design. The plan before it proposed a separate `scene` panel beside the
+ * Viewer, and then — once that was corrected — a Viewer 3D mode that special
+ * cased `geometry`. His version:
+ *
+ * > *"If we want a 'scene' we could just create a merge node with a 3D viewer,
+ * > or perhaps a 'scene' root node with a variadic input? … a 'scene' node with
+ * > a camera, lights and geometry attached becomes a '3d scene'."*
+ *
+ * What that buys is not a feature, it is the removal of a branch. **The Viewer's
+ * 3D mode renders exactly one type.** A bare `geometry` output is a scene
+ * carrying a default camera and a default light, which is what Houdini itself
+ * does — the viewport camera and the headlight exist until you make real ones —
+ * so "geometry displays in 3D" is a promotion (`sceneFromGeometry`) rather than
+ * a second code path. Every branch that special-cases geometry against scene is
+ * a place the two can disagree about framing.
+ *
+ * The same promotion is why `cascade.geo.Render` can take a scene without
+ * breaking a single existing sketch: `geometry` widens to `scene`, so the old
+ * wire is still legal and lands on `asScene`.
+ *
+ * ## Why this is not `cascade.geo.Merge`
+ *
+ * Merge concatenates points, vertices and primitives and renumbers them, and a
+ * camera is not a primitive — `mergeGeometries`' collision rules have nothing
+ * to say about one. Two operations that both take N inputs are not the same
+ * operation.
+ *
+ * ## Why the camera is nullable rather than defaulted here
+ *
+ * A scene with no camera means *"use the viewport's own navigated camera"*, and
+ * that is a different statement from *"use a 50 mm camera at the origin"*. It
+ * is also Houdini's behaviour, which Marcus confirmed on 2026-09-09 — *"yes to
+ * copying the Houdini camera"*: unwired, you fly around freely; wire a
+ * `cascade.core.Camera` and the view locks to it and navigation writes back
+ * into its parameters. A defaulted camera here would make that distinction
+ * unrepresentable, and the viewport would have no way to know whether the
+ * camera it was handed was a decision or a fallback.
+ *
+ * `CAMERA_DEFAULTS` is still where the fallback numbers live; a consumer that
+ * genuinely needs a camera object asks for one there, and the null stays
+ * meaningful.
+ */
+export interface Scene {
+    /**
+     * Every geometry in the scene, in input order.
+     *
+     * A list rather than one merged geometry, because merging is lossy in the way
+     * that matters to a viewport: two geometries with different point counts and
+     * different style attributes become one after `mergeGeometries`, and the
+     * viewport can then no longer draw them with separate styles, report which
+     * one is over the item cap, or let one be soloed. Merge is available as a
+     * node when someone wants it.
+     */
+    readonly geometry: readonly Geometry[];
+    /** `null` means the viewport's own navigated camera. See above. */
+    readonly camera: Camera | null;
+    readonly lights: readonly Light[];
+}
+/**
+ * A light, following Houdini's `/obj/hlight` where it has an equivalent.
+ *
+ * Houdini's parameters are `light_type`, `light_color` and `light_intensity`;
+ * the names here drop the redundant prefix a Cascade node does not need, since
+ * the type already says it is a light. `type` keeps Houdini's own vocabulary,
+ * including **`distant`** for what most renderers call a directional light.
+ *
+ * Nothing consumes lights yet — every piece in the vault is lines, and there is
+ * no surface to shade. They are in the type from the start anyway, because
+ * adding a field to `Scene` later means every serialized scene and every node
+ * that constructs one changes, and the whole point of landing the type first is
+ * that it stops changing.
+ */
+export interface Light {
+    /** Houdini `light_type`. `ambient` ignores `translate` and `direction`. */
+    readonly type: "point" | "distant" | "ambient" | "spot";
+    /** World position. Ignored for `distant` and `ambient`. */
+    readonly translate: Vec3;
+    /** Direction the light points. Used by `distant` and `spot`. */
+    readonly direction: Vec3;
+    /** Houdini `light_color`, as a `vec4` — colour is four components, always. */
+    readonly color: Vec4;
+    /** Houdini `light_intensity`. */
+    readonly intensity: number;
+    /** Cone angle in degrees, `spot` only. Houdini `coneangle`. */
+    readonly coneangle: number;
+}
+export declare const LIGHT_DEFAULTS: Light;
+/** A scene with nothing in it. Not a failure — an empty graph produces one. */
+export declare const EMPTY_SCENE: Scene;
+export declare function isLight(value: unknown): value is Light;
+/**
+ * Structural, and deliberately not a brand.
+ *
+ * A scene crosses the host boundary as JSON — Studio panel to worker, project
+ * module to runtime — and a branded type would not survive the round trip, so
+ * the check has to be answerable from the shape alone. It tests `geometry` and
+ * `lights` are arrays and that `camera` is present-and-nullable rather than
+ * merely absent, which is what distinguishes a scene from an arbitrary object
+ * that happens to carry a `geometry` field.
+ */
+export declare function isScene(value: unknown): value is Scene;
+/** The promotion: a geometry is a scene with the viewport's camera and no lights. */
+export declare function sceneFromGeometry(geometry: Geometry): Scene;
+/**
+ * Read a `scene` input, which may have received a `geometry`.
+ *
+ * `geometry` widens to `scene` in `IMPLICIT_TYPE_CONVERSIONS`, so a node
+ * declaring a `scene` input can be handed either. **Every consumer of a scene
+ * input must go through this**, and that is the whole contract: the alternative
+ * is each consumer testing `isScene` and getting the fallback subtly different,
+ * which is how a viewport and a render node end up framing the same graph two
+ * ways.
+ *
+ * Returns `EMPTY_SCENE` for a missing input rather than throwing, because an
+ * unwired viewport is a normal state and not an error — and for anything that
+ * is neither a scene nor a geometry, because a viewport that throws on a
+ * surprising value is a viewport that goes black while the graph is fine. The
+ * connection rules are what stop a wrong type arriving; this is the floor under
+ * them, not the check.
+ */
+export declare function asScene(value: unknown): Scene;
+//# sourceMappingURL=scene.d.ts.map

package/dist/contracts/scene.js

@@ -0,0 +1,73 @@
+export const LIGHT_DEFAULTS = {
+    type: "point",
+    translate: [0, 0, 0],
+    direction: [0, 0, -1],
+    color: [1, 1, 1, 1],
+    intensity: 1,
+    coneangle: 45,
+};
+/** A scene with nothing in it. Not a failure — an empty graph produces one. */
+export const EMPTY_SCENE = { geometry: [], camera: null, lights: [] };
+export function isLight(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const light = value;
+    return ((light.type === "point" ||
+        light.type === "distant" ||
+        light.type === "ambient" ||
+        light.type === "spot") &&
+        Array.isArray(light.translate) &&
+        Array.isArray(light.direction) &&
+        Array.isArray(light.color) &&
+        typeof light.intensity === "number");
+}
+/**
+ * Structural, and deliberately not a brand.
+ *
+ * A scene crosses the host boundary as JSON — Studio panel to worker, project
+ * module to runtime — and a branded type would not survive the round trip, so
+ * the check has to be answerable from the shape alone. It tests `geometry` and
+ * `lights` are arrays and that `camera` is present-and-nullable rather than
+ * merely absent, which is what distinguishes a scene from an arbitrary object
+ * that happens to carry a `geometry` field.
+ */
+export function isScene(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const scene = value;
+    return (Array.isArray(scene.geometry) &&
+        Array.isArray(scene.lights) &&
+        "camera" in scene &&
+        (scene.camera === null || typeof scene.camera === "object"));
+}
+/** The promotion: a geometry is a scene with the viewport's camera and no lights. */
+export function sceneFromGeometry(geometry) {
+    return { geometry: [geometry], camera: null, lights: [] };
+}
+/**
+ * Read a `scene` input, which may have received a `geometry`.
+ *
+ * `geometry` widens to `scene` in `IMPLICIT_TYPE_CONVERSIONS`, so a node
+ * declaring a `scene` input can be handed either. **Every consumer of a scene
+ * input must go through this**, and that is the whole contract: the alternative
+ * is each consumer testing `isScene` and getting the fallback subtly different,
+ * which is how a viewport and a render node end up framing the same graph two
+ * ways.
+ *
+ * Returns `EMPTY_SCENE` for a missing input rather than throwing, because an
+ * unwired viewport is a normal state and not an error — and for anything that
+ * is neither a scene nor a geometry, because a viewport that throws on a
+ * surprising value is a viewport that goes black while the graph is fine. The
+ * connection rules are what stop a wrong type arriving; this is the floor under
+ * them, not the check.
+ */
+export function asScene(value) {
+    if (value === undefined || value === null)
+        return EMPTY_SCENE;
+    if (isScene(value))
+        return value;
+    if (typeof value === "object" && value.kind === "geometry")
+        return sceneFromGeometry(value);
+    return EMPTY_SCENE;
+}
+//# sourceMappingURL=scene.js.map

package/dist/contracts/schema.js

@@ -36,7 +36,27 @@ const dataProperties = {
     step: { type: "number", exclusiveMinimum: 0 },
     accept: { type: "array", items: { type: "string", minLength: 1 } },
     control,
-    options: { type: "array" },
+    // A bare value, or `{ value, label, disabled? }`. Both forms, because a
+    // bare value means "the value is its own label" and is what every
+    // definition written before the labelled form meant.
+    options: {
+        type: "array",
+        items: {
+            anyOf: [
+                { not: { type: "object" } },
+                {
+                    type: "object",
+                    properties: {
+                        value: {},
+                        label: { type: "string", minLength: 1 },
+                        disabled: { type: "boolean" },
+                    },
+                    required: ["value", "label"],
+                    additionalProperties: false,
+                },
+            ],
+        },
+    },
 };
 const data = object(dataProperties, ["kind", "type"]);
 const output = object({ kind: dataProperties.kind, type: dataProperties.type, description }, ["kind", "type"]);
@@ -47,6 +67,8 @@ const prop = object({
     // Props only, not inputs: an input's value comes from whatever is wired to
     // it, so a default expression there would be describing the wrong thing.
     expression: { type: "string", minLength: 1 },
+    // A button that fires a named host action instead of an editable field.
+    action: { type: "string", minLength: 1 },
 }, ["type", "default"]);
 function environmentCapabilities(runsOn, capabilities) {
     return {
@@ -60,7 +82,7 @@ export const nodeDefinitionSchema = {
     ...object({
         apiVersion: { const: 1 },
         runsOn: { enum: ["portable", "browser", "server"] },
-        container: { const: "subnet" },
+        container: { enum: ["subnet", "feedback"] },
         capabilities: {
             type: "array",
             items: { type: "string" },
@@ -74,7 +96,7 @@ export const nodeDefinitionSchema = {
         props: record(prop),
     }, ["apiVersion", "runsOn"]),
     allOf: [
-        environmentCapabilities("portable", ["assets", "media"]),
+        environmentCapabilities("portable", ["assets", "media", "gpu"]),
         environmentCapabilities("browser", ["assets", "media", "gpu"]),
         environmentCapabilities("server", [
             "files",
@@ -82,6 +104,7 @@ export const nodeDefinitionSchema = {
             "media",
             "python",
             "shell",
+            "gpu",
         ]),
     ],
 };

package/dist/contracts/series.d.ts

@@ -0,0 +1,75 @@
+import type { CascadePreset } from "./document.js";
+/**
+ * A series: one system, many instances.
+ *
+ * **A series is a graph plus an ordered list of parameter sets, and nothing
+ * else.** Plan: `Work/Projects/Cascade/plans/PLAN series.md`. The definition is
+ * deliberately this thin, because the alternative is the trap the plan names —
+ * *the series must not become a second document format.* If it grows its own
+ * copy of node state it forks from the graph and the two disagree.
+ *
+ * So there is no boundary in it. Houdini marks a region because the varying
+ * thing flows through the region as geometry; here the varying thing is a
+ * sparse map of parameter overrides keyed by node id, so the affected subgraph
+ * is **derived** from those overrides by the dependency graph that already
+ * exists. Nothing is marked, so nothing can be marked wrongly. That is also
+ * why `Block Begin`/`Block End` are not copied: they exist to serve feedback,
+ * a series has none, and the form without the feedback is all cost.
+ */
+export interface CascadeSeries {
+    readonly version: 1;
+    /**
+     * Ordered, and ordered on purpose.
+     *
+     * Independent instances do not need an order, which makes a bag tempting.
+     * But feedback — instance N reading N-1 — needs a sequence, and retrofitting
+     * order onto something built unordered is the expensive kind of change.
+     * Ordered costs nothing today. Marcus, 2026-09-08: *"feedback will at some
+     * point be useful but maybe not this series."*
+     */
+    readonly instances: readonly CascadeSeriesInstance[];
+    /** Which output the series collects, one value per instance. */
+    readonly collect: SeriesCollection;
+}
+export interface CascadeSeriesInstance {
+    /**
+     * **The record's own id, never its index in the array.**
+     *
+     * The decision the plan says to make before anything is built. A set reorders
+     * the moment a filter changes or data arrives, so a judgement pinned to a
+     * position — a favourite, an override, a note — silently becomes a different
+     * picture. For the Observatory this is the moment's id; for a wedge, the
+     * parameter tuple; for a hand-written list, whatever the author typed.
+     */
+    readonly id: string;
+    /** This instance's overrides. `CascadePreset` already is a parameter set. */
+    readonly parameters: CascadePreset;
+    /** For display. Never an address — see `id`. */
+    readonly label?: string;
+}
+/**
+ * Either a graph output by name, or any node's output port.
+ *
+ * Both, for the same reason subnets stay an ordinary tool rather than the
+ * mechanism: requiring a `cascade.core.Output` node would mean restructuring an
+ * existing graph before it could be a series, and `cloud-volumes` is exactly
+ * that case.
+ */
+export type SeriesCollection = {
+    readonly graphOutput: string;
+} | {
+    readonly nodeId: string;
+    readonly output: string;
+};
+/** One instance's result. `status` is the run's, so a failed instance is
+ *  reported rather than dropped — a series that silently renders 9,998 of
+ *  10,000 is worse than one that says which two failed. */
+export interface SeriesInstanceResult {
+    readonly id: string;
+    readonly index: number;
+    readonly status: "completed" | "cancelled" | "failed";
+    readonly value: unknown;
+    readonly diagnostics: readonly unknown[];
+    readonly durationMs: number;
+}
+//# sourceMappingURL=series.d.ts.map

package/dist/contracts/series.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=series.js.map

package/dist/contracts/validate.js

@@ -13,16 +13,16 @@ const CONTROLS = new Set(["number", "slider", "range", "int", "boolean", "text",
  * capability belongs to.
  */
 export const CAPABILITIES_BY_ENVIRONMENT = {
-    portable: ["assets", "media"],
+    portable: ["assets", "media", "gpu"],
     browser: ["assets", "media", "gpu"],
-    server: ["files", "assets", "media", "python", "shell"],
+    server: ["files", "assets", "media", "python", "shell", "gpu"],
 };
 const ALLOWED = CAPABILITIES_BY_ENVIRONMENT;
 const fields = (names) => new Set(names.split(" "));
 const TOP_FIELDS = fields("apiVersion runsOn container capabilities label description icon inputs outputs props");
 const DATA_FIELDS = fields("kind type default description variadic min max step accept control options");
 const OUTPUT_FIELDS = fields("kind type description");
-const PROP_FIELDS = fields("type default label description min max step accept control options expression");
+const PROP_FIELDS = fields("type default label description min max step accept control options expression action");
 function diagnostic(code, message, path) {
     return { phase: "definition", code: `definition/${code}`, message, path };
 }
@@ -90,8 +90,10 @@ export function validateNodeDefinition(value) {
         add("api-version", "apiVersion must be 1", "apiVersion");
     if (!Object.prototype.hasOwnProperty.call(ALLOWED, String(environment)))
         add("environment", "runsOn must be portable, browser, or server", "runsOn");
-    if (value.container !== undefined && value.container !== "subnet")
-        add("invalid-container", "container must be subnet", "container");
+    if (value.container !== undefined &&
+        value.container !== "subnet" &&
+        value.container !== "feedback")
+        add("invalid-container", "container must be subnet or feedback", "container");
     const allowed = ALLOWED[environment] ?? [];
     if (value.capabilities !== undefined && !Array.isArray(value.capabilities))
         add("invalid-capabilities", "capabilities must be an array", "capabilities");
@@ -170,6 +172,22 @@ export function validateNodeDefinition(value) {
                 add("invalid-control", `${String(raw.control)} is not a Cascade control`, `${path}.control`);
             if ("options" in raw && raw.control !== "select")
                 add("options-without-select", "options require the select control", `${path}.options`);
+            // A labelled option is `{ value, label }`. Checked because the failure
+            // is cosmetic and silent: a malformed entry reaches the control and
+            // renders as "[object Object]" rather than erroring, and the labelled
+            // form exists precisely because a lost label lost a cost warning.
+            if (Array.isArray(raw.options))
+                for (const [index, option] of raw.options.entries()) {
+                    if (option === null || typeof option !== "object")
+                        continue;
+                    const entry = option;
+                    if (!("value" in entry))
+                        add("invalid-option", "a labelled option needs a value", `${path}.options[${index}]`);
+                    if (typeof entry.label !== "string" || !entry.label)
+                        add("invalid-option", "a labelled option needs a non-empty label", `${path}.options[${index}].label`);
+                    if ("disabled" in entry && typeof entry.disabled !== "boolean")
+                        add("invalid-option", "disabled must be a boolean", `${path}.options[${index}].disabled`);
+                }
             const type = raw.type;
             if (!validType(type)) {
                 add("invalid-type", `${String(type)} is not a Cascade type`, `${path}.type`);

package/dist/contracts/values.d.ts

@@ -1,6 +1,8 @@
+import type { Camera } from "./camera.js";
 import type { Color } from "./color.js";
+import type { Light, Scene } from "./scene.js";
 import type { Geometry, GeometryFileRef, GeometryJson, GeometrySerialized } from "./geometry.js";
-export declare const CORE_TYPES: readonly ["float", "int", "bool", "string", "vec2", "vec3", "vec4", "vec2i", "vec3i", "vec4i", "mat2", "mat3", "mat4", "image", "texture", "geometry", "points", "lines", "polyline", "mesh", "rects", "color", "asset", "array", "object", "any"];
+export declare const CORE_TYPES: readonly ["float", "int", "bool", "string", "vec2", "vec3", "vec4", "vec2i", "vec3i", "vec4i", "mat2", "mat3", "mat4", "image", "texture", "geometry", "points", "lines", "polyline", "mesh", "rects", "color", "camera", "scene", "light", "asset", "array", "object", "any"];
 export type CoreType = (typeof CORE_TYPES)[number];
 export type NamespacedType = `${string}.${string}`;
 export type CascadeType = CoreType | NamespacedType;
@@ -94,7 +96,7 @@ export interface AssetRef {
     readonly mediaType?: string;
 }
 export type SerializableValue = JsonValue | AssetRef | ImageRef | GeometryJson | GeometryFileRef;
-export type ValueForType<T extends CascadeType> = T extends "float" | "int" ? number : T extends "bool" ? boolean : T extends "string" ? string : T extends "vec2" ? Vec2 : T extends "vec3" ? Vec3 : T extends "vec4" ? Vec4 : T extends "vec2i" ? Vec2i : T extends "vec3i" ? Vec3i : T extends "vec4i" ? Vec4i : T extends "mat2" ? Mat2 : T extends "mat3" ? Mat3 : T extends "mat4" ? Mat4 : T extends "color" ? Color : T extends "image" ? ImageRef : T extends "texture" ? TextureHandle : T extends "geometry" ? Geometry : T extends "points" ? PointSet : T extends "lines" ? LineSegments : T extends "polyline" ? Polyline : T extends "mesh" ? Mesh : T extends "rects" ? Rects : T extends "asset" ? AssetRef : T extends "array" ? readonly unknown[] : T extends "object" ? Readonly<Record<string, unknown>> : unknown;
+export type ValueForType<T extends CascadeType> = T extends "float" | "int" ? number : T extends "bool" ? boolean : T extends "string" ? string : T extends "vec2" ? Vec2 : T extends "vec3" ? Vec3 : T extends "vec4" ? Vec4 : T extends "vec2i" ? Vec2i : T extends "vec3i" ? Vec3i : T extends "vec4i" ? Vec4i : T extends "mat2" ? Mat2 : T extends "mat3" ? Mat3 : T extends "mat4" ? Mat4 : T extends "color" ? Color : T extends "camera" ? Camera : T extends "scene" ? Scene : T extends "light" ? Light : T extends "image" ? ImageRef : T extends "texture" ? TextureHandle : T extends "geometry" ? Geometry : T extends "points" ? PointSet : T extends "lines" ? LineSegments : T extends "polyline" ? Polyline : T extends "mesh" ? Mesh : T extends "rects" ? Rects : T extends "asset" ? AssetRef : T extends "array" ? readonly unknown[] : T extends "object" ? Readonly<Record<string, unknown>> : unknown;
 export type SerializableValueForType<T extends CascadeType> = T extends "texture" ? never : T extends "geometry" ? GeometrySerialized : T extends "array" ? readonly JsonValue[] : T extends "object" ? Readonly<Record<string, JsonValue>> : T extends "any" | NamespacedType ? JsonValue : ValueForType<T>;
 export {};
 //# sourceMappingURL=values.d.ts.map

package/dist/contracts/values.js

@@ -21,6 +21,9 @@ export const CORE_TYPES = [
     "mesh",
     "rects",
     "color",
+    "camera",
+    "scene",
+    "light",
     "asset",
     "array",
     "object",
@@ -38,6 +41,13 @@ export const IMPLICIT_TYPE_CONVERSIONS = {
     vec2i: ["vec2"],
     vec3i: ["vec3"],
     vec4i: ["vec4"],
+    /**
+     * A geometry *is* a scene — one with the viewport's own camera and no lights.
+     * So the wire is legal and nothing is lost, which is the widening rule this
+     * table already follows. Every consumer of a `scene` input reads it through
+     * `asScene`, which performs the promotion; see `scene.ts`.
+     */
+    geometry: ["scene"],
     vec4: ["color"],
     color: ["vec4"],
 };

package/dist/gpu.d.ts

@@ -69,3 +69,20 @@ export declare const ColorWrite: {
     readonly ALPHA: 8;
     readonly ALL: 15;
 };
+/** Read one single-sample rgba8unorm 2D texture into owned, tightly packed
+ * top-left RGBA bytes. No colour conversion, PNG encoding or graph transport.
+ * The caller owns the source texture and must give it COPY_SRC usage.
+ */
+export declare function readTexture(device: GPUDevice, texture: GPUTexture, options?: {
+    signal?: {
+        readonly aborted: boolean;
+        addEventListener(type: 'abort', listener: () => void, options?: {
+            once?: boolean;
+        }): void;
+        removeEventListener(type: 'abort', listener: () => void): void;
+    };
+}): Promise<{
+    data: Uint8Array<ArrayBuffer>;
+    width: number;
+    height: number;
+}>;

package/dist/gpu.js

@@ -43,11 +43,71 @@ var ColorWrite = {
   ALPHA: 8,
   ALL: 15
 };
+async function readTexture(device, texture, options = {}) {
+  const { signal } = options;
+  if (signal?.aborted) throw new Error("GPU readback aborted");
+  if (texture.format !== "rgba8unorm" || texture.dimension !== "2d" || texture.depthOrArrayLayers !== 1 || texture.sampleCount !== 1 || !(texture.usage & TextureUsage.COPY_SRC)) {
+    throw new Error("GPU readback requires a single-sample rgba8unorm 2D texture with COPY_SRC usage");
+  }
+  const { width, height } = texture;
+  const rowBytes = width * 4;
+  const bytesPerRow = Math.ceil(rowBytes / 256) * 256;
+  let buffer;
+  let mapped = false;
+  let abort;
+  let errorScopeOpen = false;
+  try {
+    device.pushErrorScope("validation");
+    errorScopeOpen = true;
+    buffer = device.createBuffer({
+      label: "Cascade RGBA readback",
+      size: bytesPerRow * height,
+      usage: BufferUsage.COPY_DST | BufferUsage.MAP_READ
+    });
+    const encoder = device.createCommandEncoder();
+    encoder.copyTextureToBuffer({ texture }, { buffer, bytesPerRow }, [width, height]);
+    device.queue.submit([encoder.finish()]);
+    const validation = device.popErrorScope();
+    errorScopeOpen = false;
+    const completion = Promise.allSettled([buffer.mapAsync(MapMode.READ), validation]);
+    let completed;
+    if (signal) {
+      completed = await Promise.race([completion, new Promise((_, reject) => {
+        abort = () => reject(new Error("GPU readback aborted"));
+        signal.addEventListener("abort", abort, { once: true });
+        if (signal.aborted) abort();
+      })]);
+    } else completed = await completion;
+    const mappingResult = completed[0];
+    const validationResult = completed[1];
+    if (validationResult.status === "rejected") throw validationResult.reason;
+    const validationError = validationResult.value;
+    if (validationError) throw new Error(`GPU readback validation failed: ${validationError.message}`);
+    if (mappingResult.status === "rejected") throw mappingResult.reason;
+    mapped = true;
+    if (signal?.aborted) throw new Error("GPU readback aborted");
+    const source = new Uint8Array(buffer.getMappedRange());
+    const data = new Uint8Array(rowBytes * height);
+    for (let y = 0; y < height; y++) data.set(source.subarray(y * bytesPerRow, y * bytesPerRow + rowBytes), y * rowBytes);
+    return { data, width, height };
+  } finally {
+    if (abort) signal?.removeEventListener("abort", abort);
+    if (errorScopeOpen) {
+      try {
+        await device.popErrorScope();
+      } catch {
+      }
+    }
+    if (mapped) buffer?.unmap();
+    buffer?.destroy();
+  }
+}
 export {
   BufferUsage,
   ColorWrite,
   MapMode,
   ShaderStage,
-  TextureUsage
+  TextureUsage,
+  readTexture
 };
 //# sourceMappingURL=gpu.js.map

package/dist/index.html

@@ -4,11 +4,11 @@
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>Cascade</title>
-  <script type="module" crossorigin src="/assets/index-CMcH8AgP.js"></script>
+  <script type="module" crossorigin src="/assets/index-De1cIZ9N.js"></script>
   <link rel="modulepreload" crossorigin href="/assets/legacy-CAj2_7QE.js">
   <link rel="modulepreload" crossorigin href="/assets/index-client-BoJgsN9M.js">
-  <link rel="modulepreload" crossorigin href="/assets/nodeTypeUtils-BBA1JqHx.js">
-  <link rel="stylesheet" crossorigin href="/assets/index-BDV5xGBZ.css">
+  <link rel="modulepreload" crossorigin href="/assets/nodeTypeUtils-BDJsc2Ks.js">
+  <link rel="stylesheet" crossorigin href="/assets/index-ilgbOu6G.css">
 </head>
 <body>
   <div id="app"></div>

package/dist/io.d.ts

@@ -1,19 +1,5 @@
-/**
- * `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.
- */
+/** Shared `cascade/io` helpers. Studio uses project HTTP routes; other hosts
+ * install a bridge. Image ports carry paths rather than ambient pixel buffers. */
 export interface MediaOptions {
     /** Ask for a resized copy. Never upscales past the file's own resolution. */
     width?: number;
@@ -45,6 +31,8 @@ export interface IoBridge {
     read(path: string, options?: MediaOptions): Promise<Uint8Array>;
     /** Write bytes into the project cache. Returns the stored project-relative path. */
     write(path: string, data: Uint8Array): Promise<string>;
+    /** Host-owned display URL, valid until the host releases its stored asset. */
+    url?(path: string, options?: MediaOptions): string;
 }
 /** Install the local transport. Returns a disposer, so a test can take it down. */
 export declare function installIoBridge(bridge: IoBridge | null): () => void;

package/dist/io.js

@@ -1,6 +1,8 @@
 // server/src/runtime/io.ts
 function mediaUrl(path, options = {}) {
   if (/^(https?:|data:|blob:)/.test(path)) return path;
+  const bridge = localIo();
+  if (bridge?.url) return bridge.url(path, options);
   const clean = path.replace(/^\.?\//, "");
   const encoded = clean.split("/").map(encodeURIComponent).join("/");
   const params = new URLSearchParams();
@@ -40,17 +42,33 @@ async function loadBytes(path, options = { raw: true }) {
 async function loadImage(path, options = { raw: true }) {
   const image = new Image();
   const bridge = localIo();
-  if (bridge) {
-    image.src = new Uint8Array(await loadBytes(path, options));
-  } else {
-    image.crossOrigin = "anonymous";
-    image.src = mediaUrl(path, options);
+  let temporaryUrl;
+  try {
+    if (bridge?.url) {
+      image.crossOrigin = "anonymous";
+      image.src = bridge.url(path, options);
+    } else if (bridge) {
+      const bytes = await loadBytes(path, options);
+      if (typeof document === "undefined") {
+        image.src = new Uint8Array(bytes);
+      } else {
+        temporaryUrl = URL.createObjectURL(new Blob([bytes]));
+        image.src = temporaryUrl;
+      }
+    } else {
+      image.crossOrigin = "anonymous";
+      image.src = mediaUrl(path, options);
+    }
+    await image.decode();
+    return image;
+  } finally {
+    if (temporaryUrl) URL.revokeObjectURL(temporaryUrl);
   }
-  await image.decode();
-  return image;
 }
 async function loadBitmap(path, options = { raw: true }) {
-  if (localIo()) return createImageBitmap(new Blob([await loadBytes(path, options)]));
+  const bridge = localIo();
+  if (bridge?.url) return createImageBitmap(await loadImage(path, options));
+  if (bridge) return createImageBitmap(new Blob([await loadBytes(path, options)]));
   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());