screencast-axi 0.1.0

package/dist/src/hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../../src/hooks.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,KAAyB;IACpD,IAAI,KAAK,IAAI,KAAK,KAAK,MAAM,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACrD,MAAM,IAAI,eAAe,CAAC,iCAAiC,EAAE,kBAAkB,EAAE;YAC/E,0BAA0B;SAC3B,CAAC,CAAC;IACL,CAAC;IACD,MAAM,IAAI,eAAe,CAAC,uCAAuC,EAAE,iBAAiB,EAAE;QACpF,6FAA6F;QAC7F,+DAA+D;KAChE,CAAC,CAAC;AACL,CAAC"}

package/dist/src/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Public authoring surface.
+ *
+ * Playwright is referenced through `import type` only, so importing this
+ * module costs nothing at runtime and works in a project that has no browser
+ * installed - a site reading clip metadata at build time should not have to
+ * install one.
+ */
+export { VERSION } from "./version.js";
+export { Director, type DirectorOptions } from "./director.js";
+export { defineScenario, isScenario, type DefinedScenario, type Scenario, type ScenarioContext, type Target, type Viewport, } from "./types.js";
+export { DEFAULT_OVERLAY_THEME, resolveOverlayTheme, type OverlayApi, type OverlayTheme, type ResolvedOverlayTheme, } from "./overlay.js";
+export { DEFAULT_ENCODE_SETTINGS, encode, type EncodeOptions, type EncodeResult, type EncodeSettings, } from "./encode.js";
+export { detectToolchain, installHint, type BinaryInfo, type PosterEncoder, type Toolchain, } from "./toolchain.js";
+export { defineConfig, loadConfig, loadScenarios, type BrowserConfig, type ResolvedConfig, type ScreencastConfig, } from "./config.js";
+export { clipFilesFor, readManifest, type ClipFiles, type ManifestEntry } from "./manifest.js";
+export { basicAuth, noAuth, profileAuth, storageStateAuth, type BasicAuthOptions, type ProfileAuthOptions, type StorageStateOptions, } from "./auth/strategies.js";
+export type { AuthContext, AuthIdentity, AuthPreflightContext, AuthStrategy, ContextPatch, } from "./auth/types.js";

package/dist/src/index.js

@@ -0,0 +1,18 @@
+/**
+ * Public authoring surface.
+ *
+ * Playwright is referenced through `import type` only, so importing this
+ * module costs nothing at runtime and works in a project that has no browser
+ * installed - a site reading clip metadata at build time should not have to
+ * install one.
+ */
+export { VERSION } from "./version.js";
+export { Director } from "./director.js";
+export { defineScenario, isScenario, } from "./types.js";
+export { DEFAULT_OVERLAY_THEME, resolveOverlayTheme, } from "./overlay.js";
+export { DEFAULT_ENCODE_SETTINGS, encode, } from "./encode.js";
+export { detectToolchain, installHint, } from "./toolchain.js";
+export { defineConfig, loadConfig, loadScenarios, } from "./config.js";
+export { clipFilesFor, readManifest } from "./manifest.js";
+export { basicAuth, noAuth, profileAuth, storageStateAuth, } from "./auth/strategies.js";
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC,OAAO,EAAE,QAAQ,EAAwB,MAAM,eAAe,CAAC;AAC/D,OAAO,EACL,cAAc,EACd,UAAU,GAMX,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,qBAAqB,EACrB,mBAAmB,GAIpB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,uBAAuB,EACvB,MAAM,GAIP,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,eAAe,EACf,WAAW,GAIZ,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,YAAY,EACZ,UAAU,EACV,aAAa,GAId,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,YAAY,EAAE,YAAY,EAAsC,MAAM,eAAe,CAAC;AAC/F,OAAO,EACL,SAAS,EACT,MAAM,EACN,WAAW,EACX,gBAAgB,GAIjB,MAAM,sBAAsB,CAAC"}

package/dist/src/inventory.d.ts

@@ -0,0 +1,45 @@
+import { type ResolvedConfig } from "./config.js";
+import { type ManifestEntry, type ManifestProblem } from "./manifest.js";
+/**
+ * What the clip library actually contains, cross-referenced.
+ *
+ * Every read-only command answers some version of "what do I need to re-shoot",
+ * and deriving that from scratch means reading the manifest, listing the output
+ * directory and diffing both against the scenario list. Computing it once, in
+ * one place, is what lets the CLI answer in a single call instead of making an
+ * agent do three and guess.
+ */
+export type ClipStatus = 
+/** Recorded, and the scenario has not changed since. */
+"recorded"
+/** Recorded, but the scenario has changed - the clip shows something stale. */
+ | "stale" | "never-recorded"
+/** In the manifest, but a file it claims is missing from disk. */
+ | "incomplete";
+export interface InventoryRow {
+    readonly id: string;
+    readonly status: ClipStatus;
+    readonly title: string;
+    readonly steps: number;
+    readonly durationMs: number;
+    readonly file: string;
+    readonly entry?: ManifestEntry;
+    /** Deliverables the manifest claims but disk does not have. */
+    readonly missing: readonly string[];
+    /** Why it is stale, when it is. */
+    readonly staleReason?: "narration changed" | "scenario changed";
+}
+export interface Inventory {
+    readonly rows: readonly InventoryRow[];
+    /** Manifest entries with no scenario behind them any more. */
+    readonly orphans: readonly ManifestEntry[];
+    /** Media in the output directory that no manifest entry claims. */
+    readonly strays: readonly string[];
+    readonly problems: readonly ManifestProblem[];
+    readonly counts: Readonly<Record<ClipStatus, number>>;
+}
+export declare function buildInventory(config: ResolvedConfig): Promise<Inventory>;
+/** One-line summary, so every command phrases the same fact the same way. */
+export declare function summarise(inventory: Inventory): string;
+/** Absolute path of a clip's files, for `show`. */
+export declare function filesOf(row: InventoryRow, outDir: string): string[];

package/dist/src/inventory.js

@@ -0,0 +1,89 @@
+import { existsSync, readdirSync } from "node:fs";
+import { basename, extname, join } from "node:path";
+import { loadScenarios } from "./config.js";
+import { claimedFiles, hashSteps, hashText, missingFiles, readManifest, } from "./manifest.js";
+import { readFile } from "node:fs/promises";
+const MEDIA = new Set([".mp4", ".webm", ".webp", ".gif", ".png"]);
+async function statusOf(loaded, entry) {
+    if (!entry)
+        return { status: "never-recorded", missing: [] };
+    const { scenario, file } = loaded;
+    // Narration first: it is the cheaper check and the more common change, and
+    // it is the one that makes a clip actively wrong rather than merely dated -
+    // the caption on screen no longer matches what the scenario says.
+    if (entry.stepsHash && entry.stepsHash !== hashSteps(scenario.steps)) {
+        return { status: "stale", missing: [], staleReason: "narration changed" };
+    }
+    if (entry.sourceHash) {
+        const source = await readFile(file, "utf8").catch(() => null);
+        if (source !== null && hashText(source) !== entry.sourceHash) {
+            return { status: "stale", missing: [], staleReason: "scenario changed" };
+        }
+    }
+    return { status: "recorded", missing: [] };
+}
+export async function buildInventory(config) {
+    const loaded = await loadScenarios(config);
+    const { entries, problems } = readManifest(config.outDir);
+    const byId = new Map(entries.map((e) => [e.id, e]));
+    const rows = [];
+    for (const item of loaded) {
+        const entry = byId.get(item.scenario.id);
+        const state = await statusOf(item, entry);
+        const missing = entry ? missingFiles(entry, config.outDir) : [];
+        rows.push({
+            id: item.scenario.id,
+            title: item.scenario.title,
+            steps: item.scenario.steps?.length ?? 0,
+            durationMs: entry?.durationMs ?? 0,
+            file: item.file,
+            ...(entry ? { entry } : {}),
+            ...state,
+            // A missing file beats a stale hash: the clip is not merely dated, it is
+            // not all there.
+            ...(missing.length > 0 ? { status: "incomplete", missing } : {}),
+        });
+    }
+    const known = new Set(loaded.map((l) => l.scenario.id));
+    const orphans = entries.filter((e) => !known.has(e.id));
+    // Built from what each entry says it wrote, so an animated WebP - which
+    // shares the `.webp` extension with the poster - is not mistaken for a
+    // leftover file.
+    const claimed = new Set();
+    for (const entry of entries)
+        for (const name of claimedFiles(entry))
+            claimed.add(name);
+    const strays = existsSync(config.outDir)
+        ? readdirSync(config.outDir)
+            .filter((f) => MEDIA.has(extname(f)) && !claimed.has(basename(f)))
+            .sort()
+        : [];
+    const counts = {
+        recorded: 0,
+        stale: 0,
+        "never-recorded": 0,
+        incomplete: 0,
+    };
+    for (const row of rows)
+        counts[row.status]++;
+    return { rows, orphans, strays, problems, counts };
+}
+/** One-line summary, so every command phrases the same fact the same way. */
+export function summarise(inventory) {
+    const { rows, counts } = inventory;
+    if (rows.length === 0)
+        return "0 scenarios";
+    const parts = [`${rows.length} scenarios`];
+    for (const [state, n] of Object.entries(counts))
+        if (n > 0)
+            parts.push(`${n} ${state}`);
+    return parts.join(", ");
+}
+/** Absolute path of a clip's files, for `show`. */
+export function filesOf(row, outDir) {
+    if (!row.entry)
+        return [];
+    const formats = row.entry.formats ?? ["mp4", "webm", "webp"];
+    return formats.map((f) => join(outDir, `${row.id}.${f}`)).filter((f) => existsSync(f));
+}
+//# sourceMappingURL=inventory.js.map

package/dist/src/inventory.js.map

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

package/dist/src/manifest.d.ts

@@ -0,0 +1,89 @@
+/**
+ * The manifest: what the recorder wrote, in a form a website can read.
+ *
+ * Deliberately dependency-free (node builtins only) and exported on its own
+ * subpath, so a site importing it at build time does not pull in Playwright or
+ * a browser it has no use for.
+ */
+export declare const MANIFEST_FILENAME = "manifest.json";
+export interface ManifestEntry {
+    /** File stem shared by every deliverable of this clip. */
+    readonly id: string;
+    readonly title: string;
+    readonly description: string;
+    /** The narration, which is also the readable text of the workflow. */
+    readonly steps?: readonly string[];
+    readonly width: number;
+    readonly height: number;
+    readonly durationMs: number;
+    /** ISO 8601. Doubles as the upload date in schema.org markup. */
+    readonly recordedAt: string;
+    /** Playback multiplier the take was recorded at. */
+    readonly pace?: number;
+    /** Device preset, when the take used one. */
+    readonly device?: string;
+    /** Extensions actually written, e.g. ["mp4","webm","webp"]. */
+    readonly formats?: readonly string[];
+    /**
+     * Hash of the scenario source at record time.
+     *
+     * What makes "this clip is stale" answerable without opening the video: if
+     * the scenario has changed since, the clip shows something the code no
+     * longer does.
+     */
+    readonly sourceHash?: string;
+    /**
+     * Hash of the narration at record time.
+     *
+     * Separates the two reasons a manifest and a scenario can disagree: steps
+     * that were never written down (a safe backfill) versus wording that changed
+     * while the video still shows the old line (needs a reshoot). Without it
+     * those look identical and a human has to judge every field.
+     */
+    readonly stepsHash?: string;
+    readonly recorderVersion?: string;
+}
+export declare function hashText(text: string): string;
+export declare function hashSteps(steps: readonly string[] | undefined): string;
+export declare function manifestPath(dir: string): string;
+export interface ManifestProblem {
+    readonly index: number;
+    readonly reason: string;
+}
+export interface ValidationResult {
+    readonly entries: ManifestEntry[];
+    readonly problems: ManifestProblem[];
+}
+/**
+ * Validates parsed JSON into entries, keeping the good ones.
+ *
+ * A half-written manifest should cost you the clips it mangled, not the whole
+ * page: a site that renders four good clips and falls back for a fifth is a
+ * better outcome than one that throws during a build.
+ */
+export declare function validateManifest(value: unknown): ValidationResult;
+/** Reads and validates the manifest in `dir`. A missing file is not an error. */
+export declare function readManifest(dir: string): ValidationResult;
+/** Writes entries sorted by id, so a reshoot produces a minimal diff. */
+export declare function writeManifest(dir: string, entries: readonly ManifestEntry[]): string;
+/** Inserts or replaces one entry, leaving the rest untouched. */
+export declare function upsertEntry(dir: string, entry: ManifestEntry): string;
+export interface ClipFiles {
+    readonly mp4: string;
+    readonly webm: string;
+    readonly poster: string;
+    readonly gif?: string;
+    readonly animatedWebp?: string;
+}
+/**
+ * Absolute paths to a clip's deliverables.
+ *
+ * The poster extension follows what was actually written, because a machine
+ * without a WebP encoder produces a PNG - a consumer that assumed `.webp`
+ * would link a file that is not there.
+ */
+export declare function clipFilesFor(entry: ManifestEntry, dir: string): ClipFiles;
+/** Every file an entry claims, by name. What `check` compares disk against. */
+export declare function claimedFiles(entry: ManifestEntry): string[];
+/** Whether every file the entry claims is actually on disk. */
+export declare function missingFiles(entry: ManifestEntry, dir: string): string[];

package/dist/src/manifest.js

@@ -0,0 +1,137 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+/**
+ * The manifest: what the recorder wrote, in a form a website can read.
+ *
+ * Deliberately dependency-free (node builtins only) and exported on its own
+ * subpath, so a site importing it at build time does not pull in Playwright or
+ * a browser it has no use for.
+ */
+export const MANIFEST_FILENAME = "manifest.json";
+export function hashText(text) {
+    return createHash("sha256").update(text).digest("hex").slice(0, 16);
+}
+export function hashSteps(steps) {
+    return hashText(JSON.stringify(steps ?? []));
+}
+export function manifestPath(dir) {
+    return dir.endsWith(".json") ? dir : join(dir, MANIFEST_FILENAME);
+}
+const REQUIRED_STRINGS = ["id", "title", "description", "recordedAt"];
+const REQUIRED_NUMBERS = ["width", "height", "durationMs"];
+/**
+ * Validates parsed JSON into entries, keeping the good ones.
+ *
+ * A half-written manifest should cost you the clips it mangled, not the whole
+ * page: a site that renders four good clips and falls back for a fifth is a
+ * better outcome than one that throws during a build.
+ */
+export function validateManifest(value) {
+    if (!Array.isArray(value)) {
+        return { entries: [], problems: [{ index: -1, reason: "manifest is not an array" }] };
+    }
+    const entries = [];
+    const problems = [];
+    const seen = new Set();
+    value.forEach((raw, index) => {
+        if (typeof raw !== "object" || raw === null) {
+            problems.push({ index, reason: "entry is not an object" });
+            return;
+        }
+        const entry = raw;
+        for (const key of REQUIRED_STRINGS) {
+            if (typeof entry[key] !== "string" || entry[key].length === 0) {
+                problems.push({ index, reason: `missing or empty \`${key}\`` });
+                return;
+            }
+        }
+        for (const key of REQUIRED_NUMBERS) {
+            if (typeof entry[key] !== "number" || !Number.isFinite(entry[key])) {
+                problems.push({ index, reason: `\`${key}\` is not a number` });
+                return;
+            }
+        }
+        if (entry["steps"] !== undefined && !Array.isArray(entry["steps"])) {
+            problems.push({ index, reason: "`steps` is not an array" });
+            return;
+        }
+        const id = entry["id"];
+        if (seen.has(id)) {
+            problems.push({ index, reason: `duplicate id \`${id}\`` });
+            return;
+        }
+        seen.add(id);
+        entries.push(entry);
+    });
+    return { entries, problems };
+}
+/** Reads and validates the manifest in `dir`. A missing file is not an error. */
+export function readManifest(dir) {
+    const file = manifestPath(dir);
+    if (!existsSync(file))
+        return { entries: [], problems: [] };
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch (error) {
+        return {
+            entries: [],
+            problems: [{ index: -1, reason: `manifest is not valid JSON: ${String(error)}` }],
+        };
+    }
+    return validateManifest(parsed);
+}
+/** Writes entries sorted by id, so a reshoot produces a minimal diff. */
+export function writeManifest(dir, entries) {
+    const file = manifestPath(dir);
+    mkdirSync(dirname(file), { recursive: true });
+    const sorted = [...entries].sort((a, b) => a.id.localeCompare(b.id));
+    writeFileSync(file, `${JSON.stringify(sorted, null, 2)}\n`);
+    return file;
+}
+/** Inserts or replaces one entry, leaving the rest untouched. */
+export function upsertEntry(dir, entry) {
+    const { entries } = readManifest(dir);
+    const next = entries.filter((e) => e.id !== entry.id);
+    next.push(entry);
+    return writeManifest(dir, next);
+}
+/**
+ * Absolute paths to a clip's deliverables.
+ *
+ * The poster extension follows what was actually written, because a machine
+ * without a WebP encoder produces a PNG - a consumer that assumed `.webp`
+ * would link a file that is not there.
+ */
+export function clipFilesFor(entry, dir) {
+    const formats = entry.formats ?? ["mp4", "webm", "webp"];
+    const poster = formats.includes("png") ? "png" : "webp";
+    return {
+        mp4: join(dir, `${entry.id}.mp4`),
+        webm: join(dir, `${entry.id}.webm`),
+        poster: join(dir, `${entry.id}.${poster}`),
+        ...(formats.includes("gif") ? { gif: join(dir, `${entry.id}.gif`) } : {}),
+        ...(formats.includes("anim.webp") ? { animatedWebp: join(dir, `${entry.id}.anim.webp`) } : {}),
+    };
+}
+/** Every file an entry claims, by name. What `check` compares disk against. */
+export function claimedFiles(entry) {
+    const formats = entry.formats ?? ["mp4", "webm", "webp"];
+    return formats.map((f) => `${entry.id}.${f}`);
+}
+/** Whether every file the entry claims is actually on disk. */
+export function missingFiles(entry, dir) {
+    const files = clipFilesFor(entry, dir);
+    return [
+        files.mp4,
+        files.webm,
+        files.poster,
+        ...(files.gif ? [files.gif] : []),
+        ...(files.animatedWebp ? [files.animatedWebp] : []),
+    ]
+        .filter((f) => !existsSync(f))
+        .map((f) => basename(f));
+}
+//# sourceMappingURL=manifest.js.map

package/dist/src/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../../src/manifest.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEpD;;;;;;GAMG;AAEH,MAAM,CAAC,MAAM,iBAAiB,GAAG,eAAe,CAAC;AAwCjD,MAAM,UAAU,QAAQ,CAAC,IAAY;IACnC,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AACtE,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,KAAoC;IAC5D,OAAO,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,CAAC;AAC/C,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,GAAW;IACtC,OAAO,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,iBAAiB,CAAC,CAAC;AACpE,CAAC;AAYD,MAAM,gBAAgB,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,aAAa,EAAE,YAAY,CAAU,CAAC;AAC/E,MAAM,gBAAgB,GAAG,CAAC,OAAO,EAAE,QAAQ,EAAE,YAAY,CAAU,CAAC;AAEpE;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,QAAQ,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,0BAA0B,EAAE,CAAC,EAAE,CAAC;IACxF,CAAC;IAED,MAAM,OAAO,GAAoB,EAAE,CAAC;IACpC,MAAM,QAAQ,GAAsB,EAAE,CAAC;IACvC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAE/B,KAAK,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE;QAC3B,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;YAC5C,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,wBAAwB,EAAE,CAAC,CAAC;YAC3D,OAAO;QACT,CAAC;QACD,MAAM,KAAK,GAAG,GAA8B,CAAC;QAE7C,KAAK,MAAM,GAAG,IAAI,gBAAgB,EAAE,CAAC;YACnC,IAAI,OAAO,KAAK,CAAC,GAAG,CAAC,KAAK,QAAQ,IAAK,KAAK,CAAC,GAAG,CAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAC1E,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,sBAAsB,GAAG,IAAI,EAAE,CAAC,CAAC;gBAChE,OAAO;YACT,CAAC;QACH,CAAC;QACD,KAAK,MAAM,GAAG,IAAI,gBAAgB,EAAE,CAAC;YACnC,IAAI,OAAO,KAAK,CAAC,GAAG,CAAC,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;gBACnE,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,GAAG,oBAAoB,EAAE,CAAC,CAAC;gBAC/D,OAAO;YACT,CAAC;QACH,CAAC;QACD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC;YACnE,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,yBAAyB,EAAE,CAAC,CAAC;YAC5D,OAAO;QACT,CAAC;QAED,MAAM,EAAE,GAAG,KAAK,CAAC,IAAI,CAAW,CAAC;QACjC,IAAI,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;YACjB,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,kBAAkB,EAAE,IAAI,EAAE,CAAC,CAAC;YAC3D,OAAO;QACT,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACb,OAAO,CAAC,IAAI,CAAC,KAAiC,CAAC,CAAC;IAClD,CAAC,CAAC,CAAC;IAEH,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;AAC/B,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,YAAY,CAAC,GAAW;IACtC,MAAM,IAAI,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;IAC/B,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;IAC5D,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;IAClD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO;YACL,OAAO,EAAE,EAAE;YACX,QAAQ,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,+BAA+B,MAAM,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC;SAClF,CAAC;IACJ,CAAC;IACD,OAAO,gBAAgB,CAAC,MAAM,CAAC,CAAC;AAClC,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,aAAa,CAAC,GAAW,EAAE,OAAiC;IAC1E,MAAM,IAAI,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;IAC/B,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9C,MAAM,MAAM,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACrE,aAAa,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;IAC5D,OAAO,IAAI,CAAC;AACd,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,WAAW,CAAC,GAAW,EAAE,KAAoB;IAC3D,MAAM,EAAE,OAAO,EAAE,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;IACtC,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,KAAK,CAAC,EAAE,CAAC,CAAC;IACtD,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACjB,OAAO,aAAa,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;AAClC,CAAC;AAUD;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,KAAoB,EAAE,GAAW;IAC5D,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACzD,MAAM,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC;IACxD,OAAO;QACL,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,EAAE,MAAM,CAAC;QACjC,IAAI,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,EAAE,OAAO,CAAC;QACnC,MAAM,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,EAAE,IAAI,MAAM,EAAE,CAAC;QAC1C,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACzE,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,EAAE,YAAY,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC/F,CAAC;AACJ,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,YAAY,CAAC,KAAoB;IAC/C,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACzD,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC;AAChD,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,YAAY,CAAC,KAAoB,EAAE,GAAW;IAC5D,MAAM,KAAK,GAAG,YAAY,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IACvC,OAAO;QACL,KAAK,CAAC,GAAG;QACT,KAAK,CAAC,IAAI;QACV,KAAK,CAAC,MAAM;QACZ,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACjC,GAAG,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;KACpD;SACE,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;SAC7B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;AAC7B,CAAC"}

package/dist/src/output.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Structural mirror of the SDK's `AxiRenderable`.
+ *
+ * `axi-sdk-js` does not export its `output` module, so the renderable type is
+ * restated here rather than reached for through a deep import.
+ */
+export type AxiStructuredOutput = Record<string, unknown>;
+export type AxiRenderable = string | AxiStructuredOutput;

package/dist/src/output.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=output.js.map

package/dist/src/output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.js","sourceRoot":"","sources":["../../src/output.ts"],"names":[],"mappings":""}

package/dist/src/overlay.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Page overlay injected into every document of a recording session.
+ *
+ * Playwright videos do not contain the mouse pointer, which makes any clip of a
+ * drag or a click unreadable. This draws a synthetic pointer that follows the
+ * real one (Playwright's `mouse.move` dispatches genuine `mousemove` events, so
+ * the overlay stays in sync for free), plus a click ripple, a drag ghost and a
+ * caption bar.
+ *
+ * Everything lives in a shadow root so no page CSS can reach it, and the host
+ * is `pointer-events: none` so it never intercepts a click.
+ */
+export interface OverlayApi {
+    caption(text: string | null): void;
+    setPointerVisible(visible: boolean): void;
+    setDragging(dragging: boolean): void;
+}
+declare global {
+    interface Window {
+        __screencast?: OverlayApi;
+    }
+}
+export interface OverlayTheme {
+    /** Ripple and drag-ghost colour. Any CSS colour; hex gets alpha variants. */
+    readonly accent: string;
+    /** Replace the browser's own cursor with the drawn one. */
+    readonly hideNativeCursor: boolean;
+    /**
+     * Selectors hidden for the duration of the recording.
+     *
+     * Development-only chrome belongs here - a framework's error badge, a
+     * cookie banner, a staging ribbon - so it never lands in footage that gets
+     * shown to someone.
+     */
+    readonly hideSelectors: readonly string[];
+    readonly pointer: {
+        readonly size: number;
+        readonly fill: string;
+        readonly stroke: string;
+        readonly strokeWidth: number;
+    };
+    readonly ripple: {
+        readonly enabled: boolean;
+        readonly scale: number;
+        readonly durationMs: number;
+    };
+    readonly dragGhost: {
+        readonly enabled: boolean;
+        readonly width: number;
+        readonly height: number;
+        readonly radius: number;
+    };
+    readonly caption: {
+        readonly position: "top" | "bottom";
+        /** Distance from that edge, in px. */
+        readonly offset: number;
+        readonly maxWidth: string;
+        readonly background: string;
+        readonly color: string;
+        readonly fontSize: number;
+        readonly fontFamily: string;
+        readonly fontWeight: number;
+        readonly radius: number;
+        readonly padding: string;
+        readonly fadeMs: number;
+        readonly shadow: string;
+    };
+}
+export declare const DEFAULT_OVERLAY_THEME: OverlayTheme;
+/**
+ * Theme with every colour already resolved to a concrete CSS string.
+ *
+ * The alpha variants are computed here rather than in the page so that
+ * {@link installOverlay} stays a dumb interpolator: it has to survive being
+ * stringified, and every helper it would otherwise call is one more thing that
+ * can break in that trip.
+ */
+export interface ResolvedOverlayTheme extends OverlayTheme {
+    readonly accentSoft: string;
+    readonly accentEdge: string;
+    readonly accentRipple: string;
+    readonly accentRippleEdge: string;
+}
+export declare function resolveOverlayTheme(overrides?: DeepPartial<OverlayTheme>): ResolvedOverlayTheme;
+export type DeepPartial<T> = {
+    [K in keyof T]?: T[K] extends readonly unknown[] ? T[K] : T[K] extends object ? DeepPartial<T[K]> : T[K];
+};
+export declare function mergeThemes(base: DeepPartial<OverlayTheme> | undefined, over: DeepPartial<OverlayTheme> | undefined): DeepPartial<OverlayTheme>;
+/**
+ * Serialised form of {@link installOverlay}, ready for `addInitScript`.
+ *
+ * The function is stringified rather than passed directly because this file is
+ * compiled by esbuild under `keepNames` in some toolchains, which rewrites
+ * every inner function as `__name(fn, "fn")`. That helper only exists in the
+ * Node module scope, so the function throws `__name is not defined` the moment
+ * Playwright evaluates it in the page - silently, unless a `pageerror`
+ * listener is attached. Re-declaring `__name` as identity in the wrapper is
+ * enough, and costs nothing if a future toolchain stops emitting it.
+ *
+ * The theme travels as JSON in the same wrapper, so theming does not
+ * reintroduce a function reference that would have to survive the same trip.
+ */
+export declare function overlayInitScript(theme: ResolvedOverlayTheme): string;
+/** Runs inside the page via `addInitScript`. Must be fully self-contained. */
+export declare function installOverlay(theme: ResolvedOverlayTheme): void;