@interocitor/core 0.0.0-beta.2

package/dist/handshake/qr.d.ts

@@ -0,0 +1,100 @@
+/**
+ * interocitor/handshake/qr
+ *
+ * QR code payload encoding and decoding for the handshake protocol.
+ *
+ * ## Two intents
+ *
+ * A QR code is always generated by one device and scanned by another.
+ * The intent declares what the QR *generator* wants:
+ *
+ *   "share" — I already belong to a mesh. Scan me: I will push
+ *             remotePath + master key to you via the relay.
+ *
+ *   "join"  — I want to join a mesh. Scan me: push your mesh
+ *             credentials to me via the relay.
+ *
+ * In both cases the *scanner* is the one that ends up sending data
+ * through the cloud relay; the QR generator always receives.
+ *
+ * ## Two pieces in the QR
+ *
+ *   Cloud piece  →  handshakeId
+ *                   Scopes two short-lived relay files on the shared
+ *                   backend. Anyone with cloud access can see these
+ *                   files — but cannot decrypt them (see below).
+ *
+ *   Eyes-only    →  generatorPub (ephemeral ECDH-P256 public key)
+ *                   Used by the scanner to derive a wrapping key via
+ *                   ECDH. The corresponding private key never leaves
+ *                   the generating device. Without physically seeing
+ *                   the QR you cannot derive the wrapping key, so
+ *                   the relay payload is opaque even to someone with
+ *                   full cloud-folder access.
+ *
+ * ## What is NOT in the QR
+ *
+ *   remotePath   — travels via the relay only, encrypted with the
+ *                  ECDH-derived wrapping key.
+ *   master key   — same.
+ *
+ * ## Encoding
+ *
+ * The payload is a compact base64url JSON string, safe to embed in a
+ * URL fragment (never reaches any server):
+ *
+ *   https://yourapp.com/pair#hs=<base64url>
+ */
+export type HandshakeIntent = 'share' | 'join';
+export interface HandshakeQRPayload {
+    /**
+     * Intent of the QR *generator*:
+     *   "share" → generator has the mesh credentials and will push them.
+     *   "join"  → generator wants credentials pushed to it.
+     */
+    intent: HandshakeIntent;
+    /**
+     * Random hex string scoping the relay files on the shared backend.
+     * This is the "cloud piece" — visible to anyone with backend access,
+     * but useless without the eyes-only ECDH private key.
+     */
+    handshakeId: string;
+    /**
+     * Generator's ephemeral ECDH-P256 public key, base64url-encoded SPKI.
+     * This is the "eyes-only piece" — must be physically scanned to be useful.
+     * The scanner uses it to derive the shared wrapping key.
+     */
+    generatorPub: string;
+    /**
+     * Opaque backend connection config produced by adapter.getHandshakeConfig().
+     *
+     * Tells the scanner how to reach the same backend as the generator so
+     * they can exchange relay files. Must NOT contain credentials.
+     *
+     * Present for adapters where the backend address is not known to the app
+     * in advance (WebDAV, Google Drive, sharded CF workers, …).
+     * Absent when the backend is fixed and app-global (e.g. a single CF worker
+     * whose URL is baked into the binary).
+     *
+     * The scanner passes this to their adapter via the adapter's own
+     * fromHandshakeConfig() static factory or equivalent before starting
+     * the relay exchange.
+     */
+    adapterConfig?: string;
+}
+/** Encode a HandshakeQRPayload to a compact URL-safe base64 string. */
+export declare function encodeQRPayload(payload: HandshakeQRPayload): string;
+/** Decode a compact URL-safe base64 string back to HandshakeQRPayload. */
+export declare function decodeQRPayload(encoded: string): HandshakeQRPayload;
+/**
+ * Build a full join URL with the handshake payload in the fragment.
+ * The fragment is never sent to any server.
+ */
+export declare function buildPairUrl(baseUrl: string, payload: HandshakeQRPayload): string;
+/**
+ * Extract and decode a HandshakeQRPayload from a URL fragment string.
+ * Pass `window.location.hash` directly.
+ * Returns null if no #hs= fragment is present.
+ */
+export declare function parseQRFromUrl(hash: string): HandshakeQRPayload | null;
+//# sourceMappingURL=qr.d.ts.map

package/dist/handshake/qr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"qr.d.ts","sourceRoot":"","sources":["../../src/handshake/qr.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAEH,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,MAAM,CAAC;AAE/C,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,MAAM,EAAE,eAAe,CAAC;IACxB;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB;;;;;;;;;;;;;;OAcG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,uEAAuE;AACvE,wBAAgB,eAAe,CAAC,OAAO,EAAE,kBAAkB,GAAG,MAAM,CAQnE;AAED,0EAA0E;AAC1E,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,kBAAkB,CAuBnE;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,kBAAkB,GAAG,MAAM,CAIjF;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI,CAQtE"}

package/dist/handshake/qr.js

@@ -0,0 +1,103 @@
+/**
+ * interocitor/handshake/qr
+ *
+ * QR code payload encoding and decoding for the handshake protocol.
+ *
+ * ## Two intents
+ *
+ * A QR code is always generated by one device and scanned by another.
+ * The intent declares what the QR *generator* wants:
+ *
+ *   "share" — I already belong to a mesh. Scan me: I will push
+ *             remotePath + master key to you via the relay.
+ *
+ *   "join"  — I want to join a mesh. Scan me: push your mesh
+ *             credentials to me via the relay.
+ *
+ * In both cases the *scanner* is the one that ends up sending data
+ * through the cloud relay; the QR generator always receives.
+ *
+ * ## Two pieces in the QR
+ *
+ *   Cloud piece  →  handshakeId
+ *                   Scopes two short-lived relay files on the shared
+ *                   backend. Anyone with cloud access can see these
+ *                   files — but cannot decrypt them (see below).
+ *
+ *   Eyes-only    →  generatorPub (ephemeral ECDH-P256 public key)
+ *                   Used by the scanner to derive a wrapping key via
+ *                   ECDH. The corresponding private key never leaves
+ *                   the generating device. Without physically seeing
+ *                   the QR you cannot derive the wrapping key, so
+ *                   the relay payload is opaque even to someone with
+ *                   full cloud-folder access.
+ *
+ * ## What is NOT in the QR
+ *
+ *   remotePath   — travels via the relay only, encrypted with the
+ *                  ECDH-derived wrapping key.
+ *   master key   — same.
+ *
+ * ## Encoding
+ *
+ * The payload is a compact base64url JSON string, safe to embed in a
+ * URL fragment (never reaches any server):
+ *
+ *   https://yourapp.com/pair#hs=<base64url>
+ */
+/** Encode a HandshakeQRPayload to a compact URL-safe base64 string. */
+export function encodeQRPayload(payload) {
+    const json = JSON.stringify(payload);
+    const bytes = new TextEncoder().encode(json);
+    let binary = '';
+    for (let i = 0; i < bytes.length; i++) {
+        binary += String.fromCodePoint(bytes[i]);
+    }
+    return btoa(binary).replaceAll('+', '-').replaceAll('/', '_').replaceAll('=', '');
+}
+/** Decode a compact URL-safe base64 string back to HandshakeQRPayload. */
+export function decodeQRPayload(encoded) {
+    const padded = encoded.replaceAll('-', '+').replaceAll('_', '/');
+    const pad = (4 - (padded.length % 4)) % 4;
+    const b64 = padded + '='.repeat(pad);
+    const binary = atob(b64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    const json = new TextDecoder().decode(bytes);
+    const payload = JSON.parse(json);
+    if ((payload.intent !== 'share' && payload.intent !== 'join') ||
+        typeof payload.handshakeId !== 'string' ||
+        typeof payload.generatorPub !== 'string' ||
+        (payload.adapterConfig !== undefined && typeof payload.adapterConfig !== 'string')) {
+        throw new Error('Invalid handshake QR payload');
+    }
+    return payload;
+}
+/**
+ * Build a full join URL with the handshake payload in the fragment.
+ * The fragment is never sent to any server.
+ */
+export function buildPairUrl(baseUrl, payload) {
+    const encoded = encodeQRPayload(payload);
+    const base = baseUrl.replace(/#.*$/, '');
+    return `${base}#hs=${encoded}`;
+}
+/**
+ * Extract and decode a HandshakeQRPayload from a URL fragment string.
+ * Pass `window.location.hash` directly.
+ * Returns null if no #hs= fragment is present.
+ */
+export function parseQRFromUrl(hash) {
+    const match = hash.match(/(?:^|[#&])hs=([A-Za-z0-9_-]+)/);
+    if (!match)
+        return null;
+    try {
+        return decodeQRPayload(match[1]);
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=qr.js.map

package/dist/handshake/qr.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,46 @@
+/**
+ * interocitor
+ *
+ * Encrypted local-first CRDT database that syncs over cloud storage.
+ * Google Drive is the default path; server-managed compaction is optional.
+ *
+ * @example
+ * ```ts
+ * import { SyncEngine } from 'interocitor';
+ * import { GoogleDriveAdapter } from 'interocitor/adapters/google-drive';
+ *
+ * const adapter = new GoogleDriveAdapter({
+ *   clientId: 'YOUR_GOOGLE_CLIENT_ID',
+ * });
+ * const engine = new SyncEngine(adapter, {
+ *   remotePath: '/Interocitor',
+ *   encrypted: true, // generates key automatically
+ * });
+ *
+ * await engine.init();
+ * await engine.connect();
+ *
+ * // Share this passphrase with other devices:
+ * console.log('Passphrase:', engine.getPassphrase());
+ *
+ * await engine.put('meals', 'meal_1', { name: 'Butter Chicken', servings: 4 });
+ *
+ * engine.on((event) => {
+ *   if (event.type === 'change') {
+ *     console.log(`${event.table}/${event.rowId} updated`);
+ *   }
+ * });
+ * ```
+ */
+export { generateShareQR, generateJoinQR, handleScannedQR, buildPairUrl, parseQRFromUrl, } from './handshake/index.ts';
+export type { HandshakeCredentials, GenerateShareQROptions, GenerateShareQRResult, GenerateJoinQROptions, GenerateJoinQRResult, HandleScannedQROptions, } from './handshake/index.ts';
+export { SyncEngine } from './core/sync-engine.ts';
+export { LocalStore } from './storage/local-store.ts';
+export { type CredentialStore, type StoredCredentials, LocalStorageCredentialStore, WebAuthnCredentialStore, createCredentialStore, } from './storage/credential-store.ts';
+export { Table } from './core/table.ts';
+export { types } from './core/schema-types.ts';
+export { readColumn, rowToPlain } from './core/crdt.ts';
+export { createRowId } from './core/row-id.ts';
+export type { CreateRowIdOptions } from './core/row-id.ts';
+export type { StorageAdapter, FileEntry, LocalStoreAdapter, LocalStoreFactory, SyncConfig, DatabaseSchemaDefinition, TableSchemaDefinition, InferSchemaType, InferTableType, TableIndexDefinition, SchemaFieldKind, IndexableSchemaFieldKind, SchemaField, IndexableSchemaField, BuiltinMergeStrategy, MergeStrategy, MergeFunction, MergeContext, TableMergeConfig, WhereClause, WherePrimitive, WhereOperator, SyncEvent, SyncEventListener, Row, Manifest, ManifestPointer, ServerConfig, MeshChangePayload, MeshSnapshotPayload, DeviceInfo, DeviceMetadata, DeviceHead, ChangesHead, ReplicaConfig, } from './core/types.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAIH,OAAO,EACL,eAAe,EACf,cAAc,EACd,eAAe,EACf,YAAY,EACZ,cAAc,GACf,MAAM,sBAAsB,CAAC;AAE9B,YAAY,EACV,oBAAoB,EACpB,sBAAsB,EACtB,qBAAqB,EACrB,qBAAqB,EACrB,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,sBAAsB,CAAC;AAI9B,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACtD,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,2BAA2B,EAC3B,uBAAuB,EACvB,qBAAqB,GACtB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AACxC,OAAO,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AAI/C,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,YAAY,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAI3D,YAAY,EAEV,cAAc,EACd,SAAS,EAGT,iBAAiB,EACjB,iBAAiB,EAGjB,UAAU,EACV,wBAAwB,EACxB,qBAAqB,EACrB,eAAe,EACf,cAAc,EACd,oBAAoB,EACpB,eAAe,EACf,wBAAwB,EACxB,WAAW,EACX,oBAAoB,EACpB,oBAAoB,EACpB,aAAa,EACb,aAAa,EACb,YAAY,EACZ,gBAAgB,EAChB,WAAW,EACX,cAAc,EACd,aAAa,EAGb,SAAS,EACT,iBAAiB,EAGjB,GAAG,EAGH,QAAQ,EACR,eAAe,EACf,YAAY,EACZ,iBAAiB,EACjB,mBAAmB,EACnB,UAAU,EACV,cAAc,EACd,UAAU,EACV,WAAW,EACX,aAAa,GACd,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -0,0 +1,46 @@
+/**
+ * interocitor
+ *
+ * Encrypted local-first CRDT database that syncs over cloud storage.
+ * Google Drive is the default path; server-managed compaction is optional.
+ *
+ * @example
+ * ```ts
+ * import { SyncEngine } from 'interocitor';
+ * import { GoogleDriveAdapter } from 'interocitor/adapters/google-drive';
+ *
+ * const adapter = new GoogleDriveAdapter({
+ *   clientId: 'YOUR_GOOGLE_CLIENT_ID',
+ * });
+ * const engine = new SyncEngine(adapter, {
+ *   remotePath: '/Interocitor',
+ *   encrypted: true, // generates key automatically
+ * });
+ *
+ * await engine.init();
+ * await engine.connect();
+ *
+ * // Share this passphrase with other devices:
+ * console.log('Passphrase:', engine.getPassphrase());
+ *
+ * await engine.put('meals', 'meal_1', { name: 'Butter Chicken', servings: 4 });
+ *
+ * engine.on((event) => {
+ *   if (event.type === 'change') {
+ *     console.log(`${event.table}/${event.rowId} updated`);
+ *   }
+ * });
+ * ```
+ */
+// ─── Handshake (public API) ───────────────────────────────────────────
+export { generateShareQR, generateJoinQR, handleScannedQR, buildPairUrl, parseQRFromUrl, } from "./handshake/index.js";
+// ─── Engine ───────────────────────────────────────────────────────────
+export { SyncEngine } from "./core/sync-engine.js";
+export { LocalStore } from "./storage/local-store.js";
+export { LocalStorageCredentialStore, WebAuthnCredentialStore, createCredentialStore, } from "./storage/credential-store.js";
+export { Table } from "./core/table.js";
+export { types } from "./core/schema-types.js";
+// ─── Row utilities ────────────────────────────────────────────────────
+export { readColumn, rowToPlain } from "./core/crdt.js";
+export { createRowId } from "./core/row-id.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,yEAAyE;AAEzE,OAAO,EACL,eAAe,EACf,cAAc,EACd,eAAe,EACf,YAAY,EACZ,cAAc,GACf,MAAM,sBAAsB,CAAC;AAW9B,yEAAyE;AAEzE,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACtD,OAAO,EAGL,2BAA2B,EAC3B,uBAAuB,EACvB,qBAAqB,GACtB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AACxC,OAAO,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AAE/C,yEAAyE;AAEzE,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/storage/credential-store.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Credential Store — pluggable persistence for key material.
+ *
+ * Safari ITP wipes localStorage after 7 days of inactivity.
+ * That kills the passphrase and device ID. Lost key = lost data.
+ *
+ * This module provides:
+ *  - `LocalStorageCredentialStore` — current behaviour, extracted.
+ *  - `WebAuthnCredentialStore`    — OS keychain via navigator.credentials + largeBlob.
+ *  - `createCredentialStore()`    — auto-detects best backend.
+ *
+ * The engine uses `CredentialStore` for all key material persistence.
+ * Apps never touch this directly unless they want a custom backend.
+ */
+export interface StoredCredentials {
+    /** Base58 passphrase for the mesh encryption key. */
+    passphrase: string;
+    /** Stable device identifier. */
+    deviceId: string;
+}
+export interface CredentialStore {
+    /** Persist credentials to the primary store (localStorage). Silent. */
+    save(creds: StoredCredentials): Promise<void>;
+    /** Load persisted credentials from the primary store only. Silent. */
+    load(): Promise<StoredCredentials | null>;
+    /** Wipe stored credentials. */
+    clear(): Promise<void>;
+    /**
+     * Persist credentials to the OS keychain via biometrics (WebAuthn).
+     * Call on intentional user action (pairing, "secure my keys" button).
+     * Returns true if saved, false if unavailable or cancelled.
+     * Optional — stores that don't support biometrics return false.
+     */
+    secureWithBiometrics?(): Promise<boolean>;
+    /**
+     * Restore credentials from the OS keychain via biometrics (WebAuthn).
+     * Call on intentional user action only: "try restore purchases",
+     * "restore access", etc. Never automatic.
+     * Returns restored credentials or null if unavailable/cancelled/not found.
+     */
+    restoreWithBiometrics?(): Promise<StoredCredentials | null>;
+}
+export declare class LocalStorageCredentialStore implements CredentialStore {
+    private readonly dbName;
+    constructor(dbName: string);
+    private keyKey;
+    private get deviceKey();
+    save(creds: StoredCredentials): Promise<void>;
+    load(): Promise<StoredCredentials | null>;
+    clear(): Promise<void>;
+}
+/**
+ * Stores credentials in the OS keychain via WebAuthn `largeBlob` extension.
+ *
+ * Survives Safari ITP, browser data clears, and profile resets.
+ * Requires a platform authenticator with largeBlob support (Touch ID,
+ * Face ID, Windows Hello). Falls back gracefully — `save()` rejects
+ * if the authenticator doesn't support largeBlob.
+ *
+ * Flow:
+ *  1. `save()` → `navigator.credentials.create()` with largeBlob write.
+ *     User sees a biometric prompt. Credential ID stored in localStorage
+ *     as a hint for faster `load()`, but not required.
+ *  2. `load()` → `navigator.credentials.get()` with largeBlob read.
+ *     User sees a biometric prompt. Returns the blob.
+ *  3. If localStorage hint is gone (ITP wipe), load uses an empty
+ *     allowCredentials list — the authenticator picks the right one.
+ */
+export declare class WebAuthnCredentialStore implements CredentialStore {
+    private readonly dbName;
+    private readonly rpId;
+    /** Human-readable app name shown in biometric prompts and OS keychain. */
+    private readonly displayName;
+    private static readonly CRED_ID_KEY_PREFIX;
+    private readonly encoder;
+    private readonly decoder;
+    constructor(dbName: string, rpId?: string, 
+    /** Human-readable app name shown in biometric prompts and OS keychain. */
+    displayName?: string);
+    private credIdKey;
+    private encode;
+    private decode;
+    /** Read credential ID hint from localStorage (best-effort, survives only if ITP hasn't wiped). */
+    private loadCredentialIdHint;
+    private saveCredentialIdHint;
+    save(creds: StoredCredentials): Promise<void>;
+    private writeLargeBlob;
+    load(): Promise<StoredCredentials | null>;
+    clear(): Promise<void>;
+}
+/**
+ * Create the best available credential store.
+ *
+ * Prefers WebAuthn (survives ITP) when available, falls back to
+ * localStorage. Returns a `FallbackCredentialStore` that tries
+ * WebAuthn first and uses localStorage as backup on every operation.
+ */
+export declare function createCredentialStore(dbName: string, displayName?: string): CredentialStore;
+//# sourceMappingURL=credential-store.d.ts.map

package/dist/storage/credential-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credential-store.d.ts","sourceRoot":"","sources":["../../src/storage/credential-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,MAAM,WAAW,iBAAiB;IAChC,qDAAqD;IACrD,UAAU,EAAE,MAAM,CAAC;IACnB,gCAAgC;IAChC,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,uEAAuE;IACvE,IAAI,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,sEAAsE;IACtE,IAAI,IAAI,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAAC;IAC1C,+BAA+B;IAC/B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB;;;;;OAKG;IACH,oBAAoB,CAAC,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1C;;;;;OAKG;IACH,qBAAqB,CAAC,IAAI,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAAC;CAC7D;AAID,qBAAa,2BAA4B,YAAW,eAAe;IACrD,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,MAAM;IAE3C,OAAO,CAAC,MAAM;IACd,OAAO,KAAK,SAAS,GAA8C;IAE7D,IAAI,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAK7C,IAAI,IAAI,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAOzC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAI7B;AAID;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,uBAAwB,YAAW,eAAe;IAM3D,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,0EAA0E;IAC1E,OAAO,CAAC,QAAQ,CAAC,WAAW;IAR9B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,kBAAkB,CAAuB;IACjE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAC7C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;gBAG1B,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,MAAqD;IAC5E,0EAA0E;IACzD,WAAW,GAAE,MAAsB;IAGtD,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,MAAM;IAId,OAAO,CAAC,MAAM;IAId,kGAAkG;IAClG,OAAO,CAAC,oBAAoB;IAW5B,OAAO,CAAC,oBAAoB;IAUtB,IAAI,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;YAsCrC,cAAc;IA0BtB,IAAI,IAAI,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAgCzC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAM7B;AAmBD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,eAAe,CAE3F"}