@holostaff/sdk 0.3.0

package/dist/signals.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Fast-path signals — Wave 3b (per runtime doc §6.2).
+ *
+ * Lightweight deterministic context the SDK gathers in the browser and
+ * forwards to the per-stage monitoring agent:
+ *
+ *   - Current SPA route (location.pathname). Tracked via popstate and
+ *     wrapped history.pushState / history.replaceState.
+ *   - Time-of-last-user-interaction. Tracked via window-level
+ *     mousemove / scroll / keydown / touchstart listeners (passive).
+ *
+ * Posted to `POST /api/runtime/sessions/:sessionId/fastpath` on:
+ *   - Initial mount (so the agent has a starting route even before any
+ *     activity).
+ *   - Each route change (debounced — coalesces rapid back-to-back
+ *     navigations into a single emit ~80ms later).
+ *   - A low-frequency heartbeat (HEARTBEAT_MS) so the server's view of
+ *     the user's idle/active state stays current even on a static page.
+ *
+ * Iframe / shadow-DOM / canvas / native-webview caveats from the doc
+ * apply — for hosts where window-level listeners don't catch user
+ * activity, idle detection falls back to vision-only (the timer simply
+ * never updates).
+ */
+import { type TransportConfig } from './transport.js';
+export interface SignalsBindingDeps {
+    cfg: TransportConfig;
+    sessionId: string;
+    tenantId: string;
+    sourceId: string;
+    /** Builds the common body fields (deviceId, hostUserId, tenant/source). */
+    buildBody: () => Record<string, unknown>;
+}
+export interface SignalsBinding {
+    /** Detach all listeners and cancel pending timers. */
+    dispose(): void;
+}
+/**
+ * Start the signals subsystem. Idempotent across calls is the caller's
+ * responsibility — the holostaff singleton ensures one binding per
+ * session via _destroy on re-init.
+ */
+export declare function startSignals(deps: SignalsBindingDeps): SignalsBinding;
+//# sourceMappingURL=signals.d.ts.map

package/dist/signals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signals.d.ts","sourceRoot":"","sources":["../src/signals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAY,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAS/D,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,eAAe,CAAA;IACpB,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,2EAA2E;IAC3E,SAAS,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACzC;AAED,MAAM,WAAW,cAAc;IAC7B,sDAAsD;IACtD,OAAO,IAAI,IAAI,CAAA;CAChB;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,kBAAkB,GAAG,cAAc,CA4IrE"}

package/dist/signals.js

@@ -0,0 +1,155 @@
+/**
+ * Fast-path signals — Wave 3b (per runtime doc §6.2).
+ *
+ * Lightweight deterministic context the SDK gathers in the browser and
+ * forwards to the per-stage monitoring agent:
+ *
+ *   - Current SPA route (location.pathname). Tracked via popstate and
+ *     wrapped history.pushState / history.replaceState.
+ *   - Time-of-last-user-interaction. Tracked via window-level
+ *     mousemove / scroll / keydown / touchstart listeners (passive).
+ *
+ * Posted to `POST /api/runtime/sessions/:sessionId/fastpath` on:
+ *   - Initial mount (so the agent has a starting route even before any
+ *     activity).
+ *   - Each route change (debounced — coalesces rapid back-to-back
+ *     navigations into a single emit ~80ms later).
+ *   - A low-frequency heartbeat (HEARTBEAT_MS) so the server's view of
+ *     the user's idle/active state stays current even on a static page.
+ *
+ * Iframe / shadow-DOM / canvas / native-webview caveats from the doc
+ * apply — for hosts where window-level listeners don't catch user
+ * activity, idle detection falls back to vision-only (the timer simply
+ * never updates).
+ */
+import { postJson } from './transport.js';
+/** Heartbeat cadence. ~30s matches the runtime doc's expected
+ *  per-cycle cadence (§7) and keeps cost low for static-page sessions. */
+const HEARTBEAT_MS = 30000;
+/** Route-change debounce — coalesces rapid navigations. */
+const ROUTE_DEBOUNCE_MS = 80;
+/**
+ * Start the signals subsystem. Idempotent across calls is the caller's
+ * responsibility — the holostaff singleton ensures one binding per
+ * session via _destroy on re-init.
+ */
+export function startSignals(deps) {
+    if (typeof window === 'undefined') {
+        return { dispose: () => { } };
+    }
+    // -------- State ---------------------------------------------------------
+    let lastReportedRoute = null;
+    let lastActivityAt = new Date().toISOString();
+    let pendingRouteTimer = null;
+    let heartbeatTimer = null;
+    let disposed = false;
+    const currentRoute = () => {
+        try {
+            return window.location.pathname + window.location.search;
+        }
+        catch {
+            return '/';
+        }
+    };
+    const send = (route) => {
+        if (disposed)
+            return;
+        void postJson(deps.cfg, `/api/runtime/sessions/${deps.sessionId}/fastpath`, {
+            ...deps.buildBody(),
+            route,
+            lastActivityAt,
+        });
+    };
+    const flushRoute = () => {
+        pendingRouteTimer = null;
+        const cur = currentRoute();
+        if (cur === lastReportedRoute)
+            return;
+        lastReportedRoute = cur;
+        send(cur);
+    };
+    const scheduleRouteFlush = () => {
+        if (pendingRouteTimer)
+            return;
+        pendingRouteTimer = setTimeout(flushRoute, ROUTE_DEBOUNCE_MS);
+    };
+    // -------- Activity listeners --------------------------------------------
+    const onActivity = () => {
+        lastActivityAt = new Date().toISOString();
+        // Do NOT send immediately on every mousemove — the heartbeat will
+        // carry the updated lastActivityAt. We only emit eagerly on route
+        // changes; activity ticks are cheap to batch.
+    };
+    // -------- Route change listeners ----------------------------------------
+    const onPopstate = () => { scheduleRouteFlush(); };
+    const onHashchange = () => { scheduleRouteFlush(); };
+    const originalPushState = window.history.pushState;
+    const originalReplaceState = window.history.replaceState;
+    const wrappedPushState = function (...args) {
+        const result = originalPushState.apply(window.history, args);
+        scheduleRouteFlush();
+        return result;
+    };
+    const wrappedReplaceState = function (...args) {
+        const result = originalReplaceState.apply(window.history, args);
+        scheduleRouteFlush();
+        return result;
+    };
+    window.history.pushState = wrappedPushState;
+    window.history.replaceState = wrappedReplaceState;
+    // -------- Wire it up ----------------------------------------------------
+    // Passive activity listeners — won't block scroll perf.
+    const PASSIVE = { passive: true };
+    window.addEventListener('mousemove', onActivity, PASSIVE);
+    window.addEventListener('scroll', onActivity, PASSIVE);
+    window.addEventListener('keydown', onActivity, PASSIVE);
+    window.addEventListener('touchstart', onActivity, PASSIVE);
+    window.addEventListener('popstate', onPopstate);
+    window.addEventListener('hashchange', onHashchange);
+    // Initial emit — captures the landing route before any nav happens.
+    const initialRoute = currentRoute();
+    lastReportedRoute = initialRoute;
+    send(initialRoute);
+    // Heartbeat — fixed cadence. We don't skip when "idle" because the
+    // server uses the heartbeat itself as evidence the tab is still alive;
+    // idle vs. active is derived from lastActivityAt.
+    heartbeatTimer = setInterval(() => {
+        if (disposed)
+            return;
+        // Emit current route too — cheap insurance against missed route
+        // change events on exotic SPAs.
+        send(currentRoute());
+    }, HEARTBEAT_MS);
+    // -------- Dispose -------------------------------------------------------
+    return {
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            window.removeEventListener('mousemove', onActivity);
+            window.removeEventListener('scroll', onActivity);
+            window.removeEventListener('keydown', onActivity);
+            window.removeEventListener('touchstart', onActivity);
+            window.removeEventListener('popstate', onPopstate);
+            window.removeEventListener('hashchange', onHashchange);
+            // Restore the original History API methods. Safe: even if some
+            // other lib has further-wrapped them in the meantime, restoring
+            // ours keeps the chain intact (no-op if equal).
+            if (window.history.pushState === wrappedPushState) {
+                window.history.pushState = originalPushState;
+            }
+            if (window.history.replaceState === wrappedReplaceState) {
+                window.history.replaceState = originalReplaceState;
+            }
+            if (heartbeatTimer != null) {
+                clearInterval(heartbeatTimer);
+                heartbeatTimer = null;
+            }
+            if (pendingRouteTimer != null) {
+                clearTimeout(pendingRouteTimer);
+                pendingRouteTimer = null;
+            }
+        },
+    };
+}
+//# sourceMappingURL=signals.js.map

package/dist/signals.js.map

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

package/dist/transport.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Transport — fetch + sendBeacon wrappers for runtime endpoints.
+ *
+ * Design rules:
+ *   - Fail-soft: transport never throws into customer code. Errors
+ *     route to the `onError` callback if the caller provided one.
+ *   - Best-effort: no retry queue in Wave 1c. Network blips are
+ *     tolerated; the next call carries the state forward.
+ *   - sendBeacon: used for the pagehide/close path so the request
+ *     survives navigation (Beacon API uses POST with keepalive).
+ */
+import type { InitOptions } from './types.js';
+export interface TransportConfig {
+    baseUrl: string;
+    apiKey?: string;
+    onError?: InitOptions['onError'];
+}
+export declare function resolveTransportConfig(opts: InitOptions): TransportConfig;
+/**
+ * POST JSON to the runtime. Returns true on 2xx, false on transport
+ * or HTTP error. Errors route to onError; never throws.
+ */
+export declare function postJson(cfg: TransportConfig, path: string, body: Record<string, unknown>): Promise<boolean>;
+/**
+ * POST via sendBeacon — survives page navigation. Used by the close
+ * path on pagehide/beforeunload. Falls back to fetch with keepalive
+ * if sendBeacon is unavailable (older browsers, Node).
+ */
+export declare function postBeacon(cfg: TransportConfig, path: string, body: Record<string, unknown>): boolean;
+/**
+ * Open an SSE channel for intervention commands. Returns the
+ * EventSource so the caller can attach listeners + close it.
+ *
+ * Wave 1c: the channel opens but the server doesn't dispatch any
+ * `fire_intervention` events yet (Wave 4). We still establish it now
+ * so customer apps wire it up once and reap commands automatically
+ * when the firing engine lands.
+ */
+export declare function openCommandStream(cfg: TransportConfig, sessionId: string, tenantId: string, sourceId: string): EventSource | null;
+//# sourceMappingURL=transport.d.ts.map

package/dist/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAI7C,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,WAAW,CAAC,SAAS,CAAC,CAAA;CACjC;AAED,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,WAAW,GAAG,eAAe,CAMzE;AAQD;;;GAGG;AACH,wBAAsB,QAAQ,CAC5B,GAAG,EAAE,eAAe,EACpB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,OAAO,CAAC,OAAO,CAAC,CAwBlB;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CACxB,GAAG,EAAE,eAAe,EACpB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,OAAO,CA2BT;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,eAAe,EACpB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,GACf,WAAW,GAAG,IAAI,CAapB"}

package/dist/transport.js

@@ -0,0 +1,113 @@
+/**
+ * Transport — fetch + sendBeacon wrappers for runtime endpoints.
+ *
+ * Design rules:
+ *   - Fail-soft: transport never throws into customer code. Errors
+ *     route to the `onError` callback if the caller provided one.
+ *   - Best-effort: no retry queue in Wave 1c. Network blips are
+ *     tolerated; the next call carries the state forward.
+ *   - sendBeacon: used for the pagehide/close path so the request
+ *     survives navigation (Beacon API uses POST with keepalive).
+ */
+const DEFAULT_BASE_URL = 'https://holostaff-vision-1008066443043.us-central1.run.app';
+export function resolveTransportConfig(opts) {
+    return {
+        baseUrl: opts.baseUrl ?? DEFAULT_BASE_URL,
+        apiKey: opts.apiKey,
+        onError: opts.onError,
+    };
+}
+function buildHeaders(cfg) {
+    const headers = { 'content-type': 'application/json' };
+    if (cfg.apiKey)
+        headers['authorization'] = `Bearer ${cfg.apiKey}`;
+    return headers;
+}
+/**
+ * POST JSON to the runtime. Returns true on 2xx, false on transport
+ * or HTTP error. Errors route to onError; never throws.
+ */
+export async function postJson(cfg, path, body) {
+    try {
+        const res = await fetch(`${cfg.baseUrl}${path}`, {
+            method: 'POST',
+            headers: buildHeaders(cfg),
+            body: JSON.stringify(body),
+            // The runtime endpoints accept anonymous CORS. credentials='omit'
+            // keeps host-app cookies out of cross-origin requests by default.
+            credentials: 'omit',
+            mode: 'cors',
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => '');
+            cfg.onError?.(new Error(`HTTP ${res.status} ${res.statusText}${text ? ` — ${text}` : ''}`), { method: 'POST', path });
+            return false;
+        }
+        return true;
+    }
+    catch (err) {
+        cfg.onError?.(err instanceof Error ? err : new Error(String(err)), { method: 'POST', path });
+        return false;
+    }
+}
+/**
+ * POST via sendBeacon — survives page navigation. Used by the close
+ * path on pagehide/beforeunload. Falls back to fetch with keepalive
+ * if sendBeacon is unavailable (older browsers, Node).
+ */
+export function postBeacon(cfg, path, body) {
+    const url = `${cfg.baseUrl}${path}`;
+    const payload = JSON.stringify(body);
+    if (typeof navigator !== 'undefined' && typeof navigator.sendBeacon === 'function') {
+        try {
+            const blob = new Blob([payload], { type: 'application/json' });
+            return navigator.sendBeacon(url, blob);
+        }
+        catch (err) {
+            cfg.onError?.(err instanceof Error ? err : new Error(String(err)), { method: 'BEACON', path });
+            return false;
+        }
+    }
+    // Fallback: keepalive fetch (also designed to survive unload).
+    try {
+        void fetch(url, {
+            method: 'POST',
+            headers: buildHeaders(cfg),
+            body: payload,
+            keepalive: true,
+            credentials: 'omit',
+            mode: 'cors',
+        });
+        return true;
+    }
+    catch (err) {
+        cfg.onError?.(err instanceof Error ? err : new Error(String(err)), { method: 'BEACON', path });
+        return false;
+    }
+}
+/**
+ * Open an SSE channel for intervention commands. Returns the
+ * EventSource so the caller can attach listeners + close it.
+ *
+ * Wave 1c: the channel opens but the server doesn't dispatch any
+ * `fire_intervention` events yet (Wave 4). We still establish it now
+ * so customer apps wire it up once and reap commands automatically
+ * when the firing engine lands.
+ */
+export function openCommandStream(cfg, sessionId, tenantId, sourceId) {
+    if (typeof EventSource === 'undefined')
+        return null;
+    const qs = new URLSearchParams({ tenantId, sourceId });
+    const url = `${cfg.baseUrl}/api/runtime/sessions/${encodeURIComponent(sessionId)}/commands?${qs}`;
+    try {
+        return new EventSource(url);
+    }
+    catch (err) {
+        cfg.onError?.(err instanceof Error ? err : new Error(String(err)), {
+            method: 'SSE',
+            path: `/api/runtime/sessions/${sessionId}/commands`,
+        });
+        return null;
+    }
+}
+//# sourceMappingURL=transport.js.map

package/dist/transport.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Public types for the SDK.
+ *
+ * `BowtieStage` is duplicated here from the server schema (4th mirror,
+ * see CLAUDE.md memory `project_stage_decomposition_mirrors`). The
+ * SDK ships to customer codebases and can't depend on server internals.
+ * If a stage is added, all four mirrors update in lockstep.
+ */
+export type BowtieStage = 'awareness' | 'education' | 'selection' | 'mutual_commit' | 'onboarding' | 'adoption' | 'expansion';
+export declare const BOWTIE_STAGES: readonly BowtieStage[];
+export interface InitOptions {
+    /** The knowledge source id (e.g. 'cli-source-abc'). Provided by the deploy PR. */
+    sourceId: string;
+    /**
+     * Tenant id. Wave 1: SDK callers pass this explicitly. Future work
+     * derives it from a signed source token so customer code only needs
+     * sourceId.
+     */
+    tenantId: string;
+    /** Base URL of the holostaff runtime. Defaults to the public Cloud Run URL. */
+    baseUrl?: string;
+    /**
+     * Optional API key. Reserved for the per-source auth model that
+     * lands once SDK auth ships (runtime doc §11). Wave 1 callers can
+     * omit; the runtime endpoints are dev-token gated server-side.
+     */
+    apiKey?: string;
+    /**
+     * Optional callback fired on transport errors (network failures,
+     * non-2xx responses). The SDK never throws into customer code; this
+     * is the only way to observe failures.
+     */
+    onError?: (err: Error, ctx: {
+        method: string;
+        path: string;
+    }) => void;
+}
+export type InterventionOutcome = 'pending' | 'dismissed' | 'engaged' | 'progressed' | 'ignored' | 'errored';
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,MAAM,WAAW,GACnB,WAAW,GACX,WAAW,GACX,WAAW,GACX,eAAe,GACf,YAAY,GACZ,UAAU,GACV,WAAW,CAAA;AAEf,eAAO,MAAM,aAAa,EAAE,SAAS,WAAW,EAQtC,CAAA;AAEV,MAAM,WAAW,WAAW;IAC1B,kFAAkF;IAClF,QAAQ,EAAE,MAAM,CAAA;IAChB;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAA;CACtE;AAED,MAAM,MAAM,mBAAmB,GAC3B,SAAS,GACT,WAAW,GACX,SAAS,GACT,YAAY,GACZ,SAAS,GACT,SAAS,CAAA"}

package/dist/types.js

@@ -0,0 +1,18 @@
+/**
+ * Public types for the SDK.
+ *
+ * `BowtieStage` is duplicated here from the server schema (4th mirror,
+ * see CLAUDE.md memory `project_stage_decomposition_mirrors`). The
+ * SDK ships to customer codebases and can't depend on server internals.
+ * If a stage is added, all four mirrors update in lockstep.
+ */
+export const BOWTIE_STAGES = [
+    'awareness',
+    'education',
+    'selection',
+    'mutual_commit',
+    'onboarding',
+    'adoption',
+    'expansion',
+];
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAWH,MAAM,CAAC,MAAM,aAAa,GAA2B;IACnD,WAAW;IACX,WAAW;IACX,WAAW;IACX,eAAe;IACf,YAAY;IACZ,UAAU;IACV,WAAW;CACH,CAAA"}

package/dist/widget.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Widget — Wave 3e.
+ *
+ * Listens to the SSE command channel for `fire_intervention` events
+ * and renders a minimal text pill in the customer's host page. Wires
+ * dismiss / engage user actions back to /outcome.
+ *
+ * Wave 3e scope:
+ *   - `text` modality only. Other modalities (voice / email / sms /
+ *     phone / screen_automation) are logged and ignored — Wave 6.
+ *   - Single visible widget at a time. A new event while one is open
+ *     replaces it (and reports 'ignored' for the prior).
+ *   - No theming. Inline-styled floating pill, fixed lower-right.
+ *
+ * The widget keeps zero dependencies on host CSS — it injects its own
+ * styles into the shadow root of a top-level container so host page
+ * rules can't bleed in or out.
+ */
+import { type TransportConfig } from './transport.js';
+export interface WidgetBindingDeps {
+    cfg: TransportConfig;
+    /** Resolves the current session id at event time (may rotate after clearIdentity). */
+    getSessionId: () => string;
+    /** Common body builder — tenantId/sourceId/deviceId/hostUserId. */
+    buildBody: () => Record<string, unknown>;
+    /** SSE source — the same EventSource the SDK already opened. */
+    source: EventSource | null;
+}
+export interface WidgetBinding {
+    dispose(): void;
+}
+/**
+ * Start the widget subsystem. Subscribes to the SSE `fire_intervention`
+ * event and shows the text pill when one arrives. Idempotent in the
+ * sense that the SDK singleton ensures one binding per session.
+ */
+export declare function startWidget(deps: WidgetBindingDeps): WidgetBinding;
+//# sourceMappingURL=widget.d.ts.map

package/dist/widget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"widget.d.ts","sourceRoot":"","sources":["../src/widget.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAY,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAS/D,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,eAAe,CAAA;IACpB,sFAAsF;IACtF,YAAY,EAAE,MAAM,MAAM,CAAA;IAC1B,mEAAmE;IACnE,SAAS,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACxC,gEAAgE;IAChE,MAAM,EAAE,WAAW,GAAG,IAAI,CAAA;CAC3B;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,IAAI,IAAI,CAAA;CAChB;AAUD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,iBAAiB,GAAG,aAAa,CAiDlE"}