@field/cascade 0.2.22 → 0.3.0

package/dist/io.js

@@ -0,0 +1,303 @@
+// server/src/runtime/io.ts
+function mediaUrl(path, options = {}) {
+  if (/^(https?:|data:|blob:)/.test(path)) return path;
+  const clean = path.replace(/^\.?\//, "");
+  const encoded = clean.split("/").map(encodeURIComponent).join("/");
+  const params = new URLSearchParams();
+  if (options.raw) params.set("raw", "1");
+  else {
+    if (options.width) params.set("w", String(options.width));
+    if (options.format) params.set("fmt", options.format);
+    if (options.quality) params.set("q", String(options.quality));
+  }
+  const query = params.toString();
+  return `/api/media/${encoded}${query ? `?${query}` : ""}`;
+}
+var IO_BRIDGE_KEY = "__cascadeIoBridge";
+function installIoBridge(bridge) {
+  const globals = globalThis;
+  const previous = globals[IO_BRIDGE_KEY];
+  globals[IO_BRIDGE_KEY] = bridge ?? void 0;
+  return () => {
+    globals[IO_BRIDGE_KEY] = previous;
+  };
+}
+function localIo() {
+  const bridge = globalThis[IO_BRIDGE_KEY];
+  return bridge && typeof bridge.read === "function" && typeof bridge.write === "function" ? bridge : null;
+}
+async function loadBytes(path, options = { raw: true }) {
+  const bridge = localIo();
+  if (bridge) {
+    const bytes = await bridge.read(path, options);
+    const exact = bytes.byteOffset === 0 && bytes.byteLength === bytes.buffer.byteLength ? bytes.buffer : bytes.slice().buffer;
+    return exact;
+  }
+  const response = await fetch(mediaUrl(path, options));
+  if (!response.ok) throw new Error(`cascade/io: cannot load ${path} (${response.status})`);
+  return await response.arrayBuffer();
+}
+async function loadImage(path, options = { raw: true }) {
+  const image = new Image();
+  const bridge = localIo();
+  if (bridge) {
+    image.src = new Uint8Array(await loadBytes(path, options));
+  } else {
+    image.crossOrigin = "anonymous";
+    image.src = mediaUrl(path, options);
+  }
+  await image.decode();
+  return image;
+}
+async function loadBitmap(path, options = { raw: true }) {
+  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());
+}
+async function loadFieldBitmap(path, options = {}) {
+  return loadBitmap(path, { ...options, raw: false });
+}
+async function saveImage(source, path, options = {}) {
+  const format = options.format ?? "png";
+  const type = `image/${format}`;
+  let blob;
+  if (source instanceof Blob) {
+    blob = source;
+  } else if (typeof source.convertToBlob === "function") {
+    blob = await source.convertToBlob({ type, quality: options.quality });
+  } else if (typeof source.encode === "function") {
+    blob = new Blob([await source.encode(format, options.quality)], { type });
+  } else if (typeof source.toBuffer === "function") {
+    blob = new Blob([source.toBuffer(type)], { type });
+  } else {
+    blob = await new Promise((resolve, reject) => {
+      source.toBlob(
+        (result) => result ? resolve(result) : reject(new Error("cascade/io: canvas produced no data")),
+        type,
+        options.quality
+      );
+    });
+  }
+  return saveBytes(blob, path);
+}
+async function saveBytes(data, path) {
+  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" },
+    body: data
+  });
+  if (!response.ok) {
+    throw new Error(`cascade/io: cannot write ${path} \u2014 ${await response.text()}`);
+  }
+  const result = await response.json();
+  return result.path;
+}
+function cachePath(nodeId, suffix) {
+  const safe = nodeId.replace(/[^a-zA-Z0-9_-]/g, "_");
+  return `.cascade-cache/${safe}${suffix}`;
+}
+function parseNpyHeader(buffer) {
+  const bytes = new Uint8Array(buffer);
+  const magic = String.fromCharCode(...bytes.subarray(0, 6));
+  if (magic !== "\x93NUMPY") throw new Error("cascade/io: not a .npy file");
+  const view = new DataView(buffer);
+  const major = bytes[6];
+  const headerLength = major >= 2 ? view.getUint32(8, true) : view.getUint16(8, true);
+  const headerStart = major >= 2 ? 12 : 10;
+  const header = String.fromCharCode(...bytes.subarray(headerStart, headerStart + headerLength));
+  const dtype = header.match(/'descr':\s*'([^']+)'/)?.[1];
+  if (!dtype) throw new Error("cascade/io: .npy header has no dtype");
+  const shape = (header.match(/'shape':\s*\(([^)]*)\)/)?.[1] ?? "").split(",").map((part) => part.trim()).filter(Boolean).map(Number);
+  return {
+    dtype,
+    shape,
+    dataOffset: headerStart + headerLength,
+    fortran: /'fortran_order':\s*True/.test(header)
+  };
+}
+async function loadFloats(path) {
+  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");
+  if (header.shape.length < 2) throw new Error(`cascade/io: expected an image-shaped array, got ${header.shape.length}D`);
+  const [height, width] = header.shape;
+  const channels = header.shape.length > 2 ? header.shape.slice(2).reduce((a, b) => a * b, 1) : 1;
+  const count = width * height * channels;
+  let data;
+  if (header.dtype === "<f4" || header.dtype === "=f4") {
+    data = new Float32Array(buffer, header.dataOffset, count);
+  } else {
+    const source = readAs(buffer, header.dataOffset, header.dtype, count);
+    data = source instanceof Float32Array ? source : Float32Array.from(source);
+  }
+  return { data, size: [width, height], channels };
+}
+function readAs(buffer, offset, dtype, count) {
+  switch (dtype) {
+    case "<f8":
+    case "=f8":
+      return new Float64Array(buffer, offset, count);
+    case "|u1":
+    case "<u1":
+    case "=u1":
+    case "|b1":
+      return new Uint8Array(buffer, offset, count);
+    case "|i1":
+      return new Int8Array(buffer, offset, count);
+    case "<i2":
+      return new Int16Array(buffer, offset, count);
+    case "<u2":
+      return new Uint16Array(buffer, offset, count);
+    case "<i4":
+      return new Int32Array(buffer, offset, count);
+    case "<u4":
+      return new Uint32Array(buffer, offset, count);
+    default:
+      throw new Error(`cascade/io: .npy dtype ${dtype} is not supported`);
+  }
+}
+function encodeNpy(data, shape) {
+  const dict = `{'descr': '<f4', 'fortran_order': False, 'shape': (${shape.join(", ")}${shape.length === 1 ? "," : ""}), }`;
+  const unpadded = 10 + dict.length + 1;
+  const padding = (64 - unpadded % 64) % 64;
+  const header = dict + " ".repeat(padding) + "\n";
+  const out = new Uint8Array(10 + header.length + data.byteLength);
+  const view = new DataView(out.buffer);
+  out.set([147, 78, 85, 77, 80, 89, 1, 0], 0);
+  view.setUint16(8, header.length, true);
+  for (let i = 0; i < header.length; i++) out[10 + i] = header.charCodeAt(i);
+  out.set(new Uint8Array(data.buffer, data.byteOffset, data.byteLength), 10 + header.length);
+  return out;
+}
+async function saveFloats(image, path) {
+  const [width, height] = image.size;
+  const shape = image.channels > 1 ? [height, width, image.channels] : [height, width];
+  return saveBytes(encodeNpy(image.data, shape), path);
+}
+function toImageData(image, range = [0, 1]) {
+  const [width, height] = image.size;
+  const [low, high] = range;
+  const span = high - low || 1;
+  const out = new Uint8ClampedArray(width * height * 4);
+  for (let i = 0; i < width * height; i++) {
+    const base = i * image.channels;
+    const r = (image.data[base] - low) / span * 255;
+    const g = image.channels > 1 ? (image.data[base + 1] - low) / span * 255 : r;
+    const b = image.channels > 2 ? (image.data[base + 2] - low) / span * 255 : r;
+    const a = image.channels > 3 ? image.data[base + 3] * 255 : 255;
+    out[i * 4] = r;
+    out[i * 4 + 1] = g;
+    out[i * 4 + 2] = b;
+    out[i * 4 + 3] = a;
+  }
+  return new ImageData(out, width, height);
+}
+function uploadFloatTexture(gl, image) {
+  const [width, height] = image.size;
+  const formats = {
+    1: [gl.R32F, gl.RED],
+    2: [gl.RG32F, gl.RG],
+    3: [gl.RGB32F, gl.RGB],
+    4: [gl.RGBA32F, gl.RGBA]
+  };
+  const pair = formats[image.channels];
+  if (!pair) throw new Error(`cascade/io: ${image.channels} channels has no texture format`);
+  const [internalFormat, format] = pair;
+  const texture = gl.createTexture();
+  gl.bindTexture(gl.TEXTURE_2D, texture);
+  gl.pixelStorei(gl.UNPACK_ALIGNMENT, 1);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+  gl.texImage2D(gl.TEXTURE_2D, 0, internalFormat, width, height, 0, format, gl.FLOAT, image.data);
+  return texture;
+}
+async function textureFromImage(gl, image, options = { raw: true }) {
+  const path = typeof image === "string" ? image : image.path;
+  if (path.endsWith(".npy")) {
+    const floats = await loadFloats(path);
+    return {
+      gl,
+      texture: uploadFloatTexture(gl, floats),
+      size: floats.size,
+      channels: floats.channels,
+      float: true
+    };
+  }
+  const bitmap = await loadBitmap(path, options);
+  const texture = gl.createTexture();
+  gl.bindTexture(gl.TEXTURE_2D, texture);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+  gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, bitmap);
+  const size = [bitmap.width, bitmap.height];
+  bitmap.close();
+  return { gl, texture, size, channels: 4, float: false };
+}
+function createTexture(gl, size, options = {}) {
+  const [width, height] = size;
+  const float = options.float ?? false;
+  const channels = options.channels ?? 4;
+  const texture = gl.createTexture();
+  gl.bindTexture(gl.TEXTURE_2D, texture);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+  gl.texStorage2D(gl.TEXTURE_2D, 1, float ? gl.RGBA32F : gl.RGBA8, width, height);
+  return { gl, texture, size, channels, float };
+}
+async function textureToImage(ref, path, options = {}) {
+  const { gl, size } = ref;
+  const [width, height] = size;
+  const framebuffer = gl.createFramebuffer();
+  gl.bindFramebuffer(gl.FRAMEBUFFER, framebuffer);
+  gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, ref.texture, 0);
+  try {
+    if (ref.float) {
+      const pixels2 = new Float32Array(width * height * 4);
+      gl.readPixels(0, 0, width, height, gl.RGBA, gl.FLOAT, pixels2);
+      const stored2 = await saveFloats({ data: pixels2, size, channels: 4 }, path.replace(/\.[^.]+$/, "") + ".npy");
+      return { path: stored2, size, channels: "rgba", depth: "f32", space: options.space ?? "linear" };
+    }
+    const pixels = new Uint8ClampedArray(width * height * 4);
+    gl.readPixels(0, 0, width, height, gl.RGBA, gl.UNSIGNED_BYTE, pixels);
+    const canvas = new OffscreenCanvas(width, height);
+    canvas.getContext("2d").putImageData(new ImageData(pixels, width, height), 0, 0);
+    const format = options.format ?? "png";
+    const stored = await saveImage(canvas, path, { format });
+    return { path: stored, size, channels: "rgba", depth: "u8", space: options.space ?? "srgb" };
+  } finally {
+    gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+    gl.deleteFramebuffer(framebuffer);
+  }
+}
+export {
+  cachePath,
+  createTexture,
+  installIoBridge,
+  loadBitmap,
+  loadBytes,
+  loadFieldBitmap,
+  loadFloats,
+  loadImage,
+  mediaUrl,
+  saveBytes,
+  saveFloats,
+  saveImage,
+  textureFromImage,
+  textureToImage,
+  toImageData,
+  uploadFloatTexture
+};
+//# sourceMappingURL=io.js.map

package/dist/net.d.ts

@@ -0,0 +1 @@
+export declare function authorizedFetch(credential: string, url: string, init?: RequestInit): Promise<Response>;

package/dist/net.js

@@ -0,0 +1,28 @@
+// server/src/runtime/net.ts
+var capability = null;
+async function authorizedFetch(credential, url, init = {}) {
+  capability ??= fetch("/api/net/capability").then(async (response2) => {
+    if (!response2.ok) throw new Error(`Authorized fetch capability failed: HTTP ${response2.status}`);
+    return (await response2.json()).capability;
+  });
+  const headers = Object.fromEntries(new Headers(init.headers).entries());
+  const response = await fetch("/api/net", {
+    method: "POST",
+    headers: { "Content-Type": "application/json", "X-Cascade-Net-Capability": await capability },
+    body: JSON.stringify({
+      credential,
+      url,
+      method: init.method ?? "GET",
+      headers,
+      ...typeof init.body === "string" ? { body: init.body } : {}
+    }),
+    signal: init.signal
+  });
+  const result = await response.json();
+  if (!response.ok || !result.ok) throw new Error(result.error ?? `Authorized fetch failed: HTTP ${response.status}`);
+  return new Response(result.body, { status: result.status, statusText: result.statusText, headers: result.headers });
+}
+export {
+  authorizedFetch
+};
+//# sourceMappingURL=net.js.map

package/dist/runtime/animation/channel.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Keyframe channels, neutral runtime.
+ *
+ * A channel is the third way a parameter becomes a value, beside a literal and
+ * an expression. It is an ordered list of keys and a rule for what happens
+ * between them, and it is sampled — never pushed. The host asks for the value
+ * at a frame; nothing here holds a clock, a graph or a node, which is what
+ * keeps the whole thing deterministic and testable on its own.
+ *
+ * `sin($T)` and a drawn curve are the same shape: one written, one drawn.
+ *
+ * Every function here is pure. A channel is treated as immutable — `setKey`
+ * and `deleteKey` return a new channel rather than editing one in place — so a
+ * caller can hold a channel across a cook without it changing underneath.
+ */
+/**
+ * What happens between a key and the next one. The mode belongs to the key on
+ * the LEFT of a segment: it describes how the value leaves that key.
+ *
+ *   constant — hold the left value until the next key. Steps, not motion
+ *   linear   — straight line. Constant velocity, visible corners at the keys
+ *   smooth   — Hermite with automatic tangents. The default, because linear
+ *              everywhere is how animation looks when nobody chose
+ */
+export type Interpolation = "constant" | "linear" | "smooth";
+/** Smooth, deliberately: an unset default of `linear` animates like a robot. */
+export declare const DEFAULT_INTERPOLATION: Interpolation;
+export declare function isInterpolation(value: unknown): value is Interpolation;
+/** One key. `frame` may be fractional; `value` is a plain number. */
+export interface Keyframe {
+    readonly frame: number;
+    readonly value: number;
+    readonly interpolation: Interpolation;
+}
+/** A key as a caller may hand it in — interpolation optional. */
+export interface KeyframeInput {
+    readonly frame: number;
+    readonly value: number;
+    readonly interpolation?: Interpolation | string;
+}
+/**
+ * An animated parameter. `keys` is always sorted by frame and holds at most
+ * one key per frame — `createChannel` is the only way that invariant is
+ * established, and every other function here preserves it.
+ */
+export interface Channel {
+    readonly keys: readonly Keyframe[];
+}
+/** The empty channel. Sampling it returns undefined, so a caller falls back. */
+export declare const EMPTY_CHANNEL: Channel;
+/**
+ * Build a channel from keys in any order, with anything unusable dropped.
+ *
+ * Unordered input is sorted rather than rejected — a file edited by hand and a
+ * UI that appends are both legitimate sources. A duplicate frame keeps the
+ * LAST key given, which is what "set this key again" means.
+ */
+export declare function createChannel(keys?: readonly KeyframeInput[]): Channel;
+export declare function isChannel(value: unknown): value is Channel;
+/** A channel with no keys resolves to nothing, so the raw value still applies. */
+export declare function isEmptyChannel(channel: Channel | null | undefined): boolean;
+export declare function keyAt(channel: Channel, frame: number): Keyframe | undefined;
+/**
+ * Set a key, replacing any key already on that frame.
+ *
+ * Re-keying an existing frame keeps that key's interpolation unless a new one
+ * is given: dragging a value should not silently change its easing.
+ */
+export declare function setKey(channel: Channel | null | undefined, frame: number, value: number, interpolation?: Interpolation): Channel;
+/** Remove the key on that frame. Removing the last key leaves an empty channel. */
+export declare function deleteKey(channel: Channel | null | undefined, frame: number): Channel;
+/** Change one key's outgoing interpolation without touching its value. */
+export declare function setKeyInterpolation(channel: Channel | null | undefined, frame: number, interpolation: Interpolation): Channel;
+/**
+ * The value at any frame, fractional included.
+ *
+ * Returns undefined for a channel with no keys — that is the signal to fall
+ * back to the parameter's raw value rather than to invent a zero.
+ *
+ * Outside the key range the end values are HELD, in both directions. No
+ * extrapolation: a curve that keeps climbing past its last key is never what
+ * anyone meant, and it is the failure that is hardest to see in a render.
+ */
+export declare function sampleChannel(channel: Channel | null | undefined, frame: number): number | undefined;
+/**
+ * The on-disk form. Interpolation is omitted when it is the default, so a
+ * plain channel reads as `{ "keys": [{ "frame": 1, "value": 0 }] }` and a diff
+ * shows easing changes rather than noise.
+ *
+ * Structurally identical to `CascadeSerializedChannel` in the contracts
+ * package, which is where the document shape is declared. It is restated here
+ * so this module keeps depending on nothing.
+ */
+export interface SerializedKeyframe {
+    frame: number;
+    value: number;
+    interpolation?: Interpolation;
+}
+export interface SerializedChannel {
+    keys: SerializedKeyframe[];
+}
+export declare function serializeChannel(channel: Channel | null | undefined): SerializedChannel | undefined;
+/**
+ * Read a channel back. Anything unrecognised yields the empty channel rather
+ * than an exception — a bad channel in one parameter must not fail a load.
+ */
+export declare function deserializeChannel(data: unknown): Channel;
+//# sourceMappingURL=channel.d.ts.map

package/dist/runtime/animation/channel.js

@@ -0,0 +1,204 @@
+/**
+ * Keyframe channels, neutral runtime.
+ *
+ * A channel is the third way a parameter becomes a value, beside a literal and
+ * an expression. It is an ordered list of keys and a rule for what happens
+ * between them, and it is sampled — never pushed. The host asks for the value
+ * at a frame; nothing here holds a clock, a graph or a node, which is what
+ * keeps the whole thing deterministic and testable on its own.
+ *
+ * `sin($T)` and a drawn curve are the same shape: one written, one drawn.
+ *
+ * Every function here is pure. A channel is treated as immutable — `setKey`
+ * and `deleteKey` return a new channel rather than editing one in place — so a
+ * caller can hold a channel across a cook without it changing underneath.
+ */
+/** Smooth, deliberately: an unset default of `linear` animates like a robot. */
+export const DEFAULT_INTERPOLATION = "smooth";
+const INTERPOLATIONS = ["constant", "linear", "smooth"];
+export function isInterpolation(value) {
+    return typeof value === "string" && INTERPOLATIONS.includes(value);
+}
+/** The empty channel. Sampling it returns undefined, so a caller falls back. */
+export const EMPTY_CHANNEL = Object.freeze({ keys: Object.freeze([]) });
+/**
+ * Build a channel from keys in any order, with anything unusable dropped.
+ *
+ * Unordered input is sorted rather than rejected — a file edited by hand and a
+ * UI that appends are both legitimate sources. A duplicate frame keeps the
+ * LAST key given, which is what "set this key again" means.
+ */
+export function createChannel(keys = []) {
+    const byFrame = new Map();
+    for (const key of keys) {
+        if (!key)
+            continue;
+        const frame = Number(key.frame);
+        const value = Number(key.value);
+        if (!Number.isFinite(frame) || !Number.isFinite(value))
+            continue;
+        byFrame.set(frame, {
+            frame,
+            value,
+            interpolation: isInterpolation(key.interpolation) ? key.interpolation : DEFAULT_INTERPOLATION
+        });
+    }
+    const sorted = [...byFrame.values()].sort((a, b) => a.frame - b.frame);
+    return { keys: sorted };
+}
+export function isChannel(value) {
+    return !!value && typeof value === "object" && Array.isArray(value.keys);
+}
+/** A channel with no keys resolves to nothing, so the raw value still applies. */
+export function isEmptyChannel(channel) {
+    return !channel || channel.keys.length === 0;
+}
+export function keyAt(channel, frame) {
+    return channel.keys.find(key => key.frame === frame);
+}
+/**
+ * Set a key, replacing any key already on that frame.
+ *
+ * Re-keying an existing frame keeps that key's interpolation unless a new one
+ * is given: dragging a value should not silently change its easing.
+ */
+export function setKey(channel, frame, value, interpolation) {
+    const base = channel ?? EMPTY_CHANNEL;
+    if (!Number.isFinite(frame) || !Number.isFinite(value))
+        return createChannel(base.keys);
+    const existing = keyAt(base, frame);
+    const mode = interpolation ?? existing?.interpolation ?? DEFAULT_INTERPOLATION;
+    const kept = base.keys.filter(key => key.frame !== frame);
+    return createChannel([...kept, { frame, value, interpolation: mode }]);
+}
+/** Remove the key on that frame. Removing the last key leaves an empty channel. */
+export function deleteKey(channel, frame) {
+    const base = channel ?? EMPTY_CHANNEL;
+    return createChannel(base.keys.filter(key => key.frame !== frame));
+}
+/** Change one key's outgoing interpolation without touching its value. */
+export function setKeyInterpolation(channel, frame, interpolation) {
+    const base = channel ?? EMPTY_CHANNEL;
+    const existing = keyAt(base, frame);
+    if (!existing)
+        return createChannel(base.keys);
+    return setKey(base, frame, existing.value, interpolation);
+}
+/**
+ * The value at any frame, fractional included.
+ *
+ * Returns undefined for a channel with no keys — that is the signal to fall
+ * back to the parameter's raw value rather than to invent a zero.
+ *
+ * Outside the key range the end values are HELD, in both directions. No
+ * extrapolation: a curve that keeps climbing past its last key is never what
+ * anyone meant, and it is the failure that is hardest to see in a render.
+ */
+export function sampleChannel(channel, frame) {
+    if (!channel || channel.keys.length === 0)
+        return undefined;
+    const keys = channel.keys;
+    if (!Number.isFinite(frame))
+        return keys[0].value;
+    if (keys.length === 1)
+        return keys[0].value;
+    if (frame <= keys[0].frame)
+        return keys[0].value;
+    if (frame >= keys[keys.length - 1].frame)
+        return keys[keys.length - 1].value;
+    const i = segmentIndex(keys, frame);
+    const k0 = keys[i];
+    const k1 = keys[i + 1];
+    const span = k1.frame - k0.frame;
+    if (span <= 0)
+        return k1.value;
+    const t = (frame - k0.frame) / span;
+    switch (k0.interpolation) {
+        case "constant":
+            return k0.value;
+        case "linear":
+            return k0.value + (k1.value - k0.value) * t;
+        case "smooth":
+        default:
+            return hermite(keys, i, t, span);
+    }
+}
+/** Index of the key at or before `frame`, binary searched. */
+function segmentIndex(keys, frame) {
+    let lo = 0;
+    let hi = keys.length - 1;
+    while (lo < hi) {
+        const mid = (lo + hi + 1) >> 1;
+        if (keys[mid].frame <= frame)
+            lo = mid;
+        else
+            hi = mid - 1;
+    }
+    return Math.min(lo, keys.length - 2);
+}
+/**
+ * Cubic Hermite across segment `i`, with tangents derived from the neighbours.
+ *
+ * There are no tangent handles yet — that is the curve editor, and it is the
+ * largest single piece of UI in the plan. Until it exists the tangents are
+ * automatic, in the way both Houdini and After Effects pick them by default:
+ *
+ *   - a key with a neighbour on each side takes the central difference, which
+ *     is what makes velocity continuous through a key rather than kinked
+ *   - the first and last key are FLAT, so a two-key smooth channel eases in
+ *     and out. This is the behaviour people mean by "smooth"; a straight line
+ *     between two keys would be indistinguishable from linear
+ *   - a constant segment next door flattens the tangent it touches, so a hold
+ *     does not make the neighbouring curve bulge to reach it
+ */
+function hermite(keys, i, t, span) {
+    const k0 = keys[i];
+    const k1 = keys[i + 1];
+    const m0 = tangent(keys, i, "out");
+    const m1 = tangent(keys, i + 1, "in");
+    const t2 = t * t;
+    const t3 = t2 * t;
+    const h00 = 2 * t3 - 3 * t2 + 1;
+    const h10 = t3 - 2 * t2 + t;
+    const h01 = -2 * t3 + 3 * t2;
+    const h11 = t3 - t2;
+    return h00 * k0.value + h10 * span * m0 + h01 * k1.value + h11 * span * m1;
+}
+/** Value change per frame at key `i`, seen from the segment on `side`. */
+function tangent(keys, i, side) {
+    const prev = keys[i - 1];
+    const next = keys[i + 1];
+    if (!prev || !next)
+        return 0;
+    // A hold on either side means the curve arrives, or leaves, level.
+    if (side === "out" && prev.interpolation === "constant")
+        return 0;
+    if (side === "in" && keys[i].interpolation === "constant")
+        return 0;
+    const span = next.frame - prev.frame;
+    if (span <= 0)
+        return 0;
+    return (next.value - prev.value) / span;
+}
+export function serializeChannel(channel) {
+    if (isEmptyChannel(channel))
+        return undefined;
+    return {
+        keys: channel.keys.map(key => (key.interpolation === DEFAULT_INTERPOLATION
+            ? { frame: key.frame, value: key.value }
+            : { frame: key.frame, value: key.value, interpolation: key.interpolation }))
+    };
+}
+/**
+ * Read a channel back. Anything unrecognised yields the empty channel rather
+ * than an exception — a bad channel in one parameter must not fail a load.
+ */
+export function deserializeChannel(data) {
+    if (!data || typeof data !== "object")
+        return EMPTY_CHANNEL;
+    const keys = data.keys;
+    if (!Array.isArray(keys))
+        return EMPTY_CHANNEL;
+    return createChannel(keys);
+}
+//# sourceMappingURL=channel.js.map