@prestyj/editor 0.7.1

package/dist/core/emoji-captions.js

@@ -0,0 +1,121 @@
+import { resolveApiKey } from "./auth/api-keys.js";
+const SYSTEM = `You are an emoji selector for short-form video captions. For each caption line, return the SINGLE most-fitting emoji or an empty string when nothing clearly fits.
+
+Rules:
+- Output JSON: {"emojis": [string, ...]} aligned 1-to-1 with the input order. Length MUST equal the input length.
+- Each entry is a single emoji character (e.g. "🔥") or "". No multi-emoji entries, no text.
+- Don't force emojis where they'd feel random — empty string is the right answer ~half the time.
+- Match the density target the user specifies.`;
+const DENSITY_TARGETS = {
+    low: "Roughly 1 in 4 cues should get an emoji. Be very selective — only when an emoji genuinely amplifies the line.",
+    med: "Roughly 1 in 2 cues should get an emoji. Pick the obvious wins; leave neutral lines empty.",
+    high: "Every cue should get an emoji where ANY emoji fits. Empty only for purely connective lines.",
+};
+/**
+ * Inject emojis into a list of cues via one LLM call. On failure
+ * (network down, malformed response, length mismatch) we return the
+ * cues UNCHANGED + populate `error` so the caller can surface it.
+ *
+ * For density="high" the emoji is rendered on its own line ABOVE the
+ * caption text (separated by ASS's `\\N` break) for the stacked CapCut
+ * look. For low/med it's appended inline.
+ */
+export async function injectEmojis(cues, opts = {}) {
+    if (cues.length === 0)
+        return { cues, injected: 0 };
+    const density = opts.density ?? "med";
+    const model = opts.model ?? "gpt-4o-mini";
+    const apiKey = opts.apiKey ?? resolveApiKey("OPENAI_API_KEY", "openai");
+    if (!apiKey) {
+        return { cues, injected: 0, error: "OPENAI_API_KEY not set" };
+    }
+    const numbered = cues.map((c, i) => `${i + 1}. ${c.text}`).join("\n");
+    const userText = `Density target: ${DENSITY_TARGETS[density]}\n\n` +
+        `Return exactly ${cues.length} entries.\n\n` +
+        `CAPTIONS:\n${numbered}`;
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    let emojis;
+    try {
+        const res = await fetchImpl("https://api.openai.com/v1/chat/completions", {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${apiKey}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({
+                model,
+                messages: [
+                    { role: "system", content: SYSTEM },
+                    { role: "user", content: userText },
+                ],
+                response_format: { type: "json_object" },
+                temperature: 0,
+            }),
+            signal: opts.signal,
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            return {
+                cues,
+                injected: 0,
+                error: `OpenAI HTTP ${res.status}: ${text.slice(0, 160)}`,
+            };
+        }
+        const data = (await res.json());
+        const content = data.choices?.[0]?.message?.content ?? "";
+        emojis = parseEmojiResponse(content, cues.length);
+    }
+    catch (e) {
+        return { cues, injected: 0, error: e.message };
+    }
+    if (emojis.length !== cues.length) {
+        return { cues, injected: 0, error: "emoji count mismatch" };
+    }
+    let injected = 0;
+    const out = cues.map((c, i) => {
+        const e = (emojis[i] ?? "").trim();
+        if (!e)
+            return c;
+        injected++;
+        const text = density === "high" ? `${e}\\N${c.text}` : `${c.text} ${e}`;
+        return { ...c, text };
+    });
+    return { cues: out, injected };
+}
+/**
+ * Tolerant parser. Accepts either {emojis: [...]} or a bare array, pads
+ * / truncates to `expected` length so length always lines up. Exported
+ * for testing.
+ */
+export function parseEmojiResponse(content, expected) {
+    let arr;
+    try {
+        const obj = JSON.parse(content);
+        if (Array.isArray(obj))
+            arr = obj;
+        else if (typeof obj === "object" && obj !== null) {
+            const v = obj.emojis;
+            arr = Array.isArray(v) ? v : [];
+        }
+        else
+            arr = [];
+    }
+    catch {
+        const m = content.match(/\[[\s\S]*\]/);
+        if (m) {
+            try {
+                arr = JSON.parse(m[0]);
+            }
+            catch {
+                arr = [];
+            }
+        }
+        else
+            arr = [];
+    }
+    const list = Array.isArray(arr) ? arr.map((v) => (typeof v === "string" ? v : "")) : [];
+    while (list.length < expected)
+        list.push("");
+    return list.slice(0, expected);
+}
+//# sourceMappingURL=emoji-captions.js.map

package/dist/core/emoji-captions.js.map

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

package/dist/core/envelope-sync.d.ts

@@ -0,0 +1,52 @@
+export interface EnvelopeResult {
+    path: string;
+    envelope: Float64Array;
+    /** Total file duration in seconds. */
+    durationSec: number;
+}
+export interface EnvelopeSyncOptions {
+    /** Search window in seconds. Larger = finds bigger drifts but slower. Default 10. */
+    maxLagSec?: number;
+    signal?: AbortSignal;
+}
+export interface EnvelopeSyncResult {
+    reference: string;
+    results: Array<{
+        path: string;
+        /** Positive = file starts later than reference. */
+        offsetSec: number;
+        /** 0..1 normalised correlation strength at the chosen lag. */
+        confidence: number;
+    }>;
+    /** Set when ANY pair correlated below 0.3 (low-confidence alignment). */
+    warning?: string;
+}
+/**
+ * Extract a mono 16kHz RMS energy envelope. One value every 100ms.
+ */
+export declare function extractEnvelope(inputPath: string, opts?: {
+    signal?: AbortSignal;
+}): Promise<EnvelopeResult>;
+/**
+ * Find the lag (in blocks) at which envelope `a` best aligns with envelope `b`.
+ * Searches ±maxLagBlocks. Returns peak lag and normalised Pearson correlation.
+ *
+ * Convention: maximises sum(a[i - lag] * b[i]). So:
+ *   - Positive lag = `a` LEADS `b` (a's peaks happen at smaller indices than b's)
+ *   - Negative lag = `a` TRAILS `b` (a's peaks happen at larger indices)
+ *
+ * Callers convert this to a wall-clock offset:
+ *   offsetSec = -lagBlocks * blockSec
+ * (positive offset = `a` started later than `b`).
+ */
+export declare function correlateEnvelopes(a: Float64Array, b: Float64Array, maxLagBlocks: number): {
+    lagBlocks: number;
+    correlation: number;
+};
+/**
+ * Align 2+ inputs using envelope correlation. Reference is the first input.
+ * For each non-reference input, compute the correlation lag and report the
+ * offset in seconds.
+ */
+export declare function envelopeSync(inputPaths: string[], opts?: EnvelopeSyncOptions): Promise<EnvelopeSyncResult>;
+//# sourceMappingURL=envelope-sync.d.ts.map

package/dist/core/envelope-sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope-sync.d.ts","sourceRoot":"","sources":["../../src/core/envelope-sync.ts"],"names":[],"mappings":"AA4BA,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,YAAY,CAAC;IACvB,sCAAsC;IACtC,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,mBAAmB;IAClC,qFAAqF;IACrF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,KAAK,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,mDAAmD;QACnD,SAAS,EAAE,MAAM,CAAC;QAClB,8DAA8D;QAC9D,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC,CAAC;IACH,yEAAyE;IACzE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,wBAAsB,eAAe,CACnC,SAAS,EAAE,MAAM,EACjB,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,WAAW,CAAA;CAAO,GAClC,OAAO,CAAC,cAAc,CAAC,CA8DzB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAChC,CAAC,EAAE,YAAY,EACf,CAAC,EAAE,YAAY,EACf,YAAY,EAAE,MAAM,GACnB;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CA4B5C;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAChC,UAAU,EAAE,MAAM,EAAE,EACpB,IAAI,GAAE,mBAAwB,GAC7B,OAAO,CAAC,kBAAkB,CAAC,CAsC7B"}

package/dist/core/envelope-sync.js

@@ -0,0 +1,169 @@
+/**
+ * Envelope-based cross-correlation for multicam alignment.
+ *
+ * Why not full FFT correlation? For editorial alignment we don't need
+ * sub-millisecond precision — we need "the speaker says hello at t=2.4 here
+ * and t=3.1 there, so file B leads A by 0.7s". The energy envelope (RMS in
+ * 100ms blocks) is sufficient and far cheaper than full PCM correlation.
+ *
+ * Pipeline:
+ *   1. ffmpeg extracts mono 16kHz PCM s16le to a temp file
+ *   2. We read PCM as Int16Array, compute per-block RMS → Float64 envelope
+ *   3. Time-domain cross-correlation against a reference within ±maxLagSec
+ *   4. Peak position → lag in blocks → seconds
+ *
+ * This is the approach used by tools like PluralEyes for non-slate sync. It
+ * works on dialogue, applause, music — anything with energy variation. It
+ * fails on sustained tones (test patterns, drone) because there's no
+ * envelope to correlate against.
+ */
+import { spawn } from "node:child_process";
+import { mkdtempSync, readFileSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+const SAMPLE_RATE = 16000;
+const BLOCK_MS = 100;
+const SAMPLES_PER_BLOCK = (SAMPLE_RATE * BLOCK_MS) / 1000; // 1600
+/**
+ * Extract a mono 16kHz RMS energy envelope. One value every 100ms.
+ */
+export async function extractEnvelope(inputPath, opts = {}) {
+    const dir = mkdtempSync(join(tmpdir(), "ezeditor-env-"));
+    const pcmPath = join(dir, "audio.pcm");
+    await new Promise((resolve, reject) => {
+        const child = spawn("ffmpeg", [
+            "-hide_banner",
+            "-y",
+            "-i",
+            inputPath,
+            "-f",
+            "s16le",
+            "-ac",
+            "1",
+            "-ar",
+            String(SAMPLE_RATE),
+            pcmPath,
+        ], { stdio: ["ignore", "pipe", "pipe"] });
+        let stderr = "";
+        child.stderr.on("data", (d) => (stderr += d.toString()));
+        opts.signal?.addEventListener("abort", () => child.kill("SIGTERM"));
+        child.on("error", reject);
+        child.on("close", (code) => code === 0
+            ? resolve()
+            : reject(new Error(`ffmpeg PCM extract exited ${code}: ${stderr.slice(-300)}`)));
+    });
+    const buf = readFileSync(pcmPath);
+    const samples = new Int16Array(buf.buffer, buf.byteOffset, Math.floor(buf.byteLength / 2));
+    const numBlocks = Math.floor(samples.length / SAMPLES_PER_BLOCK);
+    const env = new Float64Array(numBlocks);
+    for (let b = 0; b < numBlocks; b++) {
+        let sumSq = 0;
+        const off = b * SAMPLES_PER_BLOCK;
+        for (let i = 0; i < SAMPLES_PER_BLOCK; i++) {
+            const s = samples[off + i] / 32768;
+            sumSq += s * s;
+        }
+        env[b] = Math.sqrt(sumSq / SAMPLES_PER_BLOCK);
+    }
+    // Normalize so different gain levels don't bias the correlation.
+    let max = 0;
+    for (let i = 0; i < env.length; i++)
+        if (env[i] > max)
+            max = env[i];
+    if (max > 0) {
+        for (let i = 0; i < env.length; i++)
+            env[i] /= max;
+    }
+    // Clean up the PCM file. The dir survives until process exit.
+    try {
+        statSync(pcmPath);
+    }
+    catch {
+        /* */
+    }
+    return {
+        path: inputPath,
+        envelope: env,
+        durationSec: samples.length / SAMPLE_RATE,
+    };
+}
+/**
+ * Find the lag (in blocks) at which envelope `a` best aligns with envelope `b`.
+ * Searches ±maxLagBlocks. Returns peak lag and normalised Pearson correlation.
+ *
+ * Convention: maximises sum(a[i - lag] * b[i]). So:
+ *   - Positive lag = `a` LEADS `b` (a's peaks happen at smaller indices than b's)
+ *   - Negative lag = `a` TRAILS `b` (a's peaks happen at larger indices)
+ *
+ * Callers convert this to a wall-clock offset:
+ *   offsetSec = -lagBlocks * blockSec
+ * (positive offset = `a` started later than `b`).
+ */
+export function correlateEnvelopes(a, b, maxLagBlocks) {
+    let bestLag = 0;
+    let bestCorr = -Infinity;
+    for (let lag = -maxLagBlocks; lag <= maxLagBlocks; lag++) {
+        // a is shifted by `lag`; compare against b.
+        // Iterate over indices i where both a[i - lag] and b[i] exist.
+        const start = Math.max(0, lag);
+        const end = Math.min(b.length, a.length + lag);
+        if (end - start < 4)
+            continue;
+        let sumAB = 0;
+        let sumAA = 0;
+        let sumBB = 0;
+        for (let i = start; i < end; i++) {
+            const av = a[i - lag];
+            const bv = b[i];
+            sumAB += av * bv;
+            sumAA += av * av;
+            sumBB += bv * bv;
+        }
+        const denom = Math.sqrt(sumAA * sumBB);
+        const corr = denom > 0 ? sumAB / denom : 0;
+        if (corr > bestCorr) {
+            bestCorr = corr;
+            bestLag = lag;
+        }
+    }
+    return { lagBlocks: bestLag, correlation: bestCorr };
+}
+/**
+ * Align 2+ inputs using envelope correlation. Reference is the first input.
+ * For each non-reference input, compute the correlation lag and report the
+ * offset in seconds.
+ */
+export async function envelopeSync(inputPaths, opts = {}) {
+    if (inputPaths.length === 0) {
+        throw new Error("envelopeSync: inputs is empty");
+    }
+    const maxLagSec = opts.maxLagSec ?? 10;
+    const maxLagBlocks = Math.round((maxLagSec * 1000) / BLOCK_MS);
+    const envs = await Promise.all(inputPaths.map((p) => extractEnvelope(p, { signal: opts.signal })));
+    const ref = envs[0];
+    const results = [{ path: ref.path, offsetSec: 0, confidence: 1 }];
+    let lowConfidence = 0;
+    for (let i = 1; i < envs.length; i++) {
+        const e = envs[i];
+        const { lagBlocks, correlation } = correlateEnvelopes(e.envelope, ref.envelope, maxLagBlocks);
+        // lagBlocks > 0 means we shifted e RIGHT to match ref → e starts EARLIER
+        // than ref → its offset relative to ref is NEGATIVE.
+        const offsetSec = -lagBlocks * (BLOCK_MS / 1000);
+        const confidence = Math.max(0, correlation);
+        if (confidence < 0.3)
+            lowConfidence += 1;
+        results.push({
+            path: e.path,
+            offsetSec: +offsetSec.toFixed(3),
+            confidence: +confidence.toFixed(3),
+        });
+    }
+    return {
+        reference: ref.path,
+        results,
+        warning: lowConfidence > 0
+            ? `${lowConfidence} of ${results.length - 1} pair(s) correlated below 0.3 \u2014 alignment uncertain`
+            : undefined,
+    };
+}
+//# sourceMappingURL=envelope-sync.js.map

package/dist/core/envelope-sync.js.map

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

package/dist/core/envelope-sync.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=envelope-sync.test.d.ts.map

package/dist/core/envelope-sync.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope-sync.test.d.ts","sourceRoot":"","sources":["../../src/core/envelope-sync.test.ts"],"names":[],"mappings":""}

package/dist/core/envelope-sync.test.js

@@ -0,0 +1,70 @@
+import { describe, expect, it } from "vitest";
+import { correlateEnvelopes } from "./envelope-sync.js";
+/**
+ * Pure-math tests for the correlator. The full envelope pipeline needs ffmpeg
+ * + real audio; the correlator itself is testable in isolation.
+ */
+function buildEnvelope(events, length) {
+    const out = new Float64Array(length);
+    for (const [pos, amp] of events)
+        out[pos] = amp;
+    return out;
+}
+describe("correlateEnvelopes", () => {
+    it("identical envelopes correlate at lag 0 with correlation ~1", () => {
+        const e = buildEnvelope([
+            [10, 1],
+            [20, 0.5],
+            [30, 0.8],
+        ], 60);
+        const r = correlateEnvelopes(e, e, 30);
+        expect(r.lagBlocks).toBe(0);
+        expect(r.correlation).toBeCloseTo(1, 3);
+    });
+    it("a trails b (peaks at later indices) → NEGATIVE lag", () => {
+        // b's peaks at 0, 2 (early in b's timeline)
+        // a's peaks at 3, 5 (late in a's timeline) — a trails b by 3.
+        const b = buildEnvelope([
+            [0, 1],
+            [2, 1],
+        ], 10);
+        const a = buildEnvelope([
+            [3, 1],
+            [5, 1],
+        ], 10);
+        const r = correlateEnvelopes(a, b, 5);
+        expect(r.lagBlocks).toBe(-3);
+        expect(r.correlation).toBeGreaterThan(0.99);
+        // Wall-clock: offsetSec = -lagBlocks * blockSec → positive → a started LATER. ✓
+    });
+    it("a leads b (peaks at earlier indices) → POSITIVE lag", () => {
+        const b = buildEnvelope([
+            [5, 1],
+            [7, 1],
+        ], 12);
+        const a = buildEnvelope([
+            [2, 1],
+            [4, 1],
+        ], 12);
+        const r = correlateEnvelopes(a, b, 5);
+        expect(r.lagBlocks).toBe(3);
+    });
+    it("uncorrelated envelopes return low correlation", () => {
+        // pure random-like signals
+        const a = new Float64Array(100);
+        const b = new Float64Array(100);
+        for (let i = 0; i < 100; i++) {
+            a[i] = Math.sin(i * 0.4);
+            b[i] = Math.cos(i * 0.7);
+        }
+        const r = correlateEnvelopes(a, b, 10);
+        expect(Math.abs(r.correlation)).toBeLessThan(0.7);
+    });
+    it("respects maxLag cap (won't return a lag outside the search range)", () => {
+        const b = buildEnvelope([[0, 1]], 50);
+        const a = buildEnvelope([[20, 1]], 50);
+        const r = correlateEnvelopes(a, b, 5);
+        expect(Math.abs(r.lagBlocks)).toBeLessThanOrEqual(5);
+    });
+});
+//# sourceMappingURL=envelope-sync.test.js.map

package/dist/core/envelope-sync.test.js.map

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

package/dist/core/face-reframe.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Face-tracked reframe — pure planning + ffmpeg-filter synthesis.
+ *
+ * `analyzeReframe` shells out to the MediaPipe / PySceneDetect sidecar to get
+ * a per-shot smoothed face centre. `buildReframeFilter` is a pure function
+ * that compiles the plan into a single ffmpeg `crop=...` expression that
+ * follows the subject across shots. Splitting the heavy I/O from the
+ * filter math keeps the latter unit-testable without Python installed.
+ */
+export type Aspect = "9:16" | "1:1" | "4:5" | "16:9";
+export interface AspectRatio {
+    /** Width side of the ratio (e.g. 9 for 9:16). */
+    w: number;
+    /** Height side of the ratio (e.g. 16 for 9:16). */
+    h: number;
+}
+export declare function parseAspect(aspect: Aspect): AspectRatio;
+export interface ReframeFrameSample {
+    atSec: number;
+    faceCx: number;
+    faceCy: number;
+    faceW: number;
+    faceH: number;
+}
+export type ShotMode = "face" | "motion" | "static";
+export interface ReframeShot {
+    startSec: number;
+    endSec: number;
+    frames: ReframeFrameSample[];
+    /** Smoothed centre X (normalized 0-1). */
+    smoothedX: number;
+    /** Smoothed centre Y (normalized 0-1). */
+    smoothedY: number;
+    mode: ShotMode;
+}
+export interface ReframePlan {
+    shots: ReframeShot[];
+    totalSec: number;
+    fps: number;
+    sourceWidth: number;
+    sourceHeight: number;
+}
+export interface AnalyzeReframeOptions {
+    signal?: AbortSignal;
+    /** Frames per second to face-detect. Default 5. */
+    sampleFps?: number;
+    /** MediaPipe min_detection_confidence. Default 0.5. */
+    minDetectionConfidence?: number;
+    /** Smoothing window in seconds (informational; sidecar uses median). Default 0.5. */
+    smoothingWindowSec?: number;
+}
+/**
+ * Spawn the face-reframe sidecar; return the parsed shot plan.
+ * Throws on sidecar failure with the structured error embedded.
+ */
+export declare function analyzeReframe(videoPath: string, opts?: AnalyzeReframeOptions): Promise<ReframePlan>;
+export interface BuildReframeFilterResult {
+    /** ffmpeg `-vf` value (already includes both crop + scale). */
+    filter: string;
+    /** Output width (after crop, before scale-back). */
+    outWidth: number;
+    /** Output height (after crop, before scale-back). */
+    outHeight: number;
+    /** Per-shot crop X positions (after clamping into [0, srcW-outW]). */
+    shotXs: number[];
+}
+/**
+ * Compute the crop dimensions for a target aspect when cropping FROM a
+ * source frame. The crop is sized to fit ENTIRELY inside the source — i.e.
+ * we letterbox neither dimension. The returned `outW` × `outH` matches the
+ * target aspect exactly.
+ *
+ * Pure / unit-testable.
+ */
+export declare function reframeCropSize(srcW: number, srcH: number, aspect: Aspect): {
+    outW: number;
+    outH: number;
+};
+/**
+ * Compile a per-shot smoothed-face plan into one ffmpeg `crop` expression
+ * that switches X position by timestamp. Each shot contributes one
+ * `if(between(t, a, b), x_i, ...)` tier; the outermost ELSE is a centre
+ * crop so the filter is a no-op outside any defined shot.
+ *
+ * The crop's Y is left static (we don't currently track vertical motion;
+ * faces tend to dominate the upper third on portrait crops anyway).
+ *
+ * Pure / unit-testable. No ffmpeg execution.
+ */
+export declare function buildReframeFilter(plan: ReframePlan, aspect: Aspect): BuildReframeFilterResult;
+//# sourceMappingURL=face-reframe.d.ts.map

package/dist/core/face-reframe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"face-reframe.d.ts","sourceRoot":"","sources":["../../src/core/face-reframe.ts"],"names":[],"mappings":"AAGA;;;;;;;;GAQG;AAEH,MAAM,MAAM,MAAM,GAAG,MAAM,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,CAAC;AAErD,MAAM,WAAW,WAAW;IAC1B,iDAAiD;IACjD,CAAC,EAAE,MAAM,CAAC;IACV,mDAAmD;IACnD,CAAC,EAAE,MAAM,CAAC;CACX;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,CAMvD;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEpD,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,kBAAkB,EAAE,CAAC;IAC7B,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,QAAQ,CAAC;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,qBAAqB;IACpC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,mDAAmD;IACnD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uDAAuD;IACvD,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,qFAAqF;IACrF,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAClC,SAAS,EAAE,MAAM,EACjB,IAAI,GAAE,qBAA0B,GAC/B,OAAO,CAAC,WAAW,CAAC,CAiCtB;AAED,MAAM,WAAW,wBAAwB;IACvC,+DAA+D;IAC/D,MAAM,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,qDAAqD;IACrD,SAAS,EAAE,MAAM,CAAC;IAClB,sEAAsE;IACtE,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GACb;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CA6BhC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,GAAG,wBAAwB,CAsC9F"}