@field/cascade 0.2.22 → 0.3.0

package/dist/cli/runtime/io.ts

@@ -43,6 +43,63 @@ export function mediaUrl(path: string, options: MediaOptions = {}): string {
   return `/api/media/${encoded}${query ? `?${query}` : ''}`;
 }
 
+/**
+ * The transport a host installs so `cascade/io` can reach project files.
+ *
+ * Same shape of decision as `cascade/stage`: the page posts to the server,
+ * because that is the only door a browser has, and a headless host installs a
+ * local transport before it runs the graph. Without one, every read here is a
+ * `fetch('/api/media/...')` against a relative URL with no origin to resolve it
+ * — which is exactly how a Canvas 2D node came to render in Studio and fail
+ * under `cascade run`.
+ *
+ * Paths stay project-relative on both sides. The bridge, not the node, decides
+ * what that resolves to.
+ */
+export interface IoBridge {
+  /** Read a project file's bytes. */
+  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>;
+}
+
+const IO_BRIDGE_KEY = '__cascadeIoBridge';
+
+/** Install the local transport. Returns a disposer, so a test can take it down. */
+export function installIoBridge(bridge: IoBridge | null): () => void {
+  const globals = globalThis as Record<string, unknown>;
+  const previous = globals[IO_BRIDGE_KEY];
+  globals[IO_BRIDGE_KEY] = bridge ?? undefined;
+  return () => {
+    globals[IO_BRIDGE_KEY] = previous;
+  };
+}
+
+function localIo(): IoBridge | null {
+  const bridge = (globalThis as Record<string, unknown>)[IO_BRIDGE_KEY] as IoBridge | undefined;
+  return bridge && typeof bridge.read === 'function' && typeof bridge.write === 'function' ? bridge : null;
+}
+
+/**
+ * A project file's bytes, over whichever transport this host has. Every read in
+ * this module goes through here so the two hosts differ in one place only.
+ */
+export async function loadBytes(path: string, options: MediaOptions = { raw: true }): Promise<ArrayBuffer> {
+  const bridge = localIo();
+  if (bridge) {
+    const bytes = await bridge.read(path, options);
+    // A Buffer is usually a view into a larger pool, and `loadFloats` builds a
+    // typed-array VIEW onto whatever comes back — so hand on the exact bytes.
+    const exact = bytes.byteOffset === 0 && bytes.byteLength === bytes.buffer.byteLength
+      ? bytes.buffer
+      : bytes.slice().buffer;
+    return exact as ArrayBuffer;
+  }
+  const response = await fetch(mediaUrl(path, options));
+  if (!response.ok) throw new Error(`cascade/io: cannot load ${path} (${response.status})`);
+  return await response.arrayBuffer();
+}
+
 /**
  * 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
@@ -50,14 +107,21 @@ export function mediaUrl(path: string, options: MediaOptions = {}): string {
  */
 export async function loadImage(path: string, options: MediaOptions = { raw: true }): Promise<HTMLImageElement> {
   const image = new Image();
-  image.crossOrigin = 'anonymous';
-  image.src = mediaUrl(path, options);
+  const bridge = localIo();
+  if (bridge) {
+    // No origin to resolve a URL against; hand the decoder the bytes.
+    (image as unknown as { src: unknown }).src = new Uint8Array(await loadBytes(path, options));
+  } else {
+    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> {
+  if (localIo()) 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());
@@ -80,6 +144,17 @@ export interface SaveOptions {
   quality?: number;
 }
 
+/**
+ * Anything that can produce encoded pixels. The two browser canvases are the
+ * usual case; a headless host's canvas offers Skia's own encoder instead, and
+ * `saveImage` takes whichever it is handed rather than making a node care.
+ */
+export interface ImageSource {
+  convertToBlob?(options?: { type?: string; quality?: number }): Promise<Blob>;
+  encode?(format: string, quality?: number): Promise<Uint8Array>;
+  toBuffer?(mime: string): Uint8Array;
+}
+
 /**
  * Write pixels into the project and get back the path to hand downstream.
  * Confined to the cache directory, like every other node output.
@@ -88,7 +163,7 @@ export interface SaveOptions {
  *   node.out('path').setValue(out);
  */
 export async function saveImage(
-  source: HTMLCanvasElement | OffscreenCanvas | Blob,
+  source: HTMLCanvasElement | OffscreenCanvas | Blob | ImageSource,
   path: string,
   options: SaveOptions = {}
 ): Promise<string> {
@@ -98,8 +173,14 @@ export async function saveImage(
 
   if (source instanceof Blob) {
     blob = source;
-  } else if ('convertToBlob' in source) {
+  } else if (typeof (source as OffscreenCanvas).convertToBlob === 'function') {
     blob = await (source as OffscreenCanvas).convertToBlob({ type, quality: options.quality });
+  } else if (typeof (source as ImageSource).encode === 'function') {
+    // A headless canvas that was handed over unwrapped — Skia's own encoder,
+    // rather than a browser API it does not have.
+    blob = new Blob([(await (source as ImageSource).encode!(format, options.quality)) as BlobPart], { type });
+  } else if (typeof (source as ImageSource).toBuffer === 'function') {
+    blob = new Blob([(source as ImageSource).toBuffer!(type) as BlobPart], { type });
   } else {
     blob = await new Promise<Blob>((resolve, reject) => {
       (source as HTMLCanvasElement).toBlob(
@@ -116,6 +197,13 @@ export async function saveImage(
 /** 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 bridge = localIo();
+  if (bridge) {
+    const bytes = data instanceof Uint8Array
+      ? data
+      : new Uint8Array(data instanceof Blob ? await data.arrayBuffer() : data);
+    return await bridge.write(clean, bytes);
+  }
   const response = await fetch(`/api/media/${clean.split('/').map(encodeURIComponent).join('/')}`, {
     method: 'PUT',
     headers: { 'Content-Type': 'application/octet-stream' },
@@ -204,9 +292,7 @@ function parseNpyHeader(buffer: ArrayBuffer): NpyHeader {
  * 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 buffer = await loadBytes(path, { raw: true });
   const header = parseNpyHeader(buffer);
 
   if (header.fortran) throw new Error('cascade/io: Fortran-ordered .npy is not supported');

package/dist/contracts/animation.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Animation as it appears in a document.
+ *
+ * A parameter can be a literal, an expression, or a keyframe channel. All
+ * three serialise in one place — the node's `props` map — because a channel
+ * that lived in a timeline object would need a registry of targets, and that
+ * registry goes stale the moment a node is renamed.
+ *
+ * A prop with neither an expression nor a channel is still written as a bare
+ * value, which is what every existing file on disk contains. The object form
+ * appears only when there is something to say beyond the value.
+ */
+export type CascadeInterpolation = "constant" | "linear" | "smooth";
+/** One key. `frame` may be fractional. Interpolation governs the segment that
+ *  LEAVES this key, and is omitted when it is the default (`smooth`). */
+export interface CascadeSerializedKeyframe {
+    readonly frame: number;
+    readonly value: number;
+    readonly interpolation?: CascadeInterpolation;
+}
+/** Keys are written in frame order and hold at most one key per frame. A
+ *  reader must tolerate neither being true and normalise. */
+export interface CascadeSerializedChannel {
+    readonly keys: readonly CascadeSerializedKeyframe[];
+}
+/**
+ * The object form of a prop. Written when the parameter carries an expression,
+ * a channel, or both.
+ *
+ * Both is legal, and the resolution order is fixed: **the channel wins and the
+ * expression is kept but inert.** Discarding an author's expression because
+ * they keyed the parameter is the worse failure of the two — the expression is
+ * still there to go back to, and deleting the channel restores it.
+ */
+export interface CascadeSerializedProp {
+    readonly value: unknown;
+    readonly expression?: string;
+    readonly channel?: CascadeSerializedChannel;
+}
+//# sourceMappingURL=animation.d.ts.map

package/dist/contracts/animation.js

@@ -0,0 +1,14 @@
+/**
+ * Animation as it appears in a document.
+ *
+ * A parameter can be a literal, an expression, or a keyframe channel. All
+ * three serialise in one place — the node's `props` map — because a channel
+ * that lived in a timeline object would need a registry of targets, and that
+ * registry goes stale the moment a node is renamed.
+ *
+ * A prop with neither an expression nor a channel is still written as a bare
+ * value, which is what every existing file on disk contains. The object form
+ * appears only when there is something to say beyond the value.
+ */
+export {};
+//# sourceMappingURL=animation.js.map

package/dist/contracts/definition.d.ts

@@ -4,7 +4,30 @@ export type RuntimeEnvironment = "portable" | "browser" | "server";
 export type CapabilityForEnvironment<E extends RuntimeEnvironment> = E extends "portable" ? "assets" | "media" : E extends "browser" ? "assets" | "media" | "webgl" : "files" | "assets" | "media" | "python" | "shell";
 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";
-type NumericMetadata<T extends CascadeType> = T extends "float" | "int" ? {
+/**
+ * `min`, `max` and `step`, for the types whose components are numbers.
+ *
+ * The vectors are included, and were not: they typed all three as `never`, so
+ * the six vector types could not carry a range at all. Nothing exercised it
+ * because no builtin vec prop has one — but Marcus's standing rule is that
+ * anything with an x and a y is one `vec2` rather than two floats, and two
+ * floats *can* carry a range while the `vec2` they became could not. So
+ * following the convention cost the Inspector its clamp and its drag
+ * granularity every time: `field-io-gradient-logo.offset` lost −1..1 step
+ * 0.005, `offset.offset` lost −2..2, `ripple.centre` lost −1..2, and every
+ * remaining vector candidate across the sketches carries a range too.
+ *
+ * One range for all components, not one per component. A per-component tuple
+ * is a real design question — an `x` and a `y` with different limits is a
+ * legitimate thing to want — but it is a second shape for this field and every
+ * reader would have to handle both, so it waits for a case that needs it
+ * rather than being guessed at now.
+ *
+ * Matrices stay excluded. Their control is a grid of components with an
+ * identity button, and a range across a transform's cells is not a thing
+ * anybody has asked for.
+ */
+type NumericMetadata<T extends CascadeType> = T extends "float" | "int" | "vec2" | "vec3" | "vec4" | "vec2i" | "vec3i" | "vec4i" ? {
     readonly min?: number;
     readonly max?: number;
     readonly step?: number;
@@ -100,6 +123,21 @@ type OutputValue<O> = O extends TriggerOutputDefinition ? {
 } : never;
 export type DeclaredCapabilities<D extends NodeDefinition> = Readonly<Pick<CapabilityMap, D["capabilities"] extends readonly NodeCapabilityName[] ? D["capabilities"][number] : never>>;
 export interface NodeExecutionContext<D extends NodeDefinition> {
+    /**
+     * This node instance's id, stable for the life of the graph.
+     *
+     * It exists for one reason: naming a scratch file so that two instances of
+     * the same module do not overwrite each other. `field-logo` runs one module
+     * three times at three sizes, and `cloud-plots` runs `height-field` twice
+     * with opposite mode toggles — a literal path silently loses one of each
+     * pair. Pass it to `cachePath(context.nodeId, '.png')` and nothing else.
+     *
+     * An id is deliberately all a node gets. It names a namespace, not a
+     * position: there is no way to reach a parent, a sibling or the graph
+     * through it, which is what keeps a definition-v1 node a pure function of
+     * its own inputs. Do not parse it.
+     */
+    readonly nodeId: string;
     readonly inputs: Readonly<{
         [K in keyof Entries<D, "inputs">]: InputValue<Entries<D, "inputs">[K]>;
     }>;

package/dist/contracts/document.d.ts

@@ -10,6 +10,21 @@ export interface CascadeDocumentNode {
         value?: unknown;
     }>[] | Readonly<Record<string, unknown>>;
     readonly props?: Readonly<Record<string, unknown>>;
+    /**
+     * The dynamic engine's stored parameter values, and dead weight here.
+     *
+     * The deterministic runtime reads `props` and nothing else, so a document
+     * that still carries `params` loses every value in it and reports nothing —
+     * a converted sketch silently reverts to its defaults and draws something
+     * different. Declared so that the runtime can recognise the key and warn
+     * about it, which is the only reason it appears in a v1 type.
+     *
+     * @deprecated Migrate to `props`.
+     */
+    readonly params?: readonly Readonly<{
+        name: string;
+        value?: unknown;
+    }>[] | Readonly<Record<string, unknown>>;
 }
 export interface CascadeDocumentAnnotation {
     readonly id: string;

package/dist/contracts/index.d.ts

@@ -1,3 +1,4 @@
+export * from "./animation.js";
 export * from "./capabilities.js";
 export * from "./color.js";
 export * from "./definition.js";

package/dist/contracts/index.js

@@ -1,3 +1,4 @@
+export * from "./animation.js";
 export * from "./capabilities.js";
 export * from "./color.js";
 export * from "./definition.js";

package/dist/contracts/validate.d.ts

@@ -1,4 +1,5 @@
-import type { NodeDefinition } from "./definition.js";
+import type { NodeCapabilityName } from "./capabilities.js";
+import type { NodeDefinition, RuntimeEnvironment } from "./definition.js";
 export interface Diagnostic {
     readonly phase: string;
     readonly code: string;
@@ -8,6 +9,14 @@ export interface Diagnostic {
     readonly line?: number;
     readonly column?: number;
 }
+/**
+ * The capabilities a definition may *declare* for each environment. Declaring
+ * one is not the same as a host installing it — `MediaCapability` is declared
+ * here and implemented by nobody — so anything deciding whether a graph can
+ * actually run must ask the host, and use this only to classify which host a
+ * capability belongs to.
+ */
+export declare const CAPABILITIES_BY_ENVIRONMENT: Record<RuntimeEnvironment, readonly NodeCapabilityName[]>;
 export declare function validateNodeDefinition(value: unknown): readonly Diagnostic[];
 export declare function assertNodeDefinition(value: unknown): asserts value is NodeDefinition;
 //# sourceMappingURL=validate.d.ts.map

package/dist/contracts/validate.js

@@ -5,11 +5,19 @@ const NAMESPACED = /^[a-z][a-z0-9-]*(?:\.[A-Za-z][A-Za-z0-9_]*)+$/;
 const RESERVED = new Set(["__proto__", "prototype", "constructor"]);
 const CORE = new Set(CORE_TYPES);
 const CONTROLS = new Set(["number", "slider", "range", "int", "boolean", "text", "textarea", "select", "vector", "matrix", "color", "image", "asset"]);
-const ALLOWED = {
+/**
+ * The capabilities a definition may *declare* for each environment. Declaring
+ * one is not the same as a host installing it — `MediaCapability` is declared
+ * here and implemented by nobody — so anything deciding whether a graph can
+ * actually run must ask the host, and use this only to classify which host a
+ * capability belongs to.
+ */
+export const CAPABILITIES_BY_ENVIRONMENT = {
     portable: ["assets", "media"],
     browser: ["assets", "media", "webgl"],
     server: ["files", "assets", "media", "python", "shell"],
 };
+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");

package/dist/graphs/default.cascade

@@ -9,7 +9,7 @@
   "nodes": [
     {
       "id": "Color1",
-      "module": "cascade.lens.Color",
+      "module": "cascade.image.Color",
       "position": [0, 0],
       "source": "stdlib",
       "props": {

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-BXYXSdgh.js"></script>
-  <link rel="modulepreload" crossorigin href="/assets/legacy-DIu3XRwl.js">
-  <link rel="modulepreload" crossorigin href="/assets/index-client-DN_FvjN8.js">
-  <link rel="modulepreload" crossorigin href="/assets/nodeTypeUtils-CweA3NHd.js">
-  <link rel="stylesheet" crossorigin href="/assets/index-CrNke7SW.css">
+  <script type="module" crossorigin src="/assets/index-HTCN44kj.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">
 </head>
 <body>
   <div id="app"></div>

package/dist/io.d.ts

@@ -0,0 +1,196 @@
+/**
+ * `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 declare function mediaUrl(path: string, options?: MediaOptions): string;
+/**
+ * The transport a host installs so `cascade/io` can reach project files.
+ *
+ * Same shape of decision as `cascade/stage`: the page posts to the server,
+ * because that is the only door a browser has, and a headless host installs a
+ * local transport before it runs the graph. Without one, every read here is a
+ * `fetch('/api/media/...')` against a relative URL with no origin to resolve it
+ * — which is exactly how a Canvas 2D node came to render in Studio and fail
+ * under `cascade run`.
+ *
+ * Paths stay project-relative on both sides. The bridge, not the node, decides
+ * what that resolves to.
+ */
+export interface IoBridge {
+    /** Read a project file's bytes. */
+    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>;
+}
+/** Install the local transport. Returns a disposer, so a test can take it down. */
+export declare function installIoBridge(bridge: IoBridge | null): () => void;
+/**
+ * A project file's bytes, over whichever transport this host has. Every read in
+ * this module goes through here so the two hosts differ in one place only.
+ */
+export declare function loadBytes(path: string, options?: MediaOptions): Promise<ArrayBuffer>;
+/**
+ * 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 declare function loadImage(path: string, options?: MediaOptions): Promise<HTMLImageElement>;
+/** Same, as an ImageBitmap — the right input for `texImage2D`. */
+export declare function loadBitmap(path: string, options?: MediaOptions): Promise<ImageBitmap>;
+/**
+ * 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 declare function loadFieldBitmap(path: string, options?: MediaOptions): Promise<ImageBitmap>;
+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;
+}
+/**
+ * Anything that can produce encoded pixels. The two browser canvases are the
+ * usual case; a headless host's canvas offers Skia's own encoder instead, and
+ * `saveImage` takes whichever it is handed rather than making a node care.
+ */
+export interface ImageSource {
+    convertToBlob?(options?: {
+        type?: string;
+        quality?: number;
+    }): Promise<Blob>;
+    encode?(format: string, quality?: number): Promise<Uint8Array>;
+    toBuffer?(mime: string): Uint8Array;
+}
+/**
+ * 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 declare function saveImage(source: HTMLCanvasElement | OffscreenCanvas | Blob | ImageSource, path: string, options?: SaveOptions): Promise<string>;
+/** Write any bytes into the project cache and return the path. */
+export declare function saveBytes(data: Blob | ArrayBuffer | Uint8Array, path: string): Promise<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 declare function cachePath(nodeId: string, suffix: string): string;
+/**
+ * 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;
+}
+/**
+ * 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 declare function loadFloats(path: string): Promise<FloatImage>;
+/** Write float pixels back into the project. Python reads the result with a
+ *  plain `np.load`. Returns the stored path. */
+export declare function saveFloats(image: FloatImage, path: string): Promise<string>;
+/**
+ * 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 declare function toImageData(image: FloatImage, range?: [number, number]): ImageData;
+/**
+ * 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 declare function uploadFloatTexture(gl: WebGL2RenderingContext, image: FloatImage): WebGLTexture;
+/**
+ * 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 declare function textureFromImage(gl: WebGL2RenderingContext, image: string | {
+    path: string;
+}, options?: MediaOptions): Promise<TextureRef>;
+/** Allocate an empty texture to render into. */
+export declare function createTexture(gl: WebGL2RenderingContext, size: [number, number], options?: {
+    float?: boolean;
+    channels?: number;
+}): TextureRef;
+/**
+ * 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 declare function textureToImage(ref: TextureRef, path: string, options?: {
+    format?: 'png' | 'webp';
+    space?: 'srgb' | 'linear';
+}): Promise<ImageRef>;
+/** 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';
+}