cbrowser 18.70.0 → 18.71.0

package/dist/recording/encoders.js

@@ -0,0 +1,304 @@
+/**
+ * Recording encoders — turn a directory of captured frames into an animated
+ * GIF, an animated WebP, or a video.
+ *
+ * Two hard constraints shape this module:
+ *
+ * 1. Frames arrive from a CDP screencast, so they are JPEGs of *differing*
+ *    byte length and occasionally differing pixel dimensions (a viewport
+ *    change mid-capture re-sizes the stream). Every frame is therefore
+ *    normalised to one locked output size before encoding. Do not "optimise"
+ *    this into raw-buffer stacking — sharp's animated encoders need a joined
+ *    input, and a stacked raw buffer silently produces a single tall page.
+ *
+ * 2. Capture is event-driven, so frames are *not* evenly spaced. Per-frame
+ *    delays come from the caller (derived from frame timestamps), never from
+ *    a constant cadence.
+ *
+ * @since v18.70.0
+ */
+import { spawn } from "node:child_process";
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import sharp from "sharp";
+/**
+ * Thrown when an encoder's external dependency is missing. Callers surface the
+ * message verbatim and exit non-zero — recording itself has already succeeded
+ * at this point, so this must never be swallowed into a silent partial result.
+ */
+export class MissingEncoderError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "MissingEncoderError";
+    }
+}
+// =========================================================================
+// Frame normalisation
+// =========================================================================
+/**
+ * Resolve the locked output dimensions from the first frame, honouring any
+ * caller override and forcing even numbers (video encoders reject odd sizes).
+ */
+async function lockDimensions(firstFrame, options, requireEven = false) {
+    const meta = await sharp(firstFrame).metadata();
+    const firstCrop = options.crops?.[0];
+    const baseWidth = options.width ?? firstCrop?.width ?? meta.width;
+    const baseHeight = options.height ?? firstCrop?.height ?? meta.height;
+    if (!baseWidth || !baseHeight) {
+        throw new Error(`Cannot determine frame dimensions from ${firstFrame}`);
+    }
+    const scale = options.scale ?? 1;
+    if (scale <= 0 || scale > 1) {
+        throw new Error(`Invalid scale ${scale} - must be > 0 and <= 1`);
+    }
+    const width = Math.max(1, Math.round(baseWidth * scale));
+    const height = Math.max(1, Math.round(baseHeight * scale));
+    // Only the video path forces even dimensions - yuv420p subsampling requires
+    // them. Applying that rounding to GIF/WebP made a 393px-wide iPhone capture
+    // emit a 394px artifact, and a one-pixel drift from the declared viewport is
+    // exactly what breaks a pixel-exact visual baseline for no real reason.
+    if (!requireEven)
+        return { width, height };
+    return {
+        width: Math.max(2, Math.round(width / 2) * 2),
+        height: Math.max(2, Math.round(height / 2) * 2),
+    };
+}
+/**
+ * Normalise one frame to the locked size. `fit: "contain"` preserves aspect
+ * ratio and letterboxes rather than distorting - a frame that arrived at a
+ * different viewport size should look small, not stretched.
+ */
+async function normaliseFrame(framePath, width, height, crop) {
+    let pipeline = sharp(framePath);
+    if (crop) {
+        // The crop is trimmed to the frame it is being applied to: an element that
+        // drifts partly off-screen still yields the visible part rather than
+        // failing the whole encode on a sharp extract_area error.
+        const meta = await pipeline.metadata();
+        const frameWidth = meta.width ?? width;
+        const frameHeight = meta.height ?? height;
+        const left = Math.max(0, Math.min(Math.round(crop.x), frameWidth - 1));
+        const top = Math.max(0, Math.min(Math.round(crop.y), frameHeight - 1));
+        const extractWidth = Math.max(1, Math.min(Math.round(crop.width), frameWidth - left));
+        const extractHeight = Math.max(1, Math.min(Math.round(crop.height), frameHeight - top));
+        pipeline = pipeline.extract({ left, top, width: extractWidth, height: extractHeight });
+    }
+    return pipeline
+        .resize(width, height, {
+        fit: "contain",
+        background: { r: 0, g: 0, b: 0, alpha: 1 },
+    })
+        .png()
+        .toBuffer();
+}
+/** Validate the frames/delays pairing shared by every animated encoder. */
+function assertEncodable(frames, delays, label) {
+    if (frames.length === 0) {
+        throw new Error(`Cannot encode ${label}: no frames`);
+    }
+    if (delays.length !== frames.length) {
+        throw new Error(`Cannot encode ${label}: ${frames.length} frames but ${delays.length} delays - ` +
+            `delays must be derived per-frame from capture timestamps`);
+    }
+    const missing = frames.filter((f) => !existsSync(f));
+    if (missing.length > 0) {
+        throw new Error(`Cannot encode ${label}: ${missing.length} frame file(s) missing, first: ${missing[0]}`);
+    }
+}
+// =========================================================================
+// Animated image encoders (sharp)
+// =========================================================================
+/**
+ * Encode frames into an animated GIF with per-frame delays.
+ *
+ * A single-frame recording (a static page that emitted no screencast events)
+ * encodes to a one-page GIF rather than failing.
+ */
+export async function encodeGif(frames, delays, outPath, options = {}) {
+    assertEncodable(frames, delays, "GIF");
+    const { width, height } = await lockDimensions(frames[0], options);
+    const normalised = await Promise.all(frames.map((f, i) => normaliseFrame(f, width, height, options.crops?.[i])));
+    await sharp(normalised, { join: { animated: true } })
+        .gif({ delay: delays.map((d) => Math.max(10, Math.round(d))), loop: options.loop ?? 0 })
+        .toFile(outPath);
+    return { path: outPath, bytes: statSync(outPath).size, frames: frames.length, width, height };
+}
+/** Encode frames into an animated WebP with per-frame delays. */
+export async function encodeWebp(frames, delays, outPath, options = {}) {
+    assertEncodable(frames, delays, "WebP");
+    const { width, height } = await lockDimensions(frames[0], options);
+    const normalised = await Promise.all(frames.map((f, i) => normaliseFrame(f, width, height, options.crops?.[i])));
+    await sharp(normalised, { join: { animated: true } })
+        .webp({ delay: delays.map((d) => Math.max(10, Math.round(d))), loop: options.loop ?? 0 })
+        .toFile(outPath);
+    return { path: outPath, bytes: statSync(outPath).size, frames: frames.length, width, height };
+}
+// =========================================================================
+// ffmpeg resolution
+// =========================================================================
+/**
+ * Locate Playwright's bundled ffmpeg. A bare `ffmpeg` is never invoked: the
+ * PATH binary is not guaranteed to exist on deploy targets, and silently
+ * picking up an arbitrary system build makes output non-reproducible.
+ *
+ * Probe order: $PLAYWRIGHT_BROWSERS_PATH, then the per-user cache directories.
+ */
+export function resolveFfmpegPath() {
+    const override = process.env.CBROWSER_FFMPEG_PATH;
+    if (override && existsSync(override))
+        return override;
+    const roots = [];
+    if (process.env.PLAYWRIGHT_BROWSERS_PATH)
+        roots.push(process.env.PLAYWRIGHT_BROWSERS_PATH);
+    roots.push(join(homedir(), ".cache", "ms-playwright"));
+    for (const root of roots) {
+        if (!existsSync(root))
+            continue;
+        let entries;
+        try {
+            entries = readdirSync(root);
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries.filter((e) => e.startsWith("ffmpeg-")).sort().reverse()) {
+            for (const bin of ["ffmpeg-linux", "ffmpeg-mac", "ffmpeg-win64.exe"]) {
+                const candidate = join(root, entry, bin);
+                if (existsSync(candidate))
+                    return candidate;
+            }
+        }
+    }
+    return null;
+}
+/** Run ffmpeg and collect stdout+stderr. */
+function runFfmpeg(bin, args, stdin) {
+    return new Promise((resolve, reject) => {
+        const proc = spawn(bin, args, { stdio: ["pipe", "pipe", "pipe"] });
+        let output = "";
+        proc.stdout.on("data", (d) => { output += d.toString(); });
+        proc.stderr.on("data", (d) => { output += d.toString(); });
+        proc.on("error", reject);
+        proc.on("close", (code) => resolve({ code: code ?? -1, output }));
+        if (stdin) {
+            proc.stdin.on("error", () => { });
+            proc.stdin.end(stdin);
+        }
+        else {
+            proc.stdin.end();
+        }
+    });
+}
+/** Cached capability probe of a resolved ffmpeg binary. */
+const capabilityCache = new Map();
+async function ffmpegCapabilities(bin) {
+    const cached = capabilityCache.get(bin);
+    if (cached)
+        return cached;
+    const parse = (text) => {
+        const names = new Set();
+        for (const line of text.split("\n")) {
+            const match = line.match(/^\s*[A-Z. ]{2,6}\s+(\S+)/);
+            if (match)
+                names.add(match[1]);
+        }
+        return names;
+    };
+    const [muxers, encoders] = await Promise.all([
+        runFfmpeg(bin, ["-hide_banner", "-muxers"]),
+        runFfmpeg(bin, ["-hide_banner", "-encoders"]),
+    ]);
+    const caps = { muxers: parse(muxers.output), encoders: parse(encoders.output) };
+    capabilityCache.set(bin, caps);
+    return caps;
+}
+/**
+ * Resample variable-delay frames onto a constant-rate timeline by repeating
+ * each frame for as long as it was on screen. Video containers assume a fixed
+ * frame rate; repeating is how event-driven capture maps onto one without
+ * inventing content that was never displayed.
+ */
+export function resampleToConstantRate(frames, delays, fps) {
+    const frameMs = 1000 / fps;
+    const timeline = [];
+    for (let i = 0; i < frames.length; i++) {
+        const repeats = Math.max(1, Math.round((delays[i] ?? frameMs) / frameMs));
+        for (let r = 0; r < repeats; r++)
+            timeline.push(frames[i]);
+    }
+    return timeline;
+}
+/**
+ * Encode frames into a video via an ffmpeg-family binary.
+ *
+ * `container` selects the muxer/encoder pair. Playwright's bundled ffmpeg is a
+ * stripped build that ships only the WebM muxer and the libvpx (VP8) encoder,
+ * so "webm" works out of the box and "mp4" requires a fuller ffmpeg.
+ */
+async function encodeVideo(frames, delays, outPath, container, options = {}) {
+    assertEncodable(frames, delays, container.toUpperCase());
+    const bin = resolveFfmpegPath();
+    if (!bin) {
+        throw new MissingEncoderError(`Cannot encode ${container.toUpperCase()}: no ffmpeg binary found. ` +
+            `Looked for Playwright's bundled ffmpeg under $PLAYWRIGHT_BROWSERS_PATH and ` +
+            `${join(homedir(), ".cache", "ms-playwright")}/ffmpeg-*/. ` +
+            `Install it with 'npx playwright install ffmpeg', or re-run with --format gif,webp.`);
+    }
+    const caps = await ffmpegCapabilities(bin);
+    const wanted = container === "webm"
+        ? { muxer: "webm", encoders: ["libvpx", "libvpx-vp9"] }
+        : { muxer: "mp4", encoders: ["libx264", "libopenh264", "h264_videotoolbox", "mpeg4"] };
+    const encoder = wanted.encoders.find((e) => caps.encoders.has(e));
+    if (!caps.muxers.has(wanted.muxer) || !encoder) {
+        const missing = [
+            !caps.muxers.has(wanted.muxer) ? `muxer '${wanted.muxer}'` : null,
+            !encoder ? `video encoder (need one of: ${wanted.encoders.join(", ")})` : null,
+        ].filter(Boolean).join(" and ");
+        throw new MissingEncoderError(`Cannot encode ${container.toUpperCase()}: ${bin} is missing ${missing}. ` +
+            `Playwright's bundled ffmpeg is a stripped build (WebM/VP8 only). ` +
+            `Install a full ffmpeg and set CBROWSER_FFMPEG_PATH, or re-run with --format ${container === "mp4" ? "webm" : "gif"}.`);
+    }
+    const { width, height } = await lockDimensions(frames[0], options, true);
+    const fps = options.fps ?? 10;
+    const timeline = resampleToConstantRate(frames, delays, fps);
+    const cropTimeline = options.crops
+        ? resampleToConstantRate(options.crops.map((_, i) => String(i)), delays, fps)
+            .map((i) => options.crops[Number(i)])
+        : undefined;
+    // Frames are normalised to identical JPEG dimensions and concatenated into
+    // one mjpeg stream; the stripped build has only the image2pipe demuxer, and
+    // it needs the decoder named explicitly when reading from a pipe.
+    const jpegs = await Promise.all(timeline.map(async (f, i) => sharp(await normaliseFrame(f, width, height, cropTimeline?.[i]))
+        .jpeg({ quality: 90 })
+        .toBuffer()));
+    const args = [
+        "-hide_banner", "-loglevel", "error", "-y",
+        "-f", "image2pipe", "-c:v", "mjpeg", "-framerate", String(fps), "-i", "pipe:0",
+        "-c:v", encoder,
+        "-pix_fmt", "yuv420p",
+        "-an",
+        outPath,
+    ];
+    const { code, output } = await runFfmpeg(bin, args, Buffer.concat(jpegs));
+    if (code !== 0 || !existsSync(outPath)) {
+        throw new Error(`ffmpeg failed encoding ${container} (exit ${code}): ${output.trim() || "no output"}`);
+    }
+    return { path: outPath, bytes: statSync(outPath).size, frames: timeline.length, width, height };
+}
+/** Encode frames into a WebM/VP8 video. Works with Playwright's bundled ffmpeg. */
+export async function encodeWebm(frames, delays, outPath, options = {}) {
+    return encodeVideo(frames, delays, outPath, "webm", options);
+}
+/**
+ * Encode frames into an MP4.
+ *
+ * Requires an ffmpeg with the mp4 muxer and an H.264-family encoder. Playwright's
+ * bundled binary has neither, so this throws {@link MissingEncoderError} unless a
+ * fuller ffmpeg is installed.
+ */
+export async function encodeMp4(frames, delays, outPath, options = {}) {
+    return encodeVideo(frames, delays, outPath, "mp4", options);
+}
+//# sourceMappingURL=encoders.js.map

package/dist/recording/encoders.js.map

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

package/dist/recording/engine.d.ts

@@ -0,0 +1,263 @@
+/**
+ * CBrowser - Cognitive Browser Automation
+ * Copyright 2026 Alexandria Eden alexandria.shai.eden@gmail.com
+ * Learn more at https://cbrowser.ai - MIT License
+ */
+import type { Locator, Page } from "playwright";
+import { type CaptureMethod, type Engine, type RecordingManifest, type RecordingTarget } from "./types.js";
+/** Output formats the CLI can request. */
+export type CaptureFormat = "gif" | "webp" | "mp4" | "webm";
+/** Condition that delays the first frame. */
+export type StartTrigger = {
+    kind: "lifecycle";
+    event: "load" | "domcontentloaded" | "networkidle";
+} | {
+    kind: "element";
+    selector: string;
+};
+/** Condition that ends the capture. */
+export type StopTrigger = {
+    kind: "element-appears";
+    selector: string;
+} | {
+    kind: "element-disappears";
+    selector: string;
+} | {
+    kind: "idle";
+    idleMs: number;
+};
+/** Default ceiling on how long any trigger may wait. */
+export declare const DEFAULT_TRIGGER_TIMEOUT_MS = 30000;
+export interface VideoCaptureOptions {
+    /** What to capture: the whole viewport, a fixed region, or a tracked element. */
+    target?: RecordingTarget;
+    /** Requested frames per second. Screencast frames above this rate are dropped. */
+    fps?: number;
+    /** Auto-stop after this many milliseconds. Omit for an open-ended recording. */
+    durationMs?: number;
+    /** Directory for frames, manifest and artifacts. Defaults to a slug dir under `baseDir`. */
+    outDir?: string;
+    /** Encoders to run at stop time. Defaults to `["gif"]`. */
+    format?: CaptureFormat[];
+    /** JPEG quality for captured frames (1-100, default 80). */
+    quality?: number;
+    /** Hard cap on retained frames; protects the disk on a long open-ended run. */
+    maxFrames?: number;
+    /** Recording name. Defaults to a timestamp slug. */
+    slug?: string;
+    /** Also write a contact sheet: one JPEG summarising the whole capture. */
+    contactSheet?: boolean | {
+        columns?: number;
+        maxFrames?: number;
+    };
+    /** Delay the first frame until this condition holds. */
+    startTrigger?: StartTrigger;
+    /** Extra delay after the start trigger fires, in milliseconds. */
+    startDelayMs?: number;
+    /** Stop capture when this condition holds. */
+    stopTrigger?: StopTrigger;
+    /** How long a trigger may wait before giving up (default 30s). */
+    triggerTimeoutMs?: number;
+    /**
+     * Resolves a selector to a Locator for element targets. Supplied by the
+     * caller so the engine reuses the browser's existing nine-strategy resolver
+     * (including its self-healing cache) rather than owning a second one.
+     */
+    resolveElement?: (selector: string) => Promise<Locator | null>;
+}
+export interface VideoCaptureStatus {
+    state: "idle" | "recording" | "stopped";
+    slug: string;
+    outDir: string;
+    /** Frames retained so far. */
+    frames: number;
+    /** Milliseconds since capture started (frozen once stopped). */
+    elapsedMs: number;
+    captureMethod: CaptureMethod;
+    /** Present once stopped. */
+    manifestPath?: string;
+}
+export interface VideoCaptureResult {
+    manifestPath: string;
+    manifest: RecordingManifest;
+    /** Encoders that failed, by format. Encoding failure never loses the frames. */
+    encodeErrors: Record<string, string>;
+}
+/**
+ * One recording run. Not reusable: `start()` may be called once, and `stop()`
+ * is idempotent, returning the same result on every subsequent call.
+ */
+export declare class VideoCaptureSession {
+    private page;
+    private engine;
+    private baseDir;
+    private opts;
+    private startTrigger?;
+    private startDelayMs;
+    private stopTrigger?;
+    private target;
+    private slug;
+    private outDir;
+    private framesDir;
+    private state;
+    private captureMethod;
+    private cdp;
+    private loopTimer;
+    private durationTimer;
+    private stopping;
+    private startWallMs;
+    private startedAtIso;
+    private stopWallMs;
+    private frames;
+    private nextDueMs;
+    private writeQueue;
+    private consoleEvents;
+    private networkEvents;
+    private consoleListener;
+    private requestListener;
+    private viewport;
+    private regionClamped;
+    private outputDims;
+    /**
+     * Output dimensions as whole pixels.
+     *
+     * NOT rounded to even: the GIF/WebP encoders now emit exactly these numbers,
+     * so a 393px-wide viewport produces a 393px artifact. Only the video path
+     * rounds up to even internally (yuv420p needs it), which is the one place a
+     * single pixel of difference is unavoidable.
+     */
+    private static outputDim;
+    /** Crop applied to frames captured right now; re-derived per frame for element targets. */
+    private currentCrop;
+    /** Whether `currentCrop` still reflects a live element measurement. */
+    private currentTracking;
+    private elementLocator;
+    private trackTimer;
+    private startTriggerLabel;
+    private stopTriggerLabel;
+    private triggerTimedOut;
+    private stopTriggerTimer;
+    private stopTimeoutTimer;
+    /** Rolling SSIM state for the idle stop trigger. */
+    private idleSignature;
+    private lastChangeMs;
+    private idleScanQueue;
+    private result;
+    private finishedResolve;
+    /**
+     * Resolves when the capture has stopped from ANY source - explicit stop(),
+     * the duration timer, or a stop trigger. Callers that started an open-ended
+     * capture await this instead of assuming they are the ones who will end it.
+     */
+    readonly finished: Promise<VideoCaptureResult>;
+    /**
+     * @param page  Page to record. Must already be navigated - the engine never
+     *              navigates, so the caller controls what is on screen at t=0.
+     * @param engine Browser family, which decides the capture method.
+     * @param baseDir Directory recordings are created under when no `outDir` is given.
+     */
+    constructor(page: Page, engine: Engine, baseDir: string);
+    start(options?: VideoCaptureOptions): Promise<VideoCaptureStatus>;
+    /**
+     * Stop capture, score the frames, write the manifest, run the encoders.
+     *
+     * Idempotent: concurrent and repeated calls all resolve to the same result,
+     * so an auto-stop racing an explicit stop cannot double-encode.
+     */
+    stop(): Promise<VideoCaptureResult>;
+    status(): VideoCaptureStatus;
+    /**
+     * Resolve the capture target into a crop rect and a locked output size.
+     *
+     * Output dimensions are fixed here, for the whole capture, because animated
+     * GIF/WebP and every video container require a constant frame size. An
+     * element that grows or shrinks is re-fitted into these locked dimensions
+     * rather than changing them mid-stream.
+     */
+    private setUpTarget;
+    /**
+     * Measure the tracked element, padded and clamped into the viewport.
+     * Returns null when the element has no usable box right now.
+     */
+    private measureElement;
+    /**
+     * Re-measure the tracked element on the frame cadence so `crop` follows it as
+     * it moves. Polling rather than measuring inside the screencast handler: that
+     * handler must stay synchronous to ack frames promptly, and an await there
+     * would stall the stream.
+     */
+    private startElementTracking;
+    /**
+     * Wait for the start trigger, then the start delay.
+     *
+     * Returns false when the trigger timed out. Timing out is a reportable
+     * outcome, not an exception: the caller still gets a manifest saying which
+     * trigger was asked for and that it never fired.
+     */
+    private awaitStartTrigger;
+    /** Whether the start condition currently holds. */
+    private startConditionHolds;
+    /** Poll a condition until it holds or the budget runs out. */
+    private waitForCondition;
+    /**
+     * Watch for the stop condition, and enforce the trigger timeout.
+     *
+     * A stop trigger that never fires must not hang the capture: the timeout
+     * stops it anyway and flags `trigger_timeout`, keeping every frame captured
+     * up to that point.
+     */
+    private startStopTriggerWatch;
+    /** Whether an element-based stop condition currently holds. */
+    private stopConditionHolds;
+    /**
+     * Stop once no frame has changed for `idleMs`.
+     *
+     * Reuses the same SSIM comparator and threshold that produce `change_points`,
+     * so "changed" means exactly the same thing live as it does in the manifest.
+     */
+    private watchIdle;
+    private startScreencast;
+    /** Firefox/WebKit fallback: poll `page.screenshot` at the target rate. */
+    private startScreenshotLoop;
+    /**
+     * Capture one frame directly through Playwright rather than the screencast.
+     * Used to bracket the recording and to drive the non-Chromium fallback.
+     */
+    private captureDirectFrame;
+    /**
+     * Rate-limit screencast frames to the requested fps.
+     *
+     * Frames are matched against a fixed grid of due times rather than against
+     * "time since the last kept frame". A since-last rule compounds every paint
+     * event's jitter into the next interval and drifts the achieved rate away
+     * from the target; the grid holds the average at exactly `fps`.
+     */
+    private shouldKeep;
+    /**
+     * Record a frame and stream its bytes to disk.
+     *
+     * The index and timestamp are assigned synchronously so frame ordering
+     * follows arrival order; only the write is deferred, serialised through a
+     * queue so a slow disk cannot reorder frames or unbound memory.
+     */
+    private enqueueFrame;
+    private attachPageListeners;
+    private detachPageListeners;
+    private doStop;
+    private buildManifest;
+    /** SSIM of each frame against its predecessor; index 0 is always null. */
+    private scoreFrames;
+    /**
+     * Attach each side-channel event to the frame whose display window contains
+     * it: the last frame at or before the event, or frame 0 for anything that
+     * fired before the first frame landed.
+     */
+    private eventsForFrame;
+    /**
+     * Run the requested encoders. An encoder failure is recorded and reported but
+     * never thrown - the frames and manifest are the durable artifact, and losing
+     * a recording because a codec is missing would be the worst possible trade.
+     */
+    private runEncoders;
+}
+//# sourceMappingURL=engine.d.ts.map

package/dist/recording/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/recording/engine.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA8BH,OAAO,KAAK,EAA8B,OAAO,EAAE,IAAI,EAAW,MAAM,YAAY,CAAC;AAMrF,OAAO,EAGL,KAAK,aAAa,EAElB,KAAK,MAAM,EAGX,KAAK,iBAAiB,EACtB,KAAK,eAAe,EAErB,MAAM,YAAY,CAAC;AAEpB,0CAA0C;AAC1C,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,CAAC;AAE5D,6CAA6C;AAC7C,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,KAAK,EAAE,MAAM,GAAG,kBAAkB,GAAG,aAAa,CAAA;CAAE,GACzE;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1C,uCAAuC;AACvC,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAC7C;IAAE,IAAI,EAAE,oBAAoB,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAChD;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAErC,wDAAwD;AACxD,eAAO,MAAM,0BAA0B,QAAS,CAAC;AAkBjD,MAAM,WAAW,mBAAmB;IAClC,iFAAiF;IACjF,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,kFAAkF;IAClF,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,gFAAgF;IAChF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4FAA4F;IAC5F,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2DAA2D;IAC3D,MAAM,CAAC,EAAE,aAAa,EAAE,CAAC;IACzB,4DAA4D;IAC5D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+EAA+E;IAC/E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oDAAoD;IACpD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0EAA0E;IAC1E,YAAY,CAAC,EAAE,OAAO,GAAG;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAClE,wDAAwD;IACxD,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,kEAAkE;IAClE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,8CAA8C;IAC9C,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,kEAAkE;IAClE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,cAAc,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;CAChE;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAAC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,8BAA8B;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,gEAAgE;IAChE,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,aAAa,CAAC;IAC7B,4BAA4B;IAC5B,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,kBAAkB;IACjC,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,gFAAgF;IAChF,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACtC;AA4DD;;;GAGG;AACH,qBAAa,mBAAmB;IA+E5B,OAAO,CAAC,IAAI;IACZ,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,OAAO;IAhFjB,OAAO,CAAC,IAAI,CAC8B;IAC1C,OAAO,CAAC,YAAY,CAAC,CAAe;IACpC,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,WAAW,CAAC,CAAc;IAClC,OAAO,CAAC,MAAM,CAAyC;IACvD,OAAO,CAAC,IAAI,CAAM;IAClB,OAAO,CAAC,MAAM,CAAM;IACpB,OAAO,CAAC,SAAS,CAAM;IAEvB,OAAO,CAAC,KAAK,CAA4C;IACzD,OAAO,CAAC,aAAa,CAAmC;IACxD,OAAO,CAAC,GAAG,CAA2B;IACtC,OAAO,CAAC,SAAS,CAA+B;IAChD,OAAO,CAAC,aAAa,CAA+B;IACpD,OAAO,CAAC,QAAQ,CAA4C;IAE5D,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,YAAY,CAAM;IAC1B,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,UAAU,CAAuC;IAEzD,OAAO,CAAC,aAAa,CAAsB;IAC3C,OAAO,CAAC,aAAa,CAAsB;IAC3C,OAAO,CAAC,eAAe,CAAgD;IACvE,OAAO,CAAC,eAAe,CAAyC;IAEhE,OAAO,CAAC,QAAQ,CAAiD;IACjE,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,UAAU,CAA2B;IAC7C;;;;;;;OAOG;IACH,OAAO,CAAC,MAAM,CAAC,SAAS;IAIxB,2FAA2F;IAC3F,OAAO,CAAC,WAAW,CAAqB;IACxC,uEAAuE;IACvE,OAAO,CAAC,eAAe,CAA+B;IACtD,OAAO,CAAC,cAAc,CAAwB;IAC9C,OAAO,CAAC,UAAU,CAA+B;IAEjD,OAAO,CAAC,iBAAiB,CAAuB;IAChD,OAAO,CAAC,gBAAgB,CAAuB;IAC/C,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,gBAAgB,CAA+B;IACvD,OAAO,CAAC,gBAAgB,CAA+B;IACvD,oDAAoD;IACpD,OAAO,CAAC,aAAa,CAA6B;IAClD,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,aAAa,CAAuC;IAC5D,OAAO,CAAC,MAAM,CAAmC;IACjD,OAAO,CAAC,eAAe,CAAwC;IAC/D;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,kBAAkB,CAAC,CAE3C;IAEH;;;;;OAKG;gBAEO,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM;IAOnB,KAAK,CAAC,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAqF3E;;;;;OAKG;IACG,IAAI,IAAI,OAAO,CAAC,kBAAkB,CAAC;IAYzC,MAAM,IAAI,kBAAkB;IAc5B;;;;;;;OAOG;YACW,WAAW;IAyDzB;;;OAGG;YACW,cAAc;IAsB5B;;;;;OAKG;IACH,OAAO,CAAC,oBAAoB;IA8B5B;;;;;;OAMG;YACW,iBAAiB;IA2B/B,mDAAmD;YACrC,mBAAmB;IAsBjC,8DAA8D;YAChD,gBAAgB;IAc9B;;;;;;OAMG;IACH,OAAO,CAAC,qBAAqB;IAoC7B,+DAA+D;YACjD,kBAAkB;IAchC;;;;;OAKG;IACH,OAAO,CAAC,SAAS;YAoCH,eAAe;IAwB7B,0EAA0E;IAC1E,OAAO,CAAC,mBAAmB;IAc3B;;;OAGG;YACW,kBAAkB;IAYhC;;;;;;;OAOG;IACH,OAAO,CAAC,UAAU;IAYlB;;;;;;OAMG;IACH,OAAO,CAAC,YAAY;IAkCpB,OAAO,CAAC,mBAAmB;IAuB3B,OAAO,CAAC,mBAAmB;YAWb,MAAM;YA4CN,aAAa;IA6C3B,0EAA0E;YAC5D,WAAW;IAiBzB;;;;OAIG;IACH,OAAO,CAAC,cAAc;IAWtB;;;;OAIG;YACW,WAAW;CAiE1B"}