@field/cascade 0.7.1 → 0.10.0

package/dist/cli/runtime/stage.ts

@@ -17,12 +17,52 @@
  * carries a project-relative path, never pixels.
  */
 
+export interface StageCallOptions {
+  /**
+   * Abandons the stage. In Studio the request is withdrawn — dropped if it is
+   * still queued for the worker, interrupted if it is running — and the call
+   * rejects at once, so a superseded cook stops costing anything the moment it
+   * is superseded rather than when the stage happens to finish.
+   *
+   * Optional: when it is absent the signal of the cook in flight is used (see
+   * `COOK_SIGNAL_KEY`), so a node that never heard of this still cancels.
+   */
+  readonly signal?: AbortSignal;
+}
+
 export interface StageBridge {
-  (stage: string, args: Record<string, unknown>): Promise<unknown>;
+  (stage: string, args: Record<string, unknown>, options?: StageCallOptions): Promise<unknown>;
 }
 
 const BRIDGE_KEY = '__cascadeStageBridge';
 
+/**
+ * Where the scheduler publishes the signal of the interactive cook in flight.
+ *
+ * On `globalThis` for the same reason as the bridge: every project module is
+ * compiled with its own copy of this file, so module state would not be shared
+ * with the scheduler that sets it. The interactive lane runs one node at a
+ * time, which is what makes a single ambient value correct: a stage started
+ * while node N cooks belongs to node N's cook. Read at call time, never later.
+ */
+export const COOK_SIGNAL_KEY = '__cascadeCookSignal';
+
+function ambientCookSignal(): AbortSignal | undefined {
+  const read = (globalThis as Record<string, unknown>)[COOK_SIGNAL_KEY];
+  if (typeof read !== 'function') return undefined;
+  const signal = (read as () => AbortSignal | null | undefined)();
+  return signal ?? undefined;
+}
+
+/** The rejection a withdrawn stage produces, recognisable without importing a
+ *  class across module copies. */
+function cancelledError(stage: string, signal: AbortSignal): Error {
+  const reason = signal.reason instanceof Error ? signal.reason.message : 'superseded';
+  const error = new Error(`stage "${stage}" was cancelled: ${reason}`);
+  error.name = 'AbortError';
+  return error;
+}
+
 /**
  * Install the local transport. Called by a host that can reach the filesystem —
  * the CLI does this before running a graph. Returns a disposer so a host can
@@ -71,20 +111,27 @@ async function capability(): Promise<string> {
   return token;
 }
 
-async function overHttp<T>(stage: string, args: Record<string, unknown>): Promise<T> {
+async function overHttp<T>(stage: string, args: Record<string, unknown>, signal?: AbortSignal): Promise<T> {
   const postStage = async () => fetch('/api/exec', {
     method: 'POST',
     headers: { 'Content-Type': 'application/json', 'X-Cascade-Exec-Capability': await capability() },
     body: JSON.stringify({ stage, args }),
+    signal,
   });
 
-  let response = await postStage();
-  if (response.status === 403) {
-    capabilityPromise = undefined;
+  let response: Response;
+  let body: { ok?: boolean; stdout?: string; stderr?: string; error?: string };
+  try {
     response = await postStage();
+    if (response.status === 403) {
+      capabilityPromise = undefined;
+      response = await postStage();
+    }
+    body = await response.json() as typeof body;
+  } catch (error) {
+    if (signal?.aborted) throw cancelledError(stage, signal);
+    throw error;
   }
-
-  const body = await response.json() as { ok?: boolean; stdout?: string; stderr?: string; error?: string };
   if (!response.ok || !body.ok) {
     throw new Error(`stage "${stage}" failed: ${body.stderr || body.error || 'unknown error'}`);
   }
@@ -113,16 +160,29 @@ export async function stageAvailable(): Promise<boolean> {
  * rather than a URL parse error from a fetch that was never going to work —
  * which is what this whole file exists to stop happening.
  */
-export async function runStage<T = unknown>(stage: string, args: Record<string, unknown> = {}): Promise<T> {
+export async function runStage<T = unknown>(
+  stage: string,
+  args: Record<string, unknown> = {},
+  options: StageCallOptions = {},
+): Promise<T> {
+  const signal = options.signal ?? ambientCookSignal();
+  if (signal?.aborted) throw cancelledError(stage, signal);
   const bridge = localBridge();
-  if (bridge) return await bridge(stage, args) as T;
+  if (bridge) {
+    try {
+      return await bridge(stage, args, signal ? { signal } : undefined) as T;
+    } catch (error) {
+      if (signal?.aborted) throw cancelledError(stage, signal);
+      throw error;
+    }
+  }
   if (typeof document === 'undefined') {
     throw new Error(
       `Cannot run stage "${stage}": no host bridge is installed and there is no page to post from. ` +
       'A headless host must call installStageBridge() from cascade/stage before executing the graph.',
     );
   }
-  return overHttp<T>(stage, args);
+  return overHttp<T>(stage, args, signal);
 }
 
 /** A scratch path for a node's output, scoped by node id so re-running a graph

package/dist/contracts/bundle.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Bundles: one port carrying a set of named fields.
+ *
+ * Marcus, 2026-10-10, looking at a graph where one node fanned out a dozen
+ * outputs wired everywhere: *"Instead of having these nodes with many different
+ * outputs (more than 3 or 4 outputs), can we just export some kind of JSON
+ * object, a sort of multi-object, instead of outputting 12 different outputs?"*
+ *
+ * A bundle value is a plain object of fields. Each field is any ordinary
+ * Cascade value; an image or a cache entry travels as its reference (an
+ * `ImageRef`, an `AssetRef`), never as pixels, so a bundle is as cheap to pass
+ * as the fields it names.
+ *
+ * What makes it more than `object`:
+ *
+ *   - a producer declares its fields (`fields: { dpi: "float", ... }`), so a
+ *     checker can name an unknown field and suggest the right one;
+ *   - an optional `schema` name (`format`, `signals`, `marks`) keeps two
+ *     unrelated bundles from being wired together;
+ *   - a consumer may declare the fields it reads (`fields: ["dpi"]`). It then
+ *     sees only those, and Studio re-cooks it only when one of them changed;
+ *   - expressions read a wired bundle's fields: `ch("format.dpi")`.
+ *
+ * Everything here is pure and dependency-free so the runtime, Studio and the
+ * CLI checker share one reading of the rules.
+ */
+import type { CascadeType } from "./values.js";
+/** A declared field: its type, or its type with words for whoever reads it. */
+export type BundleFieldDefinition = CascadeType | Readonly<{
+    type: CascadeType;
+    description?: string;
+}>;
+/** A producer's declaration: field name to type. */
+export type BundleFieldDefinitions = Readonly<Record<string, BundleFieldDefinition>>;
+export type Bundle = Readonly<Record<string, unknown>>;
+/** The type a field declaration names. */
+export declare function bundleFieldType(definition: BundleFieldDefinition | undefined): string;
+/** The description a field declaration carries, if any. */
+export declare function bundleFieldDescription(definition: BundleFieldDefinition | undefined): string | undefined;
+/**
+ * Whether two bundle ports may be wired. A port without a schema is generic and
+ * takes any bundle; two named schemas must agree.
+ */
+export declare function bundleSchemasCompatible(output: string | undefined, input: string | undefined): boolean;
+/** True for a value a bundle port can carry: a plain, non-array object. */
+export declare function isBundleValue(value: unknown): value is Bundle;
+/**
+ * A field path as an expression writes it: `format.dpi` is field `dpi` of the
+ * port `format`. Only the first dot splits, so a field name never needs
+ * escaping. Null when there is no dot to split on.
+ */
+export declare function splitBundlePath(name: string): {
+    port: string;
+    field: string;
+} | null;
+/**
+ * A bundle narrowed to the fields a consumer declared. A field the producer
+ * did not set is absent rather than `undefined`, the same as on the full value.
+ */
+export declare function selectBundleFields(value: unknown, fields: readonly string[]): Bundle | undefined;
+/**
+ * The closest candidate to a misspelt name, for "did you mean". Edit distance
+ * with a threshold that scales with the length, so `dpu` finds `dpi` and
+ * `colour` does not find `count`.
+ */
+export declare function suggestName(name: string, candidates: Iterable<string>): string | undefined;
+/** "unknown field X — did you mean Y? (fields: a, b, c)" */
+export declare function unknownFieldMessage(field: string, known: readonly string[], where: string): string;
+/**
+ * What is wrong with a value a producer committed to a bundle port, or null.
+ * With declared fields, every key must be declared; a declared field may be
+ * absent. Field types are not checked here; the runtime does that per type.
+ */
+export declare function bundleValueProblem(value: unknown, fields: BundleFieldDefinitions | undefined): string | null;
+//# sourceMappingURL=bundle.d.ts.map

package/dist/contracts/bundle.js

@@ -0,0 +1,112 @@
+/** The type a field declaration names. */
+export function bundleFieldType(definition) {
+    if (!definition)
+        return "any";
+    return typeof definition === "string" ? definition : definition.type;
+}
+/** The description a field declaration carries, if any. */
+export function bundleFieldDescription(definition) {
+    return typeof definition === "object" && definition ? definition.description : undefined;
+}
+/**
+ * Whether two bundle ports may be wired. A port without a schema is generic and
+ * takes any bundle; two named schemas must agree.
+ */
+export function bundleSchemasCompatible(output, input) {
+    return !output || !input || output === input;
+}
+/** True for a value a bundle port can carry: a plain, non-array object. */
+export function isBundleValue(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+/**
+ * A field path as an expression writes it: `format.dpi` is field `dpi` of the
+ * port `format`. Only the first dot splits, so a field name never needs
+ * escaping. Null when there is no dot to split on.
+ */
+export function splitBundlePath(name) {
+    const dot = name.indexOf(".");
+    if (dot <= 0 || dot === name.length - 1)
+        return null;
+    return { port: name.slice(0, dot), field: name.slice(dot + 1) };
+}
+/**
+ * A bundle narrowed to the fields a consumer declared. A field the producer
+ * did not set is absent rather than `undefined`, the same as on the full value.
+ */
+export function selectBundleFields(value, fields) {
+    if (!isBundleValue(value))
+        return value;
+    const selected = {};
+    for (const field of fields)
+        if (Object.prototype.hasOwnProperty.call(value, field))
+            selected[field] = value[field];
+    return Object.freeze(selected);
+}
+/**
+ * The closest candidate to a misspelt name, for "did you mean". Edit distance
+ * with a threshold that scales with the length, so `dpu` finds `dpi` and
+ * `colour` does not find `count`.
+ */
+export function suggestName(name, candidates) {
+    let best;
+    let bestDistance = Infinity;
+    const lower = name.toLowerCase();
+    for (const candidate of candidates) {
+        const distance = editDistance(lower, candidate.toLowerCase());
+        if (distance < bestDistance) {
+            best = candidate;
+            bestDistance = distance;
+        }
+    }
+    if (best === undefined)
+        return undefined;
+    const limit = Math.max(1, Math.floor(Math.max(name.length, best.length) / 3));
+    return bestDistance <= limit ? best : undefined;
+}
+/** "unknown field X — did you mean Y? (fields: a, b, c)" */
+export function unknownFieldMessage(field, known, where) {
+    const suggestion = suggestName(field, known);
+    return `${where} reads unknown bundle field "${field}"`
+        + (suggestion ? ` — did you mean "${suggestion}"?` : "")
+        + (known.length ? ` (fields: ${known.join(", ")})` : " (the bundle declares no fields)");
+}
+/**
+ * What is wrong with a value a producer committed to a bundle port, or null.
+ * With declared fields, every key must be declared; a declared field may be
+ * absent. Field types are not checked here; the runtime does that per type.
+ */
+export function bundleValueProblem(value, fields) {
+    if (value === undefined || value === null)
+        return null;
+    if (!isBundleValue(value))
+        return "a bundle must be a plain object of fields";
+    if (!fields)
+        return null;
+    const known = Object.keys(fields);
+    for (const key of Object.keys(value))
+        if (!Object.prototype.hasOwnProperty.call(fields, key)) {
+            const suggestion = suggestName(key, known);
+            return `sets undeclared bundle field "${key}"`
+                + (suggestion ? ` — did you mean "${suggestion}"?` : "")
+                + ` (declared: ${known.join(", ") || "none"})`;
+        }
+    return null;
+}
+function editDistance(a, b) {
+    const previous = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        let diagonal = previous[0];
+        previous[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const above = previous[j];
+            previous[j] = Math.min(previous[j] + 1, previous[j - 1] + 1, diagonal + (a[i - 1] === b[j - 1] ? 0 : 1));
+            diagonal = above;
+        }
+    }
+    return previous[b.length];
+}
+//# sourceMappingURL=bundle.js.map

package/dist/contracts/definition.d.ts

@@ -1,4 +1,5 @@
 import type { CapabilityMap, CascadeAbortSignal, NodeCapabilityName, ProgressReporter } from "./capabilities.js";
+import type { BundleFieldDefinition, BundleFieldDefinitions } from "./bundle.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" | "gpu" : E extends "browser" ? "assets" | "media" | "gpu" : "files" | "assets" | "media" | "python" | "shell" | "gpu";
@@ -70,6 +71,27 @@ type SelectMetadata<T extends CascadeType> = {
     readonly control: Extract<ControlFor<T>, "select">;
     readonly options?: readonly SelectOption<T>[];
 };
+/**
+ * Bundle ports name an optional `schema`, and declare fields from both ends:
+ * a producer declares what it carries (`fields: { dpi: "float" }`), a consumer
+ * the fields it reads (`fields: ["dpi"]`). A consumer that declares its fields
+ * sees only those and, in Studio, re-cooks only when one of them changed. See
+ * `bundle.ts`.
+ */
+type BundleInputMetadata<T extends CascadeType> = T extends "bundle" ? {
+    readonly schema?: string;
+    readonly fields?: readonly string[];
+} : {
+    readonly schema?: never;
+    readonly fields?: never;
+};
+type BundleOutputMetadata<T extends CascadeType> = T extends "bundle" ? {
+    readonly schema?: string;
+    readonly fields?: BundleFieldDefinitions;
+} : {
+    readonly schema?: never;
+    readonly fields?: never;
+};
 export interface TriggerInputDefinition {
     readonly kind: "trigger";
     readonly description?: string;
@@ -80,7 +102,7 @@ export type DataInputDefinition<T extends CascadeType> = {
     readonly default?: SerializableValueForType<T>;
     readonly description?: string;
     readonly variadic?: boolean;
-} & NumericMetadata<T> & AcceptMetadata<T> & SelectMetadata<T>;
+} & NumericMetadata<T> & AcceptMetadata<T> & SelectMetadata<T> & BundleInputMetadata<T>;
 export type InputDefinitionFor<E extends RuntimeEnvironment> = TriggerInputDefinition | {
     [T in DataTypeForEnvironment<E>]: DataInputDefinition<T>;
 }[DataTypeForEnvironment<E>];
@@ -88,11 +110,11 @@ export interface TriggerOutputDefinition {
     readonly kind: "trigger";
     readonly description?: string;
 }
-export interface DataOutputDefinition<T extends CascadeType> {
+export type DataOutputDefinition<T extends CascadeType> = {
     readonly kind: "data";
     readonly type: T;
     readonly description?: string;
-}
+} & BundleOutputMetadata<T>;
 export type OutputDefinitionFor<E extends RuntimeEnvironment> = TriggerOutputDefinition | {
     [T in DataTypeForEnvironment<E>]: DataOutputDefinition<T>;
 }[DataTypeForEnvironment<E>];
@@ -168,6 +190,14 @@ export interface NodeDefinitionForEnvironment<E extends RuntimeEnvironment> {
      */
     readonly container?: "subnet" | "feedback";
     readonly capabilities?: readonly CapabilityForEnvironment<E>[];
+    /**
+     * `live` marks a node that reads data from outside the graph — an archive,
+     * a CLI, a cache, body data, the filesystem or a network. `cascade export`
+     * never ships one: the author freezes it into a snapshot of chosen values or
+     * the export fails. Server nodes and nodes declaring `files`, `python` or
+     * `shell` are treated as live whether or not they say so.
+     */
+    readonly source?: "live";
     readonly label?: string;
     readonly description?: string;
     readonly icon?: string;
@@ -191,11 +221,32 @@ export interface TriggerEvent {
     }>;
 }
 type Entries<D, K extends "inputs" | "outputs" | "props"> = D extends Record<K, infer R> ? R : Record<never, never>;
-type InputValue<I> = I extends TriggerInputDefinition ? TriggerEvent | undefined : I extends DataInputDefinition<infer T> ? I extends {
+/** The value a declared bundle field holds. */
+type BundleFieldValue<F> = F extends CascadeType ? ValueForType<F> : F extends {
+    readonly type: infer T extends CascadeType;
+} ? ValueForType<T> : unknown;
+/** A bundle output's value, typed from its declared fields. Every field is
+ *  optional: a producer may leave one unset, and a consumer then reads none. */
+type BundleOutputValue<O> = O extends {
+    readonly fields: infer F extends Readonly<Record<string, BundleFieldDefinition>>;
+} ? {
+    readonly [K in keyof F]?: BundleFieldValue<F[K]>;
+} : Readonly<Record<string, unknown>>;
+/** A bundle input's value: only the declared fields, when it declares any. */
+type BundleInputValue<I> = I extends {
+    readonly fields: readonly (infer K extends string)[];
+} ? {
+    readonly [P in K]?: unknown;
+} : Readonly<Record<string, unknown>>;
+type InputValue<I> = I extends TriggerInputDefinition ? TriggerEvent | undefined : I extends DataInputDefinition<"bundle"> ? I extends {
+    readonly default: unknown;
+} ? BundleInputValue<I> : BundleInputValue<I> | undefined : I extends DataInputDefinition<infer T> ? I extends {
     readonly variadic: true;
 } ? readonly ValueForType<T>[] : "default" extends keyof I ? ValueForType<T> : ValueForType<T> | undefined : never;
 type OutputValue<O> = O extends TriggerOutputDefinition ? {
     trigger(payload?: JsonValue): void;
+} : O extends DataOutputDefinition<"bundle"> ? {
+    set(value: BundleOutputValue<O>): void;
 } : O extends DataOutputDefinition<infer T> ? {
     set(value: ValueForType<T>): void;
 } : never;
@@ -228,6 +279,18 @@ export interface NodeExecutionContext<D extends NodeDefinition> {
     readonly capabilities: DeclaredCapabilities<D>;
     readonly signal: CascadeAbortSignal;
     readonly progress: ProgressReporter;
+    /**
+     * This node's seed, derived from the graph's `seed` and the node id
+     * (`nodeSeed` in `@cascade/runtime`). Every host computes it the same way,
+     * so a seeded node draws the same thing headless and in Studio. Pass it on
+     * to anything random, including a Python stage's args.
+     */
+    readonly seed: number;
+    /**
+     * A stream of floats in [0, 1) seeded with `seed`, starting afresh at every
+     * cook. Use it instead of `Math.random`, which no host can reproduce.
+     */
+    readonly random: () => number;
 }
 export type NodeExecute<D extends NodeDefinition = NodeDefinition> = (context: NodeExecutionContext<D>) => void | Promise<void>;
 export {};

package/dist/contracts/document.d.ts

@@ -1,3 +1,4 @@
+import type { EditorDeclaration } from "./editor.js";
 import type { SerializableValue } from "./values.js";
 export interface CascadeDocumentNode {
     readonly id: string;
@@ -54,6 +55,34 @@ export interface CascadeDocument {
     readonly nodes: readonly CascadeDocumentNode[];
     readonly annotations?: readonly CascadeDocumentAnnotation[];
     readonly connections?: readonly CascadeDocumentConnection[];
+    /** The shareable editor this graph declares; ignored by the runtime. See `editor.ts`. */
+    readonly editor?: EditorDeclaration;
+    /**
+     * The graph seed, an unsigned 32-bit integer; 0 when absent. Each node's
+     * `context.seed` is derived from it and the node id, so changing it
+     * reshuffles every seeded node at once.
+     */
+    readonly seed?: number;
+    /** The timeline the graph is played and rendered over. See `TimelineSettings`. */
+    readonly timeline?: TimelineSettings;
+}
+/**
+ * The frame rate, range and looping a graph is made for, saved with it.
+ *
+ * Without it every graph opened at 30 fps and frames 1-250, and a piece made
+ * for 24 fps over 594 frames (cloud-wall's H1 flipbook) had to be set up by
+ * hand on every open. Studio's timeline reads and writes it, the runtime takes
+ * its `fps` as the graph's own rate, and `cascade run --frames timeline`
+ * renders `start`-`end`. Every field is optional; absent ones keep the
+ * defaults (30 fps, 1-250, looping).
+ */
+export interface TimelineSettings {
+    readonly fps?: number;
+    /** First frame, inclusive. */
+    readonly start?: number;
+    /** Last frame, inclusive. */
+    readonly end?: number;
+    readonly loop?: boolean;
 }
 export interface CascadePreset {
     readonly version: 1;

package/dist/contracts/editor.d.ts

@@ -0,0 +1,172 @@
+import type { SelectOption } from "./definition.js";
+import type { JsonValue } from "./values.js";
+/**
+ * The shareable editor a graph declares: which parameters someone else may
+ * change, which outputs they may export, the presets they may start from, and
+ * the assets that are allowed to leave the project with it.
+ *
+ * It sits beside `nodes` in the document, like Houdini's parameter interface on
+ * a digital asset sits beside its network. The runtime ignores it: a published
+ * parameter is an ordinary prop with a label, so a headless render, Studio and
+ * the exported editor cook the same graph. Only `cascade export`, the editor
+ * shell and scene files read it.
+ *
+ * Everything here is an allowlist. A parameter, output or asset that is not
+ * named does not reach the exported site, and a scene file carries values for
+ * named parameters only. That is the boundary a share relies on: an export is
+ * the selected subgraph plus the selected assets, never the project.
+ */
+export interface EditorDeclaration {
+    /** Stable identity of the editor, written into every scene. `cloud-type`. */
+    readonly id: string;
+    readonly title?: string;
+    readonly description?: string;
+    /** Group names in display order. Groups not listed follow, in first-use order. */
+    readonly groups?: readonly string[];
+    readonly parameters?: readonly PublishedParameter[];
+    readonly outputs?: readonly PublishedOutput[];
+    readonly presets?: readonly EditorPreset[];
+    /**
+     * Project-relative files the author selects to ship. Literal asset values of
+     * published parameters are included too; nothing else is. A path inside a
+     * `licensed/` directory, a hidden file, or a gitignored file is refused.
+     */
+    readonly assets?: readonly string[];
+    /**
+     * Data-source nodes replaced by a snapshot of chosen values. A live source
+     * (server, files, Python, shell or a `source: "live"` definition) still wired
+     * into the exported subgraph fails the export.
+     */
+    readonly freeze?: readonly FrozenSource[];
+    /** Optional project panel module that extends or replaces the generated UI. */
+    readonly panel?: EditorPanelDeclaration;
+    /** The read-only stage view. On unless the author turns it off. */
+    readonly inspect?: boolean;
+    /**
+     * Parameter ids a phone keeps in reach at the bottom sheet's lowest snap
+     * point (the text, a Reroll). Defaults to the first text and seed parameters.
+     */
+    readonly peek?: readonly string[];
+    /**
+     * Values cooked while a slider is being dragged on a phone, for a quicker
+     * preview: a lower density, say. They never enter a scene or an export, and
+     * the real values cook again on release.
+     */
+    readonly draft?: Readonly<Record<string, JsonValue>>;
+}
+export type PublishedControl = "number" | "slider" | "int" | "bool" | "select" | "text" | "textarea" | "color" | "file" | "seed" | "vec2";
+export interface PublishedParameter {
+    /** Scene key. Stable across renames of the node or the prop it targets. */
+    readonly id: string;
+    /** The node and prop whose value this parameter sets. */
+    readonly node: string;
+    readonly prop: string;
+    readonly label?: string;
+    readonly group?: string;
+    readonly order?: number;
+    readonly help?: string;
+    readonly unit?: string;
+    /** Overrides the control the prop's type implies. */
+    readonly control?: PublishedControl;
+    readonly min?: number;
+    readonly max?: number;
+    readonly step?: number;
+    readonly options?: readonly SelectOption<"string">[] | readonly SelectOption<"float">[];
+    /** File parameters: accepted extensions or media types (`.otf`, `image/*`). */
+    readonly accept?: readonly string[];
+    /**
+     * File parameters: whether a dropped file may travel inside a scene.
+     * `never` keeps it to a name and a hash (licensed fonts); `auto` embeds files
+     * up to 2 MB. Dropped files never leave the viewer's browser otherwise.
+     */
+    readonly embed?: "never" | "auto";
+    /** Shown only when other parameters have these values; a list must all hold. */
+    readonly visibleWhen?: VisibleWhen | readonly VisibleWhen[];
+}
+export type VisibleWhen = Readonly<{
+    param: string;
+    equals?: JsonValue;
+    in?: readonly JsonValue[];
+    not?: readonly JsonValue[];
+}>;
+export type PublishedOutputFormat = "png" | "svg" | "json" | "text";
+export interface PublishedOutput {
+    readonly id: string;
+    readonly node: string;
+    readonly port: string;
+    readonly label?: string;
+    readonly format: PublishedOutputFormat;
+    /** Download name; `{id}` and `{scene}` are replaced. */
+    readonly filename?: string;
+    /** Published parameter ids shown beside this output's button (dpi, ground). */
+    readonly parameters?: readonly string[];
+    /** The output shown in the viewer. One output should set it. */
+    readonly view?: boolean;
+}
+export interface EditorPreset {
+    readonly id: string;
+    readonly label: string;
+    /** Published parameter id to value. Missing parameters take their defaults. */
+    readonly values: Readonly<Record<string, JsonValue>>;
+    /** Parameters the preset leaves as they are (colour, pen) instead of resetting them. */
+    readonly keep?: readonly string[];
+}
+export interface FrozenSource {
+    /** The live node the snapshot replaces. Everything upstream of it is dropped. */
+    readonly node: string;
+    readonly output: string;
+    /** Project-relative snapshot written by `cascade freeze`. */
+    readonly snapshot: string;
+}
+export interface EditorPanelDeclaration {
+    /** Project-relative module exporting `mount(target, api)`. */
+    readonly module: string;
+    /** `extend` (default) mounts it above the generated parameters. */
+    readonly placement?: "extend" | "replace";
+}
+/** What `cascade freeze` writes: exactly the chosen values, nothing else. */
+export interface FrozenSnapshot {
+    readonly format: "cascade.frozen";
+    readonly version: 1;
+    readonly node: string;
+    readonly output: string;
+    readonly fields: readonly string[];
+    /** Fields the author marked as personal, flagged in every export plan. */
+    readonly personal?: readonly string[];
+    readonly value: JsonValue;
+    /** Project-relative files the value refers to, copied beside the snapshot. */
+    readonly files?: readonly string[];
+    readonly frozenAt: string;
+}
+/**
+ * A scene: what someone changed in an editor, as a file that opens onto the
+ * same graph in Studio, the CLI or the exported editor.
+ *
+ * It holds published parameter values and the files the person dropped, and
+ * nothing from the project. Version mismatches degrade: unknown parameters are
+ * ignored with a warning, missing ones take the graph's defaults.
+ */
+export interface CascadeScene {
+    readonly format: "cascade.scene";
+    readonly version: 1;
+    readonly graph: Readonly<{
+        id: string;
+        version: string;
+    }>;
+    readonly name?: string;
+    readonly values: Readonly<Record<string, JsonValue>>;
+    /** Files for `file` parameters, by parameter id. */
+    readonly files?: Readonly<Record<string, SceneFile>>;
+    readonly savedAt?: string;
+}
+export interface SceneFile {
+    readonly name: string;
+    readonly mediaType?: string;
+    readonly size: number;
+    /** Hex SHA-256 of the bytes, to match a file the receiver already has. */
+    readonly sha256: string;
+    /** Base64 bytes, present only when the parameter allows embedding. */
+    readonly data?: string;
+}
+export declare const SCENE_EMBED_LIMIT: number;
+//# sourceMappingURL=editor.d.ts.map

package/dist/contracts/editor.js

@@ -0,0 +1,2 @@
+export const SCENE_EMBED_LIMIT = 2 * 1024 * 1024;
+//# sourceMappingURL=editor.js.map

package/dist/contracts/index.d.ts

@@ -1,9 +1,11 @@
 export * from "./animation.js";
+export * from "./bundle.js";
 export * from "./camera.js";
 export * from "./capabilities.js";
 export * from "./color.js";
 export * from "./definition.js";
 export * from "./document.js";
+export * from "./editor.js";
 export * from "./geometry.js";
 export * from "./particles.js";
 export * from "./scene.js";

package/dist/contracts/index.js

@@ -1,9 +1,11 @@
 export * from "./animation.js";
+export * from "./bundle.js";
 export * from "./camera.js";
 export * from "./capabilities.js";
 export * from "./color.js";
 export * from "./definition.js";
 export * from "./document.js";
+export * from "./editor.js";
 export * from "./geometry.js";
 export * from "./particles.js";
 export * from "./scene.js";