auricui-skill 0.0.0-stage → 0.1.2

package/skill/assets/upstream/packages/openfilm/studio/server/track-layout.mjs

@@ -0,0 +1,43 @@
+// @ts-check
+import { kindOf } from '../../src/film-doc.mjs';
+
+/** Studio's row kind, including audio-only uses of video files.
+ * @param {{ clips: readonly { src: string, sound?: boolean }[] }} track
+ * @returns {'mg' | 'video' | 'audio'}
+ */
+export function trackKind(track) {
+  const kinds = new Set(track.clips.map((clip) => {
+    const kind = kindOf(clip);
+    return kind === 'page' ? 'mg' : kind === 'sound' ? 'audio' : 'video';
+  }));
+  return kinds.size === 1 ? /** @type {'mg' | 'video' | 'audio'} */ ([...kinds][0]) : 'video';
+}
+
+/** Picture rows count bottom up, sound rows top down; each prefix counts separately.
+ * @param {readonly string[]} kinds
+ */
+export function rowBadges(kinds) {
+  const prefixes = kinds.map((kind) => kind === 'mg' ? 'P' : kind === 'video' ? 'V' : 'A');
+  const total = new Map();
+  for (const prefix of prefixes) total.set(prefix, (total.get(prefix) ?? 0) + 1);
+  const seen = new Map();
+  return prefixes.map((prefix) => {
+    const nth = (seen.get(prefix) ?? 0) + 1;
+    seen.set(prefix, nth);
+    return `${prefix}${prefix === 'A' ? nth : total.get(prefix) - nth + 1}`;
+  });
+}
+
+/** Greedy rows in milliseconds; one millisecond of overlap is rounding at a shared edge.
+ * @template {{ startMs: number, endMs: number }} T
+ * @param {readonly T[]} blocks @returns {T[][]}
+ */
+export function layerBlocks(blocks) {
+  /** @type {T[][]} */
+  const rows = [];
+  for (const block of [...blocks].sort((a, b) => a.startMs - b.startMs || a.endMs - b.endMs)) {
+    const row = rows.find((r) => (r.at(-1)?.endMs ?? 0) <= block.startMs + 1);
+    if (row) row.push(block); else rows.push([block]);
+  }
+  return rows;
+}

package/skill/assets/upstream/packages/openfilm/studio/ui/src/App.tsx

@@ -0,0 +1,156 @@
+/**
+ * Studio is one place: a project (/projects/<id>). The projects are a popover inside it; `/` goes to the project
+ * opened last, or (none left, or only ones whose folder is gone) shows the Projects window on its own, with "New
+ * project" in it: no folder is made that the person did not ask for. The address is the state, so the agent's
+ * `openfilm open` (which sends the page to a project) and the browser's back button both work.
+ *
+ * In an app with tabs (lib/host.ts `tabs`) this page is one project's tab: a project picked opens in its own tab (the
+ * app's to open), `/` is the projects (the window with no tab open), and `openfilm open` is the app's to settle (every
+ * tab hears it).
+ */
+import { useEffect, useState, useSyncExternalStore } from 'react';
+import { api, listen, studioConnection } from './api';
+import { BrandLoadingScreen } from './components/BrandLoadingScreen';
+import { Launcher } from './components/Launcher';
+import { ProjectsPopover } from './components/ProjectsLibrary';
+import { ProjectView } from './components/ProjectView';
+import { WhatsNew } from './components/WhatsNew';
+import { useT } from './i18n';
+import { studioHost } from './lib/host';
+import { sourcesApi } from './lib/project-sources';
+import { LIST_WAIT_MS, within } from './lib/projects-page';
+
+/**
+ * `to` with this page's key in its address (the server puts it there): the address bar is what a person copies, and
+ * with the key a copied address opens Studio in any browser on this machine, or in an agent's preview.
+ */
+const keepKey = (to: string) => {
+  const key = new URLSearchParams(location.search).get('key');
+  if (!key) return to;
+  const at = new URL(to, location.origin);
+  at.searchParams.set('key', key);
+  return at.pathname + at.search;
+};
+
+const projectIn = (path: string) => /^\/projects\/([\w-]+)/.exec(path)?.[1] ?? null;
+/** the app's tabs, when Studio is a tab of an app's window */
+const tabs = studioHost?.tabs ?? null;
+
+export function App() {
+  const [path, setPath] = useState(location.pathname);
+  const go = (to: string, replace = false) => {
+    if (to !== location.pathname) (replace ? history.replaceState : history.pushState).call(history, null, '', keepKey(to));
+    setPath(to);
+  };
+
+  /* the examples and skills, read as Studio opens: a gallery opened later shows them at once */
+  useEffect(() => { sourcesApi.preload(); }, []);
+
+  useEffect(() => {
+    const onPop = () => setPath(location.pathname);
+    window.addEventListener('popstate', onPop);
+    /* `openfilm open` while this page is open: show the project it opened (with tabs, the app says which tab does) */
+    const stop = listen('events', (event) => {
+      if (event.type !== 'open') return;
+      if (tabs) tabs.openRequest(event.to); else go(event.to);
+    }, { watch: true });
+    return () => { window.removeEventListener('popstate', onPop); stop(); };
+  }, []);
+
+  /** Show a project: here, or (with tabs) in its own tab. */
+  const open = (projectId: string) => { if (tabs) tabs.open(projectId); else go(`/projects/${projectId}`); };
+  /** The project shown was deleted: its tab closes (with tabs), or back to the last project. */
+  const leave = () => { if (tabs) tabs.report({ gone: true }); else go('/', true); };
+
+  const id = projectIn(path);
+  /* no project in the address: the one opened last that is still there, else the Projects window (`none`); with
+     tabs, the projects (no tab is open) */
+  const [none, setNone] = useState(false);
+  useEffect(() => {
+    if (id || tabs) return;
+    let alive = true;
+    /* the list not read (refused, or no answer in time): the Projects window, which says so and tries again */
+    void within(api.projects(), LIST_WAIT_MS).then((projects) => {
+      if (!alive) return;
+      const last = projects.find((p) => !p.missing);
+      if (last) go(`/projects/${last.id}`, true);
+      else setNone(true);
+    }, () => { if (alive) setNone(true); });
+    return () => { alive = false; setNone(false); };
+  }, [id]);
+
+  const page = id ? <ProjectView key={id} projectId={id} onProject={open} onLeave={leave} />
+    : tabs ? <Launcher onOpen={open} />
+    : !none ? <BrandLoadingScreen labelKey="projects.opening" />
+      : (
+        <div className="workspace-shell bg-[var(--dock-shell)]">
+          <ProjectsPopover open currentProjectId="" onOpen={(next) => go(`/projects/${next}`)} onCurrentRemoved={() => {}} />
+        </div>
+      );
+  return <>{page}<ConnectionNotice /><WhatsNew /></>;
+}
+
+/**
+ * Studio answers, but not this browser: it was opened at Studio's address without the key (pasted, typed, an agent's
+ * browser given the bare address). Nothing to wait for: the page is covered and says which address lets it in.
+ */
+function LockedNotice() {
+  const t = useT();
+  const [copied, setCopied] = useState(false);
+  const COMMAND = 'openfilm open';
+  return (
+    <div role="alert" className="fixed inset-0 z-[10050] flex items-center justify-center bg-[var(--dock-shell)] p-6">
+      <div className="w-full max-w-[460px] rounded-2xl border border-[var(--border)] bg-[var(--surface)] p-6 shadow-[var(--shadow-lg)]">
+        <p className="text-[16px] font-semibold text-[var(--text)]">{t('connection.lockedTitle')}</p>
+        <p className="mt-2 text-[13px] leading-relaxed text-[var(--text-muted)]">{t('connection.lockedBody')}</p>
+        <p className="mt-3 rounded-lg bg-[var(--surface-2)] px-3 py-2 font-mono text-[12px] text-[var(--text-dim)]">{`${location.origin}/open?key=…`}</p>
+        {studioHost ? null : (
+          <div className="mt-4 flex items-center gap-2 text-[12.5px] text-[var(--text-muted)]">
+            <span>{t('connection.lockedHow')}</span>
+            <button
+              type="button"
+              onClick={() => { void navigator.clipboard?.writeText(COMMAND).then(() => setCopied(true), () => {}); }}
+              className="rounded-md bg-[var(--surface-2)] px-2 py-0.5 font-mono text-[12px] text-[var(--text)] ring-1 ring-inset ring-[var(--border)] hover:bg-[var(--bg-hover)]"
+            >
+              {copied ? t('connection.copied') : COMMAND}
+            </button>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
+
+/**
+ * Studio stopped (an update, a crash, the computer slept): a bar across the top while it is away, so nothing seems to
+ * hang for no reason. Reconnecting is tried all along; once it has been away a while the page is covered (an export or
+ * an edit made now would go nowhere) and the bar says how to start it again: this page reconnects by itself.
+ */
+function ConnectionNotice() {
+  const t = useT();
+  const state = useSyncExternalStore(studioConnection.subscribe, studioConnection.get);
+  const [copied, setCopied] = useState(false);
+  useEffect(() => { if (state === 'up') setCopied(false); }, [state]);
+  if (state === 'up') return null;
+  if (state === 'locked') return <LockedNotice />;
+  const gone = state === 'gone';
+  const COMMAND = 'openfilm open';
+  return (
+    <>
+      {gone ? <div aria-hidden className="fixed inset-0 z-[10049] bg-black/40 backdrop-blur-[1.5px]" /> : null}
+      <div role="alert" className={`fixed inset-x-0 top-0 z-[10050] flex flex-wrap items-center justify-center gap-x-3 gap-y-1.5 px-4 py-2.5 text-[13px] font-medium text-white shadow-lg ${gone ? 'bg-[#b42318]' : 'bg-[#b54708]'}`}>
+        <span aria-hidden className={`h-2 w-2 shrink-0 rounded-full bg-white ${gone ? '' : 'animate-pulse'}`} />
+        <span>{t(gone ? (studioHost ? 'connection.goneApp' : 'connection.gone') : 'connection.lost')}</span>
+        {gone && !studioHost ? (
+          <button
+            type="button"
+            onClick={() => { void navigator.clipboard?.writeText(COMMAND).then(() => setCopied(true), () => {}); }}
+            className="rounded-md bg-white/15 px-2 py-0.5 font-mono text-[12.5px] ring-1 ring-inset ring-white/30 hover:bg-white/25"
+          >
+            {copied ? t('connection.copied') : COMMAND}
+          </button>
+        ) : null}
+      </div>
+    </>
+  );
+}

package/skill/assets/upstream/packages/openfilm/studio/ui/src/api.ts

@@ -0,0 +1,328 @@
+/**
+ * Studio's API, as the editor calls it (studio/server/server.mjs). Same origin, so the launch key travels as the
+ * cookie `/open` set; writes are refused from any other origin.
+ */
+import type { ExportJob } from '@/lib/export-jobs';
+import { studioHost } from '@/lib/host';
+import { watchStudioVersion } from '@/lib/studio-version';
+
+/** `working`: an agent of the app's chat is working in it right now (it cannot be deleted meanwhile). */
+/** GET /api/version: this Studio's, and npm's latest (null when never learnt; `checking` false: never asked). */
+export interface StudioVersion { version: string; latest: string | null; newer: boolean; checkedAt: number | null; checking: boolean; source: boolean;
+  /** the update Studio runs from the top bar (lib/web-update), or one that failed */
+  update?: { status: 'updating' | 'failed'; version: string; error?: string } }
+
+/** `cover`: when the person set a cover of its own (studio/server/cover.mjs), absent when it has none. */
+export type Project = { id: string; path: string; name: string; openedAt: number; missing: boolean; working?: boolean; cover?: number };
+export type Clip = { src: string; id: string; at?: number; time?: [number] | [number, number];
+  box?: { x: number; y: number; w?: number; h?: number; r?: number }; volume?: number; speed?: number; overrides?: unknown[];
+  /** a page that sets no size of its own: the px it is laid out at (the stage's without it) */
+  size?: { w: number; h: number };
+  /** a video's sound alone (an <audio> of its file) */
+  sound?: true;
+  /** its look: class names for the film's styles, and its own CSS */
+  class?: string; style?: string; attrs?: Record<string, string> };
+export type Track = { clips: Clip[]; locked?: boolean; hidden?: boolean; muted?: boolean; attrs?: Record<string, string> };
+export type Film = { stage?: { w: number; h: number }; tracks: Track[] };
+/** `value`: film.html as read, every clip named (a clip with no id takes its file's name, as the server and preview do). */
+export type ProjectFilm = { project: Project; folder: string; text: string; rev: string; value: Film | null; doc: Film | null; problems: string[] };
+export type MediaFile = { path: string; kind: 'video' | 'image' | 'audio' | 'page' | 'other'; size: number; mtime: number; added?: number };
+/** A project's editor settings (studio/server/project-settings.mjs). */
+export type ProjectSettings = { fps?: number; trackNames?: { name: string; index: number; clips: string[] }[]; trackHeights?: { height: number; index: number; clips: string[] }[] };
+export type Listing = { files: MediaFile[]; folders: string[]; pages: { path: string; size: number; mtime: number }[] };
+export type Op =
+  | { op: 'set'; clip: string; field: string; value?: unknown }
+  | { op: 'move'; clip: string; at: number; track?: number; newTrack?: number }
+  | { op: 'insert'; clip?: Partial<Clip> & { src: string }; from?: string; at?: number; after?: string; track?: number | { insert: number }; newTrack?: number; link?: string | null }
+  | { op: 'remove'; clip: string }
+  | { op: 'split'; clip: string; at: number; time: [number, number]; restTime: [number, number] }
+  | { op: 'split'; clip: string; left: Record<string, PropValue>; right: Record<string, PropValue>; rightId?: string }
+  | { op: 'track'; track: number; field: 'locked' | 'hidden' | 'muted'; value: boolean }
+  | { op: 'reorder'; from: number; to: number }
+  | { op: 'props'; edits: PropEdit[] }
+  | { op: 'stage'; w: number; h: number }
+  | { op: 'fields'; clip: string; fields: Record<string, unknown> };
+
+/** A value a clip's property takes (null removes it). */
+export type PropValue = number | string | boolean | readonly number[] | Record<string, unknown> | null;
+/** One property of one clip, by the clip's id (see studio/server/ops.mjs). */
+export type PropEdit = { clip: string; prop: string; value: PropValue };
+
+export class ApiError extends Error {
+  constructor(message: string, readonly status: number, readonly body: Record<string, unknown>) {
+    super(message);
+  }
+}
+
+/** Writes on their way (edits, renames…): a reload for a new Studio waits for them (studioVersion). */
+let writing = 0;
+
+async function call<T>(path: string, init: RequestInit & { json?: unknown } = {}): Promise<T> {
+  const { json, ...rest } = init;
+  const write = (rest.method ?? 'GET') !== 'GET';
+  if (write) writing += 1;
+  try {
+    const res = await fetch(`/api/${path}`, {
+      ...rest,
+      headers: json === undefined ? rest.headers : { 'content-type': 'application/json', ...rest.headers },
+      body: json === undefined ? rest.body : JSON.stringify(json),
+    });
+    const body = await res.json().catch(() => ({}));
+    if (res.status === 401) markLocked();
+    if (!res.ok) throw new ApiError(String(body.error ?? `Studio answered ${res.status}`), res.status, body);
+    return body as T;
+  } finally {
+    if (write) writing -= 1;
+  }
+}
+
+const p = (id: string) => `projects/${encodeURIComponent(id)}`;
+
+/** Studio's own preferences, the same for every project (studio/server/prefs.mjs). */
+export interface StudioPrefs {
+  proxies: { on: boolean; height: 540 | 720 | 1080 };
+  seenVersion: string | null;
+  projectsFolder: string | null;
+  /** the keyboard shortcuts: the scheme in use and the custom ones (lib/keymap `KeyPrefs`, checked there) */
+  keys?: unknown;
+}
+/** Where the projects library is (src/locations.mjs): the folder, its default, whether the person chose it, the free space on its disk, how many projects are in it. */
+export interface StudioLocation { path: string; default: string; chosen: boolean; free: number | null; count: number }
+export interface StudioLocations { projects: StudioLocation }
+/** Said on the window when they change, for what plays by them (the preview's proxies). */
+export const PREFS_EVENT = 'openfilm:prefs';
+/** Said on the window when the library moved, for the Projects list. */
+export const LIBRARY_EVENT = 'openfilm:library';
+
+/** A problem as Studio keeps it (src/problems.mjs): when, what it was about, what it said. */
+export interface StudioProblem {
+  t: string;
+  area: string;
+  what: string;
+  agent?: string;
+  step?: string;
+}
+
+export const api = {
+  /** this Studio's version and the latest openfilm on npm; `check`: ask npm now */
+  version: (check = false) => call<StudioVersion>(`version${check ? '?check=1' : ''}`),
+  /** the newest openfilm, run in the background (`openfilm update`): Studio starts again on it; refused (ApiError, `body.code`) while busy */
+  update: () => call<{ update: NonNullable<StudioVersion['update']> }>('update', { method: 'POST', json: {} }),
+  /** `openfilm doctor`, run by this Studio: the report to paste into an issue (src/doctor.mjs) */
+  doctor: () => call<{ ok: boolean; text: string }>('doctor'),
+  /** what went wrong in the last two weeks, newest first (src/problems.mjs) */
+  problems: () => call<{ problems: StudioProblem[] }>('diagnostics/problems').then((r) => r.problems),
+  /** the diagnostic file (server/diagnostics.mjs): `report` and the rest, zipped into the exports folder and shown there */
+  exportDiagnostics: (report: string, conversations: boolean) => call<{ path: string; files: string[]; conversations: boolean }>('diagnostics/export', { method: 'POST', json: { report, conversations } }),
+  projects: () => call<{ projects: Project[] }>('projects').then((r) => r.projects),
+  prefs: () => call<StudioPrefs>('prefs'),
+  /** where new projects and exports go, and the free space there */
+  locations: () => call<StudioLocations>('locations'),
+  /** move the library to `path` (null: the default); with `move`, its projects go too (those that could not are in `failed`) */
+  moveLibrary: (path: string | null, move: boolean) => call<{ moved: number; failed: { name: string; error: string }[]; locations: StudioLocations }>('locations/projects', { method: 'PUT', json: { path, move } }).then((done) => {
+    window.dispatchEvent(new Event(LIBRARY_EVENT));
+    return done;
+  }),
+  /** a project's folder, shown in the system's file manager */
+  revealProject: (id: string) => call<object>(`projects/${encodeURIComponent(id)}/reveal`, { method: 'POST', json: {} }),
+  /** one of them in the system's file manager */
+  openLocation: (which: keyof StudioLocations) => call<{ ok: true }>(`locations/${which}`, { method: 'POST', json: {} }),
+  setPrefs: (patch: { proxies?: Partial<StudioPrefs['proxies']>; seenVersion?: string; projectsFolder?: string | null; keys?: unknown }) => call<StudioPrefs>('prefs', { method: 'PATCH', json: patch }).then((prefs) => {
+    window.dispatchEvent(new Event(PREFS_EVENT));
+    return prefs;
+  }),
+  /** the system's folder dialog, opened by Studio (a page in a browser cannot learn a path): the folder, or null when
+      cancelled; throws (501) where this system has none */
+  pickFolder: (title: string, at?: string) => call<{ path: string | null }>('pick-folder', { method: 'POST', json: { title, ...(at ? { at } : {}) } }).then((r) => r.path),
+  newProject: (name?: string) => call<{ project: Project }>('projects', { method: 'POST', json: { name } }).then((r) => r.project),
+  /** open a folder (its full path) as a project: made one when it is not yet */
+  openFolder: (path: string) => call<{ project: Project }>('projects', { method: 'POST', json: { path } }).then((r) => r.project),
+  rename: (id: string, name: string) => call<{ project: Project }>(p(id), { method: 'PATCH', json: { name } }).then((r) => {
+    studioHost?.projectChanged?.(r.project);
+    return r.project;
+  }),
+  forget: (id: string) => call<object>(p(id), { method: 'DELETE' }),
+  film: (id: string) => call<ProjectFilm>(p(id)),
+  /** the person opened it here: the one `openfilm open` alone comes back to */
+  opened: (id: string) => call<{ project: Project }>(`${p(id)}/opened`, { method: 'POST' }),
+  edit: (id: string, base: string | null, ops: Op[]) => call<{ text: string; rev: string; value: Film; doc: Film; rebased: boolean }>(`${p(id)}/edit`, { method: 'POST', json: { base, ops } }),
+  files: (id: string) => call<Listing>(`${p(id)}/files`),
+  /** the editor's settings of the project (`.film/settings.json`): its frame rate, its tracks' names */
+  settings: (id: string) => call<{ settings: ProjectSettings }>(`${p(id)}/settings`).then((r) => r.settings),
+  /** change some of them (null takes one away); answers them all as kept */
+  patchSettings: (id: string, patch: { fps?: number | null; trackNames?: ProjectSettings['trackNames'] | null; trackHeights?: ProjectSettings['trackHeights'] | null }) => (
+    call<{ settings: ProjectSettings }>(`${p(id)}/settings`, { method: 'PATCH', json: patch }).then((r) => r.settings)
+  ),
+  /** its markers (`.film/markers.json`, lib/markers): the whole list, read and written */
+  markers: (id: string) => call<{ markers: unknown }>(`${p(id)}/markers`).then((r) => r.markers),
+  putMarkers: (id: string, markers: unknown[]) => call<{ markers: unknown }>(`${p(id)}/markers`, { method: 'PUT', json: { markers } }).then((r) => r.markers),
+  /** the loudness of a part of a file's sound (its own seconds): integrated LUFS (null: silent) and true peak */
+  loudness: (id: string, path: string, from: number, to: number) => call<{ lufs: number | null; peak: number | null }>(
+    `${p(id)}/media?what=loudness&path=${encodeURIComponent(path)}&from=${from}&to=${to}`,
+  ),
+  /** a video's frame (`ms` of its own time) made a still beside it; answers its path */
+  freezeFrame: (id: string, path: string, ms: number) => call<{ path: string }>(`${p(id)}/files/still`, { method: 'POST', json: { path, ms } }).then((r) => r.path),
+  /** The project's own cover for its card (studio/server/cover.mjs): a picture from this computer, a picture of the project,
+      the film at `ms`, or none (null: its film's poster again). Each answers when it was set. */
+  setCover: (id: string, from: { file: Blob } | { path: string } | { ms: number }) => call<{ cover: number | null }>(`${p(id)}/cover`,
+    'file' in from ? { method: 'PUT', body: from.file, headers: { 'content-type': 'application/octet-stream' } } : { method: 'POST', json: from }).then((r) => r.cover),
+  clearCover: (id: string) => call<{ cover: null }>(`${p(id)}/cover`, { method: 'DELETE' }).then(() => null),
+  answerAsk: (askId: string, allow: boolean) => call<{ answered: boolean }>(`get/asks/${encodeURIComponent(askId)}`, { method: 'POST', json: { allow } }),
+  /** the provider's own page for its balance, opened in the person's browser */
+  openBilling: (providerId: string) => call<Record<string, never>>(`providers/${encodeURIComponent(providerId)}/billing`, { method: 'POST' }),
+  /** clips (by id), clips together (a group) and files (by path) of a project put in Saved (studio/server/saved.mjs):
+      each one's place there */
+  save: (id: string, what: { clips?: SavedAsk[]; groups?: Array<SavedAsk & { ids: string[] }>; files?: Array<SavedAsk & { path: string }>; into?: string }) => (
+    call<{ paths: string[] }>(`${p(id)}/saved`, { method: 'POST', json: what }).then((r) => r.paths)
+  ),
+  /** a thing of Saved (its `saved/` path) used in the project: a file imported (its place), or a bundle's files brought in
+      and the clip, a group's clips or the page to put on the timeline */
+  takeSaved: (id: string, path: string) => call<{ clip: Record<string, unknown> & { src: string } } | { clips: SavedGroupClip[] } | { path: string }>(
+    `${p(id)}/saved/take`, { method: 'POST', json: { path } },
+  ),
+};
+
+/** A clip of a saved group: its track counted from the group's top one, its time in seconds from the group's start. */
+export type SavedGroupClip = { track: number; at: number; clip: Record<string, unknown> & { src: string } };
+
+/** What is said of a thing put in Saved: a clip's id (a file's path beside it), a name, and how long and big it is. */
+export type SavedAsk = { id?: string; name?: string; durationMs?: number; w?: number; h?: number };
+
+/** What an agent's `openfilm get` asks the person before it spends (studio/server/get.mjs). */
+export type SpendAsk = {
+  id: string; kind: 'video'; provider: string; model?: string; seconds?: number; prompt?: string;
+};
+
+/** What the person is told without a question (studio/server/get.mjs): a provider with no balance left for a run. */
+export type StudioNotice = { id: string; kind: 'balance'; provider: string; providerId: string };
+
+export type FolderEvent = { type: 'film'; rev: string } | { type: 'files'; paths?: string[] } | { type: 'history' } | { type: 'export'; job: ExportJob } | { type: 'open'; to: string }
+  | { type: 'history-progress'; op: string; phase: string; done: number; total: number }
+  | { type: 'ask'; ask: SpendAsk } | { type: 'asked'; id: string } | { type: 'notice'; notice: StudioNotice } | { type: 'project'; project: Project }
+  /* the project was deleted, or its folder is not there any more: its pages leave it */
+  | { type: 'gone' };
+
+/**
+ * Listen to a stream of events (a WebSocket: a browser's six HTTP connections to Studio stay free for the page's
+ * requests, however many pages are open); returns a function that stops listening. It reconnects on its own;
+ * `onBack` runs when it does (Studio stopped and started again: what changed meanwhile was not told). `watch`: this
+ * stream says whether Studio answers (studioConnection), and reloads the page when Studio comes back as another
+ * version (lib/studio-version); the page's own one does. It also tells Studio whether the page is in sight, so
+ * `openfilm open` opens a browser when no page is (a tab behind others, a minimized window).
+ */
+export function listen(path: string, on: (event: FolderEvent) => void, { onBack, watch = false, gone }: { onBack?: () => void; watch?: boolean; gone?: () => Promise<boolean> } = {}): () => void {
+  const inSight = () => document.visibilityState === 'visible';
+  const url = () => `${location.protocol === 'https:' ? 'wss' : 'ws'}://${location.host}/api/${path}${watch ? `?visible=${inSight() ? 1 : 0}` : ''}`;
+  const tell = () => { if (socket?.readyState === WebSocket.OPEN) socket.send(JSON.stringify({ visible: inSight() })); };
+  if (watch) document.addEventListener('visibilitychange', tell);
+  let socket: WebSocket | null = null;
+  let stopped = false, lost = false, tries = 0;
+  let again: ReturnType<typeof setTimeout> | null = null;
+  const watcher = watch ? watchConnection() : null;
+  if (watch) studioVersion ??= watchStudioVersion({
+    version: () => fetch('/api/health', { cache: 'no-store' }).then((r) => r.json()).then((h) => (typeof h?.version === 'string' ? h.version : null)),
+    idle: () => writing === 0,
+    reload: () => location.reload(),
+    storage: (() => { try { return sessionStorage; } catch { return null; } })(),
+  });
+  const connect = () => {
+    const s = new WebSocket(url());
+    socket = s;
+    s.onopen = () => {
+      tries = 0;
+      watcher?.up();
+      if (lost) {
+        lost = false;
+        onBack?.();
+        /* back as another version (a newer openfilm, or the desktop app's): this page's code is reloaded to match */
+        if (watch) void studioVersion?.back();
+      }
+    };
+    s.onmessage = (e) => { try { on(JSON.parse(String(e.data)) as FolderEvent); } catch { /* not ours */ } };
+    s.onclose = () => {
+      if (stopped) return;
+      lost = true;
+      watcher?.down();
+      /* refused, not gone: Studio is there but this browser has no key (the stream says no reason, a request does) */
+      if (watch && tries === 0) void fetch('/api/version', { cache: 'no-store' }).then((r) => { if (r.status === 401) markLocked(); }, () => {});
+      /* soon at first, then every second: Studio restarting (`openfilm open` starts it afresh) is back within one
+         or two, and waits a few for the pages before it */
+      again = setTimeout(connect, Math.min(1000, 250 * 2 ** tries++));
+      /* refused again and again while Studio answers: what it streams may be gone (a project deleted, its folder
+         moved away), which reconnecting can't change; asked, and if so said once and left */
+      if (gone && (tries === 3 || tries % 20 === 0)) {
+        void gone().then((yes) => {
+          if (!yes || stopped) return;
+          stopped = true;
+          if (again) clearTimeout(again);
+          on({ type: 'gone' });
+        }, () => {});
+      }
+    };
+  };
+  connect();
+  return () => { stopped = true; if (again) clearTimeout(again); if (watch) document.removeEventListener('visibilitychange', tell); watcher?.stop(); socket?.close(); };
+}
+
+/** Which version of Studio served this page (see listen's `watch`). */
+let studioVersion: ReturnType<typeof watchStudioVersion> | null = null;
+
+/**
+ * Whether Studio answers, for the notice when it does not: 'up', 'lost' (stopped a moment ago, reconnecting), 'gone'
+ * (still not back), or 'locked': Studio answers but not this browser, which was never let in (its address was typed
+ * or pasted without the key `openfilm open` prints, or its key is another launch's). Waiting does not fix that one.
+ */
+export type Connection = 'up' | 'lost' | 'gone' | 'locked';
+let connection: Connection = 'up';
+const connectionListeners = new Set<() => void>();
+export const studioConnection = {
+  get: () => connection,
+  subscribe(fn: () => void) { connectionListeners.add(fn); return () => { connectionListeners.delete(fn); }; },
+};
+/** Studio answered this page 401: it was never let in (see Connection). */
+export function markLocked() { setConnection('locked'); }
+function setConnection(next: Connection) {
+  if (next === connection || (connection === 'locked' && next !== 'up')) return;
+  connection = next;
+  for (const fn of [...connectionListeners]) fn();
+}
+/** A moment without Studio is said, a long one more plainly. */
+function watchConnection() {
+  let timers: ReturnType<typeof setTimeout>[] = [];
+  const clear = () => { for (const timer of timers) clearTimeout(timer); timers = []; };
+  return {
+    down() {
+      if (timers.length || connection !== 'up') return;
+      /* a blip (the computer woke, the stream was cut and came straight back) is not worth a notice */
+      timers = [setTimeout(() => setConnection('lost'), 2000), setTimeout(() => setConnection('gone'), 20_000)];
+    },
+    up() { clear(); setConnection('up'); },
+    stop: clear,
+  };
+}
+/* One stream per project, shared by everyone listening on the page. */
+const streams = new Map<string, { stop: () => void; listeners: Set<(event: FolderEvent) => void> }>();
+export function projectEvents(id: string, on: (event: FolderEvent) => void): () => void {
+  let stream = streams.get(id);
+  if (!stream) {
+    const listeners = new Set<(event: FolderEvent) => void>();
+    const tell = (event: FolderEvent) => {
+      if (listeners.size && event.type === 'project') studioHost?.projectChanged?.(event.project);
+      for (const fn of [...listeners]) fn(event);
+    };
+    /* back after Studio was away: the film, the files and the history may all have changed meanwhile */
+    const stop = listen(`${p(id)}/events`, tell, {
+      onBack: () => { tell({ type: 'film', rev: '' }); tell({ type: 'files' }); tell({ type: 'history' }); },
+      /* the project off the list, or its folder missing: gone (a list that can't be read says nothing) */
+      gone: () => call<{ projects: Project[] }>('projects').then((r) => { const found = r.projects.find((x) => x.id === id); return !found || Boolean(found.missing); }),
+    });
+    stream = { stop, listeners };
+    streams.set(id, stream);
+  }
+  stream.listeners.add(on);
+  const mine = stream;
+  return () => {
+    mine.listeners.delete(on);
+    if (!mine.listeners.size && streams.get(id) === mine) { mine.stop(); streams.delete(id); }
+  };
+}