@arbidocs/blocks 0.4.106 → 0.4.108

package/dist/record/index.d.ts

@@ -1,27 +1,3 @@
-/**
- * Cinematic recording harness — host-agnostic.
- *
- * Turns a Playwright run into a narrated product demo: a visible cursor that
- * glides between targets, a click ripple, a caption bar that narrates each step,
- * full-screen chapter "cover" cards, and human-speed pacing. Every host app gets
- * the same polished demo capability from one factory — brand colours, fonts,
- * credentials and the login flow arrive as config, so nothing here names a host.
- *
- * Pair with a Playwright project that records video (see the host's
- * `playwright.record.config.ts`: video on, a large viewport, some slowMo).
- *
- * Usage in a `*.record.ts` spec:
- *   const cine = createCinematic({ brand, creds })
- *   await cine.installStage(page)          // before the first navigation
- *   await cine.cover(page, { kicker, title, subtitle })
- *   await cine.login(page)
- *   await cine.uncover(page)
- *   await cine.caption(page, "Opening the flagship matter…")
- *   await cine.click(page, "matters-row-…")
- *
- * `@playwright/test` is an optional peer used for TYPES only (no runtime import), so
- * importing this entry never loads Playwright.
- */
 import type { Page, Locator } from '@playwright/test';
 /** Brand skin for the on-screen chrome. All optional — sensible neutral defaults. */
 export interface CinematicBrand {
@@ -44,12 +20,22 @@ export interface CinematicBrand {
         mid: string;
         to: string;
     };
-    /** Accent (kicker text + rule) on chapter cards. */
+    /** Accent (kicker text + rule) on chapter cards, callouts and lower-thirds. */
     accent?: string;
     /** Caption bar background base colour. */
     ink?: string;
     /** Cover title text colour. */
     coverTitle?: string;
+    /**
+     * Font files for the edit's overlays (cards, captions), when the display or sans font is not
+     * installed where the video is rendered: each a family name and a `file://` or `https://` URL.
+     */
+    fontFiles?: {
+        family: string;
+        url: string;
+        weight?: string;
+        unicodeRange?: string;
+    }[];
 }
 export interface CinematicCreds {
     email: string;
@@ -57,7 +43,8 @@ export interface CinematicCreds {
 }
 export interface CinematicConfig {
     brand: CinematicBrand;
-    creds: CinematicCreds;
+    /** For `login`. */
+    creds?: CinematicCreds;
     /** Login route (default "/app/login"). */
     loginPath?: string;
     /** URL the app lands on after auth (default /\/app$/). */
@@ -69,24 +56,156 @@ export interface CinematicConfig {
         submit?: string;
     };
 }
+/** A box on screen, in page pixels. */
+export interface Box {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * A moment the edit may frame: a click, typing, reading down a result, a glide-and-look (`point`,
+ * which lasts until the next gesture), or a key moment marked with `focusOn`.
+ */
+export interface FocusEvent {
+    kind: 'click' | 'type' | 'read' | 'point' | 'focus';
+    label?: string;
+    start: number;
+    end?: number;
+    box: Box;
+    /** Draw a highlight (and the label as its tag) round the box. */
+    callout?: boolean;
+    /** How to frame it: zoom in, a picture-in-picture inset, or not at all (default: the edit decides). */
+    mode?: 'zoom' | 'pip' | 'none';
+}
+/** A take's say in its edit. */
+export interface TakeOptions {
+    /** The take's name: its files are `<dir>/<name>.waits.json` and `<dir>/<name>.focus.json`. */
+    name: string;
+    /** Where the take's files go (default `recordings`). */
+    dir?: string;
+    /** Zoom and pan onto the action (default true). */
+    zoom?: boolean;
+    /** At most this much (default 1.8). */
+    maxZoom?: number;
+    /** A picture-in-picture inset for long typing (default true). */
+    pip?: boolean;
+}
+export interface Wait {
+    label: string;
+    start: number;
+    end: number;
+}
+interface Card {
+    kicker: string;
+    title: string;
+    subtitle?: string;
+    start: number;
+    end: number | null;
+}
+/** The timecode's square, in page pixels (the renderer reads it at this size). */
+export declare const TIMECODE_CELL = 8;
+/**
+ * One recorded take: its clock, its waits and its focus timeline. Start it first thing (the video
+ * starts with the page, a moment before; `markSync` lines the two clocks up exactly).
+ */
+export declare class Take {
+    readonly page: Page;
+    private readonly options;
+    /** The take running now (one at a time: recordings run one after another). */
+    private static active;
+    readonly t0: number;
+    readonly waits: Wait[];
+    /** The brand the edit paints the cards, captions and callouts in. */
+    private readonly brand;
+    readonly file: string;
+    readonly focusFile: string;
+    private readonly timeline;
+    constructor(page: Page, options: TakeOptions, brand?: CinematicBrand);
+    /** The take running on `page`, if any. */
+    static on(page: Page): Take | null;
+    /** Seconds since the take started. */
+    now(): number;
+    /** Log a wait (written at once, so a take that fails part-way still has its cut list). */
+    log(label: string, start: number, end?: number): void;
+    /** Wait for `until` (a UI state), logged as a wait the edit may cut. */
+    wait<T>(label: string, until: () => Promise<T>): Promise<T>;
+    /**
+     * Paint the sync marker: a magenta frame for a moment, at a logged time. The edit finds it in the
+     * video and lines the take's clock up with the video's. Call it before the first navigation.
+     */
+    markSync(): Promise<void>;
+    /** Log a focus event (a `point` with no end lasts until the next event). */
+    record(event: Omit<FocusEvent, 'start' | 'end'> & {
+        start: number;
+        end?: number;
+    }): void;
+    /** @internal The stage's cards, lower-thirds and captions (drawn by the edit). */
+    cardStart(card: Omit<Card, 'start' | 'end'>): void;
+    cardEnd(): void;
+    lowerThird(kicker: string, title: string, holdMs: number): void;
+    captionStart(text: string): void;
+    captionEnd(): void;
+    private save;
+}
 export interface Cinematic {
+    /** Start a take on `page` (before `installStage`, so the stage paints its timecode). */
+    take(page: Page, options: TakeOptions): Promise<Take>;
     installStage(page: Page): Promise<void>;
     cover(page: Page, opts: {
         kicker: string;
         title: string;
         subtitle?: string;
     }, holdMs?: number): Promise<void>;
+    /** A cover the work can go on behind (clicks pass through it) until `uncover`. */
+    chapter(page: Page, opts: {
+        kicker: string;
+        title: string;
+        subtitle?: string;
+    }, holdMs?: number): Promise<void>;
     uncover(page: Page): Promise<void>;
+    /** A section's name over the bottom left while the work goes on (drawn by the edit). */
+    lowerThird(page: Page, kicker: string, title: string, holdMs?: number): void;
     caption(page: Page, text: string, holdMs?: number): Promise<void>;
     clearCaption(page: Page): Promise<void>;
     beat(page: Page, ms?: number): Promise<void>;
     glideTo(page: Page, target: string | Locator): Promise<Locator>;
     click(page: Page, target: string | Locator): Promise<void>;
     type(page: Page, target: string | Locator, text: string): Promise<void>;
+    /** A key moment: glide to it and hold; the edit zooms onto it and draws a callout with `label`. */
+    focusOn(page: Page, target: string | Locator, label?: string, opts?: {
+        holdMs?: number;
+        callout?: boolean;
+        mode?: FocusEvent['mode'];
+    }): Promise<void>;
+    /** Read down a result at a reader's pace, then back to the top. */
+    readDown(page: Page, target: string | Locator, scrolls?: number, pauseMs?: number): Promise<void>;
     /** Sign in. `{ show: false }` authenticates fast + silent (no animation/caption). */
     login(page: Page, opts?: {
         show?: boolean;
         caption?: string;
     }): Promise<void>;
 }
+/** A brand with every default filled in: what the stage paints and the take hands the edit. */
+export declare function cinematicSkin(b: CinematicBrand): {
+    firmLabel: string;
+    displayFont: string;
+    sansFont: string;
+    cursorFrom: string;
+    cursorTo: string;
+    ripple: string;
+    coverFrom: string;
+    coverMid: string;
+    coverTo: string;
+    accent: string;
+    ink: string;
+    coverTitle: string;
+    fontFiles: {
+        family: string;
+        url: string;
+        weight?: string;
+        unicodeRange?: string;
+    }[];
+};
 export declare function createCinematic(config: CinematicConfig): Cinematic;
+export {};

package/dist/record/index.js

@@ -1,4 +1,135 @@
+import { mkdirSync, writeFileSync } from 'fs';
+import path from 'path';
+
 // src/record/index.ts
+var TIMECODE_CELL = 8;
+var round = (n) => Math.round(n * 100) / 100;
+var Take = class _Take {
+  constructor(page, options, brand) {
+    this.page = page;
+    this.options = options;
+    this.brand = brand ? cinematicSkin(brand) : {};
+    const dir = path.resolve(options.dir ?? "recordings");
+    this.file = path.join(dir, `${options.name}.waits.json`);
+    this.focusFile = path.join(dir, `${options.name}.focus.json`);
+    this.timeline.viewport = page.viewportSize();
+    mkdirSync(dir, { recursive: true });
+    _Take.active = this;
+    this.save();
+  }
+  page;
+  options;
+  /** The take running now (one at a time: recordings run one after another). */
+  static active = null;
+  t0 = Date.now();
+  waits = [];
+  /** The brand the edit paints the cards, captions and callouts in. */
+  brand;
+  file;
+  focusFile;
+  timeline = {
+    sync: null,
+    viewport: null,
+    focus: [],
+    cards: [],
+    lowerThirds: [],
+    captions: []
+  };
+  /** The take running on `page`, if any. */
+  static on(page) {
+    return _Take.active?.page === page ? _Take.active : null;
+  }
+  /** Seconds since the take started. */
+  now() {
+    return (Date.now() - this.t0) / 1e3;
+  }
+  /** Log a wait (written at once, so a take that fails part-way still has its cut list). */
+  log(label, start, end = this.now()) {
+    if (end - start < 1) return;
+    this.waits.push({ label, start: round(start), end: round(end) });
+    this.save();
+  }
+  /** Wait for `until` (a UI state), logged as a wait the edit may cut. */
+  async wait(label, until) {
+    const start = this.now();
+    try {
+      return await until();
+    } finally {
+      this.log(label, start);
+    }
+  }
+  /**
+   * Paint the sync marker: a magenta frame for a moment, at a logged time. The edit finds it in the
+   * video and lines the take's clock up with the video's. Call it before the first navigation.
+   */
+  async markSync() {
+    await this.page.evaluate(
+      () => new Promise((done) => {
+        document.documentElement.style.background = "#ff00ff";
+        if (document.body) document.body.style.background = "#ff00ff";
+        requestAnimationFrame(() => requestAnimationFrame(() => done()));
+      })
+    );
+    this.timeline.sync = round(this.now());
+    await this.page.waitForTimeout(400);
+    this.save();
+  }
+  /** Log a focus event (a `point` with no end lasts until the next event). */
+  record(event) {
+    const { focus } = this.timeline;
+    const open = focus[focus.length - 1];
+    if (open && open.kind === "point" && open.end === void 0) open.end = round(event.start);
+    focus.push({
+      ...event,
+      start: round(event.start),
+      end: event.end === void 0 ? void 0 : round(event.end)
+    });
+    this.save();
+  }
+  /** @internal The stage's cards, lower-thirds and captions (drawn by the edit). */
+  cardStart(card) {
+    this.cardEnd();
+    this.captionEnd();
+    this.timeline.cards.push({ ...card, start: round(this.now()), end: null });
+    this.save();
+  }
+  cardEnd() {
+    const last = this.timeline.cards[this.timeline.cards.length - 1];
+    if (last && last.end === null) {
+      last.end = round(this.now());
+      this.save();
+    }
+  }
+  lowerThird(kicker, title, holdMs) {
+    const start = round(this.now());
+    this.timeline.lowerThirds.push({ kicker, title, start, end: round(start + holdMs / 1e3) });
+    this.save();
+  }
+  captionStart(text) {
+    this.captionEnd();
+    this.timeline.captions.push({ text, start: round(this.now()), end: null });
+    this.save();
+  }
+  captionEnd() {
+    const last = this.timeline.captions[this.timeline.captions.length - 1];
+    if (last && last.end === null) {
+      last.end = round(this.now());
+      this.save();
+    }
+  }
+  save() {
+    const { zoom, maxZoom, pip } = this.options;
+    writeFileSync(this.file, JSON.stringify({ t0: this.t0, waits: this.waits }, null, 1));
+    writeFileSync(
+      this.focusFile,
+      JSON.stringify(
+        { t0: this.t0, config: { zoom, maxZoom, pip }, brand: this.brand, ...this.timeline },
+        null,
+        1
+      )
+    );
+  }
+};
 var DEFAULTS = {
   displayFont: "ui-serif, Georgia, serif",
   sansFont: "Inter, ui-sans-serif, system-ui, sans-serif",
@@ -9,9 +140,8 @@ var DEFAULTS = {
   ink: "#0e1b2d",
   coverTitle: "#f4f6f8"
 };
-function createCinematic(config) {
-  const b = config.brand;
-  const skin = {
+function cinematicSkin(b) {
+  return {
     firmLabel: b.firmLabel,
     displayFont: b.displayFont ?? DEFAULTS.displayFont,
     sansFont: b.sansFont ?? DEFAULTS.sansFont,
@@ -23,8 +153,13 @@ function createCinematic(config) {
     coverTo: b.cover?.to ?? DEFAULTS.cover.to,
     accent: b.accent ?? DEFAULTS.accent,
     ink: b.ink ?? DEFAULTS.ink,
-    coverTitle: b.coverTitle ?? DEFAULTS.coverTitle
+    coverTitle: b.coverTitle ?? DEFAULTS.coverTitle,
+    fontFiles: b.fontFiles ?? []
   };
+}
+function createCinematic(config) {
+  const b = config.brand;
+  const skin = cinematicSkin(b);
   const loginPath = config.loginPath ?? "/app/login";
   const appUrlPattern = config.appUrlPattern ?? /\/app$/;
   const ids = {
@@ -33,113 +168,207 @@ function createCinematic(config) {
     submit: config.testIds?.submit ?? "auth-login-submit"
   };
   const resolve = (page, t) => typeof t === "string" ? page.getByTestId(t) : t;
+  async function boxOf(page, loc) {
+    const box = await loc.boundingBox().catch(() => null);
+    const vp = page.viewportSize();
+    if (!box || !vp) return box;
+    const x = Math.max(box.x, 0);
+    const y = Math.max(box.y, 0);
+    const width = Math.min(box.x + box.width, vp.width) - x;
+    const height = Math.min(box.y + box.height, vp.height) - y;
+    return width > 0 && height > 0 ? { x: round(x), y: round(y), width: round(width), height: round(height) } : null;
+  }
+  async function glide(page, target) {
+    const loc = resolve(page, target).first();
+    await loc.scrollIntoViewIfNeeded().catch(() => {
+    });
+    const box = await boxOf(page, loc);
+    if (box) {
+      await page.mouse.move(box.x + box.width / 2, box.y + box.height / 2, { steps: 26 });
+      await page.waitForTimeout(180);
+    }
+    return { loc, box };
+  }
+  async function take(page, options) {
+    return new Take(page, options, b);
+  }
   async function installStage(page) {
-    await page.addInitScript((s) => {
-      const boot = () => {
-        if (document.getElementById("__cine_cursor")) return;
-        const cursor = document.createElement("div");
-        cursor.id = "__cine_cursor";
-        cursor.style.cssText = `position:fixed;left:0;top:0;z-index:2147483647;width:22px;height:22px;margin:-11px 0 0 -11px;border-radius:50%;pointer-events:none;transition:transform .09s ease-out;background:radial-gradient(circle at 35% 35%, ${s.cursorFrom}, ${s.cursorTo});box-shadow:0 0 0 3px rgba(255,255,255,.6),0 2px 10px rgba(0,0,0,.4);`;
-        document.body.appendChild(cursor);
-        window.addEventListener(
-          "mousemove",
-          (e) => {
-            cursor.style.transform = `translate(${e.clientX}px,${e.clientY}px)`;
-          },
-          true
-        );
-        window.addEventListener(
-          "mousedown",
-          (e) => {
-            const m = e;
-            const r = document.createElement("div");
-            r.style.cssText = `position:fixed;left:${m.clientX}px;top:${m.clientY}px;z-index:2147483646;width:12px;height:12px;margin:-6px 0 0 -6px;border-radius:50%;pointer-events:none;border:2px solid ${s.ripple};animation:__cine_ripple .55s ease-out forwards;`;
-            document.body.appendChild(r);
-            setTimeout(() => r.remove(), 600);
-          },
-          true
-        );
-        const cap = document.createElement("div");
-        cap.id = "__cine_cap";
-        cap.style.cssText = `position:fixed;left:50%;bottom:34px;transform:translateX(-50%) translateY(8px);z-index:2147483646;max-width:72%;padding:13px 24px;border-radius:13px;font:500 17px/1.45 ${s.sansFont};color:#fff;letter-spacing:.01em;background:${s.ink}e0;backdrop-filter:blur(7px);box-shadow:0 10px 34px rgba(0,0,0,.4);text-align:center;opacity:0;transition:opacity .35s,transform .35s;`;
-        document.body.appendChild(cap);
-        const style = document.createElement("style");
-        style.textContent = "@keyframes __cine_ripple{to{width:46px;height:46px;margin:-23px 0 0 -23px;opacity:0}}";
-        document.head.appendChild(style);
-        window.__cine_cap = (t) => {
-          cap.textContent = t;
-          cap.style.opacity = t ? "1" : "0";
-          cap.style.transform = `translateX(-50%) translateY(${t ? 0 : 8}px)`;
+    await page.addInitScript(
+      ({ s, t0, TC }) => {
+        const boot = () => {
+          if (document.getElementById("__cine_cursor")) return;
+          const cursor = document.createElement("div");
+          cursor.id = "__cine_cursor";
+          cursor.style.cssText = `position:fixed;left:0;top:0;z-index:2147483647;width:22px;height:22px;margin:-11px 0 0 -11px;border-radius:50%;pointer-events:none;transition:transform .09s ease-out;background:radial-gradient(circle at 35% 35%, ${s.cursorFrom}, ${s.cursorTo});box-shadow:0 0 0 3px rgba(255,255,255,.6),0 2px 10px rgba(0,0,0,.4);`;
+          document.body.appendChild(cursor);
+          window.addEventListener(
+            "mousemove",
+            (e) => {
+              cursor.style.transform = `translate(${e.clientX}px,${e.clientY}px)`;
+            },
+            true
+          );
+          window.addEventListener(
+            "mousedown",
+            (e) => {
+              const m = e;
+              const r = document.createElement("div");
+              r.style.cssText = `position:fixed;left:${m.clientX}px;top:${m.clientY}px;z-index:2147483646;width:12px;height:12px;margin:-6px 0 0 -6px;border-radius:50%;pointer-events:none;border:2px solid ${s.ripple};animation:__cine_ripple .55s ease-out forwards;`;
+              document.body.appendChild(r);
+              setTimeout(() => r.remove(), 600);
+            },
+            true
+          );
+          const cap = document.createElement("div");
+          cap.id = "__cine_cap";
+          cap.style.cssText = `position:fixed;left:50%;bottom:34px;transform:translateX(-50%) translateY(8px);z-index:2147483646;max-width:72%;padding:13px 24px;border-radius:13px;font:500 17px/1.45 ${s.sansFont};color:#fff;letter-spacing:.01em;background:${s.ink}e0;backdrop-filter:blur(7px);box-shadow:0 10px 34px rgba(0,0,0,.4);text-align:center;opacity:0;transition:opacity .35s,transform .35s;`;
+          document.body.appendChild(cap);
+          const style = document.createElement("style");
+          style.textContent = "@keyframes __cine_ripple{to{width:46px;height:46px;margin:-23px 0 0 -23px;opacity:0}}";
+          document.head.appendChild(style);
+          window.__cine_cap = (t) => {
+            cap.textContent = t;
+            cap.style.opacity = t ? "1" : "0";
+            cap.style.transform = `translateX(-50%) translateY(${t ? 0 : 8}px)`;
+          };
+          if (t0 !== null) {
+            const strip = document.createElement("div");
+            strip.id = "__cine_timecode";
+            strip.style.cssText = `position:fixed;right:0;bottom:0;z-index:2147483647;display:flex;pointer-events:none;height:${TC}px`;
+            const cells = Array.from({ length: 18 }, (_, i) => {
+              const cell = document.createElement("div");
+              cell.style.cssText = `width:${TC}px;height:${TC}px;background:${i === 0 ? "#fff" : "#000"}`;
+              strip.appendChild(cell);
+              return cell;
+            });
+            document.body.appendChild(strip);
+            const tick = () => {
+              const ds = Math.max(0, Math.round((Date.now() - t0) / 100)) & 65535;
+              for (let bit = 0; bit < 16; bit += 1)
+                cells[bit + 2].style.background = ds >> 15 - bit & 1 ? "#fff" : "#000";
+              requestAnimationFrame(tick);
+            };
+            tick();
+          }
         };
-      };
-      if (document.body) boot();
-      else document.addEventListener("DOMContentLoaded", boot);
-    }, skin);
+        if (document.body) boot();
+        else document.addEventListener("DOMContentLoaded", boot);
+      },
+      { s: skin, t0: Take.on(page)?.t0 ?? null, TC: TIMECODE_CELL }
+    );
   }
   async function cover(page, { kicker, title, subtitle }, holdMs = 2600) {
+    const running = Take.on(page);
+    running?.cardStart({ kicker, title, subtitle });
     await page.evaluate(
-      ({ kicker: kicker2, title: title2, subtitle: subtitle2, s }) => {
+      ({ kicker: kicker2, title: title2, subtitle: subtitle2, s, instant }) => {
         document.getElementById("__cine_cover")?.remove();
         const el = document.createElement("div");
         el.id = "__cine_cover";
-        el.style.cssText = `position:fixed;inset:0;z-index:2147483647;display:flex;flex-direction:column;align-items:center;justify-content:center;text-align:center;padding:0 8%;background:linear-gradient(135deg,${s.coverFrom} 0%,${s.coverMid} 48%,${s.coverTo} 165%);opacity:0;transition:opacity .5s ease;font-family:${s.sansFont};`;
+        el.style.cssText = `position:fixed;inset:0;z-index:2147483647;display:flex;flex-direction:column;align-items:center;justify-content:center;text-align:center;padding:0 8%;background:linear-gradient(135deg,${s.coverFrom} 0%,${s.coverMid} 48%,${s.coverTo} 165%);opacity:${instant ? 1 : 0};transition:opacity ${instant ? 0 : 0.5}s ease;font-family:${s.sansFont};`;
         el.innerHTML = `<div style="text-transform:uppercase;letter-spacing:.26em;font-size:13px;font-weight:600;color:${s.accent};margin-bottom:22px">${kicker2}</div><div style="font-family:${s.displayFont};font-weight:600;font-size:52px;line-height:1.08;letter-spacing:-.02em;color:${s.coverTitle};max-width:16ch">${title2}</div>` + (subtitle2 ? `<div style="margin-top:22px;font-size:19px;line-height:1.5;color:${s.coverTitle}b8;max-width:46ch">${subtitle2}</div>` : "") + `<div style="margin-top:44px;display:flex;align-items:center;gap:10px;color:${s.coverTitle}80;font-size:13px;letter-spacing:.02em"><span style="width:26px;height:1px;background:${s.accent}"></span>${s.firmLabel}</div>`;
         document.body.appendChild(el);
         requestAnimationFrame(() => el.style.opacity = "1");
       },
-      { kicker, title, subtitle: subtitle ?? "", s: skin }
+      { kicker, title, subtitle: subtitle ?? "", s: skin, instant: !!running }
     );
     await page.waitForTimeout(holdMs);
   }
-  async function uncover(page) {
+  async function chapter(page, card, holdMs) {
+    await cover(page, card, holdMs);
     await page.evaluate(() => {
+      const el = document.getElementById("__cine_cover");
+      if (el) el.style.pointerEvents = "none";
+    });
+  }
+  async function uncover(page) {
+    const running = Take.on(page);
+    await page.evaluate((instant) => {
       const el = document.getElementById("__cine_cover");
       if (!el) return;
+      if (instant) return el.remove();
       el.style.opacity = "0";
       setTimeout(() => el.remove(), 520);
-    });
+    }, !!running);
+    running?.cardEnd();
     await page.waitForTimeout(560);
   }
+  function lowerThird(page, kicker, title, holdMs = 3200) {
+    Take.on(page)?.lowerThird(kicker, title, holdMs);
+  }
   async function caption(page, text, holdMs) {
-    await page.evaluate(
-      (t) => window.__cine_cap?.(t),
-      text
-    );
+    const running = Take.on(page);
+    if (running) running.captionStart(text);
+    else
+      await page.evaluate(
+        (t) => window.__cine_cap?.(t),
+        text
+      );
     const hold = holdMs ?? Math.min(4200, 900 + text.length * 45);
     await page.waitForTimeout(hold);
   }
   async function clearCaption(page) {
-    await page.evaluate(
-      () => window.__cine_cap?.("")
-    );
+    const running = Take.on(page);
+    if (running) running.captionEnd();
+    else
+      await page.evaluate(
+        () => window.__cine_cap?.("")
+      );
   }
   async function beat(page, ms = 650) {
     await page.waitForTimeout(ms);
   }
   async function glideTo(page, target) {
-    const loc = resolve(page, target).first();
-    await loc.scrollIntoViewIfNeeded().catch(() => {
-    });
-    const box = await loc.boundingBox();
-    if (box) {
-      await page.mouse.move(box.x + box.width / 2, box.y + box.height / 2, { steps: 26 });
-      await page.waitForTimeout(180);
-    }
+    const running = Take.on(page);
+    const start = running?.now() ?? 0;
+    const { loc, box } = await glide(page, target);
+    if (running && box) running.record({ kind: "point", start, box });
     return loc;
   }
   async function click(page, target) {
-    const loc = await glideTo(page, target);
+    const running = Take.on(page);
+    const start = running?.now() ?? 0;
+    const { loc, box } = await glide(page, target);
     await loc.click();
     await page.waitForTimeout(260);
+    if (running && box) running.record({ kind: "click", start, end: running.now(), box });
   }
   async function type(page, target, text) {
-    const loc = await glideTo(page, target);
+    const running = Take.on(page);
+    const start = running?.now() ?? 0;
+    const { loc, box } = await glide(page, target);
     await loc.click();
     await loc.fill("");
     await loc.pressSequentially(text, { delay: 42 });
     await page.waitForTimeout(240);
+    if (running && box) running.record({ kind: "type", start, end: running.now(), box });
+  }
+  async function focusOn(page, target, label, {
+    holdMs = 2200,
+    callout = true,
+    mode
+  } = {}) {
+    const running = Take.on(page);
+    const start = running?.now() ?? 0;
+    const { box } = await glide(page, target);
+    await page.waitForTimeout(holdMs);
+    if (running && box)
+      running.record({ kind: "focus", label, start, end: running.now(), box, callout, mode });
+  }
+  async function readDown(page, target, scrolls = 3, pauseMs = 1600) {
+    const running = Take.on(page);
+    const start = running?.now() ?? 0;
+    const { box } = await glide(page, target);
+    for (let i = 0; i < scrolls; i += 1) {
+      await page.mouse.wheel(0, 320);
+      await beat(page, pauseMs);
+    }
+    await page.mouse.wheel(0, -320 * scrolls);
+    await beat(page, 500);
+    if (running && box) running.record({ kind: "read", start, end: running.now(), box });
   }
   async function login(page, opts = {}) {
+    if (!config.creds) throw new Error("createCinematic: pass creds to sign in");
     await page.goto(loginPath);
     if (opts.show === false) {
       await page.getByTestId(ids.email).fill(config.creds.email);
@@ -156,19 +385,24 @@ function createCinematic(config) {
     await beat(page, 800);
   }
   return {
+    take,
     installStage,
     cover,
+    chapter,
     uncover,
+    lowerThird,
     caption,
     clearCaption,
     beat,
     glideTo,
     click,
     type,
+    focusOn,
+    readDown,
     login
   };
 }
 
-export { createCinematic };
+export { TIMECODE_CELL, Take, cinematicSkin, createCinematic };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map