@field/cascade 0.3.1 → 0.4.0

package/dist/cli/runtime/gpu.ts

@@ -74,3 +74,74 @@ export const ColorWrite = {
   ALPHA: 0x8,
   ALL: 0xf,
 } as const;
+
+/** 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 async 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 }> {
+  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: GPUBuffer | undefined;
+  let mapped = false;
+  let abort: (() => void) | undefined;
+  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: Awaited<typeof completion>;
+    if (signal) {
+      completed = await Promise.race([completion, new Promise<never>((_, 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 { /* Preserve the operation's original failure. */ }
+    }
+    if (mapped) buffer?.unmap();
+    buffer?.destroy();
+  }
+}

package/dist/contracts/camera.d.ts

@@ -0,0 +1,70 @@
+import type { Vec2i, Vec3 } from "./values.js";
+/**
+ * A camera, following Houdini's `/obj/cam`.
+ *
+ * `AGENTS.md` already required following Houdini's parameter names where
+ * Houdini has an equivalent node, and Marcus restated it for this type
+ * specifically on 2026-09-08. It is worth writing down what that costs, because
+ * the obvious design is not the Houdini one and it was proposed first here:
+ *
+ * **There is no field of view.** Houdini has `focal` (a focal length in
+ * millimetres) and `aperture` (the horizontal aperture, also in millimetres),
+ * and the angle is derived from the two. The defaults — 50 mm on a 41.4214 mm
+ * aperture — are a 45° horizontal field of view, which is where that odd
+ * aperture number comes from. Carrying an `fov` instead would be one number
+ * rather than two, and it would also make every lens value a photographer knows
+ * untypeable.
+ *
+ * **The orientation is `translate` and `rotate`, not eye-and-target.** A
+ * Houdini camera is an object with an ordinary transform, looking down its own
+ * **-Z** with **+Y** up, and look-at is a second mechanism layered on top
+ * (`lookatpath` and `upvector`) rather than the primitive. So `lookat` and `up`
+ * are here as the optional override they are in Houdini, and `rotate` is what
+ * the type actually carries.
+ *
+ * **Rotation is degrees, XYZ order** — Houdini's convention, and already the
+ * one `cascade.geo.Transform` uses for its own `rotate`. Note that this is
+ * deliberately unlike expressions, where bare trigonometry is radians; that
+ * divergence is recorded in `AGENTS.md` and is not new here.
+ *
+ * The one place this departs from Houdini's names is **`resolution` in place of
+ * `resx` and `resy`**, because the vault's more specific rule wins: anything
+ * with an x and a y is one `vec2`, and resolutions are named in that rule
+ * explicitly. Two floats that are really one vector cost two Inspector rows and
+ * two keyframes and let a graph carry a width without its height.
+ *
+ * Resolution belongs to the camera rather than to the render target for a
+ * Houdini reason that is easy to miss: the **vertical** aperture is not stored,
+ * it is derived from the horizontal one and the resolution ratio. So the frame
+ * shape participates in the projection, and a camera that did not know it could
+ * not produce a vertical angle at all.
+ */
+export interface Camera {
+    /** World position. Houdini `t`. */
+    readonly translate: Vec3;
+    /** Degrees, XYZ order. Houdini `r`. The camera looks down its own -Z. */
+    readonly rotate: Vec3;
+    /** Focal length in millimetres. Houdini `focal`, default 50. */
+    readonly focal: number;
+    /** Horizontal aperture in millimetres. Houdini `aperture`, default 41.4214. */
+    readonly aperture: number;
+    /** Near clipping plane. Houdini `near`, default 0.001. */
+    readonly near: number;
+    /** Far clipping plane. Houdini `far`, default 10000. */
+    readonly far: number;
+    /** Frame size in pixels. Houdini `resx`/`resy` as one `vec2i`. */
+    readonly resolution: Vec2i;
+    /** PIXEL aspect ratio, not the frame's. Houdini `aspect`, default 1. */
+    readonly aspect: number;
+    /** Houdini `projection`. */
+    readonly projection: "perspective" | "orthographic";
+    /** Width of the orthographic frame in world units. Houdini `orthowidth`. */
+    readonly orthowidth: number;
+}
+/** Houdini's own defaults, so a camera with nothing set matches a fresh
+ *  `/obj/cam` rather than something invented here. */
+export declare const CAMERA_DEFAULTS: Camera;
+/** True for any object carrying the fields this type is identified by. Used at
+ *  the document boundary, where a value arrives as parsed JSON. */
+export declare function isCamera(value: unknown): value is Camera;
+//# sourceMappingURL=camera.d.ts.map

package/dist/contracts/camera.js

@@ -0,0 +1,27 @@
+/** Houdini's own defaults, so a camera with nothing set matches a fresh
+ *  `/obj/cam` rather than something invented here. */
+export const CAMERA_DEFAULTS = Object.freeze({
+    translate: [0, 0, 0],
+    rotate: [0, 0, 0],
+    focal: 50,
+    aperture: 41.4214,
+    near: 0.001,
+    far: 10000,
+    resolution: [1280, 720],
+    aspect: 1,
+    projection: "perspective",
+    orthowidth: 2,
+});
+/** True for any object carrying the fields this type is identified by. Used at
+ *  the document boundary, where a value arrives as parsed JSON. */
+export function isCamera(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return false;
+    }
+    const candidate = value;
+    return (Array.isArray(candidate.translate) &&
+        Array.isArray(candidate.rotate) &&
+        typeof candidate.focal === "number" &&
+        typeof candidate.aperture === "number");
+}
+//# sourceMappingURL=camera.js.map

package/dist/contracts/capabilities.d.ts

@@ -77,13 +77,13 @@ export interface PythonCapability {
  * anything a graph author would recognise. So a shared device is not a
  * preference, it is the precondition for a chain of GPU nodes at all.
  *
- * **Stage 0 deliberately carries three members and no textures.** Ports still
- * pass `image`, so every picture is byte-identical to before; what this buys is
+ * **The capability carries a device/cache contract, not graph textures.** Ports
+ * still pass `image`; what this buys is
  * one device instead of one per node module, an owner for `device.lost`, and
  * somewhere legitimate to keep a pipeline — which is what lets the
  * `architecture/ambient-state` rule stay strict. The texture store, the
- * generation-stamped handles and the readback are Stage 1, and the shape of
- * this interface is meant to be lived with for a few days first.
+ * generation-stamped handles remain future work. Explicit RGBA8 readback is a
+ * helper in `cascade/gpu`, shared by browser and native hosts without encoding.
  *
  * The `GPUDevice` type comes from `@webgpu/types`, added to this package's
  * `tsconfig.json` as its only `types` entry. Contracts compiles with
@@ -102,7 +102,7 @@ export interface PythonCapability {
  */
 export interface GpuCapability {
     /**
-     * The one device for this page. Shared by every node declaring `gpu`, which
+     * The one device for this host. Shared by every node declaring `gpu`, which
      * is the whole point — see the note above on why two would be useless.
      */
     readonly device: GPUDevice;
@@ -128,7 +128,7 @@ export interface GpuCapability {
      * right answer again.
      *
      * `create` runs once per key. `destroy` is called when the entry is dropped:
-     * when the device is lost, or when the graph disposes. This is the member
+     * when the device is lost, or when the owning host disposes. This is the member
      * that makes `architecture/module-state` keepable — it was previously
      * forbidding the only available way to hold a pipeline.
      */

package/dist/contracts/definition.d.ts

@@ -1,7 +1,7 @@
 import type { CapabilityMap, CascadeAbortSignal, NodeCapabilityName, ProgressReporter } from "./capabilities.js";
 import type { CascadeType, CoreType, JsonValue, NamespacedType, SerializableValueForType, ValueForType } from "./values.js";
 export type RuntimeEnvironment = "portable" | "browser" | "server";
-export type CapabilityForEnvironment<E extends RuntimeEnvironment> = E extends "portable" ? "assets" | "media" : E extends "browser" ? "assets" | "media" | "gpu" : "files" | "assets" | "media" | "python" | "shell";
+export type CapabilityForEnvironment<E extends RuntimeEnvironment> = E extends "portable" ? "assets" | "media" | "gpu" : E extends "browser" ? "assets" | "media" | "gpu" : "files" | "assets" | "media" | "python" | "shell" | "gpu";
 export type DataTypeForEnvironment<E extends RuntimeEnvironment> = E extends "browser" ? CascadeType : Exclude<CascadeType, "texture">;
 type ControlFor<T extends CascadeType> = T extends "float" ? "number" | "slider" | "range" : T extends "int" ? "int" | "slider" | "range" : T extends "bool" ? "boolean" : T extends "string" ? "text" | "textarea" | "select" : T extends "vec2" | "vec3" | "vec4" | "vec2i" | "vec3i" | "vec4i" ? "vector" : T extends "mat2" | "mat3" | "mat4" ? "matrix" : T extends "color" ? "color" : T extends "image" ? "image" : T extends "asset" ? "asset" | "select" : T extends "texture" ? never : "select";
 /**
@@ -41,12 +41,34 @@ type AcceptMetadata<T extends CascadeType> = T extends "image" | "asset" ? {
 } : {
     readonly accept?: never;
 };
+/**
+ * One choice on a select control: the bare value, or the value with the words
+ * a person reads.
+ *
+ * The labelled form exists because losing it cost something real. Converting
+ * `image-superres` turned *"Off (pass through) / Local — Real-ESRGAN /
+ * Magnific — costs money"* into `off` / `local` / `magnific`, and that third
+ * label carried **the only warning that one of the three engines spends money
+ * per call**. A lost display name is a papercut; a lost cost warning is a
+ * bill. Six props across the sketches had lost their labels by the time this
+ * landed, and that one is why it was not deferred any longer.
+ *
+ * A bare value stays legal, and reads as "the value is the label" — which is
+ * true of most enums and is what every existing definition means.
+ */
+export type SelectOption<T extends CascadeType> = SerializableValueForType<T> | Readonly<{
+    value: SerializableValueForType<T>;
+    label: string;
+    /** Greyed out but visible: an option that exists and cannot be picked
+     *  here, which is more informative than one that is simply absent. */
+    disabled?: boolean;
+}>;
 type SelectMetadata<T extends CascadeType> = {
     readonly control?: Exclude<ControlFor<T>, "select">;
     readonly options?: never;
 } | {
     readonly control: Extract<ControlFor<T>, "select">;
-    readonly options?: readonly SerializableValueForType<T>[];
+    readonly options?: readonly SelectOption<T>[];
 };
 export interface TriggerInputDefinition {
     readonly kind: "trigger";
@@ -100,6 +122,23 @@ export type PropDefinition<T extends PropDataType> = {
      * number came from.
      */
     readonly expression?: string;
+    /**
+     * Render this prop as a button that fires a named action, rather than as an
+     * editable field.
+     *
+     * It exists because converting a node removed a button. `observatory-moment`
+     * declared `action: 'panel:observatory-moments'` as a dynamic node, which the
+     * Inspector renders from `parameter.options.action`; the v1 adapter built its
+     * options from `label`, `min`, `max`, `step` and `options` only, so the
+     * Moment picker quietly became a two-step job through the panel menu instead
+     * of one click on the node. Nothing broke — the panel falls back to the
+     * selected node and reads the same prop — which is exactly why nobody would
+     * have noticed from a test.
+     *
+     * The value is the action name the host dispatches. Cascade does not
+     * interpret it; a `panel:` prefix is a Studio convention, not a contract.
+     */
+    readonly action?: string;
 } & NumericMetadata<T> & AcceptMetadata<T> & SelectMetadata<T>;
 export type AnyPropDefinition = {
     [T in PropDataType]: PropDefinition<T>;

package/dist/contracts/index.d.ts

@@ -1,9 +1,11 @@
 export * from "./animation.js";
+export * from "./camera.js";
 export * from "./capabilities.js";
 export * from "./color.js";
 export * from "./definition.js";
 export * from "./document.js";
 export * from "./geometry.js";
+export * from "./series.js";
 export * from "./validate.js";
 export * from "./values.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/contracts/index.js

@@ -1,9 +1,11 @@
 export * from "./animation.js";
+export * from "./camera.js";
 export * from "./capabilities.js";
 export * from "./color.js";
 export * from "./definition.js";
 export * from "./document.js";
 export * from "./geometry.js";
+export * from "./series.js";
 export * from "./validate.js";
 export * from "./values.js";
 //# sourceMappingURL=index.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 {
@@ -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 };
 }
@@ -170,6 +170,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,7 @@
+import type { Camera } from "./camera.js";
 import type { Color } from "./color.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", "asset", "array", "object", "any"];
 export type CoreType = (typeof CORE_TYPES)[number];
 export type NamespacedType = `${string}.${string}`;
 export type CascadeType = CoreType | NamespacedType;
@@ -94,7 +95,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 "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,7 @@ export const CORE_TYPES = [
     "mesh",
     "rects",
     "color",
+    "camera",
     "asset",
     "array",
     "object",

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-CC6YQw2n.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="stylesheet" crossorigin href="/assets/index-Y2ock1cw.css">
 </head>
 <body>
   <div id="app"></div>