@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/state/stillStage.ts

@@ -0,0 +1,330 @@
+// An editor stage kept offscreen, that stills are drawn on: the hosted MCP
+// surface's `screenshot_shot` (plan C4), and the board's app-drawn stills
+// (stillThumbs.ts) on both lanes.
+//
+// A still of a saved Project is drawn the way the storyboard's "Frame from
+// Shot" is: the stage's own `captureFrame` (bridge v32), which flips into
+// export framing, snapshots the frame in the draw and scales it. The author's
+// stage is never used for it: loading another document there would swap what
+// they are looking at. This stage is its own `/shot-stage.html`, served as the
+// author's is (hosted, under the Service Worker, so the Project's components
+// import), and connected with handlers that ignore everything but its
+// readiness.
+//
+// ONE PER TAB, because each stage is a WebGL context. Hosted, the code host
+// owns it (browser-host boot.ts), feeds its loads the module epochs, and lends
+// it to the chrome through `DailiesHost.captureStill`; it is never the stage
+// `stageLoaded` tracks and reloads. Locally the chrome opens its own
+// (`tabStillStage`), whose loads need nothing: Vite serves the modules.
+//
+// Offscreen, never hidden: a `display: none` frame does not render, and the
+// capture waits on a drawn frame. It is closed after `idleMs` without a
+// capture, freeing its GPU context.
+//
+// The stage says it is ready ONCE, when its canvas comes up with the first
+// document, and never for a later `loadDoc`. So a stage is kept only for the
+// Project it opened on, at that size: the next still of it loads the newer
+// document and captures (the capture waits on its own drawn frame), and a
+// still of another Project, or at another size, opens a fresh stage.
+//
+// Every await on the stage races its reload (stageWatchdog.ts): a reload kills
+// the realm the bridge's promises live in, and one that never settled would
+// hold the queue for good. A capture abandoned through its signal rejects and
+// keeps the stage; a first document still coming up keeps coming up for the
+// next capture.
+//
+// A BACKGROUND capture (a thumbnail) steps aside for any other: it is refused
+// while another waits, and abandoned when one arrives, so a relayed agent
+// still never queues behind thumbnails (store mcpRelay.ts gives it 90 s).
+import type { Doc3D } from "@dailies-studio/shot/doc";
+import { connectStage } from "../bridge.js";
+import type { ShotBridgeHandlers, ShotStageBridge, ShotStageInfo } from "../bridgeTypes.js";
+import { dailiesHost } from "../hostApi.js";
+import { raceStage } from "./stageWatchdog.js";
+
+export interface StillStageDeps {
+  readonly document: Document;
+  /** After each load of the stage document: says whether the stage may be
+   *  connected (false: it is being reloaded, and the next load follows).
+   *  Hosted, it posts the module epoch and checks the Service Worker controls
+   *  the document; locally it answers true. */
+  loaded(stage: Window): boolean;
+  readonly idleMs?: number;
+  /** How long a loaded document may take to come up on the stage. */
+  readonly readyMs?: number;
+}
+
+export interface StillCaptureOptions {
+  /** Default png. */
+  readonly format?: "png" | "webp";
+  /** Abandons the capture: it rejects, and the stage is kept. */
+  readonly signal?: AbortSignal;
+  /** Steps aside for any other capture: refused while one waits, abandoned
+   *  when one arrives. Either way it rejects with `stillYielded` true. */
+  readonly background?: boolean;
+}
+
+export interface StillStage {
+  /** One still of `doc` at master `frame`, `width` by `height`. One at a
+   *  time. */
+  capture(doc: Doc3D, frame: number, width: number, height: number, options?: StillCaptureOptions): Promise<Blob>;
+}
+
+/** Whether a capture rejected because it stepped aside for another. A shape
+ *  test, since the error may come from another realm. */
+export function stillYielded(error: unknown): boolean {
+  return typeof error === "object" && error !== null && (error as { yielded?: unknown }).yielded === true;
+}
+
+const yieldedError = (): Error => Object.assign(new Error("the still stepped aside for another capture"), { yielded: true });
+
+const CANCELLED = "the still was cancelled";
+
+// `still=1`: the stage measures its canvas by hand while the page is hidden
+// (StageApp's `measureWhenHidden`), where no ResizeObserver is delivered.
+const STAGE_URL = "/shot-stage.html?theme=dark&still=1";
+
+interface Open {
+  readonly iframe: HTMLIFrameElement;
+  readonly bridge: ShotStageBridge;
+  /** False once the stage document reloaded: its bridge is dead. */
+  live: boolean;
+  /** The first document's readiness, null before the first load. */
+  shown: Promise<void> | null;
+  /** Settled by the stage's next `onReady` or `onError`. */
+  next: { ready: (info: ShotStageInfo) => void; failed: (message: string) => void } | null;
+}
+
+/** `work`, or a rejection once `signal` aborts. */
+function orCancelled<T>(work: Promise<T>, signal: AbortSignal): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const onAbort = (): void => reject(new Error(CANCELLED));
+    signal.addEventListener("abort", onAbort, { once: true });
+    if (signal.aborted) onAbort();
+    work.then(resolve, reject).finally(() => signal.removeEventListener("abort", onAbort));
+  });
+}
+
+/** How long a loaded document may take to come up on the still stage. Long
+ *  enough for a glyph face the page is still baking (the stage holds its
+ *  readiness until the face loads), and inside the object's wait for a
+ *  capture (store mcpRelay.ts RELAY_CAPTURE_TIMEOUT_MS), so this names the
+ *  stall rather than the object timing the call out. */
+export const STILL_READY_MS = 75_000;
+
+export function createStillStage(deps: StillStageDeps): StillStage {
+  const idleMs = deps.idleMs ?? 60_000;
+  const readyMs = deps.readyMs ?? STILL_READY_MS;
+  let open: Promise<Open> | null = null;
+  /** What the open stage was opened for (`keyOf`). */
+  let openKey = "";
+  let queue: Promise<unknown> = Promise.resolve();
+  let idle: ReturnType<typeof setTimeout> | undefined;
+  /** Captures that are not background, queued or running. */
+  let others = 0;
+  /** Background captures, queued or running, each abandoned when another
+   *  capture arrives. */
+  const yielding = new Set<{ controller: AbortController; yielded: boolean }>();
+  const keyOf = (doc: Doc3D): string => `${doc.id}:${doc.size.width}x${doc.size.height}`;
+
+  function close(): void {
+    const closing = open;
+    open = null;
+    void closing?.then(
+      (held) => {
+        // A reloaded stage's bridge belongs to a dead realm.
+        try {
+          held.bridge.dispose();
+        } catch {}
+        held.iframe.remove();
+      },
+      () => {},
+    );
+  }
+
+  async function start(width: number, height: number, reloaded: (held: Open) => void): Promise<Open> {
+    const iframe = deps.document.createElement("iframe");
+    iframe.title = "Dailies still stage";
+    iframe.tabIndex = -1;
+    iframe.setAttribute("aria-hidden", "true");
+    Object.assign(iframe.style, {
+      position: "fixed",
+      left: "-100000px",
+      top: "0",
+      width: `${width}px`,
+      height: `${height}px`,
+      border: "0",
+      pointerEvents: "none",
+    });
+    const loaded = new Promise<void>((resolve) => {
+      const onLoad = (): void => {
+        const stage = iframe.contentWindow;
+        if (stage === null || !deps.loaded(stage)) return;
+        iframe.removeEventListener("load", onLoad);
+        resolve();
+      };
+      iframe.addEventListener("load", onLoad);
+    });
+    iframe.src = STAGE_URL;
+    deps.document.body.appendChild(iframe);
+    try {
+      await loaded;
+      const held: { next: Open["next"] } = { next: null };
+      // Every handler but readiness is the author's chrome's business.
+      const handlers = new Proxy({} as ShotBridgeHandlers, {
+        get: (_target, key) =>
+          key === "onReady"
+            ? (info: ShotStageInfo) => held.next?.ready(info)
+            : key === "onError"
+              ? (message: string) => held.next?.failed(message)
+              : () => {},
+      });
+      const bridge = await connectStage(iframe, handlers);
+      const out: Open = {
+        iframe,
+        bridge,
+        live: true,
+        shown: null,
+        get next() {
+          return held.next;
+        },
+        set next(value) {
+          held.next = value;
+        },
+      };
+      // Any later load is a reload (a Vite full reload, a crashed document).
+      iframe.addEventListener("load", () => {
+        out.live = false;
+        reloaded(out);
+      });
+      return out;
+    } catch (error) {
+      iframe.remove();
+      throw error;
+    }
+  }
+
+  async function captureNow(
+    doc: Doc3D,
+    frame: number,
+    width: number,
+    height: number,
+    format: "png" | "webp",
+    signal: AbortSignal,
+  ): Promise<Blob> {
+    // Abandoned while it waited its turn: the stage is not touched.
+    if (signal.aborted) throw new Error(CANCELLED);
+    clearTimeout(idle);
+    if (open !== null && openKey !== keyOf(doc)) close();
+    if (open === null) {
+      const opening = start(doc.size.width, doc.size.height, () => {
+        if (open === opening) close();
+      });
+      open = opening;
+      openKey = keyOf(doc);
+      // One that failed to open is not kept, even when the capture that
+      // opened it was abandoned and no longer waits on it.
+      opening.catch(() => {
+        if (open === opening) open = null;
+      });
+    }
+    const opened = open;
+    try {
+      const held = await orCancelled(opened, signal);
+      const watch = {
+        stage: () => (held.live ? held.bridge : null),
+        bridgeAtStart: held.bridge,
+        signal,
+        reloaded: "the still stage reloaded while it drew",
+        cancelled: CANCELLED,
+      };
+      try {
+        if (held.shown === null) {
+          held.shown = new Promise<void>((resolve, reject) => {
+            const timer = setTimeout(
+              () => settle(new Error(`the stage did not show the Project within ${readyMs / 1000} s`)),
+              readyMs,
+            );
+            const settle = (error?: Error): void => {
+              clearTimeout(timer);
+              held.next = null;
+              if (error === undefined) resolve();
+              else reject(error);
+            };
+            held.next = { ready: () => settle(), failed: (message) => settle(new Error(message)) };
+          });
+          // A first document that never came up closes the stage, also when
+          // its capture was abandoned: the next still opens a fresh one
+          // rather than inheriting this failure.
+          held.shown.catch(() => {
+            if (open === opened) close();
+          });
+        }
+        // The newer document lands before the capture, which waits on a
+        // frame drawn from it. Before the first has shown, it is the one the
+        // stage comes up with.
+        held.bridge.loadDoc(doc);
+        await raceStage(held.shown, watch);
+        return await raceStage(held.bridge.captureFrame({ frame, width, height, format, signal }), watch);
+      } catch (error) {
+        // A stage that failed is not kept for the next still. One abandoned
+        // is.
+        if (!signal.aborted && open === opened) close();
+        throw error;
+      }
+    } finally {
+      idle = setTimeout(close, idleMs);
+    }
+  }
+
+  return {
+    capture(doc, frame, width, height, options = {}) {
+      const background = options.background === true;
+      if (background && others > 0) return Promise.reject(yieldedError());
+      const controller = new AbortController();
+      const outer = options.signal;
+      const forward = (): void => controller.abort();
+      if (outer?.aborted === true) controller.abort();
+      else outer?.addEventListener("abort", forward, { once: true });
+      const mine = { controller, yielded: false };
+      if (background) {
+        yielding.add(mine);
+      } else {
+        others += 1;
+        for (const other of yielding) {
+          other.yielded = true;
+          other.controller.abort();
+        }
+      }
+      const run = queue
+        .then(() => captureNow(doc, frame, width, height, options.format ?? "png", controller.signal))
+        .catch((error: unknown) => {
+          throw mine.yielded ? yieldedError() : error;
+        })
+        .finally(() => {
+          outer?.removeEventListener("abort", forward);
+          if (background) yielding.delete(mine);
+          else others -= 1;
+        });
+      queue = run.catch(() => {});
+      return run;
+    },
+  };
+}
+
+let tabStage: StillStage | undefined;
+
+/**
+ * This tab's still stage. Hosted, the code host's, because a stage the chrome
+ * opened itself would import none of the Project's modules. Locally, the
+ * chrome's own, opened on first use.
+ */
+export function tabStillStage(): StillStage {
+  if (tabStage !== undefined) return tabStage;
+  const host = dailiesHost();
+  tabStage =
+    host === undefined
+      ? createStillStage({ document, loaded: () => true })
+      : { capture: host.captureStill.bind(host) };
+  return tabStage;
+}