Skip to content

Code-first video & image, rendered natively on WebGPU.

preview imprv

okanasl4bf477c9cb37
diff --git a/.changeset/preview-agent-friendly.md b/.changeset/preview-agent-friendly.md
new file mode 100644
index 00000000..1fb3bf53
--- /dev/null
+++ b/.changeset/preview-agent-friendly.md
@@ -0,0 +1,9 @@
+---
+"gitframes": patch
+---
+
+Preview: the page's errors and the server's lifecycle are printed where the preview runs, `session.closed` resolves with why it stopped, the playhead survives reloads and `#t=` links, and `window.gitframesPreview` lets scripts seek, play and read state. The audio mixer no longer prints its progress at info level.
+
+Preview notes: pause and click the picture (or drag an area) to pin a note to that spot and moment. Notes are saved in `.gitframes/preview-notes/` (`notes.json` plus the frame with the spot marked), printed in the preview's output, listed in a Notes panel and on the timeline, and can be ticked off or copied for a chat. `notesDir` moves them, `false` turns them off.
+
+Preview playback: pausing keeps the frames rendered ahead (and keeps filling them), so playing on starts at once; moving the playhead clears them. Fixes a seek that could wait forever when it landed while a buffered frame was drawing.
diff --git a/README.md b/README.md
index f613e466..107888db 100644
--- a/README.md
+++ b/README.md
@@ -262,7 +262,9 @@ Project normalized landmarks to screen space with a configurable camera FOV, the
### 8. Live Preview in the Browser
- **Runs your composition, not a video** — `startPreview({ entry, export })` serves a localhost WebGPU player that loads the composition's own module and renders every frame live in the browser. Nothing is streamed: the server only hands over the bundle, the project's assets, and the soundtrack mixed by the export engine.
- **Timeline, waveform & frame stepping** — play/pause, scrub, step frame by frame, and read resolution, FPS, duration, and audio status at a glance.
-- **One stable URL per project** — the port is derived from the working directory, so re-running the preview replaces the running server and any open tab reloads into the new version by itself. Close the tab and the server shuts down about five seconds later.
+- **One stable URL per project** — the port is derived from the working directory, so re-running the preview replaces the running server and any open tab reloads into the new version by itself. Close the tab and the server shuts down about five seconds later. A reload comes back at the same moment, and `#t=12.5` links to one.
+- **Notes pinned on the picture** — pause, click a spot (or drag an area) and write what should change. Each note keeps its moment, its spot and a picture of the frame with the spot marked, in `.gitframes/preview-notes/`, and prints where the preview runs, so an agent can apply exactly what you meant. Tick notes off as you check them.
+- **Tells you what happened** — the page's errors (a failed build, a frame that threw, a missing font) and why the server stopped are printed where the preview runs, so whoever started it, person or agent, sees them without opening devtools. Scripts can drive the page through `window.gitframesPreview` (`seek`, `play`, `pause`, `state`).
- **Shown where you are** — `startPreview` serves the page and returns its URL instead of opening a browser, so an agent can show it in its own pane (Claude Code, Codex); pass `open: true` to open the system browser.
```typescript
diff --git a/packages/compositions/src/utils/audio-extractor.ts b/packages/compositions/src/utils/audio-extractor.ts
index 696d6a2d..b930b2f4 100644
--- a/packages/compositions/src/utils/audio-extractor.ts
+++ b/packages/compositions/src/utils/audio-extractor.ts
@@ -16,7 +16,7 @@ const verbose =
// Fallback logger for browser environment. In Node.js environment, we dynamically load @gitframes/server-utils to avoid bundling it on the frontend.
let mediaLogger = {
- info: (msg: unknown, ...args: unknown[]) => {
+ debug: (msg: unknown, ...args: unknown[]) => {
if (!verbose) return;
if (typeof msg === "object" && msg !== null) {
console.info("[AudioExtractor]", msg, ...args);
@@ -130,7 +130,7 @@ export interface AudioClip {
export async function decodeAudioSource(
url: string,
): Promise<{ channels: Float32Array[]; sampleRate: number } | null> {
- mediaLogger.info(
+ mediaLogger.debug(
`[AudioExtractor] decodeAudioSource started for url: ${url}`,
);
try {
@@ -143,7 +143,7 @@ export async function decodeAudioSource(
process.versions.node
);
if (isBrowser) {
- mediaLogger.info(
+ mediaLogger.debug(
`[AudioExtractor] Browser detected. Fetching arrayBuffer for ${url}...`,
);
const AudioContextClass =
@@ -154,7 +154,7 @@ export async function decodeAudioSource(
const audioCtx = new AudioContextClass();
try {
const response = await fetch(url);
- mediaLogger.info(
+ mediaLogger.debug(
`[AudioExtractor] Fetch response status for ${url}: ${response.status} (${response.statusText})`,
);
if (!response.ok) {
@@ -163,11 +163,11 @@ export async function decodeAudioSource(
);
}
const arrayBuffer = await response.arrayBuffer();
- mediaLogger.info(
+ mediaLogger.debug(
`[AudioExtractor] Fetched ${arrayBuffer.byteLength} bytes. Decoding audio data...`,
);
const audioBuffer = await audioCtx.decodeAudioData(arrayBuffer);
- mediaLogger.info(
+ mediaLogger.debug(
`[AudioExtractor] Decoded successfully: ${audioBuffer.numberOfChannels} channels, sampleRate: ${audioBuffer.sampleRate}, duration: ${audioBuffer.duration}s`,
);
@@ -178,18 +178,18 @@ export async function decodeAudioSource(
return { channels, sampleRate: audioBuffer.sampleRate };
} finally {
void audioCtx.close();
- mediaLogger.info(`[AudioExtractor] AudioContext closed for ${url}`);
+ mediaLogger.debug(`[AudioExtractor] AudioContext closed for ${url}`);
}
}
let inputAcquired = false;
try {
- mediaLogger.info(
+ mediaLogger.debug(
`[AudioExtractor] Server / Node.js detected. Acquiring from inputStore for ${url}...`,
);
const input = await inputStore.acquire(url);
inputAcquired = true;
- mediaLogger.info(
+ mediaLogger.debug(
`[AudioExtractor] inputStore acquired. Retrieving primary audio track...`,
);
const track = await input.getPrimaryAudioTrack();
@@ -208,7 +208,7 @@ export async function decodeAudioSource(
let sampleRate = 48000;
let numChannels = 1;
- mediaLogger.info(
+ mediaLogger.debug(
`[AudioExtractor] Starting mediabunny generator loop for ${url}...`,
);
for await (const sample of generator) {
@@ -275,7 +275,7 @@ export async function decodeAudioSource(
totalFrames += sampleFrames;
sample.close();
}
- mediaLogger.info(
+ mediaLogger.debug(
`[AudioExtractor] Generator loop finished. Decoded total frames: ${totalFrames}`,
);
@@ -400,7 +400,7 @@ export async function mixAudioTracks(
device?: GPUDevice,
renderId?: string,
): Promise<{ channels: Float32Array[]; sampleRate: number }> {
- mediaLogger.info(
+ mediaLogger.debug(
`[AudioExtractor] mixAudioTracks started. FPS: ${fps}, targetSampleRate: ${targetSampleRate}`,
);
await waitForDelayRender();
@@ -411,7 +411,7 @@ export async function mixAudioTracks(
const durationMs = getActiveMediaMetadata(virtualMedia)?.durationMs || 1000;
const totalDurationSec = durationMs / 1000;
const totalTargetSamples = Math.ceil(totalDurationSec * targetSampleRate);
- mediaLogger.info(
+ mediaLogger.debug(
`[AudioExtractor] Composition total duration: ${durationMs}ms (${totalDurationSec}s). Total mixed samples to allocate: ${totalTargetSamples}`,
);
diff --git a/packages/gitframes/src/index.ts b/packages/gitframes/src/index.ts
index df87912a..9cd1fc43 100644
--- a/packages/gitframes/src/index.ts
+++ b/packages/gitframes/src/index.ts
@@ -2639,6 +2639,7 @@ export const Light = {
};
export {
+ type PreviewCloseReason,
type PreviewOptions,
type PreviewSession,
type PreviewSource,
diff --git a/packages/gitframes/src/preview/index.ts b/packages/gitframes/src/preview/index.ts
index 52185fbf..4d0f8877 100644
--- a/packages/gitframes/src/preview/index.ts
+++ b/packages/gitframes/src/preview/index.ts
@@ -15,6 +15,7 @@ import {
onnxRuntimeWeb,
visionModelsDir,
} from "./bundle.js";
+import { describeNote, type NewNote, NoteStore } from "./notes.js";
import { previewPage } from "./page.js";
/** Where the composition comes from: the module that builds it. */
@@ -73,17 +74,43 @@ export interface PreviewOptions {
* several to allow assets kept outside it.
*/
root?: string | string[];
+ /**
+ * Where the preview reports what happens out of sight: the page opening,
+ * errors in the page (a failed build, a frame that threw, no WebGPU), and
+ * why the server stopped. Defaults to stderr, so whoever runs the preview
+ * (an agent's background command, say) reads them in its output. `false`
+ * keeps it quiet.
+ */
+ log?: ((line: string) => void) | false;
+ /**
+ * Where notes pinned on the page are kept: `notes.json` and, per note, the
+ * frame with its spot marked. Defaults to `.gitframes/preview-notes` in the
+ * working directory (`.gitframes` ignores itself in git). `false` turns
+ * notes off.
+ */
+ notesDir?: string | false;
}
+/** Why a preview stopped. */
+export type PreviewCloseReason =
+ /** `close()` was called. */
+ | "closed"
+ /** Its last tab closed (see `idleCloseMs`). */
+ | "idle"
+ /** A newer preview of the project took over its port. */
+ | "replaced";
+
export interface PreviewSession {
url: string;
close(): Promise<void>;
- /** Resolves when the server stops: `close()`, an idle tab, or a newer preview took over its port. */
- closed: Promise<void>;
+ /** Resolves with the reason when the server stops. */
+ closed: Promise<PreviewCloseReason>;
}
interface PreviewMeta {
session: string;
+ /** Where notes are kept; null when they are off. */
+ notesDir: string | null;
title: string;
fps: number;
frameCount: number;
@@ -142,9 +169,29 @@ export async function startPreview(
let idleTimer: NodeJS.Timeout | undefined;
const title = options.title ?? "gitframes preview";
const session = randomUUID();
+ const log =
+ options.log === false
+ ? () => {}
+ : (options.log ?? ((line: string) => console.error(line)));
+ const say = (line: string) => log(`[gitframes preview] ${line}`);
+ // Each distinct page error is reported once; playback repeats them per frame.
+ const reported = new Set<string>();
+ let pageOpened = false;
+
+ const notes =
+ options.notesDir === false
+ ? undefined
+ : new NoteStore(
+ path.resolve(
+ options.notesDir ??
+ path.join(process.cwd(), ".gitframes", "preview-notes"),
+ ),
+ );
+ // Changes run one at a time: each reads and rewrites notes.json.
+ let noteQueue: Promise<unknown> = Promise.resolve();
const target = await loadTarget(entry, exportName);
- const meta = await resolveMeta(target, title, session);
+ const meta = await resolveMeta(target, title, session, notes?.dir ?? null);
// The project's own code, bundled against the browser engine; the engine
// itself is prebuilt (or built once, running from source).
let bundle: Promise<string> | undefined;
@@ -157,7 +204,10 @@ export async function startPreview(
ortBase: ort.base,
}).then((b) => b.code);
bundle = built;
- built.catch(() => {
+ built.catch((err: unknown) => {
+ say(
+ `could not build ${path.relative(process.cwd(), entry)}:\n${errorText(err)}`,
+ );
// Let a later request try again, unless it started its own build.
if (bundle === built) bundle = undefined;
});
@@ -221,19 +271,21 @@ export async function startPreview(
);
}
- let resolveClosed!: () => void;
- const closed = new Promise<void>((r) => {
+ let resolveClosed!: (reason: PreviewCloseReason) => void;
+ const closed = new Promise<PreviewCloseReason>((r) => {
resolveClosed = r;
});
let closing: Promise<void> | undefined;
- function close(): Promise<void> {
+ function close(reason: PreviewCloseReason = "closed"): Promise<void> {
closing ??= new Promise<void>((resolve) => {
clearTimeout(idleTimer);
+ if (reason === "idle") say("stopped: its tab was closed");
+ if (reason === "replaced") say("stopped: a newer preview took over");
for (const client of sseClients) client.end();
sseClients.clear();
server.close(() => {
resolve();
- resolveClosed();
+ resolveClosed(reason);
});
server.closeAllConnections();
});
@@ -318,13 +370,21 @@ export async function startPreview(
);
sseClients.add(res);
clearTimeout(idleTimer);
+ if (!pageOpened) {
+ pageOpened = true;
+ say(
+ idleCloseMs === false
+ ? "page opened"
+ : `page opened; the server stops ${Number((idleCloseMs / 1000).toFixed(1))} s after its last tab closes`,
+ );
+ }
onClient?.();
req.on("close", () => {
sseClients.delete(res);
// A reload reconnects within a second; a closed tab doesn't.
if (sseClients.size === 0 && idleCloseMs !== false && !closing) {
idleTimer = setTimeout(() => {
- if (sseClients.size === 0) void close();
+ if (sseClients.size === 0) void close("idle");
}, idleCloseMs);
}
});
@@ -338,9 +398,58 @@ export async function startPreview(
req.headers[TAKEOVER_HEADER] === "1"
) {
sendJson(res, 200, { ok: true });
- setImmediate(() => void close());
+ setImmediate(() => void close("replaced"));
return;
}
+ // Errors in the page, so they reach the terminal (and an agent)
+ // without anyone looking at the browser. JSON only: other sites
+ // can't send that without a preflight this server doesn't answer.
+ if (
+ req.method === "POST" &&
+ url.pathname === "/@gitframes/log" &&
+ req.headers["content-type"] === "application/json"
+ ) {
+ const body = await readBody(req, 16 * 1024);
+ const { message, level } = JSON.parse(body) as {
+ message?: unknown;
+ level?: unknown;
+ };
+ const text = String(message ?? "").trim();
+ if (text && !reported.has(text) && reported.size < 200) {
+ reported.add(text);
+ say(
+ `${level === "warning" ? "warning" : "error"} in the page: ${text}`,
+ );
+ }
+ res.writeHead(204).end();
+ return;
+ }
+ if (notes && url.pathname === "/@gitframes/notes") {
+ if (req.method === "GET") {
+ sendJson(res, 200, await notes.list());
+ return;
+ }
+ if (
+ req.method === "POST" &&
+ req.headers["content-type"] === "application/json"
+ ) {
+ const body = JSON.parse(await readBody(req, 16 * 1024 * 1024)) as {
+ op?: string;
+ id?: number;
+ done?: boolean;
+ text?: string;
+ note?: NewNote;
+ };
+ const change = noteQueue.then(() =>
+ changeNote(notes, body, meta.fps, say),
+ );
+ noteQueue = change.catch(() => {});
+ const note = await change;
+ broadcast("notes", await notes.list());
+ sendJson(res, note ? 200 : 404, note ?? { error: "no such note" });
+ return;
+ }
+ }
if (req.method === "GET" && url.pathname === "/audio") {
if (audio.state !== "ready" || !audioWav) {
sendJson(res, 404, { error: `audio is ${audio.state}` });
@@ -444,7 +553,7 @@ export async function startPreview(
if (!reconnected) openBrowser(url);
}
- return { url, closed, close };
+ return { url, closed, close: () => close() };
}
async function loadTarget(
@@ -482,6 +591,63 @@ function repoRoot(dir: string): string {
}
}
+/** Applies one change from the page and says what it was. */
+async function changeNote(
+ notes: NoteStore,
+ body: {
+ op?: string;
+ id?: number;
+ done?: boolean;
+ text?: string;
+ note?: NewNote;
+ },
+ fps: number,
+ say: (line: string) => void,
+) {
+ if (body.op === "add" && body.note && String(body.note.text).trim()) {
+ const note = await notes.add(body.note);
+ const files = [
+ note.image && `frame with the spot marked: ${note.image}`,
+ `all notes: ${notes.file}`,
+ ];
+ say(`${describeNote(note, fps)}\n ${files.filter(Boolean).join(" · ")}`);
+ return note;
+ }
+ const id = Number(body.id);
+ if (body.op === "update") {
+ const note = await notes.update(id, body);
+ if (note && typeof body.done === "boolean")
+ say(`note ${id} marked ${note.done ? "done" : "open"}`);
+ return note;
+ }
+ if (body.op === "remove") {
+ const note = await notes.remove(id);
+ if (note) say(`note ${id} deleted`);
+ return note;
+ }
+ return undefined;
+}
+
+function errorText(err: unknown): string {
+ return err instanceof Error ? err.message : String(err);
+}
+
+function readBody(req: http.IncomingMessage, limit: number): Promise<string> {
+ return new Promise((resolve, reject) => {
+ let body = "";
+ req.setEncoding("utf8");
+ req.on("data", (chunk: string) => {
+ body += chunk;
+ if (body.length > limit) {
+ reject(new Error("request body too large"));
+ req.destroy();
+ }
+ });
+ req.on("end", () => resolve(body));
+ req.on("error", reject);
+ });
+}
+
function isInside(root: string, file: string): boolean {
const rel = path.relative(root, file);
return !!rel && !rel.startsWith("..") && !path.isAbsolute(rel);
@@ -566,12 +732,14 @@ async function resolveMeta(
target: PreviewTarget,
title: string,
session: string,
+ notesDir: string | null,
): Promise<PreviewMeta> {
const fps = target.fps ?? 24;
const durationMs =
target.durationMs ?? (await target.computeDuration?.()) ?? 5000;
return {
session,
+ notesDir,
title,
fps,
frameCount: Math.max(1, Math.round((durationMs / 1000) * fps)),
diff --git a/packages/gitframes/src/preview/notes.ts b/packages/gitframes/src/preview/notes.ts
new file mode 100644
index 00000000..f12c3ef6
--- /dev/null
+++ b/packages/gitframes/src/preview/notes.ts
@@ -0,0 +1,147 @@
+/**
+ * Notes the user pins on the preview: a moment, a spot (or an area) on the
+ * frame, and what should change there. They are kept as files so whoever
+ * edits the film (a person, or an agent) can read them: `notes.json`, plus the
+ * frame with the spot marked as `note-<id>.jpg`. The folder ignores itself in
+ * git. `notes.json` is read on every change, so it can be edited by hand
+ * (marking a note done, say) while the preview runs.
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+export interface PreviewNote {
+ id: number;
+ frame: number;
+ /** Seconds into the film. */
+ time: number;
+ /** The spot, as fractions of the frame's width and height (0..1). */
+ x: number;
+ y: number;
+ /** Set when an area was marked: its size, from the spot at its top left. */
+ w?: number;
+ h?: number;
+ text: string;
+ /** The frame with the spot marked (absolute path), when it was captured. */
+ image?: string;
+ done: boolean;
+ created: string;
+}
+
+export interface NewNote {
+ frame: number;
+ time: number;
+ x: number;
+ y: number;
+ w?: number;
+ h?: number;
+ text: string;
+ /** JPEG as a base64 data URL. */
+ image?: string;
+}
+
+export class NoteStore {
+ readonly file: string;
+
+ constructor(readonly dir: string) {
+ this.file = path.join(dir, "notes.json");
+ }
+
+ async list(): Promise<PreviewNote[]> {
+ try {
+ const notes = JSON.parse(await fs.promises.readFile(this.file, "utf8"));
+ return Array.isArray(notes) ? notes : [];
+ } catch {
+ return [];
+ }
+ }
+
+ async add(input: NewNote): Promise<PreviewNote> {
+ const notes = await this.list();
+ const id = notes.reduce((max, n) => Math.max(max, n.id), 0) + 1;
+ const note: PreviewNote = {
+ id,
+ frame: Math.max(0, Math.round(Number(input.frame) || 0)),
+ time: round(Number(input.time) || 0, 3),
+ x: round(clamp01(input.x), 4),
+ y: round(clamp01(input.y), 4),
+ ...(input.w !== undefined &&
+ input.h !== undefined && {
+ w: round(clamp01(input.w), 4),
+ h: round(clamp01(input.h), 4),
+ }),
+ text: String(input.text ?? "").trim(),
+ done: false,
+ created: new Date().toISOString(),
+ };
+ await this.ensureDir();
+ const jpeg = /^data:image\/jpeg;base64,(.+)$/.exec(input.image ?? "");
+ if (jpeg) {
+ note.image = path.join(this.dir, `note-${id}.jpg`);
+ await fs.promises.writeFile(note.image, Buffer.from(jpeg[1], "base64"));
+ }
+ await this.save([...notes, note]);
+ return note;
+ }
+
+ async update(
+ id: number,
+ patch: { done?: boolean; text?: string },
+ ): Promise<PreviewNote | undefined> {
+ const notes = await this.list();
+ const note = notes.find((n) => n.id === id);
+ if (!note) return undefined;
+ if (typeof patch.done === "boolean") note.done = patch.done;
+ if (typeof patch.text === "string" && patch.text.trim())
+ note.text = patch.text.trim();
+ await this.save(notes);
+ return note;
+ }
+
+ async remove(id: number): Promise<PreviewNote | undefined> {
+ const notes = await this.list();
+ const note = notes.find((n) => n.id === id);
+ if (!note) return undefined;
+ if (note.image) await fs.promises.rm(note.image, { force: true });
+ await this.save(notes.filter((n) => n !== note));
+ return note;
+ }
+
+ private async save(notes: PreviewNote[]): Promise<void> {
+ await this.ensureDir();
+ const tmp = `${this.file}.${process.pid}.tmp`;
+ await fs.promises.writeFile(tmp, `${JSON.stringify(notes, null, "\t")}\n`);
+ await fs.promises.rename(tmp, this.file);
+ }
+
+ private async ensureDir(): Promise<void> {
+ await fs.promises.mkdir(this.dir, { recursive: true });
+ // Notes are working material, not part of the project.
+ const ignore = path.join(path.dirname(this.dir), ".gitignore");
+ if (!fs.existsSync(ignore)) await fs.promises.writeFile(ignore, "*\n");
+ }
+}
+
+/** One line for a terminal (or an agent reading one). */
+export function describeNote(note: PreviewNote, fps: number): string {
+ const pct = (v: number) => `${Math.round(v * 100)}%`;
+ const where =
+ note.w !== undefined && note.h !== undefined
+ ? `area ${pct(note.x)},${pct(note.y)} to ${pct(note.x + note.w)},${pct(note.y + note.h)}`
+ : `spot ${pct(note.x)},${pct(note.y)}`;
+ return `note ${note.id} at ${timecode(note.frame, fps)} (frame ${note.frame}), ${where}: ${note.text}`;
+}
+
+function timecode(frame: number, fps: number): string {
+ const s = frame / fps;
+ const m = Math.floor(s / 60);
+ return `${m}:${(s - m * 60).toFixed(2).padStart(5, "0")}`;
+}
+
+function clamp01(v: unknown): number {
+ const n = Number(v);
+ return Number.isFinite(n) ? Math.min(1, Math.max(0, n)) : 0;
+}
+
+function round(v: number, digits: number): number {
+ return Number(v.toFixed(digits));
+}
diff --git a/packages/gitframes/src/preview/page.ts b/packages/gitframes/src/preview/page.ts
index df00bd53..f2093f6a 100644
--- a/packages/gitframes/src/preview/page.ts
+++ b/packages/gitframes/src/preview/page.ts
@@ -174,6 +174,115 @@ export const previewPage = /* html */ `<!doctype html>
font-size: 11px; line-height: 1; background: var(--surface-3); color: var(--ink); padding: 5px 7px; border-radius: 5px;
white-space: nowrap; z-index: 4; font-variant-numeric: tabular-nums;
}
+ /* ── Notes: pinned to a spot (or an area) and a moment ── */
+ .stage.can-note { cursor: crosshair; }
+ .overlay { position: absolute; inset: 0; pointer-events: none; }
+ .pin {
+ position: absolute; width: 22px; height: 22px; margin: -11px 0 0 -11px; padding: 0; border-radius: 50%;
+ display: grid; place-items: center; pointer-events: auto; cursor: pointer;
+ background: var(--brand); color: #fff; font-size: 11px; font-weight: 600; line-height: 1;
+ border: 2px solid #fff; box-shadow: 0 1px 5px rgb(0 0 0 / .55); transition: transform .12s;
+ }
+ .pin:hover, .pin.active { transform: scale(1.18); }
+ .pin.done { background: #6b6e76; }
+ .pin.draft { animation: pin-pulse 1.5s ease-out infinite; }
+ .pin svg { width: 11px; height: 11px; }
+ @keyframes pin-pulse {
+ from { box-shadow: 0 0 0 0 rgb(59 130 246 / .6), 0 1px 5px rgb(0 0 0 / .55); }
+ to { box-shadow: 0 0 0 14px rgb(59 130 246 / 0), 0 1px 5px rgb(0 0 0 / .55); }
+ }
+ .area {
+ position: absolute; border: 1.5px solid var(--brand); border-radius: 3px;
+ background: rgb(59 130 246 / .12); box-shadow: 0 0 0 1px rgb(0 0 0 / .35);
+ }
+ .area.done { border-color: #9a9da5; background: rgb(255 255 255 / .05); }
+ .marquee { position: absolute; display: none; border: 1.5px dashed #fff; background: rgb(59 130 246 / .16); border-radius: 3px; pointer-events: none; }
+ .stage-hint, .toast {
+ position: absolute; left: 50%; transform: translateX(-50%); pointer-events: none; white-space: nowrap;
+ padding: 6px 11px; border-radius: 999px; font-size: 12px; color: #fff; background: rgb(0 0 0 / .62);
+ backdrop-filter: blur(6px); -webkit-backdrop-filter: blur(6px); opacity: 0; transition: opacity .15s;
+ }
+ .stage-hint { top: 12px; }
+ .stage.can-note.hint:hover .stage-hint { opacity: 1; }
+ .toast { bottom: 14px; }
+ .toast.on { opacity: 1; }
+
+ .pop {
+ position: fixed; z-index: 20; width: 280px; display: none; padding: 10px 10px 8px;
+ background: var(--surface); border: 1px solid var(--line-2); border-radius: 12px;
+ box-shadow: 0 12px 32px rgb(0 0 0 / .35);
+ }
+ .pop.on { display: block; }
+ .pop-head { display: flex; align-items: center; gap: 8px; font-size: 11.5px; color: var(--ink-3); margin-bottom: 6px; }
+ .badge {
+ min-width: 18px; height: 18px; padding: 0 5px; border-radius: 9px; display: inline-grid; place-items: center; flex: none;
+ background: var(--brand); color: #fff; font-size: 10.5px; font-weight: 600;
+ }
+ .badge.done { background: var(--ink-3); }
+ .pop textarea {
+ display: block; width: 100%; min-height: 54px; max-height: 180px; resize: none; padding: 2px 2px 0;
+ border: 0; outline: none; background: transparent; color: var(--ink); font: inherit; line-height: 1.45;
+ }
+ .pop textarea::placeholder { color: var(--ink-3); }
+ .pop-text { white-space: pre-wrap; overflow-wrap: anywhere; padding: 0 2px; max-height: 200px; overflow: auto; }
+ .pop-foot { display: flex; align-items: center; gap: 6px; margin-top: 8px; font-size: 11.5px; color: var(--ink-3); }
+ .pop-foot .err { color: var(--bad); }
+ .btn {
+ height: 26px; padding: 0 10px; border-radius: 7px; border: 0; font-size: 12px; font-weight: 500;
+ display: inline-flex; align-items: center; gap: 6px; background: transparent; color: var(--ink-2); white-space: nowrap;
+ }
+ .btn:hover:not(:disabled) { background: var(--surface-2); color: var(--ink); }
+ .btn.primary { background: var(--primary-bg); color: var(--primary-ink); }
+ .btn.primary:hover:not(:disabled) { background: var(--primary-bg); filter: brightness(.9); }
+ .btn.danger:hover:not(:disabled) { color: var(--bad); }
+ .btn:disabled { opacity: .4; cursor: default; }
+ .btn svg { width: 13px; height: 13px; }
+ .x-btn { width: 22px; height: 22px; padding: 0; justify-content: center; margin-right: -4px; }
+
+ .transport { position: relative; }
+ .notes-btn { height: 32px; padding: 0 9px 0 8px; margin-right: 6px; font-size: 12.5px; }
+ .notes-btn svg { width: 15px; height: 15px; }
+ .notes-btn .badge { background: var(--surface-3); color: var(--ink-2); }
+ .notes-btn .badge.open { background: var(--brand); color: #fff; }
+ .notes-panel {
+ position: absolute; right: 0; bottom: calc(100% + 8px); z-index: 15; width: min(360px, calc(100vw - 24px));
+ max-height: min(440px, 62vh); display: none; flex-direction: column; overflow: hidden;
+ background: var(--surface); border: 1px solid var(--line-2); border-radius: 12px; box-shadow: 0 12px 32px rgb(0 0 0 / .35);
+ }
+ .notes-panel.on { display: flex; }
+ .np-head { flex: none; display: flex; align-items: center; gap: 8px; padding: 8px 8px 8px 14px; border-bottom: 1px solid var(--line); }
+ .np-head h2 { margin: 0; font-size: 13px; font-weight: 600; }
+ .np-list { overflow: auto; padding: 4px; }
+ .np-empty { padding: 22px 18px; text-align: center; color: var(--ink-3); font-size: 12.5px; }
+ .np-foot { flex: none; padding: 8px 14px; border-top: 1px solid var(--line); color: var(--ink-3); font-size: 11.5px; overflow-wrap: anywhere; }
+ .note-row {
+ display: grid; grid-template-columns: auto 1fr auto; gap: 10px; align-items: start; padding: 8px 8px 8px 10px;
+ border-radius: 8px; cursor: pointer;
+ }
+ .note-row:hover { background: var(--surface-2); }
+ .note-row .badge { margin-top: 1px; }
+ .note-row .when { font-size: 11.5px; color: var(--ink-3); }
+ .note-row .text { display: -webkit-box; -webkit-line-clamp: 2; -webkit-box-orient: vertical; overflow: hidden; overflow-wrap: anywhere; }
+ .note-row.done .text { color: var(--ink-3); text-decoration: line-through; }
+ .check {
+ width: 20px; height: 20px; border-radius: 50%; padding: 0; display: grid; place-items: center; margin-top: 1px;
+ border: 1.5px solid var(--line-2); background: transparent; color: transparent;
+ }
+ .check:hover { border-color: var(--ok); color: var(--ok); }
+ .check.on { background: var(--ok); border-color: var(--ok); color: #fff; }
+ .check svg { width: 11px; height: 11px; }
+
+ .note-marks { position: absolute; left: 0; right: 0; top: 22px; bottom: 0; pointer-events: none; z-index: 2; }
+ .note-mark {
+ position: absolute; top: 5px; width: 14px; height: 14px; margin-left: -7px; padding: 0; border: 0; border-radius: 50%;
+ display: grid; place-items: center; pointer-events: auto; cursor: pointer;
+ background: var(--brand); color: #fff; font-size: 8.5px; font-weight: 700; box-shadow: 0 0 0 2px var(--surface);
+ }
+ .note-mark::after { content: ""; position: absolute; top: 14px; left: 6.5px; width: 1px; height: 30px; background: var(--brand); opacity: .45; }
+ .note-mark.done { background: var(--ink-3); }
+ .note-mark.stacked::after { display: none; }
+ .note-mark.done::after { background: var(--ink-3); }
+ .note-mark:hover { transform: scale(1.2); }
</style>
</head>
<body>
@@ -191,6 +300,10 @@ export const previewPage = /* html */ `<!doctype html>
<div class="stage" id="stage">
<canvas id="canvas" aria-label="Rendered frame"></canvas>
<div class="stage-msg" id="stageMsg" role="alert"></div>
+ <div class="overlay" id="pins"></div>
+ <div class="marquee" id="marquee"></div>
+ <div class="stage-hint" id="stageHint">Click to pin a note · drag to mark an area</div>
+ <div class="toast" id="toast" role="status" aria-live="polite"></div>
<div class="buffering" id="buffering" role="status" aria-label="Loading"><svg viewBox="0 0 50 50"><circle cx="25" cy="25" r="20"/></svg></div>
</div>
</div>
@@ -212,6 +325,22 @@ export const previewPage = /* html */ `<!doctype html>
<span class="frame" id="tcFrame">frame 0</span>
</div>
<span class="grow"></span>
+ <button class="btn notes-btn" id="notesBtn" title="Notes" aria-haspopup="dialog" aria-expanded="false" hidden>
+ <svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linejoin="round"><path d="M3 2.75h10a1.25 1.25 0 0 1 1.25 1.25v6.5A1.25 1.25 0 0 1 13 11.75H7.5L4.5 14v-2.25H3A1.25 1.25 0 0 1 1.75 10.5V4A1.25 1.25 0 0 1 3 2.75z"/></svg>
+ Notes <span class="badge" id="notesCount">0</span>
+ </button>
+ <div class="notes-panel" id="notesPanel" role="dialog" aria-label="Notes">
+ <div class="np-head">
+ <h2>Notes</h2><span class="grow"></span>
+ <button class="btn" id="notesCopy" title="Copy the open notes, to paste into a chat">
+ <svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.4"><rect x="5.25" y="5.25" width="8" height="8" rx="1.5"/><path d="M10.75 3.5V3.25a1.5 1.5 0 0 0-1.5-1.5h-5.5a1.5 1.5 0 0 0-1.5 1.5v5.5a1.5 1.5 0 0 0 1.5 1.5H4"/></svg>
+ <span id="notesCopyLabel">Copy</span>
+ </button>
+ <button class="btn x-btn" id="notesClose" title="Close" aria-label="Close"><svg viewBox="0 0 16 16" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"><path d="M4 4l8 8M12 4l-8 8"/></svg></button>
+ </div>
+ <div class="np-list" id="notesList"></div>
+ <div class="np-foot" id="notesFoot"></div>
+ </div>
<button class="icon-btn" id="mute" title="Mute" aria-label="Mute" disabled>
<svg id="volIcon" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round" stroke-linejoin="round"><path d="M2.5 6h2.2L8 3.2v9.6L4.7 10H2.5z" fill="currentColor" stroke="none"/><path d="M10.6 5.6a3.4 3.4 0 0 1 0 4.8M12.4 3.9a5.8 5.8 0 0 1 0 8.2"/></svg>
<svg id="muteIcon" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round" style="display:none"><path d="M2.5 6h2.2L8 3.2v9.6L4.7 10H2.5z" fill="currentColor" stroke="none"/><path d="M10.5 6l3.5 4M14 6l-3.5 4"/></svg>
@@ -223,6 +352,7 @@ export const previewPage = /* html */ `<!doctype html>
<div class="tl-inner" id="tlInner">
<div class="ruler" id="ruler"></div>
<div class="buffered" id="buffered"></div>
+ <div class="note-marks" id="noteMarks"></div>
<div class="wave-lane">
<canvas id="wave"></canvas>
<div class="wave-state shimmer" id="waveState"><span class="spinner"></span>Mixing audio</div>
@@ -234,6 +364,8 @@ export const previewPage = /* html */ `<!doctype html>
</div>
</main>
+<div class="pop" id="pop" role="dialog" aria-label="Note"></div>
+
<script>
(function () {
var $ = function (id) { return document.getElementById(id); };
@@ -258,12 +390,44 @@ export const previewPage = /* html */ `<!doctype html>
}
function sleep(ms) { return new Promise(function (r) { setTimeout(r, ms); }); }
+ // ── Reporting: errors and the engine's warnings go to the preview's
+ // terminal too, so whoever runs it sees them without opening this tab.
+ // Once each; frame numbers aside, playback repeats the same one per frame ──
+ var reportedKeys = new Set();
+ function errText(x) {
+ if (x && x.message) return x.stack && x.stack.indexOf(x.message) >= 0 ? x.stack.split("\\n").slice(0, 4).join("\\n") : x.message;
+ return typeof x === "string" ? x : String(x);
+ }
+ function report(level, parts) {
+ var text = parts.map(errText).join(" ").trim(), key = level + text.replace(/\\d+/g, "#");
+ if (!text || reportedKeys.has(key) || reportedKeys.size > 100) return;
+ reportedKeys.add(key);
+ fetch("/@gitframes/log", {
+ method: "POST",
+ headers: { "content-type": "application/json" },
+ body: JSON.stringify({ level: level, message: text.slice(0, 4000) }),
+ keepalive: true
+ }).catch(function () {});
+ }
+ ["error", "warn"].forEach(function (name) {
+ var original = console[name].bind(console);
+ console[name] = function () {
+ original.apply(null, arguments);
+ var args = Array.prototype.slice.call(arguments);
+ // Errors from anywhere; warnings only from the engine (fonts, renderers).
+ if (name === "error" || (typeof args[0] === "string" && args[0].indexOf("[gitframes]") === 0)) {
+ report(name === "error" ? "error" : "warning", args);
+ }
+ };
+ });
+
// ── Frames: drawn in this tab by the composition's own code ──
function setTime(f) {
frame = f;
$("tcNow").textContent = fmt(f);
$("tcFrame").textContent = "frame " + f;
$("playhead").style.left = pct(f) + "%";
+ if (!playing && notesOn) renderPins();
}
function show(f) {
setTime(f);
@@ -277,11 +441,28 @@ export const previewPage = /* html */ `<!doctype html>
}
function seek(f) {
stop();
+ // The playhead moved: frames rendered ahead of the old spot are stale.
+ if (player) player.buffer.clear();
+ $("buffered").style.display = "none";
var done = show(clampFrame(f));
+ keepPosition();
scheduleWarm();
return done;
}
+ // ── Position in the address: #t=12.5 opens there, and a reload (the next
+ // preview taking over) comes back to the same moment ──
+ function startFrame() {
+ var m = /[#&]t=([\\d.]+)/.exec(location.hash), n = /[#&]frame=(\\d+)/.exec(location.hash);
+ if (m) return clampFrame(Number(m[1]) * meta.fps);
+ if (n) return clampFrame(Number(n[1]));
+ return 0;
+ }
+ function keepPosition() {
+ var at = frame > 0 ? "#t=" + Number((frame / meta.fps).toFixed(3)) : location.pathname;
+ try { history.replaceState(null, "", at); } catch (e) {}
+ }
+
// ── Analysing ahead: while paused, frames after the playhead are drawn
// off-screen so vision results are cached before they play ──
var warmTimer = null, warmToken = 0, warmed = new Set();
@@ -302,6 +483,8 @@ export const previewPage = /* html */ `<!doctype html>
}
}
function showError(err) {
+ report("error", [err]);
+ pageState = "error";
$("buffering").classList.remove("on");
$("stageMsg").textContent = String((err && err.message) || err);
$("stageMsg").classList.add("on");
@@ -407,6 +590,9 @@ export const previewPage = /* html */ `<!doctype html>
var token = ++playToken;
var alive = function () { return playing && token === playToken; };
setPlayingUi(true);
+ if (openId != null) closePop();
+ if (draft && !draft.text.trim()) cancelDraft();
+ if (notesOn) renderPins();
if (frame >= last()) frame = 0;
playRealtime(alive).finally(function () { if (token === playToken && playing) pause(); });
}
@@ -417,26 +603,29 @@ export const previewPage = /* html */ `<!doctype html>
setPlayingUi(false);
}
// Pausing settles on exactly the frame the timecode shows.
- function pause() { stop(); show(frame).then(scheduleWarm); }
+ function pause() { stop(); keepPosition(); show(frame).then(scheduleWarm); }
function togglePlay() { playing ? pause() : play(); }
// Like a video player: frames are rendered ahead into a buffer, in order,
// and every one is shown at the film's frame rate. Playback starts once
// three seconds (or the rest of the film) are ready; when rendering falls
// behind, the clock and the sound hold until the buffer is full again.
+ // Pausing keeps the buffer (and it keeps filling), so playing on starts at
+ // once; moving the playhead clears it.
var BUFFER_SEC = 3;
async function playRealtime(alive) {
player.buffer.start(frame);
- try {
- while (alive() && frame < last()) {
- if (!(await fillBuffer(alive))) return;
- if (!(await runClock(alive))) return;
- }
- } finally {
- player.buffer.stop();
- $("buffered").style.display = "none";
+ while (alive() && frame < last()) {
+ if (!(await fillBuffer(alive))) return;
+ if (!(await runClock(alive))) return;
}
}
+ // While paused, the loaded range keeps growing on the timeline.
+ setInterval(function () {
+ if (!player || playing) return;
+ if (player.buffer.ahead(frame) > 0) showBufferedRange();
+ else $("buffered").style.display = "none";
+ }, 250);
function showBufferedRange() {
var bar = $("buffered"), end = Math.max(frame, Math.min(last(), player.buffer.end - 1));
bar.style.display = "block";
@@ -545,6 +734,370 @@ export const previewPage = /* html */ `<!doctype html>
timeline.addEventListener("pointerup", function () { dragging = false; });
timeline.addEventListener("pointercancel", function () { dragging = false; });
+ // ── Notes: pause, click the picture (or drag an area) and say what should
+ // change. Each is saved with its moment, its spot and a picture of the
+ // frame with the spot marked, for whoever edits the film ──
+ var notes = [], notesOn = false, draft = null, openId = null, saving = false, press = null;
+ var pop = $("pop"), pins = $("pins"), NL = String.fromCharCode(10);
+ var ICON_CHECK = '<svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round"><path d="M3.5 8.5l3 3 6-7"/></svg>';
+ var ICON_X = '<svg viewBox="0 0 16 16" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"><path d="M4 4l8 8M12 4l-8 8"/></svg>';
+
+ function pct1(v) { return Math.round(v * 100) + "%"; }
+ function whereText(n) {
+ return n.w != null ? "area " + pct1(n.x) + "," + pct1(n.y) + " to " + pct1(n.x + n.w) + "," + pct1(n.y + n.h) : "spot " + pct1(n.x) + "," + pct1(n.y);
+ }
+ function noteById(id) { return notes.find(function (n) { return n.id === id; }); }
+ function openCount() { return notes.filter(function (n) { return !n.done; }).length; }
+
+ function renderNotes() {
+ renderPins();
+ renderMarks();
+ renderList();
+ var open = openCount(), count = $("notesCount");
+ count.textContent = String(open || notes.length);
+ count.classList.toggle("open", open > 0);
+ $("notesBtn").title = open + " open of " + notes.length;
+ }
+ function renderPins() {
+ if (!meta) return;
+ stage.classList.toggle("can-note", notesOn && !!player && !playing);
+ stage.classList.toggle("hint", notes.length === 0 && !draft);
+ pins.replaceChildren();
+ if (playing) return;
+ var here = notes.filter(function (n) { return n.frame === frame; });
+ if (draft && draft.frame === frame) here.push(draft);
+ here.forEach(function (n) {
+ if (n.w != null) {
+ var a = el("div", "area" + (n.done ? " done" : ""));
+ a.style.left = n.x * 100 + "%"; a.style.top = n.y * 100 + "%";
+ a.style.width = n.w * 100 + "%"; a.style.height = n.h * 100 + "%";
+ pins.append(a);
+ }
+ var pin = el("button", "pin" + (n.done ? " done" : "") + (n === draft ? " draft" : "") + (n.id === openId ? " active" : ""));
+ pin.style.left = n.x * 100 + "%"; pin.style.top = n.y * 100 + "%";
+ if (n === draft) { pin.setAttribute("aria-label", "New note"); }
+ else {
+ if (n.done) pin.innerHTML = ICON_CHECK; else pin.textContent = String(n.id);
+ pin.title = n.text;
+ pin.setAttribute("aria-label", "Note " + n.id);
+ pin.addEventListener("click", function (e) { e.stopPropagation(); openCard(n.id); });
+ }
+ pins.append(pin);
+ });
+ }
+ function renderMarks() {
+ var marks = $("noteMarks");
+ marks.replaceChildren();
+ if (!meta) return;
+ // Notes close together stack, up to three high.
+ var width = tlInner.clientWidth || 800, lanes = [];
+ notes.slice().sort(function (a, b) { return a.frame - b.frame || a.id - b.id; }).forEach(function (n) {
+ var x = (pct(n.frame) / 100) * width, lane = lanes.findIndex(function (end) { return x - end >= 16; });
+ if (lane < 0) lane = lanes.length < 3 ? lanes.length : 2;
+ lanes[lane] = x;
+ var m = el("button", "note-mark" + (n.done ? " done" : "") + (lane ? " stacked" : ""), String(n.id));
+ m.style.left = pct(n.frame) + "%";
+ m.style.top = 4 + lane * 15 + "px";
+ m.title = n.id + " · " + fmt(n.frame) + " · " + n.text;
+ m.addEventListener("pointerdown", function (e) { e.stopPropagation(); });
+ m.addEventListener("click", function (e) { e.stopPropagation(); goToNote(n.id); });
+ marks.append(m);
+ });
+ }
+ function renderList() {
+ var list = $("notesList");
+ list.replaceChildren();
+ $("notesCopy").disabled = openCount() === 0;
+ if (!notes.length) {
+ list.append(el("div", "np-empty", "Pause and click the picture to pin a note to that spot and moment. Drag to mark an area."));
+ }
+ notes.slice().sort(function (a, b) { return a.frame - b.frame || a.id - b.id; }).forEach(function (n) {
+ var row = el("div", "note-row" + (n.done ? " done" : ""));
+ var body = el("div");
+ body.append(el("div", "when tnum", fmt(n.frame) + " · frame " + n.frame), el("div", "text", n.text));
+ var check = el("button", "check" + (n.done ? " on" : ""));
+ check.innerHTML = ICON_CHECK;
+ check.title = n.done ? "Reopen" : "Mark done";
+ check.setAttribute("aria-label", check.title);
+ check.addEventListener("click", function (e) { e.stopPropagation(); setDone(n.id, !n.done); });
+ row.append(el("span", "badge" + (n.done ? " done" : ""), String(n.id)), body, check);
+ row.addEventListener("click", function () { goToNote(n.id); });
+ list.append(row);
+ });
+ var dir = meta && meta.notesDir ? meta.notesDir.split("/").slice(-2).join("/") : "";
+ $("notesFoot").textContent = "Saved in " + dir + " with a picture of each spot. Ask your agent to go through them.";
+ }
+
+ function notesRequest(body) {
+ return fetch("/@gitframes/notes", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body) })
+ .then(function (r) { if (!r.ok) throw new Error("HTTP " + r.status); return r.json(); });
+ }
+ function upsert(note) {
+ var i = notes.findIndex(function (n) { return n.id === note.id; });
+ if (i >= 0) notes[i] = note; else notes.push(note);
+ renderNotes();
+ }
+ function setDone(id, done) {
+ notesRequest({ op: "update", id: id, done: done }).then(function (n) {
+ upsert(n);
+ if (openId === id) openCard(id);
+ }, function () { toast("Couldn't save. Is the preview running?"); });
+ }
+ function removeNote(id) {
+ notesRequest({ op: "remove", id: id }).then(function () {
+ notes = notes.filter(function (n) { return n.id !== id; });
+ closePop();
+ renderNotes();
+ }, function () { toast("Couldn't delete. Is the preview running?"); });
+ }
+ function goToNote(id) {
+ var n = noteById(id);
+ if (!n) return;
+ $("notesPanel").classList.remove("on");
+ $("notesBtn").setAttribute("aria-expanded", "false");
+ seek(n.frame).then(function () { openCard(id); });
+ }
+
+ var toastTimer = null;
+ function toast(text) {
+ var t = $("toast");
+ t.textContent = text;
+ t.classList.add("on");
+ clearTimeout(toastTimer);
+ toastTimer = setTimeout(function () { t.classList.remove("on"); }, 2200);
+ }
+
+ // ── Placing a note on the picture ──
+ function fracAt(e) {
+ var r = stage.getBoundingClientRect();
+ return { x: Math.min(1, Math.max(0, (e.clientX - r.left) / r.width)), y: Math.min(1, Math.max(0, (e.clientY - r.top) / r.height)), r: r };
+ }
+ stage.addEventListener("pointerdown", function (e) {
+ if (e.button !== 0 || !player || e.target.closest(".pin")) return;
+ if (playing) { pause(); return; }
+ if (!notesOn) return;
+ if (draft && pop.querySelector("textarea") && pop.querySelector("textarea").value.trim()) {
+ pop.querySelector("textarea").focus();
+ return;
+ }
+ cancelDraft();
+ var p = fracAt(e);
+ press = { x: p.x, y: p.y, cx: e.clientX, cy: e.clientY, area: null };
+ stage.setPointerCapture(e.pointerId);
+ e.preventDefault();
+ });
+ stage.addEventListener("pointermove", function (e) {
+ if (!press) return;
+ var p = fracAt(e);
+ if (!press.area && Math.hypot(e.clientX - press.cx, e.clientY - press.cy) < 6) return;
+ press.area = { x: Math.min(press.x, p.x), y: Math.min(press.y, p.y), w: Math.abs(p.x - press.x), h: Math.abs(p.y - press.y) };
+ var m = $("marquee");
+ m.style.display = "block";
+ m.style.left = press.area.x * 100 + "%"; m.style.top = press.area.y * 100 + "%";
+ m.style.width = press.area.w * 100 + "%"; m.style.height = press.area.h * 100 + "%";
+ });
+ function endPress() {
+ if (!press) return;
+ var a = press.area;
+ $("marquee").style.display = "none";
+ draft = a && a.w > 0.01 && a.h > 0.01
+ ? { frame: frame, x: a.x, y: a.y, w: a.w, h: a.h, text: "" }
+ : { frame: frame, x: press.x, y: press.y, text: "" };
+ press = null;
+ openComposer();
+ }
+ stage.addEventListener("pointerup", endPress);
+ stage.addEventListener("pointercancel", function () { press = null; $("marquee").style.display = "none"; });
+
+ // ── The popover: writing a note, or reading one ──
+ var popAnchor = null;
+ function placePop() {
+ if (!popAnchor || !pop.classList.contains("on")) return;
+ var r = stage.getBoundingClientRect(), n = popAnchor;
+ var ax = r.left + (n.x + (n.w || 0)) * r.width, ay = r.top + (n.y + (n.h || 0)) * r.height;
+ var w = pop.offsetWidth, h = pop.offsetHeight, gap = 16;
+ var left = ax + gap + w <= innerWidth - 8 ? ax + gap : ax - gap - w - (n.w || 0) * r.width;
+ var top = ay + gap + h <= innerHeight - 8 ? ay + gap / 2 : ay - h - gap / 2 - (n.h || 0) * r.height;
+ pop.style.left = Math.max(8, Math.min(innerWidth - w - 8, left)) + "px";
+ pop.style.top = Math.max(8, Math.min(innerHeight - h - 8, top)) + "px";
+ }
+ function showPop(anchor) {
+ popAnchor = anchor;
+ pop.classList.add("on");
+ placePop();
+ }
+ function closePop() {
+ pop.classList.remove("on");
+ pop.replaceChildren();
+ popAnchor = null;
+ openId = null;
+ renderPins();
+ }
+ function cancelDraft() {
+ if (!draft) return;
+ draft = null;
+ closePop();
+ }
+ function openComposer() {
+ openId = null;
+ var head = el("div", "pop-head");
+ head.append(el("span", "badge", "+"), el("span", "tnum", fmt(draft.frame) + " · " + (draft.w != null ? "area" : "spot")));
+ var ta = document.createElement("textarea");
+ ta.placeholder = "What should change here?";
+ ta.rows = 2;
+ ta.setAttribute("aria-label", "Note");
+ var foot = el("div", "pop-foot"), status = el("span", "grow", "Enter to add");
+ var cancel = el("button", "btn", "Cancel"), add = el("button", "btn primary", "Add note");
+ add.disabled = true;
+ foot.append(status, cancel, add);
+ pop.replaceChildren(head, ta, foot);
+ ta.addEventListener("input", function () {
+ draft.text = ta.value;
+ add.disabled = !ta.value.trim() || saving;
+ ta.style.height = "auto";
+ ta.style.height = Math.min(180, ta.scrollHeight) + "px";
+ placePop();
+ });
+ ta.addEventListener("keydown", function (e) {
+ if (e.key === "Enter" && !e.shiftKey && !e.isComposing) { e.preventDefault(); saveDraft(ta, add, status); }
+ if (e.key === "Escape") { e.preventDefault(); cancelDraft(); }
+ });
+ cancel.addEventListener("click", cancelDraft);
+ add.addEventListener("click", function () { saveDraft(ta, add, status); });
+ renderPins();
+ showPop(draft);
+ ta.focus();
+ }
+ async function saveDraft(ta, add, status) {
+ var d = draft, text = ta.value.trim();
+ if (!d || !text || saving) return;
+ saving = true;
+ ta.readOnly = true;
+ add.disabled = true;
+ status.className = "grow";
+ status.textContent = "Saving…";
+ try {
+ var image = null;
+ try { image = await capture(d); } catch (err) { report("warning", ["[gitframes] no picture for the note:", err]); }
+ var note = await notesRequest({ op: "add", note: { frame: d.frame, time: d.frame / meta.fps, x: d.x, y: d.y, w: d.w, h: d.h, text: text, image: image } });
+ if (draft === d) draft = null;
+ closePop();
+ upsert(note);
+ toast("Note " + note.id + " saved");
+ } catch (err) {
+ status.className = "grow err";
+ status.textContent = "Couldn't save. Is the preview running?";
+ ta.readOnly = false;
+ add.disabled = false;
+ } finally {
+ saving = false;
+ }
+ }
+ // The frame with the spot marked, small enough to read at a glance.
+ async function capture(d) {
+ var bmp = await player.snapshot(d.frame);
+ var scale = Math.min(1, 1600 / bmp.width), w = Math.round(bmp.width * scale), h = Math.round(bmp.height * scale);
+ var c = document.createElement("canvas");
+ c.width = w; c.height = h;
+ var g = c.getContext("2d");
+ g.drawImage(bmp, 0, 0, w, h);
+ bmp.close();
+ var lw = Math.max(3, w / 400);
+ function mark(draw) {
+ // Dark, white, then blue: it reads on any picture.
+ g.lineWidth = lw + 5; g.strokeStyle = "rgba(0,0,0,0.5)"; draw();
+ g.lineWidth = lw + 2.5; g.strokeStyle = "#fff"; draw();
+ g.lineWidth = lw; g.strokeStyle = "#3b82f6"; draw();
+ }
+ if (d.w != null) {
+ mark(function () { g.strokeRect(d.x * w, d.y * h, d.w * w, d.h * h); });
+ } else {
+ var rad = Math.max(16, w / 40);
+ mark(function () { g.beginPath(); g.arc(d.x * w, d.y * h, rad, 0, Math.PI * 2); g.stroke(); });
+ g.fillStyle = "#3b82f6";
+ g.beginPath(); g.arc(d.x * w, d.y * h, lw, 0, Math.PI * 2); g.fill();
+ }
+ return c.toDataURL("image/jpeg", 0.88);
+ }
+ function openCard(id) {
+ var n = noteById(id);
+ if (!n) return;
+ if (draft) cancelDraft();
+ openId = id;
+ var head = el("div", "pop-head");
+ var close = el("button", "btn x-btn");
+ close.innerHTML = ICON_X;
+ close.title = "Close";
+ close.setAttribute("aria-label", "Close");
+ close.addEventListener("click", closePop);
+ head.append(el("span", "badge" + (n.done ? " done" : ""), String(n.id)), el("span", "tnum grow", fmt(n.frame) + " · frame " + n.frame), close);
+ var foot = el("div", "pop-foot");
+ var done = el("button", "btn");
+ done.innerHTML = ICON_CHECK;
+ done.append(document.createTextNode(n.done ? "Reopen" : "Mark done"));
+ done.addEventListener("click", function () { setDone(n.id, !n.done); });
+ var del = el("button", "btn danger", "Delete");
+ del.addEventListener("click", function () { removeNote(n.id); });
+ foot.append(done, el("span", "grow"), del);
+ pop.replaceChildren(head, el("div", "pop-text", n.text), foot);
+ renderPins();
+ showPop(n);
+ }
+
+ document.addEventListener("pointerdown", function (e) {
+ if (pop.classList.contains("on") && !pop.contains(e.target) && !stage.contains(e.target) && !e.target.closest(".note-mark, .note-row")) {
+ if (openId != null) closePop();
+ else if (draft && !draft.text.trim()) cancelDraft();
+ }
+ var panel = $("notesPanel");
+ if (panel.classList.contains("on") && !panel.contains(e.target) && !$("notesBtn").contains(e.target)) {
+ panel.classList.remove("on");
+ $("notesBtn").setAttribute("aria-expanded", "false");
+ }
+ });
+ document.addEventListener("keydown", function (e) {
+ if (e.key !== "Escape") return;
+ if (openId != null) closePop();
+ $("notesPanel").classList.remove("on");
+ $("notesBtn").setAttribute("aria-expanded", "false");
+ });
+ window.addEventListener("resize", placePop);
+ new ResizeObserver(placePop).observe(stage);
+
+ $("notesBtn").addEventListener("click", function () {
+ var on = $("notesPanel").classList.toggle("on");
+ $("notesBtn").setAttribute("aria-expanded", String(on));
+ });
+ $("notesClose").addEventListener("click", function () {
+ $("notesPanel").classList.remove("on");
+ $("notesBtn").setAttribute("aria-expanded", "false");
+ });
+ // The open notes as text, for a chat that can't read the notes folder.
+ $("notesCopy").addEventListener("click", function () {
+ var lines = ["Notes on the preview of " + JSON.stringify(meta.title) + ":"];
+ notes.filter(function (n) { return !n.done; }).sort(function (a, b) { return a.frame - b.frame; }).forEach(function (n) {
+ lines.push("- Note " + n.id + " at " + fmt(n.frame) + " (frame " + n.frame + "), " + whereText(n) + ": " + n.text + (n.image ? " [picture: " + n.image + "]" : ""));
+ });
+ var text = lines.join(NL), label = $("notesCopyLabel");
+ var done = function () { label.textContent = "Copied"; setTimeout(function () { label.textContent = "Copy"; }, 1600); };
+ (navigator.clipboard ? navigator.clipboard.writeText(text) : Promise.reject()).then(done, function () {
+ var t = document.createElement("textarea");
+ t.value = text;
+ document.body.append(t);
+ t.select();
+ try { document.execCommand("copy"); done(); } catch (e) {}
+ t.remove();
+ });
+ });
+
+ function loadNotes() {
+ if (!notesOn) return;
+ fetch("/@gitframes/notes").then(function (r) { return r.json(); }).then(function (list) {
+ notes = Array.isArray(list) ? list : [];
+ renderNotes();
+ }, function () {});
+ }
+
// ── Wiring ──
$("play").addEventListener("click", togglePlay);
$("prev").addEventListener("click", function () { seek(frame - 1); });
@@ -552,6 +1105,48 @@ export const previewPage = /* html */ `<!doctype html>
$("mute").addEventListener("click", function () { audio.muted = !audio.muted; applyVolume(); });
$("volume").addEventListener("input", function (e) { audio.volume = Number(e.target.value); audio.muted = audio.volume === 0; applyVolume(); });
+ // A hidden tab's timers are throttled, so playback would stutter: pause.
+ document.addEventListener("visibilitychange", function () {
+ if (document.hidden && playing) pause();
+ });
+
+ // ── For scripts and agents driving the page: seek, play, and read the
+ // state instead of clicking at coordinates ──
+ var pageState = "loading";
+ window.gitframesPreview = {
+ /** Shows the frame at a time in seconds; resolves once it is drawn. */
+ seek: function (sec) { return ready().then(function () { return seek(Number(sec) * meta.fps); }); },
+ /** Shows a frame by number; resolves once it is drawn. */
+ seekFrame: function (f) { return ready().then(function () { return seek(f); }); },
+ play: function () { return ready().then(play); },
+ /** Notes pinned on the page, as saved in notes.json. */
+ notes: function () { return notes.slice(); },
+ pause: function () { if (playing) pause(); },
+ /** Where the preview is: loading, ready or error, and what it shows. */
+ state: function () {
+ return {
+ state: pageState,
+ error: pageState === "error" ? $("stageMsg").textContent : null,
+ frame: frame,
+ time: meta ? Number((frame / meta.fps).toFixed(3)) : 0,
+ playing: playing,
+ buffering: stalled,
+ audio: audio.state,
+ connected: !offline,
+ meta: meta && { title: meta.title, width: meta.width, height: meta.height, fps: meta.fps, frameCount: meta.frameCount, duration: Number((last() / meta.fps).toFixed(3)) }
+ };
+ }
+ };
+ var readyWaiters = [];
+ function ready() {
+ if (player) return Promise.resolve();
+ if (pageState === "error") return Promise.reject(new Error($("stageMsg").textContent));
+ return new Promise(function (resolve, reject) { readyWaiters.push([resolve, reject]); });
+ }
+ function settleReady(err) {
+ readyWaiters.splice(0).forEach(function (w) { err ? w[1](err) : w[0](); });
+ }
+
function applyMeta(m) {
meta = m;
document.title = m.title + " · preview";
@@ -567,6 +1162,7 @@ export const previewPage = /* html */ `<!doctype html>
if (!meta) return;
renderRuler();
drawWave();
+ renderMarks();
}).observe(tlInner);
// When the preview command ends the event stream drops and the browser keeps
@@ -581,10 +1177,15 @@ export const previewPage = /* html */ `<!doctype html>
});
events.addEventListener("error", function () {
if (!meta) return;
- if (playing) stop();
+ if (playing) { stop(); keepPosition(); }
offline = true;
renderChip();
});
+ events.addEventListener("notes", function (e) {
+ notes = JSON.parse(e.data);
+ if (openId != null && !noteById(openId)) closePop();
+ renderNotes();
+ });
events.addEventListener("audio", function (e) {
if (meta) loadAudio(JSON.parse(e.data));
});
@@ -592,8 +1193,11 @@ export const previewPage = /* html */ `<!doctype html>
fetch("/meta").then(function (r) { return r.json(); }).then(function (m) {
session = m.session;
applyMeta(m);
+ notesOn = !!m.notesDir;
+ $("notesBtn").hidden = !notesOn;
+ loadNotes();
loadAudio(m.audio);
- setTime(0);
+ setTime(startFrame());
$("buffering").classList.add("on");
whenPlayer();
});
@@ -604,11 +1208,25 @@ export const previewPage = /* html */ `<!doctype html>
window.gitframesPlayer.then(function (p) {
player = p;
$("play").disabled = false;
- show(frame).then(scheduleWarm);
- }, showError);
+ show(frame).then(function () {
+ pageState = "ready";
+ renderPins();
+ document.documentElement.dataset.preview = "ready";
+ settleReady();
+ scheduleWarm();
+ });
+ }, function (err) {
+ showError(err);
+ document.documentElement.dataset.preview = "error";
+ settleReady(err instanceof Error ? err : new Error(String(err)));
+ });
}
window.addEventListener("gitframes:player", function () { if (meta) whenPlayer(); });
- window.addEventListener("error", function (e) { if (!player) showError(e.error || e.message); });
+ window.addEventListener("error", function (e) {
+ if (!player) showError(e.error || e.message);
+ else report("error", [e.error || e.message]);
+ });
+ window.addEventListener("unhandledrejection", function (e) { report("error", [e.reason]); });
})();
</script>
<script type="module" src="/@gitframes/player.js"></script>
diff --git a/packages/gitframes/src/preview/player.ts b/packages/gitframes/src/preview/player.ts
index c4e46ccd..3776efee 100644
--- a/packages/gitframes/src/preview/player.ts
+++ b/packages/gitframes/src/preview/player.ts
@@ -64,14 +64,20 @@ export interface PreviewPlayer {
warm(frame: number): Promise<boolean>;
/** Frames rendered ahead in order, for playback at full frame rate. */
buffer: PlaybackBuffer;
+ /** A frame at full size as an image, e.g. to attach to a note. */
+ snapshot(frame: number): Promise<ImageBitmap>;
}
export interface PlaybackBuffer {
/** Most frames it holds at once. */
readonly capacity: number;
- /** Starts rendering every frame from `frame` on (stops an earlier run). */
+ /**
+ * Plays on from `frame`: frames already rendered from there are kept and
+ * rendering continues after them; anywhere else starts over.
+ */
start(frame: number): void;
- stop(): void;
+ /** Drops every rendered frame, e.g. when the playhead moves elsewhere. */
+ clear(): void;
/** Frames ready in a row from `frame` (0 when `frame` isn't buffered). */
ahead(frame: number): number;
/** The first frame not rendered yet. */
@@ -301,6 +307,7 @@ async function createPlayer(
const ringFrames = new Int32Array(capacity).fill(-1);
const blitter = new Blitter(device, surface.colorFormat);
let bufferToken = 0;
+ let producing = false;
let produced = 0;
let shown = -1;
@@ -316,9 +323,19 @@ async function createPlayer(
}
async function produce(token: number): Promise<void> {
+ producing = true;
+ try {
+ await produceFrames(token);
+ } finally {
+ if (token === bufferToken) producing = false;
+ }
+ }
+
+ async function produceFrames(token: number): Promise<void> {
while (token === bufferToken && produced <= lastFrame) {
- // The slot still holds a frame that hasn't been shown yet.
- if (produced - capacity > shown) {
+ // The slot holds a frame not shown yet, or the one on screen (kept,
+ // so playing on after a pause starts from the buffer).
+ if (produced - capacity >= shown) {
await new Promise((r) => setTimeout(r, 4));
continue;
}
@@ -335,7 +352,11 @@ async function createPlayer(
);
await drawing;
drawing = null;
- if (token !== bufferToken) return;
+ if (token !== bufferToken) {
+ // Stopped mid-frame: a frame asked for meanwhile still draws.
+ pump();
+ return;
+ }
ringFrames[slot] = frame;
produced = frame + 1;
pump();
@@ -348,14 +369,21 @@ async function createPlayer(
return produced;
},
start(frame) {
- const token = ++bufferToken;
+ shown = frame - 1;
+ // Resuming where playback paused: keep what is rendered ahead.
+ if (ringFrames[frame % capacity] === frame && frame < produced) {
+ if (!producing) void produce(++bufferToken);
+ return;
+ }
ringFrames.fill(-1);
produced = frame;
- shown = frame - 1;
- void produce(token);
+ void produce(++bufferToken);
},
- stop() {
+ clear() {
bufferToken++;
+ producing = false;
+ ringFrames.fill(-1);
+ produced = 0;
},
ahead(frame) {
if (ringFrames[frame % capacity] !== frame) return 0;
@@ -393,10 +421,67 @@ async function createPlayer(
return true;
},
buffer,
+ async snapshot(frame) {
+ while (drawing) await drawing;
+ const done = (async () => {
+ await draw(frame, false);
+ if (!offscreen) throw new Error("no frame to capture");
+ return readTexture(device, offscreen);
+ })();
+ drawing = done.then(
+ () => {},
+ () => {},
+ );
+ try {
+ return await done;
+ } finally {
+ drawing = null;
+ pump();
+ }
+ },
};
return player;
}
+/** Reads a texture back as an image (RGBA or BGRA, as the canvas format is). */
+async function readTexture(
+ device: GPUDevice,
+ texture: GPUTexture,
+): Promise<ImageBitmap> {
+ const { width, height } = texture;
+ const bytesPerRow = Math.ceil((width * 4) / 256) * 256;
+ const buffer = device.createBuffer({
+ size: bytesPerRow * height,
+ usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ,
+ });
+ const encoder = device.createCommandEncoder();
+ encoder.copyTextureToBuffer(
+ { texture },
+ { buffer, bytesPerRow },
+ { width, height },
+ );
+ device.queue.submit([encoder.finish()]);
+ await buffer.mapAsync(GPUMapMode.READ);
+ const src = new Uint8Array(buffer.getMappedRange());
+ const pixels = new Uint8ClampedArray(width * height * 4);
+ const bgra = texture.format.startsWith("bgra");
+ for (let y = 0; y < height; y++) {
+ const row = src.subarray(y * bytesPerRow, y * bytesPerRow + width * 4);
+ pixels.set(row, y * width * 4);
+ }
+ buffer.unmap();
+ buffer.destroy();
+ for (let i = 0; i < pixels.length; i += 4) {
+ if (bgra) {
+ const b = pixels[i];
+ pixels[i] = pixels[i + 2];
+ pixels[i + 2] = b;
+ }
+ pixels[i + 3] = 255;
+ }
+ return createImageBitmap(new ImageData(pixels, width, height));
+}
+
function containsOp(node: VirtualMediaData, op: string): boolean {
if ((node.operation as { op?: string } | undefined)?.op === op) return true;
return (node.children ?? []).some((child) => containsOp(child, op));
diff --git a/packages/gitframes/src/preview/preview.test.ts b/packages/gitframes/src/preview/preview.test.ts
index d5bda87f..748d3730 100644
--- a/packages/gitframes/src/preview/preview.test.ts
+++ b/packages/gitframes/src/preview/preview.test.ts
@@ -155,9 +155,10 @@ describe("startPreview", () => {
});
it("closes once the last tab has gone, but not on a reload", async () => {
+ const lines: string[] = [];
const session = await start(
{ entry },
- { open: false, port: 0, idleCloseMs: 100 },
+ { open: false, port: 0, idleCloseMs: 100, log: (l) => lines.push(l) },
);
let isClosed = false;
session.closed.then(() => {
@@ -177,7 +178,121 @@ describe("startPreview", () => {
expect(isClosed).toBe(false);
// The tab closes for good.
tab.destroy();
- await session.closed;
+ expect(await session.closed).toBe("idle");
+ expect(lines).toEqual([
+ "[gitframes preview] page opened; the server stops 0.1 s after its last tab closes",
+ "[gitframes preview] stopped: its tab was closed",
+ ]);
+ });
+
+ it("reports the page's errors once each", async () => {
+ const lines: string[] = [];
+ const session = await start(
+ { entry },
+ { open: false, port: 0, log: (l) => lines.push(l) },
+ );
+ const send = (body: unknown, type = "application/json") =>
+ fetch(`${session.url}@gitframes/log`, {
+ method: "POST",
+ headers: { "content-type": type },
+ body: JSON.stringify(body),
+ });
+ expect((await send({ level: "error", message: "boom" })).status).toBe(204);
+ await send({ level: "error", message: "boom" });
+ await send({ level: "warning", message: "[gitframes] font" });
+ // Not JSON: a form post from another site.
+ expect((await send({ message: "spoof" }, "text/plain")).status).toBe(404);
+ expect(lines).toEqual([
+ "[gitframes preview] error in the page: boom",
+ "[gitframes preview] warning in the page: [gitframes] font",
+ ]);
+ });
+
+ it("keeps notes pinned on the page as files, and reports them", async () => {
+ const project = await fs.promises.mkdtemp(
+ path.join(os.tmpdir(), "gf-notes-"),
+ );
+ try {
+ const dir = path.join(project, ".gitframes", "preview-notes");
+ const lines: string[] = [];
+ const session = await start(
+ { entry },
+ { open: false, port: 0, notesDir: dir, log: (l) => lines.push(l) },
+ );
+ const meta = await (await fetch(`${session.url}meta`)).json();
+ expect(meta.notesDir).toBe(dir);
+
+ const send = (body: unknown) =>
+ fetch(`${session.url}@gitframes/notes`, {
+ method: "POST",
+ headers: { "content-type": "application/json" },
+ body: JSON.stringify(body),
+ });
+ const jpeg = `data:image/jpeg;base64,${Buffer.from("jpeg-bytes").toString("base64")}`;
+ const added = await (
+ await send({
+ op: "add",
+ note: {
+ frame: 5,
+ time: 0.5,
+ x: 0.25,
+ y: 0.5,
+ text: " Bigger title ",
+ image: jpeg,
+ },
+ })
+ ).json();
+ expect(added).toMatchObject({
+ id: 1,
+ frame: 5,
+ x: 0.25,
+ y: 0.5,
+ text: "Bigger title",
+ done: false,
+ });
+ expect(await fs.promises.readFile(added.image, "utf8")).toBe(
+ "jpeg-bytes",
+ );
+ expect(
+ await fs.promises.readFile(
+ path.join(project, ".gitframes", ".gitignore"),
+ "utf8",
+ ),
+ ).toBe("*\n");
+ expect(lines.at(-1)).toBe(
+ `[gitframes preview] note 1 at 0:00.50 (frame 5), spot 25%,50%: Bigger title\n frame with the spot marked: ${added.image} · all notes: ${dir}/notes.json`,
+ );
+
+ await send({
+ op: "add",
+ note: {
+ frame: 2,
+ time: 0.2,
+ x: 0.1,
+ y: 0.1,
+ w: 0.5,
+ h: 0.2,
+ text: "Too dark",
+ },
+ });
+ await send({ op: "update", id: 2, done: true });
+ expect(lines.at(-1)).toBe("[gitframes preview] note 2 marked done");
+
+ // notes.json is the record: edits made to it show up.
+ const file = JSON.parse(
+ await fs.promises.readFile(path.join(dir, "notes.json"), "utf8"),
+ );
+ expect(file).toHaveLength(2);
+ expect(file[1]).toMatchObject({ w: 0.5, h: 0.2, done: true });
+
+ expect((await send({ op: "remove", id: 1 })).status).toBe(200);
+ expect(fs.existsSync(added.image)).toBe(false);
+ const list = await (await fetch(`${session.url}@gitframes/notes`)).json();
+ expect(list.map((n: { id: number }) => n.id)).toEqual([2]);
+ expect((await send({ op: "remove", id: 9 })).status).toBe(404);
+ } finally {
+ await fs.promises.rm(project, { recursive: true, force: true });
+ }
});
it("a new preview of the project takes over the port", async () => {
@@ -185,7 +300,7 @@ describe("startPreview", () => {
const port = Number(new URL(first.url).port);
const second = await start({ entry }, { open: false, port });
- await first.closed;
+ expect(await first.closed).toBe("replaced");
expect(second.url).toBe(first.url);
expect((await fetch(`${second.url}meta`)).status).toBe(200);
});
diff --git a/plugins/gitframes/skills/gitframes-render/SKILL.md b/plugins/gitframes/skills/gitframes-render/SKILL.md
index 95a375e6..ae40994a 100644
--- a/plugins/gitframes/skills/gitframes-render/SKILL.md
+++ b/plugins/gitframes/skills/gitframes-render/SKILL.md
@@ -126,8 +126,11 @@ await session.closed; // keep the process alive while the user watches
```
- **The export is a function returning the `Composition`** (it may be async), or a `Composition` itself. The browser calls it, so build-time Node code in it must stay simple: `node:path`, `fileURLToPath(import.meta.url)` and synchronous `fs` reads (JSON, text) work through shims; writes are skipped. Assets referenced by absolute path load from the server, limited to the project that holds the entry (its nearest `.git` or `package.json`); pass `root` with one or more paths for assets kept outside it (e.g. a shared fonts folder).
-- **Run it in the background.** The preview serves until it is stopped. Start the script as a background command with the longest timeout your harness allows, tell the user the URL, and ask for feedback in the chat. Feedback comes from the user, not from the page.
-- **One tab for the whole loop.** The port is fixed per project directory. Running the preview again (after you've made changes) takes over from the one already running, and a tab left open reconnects and reloads into the new version by itself. Don't ask the user to reopen anything. When the user closes the tab, the preview stops by itself about 5 s later (a reload doesn't stop it). If the preview was stopped (tab closed, time limit, or you killed it), just start it again.
+- **Run it in the background, and read its output.** Start the script as a background command with the longest timeout your harness allows, tell the user the URL, and ask for feedback in the chat. The command's output (stderr, prefixed `[gitframes preview]`) says when the page opened, reports each distinct error from the page once (a build error, a frame that threw, a font or renderer that failed to load, no WebGPU), and says why it stopped. Check it after the page opens instead of assuming the film drew. `log` redirects or silences these lines, and `session.closed` resolves with the reason: `"idle"`, `"replaced"` or `"closed"`.
+- **One tab for the whole loop.** The port is fixed per project directory. Running the preview again (after you've made changes) takes over from the one already running, and a tab left open reconnects and reloads into the new version by itself, at the moment it was showing. Don't ask the user to reopen anything. When the user closes the tab, the preview stops by itself about 5 s later (a reload doesn't stop it; `idleCloseMs` changes the delay). If the preview was stopped (tab closed, time limit, or you killed it), just start it again.
+- **Notes pinned on the picture are the user's precise feedback.** Paused, the user clicks the frame (or drags an area) and writes what should change; the note keeps the frame, the spot as fractions of the frame (`x`, `y`, and `w`, `h` for an area) and the text. Each note prints in the output (`note 3 at 0:12.50 (frame 750), spot 42%,31%: …`) with the path of `note-<id>.jpg`, the frame with the spot marked, and all of them are in `.gitframes/preview-notes/notes.json` (`.gitframes` ignores itself in git; `notesDir` moves it, `false` turns notes off). To act on them: read `notes.json`, open each open note's picture to see exactly what it points at, find the layer in the code from the moment and the spot, make the change, and run the preview again. The tab comes back with the notes, so the user can check them and tick them off. You can also set `"done": true` in `notes.json` yourself. A chat that can't read files gets the same list from the **Copy** button in the Notes panel.
+- **Point at a moment.** `#t=12.5` in the URL opens the player at 12.5 s (`#frame=750` by frame), and the address follows the playhead when it stops, so a link you give the user lands where you mean.
+- **Drive it from a script, not with clicks.** If you can run JavaScript in the page (an agent browser), use `window.gitframesPreview`: `await seek(seconds)` or `await seekFrame(n)` resolve once that frame is drawn (take the screenshot then), `play()` and `pause()` control playback, `notes()` lists the notes, and `state()` returns `{ state: "loading" | "ready" | "error", error, frame, time, playing, buffering, audio, connected, meta }`. `<html data-preview="ready">` marks the first frame drawn. A hidden tab pauses playback, since browsers throttle it.
- **Show it where the user is.** `startPreview` only serves the page and returns the URL. If your app has a built-in browser (Claude Code's browser pane, Codex's), open the URL there. Otherwise give the user the link, or pass `open: true` to open their default browser (skipped when an open tab reconnects on its own). The page needs WebGPU (current Chrome, Edge or Safari).
- Audio is the same mix `renderVideo` muxes (`audio: false` skips it). Playback uses the soundtrack as its clock; when a frame takes long (a video seek, a heavy shot), the clock and the sound hold until the picture catches up.
diff --git a/plugins/gitframes/skills/gitframes/SKILL.md b/plugins/gitframes/skills/gitframes/SKILL.md
index bb95b7c8..1a1b3341 100644
--- a/plugins/gitframes/skills/gitframes/SKILL.md
+++ b/plugins/gitframes/skills/gitframes/SKILL.md
@@ -230,11 +230,12 @@ Show the user the frame PNGs or the grid before the full render. `gitframes-rend
`npm run preview` serves a localhost player (picture, sound, timeline) and prints its URL. The page runs `film.ts` itself and renders with WebGPU, so the user sees the real film at full frame rate.
-- Run it as a background command; it serves until its tab closes.
+- Run it as a background command and read its output: it says when the page opened, prints errors from the page (a failed build, a frame that threw, a missing font), and says why it stopped. It stops 5 s after its last tab closes; just run it again.
- It doesn't open anything. If your app has a built-in browser (Claude Code, Codex), open the URL there; otherwise give the user the link. `startPreview(..., { open: true })` opens their default browser.
- **Reference assets from the file's URL.** The page runs `film.ts` itself, so asset paths must resolve in the browser too: build them from the module's own URL, `path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../assets/fonts")`, rather than `process.cwd()` or a bare relative path. The preview serves any file inside the project (the folder with `package.json`); pass `root` (one or more paths) to `startPreview` for fonts or media kept elsewhere.
-- After changing the film, run it again. It takes over the same URL, and the open tab reloads by itself.
-- Take feedback in chat. `gitframes-render` has the details.
+- After changing the film, run it again. It takes over the same URL, and the open tab reloads by itself at the same moment.
+- Link to a moment with `#t=12.5` (seconds). In a browser you can script, `window.gitframesPreview` has `seek(seconds)`, `play()`, `pause()` and `state()`; `seek` resolves once the frame is drawn, so screenshot after it.
+- **The user can pin notes on the picture.** Pausing and clicking (or dragging an area) adds a note at that spot and moment. Each one prints in the preview's output and is saved in `.gitframes/preview-notes/`: `notes.json`, plus `note-<id>.jpg`, the frame with the spot marked. When the user says they left notes, read `notes.json` and look at each open note's picture before you edit. Then run the preview again so they can check the changes and tick them off. `gitframes-render` has the details.
## 5. Grow the film