cbrowser 18.78.0 → 18.80.0

package/dist/recording/inline-player.js

@@ -0,0 +1,272 @@
+/**
+ * Self-contained capture player for MCP Apps inline rendering.
+ *
+ * Differs from capture-player.ts in one way that drives every other decision:
+ * that page is served over HTTP from cbrowser.ai and can reference its own
+ * artifacts by URL. This one runs inside the host's widget sandbox, whose CSP
+ * allowlists a fixed set of origins that does not include cbrowser.ai. So it
+ * can fetch nothing. Every pixel it shows has to be embedded.
+ *
+ * data: is permitted in img-src (confirmed against the live sandbox), which is
+ * what makes this possible at all -- and it is also the binding constraint,
+ * because a capture GIF measured between 500KB and 1.4MB and base64 adds a
+ * third on top. So frames are selected rather than included, and re-encoded to
+ * fit a byte budget rather than shipped at capture resolution.
+ *
+ * The full-resolution artifacts stay reachable as links. A link is a navigation,
+ * not a subresource fetch, so the allowlist does not apply to it.
+ */
+import sharp from "sharp";
+import { existsSync } from "node:fs";
+/** Total base64 budget for embedded frames. */
+const INLINE_BUDGET_B64 = 700_000;
+/** Never embed more than this many frames regardless of budget. */
+const MAX_FRAMES = 10;
+/** Widest an embedded frame is rendered; capture width is far more than needed. */
+const FRAME_WIDTH = 720;
+const esc = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+const fmtTime = (ms) => `${(ms / 1000).toFixed(1)}s`;
+/**
+ * Choose which frames to embed.
+ *
+ * Judged moments and interactions are the frames that carry information -- a
+ * frame is a moment precisely because the interface changed enough to re-judge,
+ * and a frame is an interaction because something happened on it. Sampling
+ * evenly would spend the budget on the still stretches between them. Evenly
+ * spaced frames only fill whatever room is left.
+ */
+function selectFrames(data) {
+    const n = data.framePaths.length;
+    if (n === 0)
+        return [];
+    const picked = new Set([0]);
+    for (const m of data.moments ?? []) {
+        if (m.frameIndex >= 0 && m.frameIndex < n)
+            picked.add(m.frameIndex);
+    }
+    for (const it of data.interactions ?? []) {
+        // The frame that shows the click is the first one at or after it.
+        const idx = data.frameTimesMs.findIndex((t) => t >= it.atMs);
+        if (idx >= 0)
+            picked.add(idx);
+    }
+    picked.add(n - 1);
+    const chosen = [...picked].filter((i) => i >= 0 && i < n).sort((a, b) => a - b);
+    if (chosen.length >= MAX_FRAMES)
+        return chosen.slice(0, MAX_FRAMES);
+    // Fill remaining slots with an even spread, skipping anything already picked.
+    const want = MAX_FRAMES - chosen.length;
+    for (let k = 1; k <= want && chosen.length < MAX_FRAMES; k++) {
+        const idx = Math.round((k / (want + 1)) * (n - 1));
+        if (!picked.has(idx)) {
+            picked.add(idx);
+            chosen.push(idx);
+        }
+    }
+    return [...picked].sort((a, b) => a - b);
+}
+/**
+ * Encode one frame to a data URI under a byte ceiling.
+ *
+ * Steps quality down rather than dimensions: the frames carry an attention
+ * overlay whose whole content is where colour sits on the page, and shrinking
+ * the raster blurs that away faster than JPEG artefacts do.
+ */
+async function encodeFrame(path, ceilingB64) {
+    if (!existsSync(path))
+        return undefined;
+    for (const quality of [72, 58, 46, 36, 28, 20]) {
+        try {
+            const buf = await sharp(path).resize({ width: FRAME_WIDTH, withoutEnlargement: true })
+                .jpeg({ quality }).toBuffer();
+            if (Math.ceil(buf.length * 4 / 3) <= ceilingB64) {
+                return `data:image/jpeg;base64,${buf.toString("base64")}`;
+            }
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return undefined;
+}
+export async function buildInlineCapturePlayer(data) {
+    const idxs = selectFrames(data);
+    const perFrame = idxs.length > 0 ? Math.floor(INLINE_BUDGET_B64 / idxs.length) : 0;
+    const frames = [];
+    for (const i of idxs) {
+        const p = data.framePaths[i];
+        if (!p)
+            continue;
+        const uri = await encodeFrame(p, perFrame);
+        if (uri)
+            frames.push({ idx: i, tMs: data.frameTimesMs[i] ?? 0, uri });
+    }
+    const acts = (data.interactions ?? []).slice().sort((a, b) => a.atMs - b.atMs);
+    const dur = Math.max(1, data.durationMs);
+    const momentBy = new Map((data.moments ?? []).map((m) => [m.frameIndex, m]));
+    const embeddedBytes = frames.reduce((n, f) => n + f.uri.length, 0);
+    const head = `
+  <header>
+    <p class="eyebrow">CBrowser capture</p>
+    <h1>${esc(data.targetUrl ?? data.slug)}</h1>
+    <p class="meta">${fmtTime(data.durationMs)} &middot; ${data.framePaths.length} frames &middot;
+      ${data.actualFps.toFixed(1)} fps${data.personaName ? ` &middot; persona: ${esc(data.personaName)}` : ""}${data.goal ? ` &middot; goal: ${esc(data.goal)}` : ""}</p>
+    ${data.overlay ? `<p class="pill ${data.overlay.quantity === "predicted-attention" ? "ok" : "warn"}">${data.overlay.quantity === "predicted-attention"
+        ? `predicted attention &middot; ${data.overlay.domElements} elements`
+        : "visual contrast only &middot; no DOM"}</p>` : ""}
+  </header>`;
+    const viewer = frames.length === 0
+        ? `<p class="empty">No frames could be embedded for this capture.</p>`
+        : `
+  <div class="viewer">
+    ${frames.map((f, i) => `<img class="fr${i === 0 ? " on" : ""}" data-i="${i}" src="${f.uri}" alt="Frame ${f.idx} at ${fmtTime(f.tMs)}">`).join("")}
+  </div>
+  <div class="controls">
+    <button type="button" id="prev" aria-label="Previous frame">&#9666;</button>
+    <button type="button" id="play" aria-label="Play">&#9654;</button>
+    <button type="button" id="next" aria-label="Next frame">&#9656;</button>
+    <input type="range" id="scrub" min="0" max="${frames.length - 1}" value="0" step="1" aria-label="Frame">
+    <span class="tc" id="tc">${fmtTime(frames[0]?.tMs ?? 0)}</span>
+  </div>
+  <p class="note">${frames.length} of ${data.framePaths.length} frames embedded, chosen at judged moments and interactions.
+    ${(embeddedBytes / 1024).toFixed(0)}&thinsp;KB inline.</p>`;
+    const track = acts.length === 0 ? "" : `
+  <section>
+    <h2>Interactions</h2>
+    <div class="track">
+      ${acts.map((a) => `<button type="button" class="mark" data-at="${a.atMs}" style="--x:${((a.atMs / dur) * 100).toFixed(2)}%" title="${esc(a.type)}: ${esc(a.label.slice(0, 60))}"><span class="dot" data-type="${esc(a.type)}"></span></button>`).join("")}
+    </div>
+    <ol class="actlist">
+      ${acts.map((a) => `<li><button type="button" data-at="${a.atMs}"><span class="t">${fmtTime(a.atMs)}</span><span class="kind" data-type="${esc(a.type)}">${esc(a.type)}</span><span class="lab">${esc(a.label.slice(0, 80) || "(no label)")}</span></button></li>`).join("")}
+    </ol>
+  </section>`;
+    const timeline = (data.moments ?? []).length === 0 ? "" : `
+  <section>
+    <h2>Attention timeline</h2>
+    <ol class="moments">
+      ${(data.moments ?? []).map((m) => `
+      <li>
+        <div class="t">${fmtTime(m.tMs)}<span class="frame">frame ${m.frameIndex}</span></div>
+        <div class="body">
+          ${m.topElements.length > 0 ? `<ul class="els">${m.topElements.slice(0, 5).map((e) => `
+            <li><span class="bar" style="--w:${Math.round(e.score * 100)}%"></span><span class="score">${e.score.toFixed(2)}</span><span class="txt">${esc(e.text.slice(0, 70))}</span></li>`).join("")}</ul>` : ""}
+          ${m.reasoning ? `<p class="why">${esc(m.reasoning)}</p>` : ""}
+        </div>
+      </li>`).join("")}
+    </ol>
+  </section>`;
+    const summary = data.summary ? `<section class="summary"><h2>How this went</h2><p>${esc(data.summary)}</p></section>` : "";
+    // Links, not embeds. A link is a navigation and the origin allowlist does not
+    // govern it, so full-resolution artifacts stay one click away even though the
+    // sandbox will not fetch them into this frame.
+    const links = [
+        ...(data.playerUrl ? [[`full player`, data.playerUrl]] : []),
+        ...Object.entries(data.artifactUrls ?? {}),
+    ];
+    const dl = links.length === 0 ? "" : `
+  <section><h2>Full artifacts</h2><p class="lede">Open outside this panel &mdash; the sandbox will not load them inline.</p>
+  <div class="dl">${links.map(([k, u]) => `<a href="${esc(u)}" target="_blank" rel="noopener">${esc(k)}</a>`).join("")}</div></section>`;
+    const frameTimes = JSON.stringify(frames.map((f) => f.tMs));
+    return `<!doctype html><meta charset="utf-8">
+<style>
+  :root{color-scheme:light dark;--ink:#14161a;--ground:#fff;--muted:#666;--rule:#d9dce1;--accent:#2f6f4f;--card:#fff}
+  @media (prefers-color-scheme:dark){:root{--ink:#e8eaed;--ground:#16181c;--muted:#9aa0a8;--rule:#31353b;--accent:#6fbf8f;--card:#1d2025}}
+  *{box-sizing:border-box}
+  body{margin:0;padding:16px;font:15px/1.55 ui-sans-serif,system-ui,-apple-system,sans-serif;color:var(--ink);background:var(--ground)}
+  .eyebrow{font:600 .68rem/1 ui-monospace,monospace;letter-spacing:.14em;text-transform:uppercase;color:var(--muted);margin:0 0 .45rem}
+  h1{font-size:1.12rem;margin:0 0 .35rem;word-break:break-all;text-wrap:balance}
+  h2{font-size:.95rem;margin:1.4rem 0 .5rem}
+  .meta{font:.78rem/1.4 ui-monospace,monospace;color:var(--muted);margin:0 0 .5rem}
+  .pill{display:inline-block;font:.68rem/1 ui-monospace,monospace;letter-spacing:.06em;text-transform:uppercase;padding:.3rem .5rem;border-radius:4px;margin:0}
+  .pill.ok{background:color-mix(in srgb,var(--accent) 18%,transparent);color:var(--accent)}
+  .pill.warn{background:color-mix(in srgb,#c98a2b 20%,transparent)}
+  .viewer{position:relative;margin:.9rem 0 .5rem;border:1px solid var(--rule);border-radius:8px;overflow:hidden;background:var(--card)}
+  .viewer img{display:none;width:100%;height:auto}
+  .viewer img.on{display:block}
+  .controls{display:flex;align-items:center;gap:.5rem}
+  .controls button{font-size:.9rem;padding:.25rem .55rem;border:1px solid var(--rule);border-radius:5px;background:var(--card);color:inherit;cursor:pointer}
+  .controls button:hover{border-color:var(--accent)}
+  .controls button:focus-visible,.mark:focus-visible,.actlist button:focus-visible{outline:2px solid var(--accent);outline-offset:2px}
+  #scrub{flex:1;accent-color:var(--accent);min-width:60px}
+  .tc{font:.75rem/1 ui-monospace,monospace;color:var(--muted);font-variant-numeric:tabular-nums;flex:0 0 auto}
+  .note,.lede{font-size:.78rem;color:var(--muted);margin:.4rem 0 0}
+  .track{position:relative;height:24px;margin:.3rem 0 .7rem;border:1px solid var(--rule);border-radius:4px;background:color-mix(in srgb,var(--rule) 30%,transparent)}
+  .mark{position:absolute;left:var(--x);top:0;height:100%;width:18px;transform:translateX(-9px);background:none;border:0;padding:0;cursor:pointer;display:grid;place-items:center}
+  .mark .dot{width:10px;height:10px;border-radius:50%;background:var(--accent);border:2px solid var(--card);box-shadow:0 0 0 1px var(--accent)}
+  .mark .dot[data-type="submit"]{background:#d1495b;box-shadow:0 0 0 1px #d1495b}
+  .mark .dot[data-type="input"]{background:#e0a458;box-shadow:0 0 0 1px #e0a458}
+  .actlist,.moments{list-style:none;padding:0;margin:0}
+  .actlist button{display:flex;gap:.55rem;align-items:baseline;width:100%;text-align:left;background:none;border:0;border-radius:4px;padding:.28rem .4rem;cursor:pointer;color:inherit;font:inherit}
+  .actlist button:hover{background:color-mix(in srgb,var(--accent) 10%,transparent)}
+  .actlist .t,.moments .t{font:.73rem/1 ui-monospace,monospace;color:var(--muted);flex:0 0 3.2rem;font-variant-numeric:tabular-nums}
+  .kind{font:.63rem/1 ui-monospace,monospace;text-transform:uppercase;letter-spacing:.07em;padding:.1rem .32rem;border-radius:3px;background:color-mix(in srgb,var(--accent) 16%,transparent)}
+  .kind[data-type="submit"]{background:color-mix(in srgb,#d1495b 18%,transparent)}
+  .kind[data-type="input"]{background:color-mix(in srgb,#e0a458 22%,transparent)}
+  .lab,.txt{font-size:.84rem;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+  .moments li{display:flex;gap:.7rem;padding:.5rem 0;border-top:1px solid var(--rule)}
+  .moments .frame{display:block;font-size:.63rem;opacity:.7}
+  .els{list-style:none;padding:0;margin:0 0 .35rem}
+  .els li{display:grid;grid-template-columns:3ch 1fr;gap:.4rem;align-items:center;position:relative;padding:.12rem 0}
+  .bar{position:absolute;left:0;top:0;bottom:0;width:var(--w);background:color-mix(in srgb,var(--accent) 15%,transparent);border-radius:3px;z-index:0}
+  .score,.txt{position:relative;z-index:1}
+  .score{font:.7rem/1 ui-monospace,monospace;color:var(--muted);font-variant-numeric:tabular-nums}
+  .why{font-size:.84rem;margin:.3rem 0 0;color:var(--muted)}
+  .summary{border-left:3px solid var(--accent);padding:.1rem 0 .1rem .8rem;margin-top:1.4rem}
+  .dl{display:flex;flex-wrap:wrap;gap:.4rem;margin-top:.4rem}
+  .dl a{font:.78rem/1 ui-monospace,monospace;padding:.34rem .6rem;border:1px solid var(--rule);border-radius:5px;text-decoration:none;color:var(--accent)}
+  .dl a:hover{border-color:var(--accent)}
+  .empty{color:var(--muted);font-size:.88rem}
+  @media (prefers-reduced-motion:reduce){*{transition:none!important}}
+</style>
+${head}
+${viewer}
+${track}
+${summary}
+${timeline}
+${dl}
+<script>
+(function(){
+  var imgs = Array.prototype.slice.call(document.querySelectorAll(".viewer .fr"));
+  if (!imgs.length) return;
+  var times = ${frameTimes};
+  var scrub = document.getElementById("scrub");
+  var tc = document.getElementById("tc");
+  var playBtn = document.getElementById("play");
+  var cur = 0, timer = null;
+
+  function show(i){
+    cur = Math.max(0, Math.min(imgs.length - 1, i));
+    imgs.forEach(function(im, k){ im.classList.toggle("on", k === cur); });
+    scrub.value = String(cur);
+    tc.textContent = ((times[cur] || 0) / 1000).toFixed(1) + "s";
+  }
+  function stop(){ if (timer) { clearInterval(timer); timer = null; playBtn.innerHTML = "&#9654;"; } }
+  function play(){
+    if (timer) return stop();
+    playBtn.innerHTML = "&#10073;&#10073;";
+    timer = setInterval(function(){
+      if (cur >= imgs.length - 1) { show(0); } else { show(cur + 1); }
+    }, 700);
+  }
+  document.getElementById("prev").addEventListener("click", function(){ stop(); show(cur - 1); });
+  document.getElementById("next").addEventListener("click", function(){ stop(); show(cur + 1); });
+  playBtn.addEventListener("click", play);
+  scrub.addEventListener("input", function(){ stop(); show(parseInt(scrub.value, 10)); });
+
+  // Interaction markers seek to the embedded frame nearest that moment. Only a
+  // subset of frames is embedded, so this lands on the closest one rather than
+  // pretending every timestamp has a frame behind it.
+  document.querySelectorAll("[data-at]").forEach(function(b){
+    b.addEventListener("click", function(){
+      var at = parseInt(b.getAttribute("data-at"), 10);
+      var best = 0, bestD = Infinity;
+      times.forEach(function(t, k){ var d = Math.abs(t - at); if (d < bestD) { bestD = d; best = k; } });
+      stop(); show(best);
+    });
+  });
+  show(0);
+})();
+</script>`;
+}
+//# sourceMappingURL=inline-player.js.map

package/dist/recording/inline-player.js.map

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

package/dist/recording/saliency-overlay.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Attention overlay for captured frames.
+ *
+ * Renders the model's predicted-attention map over each captured frame so a
+ * recording can be watched with the attention structure visible, then handed to
+ * the normal encoders as an ordinary frame sequence.
+ *
+ * WHY THIS USES THE DOM. Capture runs against a LIVE page, so the DOM is right
+ * there — and `analyzeAttention` blends 35% bottom-up colour contrast with 65%
+ * DOM semantics (element type x persona priority x goal relevance). Overlaying
+ * the bottom-up half alone would paint the one component that has been
+ * benchmarked and LOST: on 495 web pages against real human fixations it scored
+ * AUC 0.585 versus a plain centre-bias baseline's 0.658. Passing DOM elements
+ * makes this the actual production attention model rather than the weakest
+ * quarter of it. Falls back to visual-only when no DOM is supplied, and says so
+ * in the result.
+ *
+ * WHAT IT DOES AND DOES NOT ESTABLISH. With DOM this is the product's attention
+ * prediction — legitimately what cbrowser computes and sells. It is not a
+ * *validated* gaze prediction: the semantic layer carrying most of the blend has
+ * never been tested against human eye movements in either direction, which is
+ * what the primary collection study is being built to settle. So "predicted
+ * attention" is accurate; "where users look" asserts an accuracy nobody has
+ * measured yet. (2026-07-30)
+ *
+ * Cost: one attention pass per frame, roughly 0.5-1s each at typical viewport
+ * sizes. A 5s capture at 10fps is ~50 frames, so budget 30-60s. That is why
+ * this is opt-in and never the default.
+ */
+import { type DOMAttentionElement } from "../visual/attention-transport.js";
+import { type JudgedMoment, type RelevanceContext } from "../visual/llm-relevance.js";
+export interface AttentionOverlayOptions {
+    /** 0-1 opacity of the heat layer. Default 0.55 — readable without hiding the page. */
+    opacity?: number;
+    /**
+     * Cells below this fraction of the frame's peak stay fully transparent, so the
+     * overlay marks hot regions rather than tinting everything. Default 0.35.
+     */
+    floor?: number;
+    /** Analysis cell size in px. Default 16, matching the shipped attention model. */
+    cellSize?: number;
+    /** Persona whose priorities weight the semantic layer. Default "first-timer". */
+    persona?: string;
+    /**
+     * DOM elements as the attention model consumes them. Supply these and the
+     * overlay reflects the full 35/65 blend; omit them and it degrades to
+     * bottom-up contrast only.
+     */
+    domElements?: DOMAttentionElement[];
+    /** Goal string, which weights goal-relevance in the semantic layer. */
+    goal?: string;
+    /**
+     * Frame indices where the interface changed enough to warrant re-judging.
+     *
+     * The capture engine already computes this as `key_frames` via SSIM, and it is
+     * the right trigger precisely because it does not saturate the way
+     * `change_points` does. Re-judging every frame would cost one model call per
+     * frame; re-judging only where the page actually changed costs a handful per
+     * recording and produces the same map, because between keyframes the page —
+     * and therefore the judgement — is unchanged.
+     */
+    keyFrames?: number[];
+    /** Per-frame timestamps, used to place moments on the recording timeline. */
+    frameTimesMs?: number[];
+    /**
+     * DOM as it stood at points in time, captured on navigation during recording.
+     *
+     * A judged frame uses the snapshot in effect AT ITS TIMESTAMP. Without this,
+     * every frame was scored against the page the capture ended on — so a frame
+     * on the pricing page got ranked against a post-click verification screen,
+     * every moment came back identical, and the summary read that uniformity as a
+     * UX finding rather than as the artifact it was.
+     */
+    domTimeline?: Array<{
+        atMs: number;
+        scrollY?: number;
+        elements: DOMAttentionElement[];
+    }>;
+    /** Scroll position over time, used to correct rects for drift since capture. */
+    scrollTrack?: Array<{
+        atMs: number;
+        scrollY: number;
+    }>;
+    /** Real interactions, for the click pulse and for the summary's action log. */
+    interactions?: Array<{
+        atMs: number;
+        type: string;
+        x: number;
+        y: number;
+        label: string;
+    }>;
+    /** Persona context for the relevance judge and the closing summary. */
+    relevanceContext?: Omit<RelevanceContext, "screenshot">;
+    /** Produce a narrative of the whole recording after the frames are overlaid. */
+    summarize?: boolean;
+    /** Resolves the Anthropic key. Absent means no judging and no summary. */
+    getApiKey?: () => string | null;
+}
+export interface OverlayResult {
+    frames: string[];
+    dir: string;
+    /** Judged moments, one per keyframe the judge was re-run on. */
+    moments?: JudgedMoment[];
+    /** Narrative of the whole recording, when a summary was requested. */
+    summary?: string;
+    /** Frames that could not be overlaid and fell back to the original. */
+    failed: number;
+    /** True when DOM elements were supplied, i.e. the full model ran. */
+    usedDom: boolean;
+    /** The quantity that was painted, for callers that label the artifact. */
+    quantity: "predicted-attention" | "visual-contrast-only";
+    /**
+     * Whether the requested persona actually exists.
+     *
+     * An unknown name does not error — it falls through keyword inference to a
+     * default, which is right for custom personas and silent for typos. A caller
+     * who asks for "alexa-eden" and gets a generic profile has no way to tell,
+     * and every number downstream is then attributed to a persona that never ran.
+     */
+    personaResolved?: boolean;
+    /** The persona actually used, which may differ from the one requested. */
+    personaUsed?: string;
+}
+/**
+ * Overlay predicted attention onto every frame, writing a parallel set beside
+ * the originals.
+ *
+ * A frame that fails falls back to the ORIGINAL frame rather than being
+ * dropped: a recording with one un-overlaid frame is still usable, while a
+ * missing frame corrupts the timing of every frame after it.
+ */
+export declare function overlayAttentionOnFrames(framePaths: string[], outDir: string, options?: AttentionOverlayOptions): Promise<OverlayResult>;
+//# sourceMappingURL=saliency-overlay.d.ts.map

package/dist/recording/saliency-overlay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"saliency-overlay.d.ts","sourceRoot":"","sources":["../../src/recording/saliency-overlay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAKH,OAAO,EAAoB,KAAK,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AAC9F,OAAO,EAGL,KAAK,YAAY,EACjB,KAAK,gBAAgB,EAEtB,MAAM,4BAA4B,CAAC;AAEpC,MAAM,WAAW,uBAAuB;IACtC,sFAAsF;IACtF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kFAAkF;IAClF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iFAAiF;IACjF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,WAAW,CAAC,EAAE,mBAAmB,EAAE,CAAC;IACpC,uEAAuE;IACvE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;;;;;OASG;IACH,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,6EAA6E;IAC7E,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,mBAAmB,EAAE,CAAA;KAAE,CAAC,CAAC;IACzF,gFAAgF;IAChF,WAAW,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACvD,+EAA+E;IAC/E,YAAY,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC1F,uEAAuE;IACvE,gBAAgB,CAAC,EAAE,IAAI,CAAC,gBAAgB,EAAE,YAAY,CAAC,CAAC;IACxD,gFAAgF;IAChF,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,0EAA0E;IAC1E,SAAS,CAAC,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;CACjC;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,gEAAgE;IAChE,OAAO,CAAC,EAAE,YAAY,EAAE,CAAC;IACzB,sEAAsE;IACtE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uEAAuE;IACvE,MAAM,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,OAAO,EAAE,OAAO,CAAC;IACjB,0EAA0E;IAC1E,QAAQ,EAAE,qBAAqB,GAAG,sBAAsB,CAAC;IACzD;;;;;;;OAOG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAwID;;;;;;;GAOG;AACH,wBAAsB,wBAAwB,CAC5C,UAAU,EAAE,MAAM,EAAE,EACpB,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,aAAa,CAAC,CAoMxB"}