tutorial-forge 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 John Brecht
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,19 @@
+# tutorial-forge
+
+Turn scripted Playwright walkthroughs into narrated tutorial videos (MP4).
+
+**Tutorials are source code.** Each tutorial pairs narration lines with raw Playwright actions; the pipeline handles TTS narration (ElevenLabs, OpenAI, Piper, or silent), screen recording, narration-driven pacing, an animated cursor, click callouts, SRT subtitles, and the FFmpeg merge. When your UI changes, re-render instead of re-recording.
+
+```ts
+import { tutorial, step } from 'tutorial-forge';
+
+export default tutorial('Getting started', [
+  step('Open the Events page from the navigation bar.', async (page) => {
+    await page.getByRole('link', { name: 'Events' }).click();
+  }),
+]);
+```
+
+This package is the library (types, spec builders, pipeline, TTS providers). Most users also want [`tutorial-forge-cli`](https://www.npmjs.com/package/tutorial-forge-cli) for the `tutorial-forge` command.
+
+**Full documentation: [github.com/jbrecht/tutorial-forge](https://github.com/jbrecht/tutorial-forge)**

package/dist/browser/callout.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Click-highlight overlay: a brief rounded-rect ring around the action target,
+ * rendered live in the browser so the raw webm already contains it (v1 —
+ * the manifest keeps the data so a later version can composite in post).
+ */
+export declare const CALLOUT_INIT_SCRIPT = "\n(() => {\n  if (window.__forgeCallout) return;\n  window.__forgeCallout = (x, y, w, h) => {\n    if (!document.documentElement) return;\n    const pad = 6;\n    const ring = document.createElement('div');\n    ring.style.cssText = [\n      'position:fixed',\n      'left:' + (x - pad) + 'px', 'top:' + (y - pad) + 'px',\n      'width:' + (w + pad * 2) + 'px', 'height:' + (h + pad * 2) + 'px',\n      'border:3px solid rgba(66,133,244,.9)', 'border-radius:8px',\n      'box-shadow:0 0 0 3px rgba(66,133,244,.25)',\n      'z-index:2147483645', 'pointer-events:none',\n      'opacity:0', 'transition:opacity 120ms ease-in',\n    ].join(';');\n    document.documentElement.appendChild(ring);\n    requestAnimationFrame(() => { ring.style.opacity = '1'; });\n    setTimeout(() => {\n      ring.style.transition = 'opacity 180ms ease-out';\n      ring.style.opacity = '0';\n      setTimeout(() => ring.remove(), 200);\n    }, 600);\n  };\n})();\n";
+export declare const CALLOUT_VISIBLE_MS = 600;

package/dist/browser/callout.js

@@ -0,0 +1,33 @@
+/**
+ * Click-highlight overlay: a brief rounded-rect ring around the action target,
+ * rendered live in the browser so the raw webm already contains it (v1 —
+ * the manifest keeps the data so a later version can composite in post).
+ */
+export const CALLOUT_INIT_SCRIPT = `
+(() => {
+  if (window.__forgeCallout) return;
+  window.__forgeCallout = (x, y, w, h) => {
+    if (!document.documentElement) return;
+    const pad = 6;
+    const ring = document.createElement('div');
+    ring.style.cssText = [
+      'position:fixed',
+      'left:' + (x - pad) + 'px', 'top:' + (y - pad) + 'px',
+      'width:' + (w + pad * 2) + 'px', 'height:' + (h + pad * 2) + 'px',
+      'border:3px solid rgba(66,133,244,.9)', 'border-radius:8px',
+      'box-shadow:0 0 0 3px rgba(66,133,244,.25)',
+      'z-index:2147483645', 'pointer-events:none',
+      'opacity:0', 'transition:opacity 120ms ease-in',
+    ].join(';');
+    document.documentElement.appendChild(ring);
+    requestAnimationFrame(() => { ring.style.opacity = '1'; });
+    setTimeout(() => {
+      ring.style.transition = 'opacity 180ms ease-out';
+      ring.style.opacity = '0';
+      setTimeout(() => ring.remove(), 200);
+    }, 600);
+  };
+})();
+`;
+export const CALLOUT_VISIBLE_MS = 600;
+//# sourceMappingURL=callout.js.map

package/dist/browser/callout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"callout.js","sourceRoot":"","sources":["../../src/browser/callout.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,CAAC,MAAM,mBAAmB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;CAyBlC,CAAC;AAEF,MAAM,CAAC,MAAM,kBAAkB,GAAG,GAAG,CAAC"}

package/dist/browser/cursor.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Fake-cursor overlay. Playwright fires real input events but renders no
+ * cursor; we inject one and move it explicitly before instrumented actions.
+ * Everything is namespaced under __forge_* and pointer-events: none —
+ * graceful degradation, never interference.
+ */
+export declare const CURSOR_INIT_SCRIPT = "\n(() => {\n  if (window.__forgeCursor) return;\n\n  const ensure = () => {\n    let el = document.getElementById('__forge_cursor__');\n    if (el) return el;\n    if (!document.documentElement) return null;\n    el = document.createElement('div');\n    el.id = '__forge_cursor__';\n    el.style.cssText = [\n      'position:fixed', 'left:0', 'top:0', 'width:24px', 'height:24px',\n      'z-index:2147483647', 'pointer-events:none',\n      'transform:translate(-100px,-100px)',\n      'transition:transform 350ms cubic-bezier(.25,.1,.25,1)',\n      'filter:drop-shadow(0 1px 2px rgba(0,0,0,.4))',\n    ].join(';');\n    el.innerHTML = '<svg width=\"24\" height=\"24\" viewBox=\"0 0 24 24\">'\n      + '<path d=\"M5 2 L5 19 L9.5 15 L12.5 21.5 L15 20.3 L12 14 L18 14 Z\"'\n      + ' fill=\"white\" stroke=\"black\" stroke-width=\"1.4\" stroke-linejoin=\"round\"/></svg>';\n    document.documentElement.appendChild(el);\n    return el;\n  };\n\n  window.__forgeCursor = {\n    moveTo(x, y) {\n      const el = ensure();\n      if (el) el.style.transform = 'translate(' + x + 'px,' + y + 'px)';\n    },\n    pulse(x, y) {\n      if (!document.documentElement) return;\n      const p = document.createElement('div');\n      p.style.cssText = [\n        'position:fixed', 'left:' + (x - 18) + 'px', 'top:' + (y - 18) + 'px',\n        'width:36px', 'height:36px', 'border-radius:50%',\n        'background:rgba(66,133,244,.45)', 'z-index:2147483646',\n        'pointer-events:none', 'transform:scale(.3)', 'opacity:1',\n        'transition:transform 300ms ease-out, opacity 300ms ease-out',\n      ].join(';');\n      document.documentElement.appendChild(p);\n      requestAnimationFrame(() => {\n        p.style.transform = 'scale(1.6)';\n        p.style.opacity = '0';\n      });\n      setTimeout(() => p.remove(), 350);\n    },\n  };\n\n  if (document.readyState !== 'loading') ensure();\n  else document.addEventListener('DOMContentLoaded', ensure, { once: true });\n})();\n";
+/** Duration of the cursor's CSS transition; instrumented actions wait this long after moveTo. */
+export declare const CURSOR_TRAVEL_MS = 350;

package/dist/browser/cursor.js

@@ -0,0 +1,61 @@
+/**
+ * Fake-cursor overlay. Playwright fires real input events but renders no
+ * cursor; we inject one and move it explicitly before instrumented actions.
+ * Everything is namespaced under __forge_* and pointer-events: none —
+ * graceful degradation, never interference.
+ */
+export const CURSOR_INIT_SCRIPT = `
+(() => {
+  if (window.__forgeCursor) return;
+
+  const ensure = () => {
+    let el = document.getElementById('__forge_cursor__');
+    if (el) return el;
+    if (!document.documentElement) return null;
+    el = document.createElement('div');
+    el.id = '__forge_cursor__';
+    el.style.cssText = [
+      'position:fixed', 'left:0', 'top:0', 'width:24px', 'height:24px',
+      'z-index:2147483647', 'pointer-events:none',
+      'transform:translate(-100px,-100px)',
+      'transition:transform 350ms cubic-bezier(.25,.1,.25,1)',
+      'filter:drop-shadow(0 1px 2px rgba(0,0,0,.4))',
+    ].join(';');
+    el.innerHTML = '<svg width="24" height="24" viewBox="0 0 24 24">'
+      + '<path d="M5 2 L5 19 L9.5 15 L12.5 21.5 L15 20.3 L12 14 L18 14 Z"'
+      + ' fill="white" stroke="black" stroke-width="1.4" stroke-linejoin="round"/></svg>';
+    document.documentElement.appendChild(el);
+    return el;
+  };
+
+  window.__forgeCursor = {
+    moveTo(x, y) {
+      const el = ensure();
+      if (el) el.style.transform = 'translate(' + x + 'px,' + y + 'px)';
+    },
+    pulse(x, y) {
+      if (!document.documentElement) return;
+      const p = document.createElement('div');
+      p.style.cssText = [
+        'position:fixed', 'left:' + (x - 18) + 'px', 'top:' + (y - 18) + 'px',
+        'width:36px', 'height:36px', 'border-radius:50%',
+        'background:rgba(66,133,244,.45)', 'z-index:2147483646',
+        'pointer-events:none', 'transform:scale(.3)', 'opacity:1',
+        'transition:transform 300ms ease-out, opacity 300ms ease-out',
+      ].join(';');
+      document.documentElement.appendChild(p);
+      requestAnimationFrame(() => {
+        p.style.transform = 'scale(1.6)';
+        p.style.opacity = '0';
+      });
+      setTimeout(() => p.remove(), 350);
+    },
+  };
+
+  if (document.readyState !== 'loading') ensure();
+  else document.addEventListener('DOMContentLoaded', ensure, { once: true });
+})();
+`;
+/** Duration of the cursor's CSS transition; instrumented actions wait this long after moveTo. */
+export const CURSOR_TRAVEL_MS = 350;
+//# sourceMappingURL=cursor.js.map

package/dist/browser/cursor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor.js","sourceRoot":"","sources":["../../src/browser/cursor.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,CAAC,MAAM,kBAAkB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmDjC,CAAC;AAEF,iGAAiG;AACjG,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAG,CAAC"}

package/dist/browser/instrument.d.ts

@@ -0,0 +1,16 @@
+import type { Page } from 'playwright';
+import type { CalloutRecord } from '../types.js';
+export interface InstrumentHooks {
+    cursor: boolean;
+    callouts: boolean;
+    /** Recording-clock time, for callout timestamps. */
+    nowMs: () => number;
+    onCallout: (c: CalloutRecord) => void;
+}
+/**
+ * Wrap a Page so locators it produces animate the fake cursor and emit
+ * callout records before delegating to real Playwright methods. If an exotic
+ * call path escapes the proxy, the action still works — the cursor just
+ * doesn't move.
+ */
+export declare function instrumentPage(page: Page, hooks: InstrumentHooks): Page;

package/dist/browser/instrument.js

@@ -0,0 +1,114 @@
+import { CURSOR_TRAVEL_MS } from './cursor.js';
+import { logger } from '../util/logger.js';
+/** Locator methods that interact with an element (cursor should travel there first). */
+const ACTION_METHODS = new Set([
+    'click', 'dblclick', 'hover', 'fill', 'check', 'uncheck', 'setChecked',
+    'selectOption', 'tap', 'press', 'pressSequentially', 'type', 'clear',
+]);
+/** Subset that warrants a click pulse + callout ring. */
+const CLICK_METHODS = new Set([
+    'click', 'dblclick', 'check', 'uncheck', 'setChecked', 'selectOption', 'tap',
+]);
+/** Locator methods that return another Locator and must stay instrumented. */
+const CHAIN_METHODS = new Set([
+    'locator', 'getByRole', 'getByText', 'getByLabel', 'getByPlaceholder',
+    'getByTestId', 'getByTitle', 'getByAltText', 'first', 'last', 'nth',
+    'filter', 'and', 'or', 'describe',
+]);
+/** Page methods that return a Locator to instrument. */
+const PAGE_LOCATOR_METHODS = new Set([
+    'locator', 'getByRole', 'getByText', 'getByLabel', 'getByPlaceholder',
+    'getByTestId', 'getByTitle', 'getByAltText',
+]);
+/** Deprecated-but-supported page-level shortcuts taking a selector first arg. */
+const PAGE_ACTION_METHODS = new Set([
+    'click', 'dblclick', 'hover', 'fill', 'check', 'uncheck', 'selectOption', 'tap', 'press', 'type',
+]);
+/**
+ * Move the cursor to the target, pulse + ring on click-like actions, record
+ * the callout. Any failure here is swallowed: the action must still run.
+ */
+async function presentAction(page, target, method, hooks) {
+    if (!hooks.cursor && !hooks.callouts)
+        return;
+    try {
+        await target.waitFor({ state: 'visible', timeout: 5000 });
+        const box = await target.boundingBox();
+        if (!box)
+            return;
+        const cx = box.x + box.width / 2;
+        const cy = box.y + box.height / 2;
+        if (hooks.cursor) {
+            await page.evaluate(([x, y]) => window.__forgeCursor?.moveTo(x, y), [cx, cy]);
+            await page.waitForTimeout(CURSOR_TRAVEL_MS + 50);
+        }
+        if (CLICK_METHODS.has(method)) {
+            if (hooks.cursor) {
+                await page.evaluate(([x, y]) => window.__forgeCursor?.pulse(x, y), [cx, cy]);
+            }
+            if (hooks.callouts) {
+                await page.evaluate(([x, y, w, h]) => window.__forgeCallout?.(x, y, w, h), [box.x, box.y, box.width, box.height]);
+                hooks.onCallout({ atMs: hooks.nowMs(), x: box.x, y: box.y, w: box.width, h: box.height });
+            }
+        }
+    }
+    catch (err) {
+        logger.debug(`cursor presentation skipped for ${method}: ${err instanceof Error ? err.message : err}`);
+    }
+}
+function wrapLocator(locator, page, hooks) {
+    return new Proxy(locator, {
+        get(target, prop, receiver) {
+            const value = Reflect.get(target, prop, target);
+            if (typeof value !== 'function' || typeof prop !== 'string')
+                return value;
+            if (ACTION_METHODS.has(prop)) {
+                return async (...args) => {
+                    await presentAction(page, target, prop, hooks);
+                    return value.apply(target, args);
+                };
+            }
+            if (CHAIN_METHODS.has(prop)) {
+                return (...args) => {
+                    const result = value.apply(target, args);
+                    return isLocatorLike(result) ? wrapLocator(result, page, hooks) : result;
+                };
+            }
+            return value.bind(target);
+        },
+    });
+}
+function isLocatorLike(v) {
+    return !!v && typeof v.click === 'function' && typeof v.boundingBox === 'function';
+}
+/**
+ * Wrap a Page so locators it produces animate the fake cursor and emit
+ * callout records before delegating to real Playwright methods. If an exotic
+ * call path escapes the proxy, the action still works — the cursor just
+ * doesn't move.
+ */
+export function instrumentPage(page, hooks) {
+    return new Proxy(page, {
+        get(target, prop, receiver) {
+            const value = Reflect.get(target, prop, target);
+            if (typeof value !== 'function' || typeof prop !== 'string')
+                return value;
+            if (PAGE_LOCATOR_METHODS.has(prop)) {
+                return (...args) => {
+                    const result = value.apply(target, args);
+                    return isLocatorLike(result) ? wrapLocator(result, target, hooks) : result;
+                };
+            }
+            if (PAGE_ACTION_METHODS.has(prop)) {
+                return async (...args) => {
+                    if (typeof args[0] === 'string') {
+                        await presentAction(target, target.locator(args[0]), prop, hooks);
+                    }
+                    return value.apply(target, args);
+                };
+            }
+            return value.bind(target);
+        },
+    });
+}
+//# sourceMappingURL=instrument.js.map

package/dist/browser/instrument.js.map

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

package/dist/browser/timing.d.ts

@@ -0,0 +1,20 @@
+/** Recording clock: all manifest offsets are ms since zero(). */
+export declare class RecordingClock {
+    private zeroEpochMs;
+    zero(): void;
+    get zeroEpoch(): number;
+    /** ms since zero() */
+    now(): number;
+}
+/**
+ * Step pacing: the step holds until both the narration budget
+ * (leadIn + audio) and the action have completed, then settles.
+ * Pure function so the math is unit-testable.
+ */
+export declare function stepHoldUntilMs(input: {
+    startMs: number;
+    leadInMs: number;
+    audioDurationMs: number;
+    actionEndMs: number;
+    settleMs: number;
+}): number;

package/dist/browser/timing.js

@@ -0,0 +1,26 @@
+/** Recording clock: all manifest offsets are ms since zero(). */
+export class RecordingClock {
+    zeroEpochMs = 0;
+    zero() {
+        this.zeroEpochMs = Date.now();
+    }
+    get zeroEpoch() {
+        return this.zeroEpochMs;
+    }
+    /** ms since zero() */
+    now() {
+        if (this.zeroEpochMs === 0)
+            throw new Error('RecordingClock used before zero()');
+        return Date.now() - this.zeroEpochMs;
+    }
+}
+/**
+ * Step pacing: the step holds until both the narration budget
+ * (leadIn + audio) and the action have completed, then settles.
+ * Pure function so the math is unit-testable.
+ */
+export function stepHoldUntilMs(input) {
+    const narrationBudgetEnd = input.startMs + input.leadInMs + input.audioDurationMs;
+    return Math.max(narrationBudgetEnd, input.actionEndMs) + input.settleMs;
+}
+//# sourceMappingURL=timing.js.map

package/dist/browser/timing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timing.js","sourceRoot":"","sources":["../../src/browser/timing.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,MAAM,OAAO,cAAc;IACjB,WAAW,GAAG,CAAC,CAAC;IAExB,IAAI;QACF,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAChC,CAAC;IAED,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,WAAW,CAAC;IAC1B,CAAC;IAED,sBAAsB;IACtB,GAAG;QACD,IAAI,IAAI,CAAC,WAAW,KAAK,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;QACjF,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,WAAW,CAAC;IACvC,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,KAM/B;IACC,MAAM,kBAAkB,GAAG,KAAK,CAAC,OAAO,GAAG,KAAK,CAAC,QAAQ,GAAG,KAAK,CAAC,eAAe,CAAC;IAClF,OAAO,IAAI,CAAC,GAAG,CAAC,kBAAkB,EAAE,KAAK,CAAC,WAAW,CAAC,GAAG,KAAK,CAAC,QAAQ,CAAC;AAC1E,CAAC"}

package/dist/config.d.ts

@@ -0,0 +1,25 @@
+import type { TutorialAdapter, TTSProvider } from './types.js';
+/** Shape of forge.config.ts in a consumer repo. CLI flags override these; these override defaults. */
+export interface ForgeConfig {
+    adapter: TutorialAdapter;
+    tts: TTSProvider;
+    /** Where final videos land. Default: tutorials/dist */
+    outDir?: string;
+    /** Globs for tutorial discovery. Default: ["**\/*.tutorial.ts"] */
+    tutorials?: string[];
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    headless?: boolean;
+    cursor?: boolean;
+    callouts?: boolean;
+    subtitles?: 'burn' | 'sidecar' | 'off';
+    leadInMs?: number;
+    keepWorkDir?: boolean;
+    ttsCacheDir?: string;
+    ttsConcurrency?: number;
+}
+export declare function defineConfig(config: ForgeConfig): ForgeConfig;
+/** Validate a loaded config object (e.g. from forge.config.ts). Throws with a readable message. */
+export declare function validateConfig(config: unknown): ForgeConfig;

package/dist/config.js

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+const configSchema = z.object({
+    adapter: z.object({
+        baseURL: z.string().url(),
+        setup: z.function(),
+        teardown: z.function().optional(),
+    }),
+    tts: z.object({
+        cacheKey: z.string().min(1),
+        synthesize: z.function(),
+    }),
+    outDir: z.string().optional(),
+    tutorials: z.array(z.string()).optional(),
+    viewport: z.object({ width: z.number().int().positive(), height: z.number().int().positive() }).optional(),
+    headless: z.boolean().optional(),
+    cursor: z.boolean().optional(),
+    callouts: z.boolean().optional(),
+    subtitles: z.enum(['burn', 'sidecar', 'off']).optional(),
+    leadInMs: z.number().nonnegative().optional(),
+    keepWorkDir: z.boolean().optional(),
+    ttsCacheDir: z.string().optional(),
+    ttsConcurrency: z.number().int().positive().optional(),
+});
+export function defineConfig(config) {
+    return config;
+}
+/** Validate a loaded config object (e.g. from forge.config.ts). Throws with a readable message. */
+export function validateConfig(config) {
+    const parsed = configSchema.safeParse(config);
+    if (!parsed.success) {
+        const issues = parsed.error.issues.map((i) => `  ${i.path.join('.') || '(root)'}: ${i.message}`);
+        throw new Error(`Invalid forge config:\n${issues.join('\n')}`);
+    }
+    return config;
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAsBxB,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5B,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC;QAChB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;QACzB,KAAK,EAAE,CAAC,CAAC,QAAQ,EAAE;QACnB,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;KAClC,CAAC;IACF,GAAG,EAAE,CAAC,CAAC,MAAM,CAAC;QACZ,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;QAC3B,UAAU,EAAE,CAAC,CAAC,QAAQ,EAAE;KACzB,CAAC;IACF,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC7B,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;IACzC,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,QAAQ,EAAE;IAC1G,QAAQ,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IAChC,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IAC9B,QAAQ,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IAChC,SAAS,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,SAAS,EAAE,KAAK,CAAC,CAAC,CAAC,QAAQ,EAAE;IACxD,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,WAAW,EAAE,CAAC,QAAQ,EAAE;IAC7C,WAAW,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IACnC,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAClC,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;CACvD,CAAC,CAAC;AAEH,MAAM,UAAU,YAAY,CAAC,MAAmB;IAC9C,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,mGAAmG;AACnG,MAAM,UAAU,cAAc,CAAC,MAAe;IAC5C,MAAM,MAAM,GAAG,YAAY,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAC9C,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,QAAQ,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;QACjG,MAAM,IAAI,KAAK,CAAC,0BAA0B,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACjE,CAAC;IACD,OAAO,MAAqB,CAAC;AAC/B,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+export type { Tutorial, Step, TutorialAdapter, TTSProvider, RenderOptions, TimingManifest, ManifestStep, CalloutRecord, } from './types.js';
+export { StepError } from './types.js';
+export { tutorial, step, validateTutorial, stepId } from './spec.js';
+export { defineConfig, validateConfig, type ForgeConfig } from './config.js';
+export { render, type RenderResult } from './pipeline/render.js';
+export { runTTSPhase, loadTTSResult } from './pipeline/tts.js';
+export { runRecordPhase, loadManifest, RAW_VIDEO_FILE, MANIFEST_FILE } from './pipeline/record.js';
+export { runPostPhase } from './pipeline/post.js';
+export { SilentProvider } from './tts/silent.js';
+export { Piper, type PiperOptions } from './tts/piper.js';
+export { ElevenLabs, type ElevenLabsOptions } from './tts/elevenlabs.js';
+export { OpenAITTS, type OpenAITTSOptions } from './tts/openai.js';
+export { estimateDurationMs } from './tts/provider.js';
+export { defaultCacheDir, synthesizeCached } from './tts/cache.js';
+export { generateSrt, srtTime, wrapText } from './post/subtitles.js';
+export { buildMergeArgs, probeDurationMs, detectFlashOffsetMs, parseFlashFromMetadata, normalizeToWav, ffmpegVersion, type MergeArgsInput, } from './post/ffmpeg.js';
+export { stepHoldUntilMs } from './browser/timing.js';

package/dist/index.js

@@ -0,0 +1,18 @@
+// Public API surface — re-exports only.
+export { StepError } from './types.js';
+export { tutorial, step, validateTutorial, stepId } from './spec.js';
+export { defineConfig, validateConfig } from './config.js';
+export { render } from './pipeline/render.js';
+export { runTTSPhase, loadTTSResult } from './pipeline/tts.js';
+export { runRecordPhase, loadManifest, RAW_VIDEO_FILE, MANIFEST_FILE } from './pipeline/record.js';
+export { runPostPhase } from './pipeline/post.js';
+export { SilentProvider } from './tts/silent.js';
+export { Piper } from './tts/piper.js';
+export { ElevenLabs } from './tts/elevenlabs.js';
+export { OpenAITTS } from './tts/openai.js';
+export { estimateDurationMs } from './tts/provider.js';
+export { defaultCacheDir, synthesizeCached } from './tts/cache.js';
+export { generateSrt, srtTime, wrapText } from './post/subtitles.js';
+export { buildMergeArgs, probeDurationMs, detectFlashOffsetMs, parseFlashFromMetadata, normalizeToWav, ffmpegVersion, } from './post/ffmpeg.js';
+export { stepHoldUntilMs } from './browser/timing.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,wCAAwC;AAYxC,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEvC,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACrE,OAAO,EAAE,YAAY,EAAE,cAAc,EAAoB,MAAM,aAAa,CAAC;AAE7E,OAAO,EAAE,MAAM,EAAqB,MAAM,sBAAsB,CAAC;AACjE,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACnG,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAE,KAAK,EAAqB,MAAM,gBAAgB,CAAC;AAC1D,OAAO,EAAE,UAAU,EAA0B,MAAM,qBAAqB,CAAC;AACzE,OAAO,EAAE,SAAS,EAAyB,MAAM,iBAAiB,CAAC;AACnE,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEnE,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACrE,OAAO,EACL,cAAc,EACd,eAAe,EACf,mBAAmB,EACnB,sBAAsB,EACtB,cAAc,EACd,aAAa,GAEd,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/pipeline/post.d.ts

@@ -0,0 +1,22 @@
+import type { TimingManifest } from '../types.js';
+export interface PostPhaseOptions {
+    workDir: string;
+    output: string;
+    viewport: {
+        width: number;
+        height: number;
+    };
+    subtitles: 'burn' | 'sidecar' | 'off';
+    leadInMs: number;
+}
+export interface PostPhaseResult {
+    output: string;
+    srtPath: string | null;
+    videoClockOffsetMs: number;
+    outputDurationMs: number;
+}
+/**
+ * Phase 3 — single ffmpeg invocation: trim pre-roll/tail, lay narration over
+ * silence at manifest offsets, downscale 2x→1x, transcode to H.264/AAC.
+ */
+export declare function runPostPhase(manifest: TimingManifest, opts: PostPhaseOptions): Promise<PostPhaseResult>;

package/dist/pipeline/post.js

@@ -0,0 +1,63 @@
+import { join, dirname, basename, extname } from 'node:path';
+import { writeFile } from 'node:fs/promises';
+import { RAW_VIDEO_FILE } from './record.js';
+import { buildMergeArgs, detectFlashOffsetMs, probeDurationMs, runFfmpeg } from '../post/ffmpeg.js';
+import { generateSrt } from '../post/subtitles.js';
+import { ensureDir, exists } from '../util/fs.js';
+import { logger } from '../util/logger.js';
+/**
+ * Phase 3 — single ffmpeg invocation: trim pre-roll/tail, lay narration over
+ * silence at manifest offsets, downscale 2x→1x, transcode to H.264/AAC.
+ */
+export async function runPostPhase(manifest, opts) {
+    const rawVideo = join(opts.workDir, RAW_VIDEO_FILE);
+    if (!(await exists(rawVideo))) {
+        throw new Error(`No ${RAW_VIDEO_FILE} in ${opts.workDir} — run the record phase first`);
+    }
+    const firstStep = manifest.steps[0];
+    if (!firstStep)
+        throw new Error('Manifest has no steps');
+    const trimStartMs = Math.max(0, firstStep.startMs - opts.leadInMs);
+    let videoOffsetMs = await detectFlashOffsetMs(rawVideo);
+    if (videoOffsetMs === null) {
+        logger.warn('calibration flash not found in recording — assuming video starts at clock zero; audio sync may drift by the context-creation gap');
+        videoOffsetMs = 0;
+    }
+    else {
+        logger.debug(`calibration flash at ${videoOffsetMs}ms into raw video`);
+    }
+    manifest.videoClockOffsetMs = videoOffsetMs;
+    await ensureDir(dirname(opts.output));
+    let srtPath = null;
+    if (opts.subtitles !== 'off') {
+        const srt = generateSrt(manifest, { leadInMs: opts.leadInMs, trimStartMs });
+        srtPath =
+            opts.subtitles === 'sidecar'
+                ? join(dirname(opts.output), basename(opts.output, extname(opts.output)) + '.srt')
+                : join(opts.workDir, 'subtitles.srt');
+        await writeFile(srtPath, srt);
+    }
+    const args = buildMergeArgs({
+        rawVideo,
+        manifest,
+        audioFiles: manifest.steps.map((s) => s.audioFile),
+        output: opts.output,
+        leadInMs: opts.leadInMs,
+        trimStartMs,
+        videoOffsetMs,
+        targetWidth: opts.viewport.width,
+        targetHeight: opts.viewport.height,
+        burnSrt: opts.subtitles === 'burn' && srtPath ? srtPath : undefined,
+    });
+    logger.info('post: merging audio + video (ffmpeg)');
+    await runFfmpeg(args);
+    const outputDurationMs = await probeDurationMs(opts.output);
+    logger.info(`post: wrote ${opts.output} (${(outputDurationMs / 1000).toFixed(1)}s)`);
+    return {
+        output: opts.output,
+        srtPath: opts.subtitles === 'sidecar' ? srtPath : null,
+        videoClockOffsetMs: videoOffsetMs,
+        outputDurationMs,
+    };
+}
+//# sourceMappingURL=post.js.map

package/dist/pipeline/post.js.map

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

package/dist/pipeline/record.d.ts

@@ -0,0 +1,23 @@
+import type { TimingManifest, Tutorial, TutorialAdapter } from '../types.js';
+import type { TTSPhaseResult } from './tts.js';
+export declare const RAW_VIDEO_FILE = "raw.webm";
+export declare const MANIFEST_FILE = "manifest.json";
+export interface RecordPhaseOptions {
+    workDir: string;
+    viewport: {
+        width: number;
+        height: number;
+    };
+    headless: boolean;
+    cursor: boolean;
+    callouts: boolean;
+    leadInMs: number;
+}
+/**
+ * Phase 2 — drive the browser through the tutorial while Playwright records
+ * video, pacing each step to its narration budget. Writes raw.webm and
+ * manifest.json into workDir.
+ */
+export declare function runRecordPhase(tutorial: Tutorial, adapter: TutorialAdapter, tts: TTSPhaseResult, opts: RecordPhaseOptions): Promise<TimingManifest>;
+/** Load a previous run's manifest.json (for `--phase post`). */
+export declare function loadManifest(workDir: string): Promise<TimingManifest>;