@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/state/layoutPrefs.ts

@@ -0,0 +1,272 @@
+// The workspace layout — three panel sizes and three collapse flags —
+// remembered across reloads.
+//
+// `workspacePrefs` in the store already carries these six across a DOCUMENT
+// switch, which is the right instinct applied to the wrong boundary: the
+// layout is a fact about the person and their screen, not about the film they
+// happen to have open. An author who dragged the dock tall to read a curve had
+// it back at 300 the moment they refreshed the tab, which is why the reach for
+// the handle became a habit rather than a decision.
+//
+// ONE KEY HOLDING ONE OBJECT, not six keys. The six move together — every one
+// of them is answering "how much of this window is chrome" — so there is no
+// case where half of them should be restored and the other half not, and a
+// single `setItem` is also the whole of the write cost this module adds.
+//
+// Guarded on both sides, like `editorPrefs`: private mode and a locked-down
+// storage policy each throw on access, and a preference is never worth an
+// exception. A read that fails answers `{}`, which is "no opinion" — `bootLayout`
+// then fits the window, which is the state the chrome had before this existed.
+//
+// ── A SIZE THIS WINDOW CANNOT HONOUR IS SUSPENDED, NOT OVERWRITTEN ────────
+//
+// `bootLayout` puts a saved size through the SETTERS so the bounds this session
+// enforces win over whatever storage remembers: a 600px dock dragged on a
+// desktop arrives on a 700px laptop as 490, and that is right — a dock with no
+// stage behind it is worse than a short dock. But the store was then the only
+// copy of that number, so the next thing the author moved wrote 490 back as if
+// they had chosen it, and reconnecting the monitor did not bring the 600 back.
+// A size suspended for one session had become a size deleted.
+//
+// So the RECORD and the LIVE VALUE are allowed to disagree. A size this boot
+// could not apply as written is held aside and re-written verbatim on every
+// save, until the author drags that panel — at which point the number on screen
+// is theirs, about this window, and the held one is dropped for good. Nothing
+// else moves: the session still runs at the clamped size, `authorLayout` still
+// keeps the window's own fitted numbers out of the record, and focus mode's
+// collapse is still not a preference.
+//
+// That buys the module its one ORDERING rule. `persistLayoutPrefs` reads the
+// record itself and compares it against the store, so it has to be called AFTER
+// `bootLayout` (main.tsx does, and says why). Subscribe first and the boot's own
+// application of the record is indistinguishable from a drag — see the test.
+import { layoutFor } from "./panelSize.js";
+import type { BootLayoutPrefs } from "./panelSize.js";
+import type { ShotEditorStore } from "./store.js";
+
+/** The one key, exported so the suite asserts against THIS string rather than
+ *  a second copy of it. A test that retypes the name still passes when the
+ *  name here changes, and a renamed key silently forgets every saved layout. */
+export const WORKSPACE_PREFS_KEY = "dailies.workspace";
+
+const SIZE_FIELDS = ["railWidth", "inspectorWidth", "dockHeight"] as const;
+const COLLAPSE_FIELDS = [
+  "railCollapsed",
+  "inspectorCollapsed",
+  "dockCollapsed",
+] as const;
+
+type SizeField = (typeof SIZE_FIELDS)[number];
+
+/** A size the author chose (`chosen`) and the one this boot left in its place
+ *  (`boot`); see `suspendedSizes`. */
+interface SuspendedSize {
+  chosen: number;
+  boot: number;
+}
+
+/**
+ * The saved layout, validated FIELD BY FIELD rather than object by object.
+ *
+ * A whole-object check would make one bad number throw away a good one, and
+ * the object is exactly the shape most likely to go half-bad: it is written by
+ * an older build, hand-edited in devtools, or truncated by a quota error
+ * mid-write. `bootLayout` already treats every field as independently absent,
+ * so an unusable `dockHeight` is best expressed as a missing one — the author
+ * keeps the rail they dragged and gets a fitted dock.
+ *
+ * Numbers must be FINITE: `JSON.parse` cannot produce a NaN, but it happily
+ * produces `1e400` as `Infinity`, and an infinite width reaches `clampSize`,
+ * which answers `min` — silently the wrong panel rather than no opinion.
+ */
+export function readLayoutPrefs(): BootLayoutPrefs {
+  let parsed: unknown;
+  try {
+    const text = localStorage.getItem(WORKSPACE_PREFS_KEY);
+    if (text === null) return {};
+    parsed = JSON.parse(text);
+  } catch {
+    return {};
+  }
+  if (typeof parsed !== "object" || parsed === null) return {};
+  const saved = parsed as Record<string, unknown>;
+  const prefs: BootLayoutPrefs = {};
+  for (const field of SIZE_FIELDS) {
+    const value = saved[field];
+    if (typeof value === "number" && Number.isFinite(value))
+      prefs[field] = value;
+  }
+  for (const field of COLLAPSE_FIELDS) {
+    const value = saved[field];
+    if (typeof value === "boolean") prefs[field] = value;
+  }
+  return prefs;
+}
+
+export function writeLayoutPrefs(prefs: BootLayoutPrefs): void {
+  try {
+    localStorage.setItem(WORKSPACE_PREFS_KEY, JSON.stringify(prefs));
+  } catch {
+    /* storage disabled or full — the session still honours the drag, it just forgets */
+  }
+}
+
+/**
+ * The layout as the AUTHOR has it, which is not the layout the store has.
+ *
+ * Two things in the state look like a preference and are not, and saving
+ * either hands the next session a decision nobody made.
+ *
+ * A FITTED SIZE IS THE WINDOW'S OPINION. Seeding the signature after
+ * `bootLayout` only defers that: `App`'s resize refit puts the NEW fitted
+ * numbers through the very setters a drag uses, so docking a 1366 laptop to a
+ * 2560 monitor would save 232/288/300, and the next boot on the laptop would
+ * prefer that record over the fit — permanently, because 232 is no longer the
+ * fitted number and refit reads it as a panel the author dragged. The test
+ * here is the one refit already uses: a panel holding exactly `layoutFor`'s
+ * number is a panel nobody has dragged. A drag that lands on the fitted value
+ * to the pixel is indistinguishable from no drag, and being re-fitted next
+ * time is the right answer for it anyway.
+ *
+ * A COLLAPSED PANEL MAY BE FOCUS MODE'S. Video at the scene level collapses
+ * both side rails and records what it found in `focusRestore*`; the collapse
+ * verbs null that slot the moment the author takes ownership. So a non-null
+ * slot reads exactly "this bit is the mode's, and here is the author's", the
+ * same rule `workspacePrefs` carries across a document switch. Without it a
+ * reload taken in Video comes back with those rails collapsed and no pending
+ * restore to bring them back: the mode's opinion promoted to a preference.
+ *
+ * THE DOCK HAS NO SLOT, because no view collapses the timeline. A collapsed
+ * dock is always the author's, so it is recorded as it stands.
+ *
+ * A SUSPENDED SIZE IS STILL THE AUTHOR'S. `held` carries the sizes this boot
+ * clamped (see `suspendedSizes`); while a panel is untouched they answer for it
+ * instead of the store, so the record keeps the number the author picked rather
+ * than the one this window allowed. This function is where the suspension is
+ * RELEASED as well as read — it is the only place that sees every notification
+ * with the store beside it, and a `held` entry outliving its panel's first drag
+ * would pin the record to a number the author has since replaced.
+ */
+function authorLayout(
+  store: ShotEditorStore,
+  held: Map<SizeField, SuspendedSize>,
+): BootLayoutPrefs {
+  const s = store.getState();
+  const prefs: BootLayoutPrefs = {
+    railCollapsed: s.focusRestoreRail ?? s.railCollapsed,
+    inspectorCollapsed: s.focusRestoreInspector ?? s.inspectorCollapsed,
+    dockCollapsed: s.dockCollapsed,
+  };
+  // No window is no fit to compare against, so nothing can be ruled out as
+  // the window's doing — same fallback posture as `setDockHeight`.
+  const fitted =
+    typeof window === "undefined"
+      ? null
+      : layoutFor(window.innerWidth, window.innerHeight);
+  for (const field of SIZE_FIELDS) {
+    const suspended = held.get(field);
+    if (suspended !== undefined) {
+      // Still exactly what the boot left it at, so the author has said nothing
+      // about this panel since: the record keeps the size they last chose.
+      if (s[field] === suspended.boot) {
+        prefs[field] = suspended.chosen;
+        continue;
+      }
+      // They have dragged it. Permanently — a later drag back onto the boot
+      // value is a statement about THIS window and belongs in the record.
+      held.delete(field);
+    }
+    if (fitted === null || s[field] !== fitted[field]) prefs[field] = s[field];
+  }
+  return prefs;
+}
+
+/**
+ * The sizes the boot did not apply as written, kept out of the record's way.
+ *
+ * Read at subscribe time, which is the one moment the record on disk and the
+ * store agree about what the author asked for: `bootLayout` has just put each
+ * saved size through the setters, so a field the store does not hold verbatim
+ * is a field this session refused — the dock past `dockCeiling` on a shorter
+ * window, or any size a build with different bounds once allowed.
+ *
+ * The refit gets no exception. It only touches a panel still holding the number
+ * `layoutFor` gave it, and a clamp lands on a BOUND: 168/460 for the rail,
+ * 264/480 for the inspector, neither of which `layoutFor` returns. The dock is
+ * the one that can coincide: under ~536px of window its fit is also its 120
+ * floor (`layoutFor` stays under the footer's ceiling), so a sub-minimum record
+ * clamps onto the fitted number, and under ~472px the boot's own ceiling is that
+ * number too, so any record does. On a window that short the
+ * refit is what releases the suspension and the record falls back to fitted.
+ * That is a viewport with no editor left in it, and the price is one forgotten
+ * size, so it is named here rather than coded around.
+ *
+ * ONE READ, no argument. `main.tsx` already has the record in hand, but adding
+ * a parameter would let a caller pass a record that is not the one the boot
+ * saw, which is the only input that could make this lie. A second `getItem` at
+ * startup is cheaper than that.
+ */
+function suspendedSizes(store: ShotEditorStore): Map<SizeField, SuspendedSize> {
+  const s = store.getState();
+  const saved = readLayoutPrefs();
+  const held = new Map<SizeField, SuspendedSize>();
+  for (const field of SIZE_FIELDS) {
+    const chosen = saved[field];
+    if (chosen !== undefined && chosen !== s[field])
+      held.set(field, { chosen, boot: s[field] });
+  }
+  return held;
+}
+
+/**
+ * Keep storage in step with the store for the life of the page.
+ *
+ * ── WHY THE SIGNATURE AND NOT JUST THE SUBSCRIPTION ───────────────────────
+ *
+ * `subscribe` is the raw channel: it fires on EVERY observable change, and
+ * during playback that is once per frame for the transport tick alone. A
+ * `setItem` per frame is a synchronous serialise-and-store sixty times a
+ * second for a value that has not moved since the author last let go of a
+ * handle. So the write is gated on `authorLayout` actually changing, which is
+ * the only event this module cares about.
+ *
+ * The signature is SEEDED at subscribe time, after `bootLayout` has run, so a
+ * boot that only restored what was already on disk writes nothing. What keeps
+ * the window's own opinions OUT of the record is `authorLayout`, not the seed.
+ *
+ * CALL IT AFTER `bootLayout`. The seed is also where `suspendedSizes` compares
+ * the record against the store, and before the boot there is nothing to
+ * compare: the boot's own application of a saved size then arrives as a change
+ * like any other, and a size it clamps is written back clamped — the loss the
+ * suspension exists to prevent. It is an ordering rule, not a guess, so it is
+ * stated here and in `main.tsx` rather than defended against.
+ */
+export function persistLayoutPrefs(store: ShotEditorStore): () => void {
+  const held = suspendedSizes(store);
+  let last = authorLayout(store, held);
+  // A RAW subscription: this runs on every store notification, sixty times a
+  // second while the transport plays and once per coalesced pointermove of
+  // every drag. It used to `JSON.stringify` the record each time to detect a
+  // change that only ever happens on a panel resize; six `Object.is` reads is
+  // the same answer.
+  return store.subscribe(() => {
+    const prefs = authorLayout(store, held);
+    if (sameLayoutPrefs(prefs, last)) return;
+    last = prefs;
+    writeLayoutPrefs(prefs);
+  });
+}
+
+const LAYOUT_PREF_KEYS: readonly (keyof BootLayoutPrefs)[] = [
+  "railWidth",
+  "inspectorWidth",
+  "dockHeight",
+  "railCollapsed",
+  "inspectorCollapsed",
+  "dockCollapsed",
+];
+
+function sameLayoutPrefs(a: BootLayoutPrefs, b: BootLayoutPrefs): boolean {
+  for (const key of LAYOUT_PREF_KEYS) if (!Object.is(a[key], b[key])) return false;
+  return true;
+}

package/src/state/layouts.ts

@@ -0,0 +1,205 @@
+// THE LAYOUT TABLE: the three editors Edit can show, and every word, key, menu
+// id and refusal sentence that names one of them.
+//
+// ── WHY THIS FILE EXISTS ────────────────────────────────────────────────
+//
+// Renaming the third layout from "Frame" to "Camera" (founder order,
+// 2026-09-05) cost edits in the toolbar, the View menu, the shortcut table,
+// two refusal sentences in `keymap.ts`, the store's error strip, four tests
+// and two docs — and STILL left the in-app manual teaching the withdrawn
+// word, because nothing tied the manual's prose to the control's chip. Every
+// one of those files had written the same three rows out by hand.
+//
+// So the rows live here once, exactly the way `tools.ts` holds the tool rows:
+// one literal, `as const satisfies Record<...>`, and every list, lookup and
+// sentence below DERIVED from it. A layout cannot be renamed on one surface
+// and not another, because no surface owns a word any more.
+//
+// ── THREE SPELLINGS PER LAYOUT IS THE FACT, NOT THE BUG ─────────────────
+//
+// The chip says "3D", the menu row and the manual say "3D view", and a clause
+// in the middle of a sentence says "the 3D view". Those are three different
+// jobs: a word in a 36px segmented track, a row that has to read as a noun
+// beside "Split", and a fragment inside "…this layout shows ___ only". The
+// table carries all three so that the SURFACES stop inventing a fourth.
+//
+// ── WHY NOT IN `stage/panes.ts` ─────────────────────────────────────────
+//
+// The stage owns the MODES (`StageLayoutMode` there is the vocabulary the
+// bridge versions and the scissor reads); this file owns what the CHROME
+// calls them. The stage has no business carrying a menu id, and the chrome
+// has no business inventing a fourth mode. Types flow one way: this file
+// imports the union, never the reverse.
+import type { StageLayoutMode, StagePane } from "../stage/panes.js";
+
+export interface LayoutSpec {
+  /** The segmented control's chip. Short: the three sit in one track beside
+   *  the Edit and Video glyphs, and the track does not grow. */
+  label: string;
+  /** The App menu row and the manual's own name for it. Reads as a noun on
+   *  its own, which "3D" does not. */
+  title: string;
+  /** The same layout inside a sentence, article included: "this layout shows
+   *  ___ only". Written out rather than composed from `title` because "the
+   *  split" is not "the Split" and English will not derive that. */
+  noun: string;
+  /** The combo that goes there, in the house glyphs ("⇧1"). The manual, the
+   *  menu accelerator, the tooltips and the refusal sentences all print THIS,
+   *  so a rebind is one edit here. */
+  key: string;
+  /** The physical key the combo is pressed on, which is what `keymap.ts`
+   *  reads (`layoutForEvent`). Shift turns "1" into "!" on a US board and
+   *  leaves it "1" on AZERTY, so the character is no witness to the key. */
+  code: string;
+  /** The App menu row's id, which is also how `shortcuts.ts` points a row at
+   *  a menu entry and how the menu asks for its accelerator. */
+  menuId: string;
+  /** The manual's line for the key. One sentence, no trailing stop: the
+   *  shortcut table's other rows have none either. */
+  does: string;
+}
+
+/**
+ * The three layouts, IN KEY ORDER (⇧1, ⇧2, ⇧3), which is also the order the
+ * toolbar draws them and the order the View menu lists them.
+ *
+ * `Object.keys` on an object literal is insertion order for string keys, so
+ * `LAYOUT_MODES` below inherits that order rather than restating it. The
+ * `satisfies` is what makes a fourth mode in `stage/panes.ts` a compile error
+ * here instead of a layout with no word for it.
+ */
+export const LAYOUT_SPECS = {
+  working: {
+    label: "3D",
+    title: "3D view",
+    noun: "the 3D view",
+    key: "⇧1",
+    code: "Digit1",
+    menuId: "view.layout.working",
+    does: "3D view",
+  },
+  split: {
+    label: "Split",
+    title: "Split",
+    noun: "the split",
+    key: "⇧2",
+    code: "Digit2",
+    menuId: "view.layout.split",
+    // Names the other two through the table rather than spelling them, so the
+    // manual's description of the split cannot outlive their names.
+    does: "Split (the 3D view with the camera beside it)",
+  },
+  camera: {
+    label: "Camera",
+    title: "Camera",
+    noun: "the camera view",
+    key: "⇧3",
+    code: "Digit3",
+    menuId: "view.layout.camera",
+    does: "Camera: the shot camera's picture, with handles",
+  },
+} as const satisfies Record<StageLayoutMode, LayoutSpec>;
+
+/** Every layout, in key order. The cast is the one place this file asserts
+ *  what `satisfies` has already proved: the literal above is the only writer
+ *  of the object and its key set IS `StageLayoutMode`, which `Object.keys`
+ *  cannot say because its return type is `string[]` for every object. */
+export const LAYOUT_MODES = Object.keys(LAYOUT_SPECS) as readonly StageLayoutMode[];
+
+/**
+ * One row, seen as a `LayoutSpec` rather than as its own literal type.
+ *
+ * `as const satisfies` narrows every row to exactly the strings it wrote,
+ * which is excellent for the table and useless for anything iterating it.
+ * This is the one widening, and it is in one place — the same bargain
+ * `specOf` makes in `tools.ts`.
+ */
+export function layoutSpec(mode: StageLayoutMode): LayoutSpec {
+  return LAYOUT_SPECS[mode];
+}
+
+/** Keyed on the physical key, built from the table so a rebind cannot leave
+ *  the key lane pointing at the old one. */
+const BY_CODE: ReadonlyMap<string, StageLayoutMode> = new Map(
+  LAYOUT_MODES.map((mode) => [LAYOUT_SPECS[mode].code, mode]),
+);
+
+/**
+ * THE KEYMAP'S WHOLE LAYOUT LANE: the layout this event picks, or null when
+ * no layout claims it.
+ *
+ * SHIFTED, AND BY `code`. The bare digits are left free for the editor's
+ * numeric verbs, and a shifted digit reports a different character on every
+ * keyboard layout ("!" on US, "1" on AZERTY), so only the physical key names
+ * it. The keymap asks this after the modifier lanes, so ⌘ and ⌥ never reach
+ * it; the shift is checked here because the bare digit must not match.
+ */
+export function layoutForEvent(event: { shiftKey: boolean; code?: string }): StageLayoutMode | null {
+  if (!event.shiftKey || event.code === undefined) return null;
+  return BY_CODE.get(event.code) ?? null;
+}
+
+/**
+ * The TAIL every "this layout cannot do that" refusal shares, given the pane
+ * that IS on screen.
+ *
+ * ── WHY A FRAGMENT AND NOT A SENTENCE ───────────────────────────────────
+ *
+ * Three callers refuse for three different reasons and each owns its own lead
+ * clause: a tool says "Rect draws in the camera view, and …", the menu says
+ * "That aims the 3D view, and …", the key lane says "that key aims the 3D
+ * view, and …" (lower case, because the store prefixes the strip's own word).
+ * Only the second half is one rule, so only the second half is shared. A
+ * function that returned the whole sentence would have to take the lead as an
+ * argument, which is the same duplication with extra steps.
+ *
+ * What it says: which view you are looking at, the key for the other one,
+ * and the key for the split that has both. The keys are in the house glyphs
+ * ("⇧1"); a caller that shows the sentence runs it through `formatCombo`, which
+ * this file cannot import (`shortcuts.ts` imports this one). Every one of those comes out of
+ * the table, so renaming a layout or rebinding a digit rewrites all three
+ * refusals with no edit here.
+ */
+export function paneOnlyRefusal(shown: StagePane): string {
+  const here = LAYOUT_SPECS[shown];
+  const other = LAYOUT_SPECS[shown === "camera" ? "working" : "camera"];
+  const split = LAYOUT_SPECS.split;
+  return (
+    `this layout shows ${here.noun} only. ` +
+    `Press ${other.key} for ${other.noun}, or ${split.key} for ${split.noun}.`
+  );
+}
+
+/**
+ * Why a view the author asked for cannot be entered here, or null when it can.
+ *
+ * Its own sentence rather than an arm of `toolRefusal`: these are not tools,
+ * and what is refused is a VIEW rather than a place to draw.
+ *
+ * ONE REFUSAL LEFT. This used to turn the 3D view and the split away above a
+ * shot too ("the scene view has one pane"), and that was withdrawn by founder
+ * order on 2026-09-05: all three layouts are live at the scene level, where
+ * the working pane draws the shot under the playhead, exactly as the stage
+ * already resolved it (`StageApp` reads `masterToSceneCached`, never the
+ * entered shot). What remains is the definition, which has no shot camera at
+ * all.
+ *
+ * It lives beside the table rather than in `keymap.ts` because the three
+ * things that ask it — the digits, the segmented control and the View menu —
+ * are the three things that read the table, and the answer is about layouts
+ * rather than about keys.
+ */
+export function layoutRefusal(inDefinition: boolean): string | null {
+  // A DEFINITION HAS NO SHOT CAMERA AT ALL, so neither Video nor a layout over
+  // it names anything it can show. The stage forces the working-only layout
+  // while one is open (StageApp's `inComponent`), so without this the keys
+  // (and the control that shares this rule) changed a mode nothing read and
+  // then reported it as active.
+  if (inDefinition) {
+    return (
+      `A component definition has no shot camera, so there is nothing to ` +
+      `switch to. Leave the definition (Esc) to get Edit and Video back.`
+    );
+  }
+  return null;
+}

package/src/state/measureMedia.ts

@@ -0,0 +1,167 @@
+// The one impure half of "a dropped recording should land at its own aspect":
+// asking the browser to decode enough of an image or a video to report how wide
+// and how tall it is.
+//
+// ── WHY IT IS NOT IN insert.ts ──────────────────────────────────────────────
+//
+// That file's contract is stated in its own header: no document, no history, no
+// asynchrony, no DOM. That is exactly what makes `boxOf` provable by calling it,
+// and a throwaway `<video>` on an object URL is all four of the things it
+// forbids. So the measurement happens here, the number crosses as
+// `InsertContext.sourceAspect`, and the geometry stays pure.
+//
+// ── WHY IT NEVER REJECTS, AND WHY IT HAS A DEADLINE ─────────────────────────
+//
+// Every failure resolves to `null`, and `null` reproduces the pre-aspect
+// geometry byte for byte. That is not defensiveness, it is the requirement:
+//
+//   - jsdom, which the editor's own test lane runs in, decodes no media at all.
+//     `loadedmetadata` never fires and `videoWidth` stays 0. Without a deadline
+//     the existing `completeImageDraw` tests would each become a 30s timeout
+//     (the fast lane's own `testTimeout`), which is a suite that "still passes"
+//     while taking four minutes to say so.
+//   - A real browser fails too: a codec it cannot decode, a file that is not
+//     the media its extension claims, a revoked blob.
+//
+// Nothing here is on the render path and nothing here reaches a document, so a
+// wrong answer costs a badly proportioned box the author can drag. A HANG would
+// cost the insert itself, which is why the deadline is not optional.
+//
+// ── NOT PERSISTED ON THE ASSET ──────────────────────────────────────────────
+//
+// `ShotAsset` is `{id, path, hash, kind}` and stays that way. Storing width and
+// height would mean a probe at upload (ffmpeg, which the CLI only shells for
+// audio today), a schema field, and two places that can disagree about one
+// file's dimensions. The runtime already learns the real size from the decoded
+// texture; this is only the INSERT's guess at a good starting box.
+
+/** How long a decode may take before the insert gives up and uses the default
+ *  geometry. Long enough for a large local file to report metadata, short
+ *  enough that a host which will never answer (jsdom) does not stall a click. */
+const MEASURE_TIMEOUT_MS = 2000;
+
+/** The slice of the media elements this needs. Named so a test can hand over a
+ *  fake without a DOM, the same seam `textureCache` uses for its videos. */
+export interface MeasurableElement {
+  addEventListener(type: string, listener: () => void): void;
+  removeEventListener(type: string, listener: () => void): void;
+}
+
+export interface MeasureDeps {
+  /** Absent = `URL.createObjectURL` / `URL.revokeObjectURL`. */
+  objectUrl?: { create: (file: Blob) => string; revoke: (url: string) => void };
+  /** Absent = a real `<video>` or `<img>`. */
+  createElement?: (kind: "image" | "video") => MeasurableElement;
+  setTimeout?: (fn: () => void, ms: number) => unknown;
+  clearTimeout?: (handle: unknown) => void;
+}
+
+/**
+ * width / height of the media at `url`, or null if it cannot be determined.
+ *
+ * NEVER REJECTS. See the header: every failure path is a `null` that puts the
+ * caller back on the geometry it had before this function existed.
+ */
+export async function measureMediaUrl(
+  url: string,
+  kind: "image" | "video",
+  deps: MeasureDeps = {},
+): Promise<number | null> {
+  const create =
+    deps.createElement ??
+    ((k: "image" | "video") =>
+      (k === "video"
+        ? Object.assign(document.createElement("video"), { preload: "metadata", muted: true })
+        : document.createElement("img")) as unknown as MeasurableElement);
+  const later = deps.setTimeout ?? ((fn: () => void, ms: number) => globalThis.setTimeout(fn, ms));
+  const cancel = deps.clearTimeout ?? ((h: unknown) => globalThis.clearTimeout(h as number));
+
+  return new Promise<number | null>((resolve) => {
+    let settled = false;
+    let timer: unknown = null;
+    const el = create(kind);
+    // The event that says the dimensions exist. A video reports them at
+    // `loadedmetadata`, which is well before it could play; an image at `load`.
+    const ready = kind === "video" ? "loadedmetadata" : "load";
+
+    const finish = (aspect: number | null): void => {
+      if (settled) return;
+      settled = true;
+      if (timer !== null) cancel(timer);
+      el.removeEventListener(ready, onReady);
+      el.removeEventListener("error", onError);
+      // The src is cleared so a video that has not finished buffering stops,
+      // and so the element drops its reference to a URL the caller is about to
+      // revoke. Guarded, because a fake element has no `src`.
+      try {
+        (el as unknown as { src?: string }).src = "";
+      } catch {
+        // A fake with a getter-only `src`. Nothing to release.
+      }
+      resolve(aspect);
+    };
+
+    function onReady(): void {
+      const e = el as unknown as { videoWidth?: number; videoHeight?: number; naturalWidth?: number; naturalHeight?: number };
+      // Chosen BY KIND rather than by `videoWidth ?? naturalWidth`. The
+      // coalesce works only because a real `<img>` has no `videoWidth` at all,
+      // which makes it correct by accident: anything exposing both (a fake, a
+      // polyfill, a future element) reads the video pair's 0 and reports
+      // nothing. The kind is already known here, so ask for the right pair.
+      const w = (kind === "video" ? e.videoWidth : e.naturalWidth) ?? 0;
+      const h = (kind === "video" ? e.videoHeight : e.naturalHeight) ?? 0;
+      // `!(...)` so a NaN from a host that reports one lands here rather than
+      // becoming a NaN aspect the geometry would then have to defend against.
+      finish(!(w > 0) || !(h > 0) ? null : w / h);
+    }
+    function onError(): void {
+      finish(null);
+    }
+
+    el.addEventListener(ready, onReady);
+    el.addEventListener("error", onError);
+    timer = later(() => finish(null), MEASURE_TIMEOUT_MS);
+    try {
+      (el as unknown as { src: string }).src = url;
+    } catch {
+      finish(null);
+    }
+  });
+}
+
+/**
+ * The same, for a `File` the author just picked: wraps it in an object URL and
+ * always revokes it, including on the timeout path.
+ *
+ * A blob left unrevoked pins the whole file in memory for the tab's lifetime,
+ * and this runs on a path whose files are screen recordings.
+ */
+export async function measureMediaFile(
+  file: Blob,
+  kind: "image" | "video",
+  deps: MeasureDeps = {},
+): Promise<number | null> {
+  const urls = deps.objectUrl ?? {
+    create: (f: Blob) => URL.createObjectURL(f),
+    revoke: (u: string) => {
+      URL.revokeObjectURL(u);
+    },
+  };
+  let url: string;
+  try {
+    url = urls.create(file);
+  } catch {
+    return null; // a host with no object-URL support measures nothing
+  }
+  try {
+    return await measureMediaUrl(url, kind, deps);
+  } finally {
+    try {
+      urls.revoke(url);
+    } catch {
+      // Already gone. Revoking twice is not an error worth surfacing.
+    }
+  }
+}
+
+export { MEASURE_TIMEOUT_MS };