@field/cascade 0.4.0 → 0.5.2

package/dist/player/app.js

@@ -0,0 +1,810 @@
+// src/player/app.ts
+import {
+  CAMERA_DEFAULTS,
+  isScene,
+  sceneFromGeometry
+} from "@field/cascade/contracts";
+import { createBrowserRuntimeHost } from "@field/cascade/runtime/browser";
+import { renderScene } from "@field/cascade/runtime/render";
+import { createRuntime, PREFLIGHT_WARNING_CODES } from "@field/cascade/runtime";
+import { sceneBounds } from "@field/cascade/runtime/scene";
+import { installIoBridge } from "@field/cascade/io";
+
+// src/browser/gpu.ts
+import {
+  createGpuHost
+} from "@field/cascade/runtime";
+function createBrowserGpuHost() {
+  const gpu = globalThis.navigator?.gpu;
+  if (!gpu) return void 0;
+  return createGpuHost({
+    async acquire() {
+      const adapter = await gpu.requestAdapter();
+      if (!adapter) {
+        throw new Error(
+          "No WebGPU adapter is available \u2014 the browser reports WebGPU but the system offers no GPU to render on."
+        );
+      }
+      const device = await adapter.requestDevice();
+      const info = adapter.info;
+      return {
+        device,
+        info: {
+          vendor: info?.vendor ?? "",
+          architecture: info?.architecture ?? "",
+          device: info?.device ?? "",
+          description: info?.description ?? ""
+        },
+        limits: device.limits ?? adapter.limits
+      };
+    }
+  });
+}
+
+// src/player/assets.ts
+var DEFAULT_MAX_BYTES = 256 * 1024 * 1024;
+var DEFAULT_MAX_ENTRIES = 4096;
+var GENERATED_ROOT = ".cascade-player/generated";
+var PlayerAssetStore = class {
+  constructor(assets, options = {}) {
+    this.authored = /* @__PURE__ */ new Map();
+    this.generated = /* @__PURE__ */ new Map();
+    this.generatedByUrl = /* @__PURE__ */ new Map();
+    this.generatedBytes = 0;
+    this.sequence = 0;
+    this.disposed = false;
+    this.maxGeneratedBytes = finiteLimit(
+      options.maxGeneratedBytes,
+      DEFAULT_MAX_BYTES,
+      "maxGeneratedBytes"
+    );
+    this.maxGeneratedEntries = finiteLimit(
+      options.maxGeneratedEntries,
+      DEFAULT_MAX_ENTRIES,
+      "maxGeneratedEntries"
+    );
+    for (const [path, url] of Object.entries(assets)) {
+      const clean = cleanPath(path);
+      if (typeof url !== "string" || url.length === 0)
+        throw new TypeError(`Player asset ${clean} has no deployment URL`);
+      this.authored.set(clean, url);
+    }
+  }
+  async read(ref, options = {}) {
+    this.assertActive();
+    const path = cleanPath(typeof ref === "string" ? ref : ref.path);
+    if (typeof ref === "string") assertIdentityMediaOptions(path, options);
+    const signal = "signal" in options ? options.signal : void 0;
+    if (signal?.aborted) throw abortError(signal.reason);
+    const generated = this.generated.get(path);
+    if (generated) return generated.bytes.slice();
+    const url = this.authored.get(path);
+    if (!url) throw new Error(`Player asset not found: ${path}`);
+    const relay = signal ? relayAbort(signal) : void 0;
+    try {
+      const response = await fetch(url, {
+        ...relay ? { signal: relay.signal } : {}
+      });
+      if (!response.ok)
+        throw new Error(`Could not read player asset ${path} (${response.status})`);
+      return new Uint8Array(await response.arrayBuffer());
+    } finally {
+      relay?.dispose();
+    }
+  }
+  async write(first, second, third) {
+    this.assertActive();
+    const fromIo = typeof first === "string";
+    const data = fromIo ? second : first;
+    if (!(data instanceof Uint8Array))
+      throw new TypeError("Player asset writes require Uint8Array bytes");
+    const metadata = fromIo ? { suggestedName: first, mediaType: mediaTypeForName(first) } : second;
+    if (third?.signal.aborted) throw abortError(third.signal.reason);
+    const name = safeName(metadata.suggestedName);
+    const path = `${GENERATED_ROOT}/${String(++this.sequence).padStart(8, "0")}-${name}`;
+    const nextBytes = this.generatedBytes + data.byteLength;
+    const nextEntries = this.generated.size + 1;
+    if (nextBytes > this.maxGeneratedBytes) {
+      throw new Error(
+        `Player asset ${path} would use ${nextBytes} bytes; limit is ${this.maxGeneratedBytes} bytes`
+      );
+    }
+    if (nextEntries > this.maxGeneratedEntries) {
+      throw new Error(
+        `Player asset ${path} would use ${nextEntries} entries; limit is ${this.maxGeneratedEntries} entries`
+      );
+    }
+    const stored = data.slice();
+    this.generated.set(path, {
+      bytes: stored,
+      ...metadata.mediaType ? { mediaType: metadata.mediaType } : {},
+      leases: 0
+    });
+    this.generatedBytes = nextBytes;
+    return fromIo ? path : { path, ...metadata.mediaType ? { mediaType: metadata.mediaType } : {} };
+  }
+  url(path, options = {}) {
+    this.assertActive();
+    assertIdentityMediaOptions(path, options);
+    const clean = cleanPath(path);
+    const authored = this.authored.get(clean);
+    if (authored) return authored;
+    const generated = this.generated.get(clean);
+    if (!generated) throw new Error(`Player asset not found: ${clean}`);
+    if (!generated.objectUrl) {
+      generated.objectUrl = URL.createObjectURL(blobFor(generated));
+      this.generatedByUrl.set(generated.objectUrl, clean);
+    }
+    return generated.objectUrl;
+  }
+  async resolveUrl(ref) {
+    this.assertActive();
+    const path = cleanPath(ref.path);
+    const generated = this.generated.get(path);
+    if (!generated) {
+      const authored = this.authored.get(path);
+      if (!authored) throw new Error(`Player asset not found: ${path}`);
+      return { value: authored, release: () => {
+      } };
+    }
+    generated.leases += 1;
+    let value;
+    try {
+      value = this.url(path, { raw: true });
+    } catch (error) {
+      generated.leases -= 1;
+      throw error;
+    }
+    let released = false;
+    return {
+      value,
+      release: () => {
+        if (released) return;
+        released = true;
+        generated.leases = Math.max(0, generated.leases - 1);
+      }
+    };
+  }
+  /** Remove generated entries that no settled graph value or display lease owns. */
+  collect(roots) {
+    if (this.disposed) return;
+    const reachable = /* @__PURE__ */ new Set();
+    const seen = /* @__PURE__ */ new Set();
+    for (const root of roots)
+      visitPaths(root, reachable, seen, this.generated, this.generatedByUrl);
+    const errors = [];
+    for (const [path, entry] of this.generated) {
+      if (reachable.has(path) || entry.leases > 0) continue;
+      try {
+        this.drop(path, entry);
+      } catch (error) {
+        errors.push(error);
+      }
+    }
+    throwCollectedErrors(errors, "Player asset collection failed");
+  }
+  stats() {
+    return {
+      generatedBytes: this.generatedBytes,
+      generatedEntries: this.generated.size,
+      objectUrls: this.generatedByUrl.size
+    };
+  }
+  dispose() {
+    if (this.disposed) return;
+    this.disposed = true;
+    const errors = [];
+    for (const [path, entry] of this.generated) {
+      try {
+        this.drop(path, entry);
+      } catch (error) {
+        errors.push(error);
+      }
+    }
+    throwCollectedErrors(errors, "Player asset disposal failed");
+  }
+  drop(path, entry) {
+    try {
+      if (entry.objectUrl) URL.revokeObjectURL(entry.objectUrl);
+    } finally {
+      if (entry.objectUrl) this.generatedByUrl.delete(entry.objectUrl);
+      this.generated.delete(path);
+      this.generatedBytes -= entry.bytes.byteLength;
+    }
+  }
+  assertActive() {
+    if (this.disposed) throw new Error("Player asset store is disposed");
+  }
+};
+function finiteLimit(value, fallback, name) {
+  const resolved = value ?? fallback;
+  if (!Number.isSafeInteger(resolved) || resolved < 0)
+    throw new TypeError(`${name} must be a non-negative safe integer`);
+  return resolved;
+}
+function cleanPath(path) {
+  const clean = path.replace(/^\.\//, "").replace(/\\/g, "/");
+  if (!clean || clean.startsWith("/") || clean.split("/").some((part) => part === ".."))
+    throw new Error(`Invalid player asset path: ${path}`);
+  return clean;
+}
+function safeName(value) {
+  const source = (value?.trim() || "asset.bin").replace(/\\/g, "/").split("/").pop();
+  const safe = source.replace(/[^A-Za-z0-9._-]/g, "-").replace(/^\.+/, "");
+  return safe || "asset.bin";
+}
+function assertIdentityMediaOptions(path, options) {
+  if (options.width !== void 0 || options.format !== void 0 || options.quality !== void 0)
+    throw new Error(`Player asset transforms are unsupported for ${path}; request the raw asset`);
+}
+function blobFor(entry) {
+  return new Blob([entry.bytes.slice().buffer], {
+    type: entry.mediaType ?? "application/octet-stream"
+  });
+}
+function visitPaths(value, reachable, seen, generated, generatedByUrl) {
+  if (typeof value === "string") {
+    const path = value.replace(/^\.\//, "");
+    if (generated.has(path)) reachable.add(path);
+    else {
+      const generatedPath = generatedByUrl.get(value);
+      if (generatedPath) reachable.add(generatedPath);
+    }
+    return;
+  }
+  if (typeof value !== "object" || value === null) return;
+  if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer) return;
+  if (seen.has(value)) return;
+  seen.add(value);
+  if ("path" in value && typeof value.path === "string") {
+    const path = value.path.replace(/^\.\//, "");
+    if (generated.has(path)) reachable.add(path);
+  }
+  if (Array.isArray(value)) {
+    for (const item of value)
+      visitPaths(item, reachable, seen, generated, generatedByUrl);
+    return;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) return;
+  for (const item of Object.values(value))
+    visitPaths(item, reachable, seen, generated, generatedByUrl);
+}
+function relayAbort(signal) {
+  const controller = new AbortController();
+  const abort = () => controller.abort(signal.reason);
+  signal.addEventListener("abort", abort, { once: true });
+  if (signal.aborted) abort();
+  return {
+    signal: controller.signal,
+    dispose: () => signal.removeEventListener("abort", abort)
+  };
+}
+function abortError(reason) {
+  return reason instanceof Error ? reason : new Error(reason === void 0 ? "Aborted" : String(reason));
+}
+function mediaTypeForName(name) {
+  if (/\.png$/i.test(name)) return "image/png";
+  if (/\.svg$/i.test(name)) return "image/svg+xml";
+  if (/\.jpe?g$/i.test(name)) return "image/jpeg";
+  if (/\.webp$/i.test(name)) return "image/webp";
+  return void 0;
+}
+function throwCollectedErrors(errors, message) {
+  if (errors.length === 1) throw errors[0];
+  if (errors.length > 1) {
+    const combined = new Error(message);
+    Object.assign(combined, { errors });
+    throw combined;
+  }
+}
+
+// src/player/app.ts
+async function startPlayer(options) {
+  const cascadeDocument = options.document;
+  const hostDocument = options.root?.ownerDocument ?? globalThis.document;
+  const root = options.root ?? hostDocument.body;
+  if (!root) throw new Error("Cascade player needs a document body or explicit root");
+  const view = hostDocument.defaultView;
+  const initial = readInitialState(view?.location.href);
+  const ui = createUi(hostDocument, root);
+  let assets;
+  let disposeIo;
+  let gpu;
+  let runtime;
+  let graph;
+  try {
+    assets = new PlayerAssetStore(options.assets);
+    disposeIo = installIoBridge(assets);
+    gpu = createBrowserGpuHost();
+    const registrations = new Map(options.registrations.map((item) => [item.moduleId, item]));
+    runtime = createRuntime({
+      host: createBrowserRuntimeHost({
+        modules: { resolve: async (moduleId) => registrations.get(moduleId) ?? null },
+        assets,
+        ...gpu ? { gpu } : {},
+        report: (diagnostic) => {
+          if (diagnostic.phase === "run") ui.error.textContent = diagnostic.message;
+        }
+      }),
+      nodes: options.registrations
+    });
+    graph = await runtime.load(cascadeDocument);
+    const preflight = graph.preflight();
+    const blocking = preflight.find((diagnostic) => !PREFLIGHT_WARNING_CODES.has(diagnostic.code));
+    if (blocking) throw new Error(blocking.message);
+    const controller = new BrowserPlayer({
+      graph,
+      runtime,
+      gpu,
+      assets,
+      disposeIo,
+      root,
+      ui,
+      document: cascadeDocument,
+      initial
+    });
+    await controller.start();
+    return controller;
+  } catch (cause) {
+    const error = asError(cause);
+    ui.error.textContent = error.message;
+    ui.error.hidden = false;
+    try {
+      await cleanupAll([
+        () => graph?.dispose(),
+        () => runtime?.dispose(),
+        () => gpu?.dispose(),
+        () => disposeIo?.(),
+        () => assets?.dispose()
+      ]);
+    } catch (cleanupError) {
+      Object.assign(error, { cleanupError });
+    }
+    throw error;
+  }
+}
+var BrowserPlayer = class {
+  constructor(context) {
+    this.context = context;
+    this.listeners = /* @__PURE__ */ new Set();
+    this.controllerRoots = /* @__PURE__ */ new Map();
+    this.settledRoots = [];
+    this.commandTail = Promise.resolve();
+    this.playing = false;
+    this.playbackAnchor = { frame: 1, time: 0 };
+    this.disposed = false;
+    this.togglePlayback = () => {
+      if (this.playing) this.pause();
+      else this.play();
+    };
+    this.commitFrame = () => {
+      const frame = Number(this.context.ui.frame.value);
+      if (Number.isFinite(frame)) void this.seek(frame).catch((error) => this.fail(asError(error)));
+    };
+    this.selected = context.initial.output;
+    this.width = Math.max(1, context.root.clientWidth || 1280);
+    this.height = Math.max(1, context.root.clientHeight || 720);
+    this.frameWindow = context.root.ownerDocument.defaultView;
+    context.graph.setFrame(context.initial.frame);
+    context.graph.setFps(context.initial.fps);
+    context.ui.play.addEventListener("click", this.togglePlayback);
+    context.ui.frame.addEventListener("change", this.commitFrame);
+  }
+  async start() {
+    await this.cook(this.context.initial.frame);
+    if (this.context.initial.autoplay) this.play();
+  }
+  play() {
+    this.assertActive();
+    if (this.playing) return;
+    this.playing = true;
+    this.context.ui.play.textContent = "Pause";
+    this.emit({ type: "playing", playing: true });
+    this.playbackAnchor = { frame: this.context.graph.getFrame(), time: this.now() };
+    const tick = (time) => {
+      if (!this.playing || this.disposed) return;
+      const elapsed = Math.max(0, time - this.playbackAnchor.time);
+      const wanted = this.playbackAnchor.frame + elapsed * this.context.graph.getFps() / 1e3;
+      this.requestPlaybackFrame(wanted);
+      this.animationFrame = this.requestAnimationFrame(tick);
+    };
+    this.animationFrame = this.requestAnimationFrame(tick);
+  }
+  pause() {
+    if (!this.playing) return;
+    this.playing = false;
+    this.pendingPlaybackFrame = void 0;
+    if (this.animationFrame !== void 0) this.cancelAnimationFrame(this.animationFrame);
+    this.animationFrame = void 0;
+    this.context.ui.play.textContent = "Play";
+    this.emit({ type: "playing", playing: false });
+  }
+  seek(frame) {
+    requireFinite(frame, "frame");
+    return this.enqueue(async () => {
+      await this.cook(frame);
+      this.pendingPlaybackFrame = void 0;
+      this.playbackAnchor = { frame: this.context.graph.getFrame(), time: this.now() };
+    });
+  }
+  setInput(nodeId, name, value) {
+    return this.enqueue(async () => {
+      await this.context.graph.setInput(nodeId, name, value);
+      this.controllerRoots.set(`input\0${nodeId}\0${name}`, value);
+      await this.cook(this.context.graph.getFrame());
+    });
+  }
+  setProp(nodeId, name, value) {
+    return this.enqueue(async () => {
+      await this.context.graph.setProp(nodeId, name, value);
+      this.controllerRoots.set(`prop\0${nodeId}\0${name}`, value);
+      await this.cook(this.context.graph.getFrame());
+    });
+  }
+  getOutput(nodeId, port) {
+    this.assertActive();
+    return this.context.graph.getOutput(nodeId, port);
+  }
+  selectOutput(nodeId, port) {
+    return this.enqueue(async () => {
+      if (!this.context.graph.getOutputs(nodeId).has(port))
+        throw new Error(`Player output not found: ${nodeId}.${port}`);
+      const previous = this.selected;
+      this.selected = { nodeId, port };
+      try {
+        await this.display(this.context.graph.getOutput(nodeId, port));
+      } catch (cause) {
+        this.selected = previous;
+        const error = asError(cause);
+        this.fail(error);
+        throw error;
+      }
+      this.collect();
+    });
+  }
+  async downloadOutput() {
+    this.assertActive();
+    const value = this.currentOutput();
+    if (value instanceof Blob) return value;
+    if (isAssetRef(value)) {
+      const bytes = await this.context.assets.read(value, { signal: new AbortController().signal });
+      const mediaType = "mediaType" in value ? value.mediaType : void 0;
+      return new Blob([bytes.slice().buffer], { type: mediaType ?? mediaTypeForName(value.path) ?? "application/octet-stream" });
+    }
+    if (typeof value === "string") {
+      return new Blob([value], {
+        type: value.trimStart().startsWith("<svg") ? "image/svg+xml" : "text/plain;charset=utf-8"
+      });
+    }
+    if ((isGeometry(value) || isScene(value)) && this.displayedElement instanceof HTMLCanvasElement)
+      return canvasBlob(this.displayedElement);
+    if (value instanceof HTMLCanvasElement) return canvasBlob(value);
+    return new Blob([JSON.stringify(value, jsonReplacer, 2)], { type: "application/json" });
+  }
+  resize(width, height) {
+    requireFinite(width, "width");
+    requireFinite(height, "height");
+    this.width = Math.max(1, Math.round(width));
+    this.height = Math.max(1, Math.round(height));
+    void this.enqueue(async () => this.display(this.currentOutput())).catch((error) => this.fail(asError(error)));
+  }
+  subscribe(listener) {
+    this.assertActive();
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+  async dispose() {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.pause();
+    this.context.graph.cancel("Player disposed");
+    await this.commandTail.catch(() => {
+    });
+    await this.playbackCook?.catch(() => {
+    });
+    this.context.ui.play.removeEventListener("click", this.togglePlayback);
+    this.context.ui.frame.removeEventListener("change", this.commitFrame);
+    this.listeners.clear();
+    try {
+      await cleanupAll([
+        () => this.releaseDisplay(),
+        () => this.context.graph.dispose(),
+        () => this.context.runtime.dispose(),
+        () => this.context.gpu?.dispose(),
+        () => this.context.disposeIo(),
+        () => this.context.assets.dispose()
+      ]);
+    } finally {
+      this.context.root.replaceChildren();
+    }
+  }
+  enqueue(operation) {
+    this.assertActive();
+    const scheduled = this.commandTail.then(operation);
+    this.commandTail = scheduled.catch(() => {
+    });
+    return scheduled;
+  }
+  requestPlaybackFrame(frame) {
+    this.pendingPlaybackFrame = frame;
+    if (this.playbackCook) return;
+    this.playbackCook = this.enqueue(async () => {
+      const next = this.pendingPlaybackFrame;
+      this.pendingPlaybackFrame = void 0;
+      if (!this.disposed && this.playing && next !== void 0) await this.cook(next);
+    }).catch(() => {
+    }).finally(() => {
+      this.playbackCook = void 0;
+      if (this.playing && this.pendingPlaybackFrame !== void 0)
+        this.requestPlaybackFrame(this.pendingPlaybackFrame);
+    });
+  }
+  async cook(frame) {
+    this.assertActive();
+    let result;
+    try {
+      result = await this.context.graph.run({ frame, fps: this.context.graph.getFps() });
+      this.settledRoots = outputValues(result);
+      if (result.status !== "completed") throw resultError(result);
+      if (!this.selected) this.selected = preferredOutput(result);
+      if (this.selected && !result.outputs.get(this.selected.nodeId)?.has(this.selected.port))
+        throw new Error(`Player output not found: ${this.selected.nodeId}.${this.selected.port}`);
+      await this.display(this.currentOutput());
+      const effectiveFrame = this.context.graph.getFrame();
+      this.context.ui.frame.value = String(effectiveFrame);
+      this.context.ui.error.hidden = true;
+      this.context.ui.error.textContent = "";
+      this.emit({ type: "frame", frame: effectiveFrame });
+    } catch (cause) {
+      const error = asError(cause);
+      this.fail(error);
+      this.collect();
+      throw error;
+    }
+    this.collect();
+  }
+  currentOutput() {
+    return this.selected ? this.context.graph.getOutput(this.selected.nodeId, this.selected.port) : void 0;
+  }
+  async display(value) {
+    const output = this.context.ui.output;
+    let next;
+    let nextRelease;
+    const asset = isAssetRef(value) ? value : void 0;
+    if (asset || typeof value === "string" && value.trimStart().startsWith("<svg")) {
+      let url;
+      if (asset) {
+        const lease = await this.context.assets.resolveUrl(asset);
+        url = lease.value;
+        nextRelease = lease.release;
+      } else {
+        url = URL.createObjectURL(new Blob([value], { type: "image/svg+xml" }));
+        nextRelease = () => URL.revokeObjectURL(url);
+      }
+      try {
+        if (!asset || isImageAsset(asset)) {
+          const image = output.ownerDocument.createElement("img");
+          image.src = url;
+          image.alt = this.selected ? `${this.selected.nodeId}.${this.selected.port}` : asset ? "Cascade output" : "Cascade SVG output";
+          await image.decode();
+          next = image;
+        } else {
+          const link = output.ownerDocument.createElement("a");
+          link.href = url;
+          link.download = asset.path.split("/").pop() || "asset";
+          link.textContent = asset.path;
+          next = link;
+        }
+      } catch (error) {
+        await nextRelease();
+        throw error;
+      }
+    } else if (isScene(value) || isGeometry(value)) {
+      const scene = isScene(value) ? value : sceneFromGeometry(value);
+      next = renderSceneCanvas(output.ownerDocument, scene, this.width, this.height);
+    } else {
+      const pre = output.ownerDocument.createElement("pre");
+      pre.textContent = value === void 0 ? "No output" : JSON.stringify(value, jsonReplacer, 2);
+      next = pre;
+    }
+    try {
+      await this.releaseDisplay();
+    } catch (error) {
+      await nextRelease?.();
+      throw error;
+    }
+    if (next.tagName === "IMG" || next.tagName === "CANVAS") {
+      Object.assign(next.style, { display: "block", maxWidth: "100%", maxHeight: "100%", objectFit: "contain", minWidth: "0", minHeight: "0" });
+    }
+    output.replaceChildren(next);
+    this.displayedElement = next;
+    this.displayRelease = nextRelease;
+  }
+  async releaseDisplay() {
+    const release = this.displayRelease;
+    this.displayRelease = void 0;
+    this.displayedElement = void 0;
+    await release?.();
+  }
+  collect() {
+    this.context.assets.collect([
+      this.context.document,
+      ...this.controllerRoots.values(),
+      ...this.settledRoots
+    ]);
+  }
+  fail(error) {
+    this.pause();
+    this.context.ui.error.hidden = false;
+    this.context.ui.error.textContent = error.message;
+    this.emit({ type: "error", error });
+  }
+  emit(event) {
+    for (const listener of this.listeners) {
+      try {
+        listener(event);
+      } catch (error) {
+        console.error("Cascade player listener failed", error);
+      }
+    }
+  }
+  now() {
+    return this.frameWindow?.performance.now() ?? performance.now();
+  }
+  requestAnimationFrame(callback) {
+    if (this.frameWindow?.requestAnimationFrame)
+      return this.frameWindow.requestAnimationFrame(callback);
+    return globalThis.setTimeout(() => callback(this.now()), 16);
+  }
+  cancelAnimationFrame(handle) {
+    if (this.frameWindow?.cancelAnimationFrame) this.frameWindow.cancelAnimationFrame(handle);
+    else globalThis.clearTimeout(handle);
+  }
+  assertActive() {
+    if (this.disposed) throw new Error("Cascade player is disposed");
+  }
+};
+function createUi(hostDocument, root) {
+  root.replaceChildren();
+  root.dataset.cascadePlayer = "";
+  Object.assign(root.style, { display: "flex", flexDirection: "column", height: "100%", margin: "0", background: "#141414", color: "#eee", overflow: "hidden" });
+  const toolbar = hostDocument.createElement("div");
+  toolbar.dataset.cascadeControls = "";
+  Object.assign(toolbar.style, { display: "flex", gap: "8px", padding: "8px", flex: "none", alignItems: "center" });
+  const play = hostDocument.createElement("button");
+  play.type = "button";
+  play.textContent = "Play";
+  const frame = hostDocument.createElement("input");
+  frame.type = "number";
+  frame.step = "any";
+  frame.setAttribute("aria-label", "Frame");
+  frame.style.width = "100px";
+  const error = hostDocument.createElement("div");
+  error.dataset.cascadeError = "";
+  error.setAttribute("role", "alert");
+  error.hidden = true;
+  Object.assign(error.style, { padding: "8px", whiteSpace: "pre-wrap", overflow: "auto" });
+  const output = hostDocument.createElement("div");
+  output.dataset.cascadeOutput = "";
+  Object.assign(output.style, { display: "grid", placeItems: "center", flex: "1", minHeight: "0", minWidth: "0", overflow: "auto" });
+  toolbar.append(play, frame);
+  root.append(toolbar, error, output);
+  return { play, frame, error, output };
+}
+function renderSceneCanvas(hostDocument, scene, width, height) {
+  let canvas;
+  const camera = scene.camera ?? fitCamera(scene, width, height);
+  renderScene(scene.geometry, {
+    camera,
+    size: [width, height],
+    stroke: [1, 1, 1, 1],
+    strokeWidth: 1,
+    opacity: 1,
+    pointRadius: 1,
+    drawPoints: true,
+    surface: (surfaceWidth, surfaceHeight) => {
+      canvas = hostDocument.createElement("canvas");
+      canvas.width = surfaceWidth;
+      canvas.height = surfaceHeight;
+      return canvas;
+    }
+  });
+  return canvas;
+}
+function fitCamera(scene, width, height) {
+  const bounds = sceneBounds(scene);
+  if (!bounds) return { ...CAMERA_DEFAULTS, projection: "orthographic", resolution: [width, height] };
+  const centerX = ((bounds.min[0] ?? 0) + (bounds.max[0] ?? 0)) / 2;
+  const centerY = ((bounds.min[1] ?? 0) + (bounds.max[1] ?? 0)) / 2;
+  const maxZ = bounds.max[2] ?? 0;
+  const spanX = (bounds.max[0] ?? 0) - (bounds.min[0] ?? 0);
+  const spanY = (bounds.max[1] ?? 0) - (bounds.min[1] ?? 0);
+  const frameAspect = width / height;
+  return {
+    ...CAMERA_DEFAULTS,
+    translate: [centerX, centerY, maxZ + Math.max(spanX, spanY, 1)],
+    projection: "orthographic",
+    orthowidth: Math.max(spanX, spanY * frameAspect, 1) * 1.1,
+    resolution: [width, height]
+  };
+}
+function readInitialState(href) {
+  const query = new URL(href ?? "http://localhost/").searchParams;
+  const frame = finiteQuery(query.get("frame"), 1);
+  const fps = finiteQuery(query.get("fps"), 30);
+  const nodeId = query.get("outputNode");
+  const port = query.get("outputPort");
+  return {
+    frame,
+    fps,
+    autoplay: query.get("autoplay") === "1",
+    ...nodeId && port ? { output: { nodeId, port } } : {}
+  };
+}
+function finiteQuery(value, fallback) {
+  if (value === null || value.trim() === "") return fallback;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : fallback;
+}
+function preferredOutput(result) {
+  let fallback;
+  let preferred;
+  for (const [nodeId, outputs] of result.outputs) {
+    for (const [port, value] of outputs) {
+      fallback = { nodeId, port };
+      if (isAssetRef(value) || isScene(value) || isGeometry(value) || typeof value === "string" && value.trimStart().startsWith("<svg"))
+        preferred = { nodeId, port };
+    }
+  }
+  return preferred ?? fallback;
+}
+function outputValues(result) {
+  const values = [];
+  for (const outputs of result.outputs.values())
+    for (const value of outputs.values()) values.push(value);
+  return values;
+}
+function resultError(result) {
+  const details = result.diagnostics.map((diagnostic) => diagnostic.message).filter(Boolean);
+  return new Error(details.join("\n") || `Player cook ${result.status}`);
+}
+function isGeometry(value) {
+  return typeof value === "object" && value !== null && value.kind === "geometry";
+}
+function isAssetRef(value) {
+  return typeof value === "object" && value !== null && typeof value.path === "string";
+}
+function isImageAsset(value) {
+  if ("size" in value && Array.isArray(value.size)) return true;
+  if ("mediaType" in value && value.mediaType?.startsWith("image/")) return true;
+  return /\.(png|svg|jpe?g|webp|gif|avif)$/i.test(value.path);
+}
+function jsonReplacer(_key, value) {
+  return ArrayBuffer.isView(value) ? Array.from(value) : value;
+}
+function canvasBlob(canvas) {
+  return new Promise((resolve, reject) => {
+    canvas.toBlob((blob) => blob ? resolve(blob) : reject(new Error("Canvas produced no image")), "image/png");
+  });
+}
+async function cleanupAll(actions) {
+  const errors = [];
+  for (const action of actions) {
+    try {
+      await action();
+    } catch (error) {
+      errors.push(error);
+    }
+  }
+  throwCollectedErrors(errors, "Cascade player cleanup failed");
+}
+function requireFinite(value, label) {
+  if (!Number.isFinite(value)) throw new TypeError(`${label} must be finite`);
+}
+function asError(value) {
+  return value instanceof Error ? value : new Error(String(value));
+}
+export {
+  startPlayer
+};