@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/app/lazyPanel.tsx

@@ -0,0 +1,137 @@
+// ON-DEMAND PANELS: the chrome's load diet (docs/performance-chrome-load-2026-10.md).
+//
+// The entry chunk holds the shell and Studio. Every other workspace, dialog
+// and drawer is a `lazyPanel`: its module (and whatever only it imports, the
+// CodeMirror and React Flow stacks among them) is a chunk fetched the first
+// time it renders. The shell that decides WHETHER it renders stays eager and
+// returns null while it is not wanted, so a closed panel costs nothing.
+//
+// WHY NOT `React.lazy` ALONE. A lazy component suspends on its first render
+// even when its module is already in memory, so a panel the idle prefetch has
+// fetched would still flash its fallback for a frame, and every unit test
+// that mounts a shell would have to await a panel it already imported. Here
+// a loaded module renders in the same commit, and only a real fetch shows the
+// fallback.
+//
+// A FAILED FETCH (a deploy replaced the chunk under an open tab, a dropped
+// connection) throws with a sentence saying what to do, and the boundary's
+// Try again fetches again. EVERY PANEL CARRIES ITS OWN `PanelBoundary`, named by
+// its `label`: several call sites (the right column, the dialogs, the Insert
+// drawer) have no boundary above them but the root's, and a throw there
+// unmounts the whole editor, stage and all, for a chunk that did not arrive.
+import { Suspense, use, useState, type ComponentType, type ReactNode } from "react";
+import { PanelBoundary } from "@dailies-studio/ui";
+
+export interface LazyPanel<P extends object> {
+  (props: P): ReactNode;
+  /** Fetch the module now; safe to call often. */
+  preload(): Promise<unknown>;
+}
+
+/** Every chunk's `preload`, for `preloadPanels`. */
+const preloads: (() => Promise<unknown>)[] = [];
+
+export const PANEL_LOAD_FAILED = "This part of Dailies did not load. Reload the page to get the latest version.";
+
+/**
+ * A chunk several panels come from. They share ONE fetch and one loaded
+ * module, so once any of them has loaded, every other renders at once: the
+ * board's right-column panels never wait on a chunk the board already has.
+ */
+export function lazyChunk<M>(load: () => Promise<M>): {
+  preload: () => Promise<M>;
+  /** A panel from this chunk. `label` names it on the crash card; `fallback`
+   *  is drawn in its place while the fetch runs: the panel's own skeleton, so
+   *  nothing around it moves when it lands. */
+  panel: <P extends object>(label: string, pick: (module: M) => ComponentType<P>, fallback?: ReactNode) => LazyPanel<P>;
+} {
+  let loaded: { module: M } | null = null;
+  let pending: Promise<M> | null = null;
+  // ONE PROMISE PER ATTEMPT. A render that suspended on a fetch that then
+  // failed must meet the SAME rejected promise when React renders it again,
+  // or the error never reaches the boundary: a fresh fetch suspends again,
+  // and the panel refetches its chunk forever behind its skeleton. A failed
+  // attempt is forgotten only by the boundary's catch (so Try again fetches
+  // anew) and by a `preload` that failed (so the next open fetches anew).
+  const attempt = (): Promise<M> =>
+    (pending ??= load().then(
+      (module) => (loaded = { module }).module,
+      (cause: unknown) => {
+        throw new Error(PANEL_LOAD_FAILED, { cause });
+      },
+    ));
+  const preload = (): Promise<M> => {
+    const tried = attempt();
+    tried.catch(() => {
+      if (pending === tried) pending = null;
+    });
+    return tried;
+  };
+  const forget = (): void => {
+    if (loaded === null) pending = null;
+  };
+  preloads.push(preload);
+  const panel = <P extends object>(
+    label: string,
+    pick: (module: M) => ComponentType<P>,
+    fallback: ReactNode = null,
+  ): LazyPanel<P> => {
+    function Body(props: P) {
+      const Panel = pick(loaded === null ? use(attempt()) : loaded.module);
+      return <Panel {...props} />;
+    }
+    function Lazy(props: P) {
+      return (
+        <PanelBoundary label={label} onCatch={forget}>
+          <Suspense fallback={fallback}>
+            <Body {...props} />
+          </Suspense>
+        </PanelBoundary>
+      );
+    }
+    return Object.assign(Lazy, { preload });
+  };
+  return { preload, panel };
+}
+
+/** A panel that is a chunk of its own: `load` resolves to the component. */
+export function lazyPanel<P extends object>(
+  label: string,
+  load: () => Promise<ComponentType<P>>,
+  fallback: ReactNode = null,
+): LazyPanel<P> {
+  return lazyChunk(load).panel(label, (component) => component, fallback);
+}
+
+/**
+ * True from the first render where `on` is true, for the rest of the
+ * component's life. A shell latches its panel: the chunk is fetched the first
+ * time the panel is wanted, and after that the panel stays mounted and gates
+ * itself, exactly as it did when it loaded with the entry, so its state and
+ * its close transition survive.
+ */
+export function useLatch(on: boolean): boolean {
+  const [latched, setLatched] = useState(on);
+  if (on && !latched) setLatched(true);
+  return latched || on;
+}
+
+/** Load every panel declared so far. Tests call it so a mounted shell renders
+ *  its panels in the same commit, as a warm session does. */
+export async function preloadPanels(): Promise<void> {
+  await Promise.all(preloads.map((preload) => preload()));
+}
+
+/**
+ * Run `work` once the page is idle after first paint, so a prefetch never
+ * competes with the boot. Returns a cancel. `requestIdleCallback` is missing
+ * in Safari and jsdom; a timeout stands in.
+ */
+export function whenIdle(work: () => void): () => void {
+  if (typeof window.requestIdleCallback === "function") {
+    const id = window.requestIdleCallback(work, { timeout: 4000 });
+    return () => window.cancelIdleCallback(id);
+  }
+  const id = window.setTimeout(work, 1500);
+  return () => window.clearTimeout(id);
+}

package/src/app/lazySurfaces.tsx

@@ -0,0 +1,203 @@
+// WHAT LOADS ON DEMAND, in one list (docs/performance-chrome-load-2026-10.md).
+//
+// The /scene entry is the shell and Studio. Each surface here is a chunk the
+// shell fetches the first time it is wanted (app/lazyPanel.tsx): the
+// Storyboard, Components, Code Studio with CodeMirror, the material nodes
+// with React Flow, the Library, Export, Version history, Preferences and
+// Insert, the font picker, the inspector's two template sections, and the
+// Agent and Comments panels. Timeline views that load when
+// they open (Sound, Graph, Generate) are declared beside the dock that shows
+// them (TimelineDock.tsx).
+//
+// Each export keeps the name of the panel it stands for, so a call site reads
+// as it did when the panel loaded with the entry. A GATED one is that panel's
+// eager shell: null until the panel is first wanted, then latched (`useLatch`)
+// so the panel gates itself from there on. The others are mounted by a call
+// site that already decides when.
+//
+// A FALLBACK IS THE PANEL'S OWN SKELETON, drawn in the panel's place while
+// its chunk loads, so nothing around it moves when it lands. A LABEL names
+// the panel on the crash card its own boundary draws when the chunk does not
+// arrive (lazyPanel.tsx).
+import { useSyncExternalStore } from "react";
+import type { ComponentType, ReactNode } from "react";
+import { useShotEditor, useStore } from "../state/context.js";
+import type { ShotEditorState } from "../state/types.js";
+import { workspaceOf } from "../state/workspace.js";
+import { InCell } from "../panels/stage/cellSlots.js";
+import { lazyChunk, lazyPanel, useLatch, type LazyPanel } from "./lazyPanel.js";
+
+// One chunk each: a surface's panels share their imports, and the board's
+// right-column panels must be ready the moment the board is.
+const storyboard = lazyChunk(() => import("../panels/storyboard/board.js"));
+const components = lazyChunk(() => import("../panels/studio/components.js"));
+
+/** A shell: null until `wanted` first holds, then the panel, for good. */
+function gated<P extends object>(Panel: LazyPanel<P>, wanted: (s: ShotEditorState) => boolean): ComponentType<P> {
+  return function Gate(props: P) {
+    return useLatch(useShotEditor(wanted)) ? <Panel {...props} /> : null;
+  };
+}
+
+/** Draws `children` only while `wanted` holds: a skeleton for a surface that
+ *  was left before its chunk arrived must not stand over the next one. */
+function While({ wanted, children }: { wanted: (s: ShotEditorState) => boolean; children: ReactNode }) {
+  return useShotEditor(wanted) ? children : null;
+}
+
+const onBoard = (s: ShotEditorState): boolean => workspaceOf(s) === "storyboard";
+const inComponents = (s: ShotEditorState): boolean => workspaceOf(s) === "components";
+const inCode = (s: ShotEditorState): boolean => inComponents(s) && s.codeComponent !== null && s.componentsTab === "edit";
+const inMaterial = (s: ShotEditorState): boolean => workspaceOf(s) === "material";
+
+/** The board's skeleton: its bar and the empty desk, in the canvas cell. */
+const BOARD_SKELETON = (
+  <While wanted={onBoard}>
+    <InCell name="centre">
+      <div className="board-skeleton" aria-busy="true">
+        <div className="panel-head" />
+      </div>
+    </InCell>
+  </While>
+);
+
+/** A mode's skeleton: its left column with its head, and its canvas. */
+function modeSkeleton(wanted: (s: ShotEditorState) => boolean): ReactNode {
+  return (
+    <While wanted={wanted}>
+      <InCell name="left">
+        <div className="mode-skeleton" aria-busy="true">
+          <div className="panel-head" />
+        </div>
+      </InCell>
+      <InCell name="centre">
+        <div className="mode-skeleton is-canvas" aria-busy="true" />
+      </InCell>
+    </While>
+  );
+}
+
+/** A right-column panel that brings its own head: the head, on the column's
+ *  ground. */
+const HEAD_SKELETON = <div className="panel-head" aria-busy="true" />;
+
+// ── THE STORYBOARD ──────────────────────────────────────────────────────────
+export const StoryboardView = gated(
+  storyboard.panel("Storyboard", (m) => m.StoryboardView, BOARD_SKELETON),
+  onBoard,
+);
+export const ComponentSheet = storyboard.panel("Component sheet", (m) => m.ComponentSheet, HEAD_SKELETON);
+export const PlanOccupant = storyboard.panel("Plan", (m) => m.PlanOccupant, HEAD_SKELETON);
+export const SketchInspector = storyboard.panel("Sketch inspector", (m) => m.SketchInspector, HEAD_SKELETON);
+/** The inspector's section for a board card (InspectorPanel), shown only on
+ *  the board, so it rides in the board's chunk. */
+export const StoryboardReferenceSection = storyboard.panel("Card", (m) => m.StoryboardReferenceSection);
+
+/** Fetch the Storyboard while the page is idle, so the first switch to it is
+ *  as quick as every later one. */
+export const prefetchStoryboard = storyboard.preload;
+
+// ── THE INSPECTOR'S ON-DEMAND SECTIONS, fetched at idle ────────────────────
+/** "Template field" (one text, image or video layer), "Make it yours" (no
+ *  selection, a Project with fields) and "Motion" (the motion presets, every
+ *  layer), drawn by InspectorPanel. Each is a chunk of its own, kept out of
+ *  the entry's budget, and fetched at idle like the Storyboard
+ *  (`prefetchInspectorSections`, App.tsx), so a selection made after that
+ *  draws it in the same commit; before it lands it draws nothing. */
+export const TemplateFieldSection = lazyPanel("Template field", () =>
+  import("../panels/inspector/design/TemplateFieldSection.js").then((m) => m.TemplateFieldSection),
+);
+export const MakeItYoursSection = lazyPanel("Make it yours", () =>
+  import("../panels/inspector/scene/MakeItYoursSection.js").then((m) => m.MakeItYoursSection),
+);
+export const PresetsSection = lazyPanel("Motion", () =>
+  import("../panels/inspector/animate/PresetsSection.js").then((m) => m.PresetsSection),
+);
+export const prefetchInspectorSections = (): Promise<unknown> =>
+  Promise.all([
+    TemplateFieldSection.preload(),
+    MakeItYoursSection.preload(),
+    PresetsSection.preload(),
+    // The stamp the Motion section's picks run (`applyMotionPreset`).
+    import("../state/motionStamp.js"),
+  ]);
+
+// ── COMPONENTS AND CODE ─────────────────────────────────────────────────────
+// Preview and the Studio share a chunk and load together, so the Preview
+// shell, mounted for the whole workspace, draws the one skeleton.
+export const ComponentsPreview = gated(
+  components.panel("Components", (m) => m.ComponentsPreview, modeSkeleton(inComponents)),
+  inComponents,
+);
+export const ComponentStudio = gated(
+  components.panel("Component studio", (m) => m.ComponentStudio),
+  inComponents,
+);
+export const CodeStudio = gated(
+  lazyPanel("Code studio", () => import("../panels/code/CodeStudio.js").then((m) => m.CodeStudio), modeSkeleton(inCode)),
+  inCode,
+);
+
+// ── THE MATERIAL NODES ──────────────────────────────────────────────────────
+export const MaterialWorkspace = gated(
+  lazyPanel("Material workspace", () => import("../panels/material/MaterialWorkspace.js").then((m) => m.MaterialWorkspace), modeSkeleton(inMaterial)),
+  inMaterial,
+);
+
+// ── DIALOGS AND DRAWERS: on open ───────────────────────────────────────────
+export const LibraryBrowser = gated(
+  lazyPanel("Library", () => import("../panels/library/LibraryBrowser.js").then((m) => m.LibraryBrowser)),
+  (s) => s.libraryBrowserOpen,
+);
+export const PreferencesDialog = gated(
+  lazyPanel("Preferences", () => import("../panels/preferences/PreferencesDialog.js").then((m) => m.PreferencesDialog)),
+  (s) => s.prefsOpen,
+);
+export const InsertDrawer = gated(
+  lazyPanel("Insert", () => import("../panels/insert/InsertDrawer.js").then((m) => m.InsertDrawer)),
+  (s) => s.insertDrawer !== null && !s.readOnly,
+);
+/** Mounted by App only while `exportOpen`. */
+export const ExportDialog = lazyPanel("Export", () => import("../panels/export/ExportDialog.js").then((m) => m.ExportDialog));
+/** Mounted by RightColumn only while `versionsOpen`; it takes the column,
+ *  head and all. */
+export const VersionHistoryPanel = lazyPanel(
+  "Version history",
+  () => import("../panels/versions/VersionHistoryPanel.js").then((m) => m.VersionHistoryPanel),
+  HEAD_SKELETON,
+);
+
+const AgentQuestionPanel = lazyPanel("Agent question", () =>
+  import("../panels/agent/AgentQuestionDialog.js").then((m) => m.AgentQuestionDialog),
+);
+/** The agent's question to the person (state/agentQuestion.ts): its chunk
+ *  loads the first time a question opens, or a studio server render starts
+ *  for an export ask (the chunk reports it when it ends), and stays.
+ *  Unconditional in App, whatever workspace is on screen. */
+export function AgentQuestionDialog() {
+  const store = useStore();
+  const wanted = useSyncExternalStore(store.agentQuestion.subscribe, () => {
+    const s = store.agentQuestion.getState();
+    return s.open || s.exportAsk?.serverJob !== undefined;
+  });
+  return useLatch(wanted) ? <AgentQuestionPanel /> : null;
+}
+
+// ── THE FONT PICKER: on open ───────────────────────────────────────────────
+/** Mounted by the inspector's Font field (FontField.tsx) only while open,
+ *  inside the field box; its module owns the Popover. Preloaded as the pointer
+ *  or focus reaches the field. Its skeleton is a ring in the box's accessory
+ *  lane, where a write's progress sits. */
+export const FontPicker = lazyPanel(
+  "Font picker",
+  () => import("../panels/fonts/FontPicker.js").then((m) => m.FontPicker),
+  <span className="field-accessory">
+    <span className="font-field-wait" aria-busy="true" />
+  </span>,
+);
+
+// ── THE AGENT AND COMMENTS: on first open ──────────────────────────────────
+/** Kept mounted by RightColumn after its first open, under an `<Activity>`. */
+export const AgentPanel = lazyPanel("Agent", () => import("../panels/agent/AgentPanel.js").then((m) => m.AgentPanel));
+/** Mounted by RightColumn while the Comments tab is the occupant. */
+export const CommentsPanel = lazyPanel("Comments", () => import("../panels/comments/CommentsPanel.js").then((m) => m.CommentsPanel));

package/src/audio/index.tsx

@@ -10,11 +10,13 @@
 // state (session, never document), so the dock head's controls and this bridge
 // read one bit and cannot disagree.
 import { useEffect } from "react";
+import { MIX_SAMPLE_RATE } from "@dailies-studio/engine";
 import { useStore } from "../state/context.js";
+import { transportAudible } from "../state/types.js";
 import { createAudioPreview } from "./preview.js";
 import type { AudioContextLike, AudioPreview, AudioPreviewDeps } from "./preview.js";
 
-export { SCRUB_JUMP_FRAMES, createAudioPreview } from "./preview.js";
+export { DRIFT_FRAMES, createAudioPreview } from "./preview.js";
 export type {
   AudioBufferLike,
   AudioBufferSourceNodeLike,
@@ -26,17 +28,22 @@ export type {
   TransportSnapshot,
 } from "./preview.js";
 
-async function fetchBytes(url: string): Promise<ArrayBuffer> {
-  const res = await fetch(url);
+async function fetchBytes(url: string, priority?: "low"): Promise<ArrayBuffer> {
+  const res = await fetch(url, { priority: priority ?? "auto" });
   if (!res.ok) throw new Error(`GET ${url} -> ${res.status}`);
   return res.arrayBuffer();
 }
 
+/** ONE offline context decodes every clip, so a decode ahead needs no realtime
+ *  context, and none exists before a press. At the export mix's rate. */
+let decoder: OfflineAudioContext | null = null;
+
 const browserDeps: AudioPreviewDeps = {
-  // Lazy: the first play edge is the user gesture that may create the context.
+  // Lazy: the first press (a queued Play's arm, or the play edge) creates it.
   createContext: () => new AudioContext() as unknown as AudioContextLike,
   fetchBytes,
-  decode: (ctx, bytes) => (ctx as unknown as AudioContext).decodeAudioData(bytes),
+  // A COPY, because `decodeAudioData` detaches the buffer it is handed.
+  decode: (bytes) => (decoder ??= new OfflineAudioContext(2, 1, MIX_SAMPLE_RATE)).decodeAudioData(bytes.slice(0)),
 };
 
 /** `create` is the test seam; production gets Web Audio. */
@@ -49,6 +56,35 @@ export function AudioPreviewBridge(props: { create?: () => AudioPreview } = {}):
     let volume: number | null = null;
     const push = (): void => {
       const s = store.getState();
+      // THE TRANSPORT FIRST. An unmute reschedules against the snapshot the
+      // scheduler holds, so it has to hold THIS one: pushing the monitor bits
+      // first anchored a session on the frame from the PREVIOUS notification
+      // whenever the two changed together. The comment here used to argue the
+      // opposite order for the same reason, and had the dependency backwards.
+      preview.update({
+        playing: s.playing,
+        frame: s.frame,
+        doc: s.doc,
+        // ONE PREDICATE, and it is not this file's. A component context drives
+        // a definition-local clock and never moves `frame`; a shuttle rate
+        // other than 1 would need reversed buffers or a time stretcher. Both
+        // are "the picture's clock and the audio clock would disagree", which
+        // is why they are decided together in `transportAudible` (state/types
+        // .ts) rather than assembled here out of two field reads.
+        audible: transportAudible(s),
+        scene: s.enteredScene,
+        // Per-tab monitoring: the bridge is the one place solo reaches.
+        solo: s.soloTracks,
+        // A queued Play (bridge v51). The store notifies inside the `set`
+        // that arms it, which is the press, so the context wakes there.
+        armed: s.playIntent !== null,
+        // The instant the transport started, which the picture clock counts
+        // from too (Header.tsx).
+        origin: s.playOrigin,
+        // A stage attached that owes the open subject no picture: the ready
+        // edge the decode ahead waits for.
+        presented: s.stageInfo !== null && !s.stageBusy,
+      });
       if (s.previewMuted !== muted) {
         muted = s.previewMuted;
         preview.setMasterMute(muted);
@@ -57,11 +93,6 @@ export function AudioPreviewBridge(props: { create?: () => AudioPreview } = {}):
         volume = s.previewVolume;
         preview.setMasterVolume(volume);
       }
-      // AFTER the monitor bits: an unmute that reschedules must do so knowing
-      // the transport it is rescheduling against, and `update` is what records
-      // it. On the very first push both orders agree, because the scheduler
-      // starts paused.
-      preview.update({ playing: s.playing, frame: s.frame, doc: s.doc });
     };
     push();
     const unsub = store.subscribe(push);