auricui-skill 0.0.0-stage → 0.1.2

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

@@ -0,0 +1,156 @@
+/**
+ * Undo by clip id: the edit that takes the film after an edit back to the film before it, for what that edit touched.
+ * Worked out from the two films, not by remembering the files, so undoing puts back one clip without putting back
+ * what the agent changed meanwhile.
+ */
+import type { Clip, Film, Op } from '../api';
+import { DEFAULT_STAGE } from '../../../../src/film-doc.mjs';
+
+/** Deep copy of plain JSON. */
+const copy = <T,>(v: T): T => structuredClone(v);
+
+/** Where each clip is: its track and its row. */
+function index(film: Film) {
+  const at = new Map<string, { track: number; row: Clip }>();
+  film.tracks.forEach((track, t) => track.clips.forEach((row) => at.set(row.id, { track: t, row })));
+  return at;
+}
+
+/**
+ * Where a track that was at `track` in `before` is in `after`. Tracks have no names: a track is known by the clips it
+ * kept. `moved` are the clips the edit touched (they do not say where their track went). Returns its index, or where a
+ * new one should go when the edit left it empty and it went.
+ */
+function trackNow(before: Film, after: Film, track: number, moved: Set<string>): { track: number } | { newTrack: number } {
+  /** a track known by a clip it kept (one the edit did not touch) */
+  const anchored = (t: number) => {
+    const anchors = (before.tracks[t]?.clips.map((c) => c.id) ?? []).filter((id) => !moved.has(id));
+    if (!anchors.length) return null;
+    const i = after.tracks.findIndex((tr) => tr.clips.some((c) => anchors.includes(c.id)));
+    return i < 0 ? null : i;
+  };
+  const findBy = (t: number) => {
+    if ((before.tracks[t]?.clips ?? []).some((c) => !moved.has(c.id))) return anchored(t);
+    /* every clip of it was touched: it is a track holding only its clips (no other track's joined them there), still
+       between the same tracks; of several, the one holding most of them (else it went, and any of those is new) */
+    const own = before.tracks[t]?.clips.map((c) => c.id) ?? [];
+    const others = new Set(before.tracks.flatMap((tr, k) => (k === t ? [] : tr.clips.map((c) => c.id))));
+    const fits = (i: number) => {
+      if (after.tracks[i].clips.some((c) => others.has(c.id))) return false;
+      for (let k = 0; k < before.tracks.length; k++) {
+        const j = k === t ? null : anchored(k);
+        if (j != null && (k < t ? j >= i : j <= i)) return false;
+      }
+      return true;
+    };
+    const homes = after.tracks
+      .map((tr, i) => ({ i, mine: tr.clips.filter((c) => own.includes(c.id)).length }))
+      .filter((h) => h.mine > 0 && fits(h.i))
+      .sort((a, b) => b.mine - a.mine || a.i - b.i);
+    return homes.length ? homes[0].i : null;
+  };
+  const same = findBy(track);
+  if (same != null) return { track: same };
+  /* it went: a new one just below the nearest track above it that is still there */
+  for (let t = track - 1; t >= 0; t--) { const i = findBy(t); if (i != null) return { newTrack: i + 1 }; }
+  return { newTrack: 0 };
+}
+
+/** A clip's fields other than its identity and its place (those go back by a move). */
+const fieldsOf = (row: Clip) => Object.keys(row).filter((k) => k !== 'id' && k !== 'at');
+
+/**
+ * The edit that takes `after` back to `before`, for the clips and tracks `ops` touched: fields go back one by one, a
+ * moved clip goes back to its track and second, a removed one comes back, an added one goes.
+ */
+export function inverse(before: Film, after: Film, ops: Op[]): Op[] {
+  const was = index(before);
+  const now = index(after);
+  const ids = new Set<string>();
+  const undo: Op[] = [];
+  for (const op of ops) {
+    if (op.op === 'track') { undo.push({ op: 'track', track: op.track, field: op.field, value: Boolean(before.tracks[op.track]?.[op.field]) }); continue; }
+    if (op.op === 'reorder') { undo.push({ op: 'reorder', from: op.to, to: op.from }); continue; }
+    if (op.op === 'stage') { const { w, h } = before.stage ?? DEFAULT_STAGE; undo.push({ op: 'stage', w, h }); continue; }
+    if (op.op === 'insert') { for (const [id] of now) if (!was.has(id)) ids.add(id); continue; }
+    if (op.op === 'props') {
+      for (const e of op.edits) {
+        if (e.prop === 'trackOrder') {
+          const { from, to } = e.value as { from: number; to: number };
+          undo.push({ op: 'reorder', from: Math.max(0, Math.min(after.tracks.length - 1, to)), to: from });
+        } else if (e.prop === 'locked' || e.prop === 'hidden' || e.prop === 'muted') {
+          const home = now.get(e.clip);
+          const old = was.get(e.clip);
+          if (home && old) undo.push({ op: 'track', track: home.track, field: e.prop, value: Boolean(before.tracks[old.track]?.[e.prop]) });
+        } else ids.add(e.clip);
+      }
+      continue;
+    }
+    ids.add(op.clip);
+    if (op.op === 'split') for (const [id] of now) if (!was.has(id)) ids.add(id);
+  }
+  /* a track the edit left empty went with its flags; made again, it gets them back (or a muted track would come back
+     sounding). Pushed before the op that makes it: the list is reversed below, so they apply right after it */
+  const flagsBack = (home: ReturnType<typeof trackNow>, track: number) => {
+    if (!('newTrack' in home)) return;
+    for (const field of ['locked', 'hidden', 'muted'] as const) {
+      if (before.tracks[track]?.[field]) undo.push(goneTrack({ op: 'track', track: home.newTrack, field, value: true }, track));
+    }
+  };
+  /* the ops that make a track the edit left empty again, by the track it was in `before` */
+  const gone = new Map<Op, number>();
+  const goneTrack = (op: Op, track: number): Op => { gone.set(op, track); return op; };
+  for (const id of ids) {
+    const old = was.get(id);
+    const cur = now.get(id);
+    if (!old && cur) { undo.push({ op: 'remove', clip: id }); continue; }
+    if (!old) continue;
+    const home = trackNow(before, after, old.track, ids);
+    if (!cur) {
+      flagsBack(home, old.track);
+      const op: Op = { op: 'insert', clip: copy(old.row), ...home };
+      undo.push('newTrack' in home ? goneTrack(op, old.track) : op);
+      continue;
+    }
+    if (!('track' in home && home.track === cur.track) || (old.row.at ?? 0) !== (cur.row.at ?? 0)) {
+      flagsBack(home, old.track);
+      const op: Op = { op: 'move', clip: id, at: old.row.at ?? 0, ...home };
+      undo.push('newTrack' in home ? goneTrack(op, old.track) : op);
+    }
+    const then = old.row as Record<string, unknown>;
+    const nowRow = cur.row as Record<string, unknown>;
+    const changed = [...new Set([...fieldsOf(old.row), ...fieldsOf(cur.row)])].filter((field) => JSON.stringify(then[field]) !== JSON.stringify(nowRow[field]));
+    if (changed.length) undo.push({ op: 'fields', clip: id, fields: Object.fromEntries(changed.map((field) => [field, field in then ? copy(then[field]) : null])) });
+  }
+  return reopenTracks(undo.reverse(), gone);
+}
+
+/**
+ * A track the edit left empty comes back once, with all of its clips: the first of them opens it (`newTrack`), the
+ * others go onto it (`track`), or each would open a track of its own (deleting a whole track's clips and undoing put
+ * every clip on a new track). These go last, after what works on tracks still there (their indexes are `after`'s, and
+ * a track opened before them would shift them), from the top track down: a `newTrack` is a place among `after`'s
+ * tracks, and each track reopened above it moves it down one.
+ */
+function reopenTracks(ops: Op[], gone: ReadonlyMap<Op, number>): Op[] {
+  const out: Op[] = ops.filter((op) => !gone.has(op));
+  const byTrack = new Map<number, Op[]>();
+  for (const op of ops) {
+    const was = gone.get(op);
+    if (was != null) byTrack.set(was, [...(byTrack.get(was) ?? []), op]);
+  }
+  let above = 0;
+  for (const was of [...byTrack.keys()].sort((a, b) => a - b)) {
+    let at: number | null = null;
+    for (const op of byTrack.get(was)!) {
+      if (op.op === 'track') { if (at != null) out.push({ ...op, track: at }); continue; }
+      if (op.op !== 'insert' && op.op !== 'move') continue;
+      const { newTrack, ...rest } = op;
+      if (at != null) { out.push({ ...rest, track: at }); continue; }
+      at = (newTrack ?? 0) + above;
+      out.push({ ...rest, newTrack: at });
+    }
+    if (at != null) above += 1;
+  }
+  return out;
+}

package/skill/assets/upstream/packages/openfilm/studio/ui/src/editor/use-film.ts

@@ -0,0 +1,212 @@
+/**
+ * The film being edited: film.html as the server last wrote it, plus the edits made here since, already applied.
+ *
+ * An edit shows at once: it is applied here with the server's own code (server/ops.mjs), the picture is told, and the
+ * edit is sent to be written, one request at a time, each against the revision the last one produced. When the
+ * server answers that the film moved on without it (the agent removed the clip), the film here becomes the server's;
+ * so it does when the folder's film, once every edit here is written, is not the one here (the agent wrote it a moment
+ * before, and the server applied the edit on top). A film.html that cannot be read (the agent is halfway through
+ * writing it, or wrote it wrong) is `broken`: the film here stays as it last was, and edits wait for it to be whole.
+ *
+ * Undo and redo are edits too, worked out by clip id from the film before and after (`inverse`), so undoing a move
+ * puts that clip back without putting back what the agent changed meanwhile.
+ */
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { applyOps, EditError } from '../../../server/ops.mjs';
+import { filmHead } from '../../../../src/film-doc.mjs';
+import { api, ApiError, projectEvents, type Film, type Op } from '../api';
+import { inverse } from './undo';
+import { dropStep, moveStep, nextStep, pushStep, type Steps } from './steps';
+
+export type FilmState = { value: Film; rev: string };
+
+/**
+ * One edit a person made here, undoable: what undoes it, what makes it again, and what to call it in the history.
+ * `outside`: an edit of another file than film.html (a subtitle's times, in its transcript), undone and made again by
+ * its own calls, which resolve to null or why they could not; its `undo` and `redo` are empty.
+ */
+export type Step = { undo: Op[]; redo: Op[]; label: string; at: number; outside?: OutsideStep };
+export type OutsideStep = { undo: () => Promise<string | null>; redo: () => Promise<string | null> };
+
+/**
+ * The film of a project, editable. `onChange(value, kind, head)` tells the picture: `edit` for an edit made here (try
+ * it in place), `server` for the film as the folder has it now (the agent wrote it, or an edit was refused), with its
+ * file's head when known (a changed one is the film loaded again: its styles are not in the value).
+ */
+export function useFilm(projectId: string, initial: FilmState | null, onChange: (value: Film, kind: 'edit' | 'server', head?: string) => void) {
+  const [state, setState] = useState<FilmState | null>(initial);
+  const [error, setError] = useState<string | null>(null);
+  /** why film.html cannot be read now (null: it can) */
+  const [broken, setBroken] = useState<string | null>(null);
+  const brokenRev = useRef<string | null>(null);
+  /** edits applied here and not yet written */
+  const pending = useRef(0);
+  const [steps, setStepsState] = useState<Steps<Step>>({ done: [], undone: [] });
+  /* the steps as they are now, ahead of the render: an undo pressed right after an edit (a nudge written the moment
+     before it) undoes that edit, not the one before */
+  const stepsRef = useRef(steps);
+  const setSteps = useCallback((next: (s: Steps<Step>) => Steps<Step>) => {
+    stepsRef.current = next(stepsRef.current);
+    setStepsState(stepsRef.current);
+  }, []);
+  const ref = useRef(state);
+  ref.current = state;
+  const queue = useRef(Promise.resolve());
+  /**
+   * revisions this editor wrote, oldest first: their echo from the folder watcher is not news. The watcher reports the
+   * file as it is once writes settle, so an echo also stands for every write before it, unreported; those are
+   * forgotten with it, or an outside write that happens to match one of them (the agent putting back an earlier text)
+   * would be taken for an echo and never shown.
+   */
+  const ours = useRef(new Set<string>());
+  const echoOf = (rev: string) => {
+    if (!ours.current.has(rev)) return false;
+    for (const r of ours.current) { ours.current.delete(r); if (r === rev) break; }
+    return true;
+  };
+  const changed = useRef(onChange);
+  changed.current = onChange;
+  useEffect(() => { if (initial && !ref.current) setState(initial); }, [initial]);
+
+  /** The film as the folder has it now; false when film.html cannot be read (`broken` says why). */
+  const fromServer = useCallback(async (): Promise<boolean> => {
+    const latest = await api.film(projectId);
+    if (!latest.doc || !latest.value) {
+      brokenRev.current = latest.rev;
+      setBroken(latest.problems.join('\n') || 'film.html cannot be read');
+      return false;
+    }
+    if (brokenRev.current) { brokenRev.current = null; setBroken(null); setError(null); }
+    const next = { value: latest.value, rev: latest.rev };
+    ref.current = next;
+    setState(next);
+    changed.current(next.value, 'server', filmHead(latest.text));
+    return true;
+  }, [projectId]);
+
+  /* the agent's writes: the film becomes the folder's (an edit of ours still on its way is applied on top by the server) */
+  useEffect(() => projectEvents(projectId, (event) => {
+    if (event.type !== 'film' || echoOf(event.rev)) return;
+    /* the same text as here is news only after the file could not be read (written whole again) */
+    if (event.rev === ref.current?.rev && !brokenRev.current) return;
+    /* not read: Studio went away (it was stopping) — it tells again when it is back */
+    void queue.current.then(fromServer).catch(() => {});
+  }), [projectId, fromServer]);
+
+  /**
+   * Apply `ops` here at once, then write them. Resolves once written: null, or why it was not (the film here is then
+   * the folder's again). Resolves at once with the reason when the film here refuses them.
+   */
+  /* `quiet`: the caller says why it was refused itself (the inspector, beside its field), so `error` is not set.
+     `one`: the step an undo or redo takes, moved to the other list once applied here */
+  const run = useCallback((ops: Op[], record: 'do' | 'undo' | 'redo' = 'do', label = 'history.stepEdit', quiet = false, one?: Step): Promise<string | null> => {
+    const current = ref.current;
+    if (!current || !ops.length) return Promise.resolve(null);
+    /* film.html cannot be read: the edit could not be written, and shown it would draw the picture again from the
+       broken file. Nothing changes; the note on the film already says why (`broken`) */
+    if (brokenRev.current) return Promise.resolve(null);
+    let after: Film;
+    try { after = applyOps(structuredClone(current.value), ops) as Film; }
+    catch (e) {
+      const why = e instanceof EditError ? e.message : String(e);
+      if (!quiet) setError(why);
+      return Promise.resolve(why);
+    }
+    const before = current.value;
+    const next = { value: after, rev: current.rev };
+    ref.current = next;
+    setState(next);
+    setError(null);
+    changed.current(after, 'edit');
+    pending.current += 1;
+    const step: Step = { undo: inverse(before, after, ops), redo: ops, label, at: Date.now() };
+    setSteps((s) => (record === 'do' ? pushStep(s, step) : one ? moveStep(s, one, record) : s));
+    const written = queue.current.then(async (): Promise<string | null> => {
+      try {
+        const done = await api.edit(projectId, ref.current?.rev ?? null, ops);
+        ours.current.delete(done.rev);
+        ours.current.add(done.rev);
+        pending.current -= 1;
+        const here = ref.current;
+        if (!here) return null;
+        /* every edit here written: the folder's film is the truth (another write came in under this one) */
+        const theirs = pending.current === 0 ? done.value : null;
+        if (theirs && (done.rebased || JSON.stringify(theirs) !== JSON.stringify(here.value))) {
+          ref.current = { value: theirs, rev: done.rev };
+          setState(ref.current);
+          changed.current(theirs, 'server', filmHead(done.text));
+        } else {
+          ref.current = { ...here, rev: done.rev };
+          setState((s) => (s ? { ...s, rev: done.rev } : s));
+        }
+        return null;
+      } catch (e) {
+        pending.current -= 1;
+        const why = e instanceof ApiError ? e.message : String(e);
+        /* what was not written is not a step to undo */
+        if (record === 'do') setSteps((s) => ({ ...s, done: s.done.filter((x) => x !== step) }));
+        if (!(await fromServer())) {
+          /* the folder's film cannot be read: back to the film as it was before this edit (the note on the film says
+             why, so it is not said again) */
+          ref.current = current;
+          setState(current);
+          changed.current(current.value, 'server');
+          return null;
+        }
+        if (!quiet) setError(why);
+        return why;
+      }
+    });
+    queue.current = written.then(() => {});
+    return written;
+  }, [projectId, fromServer, setSteps]);
+
+  /* a step of another file: moved between the lists at once, its call made in turn with the film's writes; one that
+     cannot be undone (the file changed since, elsewhere) leaves both lists, and says why */
+  const runOutside = useCallback((step: Step, kind: 'undo' | 'redo') => {
+    setSteps((s) => moveStep(s, step, kind));
+    const written = queue.current.then(async () => {
+      const why = await step.outside![kind]().catch((e: unknown) => String(e instanceof Error ? e.message : e));
+      if (why) {
+        setError(why);
+        setSteps((s) => dropStep(s, step));
+      }
+    });
+    queue.current = written;
+  }, [setSteps]);
+  /* a step of the film: one whose ops cannot be applied or written now (the agent removed its clip since) leaves both
+     lists, as one of another file does, so the next undo takes the step before it and the history ends at the oldest */
+  const step = useCallback((one: Step, kind: 'undo' | 'redo') => {
+    if (one.outside) { runOutside(one, kind); return; }
+    const ops = kind === 'undo' ? one.undo : one.redo;
+    /* nothing to apply (an edit that changed nothing): it only moves */
+    if (!ops.length) { setSteps((s) => moveStep(s, one, kind)); return; }
+    void run(ops, kind, undefined, false, one).then((why) => { if (why) setSteps((s) => dropStep(s, one)); });
+  }, [run, runOutside, setSteps]);
+  const undo = useCallback(() => {
+    const one = nextStep(stepsRef.current, 'undo');
+    if (one) step(one, 'undo');
+  }, [step]);
+  const redo = useCallback(() => {
+    const one = nextStep(stepsRef.current, 'redo');
+    if (one) step(one, 'redo');
+  }, [step]);
+  /** Undo or redo until `done` steps are done (the edit history's rows: click one to go back or forward to it). */
+  const rollbackTo = useCallback((done: number) => {
+    let { done: d, undone: u } = stepsRef.current;
+    while (d.length > done && d.length) { const one = d[d.length - 1]; step(one, 'undo'); u = [...u, one]; d = d.slice(0, -1); }
+    while (d.length < done && u.length) { const one = u[u.length - 1]; step(one, 'redo'); d = [...d, one]; u = u.slice(0, -1); }
+  }, [step]);
+  const edit = useCallback((ops: Op[], label?: string, quiet?: boolean) => run(ops, 'do', label, quiet), [run]);
+  /** An edit of another file, made already: kept as a step, so ⌘Z undoes it in turn with the film's. */
+  const record = useCallback((label: string, outside: OutsideStep) => {
+    setSteps((s) => pushStep(s, { undo: [], redo: [], label, at: Date.now(), outside }));
+  }, [setSteps]);
+  /** The film was replaced as a whole (an earlier version put back): the edits made before are not undone into it. */
+  const forget = useCallback(() => setSteps(() => ({ done: [], undone: [] })), [setSteps]);
+
+  return {
+    film: state?.value ?? null, rev: state?.rev ?? null, error, broken, edit, record, undo, redo, rollbackTo, forget, steps,
+    canUndo: steps.done.length > 0, canRedo: steps.undone.length > 0, settled: () => queue.current,
+  };
+}

package/skill/assets/upstream/packages/openfilm/studio/ui/src/editor/use-preview-renders.ts

@@ -0,0 +1,89 @@
+/**
+ * Preview renders, the editor's side: the stretches that play late (measured as the film plays, lib/preview-renders)
+ * are asked to be rendered once the film has stopped for a moment (studio/server/preview-cache.mjs, in the
+ * background), followed while they are made, and told to the preview when they are, to play in the film's place.
+ * Anything changed in the project (film.html, a page, a file) and those renders are not played until the server names
+ * them for the project as it is now.
+ */
+import { useCallback, useEffect, useMemo, useRef, useState, type RefObject } from 'react';
+import { addHeat, joinStretches, lateStretches, sameStretches, type Heat } from '@/lib/preview-renders';
+import type { PlayedReport, PreviewHandle, PreviewRender } from './Preview';
+
+type Made = { a: number; b: number; key: string; state: 'waiting' | 'making' | 'ready' | 'failed'; ratio?: number };
+
+/** How long the film stays stopped (and unchanged) before what plays late is rendered (ms). */
+const IDLE_MS = 2000;
+/** How often renders being made are asked after (ms). */
+const FOLLOW_MS = 1500;
+
+export function usePreviewRenders({ projectId, folder, fps, playing, on, film, files, preview }: {
+  projectId: string;
+  /** the project's folder on the film's origin (the preview's address of it) */
+  folder: string;
+  /** the film's frame rate: renders are made at it */
+  fps: number;
+  playing: boolean;
+  /** Settings → Playback: render what plays late */
+  on: boolean;
+  /** film.html as it is now, and the project's files' version: either changing makes the renders made before stale */
+  film: unknown;
+  files: unknown;
+  preview: RefObject<PreviewHandle | null>;
+}) {
+  const heat = useRef<Heat>(new Map());
+  /* known late before this session (the server keeps them with the renders), and found late as it plays */
+  const known = useRef<[number, number][]>([]);
+  const [late, setLate] = useState<[number, number][]>([]);
+  const [made, setMade] = useState<Made[]>([]);
+  const madeRef = useRef(made);
+  madeRef.current = made;
+  const lateNow = () => joinStretches([...known.current, ...lateStretches(heat.current)]);
+  const onPlayed = useCallback((report: PlayedReport) => {
+    /* a half second played from its render says nothing of how the film itself plays there */
+    const rendered = madeRef.current.filter((r) => r.state === 'ready');
+    addHeat(heat.current, report.spans.filter(([t]) => !rendered.some((r) => t + 0.5 > r.a && t < r.b)));
+    const next = lateNow();
+    setLate((had) => (sameStretches(had, next) ? had : next));
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+  /* another project: what is known of how it plays, from the server (an earlier session's), and its renders */
+  useEffect(() => {
+    heat.current = new Map();
+    known.current = [];
+    setLate([]);
+    setMade([]);
+    if (!on || !(fps > 0)) return undefined;
+    let alive = true;
+    void fetch(`/api/projects/${encodeURIComponent(projectId)}/preview-cache?fps=${fps}`).then((r) => (r.ok ? r.json() : null), () => null)
+      .then((answer: { late?: [number, number][]; ranges?: Made[] } | null) => {
+        if (!alive || !answer?.late?.length) return;
+        known.current = answer.late;
+        setLate(lateNow());
+        setMade(answer.ranges ?? []);
+      });
+    return () => { alive = false; };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [projectId, on, fps]);
+  /* the project changed: what was rendered of it is not played until it is named for the project as it is now */
+  useEffect(() => { setMade([]); }, [film, files]);
+  useEffect(() => {
+    if (!on || playing || !late.length || !(fps > 0)) return undefined;
+    let alive = true;
+    let timer = 0;
+    const ask = async () => {
+      const answer = await fetch(`/api/projects/${encodeURIComponent(projectId)}/preview-cache`, {
+        method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ ranges: late, fps }),
+      }).then((r) => (r.ok ? r.json() : null), () => null) as { ranges?: Made[] } | null;
+      if (!alive || !answer?.ranges) return;
+      setMade(answer.ranges);
+      if (answer.ranges.some((r) => r.state === 'waiting' || r.state === 'making')) timer = window.setTimeout(() => { void ask(); }, FOLLOW_MS);
+    };
+    timer = window.setTimeout(() => { void ask(); }, IDLE_MS);
+    return () => { alive = false; window.clearTimeout(timer); };
+  }, [on, playing, late, fps, projectId, film, files]);
+  const list = useMemo<PreviewRender[]>(() => (on
+    ? made.filter((r) => r.state === 'ready').map((r) => ({ a: r.a, b: r.b, src: `${folder}__film/preview/${r.key}.mp4` }))
+    : []), [on, made, folder]);
+  useEffect(() => { preview.current?.renders?.(list); }, [list, preview]);
+  return { onPlayed };
+}