@scalebun/web 1.0.0

package/dist/features/inbox/sync.js

@@ -0,0 +1,131 @@
+/**
+ * InboxSync (A1.3) — the delta-sync engine + conflict resolution.
+ *
+ * Two conflict domains, resolved differently (docs/INBOX-COACHMARKS-ARCHITECTURE.md §2.7):
+ *   1. CONTENT (server changed a message) → server-authoritative by `revision` (higher wins).
+ *   2. STATE (read here, archived there) → LWW by client `stateAt`, with delete winning absolutely and
+ *      the lifecycle DAG preventing regression — a stale write can never resurrect a message another
+ *      device archived/deleted. This is the guarantee Braze/Intercom lack (their bg sync can un-read).
+ *
+ * The message store doubles as the outbox: a local mutation flags `_dirty`; sync pushes those as ops and
+ * clears the flag on ack. Offline/failure keeps the flag (already persisted) → retried next sync.
+ */
+import { isOnline } from '../../core/retry';
+const RANK = { unread: 0, read: 1, archived: 2, deleted: 3 };
+const CONTENT_KEYS = [
+    'revision', 'campaignId', 'category', 'priority', 'title', 'body', 'html',
+    'imageUrl', 'iconUrl', 'cta', 'createdAt', 'expiresAt', 'groupKey', 'data',
+];
+/** Pure two-way merge for one message. `local` undefined = brand-new from the server. */
+export function mergeMessage(local, server) {
+    if (!local)
+        return server;
+    // 1. CONTENT — server wins only when its revision is strictly higher; keep local state fields.
+    let out = local;
+    if (server.revision > local.revision) {
+        const o = { ...local };
+        const s = server;
+        for (const k of CONTENT_KEYS)
+            o[k] = s[k];
+        out = o;
+    }
+    // 2. STATE — delete wins absolutely; else LWW by stateAt (server wins ties → authoritative). The DAG
+    //    guarantees no regression below what either side already reached, EXCEPT an explicit newer
+    //    regression (markUnread/unarchive) whose greater stateAt legitimately wins.
+    const ls = local.stateAt ?? 0;
+    const ss = server.stateAt ?? 0;
+    if (local.state === 'deleted' || server.state === 'deleted') {
+        out = { ...out, state: 'deleted', stateAt: Math.max(ls, ss), deletedAt: local.deletedAt ?? server.deletedAt };
+    }
+    else if (ss >= ls) {
+        out = { ...out, state: server.state, stateAt: ss, readAt: server.readAt, archivedAt: server.archivedAt };
+    }
+    else {
+        out = { ...out, state: local.state, stateAt: ls };
+    }
+    // 3. PIN — independent boolean, LWW by pinnedAt (server wins ties).
+    const lp = local.pinnedAt ?? 0;
+    const sp = server.pinnedAt ?? 0;
+    out = { ...out, pinned: sp >= lp ? server.pinned : local.pinned, pinnedAt: Math.max(lp, sp) || undefined };
+    return out;
+}
+/** Highest lifecycle rank reached — exported for the runtime's DAG guard + tests. */
+export function stateRank(s) {
+    return RANK[s];
+}
+export class InboxSync {
+    constructor(deps) {
+        this.deps = deps;
+        this.cursor = null;
+        this.cursorLoaded = false;
+        this.inflight = null;
+    }
+    /** Pull server deltas + push the local outbox, then reconcile. Single-flight: a concurrent call joins
+     *  the in-flight sync rather than racing it. Never throws. */
+    sync() {
+        if (this.inflight)
+            return this.inflight;
+        this.inflight = this.run().finally(() => { this.inflight = null; });
+        return this.inflight;
+    }
+    async run() {
+        this.deps.onStatus('syncing');
+        try {
+            if (!this.cursorLoaded) {
+                this.cursor = (await this.deps.store.getMeta('cursor')) ?? null;
+                this.cursorLoaded = true;
+            }
+            const ops = this.deps.runtime.collectDirtyOps();
+            const sent = new Map(ops.map((o) => [o.id, { stateAt: o.stateAt, pinnedAt: o.pinnedAt }]));
+            const req = { cursor: this.cursor, ops };
+            const res = await this.deps.transport.sync(req);
+            if (!res) {
+                this.deps.onStatus(isOnline() ? 'error' : 'offline'); // outbox persists → retried next sync
+                return;
+            }
+            if (res.theme)
+                this.deps.onTheme?.(res.theme);
+            this.deps.runtime.applyServerDelta(res.messages ?? [], res.tombstones ?? [], res.unreadCount);
+            this.deps.runtime.ackDirty(sent); // clear _dirty for pushed ops the user hasn't re-touched
+            if (res.cursor !== undefined) {
+                this.cursor = res.cursor;
+                await this.deps.store.setMeta('cursor', res.cursor);
+            }
+            this.deps.onStatus('idle');
+        }
+        catch {
+            this.deps.onStatus(isOnline() ? 'error' : 'offline');
+        }
+    }
+}
+/** Real HTTP transport — mirrors EngageTransport (x-scalebun-client-key, best-effort, never throws). Returns
+ *  null on any non-2xx / network error so the engine keeps the outbox for retry. */
+export class InboxTransport {
+    constructor(apiBaseUrl, clientKey, deviceId) {
+        this.apiBaseUrl = apiBaseUrl;
+        this.clientKey = clientKey;
+        this.deviceId = deviceId;
+    }
+    get usable() {
+        return !!this.clientKey && !!this.apiBaseUrl && typeof fetch !== 'undefined';
+    }
+    async sync(req) {
+        if (!this.usable)
+            return null;
+        try {
+            const res = await fetch(`${this.apiBaseUrl}/sdk/inbox/sync`, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json', 'x-scalebun-client-key': this.clientKey },
+                body: JSON.stringify({ schemaVersion: 1, deviceId: this.deviceId, ...req }),
+                keepalive: true,
+            });
+            if (!res.ok)
+                return null;
+            return (await res.json());
+        }
+        catch {
+            return null;
+        }
+    }
+}
+//# sourceMappingURL=sync.js.map

package/dist/features/inbox/sync.js.map

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

package/dist/features/inbox/types.d.ts

@@ -0,0 +1,275 @@
+/**
+ * Inbox contracts (headless-first). These types are the stable surface a host depends on whether it
+ * uses our shadow-DOM UI or renders its own. Server is the system of record; the SDK is a bounded,
+ * offline-first local cache (see docs/INBOX-COACHMARKS-ARCHITECTURE.md §2).
+ *
+ * A1.1 scope: the model contracts + controller surface. The IndexedDB store (A1.2), delta sync +
+ * conflict resolution (A1.3), and sync triggers/consent (A1.4) land beneath this same surface without
+ * changing it.
+ */
+/** Lifecycle states, ordered — state may only advance along this DAG (monotonic, no regression). */
+export type InboxMessageState = 'unread' | 'read' | 'archived' | 'deleted';
+/** A message action. `link` opens an https URL; `deep`/`custom` are surfaced to the host (SDK never
+ *  force-navigates); `dismiss` just closes + records. */
+export interface InboxCta {
+    key: string;
+    label: string;
+    action: 'link' | 'deep' | 'custom' | 'dismiss';
+    url?: string;
+}
+export interface InboxMessage {
+    /** Server ULID — globally unique + lexically sortable by creation. Primary dedupe key. */
+    id: string;
+    /** Links back to the originating EngageCampaign (funnel/goal attribution). */
+    campaignId?: string;
+    /** Server monotonic content revision — governs content-conflict resolution (higher wins). */
+    revision: number;
+    category: string;
+    /** 0=low … 3=critical (pins, forces unread, never silently swept). */
+    priority: 0 | 1 | 2 | 3;
+    title: string;
+    body?: string;
+    /** Pre-sanitized rich body (server + client allowlist; rendered in shadow DOM, no scripts). */
+    html?: string;
+    imageUrl?: string;
+    iconUrl?: string;
+    cta?: InboxCta[];
+    createdAt: number;
+    expiresAt?: number;
+    /** Server-computed collapse key (thread grouping). */
+    groupKey?: string;
+    data?: Record<string, unknown>;
+    state: InboxMessageState;
+    pinned: boolean;
+    seenAt?: number;
+    readAt?: number;
+    archivedAt?: number;
+    deletedAt?: number;
+    /** Client ts of the last STATE change — the LWW key for state conflict resolution (A1.3). */
+    stateAt?: number;
+    /** Client ts of the last PIN toggle — the LWW key for pin conflict resolution (A1.3). */
+    pinnedAt?: number;
+    /** @internal — a local mutation not yet acknowledged by the server (drives the sync outbox). */
+    _dirty?: boolean;
+}
+/** One local mutation to push (the message store doubles as the outbox — dirty messages become ops). */
+export interface InboxDirtyOp {
+    id: string;
+    state: InboxMessageState;
+    pinned: boolean;
+    stateAt: number;
+    pinnedAt?: number;
+}
+export interface InboxSyncRequest {
+    /** Opaque server watermark from the last sync (null = first sync → server returns the retained window). */
+    cursor: string | null;
+    ops: InboxDirtyOp[];
+}
+export interface InboxSyncResponse {
+    messages: InboxMessage[];
+    tombstones?: string[];
+    cursor: string | null;
+    /** Server's canonical unread count — used to reconcile the local incremental counter. */
+    unreadCount?: number;
+    /**
+     * Dashboard-authored appearance, so a brand change needs no deploy.
+     *
+     * ⚠️ Rides the sync response rather than a separate fetch: the SDK already syncs at mount, so a
+     * dedicated request would be a second round trip AND would race the first paint — the widget would
+     * visibly repaint into the brand.
+     *
+     * ⚠️ CODE STILL WINS. `mount()` options are applied over this, because an API call is a stronger
+     * statement of intent than a remote setting, and because a developer debugging a colour must be
+     * able to pin it locally.
+     */
+    theme?: InboxRemoteTheme;
+}
+/**
+ * The dashboard-owned half of customization. Colours + copy only.
+ *
+ * ⚠️ Placement (`trigger`, `position`, `rtl`, z-index) is deliberately NOT here — it depends on the
+ * host's DOM and stacking context, which a dashboard cannot know. Nothing is settable from both
+ * sides, so precedence never has to be explained.
+ */
+export interface InboxRemoteTheme {
+    /** `--scalebun-inbox-*` values, keyed WITHOUT the prefix (`bg`, `accent`, `radius`…). */
+    tokens?: Record<string, string>;
+    /** A subset of `InboxLabels` — the two plural-aware functions stay code-only. */
+    labels?: Record<string, string>;
+}
+/** The transport the sync engine depends on (real HTTP in prod; a fake in tests). Returns null on any
+ *  failure so the engine can mark offline/error and keep the outbox for the next attempt. */
+export interface InboxSyncTransport {
+    sync(req: InboxSyncRequest): Promise<InboxSyncResponse | null>;
+}
+export interface InboxQueryOptions {
+    category?: string;
+    /** Single state or a set; omitted = everything except `deleted`. */
+    state?: InboxMessageState | InboxMessageState[];
+    pinned?: boolean;
+    sort?: 'newest' | 'priority';
+    /** Page size (default 20). */
+    limit?: number;
+    /** Keyset cursor from a prior page (opaque). */
+    cursor?: string | null;
+}
+export interface InboxPage {
+    messages: InboxMessage[];
+    cursor: string | null;
+    hasMore: boolean;
+}
+export type InboxSyncStatus = 'idle' | 'syncing' | 'offline' | 'error';
+/** The cheap reactive snapshot a host subscribes to (badge + panel header). */
+export interface InboxState {
+    unreadCount: number;
+    total: number;
+    syncStatus: InboxSyncStatus;
+}
+/** Options for the built-in shadow-DOM inbox UI (A2). */
+/**
+ * Every string the widget renders.
+ *
+ * ⚠️ Until this existed the widget was **unusable outside English** — title, empty state, tab name,
+ * unread counter and every aria-label were hardcoded literals. That is not a polish item: an Arabic
+ * or French product could not ship the built-in UI at all, and the only escape was to abandon it and
+ * rebuild on the headless controller.
+ *
+ * `unread` and `openUnread` take the count, so a language whose plural rules differ from English can
+ * do its own thing (`Intl.PluralRules`) instead of being handed "1 unread".
+ *
+ * ⚠️ Rendered with `textContent`, never `innerHTML` — these can come from a dashboard field, and
+ * interpolating them as markup would put an injection point into every host page.
+ */
+export interface InboxLabels {
+    /** Panel heading. */
+    title: string;
+    /** Accessible name for the panel itself. */
+    panelAria: string;
+    /** Bell button, when there is nothing unread. */
+    open: string;
+    /** Bell button, with a count. */
+    openUnread: (n: number) => string;
+    close: string;
+    /** Subtitle under the heading. */
+    unread: (n: number) => string;
+    noUnread: string;
+    /** Empty state — heading and body are separate so neither needs markup. */
+    emptyTitle: string;
+    emptyBody: string;
+    /** Announced to screen readers when the list renders empty. */
+    emptyAnnounce: string;
+    /** The "everything" category tab. */
+    allTab: string;
+    /** Footer button on the dropdown layout. */
+    viewAll: string;
+    pin: string;
+    unpin: string;
+    archive: string;
+    delete: string;
+}
+export declare const DEFAULT_INBOX_LABELS: InboxLabels;
+/**
+ * How the panel presents itself.
+ *
+ * `drawer` — the full-height slide-over (default, unchanged). Good when the inbox is a destination.
+ * `dropdown` — a compact popover anchored under `trigger`, with an optional "View all" footer. Good
+ *   when the bell lives in an existing navbar and the inbox should not take over the page.
+ *
+ * ⚠️ `dropdown` needs a `trigger` to anchor to. Without one it falls back to the configured corner
+ * rather than guessing — a popover pinned to nothing reads as a rendering bug.
+ */
+export type InboxLayout = 'drawer' | 'dropdown';
+export interface InboxMountOptions {
+    /** CSS selector or element to use as the open/close toggle instead of the built-in floating bell. */
+    trigger?: string | HTMLElement;
+    /** Corner for the built-in bell + panel. Default 'bottom-right'. */
+    position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+    /** Force a theme; default follows the OS `prefers-color-scheme`. */
+    theme?: 'light' | 'dark';
+    /** Brand accent (bell/badge/CTA/unread). Overrides `--scalebun-inbox-accent`. */
+    accent?: string;
+    /** Drawer (default) or a navbar-anchored dropdown. See `InboxLayout`. */
+    layout?: InboxLayout;
+    /**
+     * Show a "View all" footer button and call this when it is clicked.
+     *
+     * The SDK does NOT navigate — the host owns its routes. Mostly for `dropdown`, where a compact
+     * popover deliberately shows only the most recent messages and needs somewhere to send people.
+     * Omit it and no footer renders, rather than a button that goes nowhere.
+     */
+    onViewAll?: () => void;
+    /**
+     * Cap the rows a `dropdown` renders. Ignored by `drawer`, which scrolls the full list.
+     * Defaults to 5 — enough to be useful, few enough to stay a popover.
+     */
+    maxItems?: number;
+    /**
+     * Right-to-left layout (mirrors the panel + rows).
+     *
+     * ⚠️ Defaults to the PAGE's direction, not `false`: `:host{all:initial}` does not reset
+     * `direction` (spec exception), so an RTL host would otherwise get RTL text inside an LTR layout.
+     */
+    rtl?: boolean;
+    /** Override any subset of the widget's copy. Unset keys keep the English default. */
+    labels?: Partial<InboxLabels>;
+    /**
+     * Replace the bell glyph. A string is treated as **text**, not markup — pass an element for an
+     * SVG or `<img>`, so the host decides what is safe to inject rather than us guessing.
+     */
+    icon?: string | HTMLElement;
+    /**
+     * Relative timestamp formatter. The built-in one emits English-ish abbreviations (`5m`, `3h`,
+     * `2d`) that no label map can translate — a host that needs real localisation should pass its own,
+     * typically wrapping `Intl.RelativeTimeFormat`.
+     */
+    formatTime?: (timestamp: number) => string;
+}
+/** The headless controller returned by `ScaleBun.inbox()`. Stripe/React-Query-style: verbs for
+ *  actions, reactive `subscribe` for state, UI is opt-in (mount loads a separate lazy chunk). */
+export interface InboxController {
+    /** Mount the built-in shadow-DOM inbox UI (bell + panel). Opt-in — loads a separate lazy chunk, so
+     *  hosts that render their own UI never pay for it. Idempotent (re-mount replaces). */
+    mount(opts?: InboxMountOptions): void;
+    /** Open / close the mounted panel programmatically. No-op until mounted. */
+    open(): void;
+    close(): void;
+    /** Tear down the mounted UI (the headless model keeps running). */
+    unmount(): void;
+    /** Reactive state stream. Fires immediately with the current snapshot, then on every change. */
+    subscribe(cb: (state: InboxState) => void): () => void;
+    /** Cheap scalar stream for a badge (fires immediately). */
+    onUnreadChange(cb: (unread: number) => void): () => void;
+    getState(): InboxState;
+    query(opts?: InboxQueryOptions): Promise<InboxPage>;
+    get(id: string): Promise<InboxMessage | undefined>;
+    markRead(id: string): Promise<void>;
+    markUnread(id: string): Promise<void>;
+    markAllRead(category?: string): Promise<void>;
+    archive(id: string): Promise<void>;
+    unarchive(id: string): Promise<void>;
+    pin(id: string, pinned?: boolean): Promise<void>;
+    remove(id: string): Promise<void>;
+    /** Activate a message CTA by key (fires analytics; link → open; deep/custom → onCtaAction). */
+    act(id: string, ctaKey: string): void;
+    /** Register a handler for `deep`/`custom` CTAs the SDK won't navigate itself. */
+    onCtaAction(cb: (id: string, cta: InboxCta) => void): () => void;
+    /** Force a sync now (no-op until A1.3 wires the delta protocol). */
+    refresh(): Promise<void>;
+    /** Ingest a message locally (used by push→inbox fan-out and tests until sync lands). */
+    ingest(messages: InboxMessage[]): Promise<void>;
+}
+/** Analytics event names (all carry replayCoord). Kept here so the runtime + tests agree. */
+export declare const INBOX_EVENTS: {
+    readonly received: "$message_received";
+    readonly seen: "$message_seen";
+    readonly read: "$message_read";
+    readonly cta: "$message_cta_clicked";
+    readonly archived: "$message_archived";
+    readonly unarchived: "$message_unarchived";
+    readonly pinned: "$message_pinned";
+    readonly unpinned: "$message_unpinned";
+    readonly deleted: "$message_deleted";
+    readonly expired: "$message_expired";
+    readonly unreadChanged: "$inbox_unread_changed";
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/features/inbox/types.d.ts.map

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

package/dist/features/inbox/types.js

@@ -0,0 +1,42 @@
+/**
+ * Inbox contracts (headless-first). These types are the stable surface a host depends on whether it
+ * uses our shadow-DOM UI or renders its own. Server is the system of record; the SDK is a bounded,
+ * offline-first local cache (see docs/INBOX-COACHMARKS-ARCHITECTURE.md §2).
+ *
+ * A1.1 scope: the model contracts + controller surface. The IndexedDB store (A1.2), delta sync +
+ * conflict resolution (A1.3), and sync triggers/consent (A1.4) land beneath this same surface without
+ * changing it.
+ */
+export const DEFAULT_INBOX_LABELS = {
+    title: 'Inbox',
+    panelAria: 'Notifications',
+    open: 'Open notifications',
+    openUnread: (n) => `Open notifications, ${n} unread`,
+    close: 'Close notifications',
+    unread: (n) => `${n} unread`,
+    noUnread: 'No unread messages',
+    emptyTitle: 'You’re all caught up',
+    emptyBody: 'Your notifications will appear here.',
+    emptyAnnounce: 'No notifications',
+    allTab: 'All',
+    viewAll: 'View all',
+    pin: 'Pin',
+    unpin: 'Unpin',
+    archive: 'Archive',
+    delete: 'Delete',
+};
+/** Analytics event names (all carry replayCoord). Kept here so the runtime + tests agree. */
+export const INBOX_EVENTS = {
+    received: '$message_received',
+    seen: '$message_seen',
+    read: '$message_read',
+    cta: '$message_cta_clicked',
+    archived: '$message_archived',
+    unarchived: '$message_unarchived',
+    pinned: '$message_pinned',
+    unpinned: '$message_unpinned',
+    deleted: '$message_deleted',
+    expired: '$message_expired',
+    unreadChanged: '$inbox_unread_changed',
+};
+//# sourceMappingURL=types.js.map

package/dist/features/inbox/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/features/inbox/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AA8KH,MAAM,CAAC,MAAM,oBAAoB,GAAgB;IAC/C,KAAK,EAAE,OAAO;IACd,SAAS,EAAE,eAAe;IAC1B,IAAI,EAAE,oBAAoB;IAC1B,UAAU,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,uBAAuB,CAAC,SAAS;IACpD,KAAK,EAAE,qBAAqB;IAC5B,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,SAAS;IAC5B,QAAQ,EAAE,oBAAoB;IAC9B,UAAU,EAAE,sBAAsB;IAClC,SAAS,EAAE,sCAAsC;IACjD,aAAa,EAAE,kBAAkB;IACjC,MAAM,EAAE,KAAK;IACb,OAAO,EAAE,UAAU;IACnB,GAAG,EAAE,KAAK;IACV,KAAK,EAAE,OAAO;IACd,OAAO,EAAE,SAAS;IAClB,MAAM,EAAE,QAAQ;CACjB,CAAC;AA+FF,6FAA6F;AAC7F,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,QAAQ,EAAE,mBAAmB;IAC7B,IAAI,EAAE,eAAe;IACrB,IAAI,EAAE,eAAe;IACrB,GAAG,EAAE,sBAAsB;IAC3B,QAAQ,EAAE,mBAAmB;IAC7B,UAAU,EAAE,qBAAqB;IACjC,MAAM,EAAE,iBAAiB;IACzB,QAAQ,EAAE,mBAAmB;IAC7B,OAAO,EAAE,kBAAkB;IAC3B,OAAO,EAAE,kBAAkB;IAC3B,aAAa,EAAE,uBAAuB;CAC9B,CAAC"}

package/dist/features/inbox/widget/InboxWidget.d.ts

@@ -0,0 +1,16 @@
+import type { InboxController, InboxMountOptions } from '../types';
+export interface InboxWidgetHandle {
+    open(): void;
+    close(): void;
+    destroy(): void;
+}
+/**
+ * @param remote Dashboard-authored theme, applied UNDER `opts` and under the host's own CSS.
+ *   Passed separately from `opts` on purpose: it is not something a host sets, and putting it in the
+ *   public options type would invite a caller to hand-roll it and be surprised by the precedence.
+ */
+export declare function mountInbox(inbox: InboxController, opts: InboxMountOptions, remote?: {
+    tokens?: Record<string, string>;
+    labels?: Record<string, string>;
+}): InboxWidgetHandle;
+//# sourceMappingURL=InboxWidget.d.ts.map

package/dist/features/inbox/widget/InboxWidget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InboxWidget.d.ts","sourceRoot":"","sources":["../../../../src/features/inbox/widget/InboxWidget.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,eAAe,EAA0C,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAE3G,MAAM,WAAW,iBAAiB;IAChC,IAAI,IAAI,IAAI,CAAC;IACb,KAAK,IAAI,IAAI,CAAC;IACd,OAAO,IAAI,IAAI,CAAC;CACjB;AAoLD;;;;GAIG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,eAAe,EACtB,IAAI,EAAE,iBAAiB,EACvB,MAAM,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAC5E,iBAAiB,CA8VnB"}