@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/stage/gpuTimer.ts

@@ -0,0 +1,276 @@
+// The GPU's own time per drawn frame, off three's timestamp queries.
+//
+// WHAT THE NUMBER COVERS IS THREE'S, AND IT IS NARROW. Each render pass is
+// bracketed by a timestamp pair, so a frame's time is the sum of its passes.
+// Texture uploads, mip generation and copies run outside every pass and are
+// not in it, and Chrome quantizes WebGPU timestamps to about 0.07-0.1 ms. That
+// is the right signal for a resolution decision (pixels cost pass time) and
+// the wrong one for a stall an upload or a compile causes.
+//
+// r185 reads `backend.trackTimestamp` per pass (`initTimestampQuery` on both
+// backends), so it can be switched on after the renderer was made. A backend
+// without the feature must never have it on: WebGPU would create a timestamp
+// query set the device cannot validate. The pool holds 2048 queries (1024
+// passes) and only a resolve empties it, so the timer resolves after every
+// draw, or with the next draw while one resolve is still out.
+//
+// EVERY FRAME OF A RESOLVE IS A SAMPLE, AND THE TIMER EMPTIES THREE'S MAP. A
+// resolve answers with the LAST frame it saw, but on WebGPU the frames drawn
+// while the one before it was out are in the same batch. three keeps each
+// pass's ms in the pool's `timestamps`, keyed by a uid that ends in
+// `:f<frame id>`, so the timer sums them per frame. three never deletes from
+// that map and every frame adds new uids, so the timer clears it after each
+// resolve: nothing in the stage reads `getTimestamp`, which is the map's only
+// other reader. WebGL LOSES those frames instead: its pool reads only the
+// queries that had ended when the resolve began, then forgets every query
+// offset, the ones frames drew while it was out included (r185
+// WebGLTimestampQueryPool `resolveQueriesAsync`). There a sample is one frame
+// in two or three, which is why the controller closes a window by time as well
+// as by count (renderScaleController.ts).
+//
+// A SCALED FRAME'S PASSES UP TO THE CANVAS ARE KEPT APART. The copy of P and
+// the present cover the canvas whatever the playback scale, so each frame's
+// sum comes with the share each took, by the uid and kind the presentation
+// child recorded (`takePresentationPass`, packages/shot/src/presentationScale.ts):
+// the present is the output pass a frame at 1 draws too, and the copy one only
+// a scaled frame draws, which the controller prices apart.
+//
+// A frame here is three's rAF tick (`info.frame`), not a stage draw. PerfProbe
+// resets three's Info at the start of every stage draw, so two draws inside
+// one tick (a resize redraw) restart the render-call count in the uid, and
+// three keeps only the second draw's queries for that tick.
+//
+// Known r185 leftover, harmless: WebGPU caches the canvas pass descriptor, so
+// after `stop` it keeps writing its last timestamp pair into the idle query
+// set until three rebuilds it. No pixel depends on it.
+//
+// ── IN PRODUCTION, WHILE THE TRANSPORT PLAYS ─────────────────────────────
+//
+// The playback render scale decides on this number, beside the presented
+// frames' deadlines (renderScaleController.ts: a step down needs both), so
+// `GpuTimer` below is mounted in the editor's non-export branch whenever
+// the stage plays, perf or not (StageApp): the transport, or a preparing
+// pass, whose frames the controller drops. Pause unmounts it. Its cost per
+// drawn frame is a timestamp pair per pass and one resolve: a query-set
+// resolve, a buffer copy and a map, and never a second resolve while one is
+// out. The perf HUD keeps it on while paused too, for its own reading.
+import { useEffect, useRef } from "react";
+import { useFrame, useThree } from "@react-three/fiber";
+import { takePresentationPass } from "@dailies-studio/shot";
+import type { PresentationPass } from "@dailies-studio/shot";
+import { percentile } from "./stagePerformanceTelemetry.js";
+
+interface TimestampRenderer {
+  backend: {
+    isWebGPUBackend?: boolean;
+    isWebGLBackend?: boolean;
+    /** WebGL: EXT_disjoint_timer_query_webgl2 was found. WebGPU answers true
+     *  always, so it is no feature test there. */
+    hasTimestamp?: boolean;
+    hasFeature?: (name: string) => boolean;
+    trackTimestamp?: boolean;
+    timestampQueryPool?: {
+      render?: {
+        currentQueryIndex?: number;
+        /** Each resolved pass's ms, by uid (`r:<call>:<context>:f<frame id>`). */
+        timestamps?: Map<string, number>;
+      } | null;
+    };
+  };
+  resolveTimestampsAsync(type: "render"): Promise<number | undefined>;
+}
+
+export type GpuTimerKind = "webgpu" | "webgl";
+
+export interface GpuTimerHandle {
+  readonly kind: GpuTimerKind;
+  /** After every draw: resolve the passes it timed. */
+  afterDraw(): void;
+  /** Drain once, then stop timing passes. */
+  stop(): void;
+}
+
+/** Which timer this renderer can run, or null when it has none. */
+export function gpuTimerKind(renderer: unknown): GpuTimerKind | null {
+  const gl = renderer as Partial<TimestampRenderer> | null | undefined;
+  const backend = gl?.backend;
+  if (backend === undefined || typeof gl?.resolveTimestampsAsync !== "function") return null;
+  if (backend.isWebGPUBackend === true) {
+    return backend.hasFeature?.("timestamp-query") === true ? "webgpu" : null;
+  }
+  if (backend.isWebGLBackend === true) return backend.hasTimestamp === true ? "webgl" : null;
+  return null;
+}
+
+/** One resolved frame's ms, and the ms its playback-scale copy of P and its
+ *  present took (0 each for an unscaled frame). */
+export type GpuFrameSink = (ms: number, copyMs: number, presentMs: number) => void;
+
+/** Turn the renderer's timestamps on and hand each resolved frame to
+ *  `onFrame`, oldest first. Null, and nothing switched on, without a timer. */
+export function startGpuTimer(renderer: unknown, onFrame: GpuFrameSink): GpuTimerHandle | null {
+  const kind = gpuTimerKind(renderer);
+  if (kind === null) return null;
+  const gl = renderer as TimestampRenderer;
+  const backend = gl.backend;
+  backend.trackTimestamp = true;
+  let resolving = false;
+  let stopped = false;
+  const pool = () => backend.timestampQueryPool?.render ?? null;
+  // Asked before every resolve: with no pass written since the last one, a
+  // resolve has nothing to read.
+  const pending = (): boolean => (pool()?.currentQueryIndex ?? 0) > 0;
+  const resolve = (): void => {
+    resolving = true;
+    void gl.resolveTimestampsAsync("render").then(
+      () => {
+        resolving = false;
+        const timestamps = pool()?.timestamps;
+        if (timestamps === undefined) return;
+        const frames = framesOf(timestamps, (uid) => takePresentationPass(gl, uid));
+        timestamps.clear();
+        if (stopped) return;
+        for (const frame of frames) onFrame(frame.ms, frame.copyMs, frame.presentMs);
+      },
+      () => {
+        resolving = false;
+        pool()?.timestamps?.clear();
+      },
+    );
+  };
+  return {
+    kind,
+    afterDraw() {
+      if (!stopped && !resolving && pending()) resolve();
+    },
+    stop() {
+      if (stopped) return;
+      stopped = true;
+      // The resolve reads `trackTimestamp` as it is called, so it goes first.
+      if (!resolving && pending()) resolve();
+      backend.trackTimestamp = false;
+    },
+  };
+}
+
+/** The stage child that runs the timer on the canvas's renderer: `onTimer`
+ *  once at mount with the timer it found (null when the renderer has none),
+ *  then `onFrame` with each resolved frame's ms, its copy's and its
+ *  present's. Stopped, after one drain, on unmount. Both are read at call
+ *  time, so a new callback restarts nothing. */
+export function GpuTimer({
+  onFrame,
+  onTimer,
+}: {
+  onFrame: GpuFrameSink;
+  onTimer: (kind: GpuTimerKind | null) => void;
+}): null {
+  const gl = useThree((s) => s.gl);
+  const timer = useRef<GpuTimerHandle | null>(null);
+  const sinks = useRef({ onFrame, onTimer });
+  sinks.current = { onFrame, onTimer };
+  useEffect(() => {
+    const started = startGpuTimer(gl, (ms, copyMs, presentMs) => sinks.current.onFrame(ms, copyMs, presentMs));
+    timer.current = started;
+    sinks.current.onTimer(started?.kind ?? null);
+    return () => {
+      started?.stop();
+      timer.current = null;
+    };
+  }, [gl]);
+  // The scheduler's finish phase, like PerfProbe's: after every render the
+  // frame made, the presenters' included. fiber stands its own draw down only
+  // for render-phase jobs, so this one can never leave a pane blank.
+  useFrame(() => {
+    timer.current?.afterDraw();
+  }, { phase: "finish" });
+  return null;
+}
+
+/** One resolve's passes summed per frame, in the order three drew them, each
+ *  with the shares its copy and present passes took (`passOf`). A frame whose
+ *  sum is not a time is dropped. */
+function framesOf(
+  timestamps: ReadonlyMap<string, number>,
+  passOf: (uid: string) => PresentationPass | null,
+): { ms: number; copyMs: number; presentMs: number }[] {
+  const frames = new Map<string, { ms: number; copyMs: number; presentMs: number }>();
+  for (const [uid, ms] of timestamps) {
+    const at = uid.lastIndexOf(":f");
+    const key = at < 0 ? uid : uid.slice(at + 2);
+    let frame = frames.get(key);
+    if (frame === undefined) {
+      frame = { ms: 0, copyMs: 0, presentMs: 0 };
+      frames.set(key, frame);
+    }
+    frame.ms += ms;
+    const pass = passOf(uid);
+    if (pass === "copy") frame.copyMs += ms;
+    else if (pass === "present") frame.presentMs += ms;
+  }
+  return [...frames.values()].filter((frame) => Number.isFinite(frame.ms) && frame.ms >= 0);
+}
+
+/** GPU time per frame over the samples a reader asked for. Every value is
+ *  null when there are none. */
+export interface GpuStats {
+  samples: number;
+  p50Ms: number | null;
+  p95Ms: number | null;
+  maxMs: number | null;
+  /** Samples the ring overwrote since it was made, inside the range or not. */
+  lost: number;
+}
+
+export const NO_GPU_STATS: Readonly<GpuStats> = Object.freeze({
+  samples: 0,
+  p50Ms: null,
+  p95Ms: null,
+  maxMs: null,
+  lost: 0,
+});
+
+/** Over nine minutes of frames at 60 a second. */
+const GPU_SAMPLE_CAPACITY = 1 << 15;
+
+/**
+ * The frames the timer resolved, newest last, at most `capacity` of them: what
+ * the HUD and `__perfProbe.gpu()` read. Each is timed when its resolve landed
+ * (the stage's `performance.now()`), a frame or two after its draw.
+ */
+export class GpuSamples {
+  readonly #at: Float64Array;
+  readonly #ms: Float64Array;
+  #count = 0;
+
+  constructor(capacity = GPU_SAMPLE_CAPACITY) {
+    this.#at = new Float64Array(capacity);
+    this.#ms = new Float64Array(capacity);
+  }
+
+  push(at: number, ms: number): void {
+    const slot = this.#count % this.#at.length;
+    this.#at[slot] = at;
+    this.#ms[slot] = ms;
+    this.#count += 1;
+  }
+
+  /** The kept samples that landed in `[fromMs, toMs)`. */
+  stats(fromMs = Number.NEGATIVE_INFINITY, toMs = Number.POSITIVE_INFINITY): GpuStats {
+    const capacity = this.#at.length;
+    const lost = Math.max(0, this.#count - capacity);
+    const values: number[] = [];
+    for (let index = lost; index < this.#count; index += 1) {
+      const slot = index % capacity;
+      const at = this.#at[slot]!;
+      if (at >= fromMs && at < toMs) values.push(this.#ms[slot]!);
+    }
+    return {
+      samples: values.length,
+      p50Ms: percentile(values, 0.5),
+      p95Ms: percentile(values, 0.95),
+      maxMs: percentile(values, 1),
+      lost,
+    };
+  }
+}

package/src/stage/instanceModules.ts

@@ -21,19 +21,33 @@
 //                   and needs no network at all.
 //
 // FAILURE IS NEVER FATAL. Every load is caught: a component that will not
-// resolve is simply absent from the map and its layer draws nothing, with the
-// reason travelling up the stage's existing error channel. A stage that threw
-// here would blank the whole editor over one broken import.
+// resolve is absent from the map, its id is in `failed`, and the stage
+// marks each placed layer of it as a failed piece (a dashed placeholder on the
+// frame, the reason in the inspector). A stage that threw
+// here would blank the whole editor over one broken import. The reason is the
+// import's own error message: hosted, a module that failed to compile or
+// imports what the stage cannot serve throws one naming the file and the
+// specifier, and that is the line an author needs.
+//
+// THE MODULE EPOCH (moduleEpoch.ts). Hosted, each compile of the user's code
+// is a new epoch, and the registry URL and every project-relative controls URL
+// carry it as `?v=<epoch>`. Locally there is never an epoch, and every URL is
+// byte-for-byte what it always was. Both caches are scoped to the epoch, so a
+// bump re-imports (a failed import included) and an unchanged epoch keeps
+// every promise, hence every module identity.
 import {
+  CODE_PREVIEW_DEF_ID,
+  CODE_PREVIEW_LAYER_ID,
   controlsModuleOf,
   instanceComponentIdsOf,
   instanceContractBindings,
   instanceModuleOf,
   isBareModuleSpecifier,
 } from "@dailies-studio/shot/doc";
-import type { Doc3D } from "@dailies-studio/shot/doc";
+import type { Doc3D, PieceFailure } from "@dailies-studio/shot/doc";
 import type { Contract } from "@dailies-studio/contract";
 import type { ComponentType } from "react";
+import type { ModuleEpoch } from "./moduleEpoch.js";
 
 /** The `virtual:studio-components` row shape (cli registry.ts). */
 interface RegistryEntry {
@@ -51,15 +65,23 @@ export interface InstanceResolution {
   /** One line per component that could not be resolved. Empty when everything
    *  loaded (or the document has no instances). */
   errors: string[];
+  /** Each component whose module did not load, with its line from `errors`.
+   *  Its placed layers draw a failed placeholder on the frame instead of
+   *  nothing. */
+  failed: Record<string, string>;
 }
 
-const EMPTY: InstanceResolution = { instances: {}, contracts: {}, errors: [] };
+const EMPTY: InstanceResolution = { instances: {}, contracts: {}, errors: [], failed: {} };
+
+/** A component load's answer: the component, or why there is none (null when
+ *  the registry simply does not know the id). */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type ComponentLoad = { component: ComponentType<any> } | { reason: string | null };
 
 /** Module-level caches: the stage re-resolves on every document identity change
  *  (an inspector keystroke), and a dynamic import is idempotent but a REJECTED
  *  one is not cheap to retry in a loop. */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-const componentCache = new Map<string, Promise<ComponentType<any> | null>>();
+const componentCache = new Map<string, Promise<ComponentLoad>>();
 const contractCache = new Map<string, Promise<Contract | null>>();
 
 /** The registry's URL, not its module ID. `virtual:studio-components` is
@@ -68,63 +90,147 @@ const contractCache = new Map<string, Promise<Contract | null>>();
  *  a const so Vite's import analysis cannot see a literal and try. */
 const COMPONENT_REGISTRY_URL = "/@id/virtual:studio-components";
 
-async function registry(): Promise<Record<string, RegistryEntry>> {
-  const mod = (await import(/* @vite-ignore */ COMPONENT_REGISTRY_URL)) as {
+/** The dynamic import every module load goes through. */
+export type ImportModule = (url: string) => Promise<unknown>;
+const dynamicImport: ImportModule = (url) => import(/* @vite-ignore */ url);
+
+/** `url` under `epoch`, or `url` untouched when there is none. */
+function versioned(url: string, epoch: ModuleEpoch): string {
+  return epoch === null ? url : `${url}?v=${epoch}`;
+}
+
+/** A cache key scoped to one epoch. Keys hold no newline, so no two collide. */
+function scoped(epoch: ModuleEpoch, key: string): string {
+  return epoch === null ? key : `${epoch}\n${key}`;
+}
+
+async function registry(
+  epoch: ModuleEpoch,
+  importModule: ImportModule,
+): Promise<Record<string, RegistryEntry>> {
+  const mod = (await importModule(versioned(COMPONENT_REGISTRY_URL, epoch))) as {
     components?: Record<string, RegistryEntry>;
   };
   return mod.components ?? {};
 }
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-function loadComponent(id: string): Promise<ComponentType<any> | null> {
-  const hit = componentCache.get(id);
+function loadComponent(id: string, epoch: ModuleEpoch, importModule: ImportModule): Promise<ComponentLoad> {
+  const key = scoped(epoch, id);
+  const hit = componentCache.get(key);
   if (hit !== undefined) return hit;
-  const p = (async () => {
-    const entry = (await registry())[id];
-    if (entry === undefined) return null;
+  const p = (async (): Promise<ComponentLoad> => {
+    const entry = (await registry(epoch, importModule))[id];
+    if (entry === undefined) return { reason: null };
     const value = await entry.load();
     // A vanished export resolves to undefined; treat it as "not resolvable"
     // rather than rendering `undefined` into the tree.
     return typeof value === "function" || (typeof value === "object" && value !== null)
       ? // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        (value as ComponentType<any>)
+        { component: value as ComponentType<any> }
+      : { reason: null };
+  })().catch((e: unknown): ComponentLoad => ({ reason: e instanceof Error ? `${e.name}: ${e.message}` : String(e) }));
+  componentCache.set(key, p);
+  return p;
+}
+
+/**
+ * The registry's own contract for one component, over HTTP.
+ *
+ * FOR THE UNPLACED ONLY. Every other path here resolves a contract from the
+ * DOCUMENT: a declared one through the controls module the layer's
+ * `EmbedContractRef` names, an inferred one through the snapshot the document
+ * froze at bind time. The code studio renders a component the document does
+ * not place, so it has neither, and without a contract `buildProps` falls
+ * through to the raw prop map — which for a preview is empty, so the component
+ * would mount with no props at all rather than at its declared defaults.
+ *
+ * `/api/components/:id` is the one answer that covers both contract sources,
+ * and it is the same route the chrome's own `loadContract` reads, so the two
+ * sides cannot end up holding different contracts for one id. Same-origin GET:
+ * the stage is served by this server, so the bridge pairing gate never applies.
+ */
+function loadRegistryContract(id: string, epoch: ModuleEpoch): Promise<Contract | null> {
+  const key = scoped(epoch, `registry:${id}`);
+  const hit = contractCache.get(key);
+  if (hit !== undefined) return hit;
+  const p = (async () => {
+    const res = await fetch(`/api/components/${encodeURIComponent(id)}`);
+    if (!res.ok) return null;
+    const detail = (await res.json()) as { contract?: unknown };
+    const contract = detail.contract;
+    return contract !== null && typeof contract === "object" && "keys" in contract
+      ? (contract as Contract)
       : null;
   })().catch(() => null);
-  componentCache.set(id, p);
+  contractCache.set(key, p);
   return p;
 }
 
-function loadDeclaredContract(specifier: string): Promise<Contract | null> {
-  const hit = contractCache.get(specifier);
+function loadDeclaredContract(
+  specifier: string,
+  epoch: ModuleEpoch,
+  importModule: ImportModule,
+): Promise<Contract | null> {
+  const key = scoped(epoch, specifier);
+  const hit = contractCache.get(key);
   if (hit !== undefined) return hit;
-  const url = isBareModuleSpecifier(specifier) ? specifier : `/${specifier}`;
+  // A bare specifier is a package the import map (or Vite) resolves, never a
+  // project file, so it stays bare.
+  const url = isBareModuleSpecifier(specifier) ? specifier : versioned(`/${specifier}`, epoch);
   const p = (async () => {
-    const mod = (await import(/* @vite-ignore */ url)) as { controls?: unknown };
+    const mod = (await importModule(url)) as { controls?: unknown };
     const controls = mod.controls;
     return controls !== null && typeof controls === "object" && "keys" in controls
       ? (controls as Contract)
       : null;
   })().catch(() => null);
-  contractCache.set(specifier, p);
+  contractCache.set(key, p);
   return p;
 }
 
-/** Resolve every instance target in `doc`. Pure I/O — no React, no state — so
- *  the caller owns when it runs and what it does with a partial answer. */
-export async function resolveInstanceModules(doc: Doc3D): Promise<InstanceResolution> {
-  const ids = instanceComponentIdsOf(doc);
+export interface ResolveOptions {
+  /** The stage's module epoch. Absent or null: today's URLs exactly. */
+  readonly epoch?: ModuleEpoch;
+  /** Tests pass a recorder here; the stage never does. */
+  readonly importModule?: ImportModule;
+}
+
+/**
+ * Resolve every instance target in `doc`. Pure I/O — no React, no state — so
+ * the caller owns when it runs and what it does with a partial answer.
+ *
+ * `extraIds` are components to resolve that the DOCUMENT does not place. The
+ * code studio is the one caller: it renders a component standalone through a
+ * synthetic definition that lives outside the document, so the id set the
+ * document walks would never include it and the preview would sit empty
+ * forever. Their contracts come from the registry route rather than from a
+ * layer's binding, because a component with no placement has no binding.
+ */
+export async function resolveInstanceModules(
+  doc: Doc3D,
+  extraIds: readonly string[] = [],
+  options: ResolveOptions = {},
+): Promise<InstanceResolution> {
+  const ids = [...new Set([...instanceComponentIdsOf(doc), ...extraIds])].sort();
   if (ids.length === 0) return EMPTY;
+  const epoch = options.epoch ?? null;
+  const importModule = options.importModule ?? dynamicImport;
 
   const instances: InstanceModules = {};
   const errors: string[] = [];
+  const failed: Record<string, string> = {};
   await Promise.all(
     ids.map(async (id) => {
-      const comp = await loadComponent(id);
-      if (comp === null) {
-        errors.push(`instance "${id}" could not be loaded from the project — its layer is empty.`);
+      const loaded = await loadComponent(id, epoch, importModule);
+      if ("reason" in loaded) {
+        const line =
+          `instance "${id}" could not be loaded from the project` +
+          (loaded.reason === null ? "." : `: ${loaded.reason}`);
+        failed[id] = line;
+        errors.push(line);
         return;
       }
-      instances[id] = comp;
+      instances[id] = loaded.component;
     }),
   );
 
@@ -136,11 +242,11 @@ export async function resolveInstanceModules(doc: Doc3D): Promise<InstanceResolu
     instanceContractBindings(doc).map(async ({ component, ref }) => {
       if (ref.source === "snapshot") return;
       const specifier = controlsModuleOf(instanceModuleOf(component), ref.source);
-      const contract = await loadDeclaredContract(specifier);
+      const contract = await loadDeclaredContract(specifier, epoch, importModule);
       if (contract === null) {
         errors.push(
           `instance "${component}" declares its contract in ${JSON.stringify(specifier)}, which ` +
-            `did not load — its props render unmapped here.`,
+            `did not load, so its props render unmapped here.`,
         );
         return;
       }
@@ -148,5 +254,60 @@ export async function resolveInstanceModules(doc: Doc3D): Promise<InstanceResolu
     }),
   );
 
-  return { instances, contracts, errors };
+  // The unplaced ones, after the document's own — so a component that is BOTH
+  // open in the code studio and placed in the shot keeps the binding the
+  // document authored, and the registry answer never shadows it.
+  await Promise.all(
+    extraIds
+      .filter((id) => contracts[id] === undefined)
+      .map(async (id) => {
+        const contract = await loadRegistryContract(id, epoch);
+        // Not an error: a component with no contract at all is legal, and it
+        // renders with the props it was given. Only a component the registry
+        // does not know is worth saying anything about, and `loadComponent`
+        // above has already said it.
+        if (contract !== null) contracts[id] = contract;
+      }),
+  );
+
+  return { instances, contracts, errors, failed };
+}
+
+/**
+ * One isolated failure per placed layer whose component did not load, in the
+ * runtime's own `PieceFailure` shape, so it rides the same channel a render
+ * crash does: the dashed placeholder on the frame, the failure bar, the
+ * chrome's badge and inspector row, and the export gate. `codeId` is the code
+ * studio's subject, whose one layer lives in no document.
+ */
+export function instanceLoadFailures(
+  doc: Doc3D | null,
+  failed: Readonly<Record<string, string>>,
+  codeId: string | null,
+): PieceFailure[] {
+  const out: PieceFailure[] = [];
+  const failure = (sceneId: string, layerId: string, message: string): PieceFailure => ({
+    kind: "instance",
+    sceneId,
+    layerId,
+    message,
+    stack: "",
+    firstFrame: 0,
+    rev: null,
+  });
+  if (doc !== null) {
+    const homes = [
+      ...doc.scenes.map((id) => [id, doc.scenesById[id]] as const),
+      ...Object.entries(doc.components ?? {}),
+    ];
+    for (const [homeId, home] of homes) {
+      for (const layer of Object.values(home?.layersById ?? {})) {
+        const message = layer.kind === "instance" ? failed[layer.instance.component] : undefined;
+        if (message !== undefined) out.push(failure(homeId, layer.id, message));
+      }
+    }
+  }
+  const codeMessage = codeId === null ? undefined : failed[codeId];
+  if (codeMessage !== undefined) out.push(failure(CODE_PREVIEW_DEF_ID, CODE_PREVIEW_LAYER_ID, codeMessage));
+  return out;
 }

package/src/stage/interactions/move.ts

@@ -1,20 +1,20 @@
 // Turning a pointer into a DESIGN-SPACE delta, which is the one thing the
 // chrome's document math cannot do for itself.
 //
-// ── THE V-vs-G RULE, WHICH IS THE WHOLE FILE ────────────────────────────
+// ── THE PLAIN-vs-ALT RULE, WHICH IS THE WHOLE FILE ──────────────────────
 //
 // The 2D lane could say "screen delta ÷ zoom" because everything was coplanar.
 // Here each layer sits at its OWN depth under a perspective camera, so a screen
 // delta maps to a different world delta per layer — and there is no single
 // correct answer, because two different gestures are being asked for:
 //
-//   SELECT (V) unprojects onto the LAYER'S OWN tilted plane. Dragging a tilted
+//   A PLAIN DRAG unprojects onto the LAYER'S OWN tilted plane. Dragging a tilted
 //     layer slides it along its own surface, which is what "move this thing"
 //     means once the thing is a plane in space.
 //
-//   MOVE (G) unprojects onto the plane through the layer's origin PARALLEL to
-//     the export frame. Flat screen space: z never changes and tilt is ignored,
-//     which is what "move it on the canvas" means.
+//   AN ALT-DRAG unprojects onto the plane through the layer's origin PARALLEL
+//     to the export frame. Flat screen space: z never changes and tilt is
+//     ignored, which is what "move it on the canvas" means.
 //
 // Two `Ray.intersectPlane` calls. One plane constructor different. That is the
 // entire distinction, and stating it as two planes rather than as two code
@@ -44,6 +44,25 @@ export function gesturePlane(kind: MovePlane, matrixWorld: { elements: ArrayLike
   return new Plane().setFromNormalAndCoplanarPoint(normal, origin);
 }
 
+/**
+ * A plane through a WORLD point with a WORLD normal.
+ *
+ * `gesturePlane`'s sibling for the two things that have no layer matrix to read
+ * a basis out of: the transform gizmo's PLANE PADS (whose normal is a design
+ * axis) and its VIEW-PLANE DISC (whose normal is the working camera's own
+ * forward). Both then feed the same `designDelta` a body drag does, so there is
+ * one unprojection in this lane and not three.
+ */
+export function planeAt(
+  point: readonly [number, number, number],
+  normal: readonly [number, number, number],
+): Plane {
+  return new Plane().setFromNormalAndCoplanarPoint(
+    new Vector3(normal[0], normal[1], normal[2]).normalize(),
+    new Vector3(point[0], point[1], point[2]),
+  );
+}
+
 /** Where a ray meets a plane, or null when it is parallel to it (an edge-on
  *  layer) — which is a real case and must not become a NaN delta. */
 export function unproject(ray: Ray, plane: Plane): Vector3 | null {