@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/state/sketchGuide.ts

@@ -0,0 +1,51 @@
+// "GUIDE: SKETCH N" (the Brief, schema v44): one storyboard sketch as the
+// plain shapes bridge v47 carries, so the stage draws it as dashed outlines
+// over the camera frame without any storyboard code of its own. Pure.
+import { findSketch, sketchCardOf } from "@dailies-studio/shot/doc";
+import type { Doc3D } from "@dailies-studio/shot/doc";
+import { framesToSeconds } from "@dailies-studio/engine";
+import type { ShotSketchGuide, ShotSketchGuideRect } from "../bridgeTypes.js";
+import { formatDuration } from "../panels/timeline/model.js";
+
+/** A box's corner on the stage, the sketch's own `radius` (sketch.ts). */
+const BOX_RADIUS = 8;
+/** A text item's chip says its words, cut to fit a chip. */
+const TEXT_CHIP_MAX = 24;
+
+function clip(text: string): string {
+  const one = text.replace(/\s+/g, " ").trim();
+  return one.length <= TEXT_CHIP_MAX ? one : `${one.slice(0, TEXT_CHIP_MAX - 1)}…`;
+}
+
+/**
+ * The guide for one sketch, or null when the part does not hold it. Every
+ * image, component, text and box item is an outline with its label (a box's
+ * label, a card's label, a text's words); an arrow stays an arrow. The first
+ * label carries the sketch's time, "pile · 1.60s", the one moment it shows.
+ */
+export function sketchGuideOf(doc: Doc3D, partId: string, sketchId: string): ShotSketchGuide | null {
+  const found = findSketch(doc, sketchId);
+  if (found === null || found.part.id !== partId) return null;
+  const rects: ShotSketchGuideRect[] = [];
+  const arrows: ShotSketchGuide["arrows"][number][] = [];
+  for (const item of found.sketch.items) {
+    if (item.kind === "arrow") {
+      arrows.push({ from: item.from, to: item.to, ...(item.label === undefined ? {} : { label: item.label }) });
+      continue;
+    }
+    const label =
+      item.kind === "box" ? item.label : item.kind === "text" ? clip(item.text) : (sketchCardOf(doc, item)?.label ?? "Missing");
+    rects.push({
+      at: item.position,
+      size: item.size,
+      ...(item.kind === "box" ? { radius: BOX_RADIUS } : {}),
+      ...(label === undefined || label.trim() === "" ? {} : { label: label.trim() }),
+    });
+  }
+  const frame = found.sketch.frame;
+  const first = rects.find((rect) => rect.label !== undefined);
+  if (frame !== undefined && first !== undefined) {
+    first.label = `${first.label} · ${formatDuration(framesToSeconds(frame, doc.fps))}`;
+  }
+  return { rects, arrows };
+}

package/src/state/splineRefs.ts

@@ -0,0 +1,87 @@
+import {
+  MAX_FRAMING_ZOOM,
+  MIN_FRAMING_ZOOM,
+  layerChildren,
+  meshPrimitiveOf,
+  planeDistance,
+  splineFrameScale,
+  splineProjectedRange,
+  splineReferenceProblems,
+  worldBaseTransform,
+} from "@dailies-studio/shot/doc";
+import type { Layer3D, Scene3D } from "@dailies-studio/shot/doc";
+
+/** Check the graph the inspector would commit before offering a spline source. */
+export function splineSourceIsSafe(
+  layersById: Readonly<Record<string, Layer3D>>,
+  consumerIds: readonly string[],
+  source: string,
+  site: "follow" | "cloner",
+): boolean {
+  const consumers = new Set(consumerIds);
+  const proposed: Record<string, Layer3D> = { ...layersById };
+  for (const id of consumerIds) {
+    const layer = proposed[id];
+    if (layer === undefined) continue;
+    if (site === "follow") {
+      proposed[id] = {
+        ...layer,
+        splineFollow: { ...layer.splineFollow, spline: source },
+      } as Layer3D;
+      continue;
+    }
+    if (layer.kind === "cloner") {
+      proposed[id] = {
+        ...layer,
+        cloner: { ...layer.cloner, mode: { kind: "spline", spline: source } },
+      };
+    }
+  }
+  return !splineReferenceProblems(proposed).some((problem) =>
+    consumers.has(problem.consumer) || problem.cycle?.some((id) => consumers.has(id)) === true,
+  );
+}
+
+/** Camera rails have a stricter source contract than layer followers.
+ *
+ * The editor repeats the validator's read-only predicate so its picker never
+ * offers a choice that the next autosave would refuse. A cloner would give the
+ * source multiple simultaneous poses, while the authored base centreline must
+ * begin inside the camera distance range. Transform and visible-trim animation
+ * are allowed; runtime samples them live and falls back at the safe-band edge.
+ */
+export function cameraSplineSourceIsSafe(
+  scene: Scene3D,
+  sourceId: string,
+  designHeight: number,
+): boolean {
+  const source = scene.layersById[sourceId];
+  const spline = source?.kind === "mesh" ? meshPrimitiveOf(source.mesh) : null;
+  if (source?.kind !== "mesh" || spline?.kind !== "spline") return false;
+
+  const parent = new Map<string, string>();
+  for (const [id, layer] of Object.entries(scene.layersById)) {
+    for (const child of layerChildren(layer)) parent.set(child, id);
+  }
+  const seen = new Set<string>();
+  let id: string | undefined = source.id;
+  while (id !== undefined && !seen.has(id)) {
+    seen.add(id);
+    const layer = scene.layersById[id];
+    if (layer === undefined) return false;
+    id = parent.get(id);
+    if (id !== undefined && scene.layersById[id]?.kind === "cloner") return false;
+  }
+  if (id !== undefined) return false;
+  const scale = splineFrameScale(spline, source.transform.size);
+  const rigid = worldBaseTransform(scene, source.id);
+  const projection: [number, number, number] = [
+    -rigid.rotation[2][0] * scale[0],
+    rigid.rotation[2][1] * scale[1],
+    rigid.rotation[2][2] * scale[2],
+  ];
+  const range = splineProjectedRange(spline, projection, -rigid.position[2]);
+  const nearest = planeDistance(designHeight, scene.fovDeg, MAX_FRAMING_ZOOM);
+  const farthest = planeDistance(designHeight, scene.fovDeg, MIN_FRAMING_ZOOM);
+  return range.max <= -nearest && range.min >= -farthest;
+}

package/src/state/stageHealth.ts

@@ -0,0 +1,259 @@
+// What this editor tab tells an agent about its stage (shot/stageHealth.ts).
+//
+// An agent writes a Project over MCP; this tab adopts the new revision and
+// its stage draws it. The agent's write answer waits for that draw and
+// reports what the stage holds once it lands: the isolated pieces, the crash,
+// the render fallbacks, the component failures and the errors of every realm
+// the picture depends on. It is asked through the host's channel: the dev
+// server's change feed locally (a `relay-request` for the tool `stage`,
+// answered at `POST /api/relay/:id/result`, renderEvents.ts), the code host's
+// relay hosted (`provideStageHealth`, browser-host boot.ts).
+//
+// THE WAIT IS EVENT-DRIVEN. It wakes on the stage's `onStageHealth` (bridge
+// v35: a presentation of another revision or module epoch, a failure), on the
+// chrome's own state and on the chrome's error log, and one timer bounds it.
+// A background tab throttles timers, never these events, so a stage that
+// draws answers the moment it has.
+//
+// THEN THE PICTURE ITSELF. A stage that drew the revision with nothing
+// failing can still show nothing of a model (a background or a layer painted
+// over it, a camera that does not see it), so once the wait settles on a
+// drawn revision the stage is asked which mesh-like layers put a pixel in its
+// frame (bridge v36 `coverage()`), bounded by `COVERAGE_WAIT_MS`, and the
+// answer, or why there is none, rides the report.
+import { COVERAGE_WAIT_MS, instanceComponentIdsOf } from "@dailies-studio/shot/doc";
+import type {
+  StageCoverage,
+  StageHealthReport,
+  StageHealthRequest,
+  StageHealthSnapshot,
+  StageLink,
+  StageRuntimeError,
+} from "@dailies-studio/shot/doc";
+import { runtimeErrors, subscribeRuntimeErrors } from "./runtimeErrors.js";
+import type { ShotEditorStore } from "./store.js";
+
+/** Where a wait stands: settled (the stage drew what was asked, or failed in
+ *  a way that ends the wait), still waiting on something, or answered at once
+ *  because waiting cannot change the answer. */
+interface Verdict {
+  settled: boolean;
+  /** What the stage has not done yet; null once settled. */
+  waitingFor: string | null;
+  /** Answer now, settled or not. */
+  final: boolean;
+}
+
+function snapshotOf(store: ShotEditorStore): { snapshot: StageHealthSnapshot | null; error: string | null } {
+  const bridge = store.stage();
+  if (bridge === null) return { snapshot: null, error: null };
+  if (typeof bridge.health !== "function") {
+    // A v34 stage cannot be here (connectStage refuses it), but a report
+    // must never throw on one.
+    return { snapshot: null, error: "the stage does not report its health: reload the editor, which rebuilds both halves" };
+  }
+  try {
+    return { snapshot: bridge.health(), error: null };
+  } catch (e) {
+    return { snapshot: null, error: `the stage could not report its health: ${e instanceof Error ? e.message : String(e)}` };
+  }
+}
+
+function linkOf(store: ShotEditorStore, healthError: string | null): { link: StageLink; linkError: string | null } {
+  if (healthError !== null) return { link: "failed", linkError: healthError };
+  if (store.stage() !== null) return { link: "connected", linkError: null };
+  const failed = store.stageConnectError();
+  if (failed !== null) return { link: "failed", linkError: failed };
+  return { link: store.getState().stageExpected ? "connecting" : "none", linkError: null };
+}
+
+/** What the coverage check found, or why there is none. */
+export interface CoverageAnswer {
+  coverage: StageCoverage | null;
+  coverageError: string | null;
+}
+
+const NOT_CHECKED: CoverageAnswer = { coverage: null, coverageError: null };
+
+/** The report as it stands, with `verdict`'s wait state. `extraErrors` are
+ *  the host's own (the hosted code host's compile worker). */
+export function stageHealthReport(
+  store: ShotEditorStore,
+  verdict: Pick<Verdict, "settled" | "waitingFor"> = { settled: true, waitingFor: null },
+  extraErrors: readonly StageRuntimeError[] = [],
+  checked: CoverageAnswer = NOT_CHECKED,
+): StageHealthReport {
+  const state = store.getState();
+  const { snapshot, error } = snapshotOf(store);
+  const { link, linkError } = linkOf(store, error);
+  return {
+    v: 1,
+    project: state.name,
+    savedRev: state.rev,
+    dirty: state.dirty,
+    sceneId: state.sceneId,
+    frame: state.frame,
+    link,
+    linkError,
+    stage: snapshot,
+    errors: [...runtimeErrors(), ...extraErrors],
+    editorError: state.error,
+    settled: verdict.settled,
+    waitingFor: verdict.waitingFor,
+    coverage: checked.coverage,
+    coverageError: checked.coverageError,
+  };
+}
+
+/**
+ * Ask the stage which mesh-like layers put a pixel in its frame, once the
+ * wait settled on a DRAWN revision. A wait that did not settle, a stage that
+ * could not come up or crashed (their failure is the answer) is not asked;
+ * one that cannot answer in `COVERAGE_WAIT_MS`, or refuses, says why.
+ */
+export async function coverageOf(
+  store: ShotEditorStore,
+  verdict: Pick<Verdict, "settled">,
+  deps: Pick<StageWaitDeps, "setTimeout" | "clearTimeout"> = TIMERS,
+): Promise<CoverageAnswer> {
+  if (!verdict.settled) return NOT_CHECKED;
+  const bridge = store.stage();
+  const { snapshot } = snapshotOf(store);
+  if (bridge === null || snapshot === null || snapshot.crashed !== null) return NOT_CHECKED;
+  if (typeof bridge.coverage !== "function") {
+    return { coverage: null, coverageError: "the stage does not check which layers draw: reload the editor, which rebuilds both halves" };
+  }
+  let timer: unknown = null;
+  try {
+    const coverage = await Promise.race([
+      bridge.coverage(),
+      new Promise<never>((_, reject) => {
+        timer = deps.setTimeout(
+          () => reject(new Error(`the stage's check of which layers draw did not finish within ${COVERAGE_WAIT_MS / 1000} s`)),
+          COVERAGE_WAIT_MS,
+        );
+      }),
+    ]);
+    return { coverage, coverageError: null };
+  } catch (e) {
+    return { coverage: null, coverageError: e instanceof Error ? e.message : String(e) };
+  } finally {
+    if (timer !== null) deps.clearTimeout(timer);
+  }
+}
+
+/** Where a wait for `request` stands now. */
+export function judgeStage(store: ShotEditorStore, request: StageHealthRequest): Verdict {
+  const state = store.getState();
+  if (request.name !== undefined && state.name !== request.name) {
+    return {
+      settled: false,
+      final: true,
+      waitingFor:
+        state.name === null ? "this editor tab has no Project open" : `this editor tab shows ${JSON.stringify(state.name)}`,
+    };
+  }
+  if (state.name === null || state.doc === null) {
+    return { settled: false, final: true, waitingFor: "this editor tab has no Project open" };
+  }
+  const { snapshot, error } = snapshotOf(store);
+  const { link } = linkOf(store, error);
+  // A stage that cannot come up, or came down, ends the wait: it is the answer.
+  if (link === "failed") return { settled: true, final: true, waitingFor: null };
+  if (link === "none") return { settled: false, final: true, waitingFor: "this editor tab has no stage mounted" };
+  if (snapshot === null) return { settled: false, final: false, waitingFor: "the stage is still loading" };
+  if (snapshot.crashed !== null) return { settled: true, final: true, waitingFor: null };
+  const want = request.rev ?? state.rev;
+  if (state.dirty) {
+    // Unsaved edits: the tab takes no revision written elsewhere until they
+    // are saved or dropped, and its stage shows neither.
+    return {
+      settled: false,
+      final: true,
+      waitingFor: `the editor holds unsaved edits of ${JSON.stringify(state.name)}, so its stage shows them and not revision ${want ?? "(none)"}`,
+    };
+  }
+  const drawn = snapshot.rendered;
+  if (want === null || drawn === null || drawn.rev !== want || drawn.docId !== state.doc.id) {
+    return { settled: false, final: false, waitingFor: `the stage has not drawn revision ${want ?? "(none)"} yet` };
+  }
+  const code = request.code;
+  if (code !== undefined && instanceComponentIdsOf(state.doc).length > 0) {
+    if (code.epoch !== undefined && (drawn.epoch ?? -1) < code.epoch) {
+      return { settled: false, final: false, waitingFor: "the stage has not drawn with the code as it was just compiled" };
+    }
+    if (code.since !== undefined && snapshot.loadedAt < code.since) {
+      return { settled: false, final: false, waitingFor: "the stage has not taken the code as it was just written" };
+    }
+  }
+  return { settled: true, final: true, waitingFor: null };
+}
+
+export interface StageWaitDeps {
+  setTimeout(run: () => void, ms: number): unknown;
+  clearTimeout(timer: unknown): void;
+  /** Run `run` in the next task. */
+  nextTask(run: () => void): void;
+}
+
+const TIMERS: StageWaitDeps = {
+  setTimeout: (run, ms) => setTimeout(run, ms),
+  clearTimeout: (timer) => clearTimeout(timer as ReturnType<typeof setTimeout>),
+  // A message port, not a timer: a background tab throttles timers to a
+  // second, never a port.
+  nextTask: (run) => {
+    if (typeof MessageChannel !== "function") {
+      setTimeout(run, 0);
+      return;
+    }
+    const channel = new MessageChannel();
+    channel.port1.onmessage = () => {
+      channel.port1.close();
+      run();
+    };
+    channel.port2.postMessage(null);
+  },
+};
+
+/**
+ * Wait, at most `request.waitMs`, for the stage to draw what `request` asks
+ * (the saved revision, and the code), then report. Answers at once when the
+ * tab shows another Project, holds unsaved edits, has no stage, or its stage
+ * cannot come up or crashed: waiting changes none of those.
+ */
+export function awaitStageHealth(
+  store: ShotEditorStore,
+  request: StageHealthRequest,
+  extraErrors: () => readonly StageRuntimeError[] = () => [],
+  deps: StageWaitDeps = TIMERS,
+): Promise<StageHealthReport> {
+  return new Promise((resolve) => {
+    let done = false;
+    const stops: Array<() => void> = [];
+    const finish = (verdict: Verdict): void => {
+      if (done) return;
+      done = true;
+      for (const stop of stops) stop();
+      void coverageOf(store, verdict, deps).then((checked) => resolve(stageHealthReport(store, verdict, extraErrors(), checked)));
+    };
+    // THE REST OF THE COMMIT FIRST. The stage says it drew from inside its
+    // draw, and a piece that failed in that same commit (a placed component's
+    // boundary, a layer's apply) reports in the same task, possibly after it.
+    // So a final answer is taken in the next task, judged again.
+    let confirming = false;
+    const check = (): void => {
+      if (done || confirming || !judgeStage(store, request).final) return;
+      confirming = true;
+      deps.nextTask(() => {
+        confirming = false;
+        const verdict = judgeStage(store, request);
+        if (verdict.final) finish(verdict);
+      });
+    };
+    stops.push(store.subscribeStageHealth(check), store.subscribe(check), subscribeRuntimeErrors(check));
+    const wait = Math.max(0, Math.floor(request.waitMs));
+    const timer = deps.setTimeout(() => finish({ ...judgeStage(store, request), final: true }), wait);
+    stops.push(() => deps.clearTimeout(timer));
+    check();
+  });
+}

package/src/state/stageWatchdog.ts

@@ -0,0 +1,47 @@
+// Every await on the stage that holds the export lock races this.
+//
+// A promise the stage hands back lives in the IFRAME's realm. If the stage
+// reloads mid-call (Vite HMR remints the bridge, a crashed stage is swapped
+// for a fresh one), that realm dies: the promise never settles, and the abort
+// listener the stage registered on the call's signal died with it. The lock
+// is released only when the await ends, so without this race it stayed held,
+// Cancel did nothing, and every later export, capture and Play refused until
+// the page was reloaded. Both halves are watched from the chrome's realm.
+import type { ShotStageBridge } from "../bridgeTypes.js";
+
+/** How often the attached bridge is compared with the one the call went to. */
+const STAGE_POLL_MS = 500;
+
+/**
+ * Settle with `work`, or reject first: with `cancelled` (default "export
+ * cancelled") when `signal` aborts, and with `reloaded` once `stage()` no
+ * longer answers `bridgeAtStart`.
+ */
+export function raceStage<T>(
+  work: Promise<T>,
+  watch: {
+    stage: () => ShotStageBridge | null;
+    bridgeAtStart: ShotStageBridge;
+    signal: AbortSignal;
+    reloaded: string;
+    cancelled?: string;
+  },
+): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const timer = setInterval(() => {
+      if (watch.stage() !== watch.bridgeAtStart) stop(() => reject(new Error(watch.reloaded)));
+    }, STAGE_POLL_MS);
+    const onAbort = (): void => stop(() => reject(new Error(watch.cancelled ?? "export cancelled")));
+    function stop(settle: () => void): void {
+      clearInterval(timer);
+      watch.signal.removeEventListener("abort", onAbort);
+      settle();
+    }
+    watch.signal.addEventListener("abort", onAbort, { once: true });
+    if (watch.signal.aborted) onAbort();
+    work.then(
+      (value) => stop(() => resolve(value)),
+      (error: unknown) => stop(() => reject(error)),
+    );
+  });
+}