@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/state/unsavedGuard.ts

@@ -0,0 +1,49 @@
+import { useEffect } from "react";
+import type { SaveState } from "./types.js";
+
+/**
+ * Whether work exists that is NOT on disk.
+ *
+ * `dirty` covers the ordinary case: the autosave debounce is 400ms
+ * (`AUTOSAVE_MS`), and a tab closed inside that window takes the edit with it.
+ *
+ * `saveState === "error"` is the case that matters more, and it is the reason
+ * this guard is not optional. `runSave` deliberately does NOT retry a failed
+ * save: the failure that gets there is a 409 against a baseline someone else
+ * moved, and re-sending the same rev would be the corruption rather than the
+ * cure. Refusing "keeps the document open, in memory, with the reason already
+ * on screen" — a design that assumes the document survives until the author
+ * acts on it. Nothing enforced that assumption, so the recovery path this
+ * chrome carefully preserves could be closed away by a keystroke.
+ *
+ * A save in flight needs no separate case: `dirty` is cleared only on success,
+ * so it is still true while "saving".
+ */
+export function unsavedWorkPending(dirty: boolean, saveState: SaveState, syncUnstored: boolean | null = null): boolean {
+  // LIVE SYNC: an edit is safe once it is in IndexedDB, acked or not, so the
+  // guard warns only while one is not (`ShotEditorState.syncUnstored`).
+  return syncUnstored ?? (dirty || saveState === "error");
+}
+
+/**
+ * Arm the browser's own close confirmation while unsaved work exists.
+ *
+ * Deliberately only `beforeunload`. A `pagehide` handler cannot await, so the
+ * flush it started would be abandoned mid-request, and a blind re-PUT of a
+ * moved rev is exactly the write `runSave` refuses to make. The prompt is the
+ * guarantee; there is no partial save behind it.
+ */
+export function useUnsavedWorkGuard(dirty: boolean, saveState: SaveState, syncUnstored: boolean | null = null): void {
+  const pending = unsavedWorkPending(dirty, saveState, syncUnstored);
+  useEffect(() => {
+    if (!pending) return;
+    const onBeforeUnload = (event: BeforeUnloadEvent): void => {
+      // preventDefault is the modern spelling; returnValue is what older
+      // engines read. Neither carries custom text any more, by design.
+      event.preventDefault();
+      event.returnValue = "";
+    };
+    window.addEventListener("beforeunload", onBeforeUnload);
+    return () => window.removeEventListener("beforeunload", onBeforeUnload);
+  }, [pending]);
+}

package/src/state/viewMode.ts

@@ -0,0 +1,200 @@
+// EDIT AND VIDEO: the two words the editor offers for "what am I doing", and
+// the three questions the rest of the chrome asks about them.
+//
+// ── VIDEO IS A FLAG OVER THE PICTURE, NOT A PANE ───────────────────────────
+//
+// Video is the export's frame with the authoring taken off it: no handles, no
+// hover outline, no marquee, no drawing, no drags. Edit is that same editor
+// with all of it back. The transport runs in both.
+//
+// It was spelled as a PANE LAYOUT — Edit meant `working`, Video meant `camera`
+// — and that could not survive contact with the stage. The rect, ellipse,
+// line, text, image and pen tools draw in the CAMERA pane and nowhere else
+// (`StageApp`'s draw lane), and so do the move, resize and rotate handles. The
+// working pane is the 3D viewport: orbit, gizmo, frustum, the G/R/S modals. So
+// "Video is the camera pane" made drawing impossible in the view that could
+// not play and possible in the one that could, and `toolRefusal` was left
+// telling authors to press 3 for Video in order to draw a rectangle.
+//
+// The two ideas are orthogonal, so they are two fields:
+//
+//   `state.video`            am I watching, or working
+//   `state.stageLayout.mode` WHICH EDITOR — the 3D viewport, the split, or the
+//                            frame. Keys ⇧1 / ⇧2 / ⇧3, the View menu, and the
+//                            thing Video is drawn over and hands back.
+//
+// The stage still speaks `working | split | camera` (`stage/panes.ts`) and the
+// bridge versions that vocabulary, because those are PANES. Nothing here
+// renames them; what changed is that they stopped being asked a question they
+// could not answer.
+//
+// ── AND THE WAY OUT OF VIDEO IS ANY EDIT ───────────────────────────────────
+//
+// Every selection verb, the document seam, both scrub lanes, the tool arm and
+// the four "go somewhere to work" doors call the store's `enterEdit()`. So the
+// author never meets a dead control: the click that would have edited lands in
+// Edit, paused, on the frame they were watching.
+import type { ShotEditorState } from "./types.js";
+import type { StageLayout } from "../stage/panes.js";
+
+/** The value the segmented control shows, and the value its two options carry.
+ *  Its own two words rather than a `StageLayout["mode"]`: what this names is
+ *  what the author is DOING, and the layout underneath is a separate choice
+ *  with three answers (see `setViewLayout`). */
+export type ViewMode = "edit" | "video";
+
+export interface ViewModeSpec {
+  /** The word, which is also the toggle's accessible name (it is a glyph),
+   *  the View menu's row, the help sentences and the key table's line. */
+  label: string;
+  /** What gets you there, in the house glyphs. Not a pair: ⇧4 goes to the
+   *  picture and Escape comes back, because Escape already means "put the
+   *  editor back" everywhere else in this chrome. */
+  key: string;
+  /** The physical key, for the one of the two the keymap reads by `code`
+   *  (⇧4 types "$" on a US board and "4" on AZERTY). */
+  code?: string;
+  /** The App menu row, for the one of the two that has one. Edit is not a row:
+   *  the menu carries Video as a CHECKBOX, because Video is drawn over Edit
+   *  rather than chosen instead of it. */
+  menuId?: string;
+}
+
+/**
+ * The two words, in the order the work is: you build a thing and then you
+ * watch it.
+ *
+ * Same bargain as `state/layouts.ts` and `tools.ts` — one literal, every
+ * surface derives. The bar, the menu row and the key lane all read these, so
+ * the flag cannot be "Clean view" on the control while the menu still says
+ * Video. The GLYPHS stay in the bar: `state/` is JSX-free on purpose.
+ *
+ * "Clean view", not "Video" (2026-10-13 design review): the footer draws the
+ * flag as an eye toggle beside the layouts, and what it does is take the
+ * authoring furniture off the frame. The state, the verb and the key keep
+ * their old names (`state.video`, `setVideo`, ⇧4), so nothing persisted or
+ * bridged moves. Edit has no control of its own any more: it is the toggle
+ * off, and Escape.
+ */
+export const VIEW_MODE_SPECS = {
+  edit: { label: "Edit", key: "Esc" },
+  video: { label: "Clean view", key: "⇧4", code: "Digit4", menuId: "view.video" },
+} as const satisfies Record<ViewMode, ViewModeSpec>;
+
+/** Both words, in control order. */
+export const VIEW_MODES = Object.keys(VIEW_MODE_SPECS) as readonly ViewMode[];
+
+/**
+ * The author is standing above every shot: arranging the cut, not authoring
+ * inside one.
+ *
+ * The store has this predicate too (`inSceneContext`), closed over its own
+ * state; this is the same sentence for the chrome readers that cannot reach
+ * it. `editingDef` is part of it because a definition opened from the scene
+ * level is a container the author IS inside.
+ */
+export function isSceneContext(s: ShotEditorState): boolean {
+  return s.doc !== null && s.enteredScene === null && s.editingDef === null;
+}
+
+/** Inside a component definition: a container with its own clock and no shot
+ *  camera. The third context, and the one every layout verb refuses. */
+export function inDefinition(s: Pick<ShotEditorState, "editingDef">): boolean {
+  return s.editingDef !== null;
+}
+
+/** Inside a shot, authoring its elements. The complement of the two above,
+ *  spelled once because five panels were each deriving it from two fields. */
+export function inShotContext(s: Pick<ShotEditorState, "enteredScene" | "editingDef">): boolean {
+  return s.enteredScene !== null && s.editingDef === null;
+}
+
+/**
+ * WHICH CLOCK AN EDIT IS ON: a definition plays on its own frame, everything
+ * else on the document's.
+ *
+ * Nine call sites wrote this ternary out. It is one rule — an edit inside a
+ * container is timed by that container — and getting it wrong writes a
+ * keyframe at the wrong frame with no error, which is the kind of bug an
+ * author reports as "the animation is off" a week later.
+ *
+ * A `Pick` and not the whole state, so the timeline's own narrow row objects
+ * and `store.getState()` both fit. Three sites that LOOK like this rule are
+ * deliberately not routed here: the dock's lane frame subtracts a row origin
+ * on one arm, the material graph compares `editingDef` to its container id
+ * rather than to null, and the inspector's hook reads the COALESCED frame.
+ */
+export function authoringFrame(
+  s: Pick<ShotEditorState, "editingDef" | "defFrame" | "frame">,
+): number {
+  return s.editingDef !== null ? s.defFrame : s.frame;
+}
+
+/**
+ * Is there a shot camera here at all — a picture Video could be OF?
+ *
+ * A component definition, Code Studio and the material graph each put
+ * something that is not the film on the stage: a definition plays on its own
+ * clock (`defFrame`) and the stage forces the working-only layout while one is
+ * open, and the other two frame one subject into a hole in the canvas cell. None of
+ * them has a Video to be in, so every question below forks on this first.
+ *
+ * The store keeps the author OUT of that ambiguity rather than resolving it:
+ * opening any of the three calls `enterEdit()` on the way in, so `video` is
+ * never true underneath one. This predicate is what makes that reachable.
+ */
+export function hasVideo(s: ShotEditorState): boolean {
+  return (
+    s.doc !== null &&
+    s.editingDef === null &&
+    s.codeComponent === null &&
+    s.materialWorkspace === null
+  );
+}
+
+/**
+ * VIDEO IS ON SCREEN: the picture is the export's and nothing is drawn over
+ * it. What the control lights, what the stage draws, and what the keys ask
+ * before they refuse.
+ */
+export function videoView(s: ShotEditorState): boolean {
+  return hasVideo(s) && s.video;
+}
+
+/** Which of the two words is lit. */
+export function viewModeOf(s: ShotEditorState): ViewMode {
+  return videoView(s) ? "video" : "edit";
+}
+
+/**
+ * WHICH PANES ARE ON SCREEN, which is not the same as which layout is chosen.
+ *
+ * Video draws the frame over whatever Edit was showing without writing it, so
+ * a reader that asked `stageLayout.mode` while watching would answer for a
+ * viewport nobody can see: the shading bar would offer to change an invisible
+ * pane's mode, the split divider would draw a handle across the picture, and
+ * `toolRefusal` would tell an author looking at the frame that the frame is
+ * not on screen. Every one of those asks this instead.
+ *
+ * The verbs that WRITE the layout keep reading `stageLayout.mode`: what they
+ * change is the editor underneath, which is still there.
+ */
+export function shownLayoutMode(s: ShotEditorState): StageLayout["mode"] {
+  return videoView(s) ? "camera" : s.stageLayout.mode;
+}
+
+/**
+ * THE LAYOUT THE TOOLS ARE JUDGED AGAINST (`toolRefusal`): what is on screen,
+ * except inside a definition.
+ *
+ * There the stage draws one pane whatever layout the Shot left stashed (layout
+ * verbs are refused in a definition, so the stash carries in), and that pane
+ * plays both roles: the frame the box tools and the pen draw on, and the 3D
+ * view the spline draws in. Every tool's pane is on screen, which is the
+ * split's answer. Asking `shownLayoutMode` there judged the tools against a
+ * layout nothing draws: Rect refused or armed depending on where the Shot was
+ * left, and Spline refused in the pane it works in.
+ */
+export function toolLayoutMode(s: ShotEditorState): StageLayout["mode"] {
+  return inDefinition(s) ? "split" : shownLayoutMode(s);
+}