@bitmagic/cli 0.1.61-dev.0 → 0.1.61-dev.2

package/dist/trailer/client.js

@@ -0,0 +1,133 @@
+/**
+ * The two api-server calls behind `bitmagic trailer publish`: mint a signed PUT for the video,
+ * and attach the uploaded URL to the game page's gallery.
+ *
+ * Status mapping is this module's own, for the reason `http/signed-upload.ts` gives: `client.ts`'s
+ * `request()` reads every 403 as a Bitmagic Pro refusal, and on these routes a 403 is more often
+ * "not your game" or "this game is banned" — sending that creator to `bitmagic subscribe` would
+ * point them somewhere that cannot help. The one status these routes add is 409 `media_full`: the
+ * page's gallery is capped at twelve items, and the creator has to make room, or let the CLI swap
+ * the previous trailer out (which it does by itself on a re-run, through `replaceUrl`).
+ */
+import { CliError } from '../errors.js';
+import { proRefusal } from '../http/client.js';
+import { isJsonObject } from '../project/world-json.js';
+import { apiServerHeaders } from '../telemetry/request-headers.js';
+export const TRAILER_UPLOAD_URL_PATH = '/api/cli/v1/trailer/upload-url';
+export const TRAILER_ATTACH_PATH = '/api/cli/v1/trailer/attach';
+/** The gallery cap api-server enforces (`MAX_MEDIA_ITEMS` in game-page-edit-rules.ts). */
+export const MAX_GALLERY_ITEMS = 12;
+async function readJsonBody(response) {
+    try {
+        const parsed = await response.json();
+        return isJsonObject(parsed) ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+async function callApi(environment, path, method, accessToken, body, deps) {
+    try {
+        return await deps.fetch(`${environment.apiUrl}${path}`, {
+            method,
+            headers: {
+                ...apiServerHeaders(),
+                Authorization: `Bearer ${accessToken}`,
+                'Content-Type': 'application/json',
+                Accept: 'application/json',
+            },
+            body: JSON.stringify(body),
+        });
+    }
+    catch {
+        throw new CliError(`Cannot reach api-server at ${environment.apiUrl}.`, 1, 'unreachable');
+    }
+}
+/**
+ * The refusal an error status stands for, shared by both calls so they cannot drift on what a
+ * 403 or a 404 means. `what` names the step for the 400 and generic messages.
+ */
+async function refusal(response, environment, path, gameId, what) {
+    if (response.status === 401) {
+        return new CliError('Your session has expired. Run `bitmagic login`.', 1, 'session_expired');
+    }
+    if (response.status === 403) {
+        // Three refusals share the status: the Pro gate on every /api/cli/v1 route (which carries a
+        // `code`), the route's own ownership check, and a banned game.
+        const clone = response.clone();
+        const parsed = await readJsonBody(response);
+        if (parsed.code === 'pro_expired' || parsed.code === 'pro_required') {
+            const pro = await proRefusal(clone);
+            return new CliError(pro.message, 1, pro.code);
+        }
+        if (parsed.error === 'Game is banned') {
+            const reason = typeof parsed.banReason === 'string' && parsed.banReason !== '' ? ` (${parsed.banReason})` : '';
+            return new CliError(`Game "${gameId}" is banned${reason}, so its page cannot be changed until an admin lifts the ban.`, 1, 'banned');
+        }
+        return new CliError(`You do not own game "${gameId}", so ${what} is not allowed. Check the gameId in bitmagic.json.`, 1, 'not_owner');
+    }
+    if (response.status === 404) {
+        return new CliError(`Game "${gameId}" does not exist in the "${environment.name}" environment. Check the gameId in `
+            + 'bitmagic.json, or run `bitmagic init` to create a game there.', 1, 'not_found');
+    }
+    if (response.status === 400) {
+        const parsed = await readJsonBody(response);
+        const message = typeof parsed.error === 'string' ? parsed.error : `api-server rejected ${what}.`;
+        return new CliError(`api-server refused ${what}: ${message}`);
+    }
+    if (response.status === 503) {
+        return new CliError(`api-server reported media uploads are unavailable in the "${environment.name}" environment.`, 1, 'unavailable');
+    }
+    return new CliError(`api-server returned HTTP ${response.status} for ${path}.`, 1, 'http_error');
+}
+/**
+ * Ask api-server for a signed PUT under `game-media/<gameId>/`. Ownership and the video-only rule
+ * are checked there before anything is minted, so a refusal here has cost nothing.
+ */
+export async function mintTrailerUploadUrl(environment, accessToken, body, deps) {
+    const response = await callApi(environment, TRAILER_UPLOAD_URL_PATH, 'POST', accessToken, body, deps);
+    if (!response.ok) {
+        throw await refusal(response, environment, TRAILER_UPLOAD_URL_PATH, body.gameId, 'the trailer upload');
+    }
+    const parsed = await readJsonBody(response);
+    if (typeof parsed.uploadUrl !== 'string' || typeof parsed.publicUrl !== 'string') {
+        throw new CliError('api-server minted an upload URL this CLI cannot read — is it newer than this CLI?');
+    }
+    return {
+        uploadUrl: parsed.uploadUrl,
+        publicUrl: parsed.publicUrl,
+        path: typeof parsed.path === 'string' ? parsed.path : '',
+        maxBytes: typeof parsed.maxBytes === 'number' ? parsed.maxBytes : 0,
+        // The server echoes it; fall back to what was asked for against an older api-server.
+        contentType: typeof parsed.contentType === 'string' ? parsed.contentType : body.contentType,
+    };
+}
+/**
+ * Put the uploaded video at the front of the game page's gallery. api-server drops any item already
+ * pointing at `url` or at `replaceUrl`, so re-running replaces the previous trailer rather than
+ * stacking a new one beside it.
+ */
+export async function attachTrailer(environment, accessToken, body, deps, hints = {}) {
+    const response = await callApi(environment, TRAILER_ATTACH_PATH, 'PUT', accessToken, body, deps);
+    if (response.status === 409) {
+        const parsed = await readJsonBody(response);
+        const max = typeof parsed.max === 'number' ? parsed.max : MAX_GALLERY_ITEMS;
+        const where = hints.manageUrl ? `on ${hints.manageUrl}` : 'on the My games page';
+        throw new CliError(`The game page already holds ${max} media items — remove one ${where} or re-run to replace the `
+            + 'previous trailer.', 1, 'media_full');
+    }
+    if (!response.ok) {
+        throw await refusal(response, environment, TRAILER_ATTACH_PATH, body.gameId, 'attaching the trailer');
+    }
+    const parsed = await readJsonBody(response);
+    if (typeof parsed.pageUrl !== 'string') {
+        throw new CliError('api-server attached the trailer but answered in a shape this CLI cannot read — is it newer than this CLI?');
+    }
+    return {
+        media: Array.isArray(parsed.media) ? parsed.media : [],
+        pageUrl: parsed.pageUrl,
+        isPublic: parsed.isPublic === true,
+        published: parsed.published === true,
+    };
+}
+//# sourceMappingURL=client.js.map

package/dist/trailer/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/trailer/client.ts"],"names":[],"mappings":"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"}

package/dist/trailer/edl-time.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Pure EDL time mapping: source frames -> output-timeline seconds.
+ *
+ * Crossfades OVERLAP the previous clip, so every clip after a crossfade
+ * starts (and ends) earlier on the output timeline than a cut-only chain
+ * would place it. All render math (xfade offsets, sound delays, total
+ * duration) derives from this module so it can be unit-tested without ffmpeg.
+ */
+import type { EdlClip, TimelineSound } from './timeline-types.js';
+export declare const DEFAULT_CROSSFADE_SEC = 0.25;
+export declare const DEFAULT_TAIL_PAD_FRAMES = 30;
+export declare const MIN_SPEED = 0.25;
+export declare const MAX_SPEED = 2;
+export interface ClipTiming {
+    index: number;
+    in: number;
+    out: number;
+    speed: number;
+    /** Resolved transition INTO this clip; first clip is always 'cut'. */
+    transition: 'cut' | 'crossfade';
+    /** Seconds; 0 for cuts. Also the xfade offset shortfall vs a plain concat. */
+    transitionDuration: number;
+    /** Seconds on the output timeline where this clip's first frame lands. */
+    outputStart: number;
+    /** Seconds this clip occupies on the output timeline (source frames / fps / speed). */
+    outputDuration: number;
+    label?: string;
+    /** Per-clip UI-overlay override; undefined means "follow the global --ui flag". */
+    ui?: boolean;
+}
+export interface ClipTimelineResult {
+    timings: ClipTiming[];
+    totalDuration: number;
+    warnings: string[];
+}
+export declare function computeClipTimeline(clips: EdlClip[], fps: number): ClipTimelineResult;
+/**
+ * Output-timeline seconds where a source frame inside `timing` lands. Frames
+ * before the clip's first frame (sound tail pad) clamp to the clip start.
+ */
+export declare function sourceFrameToOutputSec(timing: ClipTiming, sourceFrame: number, fps: number): number;
+/**
+ * Output time at which a clip stops being the only source on screen. A
+ * crossfade INTO the next clip begins at that clip's outputStart — before this
+ * clip's last frame — so anything that must not double up (UI overlays) hands
+ * over there rather than at this clip's own end.
+ */
+export declare function exclusiveOutputEnd(timings: readonly ClipTiming[], index: number): number;
+export interface PlacedSound {
+    sound: TimelineSound;
+    clipIndex: number;
+    /** Seconds on the output timeline where this sound instance starts. */
+    outputTimeSec: number;
+}
+/**
+ * Place timeline sounds onto the output timeline. A clip picks up sounds with
+ * frame in [in - tailPadFrames, out); sounds from the tail pad (before the
+ * clip's first frame) clamp to the clip's output start. The same sound can be
+ * placed once per clip whose source range covers it.
+ */
+export declare function placeSounds(timings: ClipTiming[], sounds: TimelineSound[], fps: number, tailPadFrames?: number): PlacedSound[];

package/dist/trailer/edl-time.js

@@ -0,0 +1,105 @@
+import { CliError } from '../errors.js';
+export const DEFAULT_CROSSFADE_SEC = 0.25;
+export const DEFAULT_TAIL_PAD_FRAMES = 30;
+export const MIN_SPEED = 0.25;
+export const MAX_SPEED = 2.0;
+export function computeClipTimeline(clips, fps) {
+    if (clips.length === 0)
+        throw new CliError('EDL has no clips');
+    if (!Number.isFinite(fps) || fps <= 0)
+        throw new Error(`invalid fps: ${fps}`);
+    const warnings = [];
+    const timings = [];
+    let cursor = 0; // output-timeline end of the previous clip
+    clips.forEach((clip, index) => {
+        if (!Number.isInteger(clip.in) || !Number.isInteger(clip.out) || clip.in < 0 || clip.out <= clip.in) {
+            throw new Error(`clip ${index}: invalid frame range in=${clip.in} out=${clip.out}`);
+        }
+        let speed = clip.speed ?? 1;
+        if (speed < MIN_SPEED || speed > MAX_SPEED) {
+            const clamped = Math.min(MAX_SPEED, Math.max(MIN_SPEED, speed));
+            warnings.push(`clip ${index}: speed ${speed} outside [${MIN_SPEED}, ${MAX_SPEED}], clamped to ${clamped}`);
+            speed = clamped;
+        }
+        const outputDuration = (clip.out - clip.in) / fps / speed;
+        let transition = 'cut';
+        let transitionDuration = 0;
+        if (index === 0) {
+            if (clip.transition === 'crossfade')
+                warnings.push('clip 0: transition on the first clip is ignored');
+        }
+        else if (clip.transition === 'crossfade') {
+            transition = 'crossfade';
+            transitionDuration = clip.transitionDuration ?? DEFAULT_CROSSFADE_SEC;
+            if (transitionDuration <= 0) {
+                warnings.push(`clip ${index}: non-positive transitionDuration ${transitionDuration}, treating as cut`);
+                transition = 'cut';
+                transitionDuration = 0;
+            }
+            else {
+                const maxFade = Math.min(timings[index - 1].outputDuration, outputDuration);
+                if (transitionDuration > maxFade) {
+                    warnings.push(`clip ${index}: transitionDuration ${transitionDuration} longer than an adjacent clip, clamped to ${maxFade}`);
+                    transitionDuration = maxFade;
+                }
+            }
+        }
+        const outputStart = index === 0 ? 0 : cursor - transitionDuration;
+        const timing = {
+            index,
+            in: clip.in,
+            out: clip.out,
+            speed,
+            transition,
+            transitionDuration,
+            outputStart,
+            outputDuration
+        };
+        if (clip.label !== undefined)
+            timing.label = clip.label;
+        if (clip.ui !== undefined)
+            timing.ui = clip.ui;
+        timings.push(timing);
+        cursor = outputStart + outputDuration;
+    });
+    return { timings, totalDuration: cursor, warnings };
+}
+/**
+ * Output-timeline seconds where a source frame inside `timing` lands. Frames
+ * before the clip's first frame (sound tail pad) clamp to the clip start.
+ */
+export function sourceFrameToOutputSec(timing, sourceFrame, fps) {
+    return timing.outputStart + Math.max(0, sourceFrame - timing.in) / fps / timing.speed;
+}
+/**
+ * Output time at which a clip stops being the only source on screen. A
+ * crossfade INTO the next clip begins at that clip's outputStart — before this
+ * clip's last frame — so anything that must not double up (UI overlays) hands
+ * over there rather than at this clip's own end.
+ */
+export function exclusiveOutputEnd(timings, index) {
+    const timing = timings[index];
+    const ownEnd = timing.outputStart + timing.outputDuration;
+    const next = timings[index + 1];
+    return next === undefined ? ownEnd : Math.min(ownEnd, next.outputStart);
+}
+/**
+ * Place timeline sounds onto the output timeline. A clip picks up sounds with
+ * frame in [in - tailPadFrames, out); sounds from the tail pad (before the
+ * clip's first frame) clamp to the clip's output start. The same sound can be
+ * placed once per clip whose source range covers it.
+ */
+export function placeSounds(timings, sounds, fps, tailPadFrames = DEFAULT_TAIL_PAD_FRAMES) {
+    const placements = [];
+    for (const timing of timings) {
+        for (const sound of sounds) {
+            if (sound.frame < timing.in - tailPadFrames || sound.frame >= timing.out)
+                continue;
+            const outputTimeSec = sourceFrameToOutputSec(timing, sound.frame, fps);
+            placements.push({ sound, clipIndex: timing.index, outputTimeSec });
+        }
+    }
+    placements.sort((a, b) => a.outputTimeSec - b.outputTimeSec);
+    return placements;
+}
+//# sourceMappingURL=edl-time.js.map

package/dist/trailer/edl-time.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"edl-time.js","sourceRoot":"","sources":["../../src/trailer/edl-time.ts"],"names":[],"mappings":"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"}

package/dist/trailer/ffmpeg.d.ts

@@ -0,0 +1,8 @@
+export type FfmpegTool = 'ffmpeg' | 'ffprobe';
+export declare function missingFfmpegMessage(tool?: FfmpegTool): string;
+/**
+ * Refuse up front when a tool is missing, before any frames are read or sparks spent. `spawnSync`
+ * with `-version` is the cheapest probe that also proves the binary actually runs.
+ */
+export declare function ensureFfmpeg(tools?: readonly FfmpegTool[]): void;
+export declare function runFfmpeg(args: string[]): Promise<void>;

package/dist/trailer/ffmpeg.js

@@ -0,0 +1,55 @@
+/**
+ * Thin ffmpeg process wrapper. Always argument arrays, never shell strings.
+ *
+ * ffmpeg is the one external tool the trailer lane needs and the one a creator's machine is least
+ * likely to have, so its absence is reported as a sentence with the install command rather than as
+ * an ENOENT stack trace from deep inside a filtergraph.
+ */
+import { spawn, spawnSync } from 'child_process';
+import { CliError, errnoCode } from '../errors.js';
+const STDERR_KEEP_BYTES = 65536;
+const STDERR_REPORT_LINES = 30;
+export function missingFfmpegMessage(tool = 'ffmpeg') {
+    return (`${tool} was not found on PATH. \`bitmagic trailer\` cuts and encodes with ffmpeg (and ffprobe) — ` +
+        'install it (macOS: brew install ffmpeg · Debian/Ubuntu: sudo apt install ffmpeg · ' +
+        'Windows: winget install Gyan.FFmpeg) and run the command again.');
+}
+/**
+ * Refuse up front when a tool is missing, before any frames are read or sparks spent. `spawnSync`
+ * with `-version` is the cheapest probe that also proves the binary actually runs.
+ */
+export function ensureFfmpeg(tools = ['ffmpeg']) {
+    for (const tool of tools) {
+        const probe = spawnSync(tool, ['-version'], { stdio: 'ignore' });
+        if (probe.error !== undefined && errnoCode(probe.error) === 'ENOENT') {
+            throw new CliError(missingFfmpegMessage(tool), 1, 'ffmpeg_missing');
+        }
+    }
+}
+export async function runFfmpeg(args) {
+    return new Promise((resolve, reject) => {
+        const child = spawn('ffmpeg', args, { stdio: ['ignore', 'ignore', 'pipe'] });
+        let stderr = '';
+        child.stderr.on('data', (chunk) => {
+            stderr += chunk.toString('utf-8');
+            if (stderr.length > STDERR_KEEP_BYTES)
+                stderr = stderr.slice(-STDERR_KEEP_BYTES / 2);
+        });
+        child.on('error', (err) => {
+            if (errnoCode(err) === 'ENOENT')
+                reject(new CliError(missingFfmpegMessage('ffmpeg'), 1, 'ffmpeg_missing'));
+            else
+                reject(new Error(`failed to start ffmpeg: ${err.message}`));
+        });
+        child.on('close', (code) => {
+            if (code === 0) {
+                resolve();
+            }
+            else {
+                const tail = stderr.trim().split('\n').slice(-STDERR_REPORT_LINES).join('\n');
+                reject(new CliError(`ffmpeg exited with code ${code}:\n${tail}`));
+            }
+        });
+    });
+}
+//# sourceMappingURL=ffmpeg.js.map

package/dist/trailer/ffmpeg.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ffmpeg.js","sourceRoot":"","sources":["../../src/trailer/ffmpeg.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEnD,MAAM,iBAAiB,GAAG,KAAK,CAAC;AAChC,MAAM,mBAAmB,GAAG,EAAE,CAAC;AAI/B,MAAM,UAAU,oBAAoB,CAAC,OAAmB,QAAQ;IAC9D,OAAO,CACL,GAAG,IAAI,4FAA4F;QACnG,oFAAoF;QACpF,iEAAiE,CAClE,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,QAA+B,CAAC,QAAQ,CAAC;IACpE,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,KAAK,GAAG,SAAS,CAAC,IAAI,EAAE,CAAC,UAAU,CAAC,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC;QACjE,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS,IAAI,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,QAAQ,EAAE,CAAC;YACrE,MAAM,IAAI,QAAQ,CAAC,oBAAoB,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,gBAAgB,CAAC,CAAC;QACtE,CAAC;IACH,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,IAAc;IAC5C,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,KAAK,GAAG,KAAK,CAAC,QAAQ,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;QAC7E,IAAI,MAAM,GAAG,EAAE,CAAC;QAChB,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE;YACxC,MAAM,IAAI,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;YAClC,IAAI,MAAM,CAAC,MAAM,GAAG,iBAAiB;gBAAE,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,iBAAiB,GAAG,CAAC,CAAC,CAAC;QACvF,CAAC,CAAC,CAAC;QACH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE;YACxB,IAAI,SAAS,CAAC,GAAG,CAAC,KAAK,QAAQ;gBAAE,MAAM,CAAC,IAAI,QAAQ,CAAC,oBAAoB,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,gBAAgB,CAAC,CAAC,CAAC;;gBACtG,MAAM,CAAC,IAAI,KAAK,CAAC,2BAA2B,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;QACnE,CAAC,CAAC,CAAC;QACH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE;YACzB,IAAI,IAAI,KAAK,CAAC,EAAE,CAAC;gBACf,OAAO,EAAE,CAAC;YACZ,CAAC;iBAAM,CAAC;gBACN,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,mBAAmB,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBAC9E,MAAM,CAAC,IAAI,QAAQ,CAAC,2BAA2B,IAAI,MAAM,IAAI,EAAE,CAAC,CAAC,CAAC;YACpE,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/trailer/hud-raster.d.ts

@@ -0,0 +1,28 @@
+import { type Browser } from 'playwright-core';
+import type { UiKeyframe } from './hud-state.js';
+export declare const CHROME_MISSING_HINT = "Google Chrome could not be launched \u2014 install it from https://www.google.com/chrome/";
+/** Headless system Chrome for offscreen rasterization; null (with a warning) when it cannot start. */
+export declare function launchRasterBrowser(purpose: string): Promise<Browser | null>;
+export interface RasterizeOptions {
+    harnessUrl: string;
+    /** Overlay PNGs are written here as ui_NNNN.png, one per keyframe. */
+    outDir: string;
+    /** Recording resolution — both the browser viewport and the HUD root size. */
+    width: number;
+    height: number;
+}
+export declare function uiPngPath(outDir: string, index: number): string;
+/**
+ * Render one transparent PNG per keyframe, reusing a single browser + page.
+ * Returns paths in keyframe order, or null when UI overlays must be skipped
+ * (no Chrome, harness unreachable, or the harness rejected a state).
+ */
+export declare function rasterizeUiKeyframes(keyframes: readonly UiKeyframe[], options: RasterizeOptions): Promise<string[] | null>;
+/**
+ * Width/height straight out of a PNG's IHDR chunk, so the filtergraph only
+ * pays for a scale filter when the overlay really is the wrong size.
+ */
+export declare function readPngSize(filePath: string): {
+    width: number;
+    height: number;
+} | null;

package/dist/trailer/hud-raster.js

@@ -0,0 +1,114 @@
+/**
+ * Rasterize replay states into transparent PNG overlays with headless Chrome.
+ *
+ * The harness page (`/hud-replay.html` on the running `bitmagic dev` sidecar) owns a real GameHUD,
+ * so the overlay is the game's own UI rather than a reimplementation. Contract:
+ *   window.__hudReplayReady === true      when the page can accept states
+ *   window.__hudReplay.render(state)      synchronous; applies a replay state
+ *   window.__hudReplay.setViewport(w, h)  sizes the HUD root
+ * plus a transparent page background, so `omitBackground` yields real alpha.
+ *
+ * Every failure path here degrades to "no overlays" (returns null) instead of failing the trailer:
+ * a UI-less video still beats no video. Chrome is the creator's installed browser
+ * (`channel: 'chrome'`), the same one `bitmagic verify` drives — nothing is downloaded.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { chromium } from 'playwright-core';
+import { out, warn } from './io.js';
+const NAV_TIMEOUT_MS = 20000;
+const READY_TIMEOUT_MS = 20000;
+export const CHROME_MISSING_HINT = 'Google Chrome could not be launched — install it from https://www.google.com/chrome/';
+/**
+ * The state is embedded in the expression rather than passed as an argument:
+ * Playwright treats a string pageFunction as a plain expression and drops the
+ * arg, so an IIFE is the reliable form.
+ */
+function applyStateExpression(state, width, height) {
+    return ('(() => {' +
+        ' const replay = window.__hudReplay;' +
+        ' if (!replay || typeof replay.render !== "function") throw new Error("window.__hudReplay.render is missing");' +
+        ' if (typeof replay.setViewport === "function") replay.setViewport(' +
+        `${JSON.stringify(width)}, ${JSON.stringify(height)});` +
+        ` replay.render(${JSON.stringify(state)});` +
+        ' return true;' +
+        '})()');
+}
+/** Headless system Chrome for offscreen rasterization; null (with a warning) when it cannot start. */
+export async function launchRasterBrowser(purpose) {
+    try {
+        return await chromium.launch({ headless: true, channel: 'chrome', args: ['--mute-audio'] });
+    }
+    catch (err) {
+        warn(`${purpose}: ${CHROME_MISSING_HINT} (${err instanceof Error ? err.message.split('\n')[0] : String(err)})`);
+        return null;
+    }
+}
+export function uiPngPath(outDir, index) {
+    return path.join(outDir, `ui_${String(index).padStart(4, '0')}.png`);
+}
+/**
+ * Render one transparent PNG per keyframe, reusing a single browser + page.
+ * Returns paths in keyframe order, or null when UI overlays must be skipped
+ * (no Chrome, harness unreachable, or the harness rejected a state).
+ */
+export async function rasterizeUiKeyframes(keyframes, options) {
+    if (keyframes.length === 0)
+        return [];
+    const browser = await launchRasterBrowser('ui');
+    if (browser === null) {
+        warn('ui: rendering without HUD overlays');
+        return null;
+    }
+    fs.mkdirSync(options.outDir, { recursive: true });
+    try {
+        const context = await browser.newContext({
+            viewport: { width: options.width, height: options.height },
+            deviceScaleFactor: 1
+        });
+        const page = await context.newPage();
+        await page.goto(options.harnessUrl, { waitUntil: 'domcontentloaded', timeout: NAV_TIMEOUT_MS });
+        await page.waitForFunction('window.__hudReplayReady === true', undefined, { timeout: READY_TIMEOUT_MS });
+        const paths = [];
+        for (let i = 0; i < keyframes.length; i++) {
+            const pngPath = uiPngPath(options.outDir, i);
+            await page.evaluate(applyStateExpression(keyframes[i].state, options.width, options.height));
+            await page.screenshot({ path: pngPath, omitBackground: true, type: 'png' });
+            paths.push(pngPath);
+        }
+        out(`ui: rasterized ${paths.length} overlay(s) at ${options.width}x${options.height} from ${options.harnessUrl}`);
+        return paths;
+    }
+    catch (err) {
+        warn(`ui: overlay rasterization failed against ${options.harnessUrl} ` +
+            `(${err instanceof Error ? err.message : String(err)}) — rendering without UI`);
+        return null;
+    }
+    finally {
+        try {
+            await browser.close();
+        }
+        catch (err) {
+            warn(`ui: browser close failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+}
+/**
+ * Width/height straight out of a PNG's IHDR chunk, so the filtergraph only
+ * pays for a scale filter when the overlay really is the wrong size.
+ */
+export function readPngSize(filePath) {
+    const header = Buffer.alloc(24);
+    const fd = fs.openSync(filePath, 'r');
+    try {
+        if (fs.readSync(fd, header, 0, 24, 0) < 24)
+            return null;
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    if (header.readUInt32BE(0) !== 0x89504e47 || header.toString('ascii', 12, 16) !== 'IHDR')
+        return null;
+    return { width: header.readUInt32BE(16), height: header.readUInt32BE(20) };
+}
+//# sourceMappingURL=hud-raster.js.map

package/dist/trailer/hud-raster.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hud-raster.js","sourceRoot":"","sources":["../../src/trailer/hud-raster.ts"],"names":[],"mappings":"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"}

package/dist/trailer/hud-state.d.ts

@@ -0,0 +1,110 @@
+/**
+ * HUD replay: turn the recorded `hud[]` op track back into UI state.
+ *
+ * Captured frames are UI-less (the HUD is DOM, not WebGL), so the engine logs
+ * semantic HUD *state changes* instead of pixels. This module reduces that
+ * sparse op stream back to the complete UI state at any source frame
+ * (`reduceHudState`), and picks the frames worth rasterizing per EDL clip
+ * (`collectUiKeyframes`). Output-timeline placement comes from edl-time.ts —
+ * this file never re-derives crossfade/speed math.
+ *
+ * Timers are the one derived value: they are logged as start/pause/reset ops,
+ * never per tick, and the displayed value is computed from FRAME time (which
+ * is more correct than the widget's wall clock under a dilated recording).
+ */
+import type { ClipTiming } from './edl-time.js';
+import type { HudElementKind, HudOp } from './timeline-types.js';
+/**
+ * Engine-owned chrome that lives in the HUD element registry but must never
+ * reach a trailer: interactive controls the viewer can't click in a video.
+ * `mute-button` is `MuteControl`'s custom element (engine/ui/MuteControl.ts).
+ */
+export declare const CHROME_ELEMENT_IDS: ReadonlySet<string>;
+export interface HudHealthState {
+    current: number;
+    max: number;
+    visible: boolean;
+}
+/**
+ * One HUD element. Keys beyond id/type/anchor/visible are per-kind and are
+ * omitted when the recording never set them.
+ */
+export interface HudElementState {
+    id: string;
+    type: HudElementKind;
+    anchor: string;
+    visible: boolean;
+    label?: string;
+    color?: string;
+    width?: number;
+    showText?: boolean;
+    percent?: number;
+    icon?: string;
+    text?: string;
+    iconSize?: number;
+    /** Timer only: the DERIVED displayed seconds; the harness formats it. */
+    seconds?: number;
+    countDown?: boolean;
+    format?: string;
+    html?: string;
+    css?: string;
+}
+export interface HudToastState {
+    message: string;
+    variant?: string;
+}
+export interface HudReplayState {
+    version: 1;
+    hudVisible: boolean;
+    /** null until the recording touches health at all. */
+    health: HudHealthState | null;
+    /** Verbatim from the `theme` op; null when the recording carried none. */
+    theme: unknown;
+    /** Creation order (= stacking order within an anchor); removed ones dropped. */
+    elements: HudElementState[];
+    toasts: HudToastState[];
+}
+/** The engine records `frame` on a 60fps source clock. */
+export declare const DEFAULT_HUD_FPS = 60;
+/** IGameHUD.showToast's default duration. */
+export declare const DEFAULT_TOAST_MS = 2500;
+/**
+ * The complete HUD state at `frame`. Ops after `frame` are ignored; unknown
+ * op names are skipped rather than throwing.
+ */
+export declare function reduceHudState(ops: readonly HudOp[], frame: number, fps?: number): HudReplayState;
+/** True when a state would rasterize to a fully transparent frame. */
+export declare function isBlankHudState(state: HudReplayState): boolean;
+export interface UiKeyframe {
+    /** Source frame whose state this is. */
+    sourceFrame: number;
+    clipIndex: number;
+    /** Output-timeline seconds this overlay becomes visible. */
+    outputStartSec: number;
+    /** Output-timeline seconds it stops being visible (next keyframe / clip end). */
+    outputEndSec: number;
+    state: HudReplayState;
+}
+export interface CollectUiKeyframesOptions {
+    /** Source-clock fps. Default 60. */
+    fps?: number;
+    /** Ceiling on keyframes per second of OUTPUT time. Default 10. */
+    maxPerSecond?: number;
+    /** Hard ceiling per clip. Default 240. */
+    maxPerClip?: number;
+    /** Per-clip opt-out; defaults to every clip. */
+    clipEnabled?: (clipIndex: number) => boolean;
+    /** Where truncation notices go. Defaults to stderr. */
+    log?: (line: string) => void;
+}
+export declare const DEFAULT_MAX_KEYFRAMES_PER_SECOND = 10;
+export declare const DEFAULT_MAX_KEYFRAMES_PER_CLIP = 240;
+/**
+ * Walk every enabled clip's source range and emit a keyframe wherever the
+ * reduced HUD state changes.
+ *
+ * A clip's overlays stop at `exclusiveOutputEnd`, so during a crossfade the
+ * incoming clip's UI takes over at the fade start and exactly one overlay is
+ * ever active — two stacked HUDs would double-draw every element.
+ */
+export declare function collectUiKeyframes(ops: readonly HudOp[], clips: readonly ClipTiming[], opts?: CollectUiKeyframesOptions): UiKeyframe[];