@hatk/hatk 0.0.1-alpha.7 → 0.0.1-alpha.71

package/dist/hooks.d.ts.map

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

package/dist/hooks.js

@@ -0,0 +1,163 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+/**
+ * Lifecycle hooks that run in response to server events.
+ *
+ * Place hook modules in the `hooks/` directory. Currently supported hooks:
+ *
+ * - `on-login.ts` — called after each successful OAuth login
+ * - `on-commit-*.ts` — called after records are indexed from the firehose
+ *
+ * Each hook default-exports the result of `defineHook()`.
+ *
+ * @example
+ * ```ts
+ * // hooks/on-login.ts
+ * import { defineHook } from '$hatk'
+ *
+ * export default defineHook("on-login", async (ctx) => {
+ *   await ctx.ensureRepo(ctx.did)
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // hooks/on-commit-favorite.ts
+ * import { defineHook } from '$hatk'
+ *
+ * export default defineHook("on-commit", { collections: ["social.grain.favorite"] },
+ *   async ({ action, collection, record, repo, uri, db, lookup, push }) => {
+ *     if (action !== "create") return
+ *     // send push notification, etc.
+ *   }
+ * )
+ * ```
+ */
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { pdsCreateRecord, pdsPutRecord, pdsDeleteRecord } from "./pds-proxy.js";
+import { log, emit } from "./logger.js";
+import { setRepoStatus, runSQL } from "./database/db.js";
+import { triggerAutoBackfill, awaitBackfill } from "./indexer.js";
+import { buildBaseContext } from "./hydrate.js";
+import { buildPushInterface, isPushEnabled } from "./push.js";
+export function defineHook(event, ...args) {
+    if (event === 'on-login') {
+        return { __type: 'hook', event, handler: args[0] };
+    }
+    if (event === 'on-commit') {
+        const options = args[0];
+        const handler = args[1];
+        return { __type: 'hook', event, collections: options.collections, handler };
+    }
+    throw new Error(`Unknown hook event: ${event}`);
+}
+let onLoginHook = null;
+const onCommitHooks = [];
+/**
+ * Discover and load the on-login hook from the project's `hooks/` directory.
+ * Looks for `on-login.ts` or `on-login.js`. Safe to call if no hook exists.
+ */
+export async function loadOnLoginHook(hooksDir) {
+    const tsPath = resolve(hooksDir, 'on-login.ts');
+    const jsPath = resolve(hooksDir, 'on-login.js');
+    const path = existsSync(tsPath) ? tsPath : existsSync(jsPath) ? jsPath : null;
+    if (!path)
+        return;
+    const mod = await import(__rewriteRelativeImportExtension(/* @vite-ignore */ `${path}?t=${Date.now()}`));
+    onLoginHook = mod.default;
+    log('[hooks] on-login hook loaded');
+}
+/** Mark a DID as pending, trigger auto-backfill, and wait for completion. */
+async function ensureRepo(did) {
+    await setRepoStatus(did, 'pending');
+    triggerAutoBackfill(did);
+    await awaitBackfill(did);
+}
+/** Register a hook from a scanned server/ module. */
+export function registerHook(event, handler, options) {
+    if (event === 'on-login') {
+        onLoginHook = handler;
+        log('[hooks] on-login hook registered');
+    }
+    else if (event === 'on-commit') {
+        const collections = new Set(options?.collections || []);
+        onCommitHooks.push({ collections, handler: handler });
+        log(`[hooks] on-commit hook registered (collections: ${[...collections].join(', ')})`);
+    }
+}
+/** Fire the on-login hook if loaded. Errors are logged but never block login. */
+export async function fireOnLoginHook(did, oauthConfig) {
+    if (!onLoginHook)
+        return;
+    try {
+        const base = buildBaseContext({ did });
+        const viewer = { did };
+        const hookPromise = onLoginHook({
+            ...base,
+            did,
+            db: { query: base.db.query, run: runSQL },
+            ensureRepo,
+            createRecord: async (collection, record, opts) => {
+                if (!oauthConfig)
+                    throw new Error('No OAuth config — cannot write to PDS');
+                return pdsCreateRecord(oauthConfig, viewer, { collection, record, rkey: opts?.rkey });
+            },
+            putRecord: async (collection, rkey, record) => {
+                if (!oauthConfig)
+                    throw new Error('No OAuth config — cannot write to PDS');
+                return pdsPutRecord(oauthConfig, viewer, { collection, rkey, record });
+            },
+            deleteRecord: async (collection, rkey) => {
+                if (!oauthConfig)
+                    throw new Error('No OAuth config — cannot write to PDS');
+                await pdsDeleteRecord(oauthConfig, viewer, { collection, rkey });
+            },
+        });
+        const timeout = new Promise((_, reject) => setTimeout(() => reject(new Error('on-login hook timed out after 30s')), 30_000));
+        await Promise.race([hookPromise, timeout]);
+    }
+    catch (err) {
+        emit('hooks', 'on_login_error', { did, error: err.message });
+    }
+}
+/**
+ * Fire on-commit hooks for a batch of indexed records.
+ * Runs async and non-blocking — errors are logged but never throw.
+ */
+export function fireOnCommitHooks(items) {
+    if (onCommitHooks.length === 0)
+        return;
+    const base = buildBaseContext(null);
+    const push = isPushEnabled() ? buildPushInterface() : { send: async () => { } };
+    for (const item of items) {
+        for (const hook of onCommitHooks) {
+            if (hook.collections.size > 0 && !hook.collections.has(item.collection))
+                continue;
+            hook
+                .handler({
+                action: item.action,
+                collection: item.collection,
+                record: item.record,
+                repo: item.authorDid,
+                uri: item.uri,
+                db: { query: base.db.query, run: runSQL },
+                lookup: base.lookup,
+                push,
+            })
+                .catch((err) => {
+                emit('hooks', 'on_commit_error', {
+                    collection: item.collection,
+                    uri: item.uri,
+                    error: err.message,
+                });
+            });
+        }
+    }
+}

package/dist/hydrate.d.ts

@@ -1,9 +1,9 @@
 import type { Row } from './lex-types.ts';
 export type { Row };
-export interface HydrateContext<T = unknown> {
-    items: Row<T>[];
+export interface BaseContext {
     viewer: {
         did: string;
+        handle?: string;
     } | null;
     db: {
         query: (sql: string, params?: unknown[]) => Promise<unknown[]>;
@@ -12,12 +12,13 @@ export interface HydrateContext<T = unknown> {
     lookup: <R = unknown>(collection: string, field: string, values: string[]) => Promise<Map<string, Row<R>>>;
     count: (collection: string, field: string, values: string[]) => Promise<Map<string, number>>;
     labels: (uris: string[]) => Promise<Map<string, unknown[]>>;
-    blobUrl: (did: string, ref: unknown, preset?: 'avatar' | 'banner' | 'feed_thumbnail' | 'feed_fullsize') => string | undefined;
+    blobUrl: (did: string, ref: unknown, preset?: string) => string | undefined;
 }
 /** Fetch records for URIs, reshape them, and filter out taken-down DIDs. */
 export declare function resolveRecords(uris: string[]): Promise<Row<unknown>[]>;
-/** Build a HydrateContext for a feed's hydrate function. */
-export declare function buildHydrateContext(items: Row<unknown>[], viewer: {
+/** Build a BaseContext for hydration. */
+export declare function buildBaseContext(viewer: {
     did: string;
-} | null): HydrateContext;
+    handle?: string;
+} | null): BaseContext;
 //# sourceMappingURL=hydrate.d.ts.map

package/dist/hydrate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hydrate.d.ts","sourceRoot":"","sources":["../src/hydrate.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAA;AAEzC,YAAY,EAAE,GAAG,EAAE,CAAA;AAInB,MAAM,WAAW,cAAc,CAAC,CAAC,GAAG,OAAO;IACzC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,CAAA;IACf,MAAM,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAA;IAC9B,EAAE,EAAE;QAAE,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,OAAO,EAAE,CAAC,CAAA;KAAE,CAAA;IACtE,UAAU,EAAE,CAAC,CAAC,GAAG,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IAC7F,MAAM,EAAE,CAAC,CAAC,GAAG,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IAC1G,KAAK,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IAC5F,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,CAAA;IAC3D,OAAO,EAAE,CACP,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,OAAO,EACZ,MAAM,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,gBAAgB,GAAG,eAAe,KAC9D,MAAM,GAAG,SAAS,CAAA;CACxB;AAID,4EAA4E;AAC5E,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,CAoC5E;AAID,4DAA4D;AAC5D,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,GAAG,CAAC,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,GAAG,cAAc,CA4BzG"}
+{"version":3,"file":"hydrate.d.ts","sourceRoot":"","sources":["../src/hydrate.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAA;AAEzC,YAAY,EAAE,GAAG,EAAE,CAAA;AAInB,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAA;IAC/C,EAAE,EAAE;QAAE,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,OAAO,EAAE,CAAC,CAAA;KAAE,CAAA;IACtE,UAAU,EAAE,CAAC,CAAC,GAAG,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IAC7F,MAAM,EAAE,CAAC,CAAC,GAAG,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IAC1G,KAAK,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IAC5F,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,CAAA;IAC3D,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAA;CAC5E;AAID,4EAA4E;AAC5E,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,CAoC5E;AAID,yCAAyC;AACzC,wBAAgB,gBAAgB,CAAC,MAAM,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,GAAG,WAAW,CAkB7F"}

package/dist/hydrate.js

@@ -1,4 +1,4 @@
-import { getRecordsByUris, countByFieldBatch, lookupByFieldBatch, querySQL, reshapeRow, queryLabelsForUris, filterTakendownDids, } from "./db.js";
+import { getRecordsMap, countByFieldBatch, lookupByFieldBatch, querySQL, queryLabelsForUris, filterTakendownDids, getRecordsByUris, reshapeRow, } from "./database/db.js";
 import { blobUrl } from "./xrpc.js";
 // --- Record Resolution ---
 /** Fetch records for URIs, reshape them, and filter out taken-down DIDs. */
@@ -39,24 +39,12 @@ export async function resolveRecords(uris) {
         .filter((r) => r != null);
 }
 // --- Context Builder ---
-/** Build a HydrateContext for a feed's hydrate function. */
-export function buildHydrateContext(items, viewer) {
+/** Build a BaseContext for hydration. */
+export function buildBaseContext(viewer) {
     return {
-        items,
         viewer,
         db: { query: querySQL },
-        getRecords: async (collection, uris) => {
-            if (uris.length === 0)
-                return new Map();
-            const records = await getRecordsByUris(collection, uris);
-            const map = new Map();
-            for (const r of records) {
-                const shaped = reshapeRow(r, r?.__childData, r?.__unionData);
-                if (shaped)
-                    map.set(shaped.uri, shaped);
-            }
-            return map;
-        },
+        getRecords: getRecordsMap,
         lookup: async (collection, field, values) => {
             if (values.length === 0)
                 return new Map();

package/dist/indexer.d.ts

@@ -1,14 +1,120 @@
+/** A single normalized repo operation, independent of the wire it arrived on. */
+export interface CommitOp {
+    action: 'create' | 'update' | 'delete';
+    collection: string;
+    rkey: string;
+    /** Absent on deletes. */
+    cid?: string;
+    /** Absent on deletes. */
+    record?: Record<string, any>;
+}
+/** Record the latest firehose sequence seen. Source of truth for cursor persistence and reconnect resume. */
+export declare function noteSeq(seq: number): void;
+/** The highest seq this process has seen, or null before the first event. */
+export declare function getLastSeq(): number | null;
+/**
+ * Persist the latest firehose sequence when it has advanced past the stored
+ * cursor. Runs on a timer independent of the write path: an app whose
+ * collections rarely appear on the firehose never flushes a batch, so the
+ * flush-path cursor write alone leaves the stored cursor frozen — and a frozen
+ * cursor makes the relay replay its whole retention window at line rate
+ * (~135 GB/hour observed against bsky.network) on every boot and reconnect.
+ */
+export declare function checkpointCursor(): Promise<void>;
+/** Point cursor persistence at a stream's own `_cursor` row. See {@link cursorKey}. */
+export declare function setCursorKey(key: 'relay' | 'jetstream'): void;
+/**
+ * The cursor a reconnect should resume from: the latest seq this process has
+ * seen, falling back to the boot-time cursor before any message has arrived.
+ * Reusing the boot-time cursor on every reconnect would replay everything
+ * received since the process started.
+ */
+export declare function resumeCursor(liveSeq: number | null, bootCursor: string | null | undefined): string | null | undefined;
+/** Reset module cursor state between tests. */
+export declare function _resetCursorStateForTests(): void;
+/**
+ * Drain the write buffer synchronously instead of waiting out
+ * FLUSH_INTERVAL_MS. Lets end-to-end tests assert on rows immediately after
+ * feeding a frame.
+ */
+export declare function _flushForTests(): Promise<void>;
+/**
+ * Auto-backfill a DID's repo when first seen on the firehose.
+ *
+ * Fetches the full repo via CAR export, inserts all records, then replays any
+ * firehose events that arrived during the backfill. Concurrency is capped at
+ * `maxConcurrentBackfills`. Failed backfills retry with exponential delay up
+ * to `maxRetries`.
+ */
+/** Wait for a DID's backfill to complete if one is in flight. */
+export declare function awaitBackfill(did: string): Promise<void>;
 export declare function triggerAutoBackfill(did: string, attempt?: number): Promise<void>;
-interface IndexerOpts {
-    relayUrl: string;
+/**
+ * Indexing behaviour shared by every stream source. Both the relay firehose
+ * and the Jetstream live tail feed the same buffers, backfill signalling, and
+ * cursor machinery — only the wire differs.
+ */
+export interface IndexerCoreOpts {
+    plcUrl: string;
     collections: Set<string>;
     signalCollections?: Set<string>;
     pinnedRepos?: Set<string>;
-    cursor?: string | null;
     fetchTimeout: number;
     maxRetries: number;
+    parallelism?: number;
     ftsRebuildInterval?: number;
 }
+/** Configuration for the relay firehose indexer. */
+interface IndexerOpts extends IndexerCoreOpts {
+    relayUrl: string;
+    cursor?: string | null;
+}
+/**
+ * Connect to the AT Protocol relay firehose and begin indexing.
+ *
+ * Opens a WebSocket to `subscribeRepos`, processes commit messages synchronously
+ * on the event loop to minimize backpressure, and batches writes through
+ * {@link flushBuffer}. New DIDs trigger auto-backfill via {@link triggerAutoBackfill}.
+ * Reconnects automatically on disconnect after a 3s delay.
+ *
+ * @returns The WebSocket connection (for shutdown coordination)
+ */
+export declare function configureIndexer(opts: IndexerCoreOpts): Promise<void>;
 export declare function startIndexer(opts: IndexerOpts): Promise<WebSocket>;
+/**
+ * Handle a `#identity` firehose event for a DID. The `handle` field on the
+ * event is optional per the lexicon, and some emitters omit it (signalling
+ * "re-resolve"). When absent, we re-resolve from the PLC directory so handle
+ * renames propagate even when the relay payload is sparse.
+ *
+ * Only updates DIDs we already track (present in repoStatusCache) to avoid
+ * writing rows for the entire network.
+ */
+export declare function handleIdentityEvent(did: string, payloadHandle: string | undefined): Promise<void>;
+/**
+ * Whether a collection's records may be written from network data.
+ *
+ * Private collections are AppView-authoritative: nothing on the network may
+ * write or delete their rows, so stream ops naming them are spoofed by
+ * definition and must be dropped regardless of which source delivered them.
+ */
+export declare function isIndexableCollection(collection: string, collections: Set<string>): boolean;
+/**
+ * Apply a repo's commit ops to the index.
+ *
+ * Wire-agnostic: the relay path reaches here after CBOR/CAR decoding, the
+ * Jetstream path after parsing JSON. Callers must have already filtered `ops`
+ * through {@link isIndexableCollection}.
+ *
+ * Handles auto-backfill signalling, buffering for DIDs mid-backfill, lexicon
+ * validation, and delete/put routing.
+ */
+export declare function applyCommit(did: string, ops: CommitOp[]): void;
+/**
+ * Process a single firehose message. Decodes the CBOR header/body, filters
+ * for relevant collections, validates records against lexicons, and routes
+ * writes to the buffer (or pending buffer if the DID is mid-backfill).
+ */
+export declare function processMessage(bytes: Uint8Array, collections: Set<string>): void;
 export {};
 //# sourceMappingURL=indexer.d.ts.map

package/dist/indexer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"indexer.d.ts","sourceRoot":"","sources":["../src/indexer.ts"],"names":[],"mappings":"AAkIA,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,SAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAsDjF;AAED,UAAU,WAAW;IACnB,QAAQ,EAAE,MAAM,CAAA;IAChB,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IACxB,iBAAiB,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IAC/B,WAAW,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IACzB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,YAAY,EAAE,MAAM,CAAA;IACpB,UAAU,EAAE,MAAM,CAAA;IAClB,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAC5B;AAyBD,wBAAsB,YAAY,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,SAAS,CAAC,CAkDxE"}
+{"version":3,"file":"indexer.d.ts","sourceRoot":"","sources":["../src/indexer.ts"],"names":[],"mappings":"AA8BA,iFAAiF;AACjF,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAA;IACtC,UAAU,EAAE,MAAM,CAAA;IAClB,IAAI,EAAE,MAAM,CAAA;IACZ,yBAAyB;IACzB,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,yBAAyB;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CAC7B;AA0JD,6GAA6G;AAC7G,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAEzC;AAED,6EAA6E;AAC7E,wBAAgB,UAAU,IAAI,MAAM,GAAG,IAAI,CAE1C;AAED;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAStD;AAED,uFAAuF;AACvF,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,WAAW,GAAG,IAAI,CAE7D;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAErH;AAED,+CAA+C;AAC/C,wBAAgB,yBAAyB,IAAI,IAAI,CAIhD;AAED;;;;GAIG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC,CAMpD;AAED;;;;;;;GAOG;AACH,iEAAiE;AACjE,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGxD;AAED,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,SAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CA8EjF;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAA;IACd,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IACxB,iBAAiB,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IAC/B,WAAW,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IACzB,YAAY,EAAE,MAAM,CAAA;IACpB,UAAU,EAAE,MAAM,CAAA;IAClB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAC5B;AAED,oDAAoD;AACpD,UAAU,WAAY,SAAQ,eAAe;IAC3C,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACvB;AAyBD;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CA6B3E;AAED,wBAAsB,YAAY,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,SAAS,CAAC,CAkCxE;AAED;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CA4CvG;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,OAAO,CAE3F;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,IAAI,CAwE9D;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,CAoDhF"}