trace-avatar-render 0.0.0-stage → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,840 @@
1
+ import { Page, Browser } from 'playwright';
2
+ import { Ai, preview, Suggestion, Candidate, TextCandidate, applyRaw } from 'trace-avatar/assist';
3
+
4
+ /**
5
+ * The guide's own timeline, and the edit list made from it. PURE: plain numbers in, plain numbers out.
6
+ *
7
+ * Times are wall-clock milliseconds (the page logs Date.now(), the screencast stamps frames in epoch
8
+ * seconds), so events and frames from every page load share one clock.
9
+ */
10
+ type Phase = 'idle' | 'playing' | 'paused' | 'waiting' | 'ended';
11
+ interface TimelineEvent {
12
+ t: number;
13
+ type: 'ready' | 'play' | 'state' | 'step' | 'stalled' | 'handoff' | 'page' | 'end' | 'error' | 'blocked' | 'unload';
14
+ phase?: Phase;
15
+ index?: number;
16
+ stepType?: string;
17
+ reason?: string;
18
+ message?: string;
19
+ url?: string;
20
+ /** step: where its element was (viewport CSS px). */
21
+ rect?: {
22
+ x: number;
23
+ y: number;
24
+ w: number;
25
+ h: number;
26
+ };
27
+ /** step: its words. */
28
+ say?: string;
29
+ }
30
+ interface Span {
31
+ from: number;
32
+ to: number;
33
+ phase: Phase;
34
+ }
35
+ /**
36
+ * A kept stretch of the capture, in source time. A hold (from === to, `hold` ms) shows the frame at `from`
37
+ * for that long: the video waits, for instance while a narrated line finishes.
38
+ */
39
+ interface Segment {
40
+ from: number;
41
+ to: number;
42
+ hold?: number;
43
+ }
44
+ interface EditOptions {
45
+ /** Where the output starts and ends (source time). */
46
+ start: number;
47
+ end: number;
48
+ /** A wait longer than this keeps its first and last half of it; the middle is cut. Default 800. 0 keeps every wait. */
49
+ maxWaitMs?: number;
50
+ }
51
+ declare const DEFAULT_MAX_WAIT_MS = 800;
52
+ /**
53
+ * The player's phase over [start, end]. A page unloading counts as waiting until the next page's player
54
+ * reports a phase again.
55
+ */
56
+ declare function spansOf(events: readonly TimelineEvent[], start: number, end: number): Span[];
57
+ /** The stretches of the capture to keep: everything, except the middle of each long wait. */
58
+ declare function editList(events: readonly TimelineEvent[], o: EditOptions): Segment[];
59
+ declare const durationOf: (segs: readonly Segment[]) => number;
60
+ /** The source time shown at output time `t` (clamped to the ends). */
61
+ declare function sourceAt(segs: readonly Segment[], t: number): number;
62
+ /** The output time where source time `src` lands, or null when it was cut. */
63
+ declare function outputAt(segs: readonly Segment[], src: number): number | null;
64
+ /**
65
+ * Insert holds: each `{ at, ms }` (at = output time on `segs`) freezes the frame there for `ms`. Later output
66
+ * times move by the holds before them.
67
+ */
68
+ declare function withHolds(segs: readonly Segment[], holds: ReadonlyArray<{
69
+ at: number;
70
+ ms: number;
71
+ }>): Segment[];
72
+ /** The source time of every output frame at `fps`. */
73
+ declare function frameTimes(segs: readonly Segment[], fps: number): number[];
74
+ /** For each wanted time, the last captured frame at or before it (the first frame before any). */
75
+ declare function pickFrames(captured: readonly number[], want: readonly number[]): number[];
76
+
77
+ /**
78
+ * Play a trace on the real app in headless Chromium and capture it.
79
+ *
80
+ * The player (trace-perform.min.js) and a small bootstrap are injected into every page of the context,
81
+ * so a guide that crosses a full page load carries on (the player's resumeKey) and keeps logging its
82
+ * events. Frames come from Chromium's screencast, stamped on the same wall clock as the events.
83
+ */
84
+
85
+ interface CaptureOptions {
86
+ /** The trace object. */
87
+ trace: unknown;
88
+ url: string;
89
+ mode: 'overlay' | 'perform';
90
+ viewport: {
91
+ w: number;
92
+ h: number;
93
+ };
94
+ /** Device pixel ratio. Default 1. */
95
+ scale?: number;
96
+ /** A signed-in session (Playwright storageState file). */
97
+ storageState?: string;
98
+ /** The player build (trace-perform.min.js). */
99
+ playerFile: string;
100
+ /** Selectors hidden before capture (e.g. your own dev toolbars). */
101
+ hide?: string[];
102
+ /** Selectors blurred before capture, as well as [data-trace-blur]. */
103
+ blur?: string[];
104
+ rate?: number;
105
+ /** The player's own captions: 'none' when the renderer burns them in itself. Default: the player's. */
106
+ captions?: 'bubble' | 'bar' | 'none';
107
+ /** A guide's own pause (or a hand-off) is held this long, then it plays on. Default 1200. */
108
+ pauseHoldMs?: number;
109
+ /** Keep capturing this long after the end. Default 1500. */
110
+ holdEndMs?: number;
111
+ /** Still frames before the guide starts. Default 500. */
112
+ leadMs?: number;
113
+ /** Render a stalled guide anyway (it shows "Looking for …") instead of failing. */
114
+ allowStall?: boolean;
115
+ /** Called on a stall with the live page, before anything else happens; what it returns rides on the RenderError. */
116
+ onStall?: (page: Page, stall: {
117
+ index: number;
118
+ reason: string;
119
+ }) => Promise<unknown>;
120
+ /** Give up after this long. Default 120 000. */
121
+ timeoutMs?: number;
122
+ headless?: boolean;
123
+ }
124
+ interface CapturedFrame {
125
+ t: number;
126
+ png: Buffer;
127
+ }
128
+ interface Capture {
129
+ frames: CapturedFrame[];
130
+ /** The viewport in CSS px and the device pixel ratio (frames are viewport × scale). */
131
+ viewport?: {
132
+ w: number;
133
+ h: number;
134
+ scale: number;
135
+ };
136
+ /** Each page's title, by path. */
137
+ titles?: Record<string, string>;
138
+ events: TimelineEvent[];
139
+ /** When the guide started and when capture stopped (wall ms). */
140
+ playAt: number;
141
+ stopAt: number;
142
+ endAt: number | null;
143
+ }
144
+ declare class RenderError extends Error {
145
+ readonly screenshot?: Buffer | undefined;
146
+ /** A stall: which step, why, and what onStall found on the page. */
147
+ stall?: {
148
+ index: number;
149
+ reason: string;
150
+ data?: unknown;
151
+ };
152
+ constructor(message: string, screenshot?: Buffer | undefined);
153
+ }
154
+ declare function capture(o: CaptureOptions): Promise<Capture>;
155
+ /** Where the player build is: an explicit file, TRACE_AVATAR_PLAYER, or the installed trace-avatar. */
156
+ declare function findPlayer(explicit?: string, env?: NodeJS.ProcessEnv): Promise<string>;
157
+
158
+ /** RGBA pixel helpers. PURE. */
159
+ interface Image {
160
+ width: number;
161
+ height: number;
162
+ data: Uint8Array;
163
+ }
164
+ /** The size to scale to for a target width (even numbers, for video encoders), keeping the aspect. */
165
+ declare function fitWidth(w: number, h: number, width?: number): {
166
+ width: number;
167
+ height: number;
168
+ };
169
+ /** Area-average (box) downscale: every source pixel contributes by its overlap. Upscaling isn't needed here. */
170
+ declare function resize(src: Image, W: number, H: number): Image;
171
+ /** Crop to the top-left W×H (to make sizes even). */
172
+ declare function crop(src: Image, W: number, H: number): Image;
173
+ declare function pixel(img: Image, x: number, y: number): [number, number, number];
174
+
175
+ /**
176
+ * The auto camera: zoom in on the action before it happens, pan between actions close in time, and zoom
177
+ * back out between bursts. Deterministic: the same timeline gives the same camera. PURE.
178
+ *
179
+ * Times are output milliseconds (after cuts); points and rects are source pixels.
180
+ */
181
+ interface Rect {
182
+ x: number;
183
+ y: number;
184
+ w: number;
185
+ h: number;
186
+ }
187
+ interface Action {
188
+ t: number;
189
+ x: number;
190
+ y: number;
191
+ kind: string;
192
+ }
193
+ interface CameraOptions {
194
+ width: number;
195
+ height: number;
196
+ /** How far in. Default 1.6. */
197
+ zoom?: number;
198
+ /** The camera arrives this long before the action. Default 400. */
199
+ leadMs?: number;
200
+ /** Each move takes this long. Default 400. */
201
+ easeMs?: number;
202
+ /** Actions closer than this stay in one zoomed shot (the camera pans). Default 2500. */
203
+ joinMs?: number;
204
+ /** Stay in after the last action of a shot. Default 900. */
205
+ holdMs?: number;
206
+ /** A zoom change at most this often: shots closer than this are joined. Default 1500. */
207
+ minChangeMs?: number;
208
+ }
209
+ interface Key {
210
+ t: number;
211
+ z: number;
212
+ x: number;
213
+ y: number;
214
+ }
215
+ /** Steps the camera zooms to; scrolls (and anything without a point) send it back out. */
216
+ declare const ZOOM_KINDS: Set<string>;
217
+ /** Keyframes for the camera (exported for tests). */
218
+ declare function cameraKeys(actions: readonly Action[], o: CameraOptions): Key[];
219
+ /** The camera at each output time: the source rect to show. */
220
+ declare function cameraPath(actions: readonly Action[], o: CameraOptions): (t: number) => Rect;
221
+
222
+ /** Where the capture goes in the output picture. PURE. */
223
+
224
+ type FrameStyle = 'none' | 'browser';
225
+ interface Layout {
226
+ width: number;
227
+ height: number;
228
+ /** Where the page is drawn. */
229
+ content: Rect;
230
+ /** The window's title bar (browser frame only). */
231
+ bar: Rect | null;
232
+ /** The window (bar + content), for the shadow and corners. */
233
+ window: Rect;
234
+ }
235
+ /**
236
+ * The output size for a capture of srcW×srcH shown `width` wide (default: the capture's width, never
237
+ * upscaled), with or without a browser window around it.
238
+ */
239
+ declare function layoutOf(srcW: number, srcH: number, width: number | undefined, frame?: FrameStyle): Layout;
240
+
241
+ /**
242
+ * The parts of a frame that have text in them (the window's title bar, burned-in captions, title and end
243
+ * cards) are drawn once each by Chromium and composed in JS. One page, reused.
244
+ */
245
+
246
+ interface CardOptions {
247
+ title: string;
248
+ sub?: string;
249
+ color?: string;
250
+ }
251
+ interface Layers {
252
+ /** The background, the window and its title bar, for a page path. */
253
+ base(layout: Layout, o: {
254
+ background: string;
255
+ title?: string;
256
+ path?: string;
257
+ }): Promise<Image>;
258
+ /** A caption with its own backdrop, on transparent pixels, at most `maxWidth` wide. */
259
+ caption(text: string, o: {
260
+ maxWidth: number;
261
+ fontPx: number;
262
+ }): Promise<Image>;
263
+ /** A full-frame card. */
264
+ card(layout: Layout, o: CardOptions & {
265
+ background: string;
266
+ }): Promise<Image>;
267
+ close(): Promise<void>;
268
+ }
269
+ /** The default background behind a framed capture. */
270
+ declare const DEFAULT_BACKGROUND = "linear-gradient(135deg, #dfe7fb 0%, #eef0f6 50%, #f6e9f1 100%)";
271
+ declare function createLayers(browser: Browser): Promise<Layers>;
272
+
273
+ /**
274
+ * Mono 16-bit PCM: read and write WAV, resample, trim silence, and lay lines on one track. PURE.
275
+ */
276
+ interface Pcm {
277
+ pcm: Int16Array;
278
+ sampleRate: number;
279
+ }
280
+ /** The output track's rate. */
281
+ declare const TRACK_RATE = 48000;
282
+ /** A WAV file (mono, 16-bit) for these samples. */
283
+ declare function toWav(pcm: Int16Array, sampleRate: number): Uint8Array;
284
+ /** Samples from a WAV file: 16-bit PCM, any number of channels (mixed down to mono). */
285
+ declare function fromWav(bytes: Uint8Array): Pcm;
286
+ /** Little-endian 16-bit samples from raw bytes. */
287
+ declare function fromS16le(bytes: Uint8Array): Int16Array;
288
+ /** Linear resampling. */
289
+ declare function resample(pcm: Int16Array, from: number, to: number): Int16Array;
290
+ /** Without the silence at either end (below `level`), keeping `padMs` of it. All silence gives nothing. */
291
+ declare function trimSilence(p: Pcm, o?: {
292
+ level?: number;
293
+ padMs?: number;
294
+ }): Pcm;
295
+ declare const msOf: (p: Pcm) => number;
296
+ /**
297
+ * One track `totalMs` long at TRACK_RATE: each line from its start (ms), with a short fade in and out, summed
298
+ * and clipped. A line that runs past the end is cut there.
299
+ */
300
+ declare function mix(lines: ReadonlyArray<{
301
+ start: number;
302
+ audio: Pcm;
303
+ }>, totalMs: number, o?: {
304
+ fadeMs?: number;
305
+ }): Int16Array;
306
+
307
+ /**
308
+ * Narration: what each step says, when, and where the video holds so a line ends before its step acts.
309
+ * The planning is PURE; suggestScript() asks an AI for spoken lines (a person edits the file it writes).
310
+ */
311
+
312
+ /** A narration script: lines by step number (1-based). */
313
+ interface Script {
314
+ lines: Array<{
315
+ n: number;
316
+ text: string;
317
+ }>;
318
+ }
319
+ interface PlannedLine {
320
+ index: number;
321
+ text: string; /** ms on the held timeline */
322
+ start: number;
323
+ ms: number;
324
+ }
325
+ interface NarrationPlan {
326
+ lines: PlannedLine[];
327
+ /** Output times on the cut timeline (before any hold) and how long to hold there. */
328
+ holds: Array<{
329
+ at: number;
330
+ ms: number;
331
+ }>;
332
+ /** Steps whose line needed a hold longer than maxHoldMs. */
333
+ long: Array<{
334
+ index: number;
335
+ ms: number;
336
+ }>;
337
+ }
338
+ interface PlanOptions {
339
+ /** The first line starts here. Default 300. */
340
+ firstMs?: number;
341
+ /** A line starts this long after the step before it acts (the cursor sets off). Default 200. */
342
+ afterActMs?: number;
343
+ /** A line ends at least this long before its step acts. Default 250. */
344
+ beforeActMs?: number;
345
+ /** Between two lines. Default 150. */
346
+ gapMs?: number;
347
+ /** After the last line, before the video ends. Default 400. */
348
+ tailMs?: number;
349
+ /** A hold longer than this is reported in `long`. Default 8000. */
350
+ maxHoldMs?: number;
351
+ }
352
+ /** The spoken text of each step: the script's line, else its caption (say). Steps with neither are silent. */
353
+ declare function linesOf(steps: ReadonlyArray<{
354
+ say?: string;
355
+ }>, script?: Script): Map<number, string>;
356
+ /** Reads a script: { lines: [{ n, text }] }. */
357
+ declare function parseScript(json: unknown): Script;
358
+ /**
359
+ * When each line plays, and the holds that make it fit. `acts` are the steps as they act, on the cut timeline
360
+ * (output ms, before holds); `ms` is how long each step's line is; `endMs` the cut timeline's length.
361
+ */
362
+ declare function planNarration(acts: ReadonlyArray<{
363
+ index: number;
364
+ t: number;
365
+ }>, lines: ReadonlyMap<number, {
366
+ text: string;
367
+ ms: number;
368
+ }>, endMs: number, o?: PlanOptions): NarrationPlan & {
369
+ endHoldMs: number;
370
+ };
371
+ /** <out>.narration.txt: the spoken script with its times in the video. */
372
+ declare function narrationText(lines: readonly PlannedLine[], offsetMs?: number): string;
373
+ /** A script proposed by an AI from the steps (the same privacy-safe payload as captions: nothing typed is sent). */
374
+ declare function suggestScript(ai: Ai, trace: Parameters<typeof preview>[1]): Promise<{
375
+ script: Script;
376
+ dropped: Array<{
377
+ n: unknown;
378
+ why: string;
379
+ }>;
380
+ }>;
381
+
382
+ /**
383
+ * Voices for narration (--voice). Always configurable; without --voice nothing speaks.
384
+ *
385
+ * --voice gateway[:gemini[/<model>][:<voice>]] our AI gateway (AI_GATEWAY_URL, AI_GATEWAY_KEY). DeepSeek goes
386
+ * first wherever it offers a feature, but has no speech API, so
387
+ * this is Gemini (default gemini-2.5-flash-preview-tts, Kore)
388
+ * --voice openai:<model>[:<voice>] /audio/speech at OPENAI_BASE_URL (OpenAI, or any compatible
389
+ * local server); OPENAI_API_KEY
390
+ * --voice say[:<voice>] macOS `say`, offline
391
+ * --voice ./voice.js a module whose default export is a Voice
392
+ *
393
+ * Only the spoken text is sent. Lines are cached by (voice, text), so a re-render pays only for changed lines.
394
+ */
395
+
396
+ /** Speak one line. */
397
+ type Voice = (text: string) => Promise<Pcm>;
398
+ declare const GEMINI_TTS: {
399
+ model: string;
400
+ voice: string;
401
+ };
402
+ /** Gemini speech (generateContent with audio out): 24 kHz 16-bit PCM, base64. */
403
+ declare function geminiVoice(o: {
404
+ url: string;
405
+ key: string;
406
+ model?: string;
407
+ voice?: string;
408
+ bearer?: boolean;
409
+ headers?: Record<string, string>;
410
+ fetch?: typeof fetch;
411
+ }): Voice;
412
+ /** OpenAI-compatible /audio/speech, as raw 24 kHz 16-bit PCM. */
413
+ declare function openAiVoice(o: {
414
+ baseUrl: string;
415
+ key?: string;
416
+ model: string;
417
+ voice?: string;
418
+ fetch?: typeof fetch;
419
+ }): Voice;
420
+ /** macOS `say`, offline. */
421
+ declare function sayVoice(o?: {
422
+ voice?: string;
423
+ }): Voice;
424
+ /** A voice that keeps every line it speaks in `dir`, by hash(id, text). */
425
+ declare function cached(voice: Voice, id: string, dir: string): Voice & {
426
+ hits: number;
427
+ misses: number;
428
+ };
429
+ /** The --voice spec to a Voice (cached in `cacheDir` unless it is null). */
430
+ declare function voiceOf(spec: string, env?: NodeJS.ProcessEnv, o?: {
431
+ cacheDir?: string | null;
432
+ fetch?: typeof fetch;
433
+ }): Promise<Voice>;
434
+
435
+ /**
436
+ * AI in the renderer: which provider (--ai), and the visual check of rendered frames (--qa).
437
+ * Without --ai nothing calls a model. The renderer never changes a trace: suggestions go to a file
438
+ * a person applies (the suggest / apply commands).
439
+ */
440
+
441
+ /**
442
+ * --ai gateway DeepSeek, falling back to Gemini, then OpenAI (AI_GATEWAY_URL, AI_GATEWAY_KEY)
443
+ * --ai gateway:<p>[/<model>][,<p>…] those providers in that order (a model for the first)
444
+ * --ai openai:<model> (OPENAI_BASE_URL, default https://api.openai.com/v1; OPENAI_API_KEY)
445
+ * --ai ./provider.js (its default export is the Ai function)
446
+ * `vision` (--ai-vision) is the model for calls with images; the gateway's DeepSeek default is deepseek-flash.
447
+ */
448
+ declare function providerOf(spec: string, env?: NodeJS.ProcessEnv, o?: {
449
+ vision?: string;
450
+ }): Promise<Ai>;
451
+ declare const QA_KINDS: readonly ["error", "empty", "stalled", "personal-data", "wrong-page", "other"];
452
+ type QaKind = (typeof QA_KINDS)[number];
453
+ interface QaFrame {
454
+ at: number;
455
+ label: string;
456
+ png: Uint8Array;
457
+ }
458
+ interface QaFlag {
459
+ at: number;
460
+ kind: QaKind;
461
+ note: string;
462
+ }
463
+ /** Ask the model to look at the frames. The answer is checked: unknown frames or kinds are dropped. */
464
+ declare function runQa(ai: Ai, frames: readonly QaFrame[], context: {
465
+ title?: string;
466
+ steps: Array<{
467
+ n: number;
468
+ type: string;
469
+ say?: string;
470
+ }>;
471
+ }): Promise<QaFlag[]>;
472
+
473
+ /** WebVTT captions and chapters on the edited timeline. PURE. */
474
+ interface Cue {
475
+ start: number;
476
+ end: number;
477
+ text: string;
478
+ }
479
+ declare function toVtt(cues: readonly Cue[]): string;
480
+ /**
481
+ * Captions from (time, text) starts: each lasts until the next starts, at most `maxMs`, and never past the end.
482
+ */
483
+ declare function captionCues(starts: ReadonlyArray<{
484
+ t: number;
485
+ text: string;
486
+ }>, endMs: number, maxMs?: number): Cue[];
487
+ /** Chapters: each caption starts one, titled by its first sentence; each runs until the next. */
488
+ declare function chapterCues(starts: ReadonlyArray<{
489
+ t: number;
490
+ text: string;
491
+ }>, endMs: number): Cue[];
492
+
493
+ /**
494
+ * render(): play a trace on the real app, cut its waits, and write GIF / MP4 files.
495
+ *
496
+ * capture (headless Chromium) ──► timeline + frames ──► edit list ──► frames at the target fps
497
+ * ──► compose (window frame, camera, burned-in captions, title / end cards) ──► encode (+ poster, VTT)
498
+ *
499
+ * With none of the E2 options set, a frame is the capture scaled to the output width, as in E1.
500
+ */
501
+
502
+ type OutFormat = 'gif' | 'mp4';
503
+ interface OutSpec {
504
+ file: string;
505
+ /** Output width in pixels (height keeps the aspect). Default: GIF 800, MP4 the capture's width. */
506
+ width?: number;
507
+ /** Default: GIF 12, MP4 30. */
508
+ fps?: number;
509
+ }
510
+ interface RenderOptions {
511
+ /** A trace object, or the path of a .trace.json. */
512
+ trace: unknown;
513
+ /** The page the guide starts on. */
514
+ url: string;
515
+ /** 'overlay' (Show me, default) or 'perform' (Do it for me: clicks and types for real). */
516
+ mode?: 'overlay' | 'perform';
517
+ /** Required for mode 'perform': render it only against a sandbox account. */
518
+ allowPerform?: boolean;
519
+ /** A signed-in session (Playwright storageState file). */
520
+ storageState?: string;
521
+ /** Default: the trace's meta.viewport, else 1280×800. */
522
+ viewport?: {
523
+ w: number;
524
+ h: number;
525
+ };
526
+ /** Device pixel ratio of the capture (2 for crisp video text). Default 1. */
527
+ scale?: number;
528
+ out: Array<string | OutSpec>;
529
+ cuts?: {
530
+ maxWaitMs?: number;
531
+ };
532
+ /** Render a stalled guide anyway instead of failing. */
533
+ allowStall?: boolean;
534
+ hide?: string[];
535
+ blur?: string[];
536
+ rate?: number;
537
+ /** The player build. Default: TRACE_AVATAR_PLAYER, else the installed trace-avatar's dist/trace-perform.min.js. */
538
+ player?: string;
539
+ /** Write the timeline and the edit list here (JSON). */
540
+ timeline?: string;
541
+ timeoutMs?: number;
542
+ headless?: boolean;
543
+ /** 'browser' puts the capture in a window (title bar with the page path) on a background. Default 'none'. */
544
+ frame?: FrameStyle;
545
+ /** CSS background behind the window and on the cards. Default a soft gradient. */
546
+ background?: string;
547
+ /** Zoom in on each action and pan between close ones. true, or { zoom } (default 1.6). Default off. */
548
+ camera?: boolean | {
549
+ zoom?: number;
550
+ };
551
+ /** 'burn' draws the steps' words into the video (the player's own bubble is then off), 'vtt' writes
552
+ * <out>.vtt and <out>.chapters.vtt beside the first output, 'both' does both. Default: neither. */
553
+ captions?: 'burn' | 'vtt' | 'both';
554
+ /** A still at the first click: true writes <out>.png beside the first output, or give a path. */
555
+ poster?: boolean | string;
556
+ /** A 1.5 s card before the guide: true (the trace's title and avatar), a title, or { title, sub }. */
557
+ titleCard?: boolean | string | CardOptions;
558
+ /** A 2 s card after it: true ("Done"), a title, or { title, sub }. */
559
+ endCard?: boolean | string | CardOptions;
560
+ /** The AI for qa and alt (see trace-avatar/assist). Without it nothing calls a model. */
561
+ ai?: Ai;
562
+ /** Send a frame per step (640 px) to the AI to look for errors, empty states, a stall, personal data. */
563
+ qa?: boolean;
564
+ /** Write <out>.alt.txt (alt text for the GIF) and, with VTT captions, AI chapter names. */
565
+ alt?: boolean;
566
+ /** Narrate MP4 outputs with this voice (see voiceOf). GIFs keep their timing and have no sound. */
567
+ voice?: Voice;
568
+ /** What each step says: a script ({ lines: [{ n, text }] }) or its path. Default: each step's caption. */
569
+ script?: string | Script;
570
+ /** Fail when a line needs a hold longer than 8 s (otherwise a warning). */
571
+ voiceStrict?: boolean;
572
+ /** Also write the narration track here (WAV). */
573
+ voiceOut?: string;
574
+ /** When a step can't find its element, or a wait's text never shows: propose a fix (<out>.repair.json, for
575
+ * `apply`), verified by playing the guide again with it. The render still fails: a person accepts the fix.
576
+ * With `ai`, unsure cases are asked; a wait with no clear text is offered as a guess (`by: 'guess'`). */
577
+ repair?: boolean;
578
+ /** With repair and ai: send a screenshot of the stalled page too. */
579
+ repairVision?: boolean;
580
+ }
581
+ /** What finish() takes besides the capture: the composing options, with the cards resolved. */
582
+ type FinishOptions = Pick<RenderOptions, 'cuts' | 'timeline' | 'frame' | 'background' | 'camera' | 'captions' | 'poster'> & {
583
+ cards?: {
584
+ title?: CardOptions;
585
+ end?: CardOptions;
586
+ };
587
+ /** Check frames with this AI (the steps give it context). */
588
+ qa?: {
589
+ ai: Ai;
590
+ title?: string;
591
+ steps: Array<{
592
+ n: number;
593
+ type: string;
594
+ say?: string;
595
+ }>;
596
+ };
597
+ /** Chapter names by step index (from the AI), instead of each caption's first sentence. */
598
+ chapterNames?: Array<{
599
+ index: number;
600
+ name: string;
601
+ }>;
602
+ /** Spoken lines by step index, for MP4 outputs. */
603
+ narration?: {
604
+ lines: Map<number, {
605
+ text: string;
606
+ audio: Pcm;
607
+ }>;
608
+ strict?: boolean;
609
+ out?: string;
610
+ };
611
+ };
612
+ interface RenderOutput {
613
+ file: string;
614
+ format: OutFormat;
615
+ width: number;
616
+ height: number;
617
+ fps: number;
618
+ frames: number;
619
+ bytes: number;
620
+ durationMs: number;
621
+ }
622
+ interface RenderResult {
623
+ /** Length of the video: after cuts, with any cards. */
624
+ durationMs: number;
625
+ /** Where the guide starts in the video (the title card's length; 0 without one). Add it to outputAt(). */
626
+ offsetMs: number;
627
+ /** Length as it played. */
628
+ rawMs: number;
629
+ /** Kept stretches, ms from the start of the capture. */
630
+ segments: Segment[];
631
+ /** Events, ms from the start of the capture. */
632
+ events: TimelineEvent[];
633
+ outputs: RenderOutput[];
634
+ /** Files written besides the videos. */
635
+ poster?: string;
636
+ vtt?: string;
637
+ chapters?: string;
638
+ /** <out>.alt.txt, with alt. */
639
+ alt?: string;
640
+ /** What the AI flagged in the frames, with qa (times in the video). */
641
+ qa?: QaFlag[];
642
+ /** With a voice: the lines as placed (ms in the video), the time added by holds, the script file, the track. */
643
+ narration?: {
644
+ lines: PlannedLine[];
645
+ holdMs: number;
646
+ text: string;
647
+ wav?: string;
648
+ };
649
+ /** Things worth knowing that didn't stop the render. */
650
+ warnings?: string[];
651
+ }
652
+ declare const formatOf: (file: string) => OutFormat;
653
+ /** A card option to a card, or nothing. Exported for tests. */
654
+ declare function cardOf(v: boolean | string | CardOptions | undefined, fallback: CardOptions): CardOptions | undefined;
655
+ declare function render(o: RenderOptions): Promise<RenderResult>;
656
+ /** From a capture to files. Exported for tests (a capture can be made up). */
657
+ declare function finish(cap: Capture, outs: Array<OutSpec & {
658
+ format: OutFormat;
659
+ }>, o?: FinishOptions): Promise<RenderResult>;
660
+
661
+ /**
662
+ * GIF encoding with gifenc (pure JS, no binaries).
663
+ *
664
+ * UI frames change little from one to the next, so: one palette for the whole GIF (from a sample of
665
+ * frames), identical frames merged into one longer frame, and every later frame writes only what
666
+ * changed (unchanged pixels are transparent and the frame below shows through).
667
+ */
668
+
669
+ interface GifOptions {
670
+ fps: number;
671
+ /** 0 = loop forever (default), -1 = play once. */
672
+ repeat?: number;
673
+ /** Frames sampled for the palette. Default 12. */
674
+ paletteSamples?: number;
675
+ }
676
+ /** Build one palette from evenly spaced frames (every 3rd pixel of each). Exported for tests. */
677
+ declare function paletteOf(frames: readonly Image[], samples?: number): number[][];
678
+ interface GifResult {
679
+ bytes: Uint8Array;
680
+ frames: number;
681
+ durationMs: number;
682
+ }
683
+ /** Encode frames shown at a steady fps. */
684
+ declare function encodeGif(frames: readonly Image[], o: GifOptions): GifResult;
685
+ interface GifWriter {
686
+ /** The next frame (same size as the first); it can be reused by the caller once this returns. */
687
+ add(frame: Image): void;
688
+ finish(): GifResult;
689
+ }
690
+ /**
691
+ * A GIF written one frame at a time, so a long video never holds all its frames: the palette comes first
692
+ * (from sample frames, paletteOf), identical frames in a row are merged, later frames hold only changes.
693
+ */
694
+ declare function createGifWriter(o: {
695
+ width: number;
696
+ height: number;
697
+ fps: number;
698
+ palette: number[][];
699
+ repeat?: number;
700
+ }): GifWriter;
701
+
702
+ /**
703
+ * MP4 (H.264) through the system ffmpeg: composed RGBA frames are piped in at a steady fps.
704
+ * There is no bundled ffmpeg; without one on the PATH (or FFMPEG), MP4 output fails with a clear message.
705
+ */
706
+ /** The ffmpeg to use, or null. `FFMPEG` overrides the PATH. */
707
+ declare function findFfmpeg(env?: NodeJS.ProcessEnv): string | null;
708
+ /**
709
+ * The ffmpeg arguments for raw RGBA frames of width×height piped in (the renderer composes them), and an
710
+ * optional audio track (a WAV as long as the video). Exported for tests.
711
+ */
712
+ declare function mp4Args(file: string, fps: number, size: {
713
+ width: number;
714
+ height: number;
715
+ }, audio?: string): string[];
716
+ /** Write RGBA frames (one per output frame, even width and height) to an MP4. */
717
+ declare function encodeMp4(frames: Iterable<Uint8Array>, o: {
718
+ file: string;
719
+ fps: number;
720
+ width: number;
721
+ height: number;
722
+ ffmpeg?: string;
723
+ audio?: string;
724
+ }): Promise<void>;
725
+
726
+ /**
727
+ * Putting an output frame together: the background (and window) first, then the camera's view of the
728
+ * capture into the content area, then overlays such as a burned-in caption. PURE.
729
+ */
730
+
731
+ /** Draw `src`'s region `from` into `dst`'s region `to`: area-averaged when shrinking, bilinear when growing. */
732
+ declare function drawRegion(dst: Image, to: Rect, src: Image, from: Rect): void;
733
+ /** Alpha-blend `img` onto `dst` at (x, y), its own alpha times `alpha`. */
734
+ declare function overlay(dst: Image, img: Image, x: number, y: number, alpha?: number): void;
735
+ /** A mix of two same-size frames (u = 0: a, 1: b). */
736
+ declare function crossfade(a: Image, b: Image, u: number): Image;
737
+ declare const blank: (width: number, height: number, rgb?: [number, number, number]) => Image;
738
+
739
+ /**
740
+ * From the captured events to what the composer needs, on the edited (output) timeline: the camera's
741
+ * actions, the caption cues, and which page is showing. PURE.
742
+ */
743
+
744
+ /**
745
+ * Camera actions: each step with an element, at its centre (in capture pixels: CSS px × scale). A page
746
+ * change is an action too (not a zoomable one), so a shot never spans two pages.
747
+ */
748
+ declare function actionsOf(events: readonly TimelineEvent[], segs: readonly Segment[], scale?: number): Action[];
749
+ /**
750
+ * Caption cues as the player shows them: a step's words from the step before it (while the cursor
751
+ * travels) until just after it acts. Cues never overlap; each lasts at least `minMs` where there's room.
752
+ */
753
+ declare function stepCues(events: readonly TimelineEvent[], segs: readonly Segment[], endMs: number, o?: {
754
+ afterMs?: number;
755
+ minMs?: number;
756
+ }): Cue[];
757
+ /** The page path showing at a source time (the last event's page at or before it). */
758
+ declare function pageAt(events: readonly TimelineEvent[]): (src: number) => string;
759
+ /** The cue showing at output time t, and how opaque (fading in and out over `fadeMs`). */
760
+ declare function cueAt(cues: readonly Cue[], t: number, fadeMs?: number): {
761
+ cue: Cue;
762
+ alpha: number;
763
+ } | null;
764
+
765
+ /**
766
+ * --repair: when a step can't find its element, look at the page as it is now, choose what the step means
767
+ * (code first, the AI only when unsure), re-record that element as the step's target, and play the guide
768
+ * again with the fix (in memory) to see that it gets past the step. A wait whose text never showed is fixed
769
+ * the same way: the texts on the page (and those that showed while it waited) are scored, and the chosen one
770
+ * becomes what the step waits for. Up to `maxStalls` stalls in one run.
771
+ *
772
+ * Nothing is written to the trace: the fixes are suggestions in a file that `apply` takes once a person agrees.
773
+ */
774
+
775
+ type Trace = Parameters<typeof applyRaw>[0];
776
+ /** `by: 'guess'`: a wait's text that was not a clear winner (the best that scored well, or what showed after the action), kept only when the replay passes. */
777
+ interface RepairSuggestion extends Suggestion {
778
+ id: number;
779
+ by: 'score' | 'ai' | 'guess';
780
+ score?: number;
781
+ }
782
+ interface Unresolved {
783
+ index: number;
784
+ reason: string;
785
+ why: string;
786
+ /** The best candidates by score, for a person to pick from: elements, or (for a wait) texts. */
787
+ top: Array<(Omit<Candidate, 'key'> | Omit<TextCandidate, 'id'>) & {
788
+ score: number;
789
+ }>;
790
+ }
791
+ interface RepairOutcome {
792
+ suggestions: RepairSuggestion[];
793
+ unresolved: Unresolved[];
794
+ /** The guide played to the end with every suggestion in. */
795
+ passed: boolean;
796
+ }
797
+ interface Found {
798
+ chosen?: {
799
+ target: NonNullable<Suggestion['target']>;
800
+ by: 'score' | 'ai';
801
+ score?: number;
802
+ why?: string;
803
+ };
804
+ /** For a wait: the text to wait for now. */
805
+ text?: {
806
+ value: string;
807
+ by: 'score' | 'ai' | 'guess';
808
+ score?: number;
809
+ why?: string;
810
+ };
811
+ why?: string;
812
+ top: Unresolved['top'];
813
+ }
814
+ /** The repair script that ships next to the player (trace-avatar ≥ 0.1.7). */
815
+ declare function repairScriptOf(playerFile: string): string;
816
+ /** What onStall does: candidates on the live page, a choice, the chosen element re-recorded and checked. */
817
+ declare function stallInspector(o: {
818
+ script: string;
819
+ trace: () => Trace;
820
+ ai?: Ai;
821
+ vision?: boolean;
822
+ skip?: string[];
823
+ }): (page: Page, stall: {
824
+ index: number;
825
+ reason: string;
826
+ }) => Promise<Found>;
827
+ /**
828
+ * Repair a guide: each stall is fixed in memory and the guide played again, until it ends, a stall can't be
829
+ * fixed, or `maxStalls` is reached. `first` is a stall already met (with onStall data) to start from.
830
+ */
831
+ declare function repairGuide(o: {
832
+ trace: Trace;
833
+ capture: Omit<CaptureOptions, 'trace' | 'onStall' | 'allowStall'>;
834
+ ai?: Ai;
835
+ vision?: boolean;
836
+ maxStalls?: number;
837
+ first?: RenderError;
838
+ }): Promise<RepairOutcome>;
839
+
840
+ export { type Action, type CameraOptions, type Capture, type CaptureOptions, type CapturedFrame, type CardOptions, type Cue, DEFAULT_BACKGROUND, DEFAULT_MAX_WAIT_MS, type EditOptions, type FinishOptions, type FrameStyle, GEMINI_TTS, type GifOptions, type GifResult, type GifWriter, type Image, type Layers, type Layout, type NarrationPlan, type OutFormat, type OutSpec, type Pcm, type Phase, type PlanOptions, type PlannedLine, type Rect, RenderError, type RenderOptions, type RenderOutput, type RenderResult, type RepairOutcome, type RepairSuggestion, type Script, type Segment, type Span, TRACK_RATE, type TimelineEvent, type Unresolved, type Voice, ZOOM_KINDS, actionsOf, blank, cached, cameraKeys, cameraPath, captionCues, capture, cardOf, chapterCues, createGifWriter, createLayers, crop, crossfade, cueAt, drawRegion, durationOf, editList, encodeGif, encodeMp4, findFfmpeg, findPlayer, finish, fitWidth, formatOf, frameTimes, fromS16le, fromWav, geminiVoice, layoutOf, linesOf, mix, mp4Args, msOf, narrationText, openAiVoice, outputAt, overlay, pageAt, paletteOf, parseScript, pickFrames, pixel, planNarration, providerOf, render, repairGuide, repairScriptOf, resample, resize, runQa, sayVoice, sourceAt, spansOf, stallInspector, stepCues, suggestScript, toVtt, toWav, trimSilence, voiceOf, withHolds };