@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/state/posterCapture.ts

@@ -0,0 +1,242 @@
+// The dashboard's debounced poster attempt after a save.
+//
+// ── WHY THE EDITOR AND NOT THE SERVER ────────────────────────────────────
+//
+// The hosted lane has no server renderer, so the stage is the only thing that
+// can draw a poster. It captures the poster frame exactly as a Tier-1 export
+// captures a frame (export framing, then the in-draw snapshot), because the
+// GL framebuffer is unpreserved and a late read of it can be black.
+//
+// The trade is named: for that one capture the stage shows export framing,
+// the same swap an in-browser export makes. So the poster never holds the
+// stage against the author: the stage answers null while they are playing,
+// exporting, preparing Play or inside a component, and anything they start on
+// it mid-capture (Play, an export, a scrub, an edit, a press) aborts the
+// capture, which also answers null (`capturePoster`, bridgeClient.ts).
+//
+// Locally this stays inert: the CLI renders every card's poster itself
+// through its pinned Chromium (`posterStore.ts`), so an upload from here would
+// be a second writer for the same picture.
+//
+// ── A POSTER IS OWED UNTIL IT LANDS ──────────────────────────────────────
+//
+// A save makes the open Project's poster owed. Null means "not now", so the
+// owed poster is asked for again a settle later, for as long as that Project
+// stays open; a stage whose capture failed for a document answers null for it
+// at once until the document changes, so asking again costs nothing. A hidden
+// tab presents nothing, so the ask waits for the tab to come back. And the
+// menu's ways out of the editor run an owed poster before they leave
+// (`flushPoster`), because the save that just landed is usually the last one.
+//
+// ── EVERY FAILURE IS SILENT ──────────────────────────────────────────────
+//
+// A thumbnail is decoration. Nothing in here may surface an error or delay a
+// save: the fallback is a gradient the dashboard draws anyway.
+import type { ShotStageBridge } from "../bridgeTypes.js";
+
+/**
+ * Exactly what this module reads from the store, and nothing else.
+ *
+ * Structural rather than `Pick<ShotEditorStore, …>` on purpose: the state has
+ * ~58 fields, and depending on the whole shape would mean a test double has to
+ * fabricate all of them to stand in for the two that matter.
+ */
+export interface PosterStore {
+  getState(): { saveState: string; name: string | null };
+  /** The COLD lane: a save and a name are never a transport tick. */
+  subscribeCold(listener: () => void): () => void;
+  stage(): ShotStageBridge | null;
+}
+
+/** Wide enough to look sharp on a card, small enough that a JPEG of it is
+ *  tens of KB. The Worker caps the upload at 512KB regardless. */
+const POSTER_WIDTH = 640;
+
+/**
+ * How long after a save to attempt the poster request, and how long to wait
+ * before asking again when the stage answered "not now".
+ *
+ * Long enough that a burst of autosaves during an edit produces ONE request.
+ * This delay is only debounce policy. Pixel readiness belongs to the stage's
+ * exact presentation latch and must never be inferred from elapsed time.
+ */
+const SETTLE_MS = 10_000;
+
+/** The most a way out of the editor waits for an owed poster: a warm capture
+ *  and its upload fit well inside it. A cold one is abandoned with the page
+ *  rather than holding the author at the door. */
+const POSTER_FLUSH_MS = 5_000;
+
+/**
+ * Only in the hosted lane.
+ *
+ * The editor host stamps this marker into `/scene` (browser-host's
+ * `stampHostBoot`, which the Worker's `editorPage` calls). Locally the CLI
+ * renders every card's poster itself and has no route to accept one, so the
+ * whole feature stays inert rather than 404ing on every save.
+ */
+export function isCloudWorkspace(doc: Document = document): boolean {
+  return doc.querySelector('meta[name="dailies-workspace"][content="cloud"]') !== null;
+}
+
+export interface PosterCaptureDeps {
+  store: PosterStore;
+  /** Injected so tests can drive the timing without a real clock. */
+  setTimeout?: (fn: () => void, ms: number) => unknown;
+  clearTimeout?: (handle: unknown) => void;
+  fetch?: typeof fetch;
+  enabled?: boolean;
+  /** Whether the page is hidden: nothing presents there, so no capture can. */
+  hidden?: () => boolean;
+  /** Subscribe to the page's visibility changing; returns the unsubscribe. */
+  onVisibilityChange?: (listener: () => void) => () => void;
+}
+
+/** The running capture's flush, for `flushPoster`. One editor per page. */
+let flushRunning: (() => Promise<void>) | null = null;
+
+/**
+ * Run an owed poster now and wait for its upload, for a page about to leave
+ * the editor. Resolves (never rejects) within `POSTER_FLUSH_MS` whatever the
+ * stage does, and at once when nothing is owed or the feature is inert.
+ */
+export function flushPoster(): Promise<void> {
+  return flushRunning?.() ?? Promise.resolve();
+}
+
+/**
+ * Watch for saves and upload a poster after things settle. Returns the
+ * unsubscribe.
+ */
+export function startPosterCapture(deps: PosterCaptureDeps): () => void {
+  const enabled = deps.enabled ?? isCloudWorkspace();
+  if (!enabled) return () => {};
+
+  const later = deps.setTimeout ?? ((fn, ms) => globalThis.setTimeout(fn, ms));
+  const cancel = deps.clearTimeout ?? ((h) => globalThis.clearTimeout(h as never));
+  const send = deps.fetch ?? globalThis.fetch.bind(globalThis);
+  // "hidden" only: jsdom and prerendered pages report other states, and a
+  // poster that waited for "visible" there would never be asked for.
+  const hidden = deps.hidden ?? (() => typeof document !== "undefined" && document.visibilityState === "hidden");
+  const onVisibilityChange =
+    deps.onVisibilityChange ??
+    ((listener: () => void) => {
+      if (typeof document === "undefined") return () => {};
+      document.addEventListener("visibilitychange", listener);
+      return () => document.removeEventListener("visibilitychange", listener);
+    });
+
+  let timer: unknown = null;
+  let lastSaveState = deps.store.getState().saveState;
+  /** The Project whose poster is owed, or null. */
+  let owed: string | null = null;
+  /** Counts saves, so a capture that finishes after a newer save does not
+   *  settle the debt that save made. */
+  let saves = 0;
+  let inFlight: Promise<void> | null = null;
+
+  function arm(): void {
+    if (timer !== null) cancel(timer);
+    timer = later(() => {
+      timer = null;
+      void attempt();
+    }, SETTLE_MS);
+  }
+
+  function attempt(): Promise<void> {
+    if (inFlight !== null) return inFlight;
+    const name = owed;
+    if (name === null) return Promise.resolve();
+    // Another Project opened: its own saves owe its own poster.
+    if (deps.store.getState().name !== name) {
+      owed = null;
+      return Promise.resolve();
+    }
+    // Asked again when the tab comes back.
+    if (hidden()) return Promise.resolve();
+    inFlight = capture(name, saves).finally(() => {
+      inFlight = null;
+    });
+    return inFlight;
+  }
+
+  async function capture(name: string, served: number): Promise<void> {
+    const bridge = deps.store.stage();
+    // A stage still booting: ask again later.
+    if (bridge === null) {
+      arm();
+      return;
+    }
+    // A v12 stage under a v13 chrome cannot answer. The connect-time version
+    // gate should have caught it; this keeps a stale build from throwing on
+    // every save if it ever does not.
+    if (typeof bridge.capturePoster !== "function") {
+      owed = null;
+      return;
+    }
+    const blob = await bridge.capturePoster(POSTER_WIDTH).catch(() => null);
+    // The stage draws the OPEN project. Another one opened during the
+    // capture would put its picture on this card.
+    if (deps.store.getState().name !== name) {
+      if (owed === name) owed = null;
+      return;
+    }
+    if (blob === null) {
+      // Not now (playing, exporting, a capture that stepped aside): owed
+      // still, and asked again once things settle.
+      if (owed === name) arm();
+      return;
+    }
+    if (saves === served) owed = null;
+    try {
+      await send(`/api/posters/shot/${encodeURIComponent(name)}`, {
+        method: "PUT",
+        headers: { "content-type": "image/jpeg" },
+        body: blob,
+      });
+    } catch {
+      // Offline, or the route is not there. The card keeps its existing poster
+      // when it has one, otherwise it keeps the deterministic gradient.
+    }
+  }
+
+  const unsubscribe = deps.store.subscribeCold(() => {
+    const { saveState, name } = deps.store.getState();
+    const justSaved = saveState === "saved" && lastSaveState !== "saved";
+    lastSaveState = saveState;
+    if (!justSaved || name === null) return;
+    owed = name;
+    saves += 1;
+    arm();
+  });
+
+  const unwatchVisibility = onVisibilityChange(() => {
+    if (owed !== null && timer === null && inFlight === null && !hidden()) arm();
+  });
+
+  const flush = async (): Promise<void> => {
+    if (owed === null && inFlight === null) return;
+    if (timer !== null) {
+      cancel(timer);
+      timer = null;
+    }
+    let giveUp: unknown = null;
+    await Promise.race([
+      attempt(),
+      new Promise<void>((resolve) => {
+        giveUp = later(resolve, POSTER_FLUSH_MS);
+      }),
+    ]);
+    cancel(giveUp);
+  };
+  flushRunning = flush;
+
+  return () => {
+    if (timer !== null) cancel(timer);
+    timer = null;
+    owed = null;
+    unsubscribe();
+    unwatchVisibility();
+    if (flushRunning === flush) flushRunning = null;
+  };
+}

package/src/state/presence.ts

@@ -0,0 +1,254 @@
+// WHO ELSE IS HERE (collaboration lane R7, Paper page 21).
+//
+// A store of its own, like the comments': presence never enters undo, the
+// save or the document. It lives on the live sync socket (state/sync.ts hands
+// over the session's `peers`, `peer` and `peer-left`) and is gone with it, so
+// there is presence only while live sync is on.
+//
+// ── ONE PERSON, ONE FACE ────────────────────────────────────────────────────
+//
+// The session tells tabs. Here they are grouped by user: one person with three
+// tabs is one face, and their selection, Shot and playhead are the ones of the
+// tab they touched last (the newest `at`). This tab's own user is left out,
+// with its other tabs: the CLI's tabs are all user "local", so the CLI shows
+// no faces at all.
+//
+// ── WHAT THIS TAB SAYS ──────────────────────────────────────────────────────
+//
+// `update` takes where this tab is (the store's selection, Shot and playhead;
+// the board's cursor) and says it: a new selection or Shot at once, a moving
+// playhead or cursor at most every `PRESENCE_MS` (15 Hz), with the last one
+// always sent.
+import { PRESENCE_SEL_MAX } from "@dailies-studio/shot/doc";
+import type { SyncCursor, SyncPeerPresence, SyncPresence, SyncPresenceMessage } from "@dailies-studio/shot/doc";
+
+/** A moving playhead or cursor is said at most this often (15 Hz). */
+export const PRESENCE_MS = 67;
+
+/** The peer palette (page 21): eight colours, none of them the selection's
+ *  blue, the warning amber, the error coral or the Agent's mint. */
+export const PEER_COLORS = [
+  "#8A6CFF",
+  "#FF7A3D",
+  "#2EC4B6",
+  "#D86CFF",
+  "#A8D84A",
+  "#FF7AC6",
+  "#5AD2F0",
+  "#E8D44D",
+] as const;
+
+/** The Agent's colour, only ever the Agent's. */
+export const AGENT_COLOR = "#34D399";
+
+/** A person's peer colour, stable for their user id. */
+export function peerColor(userId: string): string {
+  let hash = 0;
+  for (let i = 0; i < userId.length; i++) hash = (hash * 31 + userId.charCodeAt(i)) | 0;
+  return PEER_COLORS[Math.abs(hash) % PEER_COLORS.length]!;
+}
+
+export interface PresenceName {
+  name: string;
+  avatarUrl?: string | null;
+}
+
+/** One face: a person, however many tabs they have open. */
+export interface PresencePerson {
+  user: string;
+  name: string;
+  color: string;
+  avatarUrl: string | null;
+  /** "edit" when any of their tabs may edit. */
+  role: "edit" | "view";
+  tabs: number;
+  /** From the tab they touched last. */
+  sel: readonly string[];
+  scene: string | null;
+  frame: number | null;
+  cursor: SyncCursor | null;
+}
+
+export interface PresenceState {
+  /** The session told us who is here (joined, and the socket is up). */
+  live: boolean;
+  /** This tab's user, from the session. */
+  self: string | null;
+  /** Every other tab, as the session told them. */
+  tabs: readonly SyncPeerPresence[];
+  /** The faces, in the order they arrived. */
+  people: readonly PresencePerson[];
+  names: Readonly<Record<string, PresenceName>>;
+  /** The user this tab follows, or null. */
+  following: string | null;
+  /** Why a follow ended on its own ("Maya left the Shot"), until dismissed. */
+  notice: string | null;
+}
+
+/** This tab's own place. `null` clears a field. */
+export interface PresenceLocal {
+  sel?: readonly string[];
+  scene?: string | null;
+  frame?: number | null;
+  cursor?: SyncCursor | null;
+}
+
+export interface PresenceStore {
+  getState(): PresenceState;
+  subscribe(listener: () => void): () => void;
+  /** Where presence goes out (the sync client's `presence`), or null with no
+   *  live sync. */
+  attach(send: ((p: SyncPresence) => void) | null): void;
+  /** A session message, or null when the socket went. */
+  receive(msg: SyncPresenceMessage | null): void;
+  /** Names learnt (the Project's people route, comment authors). */
+  learn(names: Readonly<Record<string, PresenceName>>): void;
+  update(local: PresenceLocal): void;
+  /** Follow a person, or stop (`null`). `notice` says why it stopped. */
+  follow(user: string | null, notice?: string): void;
+  dismissNotice(): void;
+}
+
+const EMPTY: PresenceState = {
+  live: false,
+  self: null,
+  tabs: [],
+  people: [],
+  names: {},
+  following: null,
+  notice: null,
+};
+
+/** The faces for a list of tabs: grouped by user, without `self`. */
+export function groupPeople(
+  tabs: readonly SyncPeerPresence[],
+  self: string | null,
+  names: Readonly<Record<string, PresenceName>>,
+): PresencePerson[] {
+  const by = new Map<string, PresencePerson & { at: number }>();
+  for (const t of tabs) {
+    if (t.user === self) continue;
+    const seen = by.get(t.user);
+    const where = { at: t.at, sel: t.sel ?? [], scene: t.scene ?? null, frame: t.frame ?? null, cursor: t.cursor ?? null };
+    if (seen === undefined) {
+      by.set(t.user, {
+        user: t.user,
+        name: names[t.user]?.name ?? "Someone",
+        color: peerColor(t.user),
+        avatarUrl: names[t.user]?.avatarUrl ?? null,
+        role: t.role,
+        tabs: 1,
+        ...where,
+      });
+      continue;
+    }
+    seen.tabs++;
+    if (t.role === "edit") seen.role = "edit";
+    if (t.at >= seen.at) Object.assign(seen, where);
+  }
+  return [...by.values()].map(({ at: _at, ...person }) => person);
+}
+
+const sameIds = (a: readonly string[] | undefined, b: readonly string[] | undefined): boolean =>
+  (a ?? []).length === (b ?? []).length && (a ?? []).every((id, i) => id === b![i]);
+
+export function createPresenceStore(deps: { now?: () => number } = {}): PresenceStore {
+  const now = deps.now ?? (() => Date.now());
+  let state = EMPTY;
+  const listeners = new Set<() => void>();
+  let send: ((p: SyncPresence) => void) | null = null;
+  /** This tab's place, as last said and as now. */
+  let mine: SyncPresence = {};
+  let said: SyncPresence | null = null;
+  let saidAt = -Infinity;
+  let timer: ReturnType<typeof setTimeout> | null = null;
+
+  function set(patch: Partial<PresenceState>): void {
+    const before = state.people;
+    state = { ...state, ...patch };
+    if (patch.tabs !== undefined || patch.self !== undefined || patch.names !== undefined) {
+      state = { ...state, people: groupPeople(state.tabs, state.self, state.names) };
+    }
+    // A follow ends when its person leaves.
+    if (state.following !== null && !state.people.some((p) => p.user === state.following)) {
+      const gone = before.find((p) => p.user === state.following)?.name ?? "They";
+      state = { ...state, following: null, notice: `${gone} left. Follow ended.` };
+    }
+    for (const listener of listeners) listener();
+  }
+
+  function flush(): void {
+    if (timer !== null) clearTimeout(timer);
+    timer = null;
+    said = mine;
+    saidAt = now();
+    send?.(mine);
+  }
+
+  return {
+    getState: () => state,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    attach(next) {
+      send = next;
+      said = null;
+      if (next !== null) flush();
+      else if (timer !== null) {
+        clearTimeout(timer);
+        timer = null;
+      }
+    },
+    receive(msg) {
+      if (msg === null) {
+        if (state.live || state.tabs.length > 0) set({ live: false, tabs: [], following: null });
+        return;
+      }
+      if (msg.t === "peers") set({ live: true, self: msg.user, tabs: msg.peers });
+      else if (msg.t === "peer") {
+        const at = state.tabs.findIndex((t) => t.id === msg.peer.id);
+        set({ tabs: at < 0 ? [...state.tabs, msg.peer] : state.tabs.map((t, i) => (i === at ? msg.peer : t)) });
+      } else set({ tabs: state.tabs.filter((t) => t.id !== msg.id) });
+    },
+    learn(names) {
+      set({ names: { ...state.names, ...names } });
+    },
+    update(local) {
+      const next: SyncPresence = { ...mine };
+      for (const key of ["sel", "scene", "frame", "cursor"] as const) {
+        if (!(key in local)) continue;
+        const v = local[key];
+        if (v === null || v === undefined || (key === "sel" && (v as readonly string[]).length === 0)) delete next[key];
+        else if (key === "sel") next.sel = (v as readonly string[]).slice(0, PRESENCE_SEL_MAX);
+        else (next as Record<string, unknown>)[key] = v;
+      }
+      const prev = mine;
+      mine = next;
+      if (send === null) return;
+      if (
+        sameIds(prev.sel, next.sel) &&
+        prev.scene === next.scene &&
+        prev.frame === next.frame &&
+        prev.cursor?.x === next.cursor?.x &&
+        prev.cursor?.y === next.cursor?.y &&
+        prev.cursor?.space === next.cursor?.space &&
+        prev.cursor?.where === next.cursor?.where
+      ) {
+        return;
+      }
+      // A new selection or Shot, or a cursor leaving, goes at once.
+      const urgent =
+        said === null || !sameIds(said.sel, next.sel) || said.scene !== next.scene || (said.cursor !== undefined && next.cursor === undefined);
+      const wait = saidAt + PRESENCE_MS - now();
+      if (urgent || wait <= 0) return flush();
+      timer ??= setTimeout(flush, wait);
+    },
+    follow(user, notice) {
+      set({ following: user, notice: notice ?? null });
+    },
+    dismissNotice() {
+      if (state.notice !== null) set({ notice: null });
+    },
+  };
+}

package/src/state/projectComponents.ts

@@ -0,0 +1,160 @@
+// WHICH COMPONENTS BELONG TO THIS PROJECT.
+//
+// Nothing on the wire answers this. A workspace is scanned whole (`src/**/*.tsx`
+// from the root) and a registry row carries `id`, `rel`, `name`, `exportName`,
+// `host` and the studio-versus-user `source`. There is no project id, no owner
+// and no document name on it. In a workspace holding forty films that means one
+// film's board offered the other thirty-nine films' components, plus the four
+// foreign workspaces a marketplace claim copies into `src/market/`.
+//
+// So the group is DERIVED, from the facts the document itself holds:
+//
+//   1. the components it already places or cites (exact, and the seed),
+//   2. the code files made for it (`componentFiles`, exact, and never a seed),
+//      and
+//   3. the folders the placed and cited sit in (convention, and what makes a
+//      component written for this film appear without being placed first).
+//
+// A file made for this Project never folds its folder in: agents pick the
+// folder (`src/components/` is a common one), so a member's folder is shared
+// with other Projects' members far more often than a placed component's is.
+// And with `homes` (the workspace's index of which Project lists or uses each
+// file) a folder-mate another Project holds is left out of the fold too.
+//
+// The fold is the half that needs guarding. `src/Foo.tsx` sits at the source
+// root, so folding on its directory would hand back the whole tree; and one film
+// placed inside another is a real thing, so folding on the generated directory
+// would hand back every film. Both are excluded by name, and this Project's own
+// generated film is added back by an exact match on `doc.name`.
+//
+// A Project that has used nothing gets an EMPTY group, deliberately: the rail's
+// search reaches the whole registry, and answering "everything" would be the
+// same wrong list this module exists to stop.
+import { GENERATED_SHOTS_DIR, componentFilesOf, usedInstanceComponentsOf } from "@dailies-studio/shot/doc";
+import type { Doc3D, UsedInstanceComponent } from "@dailies-studio/shot/doc";
+import { isProjectComponent } from "@dailies-studio/ui";
+import type { ComponentFileHome, ComponentRow } from "../api.js";
+import { storyboardComponentsOf } from "./storyboardModel.js";
+
+/**
+ * The registry components a document PLACES plus the ones its storyboard
+ * CITES, so "components are shared by both views" is one list. A board-only
+ * entry has no layers: its row is a name and nothing to select.
+ *
+ * Lifted out of `FilePanel` so the files panel and the storyboard rail cannot
+ * answer "what does this Project use" two different ways.
+ */
+export function usedComponentsOf(doc: Doc3D): UsedInstanceComponent[] {
+  const placed = usedInstanceComponentsOf(doc);
+  const seen = new Set(placed.map((used) => used.component));
+  const extra = storyboardComponentsOf(doc)
+    .filter((row) => !seen.has(row.component))
+    .map((row): UsedInstanceComponent => ({ component: row.component, layerIds: [] }));
+  return extra.length === 0 ? placed : [...placed, ...extra];
+}
+
+/** The directory part of a posix path, or "" for a bare file name. */
+function dirOf(rel: string): string {
+  const cut = rel.lastIndexOf("/");
+  return cut === -1 ? "" : rel.slice(0, cut);
+}
+
+/**
+ * Folders the fold may never claim.
+ *
+ * The source root, because a component at the top of `src/` would otherwise
+ * fold in every project file in the workspace. The generated directory,
+ * because a film placed inside another film is an ordinary instance and would
+ * otherwise fold in every other film. Both are single directories rather than
+ * a prefix test: `src/cero` is fine, `src` is not.
+ */
+function foldable(dir: string): boolean {
+  return dir !== "" && dir !== "src" && dir !== GENERATED_SHOTS_DIR;
+}
+
+export interface ProjectComponents {
+  /** This Project's own: what it uses, the files made for it, the folders of
+   *  what it uses, and its generated film. */
+  project: ComponentRow[];
+  /** Shipped builtins and vendored shared components. */
+  library: ComponentRow[];
+  /** Other Projects' generated films, which are build products, not source. */
+  films: ComponentRow[];
+  /** Every row, in registry order — what the rail's search runs over. */
+  all: ComponentRow[];
+}
+
+const EMPTY: ProjectComponents = { project: [], library: [], films: [], all: [] };
+
+/**
+ * Split the registry three ways for one open document.
+ *
+ * Order is the registry's own throughout, so a row never moves because of
+ * which group it landed in. With no document open every group is empty rather
+ * than a copy of the registry: "no Project" is not "every component".
+ */
+export function projectComponents(
+  doc: Doc3D | null,
+  library: readonly ComponentRow[],
+  /** The workspace's `homes` (`componentHomes`), when read: a folder-mate
+   *  another Project lists or uses is that Project's, not this one's. */
+  homes: readonly ComponentFileHome[] | null = null,
+): ProjectComponents {
+  if (doc === null) return { ...EMPTY, all: [...library] };
+
+  const used = new Set(usedComponentsOf(doc).map((row) => row.component));
+  const members = new Set(componentFilesOf(doc).filter((path) => !path.startsWith(`${GENERATED_SHOTS_DIR}/`)));
+  const elsewhere = new Set((homes ?? []).filter((h) => h.projectId !== doc.id).map((h) => h.path));
+  const byId = new Map(library.map((row) => [row.id, row]));
+
+  // Only a PROJECT row's folder folds. A builtin's `rel` is a package
+  // specifier (`@dailies-studio/particles`), which has no directory to speak of.
+  const folders = new Set<string>();
+  for (const id of used) {
+    const row = byId.get(id);
+    if (row === undefined || !isProjectComponent(row)) continue;
+    const dir = dirOf(row.rel);
+    if (foldable(dir)) folders.add(dir);
+  }
+
+  const ownFilm = `${GENERATED_SHOTS_DIR}/${doc.name}.tsx`;
+  const inFolder = (rel: string): boolean => {
+    for (const dir of folders) if (rel.startsWith(`${dir}/`)) return true;
+    return false;
+  };
+
+  const out: ProjectComponents = { project: [], library: [], films: [], all: [...library] };
+  for (const row of library) {
+    if (!isProjectComponent(row)) {
+      out.library.push(row);
+    } else if (
+      used.has(row.id) ||
+      members.has(row.rel) ||
+      row.rel === ownFilm ||
+      (inFolder(row.rel) && !elsewhere.has(row.rel))
+    ) {
+      out.project.push(row);
+    } else if (row.rel.startsWith(`${GENERATED_SHOTS_DIR}/`)) {
+      out.films.push(row);
+    } else {
+      // A project component of some OTHER film. Reachable through the rail's
+      // search and nowhere else, which is the whole point.
+    }
+  }
+  return out;
+}
+
+/**
+ * The folder a row sits in, for the badge the rail puts on a search hit from
+ * outside this Project. A builtin has none, and says so with its package name.
+ */
+export function componentFolderOf(row: ComponentRow): string {
+  return isProjectComponent(row) ? (dirOf(row.rel) || row.rel) : row.rel;
+}
+
+/** Case-insensitive match over the two strings a person would type. */
+export function matchesComponent(row: ComponentRow, query: string): boolean {
+  const q = query.trim().toLowerCase();
+  if (q === "") return true;
+  return row.name.toLowerCase().includes(q) || row.id.toLowerCase().includes(q);
+}