recordable 0.1.0

package/dist/compose/recordable.d.ts

@@ -0,0 +1,149 @@
+import { type GoToOptions } from "puppeteer";
+import { type AudioOptions, type InsertOptions, type RecordableConfig, type WaitForOptions } from "../config.js";
+import { type Script } from "../script.js";
+export declare class Recordable {
+    private cfg;
+    private readonly userConfig;
+    private readonly log;
+    private readonly recorder;
+    private readonly audioTrack;
+    private readonly runtime;
+    private queue;
+    private pending;
+    private recording;
+    constructor(config?: RecordableConfig);
+    /** Load a JSON script — an array of actions, a `{ config, actions }` object, or a
+     *  raw JSON string — enqueuing each action. Returns `this` to chain into `.run()`. */
+    fromJSON(script: Script | string): this;
+    /**
+     * Load a Markdown document — synchronous and chainable. The `voiceover`
+     * frontmatter key picks the path: present → synthesize narration + computed
+     * waits (the add-on, dynamically imported so a no-audio run never loads TTS),
+     * deferred to `run()`; absent → flatten markers to a plain chain now. Caller
+     * reads the file (and loads any `.env`).
+     */
+    fromMarkdown(md: string): this;
+    /** Synthesize a voiceover document and splice its actions into the queue at the
+     *  position `fromMarkdown` was called (so chaining order is preserved). */
+    private _stageVoiceover;
+    /** Merge config mid-sequence — enqueued so it takes effect at this point. */
+    setConfig(config: RecordableConfig): this;
+    /**
+     * Stop capturing. The chain keeps running — anything between `pause()` and the
+     * next resume executes off-camera (page loads, logins, data setup) and is
+     * omitted from the final video. Place it first to skip the cold open.
+     */
+    pause(): this;
+    /** Resume capturing in a fresh segment, immediately. */
+    resume(): this;
+    /**
+     * Resume capturing, but only once the user *plays* — clicks the in-page ▶ Play
+     * button (or presses Enter in the terminal). Use for manual actions such as a
+     * login: `pause()` first, sign in by hand (headful), then `resumeOnInput()`.
+     */
+    resumeOnInput(message?: string): this;
+    /**
+     * Splice an external video clip into the timeline at this point — first call =
+     * intro, last = outro, anywhere between = mid-roll. The clip is normalized to
+     * the recording's resolution / fps / codec so the join stays seamless.
+     *
+     * Pass `fadeIn` / `fadeOut` (ms) to cross-fade with the neighbouring footage
+     * (or from/to black at the timeline ends). Omit them for a hard cut.
+     * Auto-segments: no pause/resume needed.
+     */
+    insert(path: string, options?: InsertOptions): this;
+    /**
+     * Lay an existing audio file (mp3/wav) onto the timeline at this point —
+     * narration, music bed, sound effect. Mixed onto the silent capture at
+     * finalise, positioned by where this call lands in *recorded* time (off-camera
+     * pauses excluded). By default the chain blocks until the clip finishes
+     * (`{ wait: false }` to play it over following actions); `{ volume }` gains it.
+     * Don't `pause()` mid-clip — paused time is dropped, desyncing the audio.
+     */
+    audio(path: string, options?: AudioOptions): this;
+    /** Navigate to a URL and wait for the page to settle. */
+    visit(url: string, options?: GoToOptions): this;
+    /**
+     * Wait for an element to reach a given state before continuing. Useful for async
+     * content, or as an automatic gate after a manual step. `target` accepts a CSS
+     * selector or a `text:` prefix; see {@link WaitForOptions} for `state`/`timeout`.
+     */
+    waitFor(target: string, options?: WaitForOptions): this;
+    /**
+     * Click an element. Accepts a CSS selector (`#id`, `.class`, `input[name="…"]`)
+     * or a `text:` prefix (`"text:Next"`, matched by visible text).
+     */
+    click(target: string): this;
+    /**
+     * Move the mouse (and cursor overlay) onto an element without clicking, so any
+     * `:hover` state — tooltips, dropdowns, menus — is revealed.
+     */
+    hover(target: string): this;
+    /**
+     * Type into an element with human-like timing. Accepts a CSS selector or a
+     * `text:` prefix. Timing is **jittered yet deterministic in total**: keystroke
+     * delays vary but always sum to `typingDuration(text, speed)`, so the voiceover
+     * compiler can predict this action's length. Pass `{ duration }` (ms) to
+     * override that total.
+     */
+    type(target: string, text: string, options?: {
+        duration?: number;
+    }): this;
+    /** Clear an input or textarea (select-all + delete). Handy before re-typing. */
+    clear(target: string): this;
+    /**
+     * Choose an option in a native `<select>` by its `value`. The cursor animates to
+     * the control like `click()`. Note: the open option list is OS-drawn, *outside*
+     * the page, so it can't be captured — build a custom dropdown from `click()`s
+     * for an on-camera menu.
+     */
+    select(target: string, value: string): this;
+    /** Press a keyboard key (e.g. "Escape", "Enter", "Tab"). */
+    key(key: string): this;
+    /**
+     * Move the mouse (and cursor overlay) to a target or coordinates — a CSS
+     * selector / plain text (element centre) or `{ x, y }` (viewport coords).
+     */
+    mouse(target: string | {
+        x: number;
+        y: number;
+    }): this;
+    /**
+     * Smooth-scroll to an element or position: `"top"`/`"bottom"`, a CSS selector or
+     * plain text (centred), or a number (absolute Y). `duration` (ms) overrides the
+     * default animation length.
+     */
+    scroll(target: string | number, options?: {
+        duration?: number;
+    }): this;
+    /**
+     * Smoothly scale the viewport to `level` from a transform origin. Calling zoom()
+     * again while zoomed transitions both scale and origin at once — no reset needed.
+     * `origin` accepts position keywords, percentages, a CSS selector, or `text:`.
+     * `duration` overrides `zoomDuration` for this call.
+     */
+    zoom(level: number, options?: {
+        origin?: string;
+        duration?: number;
+    }): this;
+    /** Smoothly reset zoom back to 1. */
+    resetZoom(options?: {
+        duration?: number;
+    }): this;
+    /** Pause the sequence for `ms` milliseconds. */
+    wait(ms: number): this;
+    /** Execute the queued action sequence, then finalise the recording. */
+    run(): Promise<void>;
+    /** Resolve a local asset path (insert/audio clip) against `baseDir` so a
+     *  Markdown/JSON script and its clips travel together; absolute paths pass
+     *  through. `baseDir` empty → resolve against cwd (the programmatic default). */
+    private _resolveFile;
+    private _enqueue;
+    /** Recompute `cfg` as defaults < content config < constructor config, then
+     *  resolve a relative `outputDir`/`assetsDir` against `baseDir`. */
+    private _applyContentConfig;
+    /** Validate each action against the manifest and enqueue it by calling its method
+     *  (relative `visit` URLs resolve against `baseDir` first). */
+    private _loadActions;
+}
+//# sourceMappingURL=recordable.d.ts.map

package/dist/compose/recordable.d.ts.map

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

package/dist/compose/recordable.js

@@ -0,0 +1,337 @@
+import { isAbsolute, resolve } from "node:path";
+import { DEFAULT_CONFIG, } from "../config.js";
+import { sleep, truncate } from "../utils.js";
+import { createLogger } from "../logger.js";
+import { parseConfig } from "../validate.js";
+import { Recorder } from "../video/recorder.js";
+import { AudioTrack } from "../audio/track.js";
+import { Runtime } from "../browser/runtime.js";
+import { Session } from "./session.js";
+import { buildArgs, validateAction } from "../actions.js";
+import { resolveVisitUrls, splitScript } from "../script.js";
+import { extractActions, parseMarkdown } from "../formats/markdown/parse.js";
+// ─── Compose layer: the builder ──────────────────────────────────────────────
+//
+// The public fluent API. Chain methods *describe* a recording by enqueuing
+// actions; they perform no page work themselves — interaction is delegated to the
+// Runtime, and execution to the Session at run(). Also owns config resolution and
+// the declarative loaders (JSON / Markdown).
+export class Recordable {
+    cfg = { ...DEFAULT_CONFIG };
+    // Constructor config — always wins over config from a loaded document
+    // (frontmatter / script `config`), which layers underneath.
+    userConfig;
+    log = createLogger(() => this.cfg.silent);
+    recorder = new Recorder(() => this.cfg, this.log);
+    audioTrack = new AudioTrack();
+    runtime = new Runtime(() => this.cfg, this.log);
+    queue = [];
+    // Deferred load work (voiceover synthesis), run by run() — so `fromMarkdown`
+    // stays synchronous and building a script never triggers synthesis.
+    pending = [];
+    // Recording state. `recording` is the *intent* (should we be capturing?); the
+    // recorder starts segments lazily so a leading pause() never makes a clip.
+    recording = true;
+    constructor(config = {}) {
+        this.userConfig = parseConfig(config);
+        this._applyContentConfig({}); // sets cfg = defaults < userConfig, resolving paths
+    }
+    // ─── Loaders ───────────────────────────────────────────────────────────────
+    //
+    // Turn declarative content into queued actions, between construction and run().
+    /** Load a JSON script — an array of actions, a `{ config, actions }` object, or a
+     *  raw JSON string — enqueuing each action. Returns `this` to chain into `.run()`. */
+    fromJSON(script) {
+        const parsed = typeof script === "string" ? JSON.parse(script) : script;
+        const { config, actions } = splitScript(parsed);
+        if (!Array.isArray(actions))
+            throw new Error("Script must be an array of actions, or { actions: [...] }");
+        this._applyContentConfig(config ?? {});
+        this._loadActions(actions);
+        return this;
+    }
+    /**
+     * Load a Markdown document — synchronous and chainable. The `voiceover`
+     * frontmatter key picks the path: present → synthesize narration + computed
+     * waits (the add-on, dynamically imported so a no-audio run never loads TTS),
+     * deferred to `run()`; absent → flatten markers to a plain chain now. Caller
+     * reads the file (and loads any `.env`).
+     */
+    fromMarkdown(md) {
+        const parsed = parseMarkdown(md);
+        this._applyContentConfig(parsed.config);
+        if (!parsed.voiceover) {
+            this._loadActions(extractActions(parsed.blocks));
+            return this;
+        }
+        // Defer TTS to run(); remember where these actions belong in the queue.
+        const insertAt = this.queue.length;
+        this.pending.push(() => this._stageVoiceover(md, insertAt));
+        return this;
+    }
+    /** Synthesize a voiceover document and splice its actions into the queue at the
+     *  position `fromMarkdown` was called (so chaining order is preserved). */
+    async _stageVoiceover(md, insertAt) {
+        // Pick up secrets (ELEVENLABS_API_KEY) from a .env beside the document.
+        if (this.cfg.baseDir) {
+            try {
+                process.loadEnvFile(resolve(this.cfg.baseDir, ".env"));
+            }
+            catch {
+                // No .env beside the document — fine, secrets may already be in the env.
+            }
+        }
+        const { compileMarkdown } = await import("../voiceover/index.js");
+        const compiled = await compileMarkdown(md, {
+            assetsDir: this.cfg.assetsDir,
+            configOverride: this.cfg,
+            log: this.log,
+        });
+        this.cfg = { ...this.cfg, actionDelay: 0 }; // computed waits assume no inter-action delay
+        // Build the compiled actions in isolation (the chain methods push to `queue`),
+        // then splice them in. Safe: this runs during run()'s await, single-threaded.
+        const saved = this.queue;
+        this.queue = [];
+        this._loadActions(compiled.actions);
+        const items = this.queue;
+        this.queue = saved;
+        this.queue.splice(insertAt, 0, ...items);
+    }
+    /** Merge config mid-sequence — enqueued so it takes effect at this point. */
+    setConfig(config) {
+        return this._enqueue(async () => {
+            this.cfg = { ...this.cfg, ...parseConfig(config) };
+        });
+    }
+    // ─── Recording control ───────────────────────────────────────────────────────
+    //
+    // Recording is ON from the top by default and finalises automatically when
+    // run() ends — there is no start()/stop(). Use pause()/resume() to carve
+    // off-camera gaps; every captured segment is stitched into one seamless MP4.
+    /**
+     * Stop capturing. The chain keeps running — anything between `pause()` and the
+     * next resume executes off-camera (page loads, logins, data setup) and is
+     * omitted from the final video. Place it first to skip the cold open.
+     */
+    pause() {
+        return this._enqueue(async () => {
+            this.recording = false;
+            await this.recorder.end();
+        }, true);
+    }
+    /** Resume capturing in a fresh segment, immediately. */
+    resume() {
+        return this._enqueue(async (page) => {
+            this.recording = true;
+            await this.recorder.begin(page);
+        }, true);
+    }
+    /**
+     * Resume capturing, but only once the user *plays* — clicks the in-page ▶ Play
+     * button (or presses Enter in the terminal). Use for manual actions such as a
+     * login: `pause()` first, sign in by hand (headful), then `resumeOnInput()`.
+     */
+    resumeOnInput(message = "Press ▶ Play when you're ready to record") {
+        return this._enqueue(async (page) => {
+            await this.runtime.waitForPlay(page, message);
+            this.recording = true;
+            await this.recorder.begin(page);
+            // The page may have navigated during the manual step — re-inject cursor.
+            await this.runtime.injectCursor(page);
+        }, true);
+    }
+    /**
+     * Splice an external video clip into the timeline at this point — first call =
+     * intro, last = outro, anywhere between = mid-roll. The clip is normalized to
+     * the recording's resolution / fps / codec so the join stays seamless.
+     *
+     * Pass `fadeIn` / `fadeOut` (ms) to cross-fade with the neighbouring footage
+     * (or from/to black at the timeline ends). Omit them for a hard cut.
+     * Auto-segments: no pause/resume needed.
+     */
+    insert(path, options = {}) {
+        return this._enqueue(async () => {
+            const file = this._resolveFile(path);
+            this.log("Insert", file);
+            await this.recorder.insert(file, options);
+        }, true);
+    }
+    /**
+     * Lay an existing audio file (mp3/wav) onto the timeline at this point —
+     * narration, music bed, sound effect. Mixed onto the silent capture at
+     * finalise, positioned by where this call lands in *recorded* time (off-camera
+     * pauses excluded). By default the chain blocks until the clip finishes
+     * (`{ wait: false }` to play it over following actions); `{ volume }` gains it.
+     * Don't `pause()` mid-clip — paused time is dropped, desyncing the audio.
+     */
+    audio(path, options = {}) {
+        return this._enqueue(async () => {
+            const { wait = true, volume } = options;
+            const file = this._resolveFile(path);
+            // Pin the clip to where we are in recorded time (the video timeline), then
+            // hand it to the audio layer to probe + collect for the final mix.
+            const startMs = this.recorder.currentTimelineMs();
+            const { durationMs } = await this.audioTrack.add(file, startMs, { volume });
+            this.log("Audio", `${truncate(file)} @ ${Math.round(startMs)}ms (${Math.round(durationMs)}ms)`);
+            if (wait)
+                await sleep(durationMs);
+        });
+    }
+    // ─── Navigation ────────────────────────────────────────────────────────────
+    /** Navigate to a URL and wait for the page to settle. */
+    visit(url, options) {
+        return this._enqueue((page) => this.runtime.visit(page, url, options));
+    }
+    /**
+     * Wait for an element to reach a given state before continuing. Useful for async
+     * content, or as an automatic gate after a manual step. `target` accepts a CSS
+     * selector or a `text:` prefix; see {@link WaitForOptions} for `state`/`timeout`.
+     */
+    waitFor(target, options = {}) {
+        return this._enqueue((page) => this.runtime.waitFor(page, target, options));
+    }
+    // ─── Interactions ──────────────────────────────────────────────────────────
+    /**
+     * Click an element. Accepts a CSS selector (`#id`, `.class`, `input[name="…"]`)
+     * or a `text:` prefix (`"text:Next"`, matched by visible text).
+     */
+    click(target) {
+        return this._enqueue((page) => this.runtime.click(page, target));
+    }
+    /**
+     * Move the mouse (and cursor overlay) onto an element without clicking, so any
+     * `:hover` state — tooltips, dropdowns, menus — is revealed.
+     */
+    hover(target) {
+        return this._enqueue((page) => this.runtime.hover(page, target));
+    }
+    /**
+     * Type into an element with human-like timing. Accepts a CSS selector or a
+     * `text:` prefix. Timing is **jittered yet deterministic in total**: keystroke
+     * delays vary but always sum to `typingDuration(text, speed)`, so the voiceover
+     * compiler can predict this action's length. Pass `{ duration }` (ms) to
+     * override that total.
+     */
+    type(target, text, options = {}) {
+        return this._enqueue((page) => this.runtime.type(page, target, text, options));
+    }
+    /** Clear an input or textarea (select-all + delete). Handy before re-typing. */
+    clear(target) {
+        return this._enqueue((page) => this.runtime.clear(page, target));
+    }
+    /**
+     * Choose an option in a native `<select>` by its `value`. The cursor animates to
+     * the control like `click()`. Note: the open option list is OS-drawn, *outside*
+     * the page, so it can't be captured — build a custom dropdown from `click()`s
+     * for an on-camera menu.
+     */
+    select(target, value) {
+        return this._enqueue((page) => this.runtime.select(page, target, value));
+    }
+    /** Press a keyboard key (e.g. "Escape", "Enter", "Tab"). */
+    key(key) {
+        return this._enqueue((page) => this.runtime.key(page, key));
+    }
+    /**
+     * Move the mouse (and cursor overlay) to a target or coordinates — a CSS
+     * selector / plain text (element centre) or `{ x, y }` (viewport coords).
+     */
+    mouse(target) {
+        return this._enqueue((page) => this.runtime.mouse(page, target));
+    }
+    // ─── Scrolling ─────────────────────────────────────────────────────────────
+    /**
+     * Smooth-scroll to an element or position: `"top"`/`"bottom"`, a CSS selector or
+     * plain text (centred), or a number (absolute Y). `duration` (ms) overrides the
+     * default animation length.
+     */
+    scroll(target, options = {}) {
+        return this._enqueue((page) => this.runtime.scroll(page, target, options));
+    }
+    // ─── Zoom ──────────────────────────────────────────────────────────────────
+    /**
+     * Smoothly scale the viewport to `level` from a transform origin. Calling zoom()
+     * again while zoomed transitions both scale and origin at once — no reset needed.
+     * `origin` accepts position keywords, percentages, a CSS selector, or `text:`.
+     * `duration` overrides `zoomDuration` for this call.
+     */
+    zoom(level, options = {}) {
+        return this._enqueue((page) => this.runtime.zoomTo(page, level, options));
+    }
+    /** Smoothly reset zoom back to 1. */
+    resetZoom(options = {}) {
+        return this._enqueue((page) => this.runtime.resetZoom(page, options));
+    }
+    // ─── Timing ────────────────────────────────────────────────────────────────
+    /** Pause the sequence for `ms` milliseconds. */
+    wait(ms) {
+        return this._enqueue(async () => {
+            this.log("Wait", `${ms}ms`);
+            await sleep(ms);
+        });
+    }
+    // ─── Execution ─────────────────────────────────────────────────────────────
+    /** Execute the queued action sequence, then finalise the recording. */
+    async run() {
+        // Finish any deferred load work (voiceover synthesis) before recording.
+        for (const job of this.pending)
+            await job();
+        this.pending = [];
+        // Expose just what the session needs; cfg/recording are read live via arrow
+        // getters (this instance mutates them as control actions run).
+        const comp = {
+            queue: this.queue,
+            log: this.log,
+            recorder: this.recorder,
+            audioTrack: this.audioTrack,
+            runtime: this.runtime,
+        };
+        Object.defineProperty(comp, "cfg", { get: () => this.cfg, enumerable: true });
+        Object.defineProperty(comp, "recording", {
+            get: () => this.recording,
+            enumerable: true,
+        });
+        await new Session(comp).run();
+    }
+    // ─── Private ───────────────────────────────────────────────────────────────
+    /** Resolve a local asset path (insert/audio clip) against `baseDir` so a
+     *  Markdown/JSON script and its clips travel together; absolute paths pass
+     *  through. `baseDir` empty → resolve against cwd (the programmatic default). */
+    _resolveFile(path) {
+        return isAbsolute(path) ? path : resolve(this.cfg.baseDir, path);
+    }
+    _enqueue(run, control = false) {
+        this.queue.push({ run, control });
+        return this;
+    }
+    /** Recompute `cfg` as defaults < content config < constructor config, then
+     *  resolve a relative `outputDir`/`assetsDir` against `baseDir`. */
+    _applyContentConfig(content) {
+        this.cfg = { ...DEFAULT_CONFIG, ...parseConfig(content), ...this.userConfig };
+        const base = this.cfg.baseDir;
+        if (base) {
+            if (!isAbsolute(this.cfg.outputDir))
+                this.cfg.outputDir = resolve(base, this.cfg.outputDir);
+            if (!isAbsolute(this.cfg.assetsDir))
+                this.cfg.assetsDir = resolve(base, this.cfg.assetsDir);
+        }
+    }
+    /** Validate each action against the manifest and enqueue it by calling its method
+     *  (relative `visit` URLs resolve against `baseDir` first). */
+    _loadActions(actions) {
+        resolveVisitUrls(actions, this.cfg.baseDir);
+        actions.forEach((step, i) => {
+            const where = `step ${i} (${step?.action ?? "?"})`;
+            if (!step || typeof step !== "object")
+                throw new Error(`${where}: not an object`);
+            try {
+                validateAction(step);
+            }
+            catch (err) {
+                throw new Error(`${where}: ${err.message}`, { cause: err });
+            }
+            this[step.action](...buildArgs(step, step.action));
+        });
+    }
+}
+//# sourceMappingURL=recordable.js.map

package/dist/compose/recordable.js.map

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

package/dist/compose/session.d.ts

@@ -0,0 +1,38 @@
+import { type Page } from "puppeteer";
+import { type Logger } from "../logger.js";
+import type { ResolvedConfig } from "../config.js";
+import { type Recorder } from "../video/recorder.js";
+import { type AudioTrack } from "../audio/track.js";
+import { type Runtime } from "../browser/runtime.js";
+/** One queued action. `control` actions (pause/resume/insert) run without forcing a
+ *  capture segment to begin. */
+export interface QueueItem {
+    run: (page: Page) => Promise<void>;
+    control: boolean;
+}
+/** What the session needs from the builder to execute a composed recording.
+ *  `cfg` and `recording` are read live (the builder mutates them mid-run). */
+export interface Composition {
+    readonly queue: QueueItem[];
+    readonly log: Logger;
+    readonly recorder: Recorder;
+    readonly audioTrack: AudioTrack;
+    readonly runtime: Runtime;
+    readonly cfg: ResolvedConfig;
+    readonly recording: boolean;
+}
+export declare class Session {
+    private readonly comp;
+    private browser;
+    private outputPath;
+    private finalised;
+    constructor(comp: Composition);
+    /** Execute the queued action sequence, then finalise the recording. */
+    run(): Promise<void>;
+    private _cleanup;
+    /** Seal the recording: stitch the captured/inserted segments (video layer),
+     *  then mix the audio track onto them (audio layer). The video defines the
+     *  length. Idempotent — a signal handler and the normal path both call it. */
+    private _finalize;
+}
+//# sourceMappingURL=session.d.ts.map

package/dist/compose/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/compose/session.ts"],"names":[],"mappings":"AAAA,OAAkB,EAAgB,KAAK,IAAI,EAAE,MAAM,WAAW,CAAC;AAI/D,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAErD,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,uBAAuB,CAAC;AASrD;gCACgC;AAChC,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;8EAC8E;AAC9E,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,SAAS,EAAE,CAAC;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,GAAG,EAAE,cAAc,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED,qBAAa,OAAO;IAKN,OAAO,CAAC,QAAQ,CAAC,IAAI;IAJjC,OAAO,CAAC,OAAO,CAAwB;IACvC,OAAO,CAAC,UAAU,CAAM;IACxB,OAAO,CAAC,SAAS,CAAS;gBAEG,IAAI,EAAE,WAAW;IAE9C,uEAAuE;IACjE,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;YAyEZ,QAAQ;IAStB;;kFAE8E;YAChE,SAAS;CA0BxB"}