@field/cascade 0.2.22 → 0.3.1

package/dist/cli/runtime/gpu.ts

@@ -0,0 +1,76 @@
+/**
+ * `cascade/gpu` — WebGPU's flag namespaces as plain values.
+ *
+ * Small, and it was load-bearing. TypeScript's DOM library declares the WebGPU
+ * *interfaces* but not the constant objects, so the only way to reach
+ * `GPUTextureUsage.RENDER_ATTACHMENT` was off `globalThis` — which
+ * `architecture/ambient-state` correctly forbids inside a node module, because
+ * an ambient read makes a node's inputs invisible to the static reader that
+ * lets `cascade check` say anything without cooking.
+ *
+ * So a sketch had to choose between a rule and a working shader, and it chose
+ * a project library file to hide the read in. Both stay honest now: the rule
+ * keeps its teeth and a node imports these instead. That is the whole reason
+ * this file exists, and it is why it had to land with the capability rather
+ * than after it — a rule whose only workaround is removed at the same moment
+ * is a rule; one enforced a release earlier is a nuisance.
+ *
+ * The values are fixed by the WebGPU specification, not by an implementation,
+ * which is what makes writing them down safe rather than a guess. They are
+ * checked against a real browser's own globals in `tests/gpu-usage-flags.test.ts`
+ * — the numbers below were verified against Chrome rather than recalled.
+ */
+
+/** `GPUBufferUsage`. */
+export const BufferUsage = {
+  MAP_READ: 0x0001,
+  MAP_WRITE: 0x0002,
+  COPY_SRC: 0x0004,
+  COPY_DST: 0x0008,
+  INDEX: 0x0010,
+  VERTEX: 0x0020,
+  UNIFORM: 0x0040,
+  STORAGE: 0x0080,
+  INDIRECT: 0x0100,
+  QUERY_RESOLVE: 0x0200,
+} as const;
+
+/** `GPUTextureUsage`. */
+export const TextureUsage = {
+  COPY_SRC: 0x01,
+  COPY_DST: 0x02,
+  TEXTURE_BINDING: 0x04,
+  STORAGE_BINDING: 0x08,
+  RENDER_ATTACHMENT: 0x10,
+  /**
+   * Chrome 147 has this and it is newer than the rest — verified present
+   * 2026-09-08 alongside the others, but do not assume every implementation
+   * carries it. Included rather than omitted deliberately: leaving it out
+   * would send a node that wants it back to `globalThis`, which is the exact
+   * ambient read this file exists to remove, so an honest constant with a
+   * caveat beats an omission that forces a rule violation.
+   */
+  TRANSIENT_ATTACHMENT: 0x20,
+} as const;
+
+/** `GPUShaderStage`, for a bind group layout entry's `visibility`. */
+export const ShaderStage = {
+  VERTEX: 0x1,
+  FRAGMENT: 0x2,
+  COMPUTE: 0x4,
+} as const;
+
+/** `GPUMapMode`, for `buffer.mapAsync`. */
+export const MapMode = {
+  READ: 0x1,
+  WRITE: 0x2,
+} as const;
+
+/** `GPUColorWrite`, for a colour target's `writeMask`. */
+export const ColorWrite = {
+  RED: 0x1,
+  GREEN: 0x2,
+  BLUE: 0x4,
+  ALPHA: 0x8,
+  ALL: 0xf,
+} as const;

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

@@ -1,4 +1,4 @@
-import type { AssetRef, ImageRef, JsonValue, TextureHandle } from "./values.js";
+import type { AssetRef, ImageRef, JsonValue } from "./values.js";
 export interface CascadeAbortSignal {
     readonly aborted: boolean;
     readonly reason?: unknown;
@@ -66,10 +66,73 @@ export interface PythonCapability {
         progress: ProgressReporter;
     }): Promise<JsonValue | AssetRef | ImageRef>;
 }
-export interface WebGLCapability {
-    createTexture(descriptor: JsonValue, options: {
-        signal: CascadeAbortSignal;
-    }): Promise<ResourceLease<TextureHandle>>;
+/**
+ * A GPU a node can compute on, and the state that has to outlive one cook.
+ *
+ * This replaces `WebGLCapability`, which nothing implemented, nothing declared
+ * and no host installed — its one method was WebGL2-shaped, and keeping both
+ * names would have meant two devices in one page. Two devices cannot exchange
+ * a texture: an allocation made on one is not bindable, sampleable or copyable
+ * on the other, and the failure is a validation error at bind time rather than
+ * 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
+ * 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.
+ *
+ * The `GPUDevice` type comes from `@webgpu/types`, added to this package's
+ * `tsconfig.json` as its only `types` entry. Contracts compiles with
+ * `lib: ["ES2022"]` and no DOM on purpose — it is the vocabulary both hosts
+ * share, so pulling in the whole browser would let a browser-only type reach a
+ * portable definition by accident. A hand-written stub was the alternative and
+ * would have been worse than a dependency: it would shadow the genuine
+ * `GPUDevice` at the node's own call site, so every real method call would
+ * stop typechecking.
+ *
+ * The device is raw on purpose. A wrapped pipeline API would be a second thing
+ * to learn, would lag the spec, and would fight the reason to reach for WebGPU
+ * at all, which is that you write WGSL and encode passes. The capability wraps
+ * only what carries lifetime or identity, because those are the parts a host
+ * has to be able to account for.
+ */
+export interface GpuCapability {
+    /**
+     * The one device for this page. Shared by every node declaring `gpu`, which
+     * is the whole point — see the note above on why two would be useless.
+     */
+    readonly device: GPUDevice;
+    /**
+     * Who is actually rendering, recorded so a difference between two runs of
+     * the same graph is attributable rather than a mystery. WebGPU output can
+     * differ across adapters, and today there is no way to answer "which one".
+     */
+    readonly adapterInfo: Readonly<{
+        vendor: string;
+        architecture: string;
+        device: string;
+        description: string;
+    }>;
+    /** What this adapter will actually allow — `maxTextureDimension3D` and the
+     *  rest. Read at runtime rather than assumed; the 3D default is far below
+     *  the 2D one and a hard-coded guess would be wrong on some machines. */
+    readonly limits: Readonly<Record<string, number>>;
+    /**
+     * A resource that outlives one cook — a compiled pipeline, a sampler, a
+     * bind group layout. Keyed per node by the host, so two instances of one
+     * module do not share a cache entry and a module-level `Map` is never the
+     * 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
+     * that makes `architecture/module-state` keepable — it was previously
+     * forbidding the only available way to hold a pipeline.
+     */
+    cache<T>(key: string, create: (device: GPUDevice) => T, destroy?: (value: T) => void): T;
 }
 export interface ShellRunResult {
     readonly stdout: string;
@@ -102,7 +165,7 @@ export interface CapabilityMap {
     readonly assets: AssetCapability;
     readonly media: MediaCapability;
     readonly python: PythonCapability;
-    readonly webgl: WebGLCapability;
+    readonly gpu: GpuCapability;
     readonly shell: ShellCapability;
 }
 export type NodeCapabilityName = keyof CapabilityMap;

package/dist/contracts/definition.d.ts

@@ -1,10 +1,33 @@
 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" | "webgl" : "files" | "assets" | "media" | "python" | "shell";
+export type CapabilityForEnvironment<E extends RuntimeEnvironment> = E extends "portable" ? "assets" | "media" : E extends "browser" ? "assets" | "media" | "gpu" : "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;
@@ -57,6 +80,26 @@ export type PropDefinition<T extends PropDataType> = {
     readonly default: SerializableValueForType<T>;
     readonly label?: string;
     readonly description?: string;
+    /**
+     * An expression the prop starts with, so a node can come out of the box
+     * already moving — `sine-oscillator` and `ripple` baked in `$T` as dynamic
+     * nodes and shipped a static 0 once converted, which is what this restores.
+     * Marcus's decision, 2026-09-08, asked as a taste question about his own
+     * tool: a node like that should self-animate when dropped.
+     *
+     * **It is a default, so it loses to a stored value like any other.** A
+     * document that saved a plain number for this prop keeps that number and
+     * does not silently start animating on load. That is the mirror of the
+     * dropped-`params` fault: whatever the author set has to win, and the test
+     * for this asserts the losing case rather than the winning one.
+     *
+     * Applied only when the document stored nothing at all for the prop. It is a
+     * real expression once applied, not a hidden fallback — visible in the
+     * Inspector, editable, and deletable, which is how a stored expression
+     * already reads and the only version that does not lie about where the
+     * number came from.
+     */
+    readonly expression?: string;
 } & NumericMetadata<T> & AcceptMetadata<T> & SelectMetadata<T>;
 export type AnyPropDefinition = {
     [T in PropDataType]: PropDefinition<T>;
@@ -100,6 +143,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/schema.js

@@ -41,10 +41,13 @@ const dataProperties = {
 const data = object(dataProperties, ["kind", "type"]);
 const output = object({ kind: dataProperties.kind, type: dataProperties.type, description }, ["kind", "type"]);
 const { kind: _kind, variadic: _variadic, ...propProperties } = dataProperties;
-const prop = object({ ...propProperties, label: { type: "string" } }, [
-    "type",
-    "default",
-]);
+const prop = object({
+    ...propProperties,
+    label: { type: "string" },
+    // 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 },
+}, ["type", "default"]);
 function environmentCapabilities(runsOn, capabilities) {
     return {
         if: { properties: { runsOn: { const: runsOn } } },
@@ -72,7 +75,7 @@ export const nodeDefinitionSchema = {
     }, ["apiVersion", "runsOn"]),
     allOf: [
         environmentCapabilities("portable", ["assets", "media"]),
-        environmentCapabilities("browser", ["assets", "media", "webgl"]),
+        environmentCapabilities("browser", ["assets", "media", "gpu"]),
         environmentCapabilities("server", [
             "files",
             "assets",

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,16 +5,24 @@ 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"],
+    browser: ["assets", "media", "gpu"],
     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");
 const OUTPUT_FIELDS = fields("kind type description");
-const PROP_FIELDS = fields("type default label description min max step accept control options");
+const PROP_FIELDS = fields("type default label description min max step accept control options expression");
 function diagnostic(code, message, path) {
     return { phase: "definition", code: `definition/${code}`, message, path };
 }
@@ -186,6 +194,15 @@ export function validateNodeDefinition(value) {
                     !Number.isFinite(raw.step) ||
                     raw.step <= 0))
                 add("invalid-step", "step must be greater than zero", `${path}.step`);
+            if (section === "props" &&
+                "expression" in raw &&
+                (typeof raw.expression !== "string" || raw.expression.length === 0))
+                add("invalid-expression", "expression must be a non-empty string", `${path}.expression`);
+            for (const field of ["min", "max"]) {
+                if (field in raw &&
+                    (typeof raw[field] !== "number" || !Number.isFinite(raw[field])))
+                    add(`invalid-${field}`, `${field} must be a finite number`, `${path}.${field}`);
+            }
             if (typeof raw.min === "number" &&
                 typeof raw.max === "number" &&
                 raw.min > raw.max)