@dailies-studio/shot-editor 0.1.0

package/src/state/triangles.ts

@@ -0,0 +1,70 @@
+// What a scene's geometry costs, and when to say something about it.
+//
+// ── WHY A BUDGET AT ALL ─────────────────────────────────────────────────
+//
+// A model's triangle count is the one authoring decision in this lane that can
+// make the editor unusable, and it is the one an author has no way to see. A
+// GLB is a file with a name; nothing on screen distinguishes a 4k-triangle prop
+// from a 900k-triangle scan until the pane stops keeping up, and by then the
+// document is built around it.
+//
+// ── AND WHY THE TWO NUMBERS ARE WHAT THEY ARE ───────────────────────────
+//
+// The split viewport draws the scene ONCE PER PANE, so an authored count is
+// doubled before it reaches the GPU, and every one of those frames is a
+// re-draw the author is watching happen under their hands.
+//
+//   SOFT 500k (1M drawn) is where a per-commit redraw stops being instant on
+//   integrated graphics with this lane's unlit single-pipeline materials. It
+//   WARNS: the outliner tints the badges and the title says why. A hard block
+//   here would refuse work that renders perfectly well on a workstation.
+//
+//   HARD 2M (4M drawn) is where even discrete hardware drops below a usable
+//   frame rate for a drag. It refuses the INSERT — the moment a model is added
+//   is the only moment refusing costs nothing, because nothing has been built
+//   on it yet. An already-heavy document still opens and still edits: a cap
+//   that locked an author out of their own file would be the worse failure.
+//
+// Both are reasoned from how the lane draws rather than measured on target
+// hardware, and the HUD's `tris` readout is what will eventually replace the
+// reasoning with numbers.
+export const TRIANGLE_SOFT_BUDGET = 500_000;
+export const TRIANGLE_HARD_CAP = 2_000_000;
+
+/**
+ * The scene's total.
+ *
+ * A SUM OVER LOADED MODELS, and it under-counts on purpose in one place: a
+ * cloner draws its subtree N times and this counts it once. Multiplying would
+ * need the clone count at this level, which is a document walk for a number
+ * whose job is to be a rough warning.
+ *
+ * ponytail: multiply by clone count when someone ships a cloned model heavy
+ * enough that the badge disagrees with the frame rate.
+ */
+export function sumTriangles(byLayer: Readonly<Record<string, number>>): number {
+  let total = 0;
+  for (const n of Object.values(byLayer)) total += n;
+  return total;
+}
+
+/** `12.4k`, `1.2M`. Short enough for a row that already carries an icon, a
+ *  name and two toggles. */
+export function formatTriangles(count: number): string {
+  if (count >= 1_000_000) return `${(count / 1_000_000).toFixed(1)}M`;
+  if (count >= 1_000) return `${(count / 1_000).toFixed(count >= 10_000 ? 0 : 1)}k`;
+  return String(count);
+}
+
+/** The soft-budget message, on the badge's own title. */
+export function sceneBudgetWarning(total: number): string {
+  return (
+    `THIS SCENE CARRIES ${total.toLocaleString()} TRIANGLES. ` +
+    `ABOVE ${TRIANGLE_SOFT_BUDGET.toLocaleString()} THE WORKING PANE STOPS FEELING INSTANT.`
+  );
+}
+
+/** The insert refusal, verbatim. */
+export const TRIANGLE_CAP_REFUSAL =
+  `A SCENE HOLDS AT MOST ${TRIANGLE_HARD_CAP.toLocaleString()} TRIANGLES. ` +
+  `REMOVE OR SIMPLIFY A MODEL BEFORE ADDING ANOTHER.`;

package/src/state/types.ts

@@ -0,0 +1,384 @@
+// The shot chrome's state shape. ONE document, flat fields.
+//
+// ── WHY THERE ARE NO BOARDS ───────────────────────────────────────────────
+//
+// The canvas lane keeps N documents open on an infinite pasteboard because a
+// Doc2D is a COMPONENT and a project holds dozens. A shot document is a
+// DELIVERABLE VIDEO; Raylight's "many things at once" is scenes INSIDE one
+// document, which is the timeline's macro lane, not a pasteboard.
+//
+// The non-aesthetic reason is `GL_CONTEXT_BUDGET = 12` (cli/src/pageCount.ts):
+// a measured per-origin browser ceiling on live WebGL contexts whose failure
+// mode is a SILENT WEDGE, not an error. Every mounted shot owns a `<Canvas>`.
+// The canvas lane never had that ceiling because its boards are DOM.
+//
+// So: one document, flat fields, and roughly 1700 lines of board machinery
+// simply not written. Autosave debounce, the sha256 rev and the generation
+// fence all still apply — they were never board-shaped, only board-keyed.
+import { DOCK_HEIGHT, RAIL_WIDTH } from "./panelSize.js";
+import type { Doc3D } from "@dailies-studio/shot/doc";
+import type { AgentCredentialsInfo, AgentTranscriptItem } from "@dailies-studio/agent-client";
+import type { Contract } from "@dailies-studio/contract";
+import type { ComponentRow, RenderJob, ShotListing } from "../api.js";
+import type { ShadingMode, ShotStageInfo, ShotView, StageLayout, StagePane, WorkingView } from "../bridgeTypes.js";
+import { INITIAL_WORKING_VIEW } from "../stage/workingView.js";
+import type { DrawPoint } from "./insert.js";
+import type { ShotTool } from "../tools.js";
+
+export type SaveState = "idle" | "saving" | "saved" | "error";
+
+export interface ShotEditorState {
+  /** Everything in `.studio/shots/`, for the switcher. */
+  shots: readonly ShotListing[];
+  /** The open document's store name, or null at the empty state. */
+  name: string | null;
+  doc: Doc3D | null;
+  /** The rev the open document was READ at, and the baseline every save
+   *  claims. null = nothing open, or a create that has not landed yet. */
+  rev: string | null;
+
+  /** MASTER frame. Integer, always. */
+  frame: number;
+  playing: boolean;
+
+  /** Which scene the micro timeline and the inspector are looking at. This is
+   *  the SINGLE bit that decides macro vs micro, and it is the same bit the URL
+   *  mirrors — one two-level model, not two. */
+  sceneId: string | null;
+  /** Layer ids, in document order, deduped. */
+  selection: readonly string[];
+
+  /** Which tool is armed. Decides what a canvas press does, and which plane a
+   *  move unprojects onto. */
+  tool: ShotTool;
+
+  /**
+   * TWO MODE BITS, and collapsing them would be a data-corrupting surprise.
+   *
+   * `inspectorMode` is a VIEW choice, set by clicking the inspector's tabs.
+   * `animateMode` is a BEHAVIOUR choice, set ONLY by ⇧A: with it on, a canvas
+   * drag authors a BLOCK ending at the playhead instead of writing the base.
+   *
+   * One bit would mean that clicking "Animate" to LOOK at the blocks silently
+   * arms block authoring on the next drag.
+   */
+  inspectorMode: "design" | "animate";
+  animateMode: boolean;
+
+  /**
+   * The block the dock has focused, or null.
+   *
+   * Addressed by (scene, layer, block) even though a block id is unique across
+   * the document. The layer is what tells a row which lane it is in without a
+   * lookup; the SCENE is what stopped being derivable when the dock became one
+   * master strip. `state.sceneId` follows the playhead, so a block clicked in
+   * scene 3 while the playhead sits in scene 1 would have sent Delete and Split
+   * at scene 1 — where the id does not exist, so both would have silently done
+   * nothing.
+   */
+  selectedBlock: { sceneId: string; layerId: string; blockId: string } | null;
+  /**
+   * The marker the strip has selected, or null.
+   *
+   * A BARE ID, unlike `selectedBlock`: a marker belongs to the document rather
+   * than to a scene (`MarkerRef.frame` is a master frame), so there is nothing
+   * to address it relative to and nothing that can go stale under a retime.
+   *
+   * It is the FIRST subject Delete and the inspector consult — see
+   * `deleteSelection`. Any layer selection clears it, so "click a layer, press
+   * Delete" can never remove a marker the author stopped looking at.
+   */
+  selectedMarker: string | null;
+  /**
+   * The box a drawn IMAGE layer is waiting to land in, or null.
+   *
+   * The image tool draws its box first and asks for a file second, and a file
+   * dialog can only be opened from a real click on a real `<input>` — which the
+   * store is not. So the geometry parks here and the toolbar's hidden input
+   * picks it up; `completeImageDraw` is the other half. Never persisted, never
+   * a document edit: nothing exists yet.
+   */
+  imagePick: readonly DrawPoint[] | null;
+  /**
+   * The stage's last right press, or null. A MAILBOX, not a menu.
+   *
+   * Fresh identity per event, so `StageMenu`'s effect fires again when the
+   * author right-clicks a second time at the same point on the same layer —
+   * value equality here would silently swallow the second menu.
+   *
+   * Cleared by `onActivePane`, which is the seam EVERY stage press and wheel
+   * already crosses. It has to be cleared from the stage side: a pointerdown
+   * inside the iframe is a different document's event and never reaches the
+   * chrome window's outside-click listener.
+   */
+  stageMenu: { at: { x: number; y: number }; hits: readonly string[]; pane: StagePane } | null;
+  /**
+   * The mesh layers a material pick would be applied to, or null when the
+   * picker is closed. Editor state: nothing exists in the document until a
+   * card is chosen.
+   */
+  materialPicker: { layerIds: readonly string[] } | null;
+  /**
+   * Triangle counts by mesh layer id, pushed up from the stage as models load.
+   *
+   * The chrome is three-free by test, so it cannot count them itself. Held here
+   * rather than derived because the count is a property of the loaded GLB, not
+   * of the document: two layers on one asset report the same number, and a
+   * layer whose model has not arrived yet reports nothing at all.
+   */
+  meshTriangles: Readonly<Record<string, number>>;
+  /**
+   * The subtree being edited in isolation, or null for the whole scene.
+   *
+   * EDITOR STATE, never a document field. It scopes three things at once — the
+   * working pane's camera, what is pickable, and what is dimmed — and all three
+   * derive from this ONE id rather than from copies, so they cannot disagree
+   * about what the author is inside.
+   *
+   * Validated on every document write (`onHistoryChange`): a delete, an undo or
+   * an agent edit can take the layer away, and an isolation pointing at nothing
+   * is a pane framing nothing with everything else unpickable.
+   */
+  isolation: string | null;
+  /**
+   * Inside isolation, the AUTHOR owns the working camera.
+   *
+   * False is the entry state: the derived orthographic head-on rig draws the
+   * pane, which is the only camera that can frame a rolled or face-down card.
+   * The first orbit, pan or dolly flips this and the ordinary perspective orbit
+   * rig takes over — Blender's local view scopes what you SEE and leaves the
+   * camera free, and this is that.
+   *
+   * Home and numpad-dot clear it, so head-on is the RESET rather than a cage.
+   * Entering another subtree clears it too (`setIsolation` on the stage does
+   * the same on its own side), so a second card always opens head-on.
+   *
+   * WORKSPACE STATE. It is meaningless while `isolation` is null, and
+   * `writeFramingFromView` reads the pair to decide whether the pose it is
+   * about to project onto the shot camera is one anybody can see.
+   */
+  isolationOrbit: boolean;
+  /** The shading the working pane was in before the current one, so ⇧Z can
+   *  toggle wireframe and come BACK rather than stranding the author in it. */
+  previousShading: ShadingMode;
+  /**
+   * The component definition the OUTLINE is scoped to, or null for the scene.
+   *
+   * Separate from `isolation` on purpose. Isolation is a SPATIAL move — the
+   * working pane frames a subtree that is on screen — and a definition's layers
+   * are in no scene and have no camera at all. Conflating them would make
+   * "what am I looking at" and "what am I editing" one field that has to answer
+   * both, and the answer for a definition would be a camera pointing at
+   * nothing.
+   *
+   * Cleared with the other selection bits on document close, and validated on
+   * every write beside `isolation` — a definition can be deleted too.
+   */
+  editingDef: string | null;
+  /** The export dialog is open. A store bit rather than local state, because
+   *  the keymap opens it (⌘E) and the header's button toggles it, and two
+   *  places holding "is it open" is one place for them to disagree. */
+  exportOpen: boolean;
+  /**
+   * The live (or most recent) render, mirrored off the SSE bus.
+   *
+   * Held in the STORE and not in the dialog, so closing the dialog does not
+   * lose the render: the header keeps showing progress and the author can walk
+   * away from the modal without cancelling anything.
+   */
+  renderJob: RenderJob | null;
+  // ── the agent drawer ─────────────────────────────────────────────────────
+  //
+  // Held in the STORE and not in the panel, for the reason the render job is:
+  // closing the drawer must not cancel a running turn or lose its transcript.
+  agentOpen: boolean;
+  agentItems: readonly AgentTranscriptItem[];
+  agentRunning: boolean;
+  agentError: string | null;
+  /** The session the CURRENT turn is streaming. Apply targets the session
+   *  that MINTED a card, which is carried on the card itself — this is only
+   *  for cancel. */
+  agentSessionId: string | null;
+  /** A per-chrome model override, or null for the server's default. */
+  agentModel: string | null;
+  agentCostUsd: number | null;
+  agentCredentials: AgentCredentialsInfo | null;
+  agentCredentialsError: string | null;
+  /** Hidden, not unmounted — see TimelineDock. */
+  dockCollapsed: boolean;
+  /** The two side rails, hidden so the stage can be seen. Unlike the dock
+   *  these ARE unmounted (`display: none`): they hold no live geometry that a
+   *  remount would lose, and the widths they occupy are variables the control
+   *  strip and the dock position themselves against. */
+  railCollapsed: boolean;
+  inspectorCollapsed: boolean;
+  /**
+   * What entering the working view auto-collapsed, per panel: the collapse
+   * value to restore on leaving, or null when there is nothing pending —
+   * either the mode is not on, or the author toggled that panel themselves
+   * inside it and took ownership (the collapse verbs null the slot).
+   */
+  focusRestoreInspector: boolean | null;
+  focusRestoreDock: boolean | null;
+  /** Dragged sizes, in PIXELS — see state/panelSize.ts for why not `vh`. */
+  railWidth: number;
+  dockHeight: number;
+  /** Pixels per frame in the dock. The unit @dailies-studio/timeline's geometry
+   *  and `useAnchoredZoom` both speak, so there is no second zoom scale. */
+  dockPpf: number;
+
+  /**
+   * PREVIEW audio, and only preview: the monitoring level in this browser tab.
+   *
+   * Never the document, and the distinction is load-bearing. `clip.gain` and
+   * `clip.muted` are the mix and they are exported; these two are the author
+   * turning their speakers down, and an export that got quieter because
+   * somebody muted their monitor would be the worst kind of silent corruption.
+   * They ride `workspacePrefs` with the rest of "where the author is standing".
+   */
+  previewMuted: boolean;
+  /** Linear, 0..1. */
+  previewVolume: number;
+
+  /** The stage's working-area view. Owned by the stage, mirrored here so the
+   *  zoom readout has something to read and "fit" has something to write. */
+  view: ShotView;
+  /**
+   * How many views the stage is showing, and how the width is divided.
+   *
+   * A WORKSPACE PREF, listed in `workspacePrefs`: it survives a document switch
+   * and never dirties the document. The split is where the author is standing,
+   * not something about the shot — and a layout that reset on every open would
+   * be a setting nobody could keep.
+   */
+  stageLayout: StageLayout;
+  /** The working pane's orbit camera. A workspace pref for the same reason, and
+   *  additionally: it is EDITOR STATE that must never reach an export. */
+  workingView: WorkingView;
+  /** Which pane the author last acted in. The zoom controls and the fit
+   *  shortcut point at it, so it follows the POINTER and not the selection. */
+  activePane: StagePane;
+  /**
+   * "Camera follows this view": orbiting the working pane writes the shot
+   * camera's framing continuously.
+   *
+   * A WORKSPACE PREF like the other two, and deliberately NOT called a lock.
+   * The word says "nothing can move" when what is true is the opposite — the
+   * camera is being moved by everything you do. It is armed only by its own
+   * control, never as a side effect of entering a mode, for the reason
+   * `animateMode` is: a bit that silently makes drags write the document must
+   * be turned on on purpose.
+   */
+  cameraFollowsView: boolean;
+  /**
+   * The WORKING pane's shading (solid / wireframe / material / rendered).
+   *
+   * A workspace pref like the layout: how the author looks at the scene, never
+   * something about the shot. The camera pane is not addressable — it is
+   * always the graded render, which is what makes "preview === export" a
+   * sentence with no footnotes.
+   */
+  shadingMode: ShadingMode;
+  /** What the stage reported on ready, or null before it did. */
+  stageInfo: ShotStageInfo | null;
+  /** A stage connect or runtime failure, for the overlay strip. */
+  stageError: string | null;
+
+  // ── the component registry, for `instance` layers ────────────────────────
+  /** Every registry row, whatever its host: the ADD menu filters to "three",
+   *  and the inspector needs the others in order to SAY why a layer's target
+   *  no longer qualifies rather than reporting it as missing. */
+  library: readonly ComponentRow[];
+  /** Has `GET /api/components` ever ANSWERED? "loading finished" is not the
+   *  same thing — a FAILED fetch also ends with an empty list, and judging an
+   *  instance against that would report every one of them as an unknown
+   *  component, which is a claim nobody established. */
+  libraryLoaded: boolean;
+  libraryError: string | null;
+  /** Lazily fetched contracts by component id — the inspector's row source. */
+  contracts: Readonly<Record<string, Contract>>;
+
+  saveState: SaveState;
+  /** Unsaved edits exist. Separate from `saveState` because a save that is
+   *  in flight while a new edit lands is BOTH "saving" and dirty. */
+  dirty: boolean;
+  /** The last API failure, in words the author can act on. */
+  error: string | null;
+  /** Codegen refused to overwrite a hand-edited generated file. Sticky until
+   *  the next clean save, because it means the .tsx on disk no longer matches
+   *  the document — which is exactly the thing an author must not miss. */
+  emitWarning: string | null;
+
+  canUndo: boolean;
+  canRedo: boolean;
+}
+
+export const INITIAL_VIEW: ShotView = { zoom: 1, panX: 0, panY: 0 };
+
+/** Camera only, because that is the pane that IS the export: an editor that
+ *  opened onto a working pane would open onto a view of the shot that is not
+ *  the shot. */
+export const INITIAL_STAGE_LAYOUT: StageLayout = { mode: "camera", splitRatio: 0.5 };
+
+export const INITIAL_STATE: ShotEditorState = {
+  shots: [],
+  name: null,
+  doc: null,
+  rev: null,
+  frame: 0,
+  playing: false,
+  sceneId: null,
+  selection: [],
+  isolation: null,
+  isolationOrbit: false,
+  previousShading: "solid",
+  editingDef: null,
+  tool: "select",
+  inspectorMode: "design",
+  animateMode: false,
+  selectedBlock: null,
+  selectedMarker: null,
+  imagePick: null,
+  stageMenu: null,
+  materialPicker: null,
+  meshTriangles: {},
+  exportOpen: false,
+  renderJob: null,
+  agentOpen: false,
+  agentItems: [],
+  agentRunning: false,
+  agentError: null,
+  agentSessionId: null,
+  agentModel: null,
+  agentCostUsd: null,
+  agentCredentials: null,
+  agentCredentialsError: null,
+  dockCollapsed: false,
+  railCollapsed: false,
+  inspectorCollapsed: false,
+  focusRestoreInspector: null,
+  focusRestoreDock: null,
+  railWidth: RAIL_WIDTH.default,
+  dockHeight: DOCK_HEIGHT.default,
+  dockPpf: 6,
+  previewMuted: false,
+  previewVolume: 1,
+  view: INITIAL_VIEW,
+  stageLayout: INITIAL_STAGE_LAYOUT,
+  workingView: INITIAL_WORKING_VIEW,
+  activePane: "camera",
+  cameraFollowsView: false,
+  shadingMode: "solid",
+  stageInfo: null,
+  stageError: null,
+  library: [],
+  libraryLoaded: false,
+  libraryError: null,
+  contracts: {},
+  saveState: "idle",
+  dirty: false,
+  error: null,
+  emitWarning: null,
+  canUndo: false,
+  canRedo: false,
+};