@ixo/openhands-sdk 0.0.0-stage → 0.1.0

package/dist/cjs/chain/store.d.ts

@@ -0,0 +1,115 @@
+import { type DocStore } from "../data/docUrls.ts";
+import { type QiSession } from "./session.ts";
+/**
+ * Putting a document where anyone can check it.
+ *
+ * Two doors, one rule. A person who is signed in through the auth hub holds
+ * an ed25519 signing key the hub registered on their DID document; with it
+ * they write to their **own** filesystem namespace, published, and the file's
+ * content address is the same one the network's IPFS pins would give the
+ * bytes. Everyone else — a phone that has not signed in, the worker's own
+ * keys, a script — uploads to **IPFS** through the ixo gateway, whose door is
+ * open the way the cellnode's was.
+ *
+ * The filesystem is tried first and never insisted on: a person whose DID
+ * document does not carry the key yet, a token the worker refuses, a bad
+ * minute at the worker — each falls through to the gateway, and the caller
+ * gets an address either way. What never happens is a document that could
+ * not be stored because the better store was fussy.
+ *
+ * **What the browser holds.** The signing key never leaves the browser: it
+ * mints a single-use token — one write, one subtree, five minutes, addressed
+ * to this network's filesystem worker by DID — and only the token travels.
+ * A token lifted from a network log is worth one write under `/openhands`
+ * in the signer's own namespace, for the minutes it has left.
+ */
+export interface Stored {
+    cid: string;
+    /** Where the bytes can be fetched from — the store that took them. */
+    url: string;
+    store: DocStore;
+}
+/** The key that signs filesystem tokens, and the account it signs for. */
+export interface Signer {
+    mnemonic: string;
+    address: string;
+}
+/**
+ * The most this estate will store as one document.
+ *
+ * The cellnode's measured ceiling was 2.8 MB, and every phone's photograph
+ * is shrunk to a few hundred kilobytes before it gets here; the gateway
+ * takes a hundred megabytes and the filesystem five gigabytes, but nothing
+ * this estate publishes is bigger than a photograph, and a ceiling this side
+ * of the store is what keeps a bug from becoming a bill.
+ */
+export declare const MAX_PROOF_BYTES = 2800000;
+/** The service an ask's entity publishes so other readers can find its documents. */
+export declare const ipfsService: () => {
+    id: string;
+    type: string;
+    serviceEndpoint: string;
+};
+/** The filesystem worker's DID — a `did:web` on its own host, as it publishes at `/.well-known/did.json`. */
+export declare const vfsDid: () => string;
+/** The one subtree a token from this app may write. */
+export declare const VFS_SCOPE = "/openhands";
+/**
+ * A single-use write token for the signer's own namespace, scoped to this
+ * app's subtree. `@ixo/ucan` is loaded here rather than at the top: it
+ * carries ucanto and its codecs, which no page should pay for until a
+ * document is actually being stored.
+ */
+export declare function mintVfsBearer(signer: Signer, options?: {
+    ttlSeconds?: number;
+}): Promise<string>;
+/**
+ * Where a document goes in the signer's tree: one folder per network and
+ * month, a name that says what it is, and enough randomness that two
+ * uploads in the same millisecond cannot collide on the path.
+ */
+export declare function vfsPathFor(kind: string, contentType: string): string;
+type Body = Blob | Uint8Array | string;
+/** Stored on the filesystem, or null when the worker would not take it (the caller falls back). */
+export declare function uploadToVfs(body: Body, contentType: string, args: {
+    bearer: string;
+    path: string;
+    signal?: AbortSignal;
+}): Promise<Stored | null>;
+/** Stored on IPFS through the gateway, or null. */
+export declare function uploadToIpfs(body: Body, contentType: string, args?: {
+    name?: string;
+    signal?: AbortSignal;
+}): Promise<Stored | null>;
+export interface UploadOptions {
+    /** What the document is, for its name in a filesystem. */
+    kind?: string;
+    /** A filename to record with the bytes. */
+    name?: string;
+    /** Who is signed in. `undefined` asks the browser's session; `null` is nobody. */
+    signer?: Signer | null;
+    signal?: AbortSignal;
+}
+/** The signer in this browser's session, when the hub gave it a signing key. */
+export declare function signerFromSession(session?: QiSession | null): Signer | null;
+/** Forget a refusal — for tests, and for a person who has just signed in. */
+export declare const resetStoreMemory: () => void;
+export declare function uploadDoc(body: Body, contentType: string, options?: UploadOptions): Promise<Stored | null>;
+/**
+ * Publishing a JSON document — an ask's terms, a claim envelope, a receipt.
+ * The returned address is the hash of the bytes, so what was promised gets
+ * the same kind of identity as the work itself: fetchable, and impossible to
+ * edit after the fact without changing the address it lives at.
+ */
+export declare const uploadPublicJson: (doc: unknown, options?: UploadOptions) => Promise<Stored | null>;
+/**
+ * The same, for a document whose EXACT bytes matter: a rubric's on-chain
+ * proof is the hash of what a reader will fetch, so the text that was hashed
+ * has to be the text that was stored — re-serialising an object in between
+ * is how those two quietly stop being the same thing.
+ */
+export declare const uploadPublicText: (text: string, contentType?: string, options?: UploadOptions) => Promise<Stored | null>;
+/** A photograph or file somebody handed over. */
+export declare function uploadProofFile(file: File, options?: UploadOptions): Promise<Stored | null>;
+export {};
+//# sourceMappingURL=store.d.ts.map

package/dist/cjs/chain/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../src/chain/store.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0D,KAAK,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC3G,OAAO,EAAe,KAAK,SAAS,EAAE,MAAM,cAAc,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,MAAM,WAAW,MAAM;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,sEAAsE;IACtE,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,QAAQ,CAAC;CACjB;AAED,0EAA0E;AAC1E,MAAM,WAAW,MAAM;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe,UAAY,CAAC;AAEzC,qFAAqF;AACrF,eAAO,MAAM,WAAW;;;;CAA0F,CAAC;AAEnH,6GAA6G;AAC7G,eAAO,MAAM,MAAM,QAAO,MAAkE,CAAC;AAE7F,uDAAuD;AACvD,eAAO,MAAM,SAAS,eAAe,CAAC;AAKtC;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAc1G;AAWD;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAOpE;AAED,KAAK,IAAI,GAAG,IAAI,GAAG,UAAU,GAAG,MAAM,CAAC;AAKvC,mGAAmG;AACnG,wBAAsB,WAAW,CAAC,IAAI,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAE,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAkBvJ;AAED,mDAAmD;AACnD,wBAAsB,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,IAAI,GAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAO,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAiB9I;AAED,MAAM,WAAW,aAAa;IAC5B,0DAA0D;IAC1D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kFAAkF;IAClF,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,gFAAgF;AAChF,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,SAAS,GAAG,IAA2D,GAAG,MAAM,GAAG,IAAI,CAGjI;AAgBD,6EAA6E;AAC7E,eAAO,MAAM,gBAAgB,QAAO,IAAkC,CAAC;AAEvE,wBAAsB,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAcpH;AAED;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAAI,KAAK,OAAO,EAAE,UAAS,aAAkB,KAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAC9B,CAAC;AAErE;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAAI,MAAM,MAAM,EAAE,oBAAgC,EAAE,UAAS,aAAkB,KAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CACzD,CAAC;AAE5E,iDAAiD;AACjD,wBAAsB,eAAe,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAGrG"}

package/dist/cjs/chain/store.js

@@ -0,0 +1,212 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.uploadPublicText = exports.uploadPublicJson = exports.resetStoreMemory = exports.VFS_SCOPE = exports.vfsDid = exports.ipfsService = exports.MAX_PROOF_BYTES = void 0;
+exports.mintVfsBearer = mintVfsBearer;
+exports.vfsPathFor = vfsPathFor;
+exports.uploadToVfs = uploadToVfs;
+exports.uploadToIpfs = uploadToIpfs;
+exports.signerFromSession = signerFromSession;
+exports.uploadDoc = uploadDoc;
+exports.uploadProofFile = uploadProofFile;
+const docUrls_ts_1 = require("../data/docUrls.js");
+const session_ts_1 = require("./session.js");
+/**
+ * The most this estate will store as one document.
+ *
+ * The cellnode's measured ceiling was 2.8 MB, and every phone's photograph
+ * is shrunk to a few hundred kilobytes before it gets here; the gateway
+ * takes a hundred megabytes and the filesystem five gigabytes, but nothing
+ * this estate publishes is bigger than a photograph, and a ceiling this side
+ * of the store is what keeps a bug from becoming a bill.
+ */
+exports.MAX_PROOF_BYTES = 2_800_000;
+/** The service an ask's entity publishes so other readers can find its documents. */
+const ipfsService = () => ({ id: "{id}#ipfs", type: "Ipfs", serviceEndpoint: `${(0, docUrls_ts_1.ipfsGatewayUrl)()}/ipfs/` });
+exports.ipfsService = ipfsService;
+/** The filesystem worker's DID — a `did:web` on its own host, as it publishes at `/.well-known/did.json`. */
+const vfsDid = () => `did:web:${new URL((0, docUrls_ts_1.vfsUrl)()).host.replace(/:/g, "%3A")}`;
+exports.vfsDid = vfsDid;
+/** The one subtree a token from this app may write. */
+exports.VFS_SCOPE = "/openhands";
+/** How long a token lives. A write takes seconds; the rest is clock skew. */
+const TOKEN_TTL_SECONDS = 300;
+/**
+ * A single-use write token for the signer's own namespace, scoped to this
+ * app's subtree. `@ixo/ucan` is loaded here rather than at the top: it
+ * carries ucanto and its codecs, which no page should pay for until a
+ * document is actually being stored.
+ */
+async function mintVfsBearer(signer, options = {}) {
+    const { signerFromMnemonic, createInvocation, serializeInvocation } = await Promise.resolve().then(() => __importStar(require("@ixo/ucan")));
+    const did = `did:ixo:${signer.address}`;
+    const { signer: key } = await signerFromMnemonic(signer.mnemonic, did);
+    const invocation = await createInvocation({
+        issuer: key,
+        audience: (0, exports.vfsDid)(),
+        capability: { can: "fs/write", with: `ixo:filesystem${exports.VFS_SCOPE}` },
+        expiration: Math.floor(Date.now() / 1000) + (options.ttlSeconds ?? TOKEN_TTL_SECONDS),
+        /* Two identical tokens in the same second would share a content address,
+           and the worker refuses an address it has seen. */
+        facts: [{ nonce: crypto.randomUUID() }]
+    });
+    return serializeInvocation(invocation);
+}
+const EXTENSIONS = {
+    "application/json": "json",
+    "application/ld+json": "jsonld",
+    "image/jpeg": "jpg",
+    "image/png": "png",
+    "image/webp": "webp",
+    "text/plain": "txt"
+};
+/**
+ * Where a document goes in the signer's tree: one folder per network and
+ * month, a name that says what it is, and enough randomness that two
+ * uploads in the same millisecond cannot collide on the path.
+ */
+function vfsPathFor(kind, contentType) {
+    const now = new Date();
+    const month = `${now.getUTCFullYear()}/${String(now.getUTCMonth() + 1).padStart(2, "0")}`;
+    const ext = EXTENSIONS[contentType.split(";")[0].trim().toLowerCase()] ?? "bin";
+    const safeKind = kind.toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "") || "doc";
+    const rand = Math.random().toString(36).slice(2, 8);
+    return `${exports.VFS_SCOPE}/${(0, docUrls_ts_1.network)()}/${month}/${safeKind}-${Date.now().toString(36)}-${rand}.${ext}`;
+}
+/** The body as something `fetch` sends whole — never a stream, which cannot be sent twice. */
+const asBody = (body) => (body instanceof Uint8Array ? body : body);
+/** Stored on the filesystem, or null when the worker would not take it (the caller falls back). */
+async function uploadToVfs(body, contentType, args) {
+    try {
+        const url = `${(0, docUrls_ts_1.vfsUrl)()}/api/fs/files?path=${encodeURIComponent(args.path)}&public=true`;
+        const response = await fetch(url, {
+            method: "POST",
+            headers: { authorization: `Bearer ${args.bearer}`, "content-type": contentType },
+            body: asBody(body),
+            signal: args.signal ?? AbortSignal.timeout(30_000)
+        });
+        if (!response.ok) {
+            await response.body?.cancel().catch(() => undefined);
+            return null;
+        }
+        const meta = (await response.json());
+        return typeof meta.cid === "string" && meta.cid ? { cid: meta.cid, url: (0, docUrls_ts_1.vfsDocUrl)(meta.cid), store: "vfs" } : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Stored on IPFS through the gateway, or null. */
+async function uploadToIpfs(body, contentType, args = {}) {
+    try {
+        const response = await fetch(`${(0, docUrls_ts_1.ipfsGatewayUrl)()}/upload`, {
+            method: "POST",
+            headers: { "content-type": contentType, ...(args.name ? { "x-file-name": args.name.slice(0, 120) } : {}) },
+            body: asBody(body),
+            signal: args.signal ?? AbortSignal.timeout(60_000)
+        });
+        if (!response.ok) {
+            await response.body?.cancel().catch(() => undefined);
+            return null;
+        }
+        const doc = (await response.json());
+        return typeof doc.cid === "string" && doc.cid ? { cid: doc.cid, url: (0, docUrls_ts_1.ipfsDocUrl)(doc.cid), store: "ipfs" } : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The signer in this browser's session, when the hub gave it a signing key. */
+function signerFromSession(session = typeof window === "undefined" ? null : (0, session_ts_1.loadSession)()) {
+    const mnemonic = session?.signingKey?.mnemonic;
+    return mnemonic && session?.address ? { mnemonic, address: session.address } : null;
+}
+/**
+ * Store a document: the signer's filesystem when there is a signer and the
+ * worker takes it, else IPFS. Null only when neither door opened.
+ */
+/**
+ * When the filesystem last refused a write, it is not asked again for a
+ * while. A submission is several uploads — photographs, a thumbnail, the
+ * envelope — and readers find a photograph on the store that holds its
+ * envelope, so the whole of one has to land in one place: a store that
+ * failed halfway is left alone until the submission is well past.
+ */
+const VFS_REST_MS = 10 * 60_000;
+let vfsRestingUntil = 0;
+/** Forget a refusal — for tests, and for a person who has just signed in. */
+const resetStoreMemory = () => void (vfsRestingUntil = 0);
+exports.resetStoreMemory = resetStoreMemory;
+async function uploadDoc(body, contentType, options = {}) {
+    const signer = options.signer === undefined ? signerFromSession() : options.signer;
+    if (signer && Date.now() >= vfsRestingUntil) {
+        try {
+            const bearer = await mintVfsBearer(signer);
+            const stored = await uploadToVfs(body, contentType, { bearer, path: vfsPathFor(options.kind ?? "doc", contentType), signal: options.signal });
+            if (stored)
+                return stored;
+        }
+        catch {
+            /* A key the library could not use, or a worker that would not answer:
+               the gateway is the door that is always open. */
+        }
+        if (!options.signal?.aborted)
+            vfsRestingUntil = Date.now() + VFS_REST_MS;
+    }
+    return uploadToIpfs(body, contentType, { name: options.name, signal: options.signal });
+}
+/**
+ * Publishing a JSON document — an ask's terms, a claim envelope, a receipt.
+ * The returned address is the hash of the bytes, so what was promised gets
+ * the same kind of identity as the work itself: fetchable, and impossible to
+ * edit after the fact without changing the address it lives at.
+ */
+const uploadPublicJson = (doc, options = {}) => (0, exports.uploadPublicText)(JSON.stringify(doc), "application/json", options);
+exports.uploadPublicJson = uploadPublicJson;
+/**
+ * The same, for a document whose EXACT bytes matter: a rubric's on-chain
+ * proof is the hash of what a reader will fetch, so the text that was hashed
+ * has to be the text that was stored — re-serialising an object in between
+ * is how those two quietly stop being the same thing.
+ */
+const uploadPublicText = (text, contentType = "application/json", options = {}) => uploadDoc(text, contentType, { kind: options.kind ?? "doc", ...options });
+exports.uploadPublicText = uploadPublicText;
+/** A photograph or file somebody handed over. */
+async function uploadProofFile(file, options = {}) {
+    if (file.size > exports.MAX_PROOF_BYTES)
+        return null;
+    return uploadDoc(file, file.type || "application/octet-stream", { kind: options.kind ?? (file.type.startsWith("image/") ? "photo" : "file"), name: options.name ?? file.name, ...options });
+}
+//# sourceMappingURL=store.js.map

package/dist/cjs/chain/store.js.map

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

package/dist/cjs/chain/subscription.d.ts

@@ -0,0 +1,73 @@
+import type { EncodeObject } from "@cosmjs/proto-signing";
+import { type PhonePrompt } from "./signWith.ts";
+import type { QiSession } from "./session.ts";
+export interface Subscription {
+    /** The claim collection the credit is billed through. */
+    collectionId: string;
+    /** The deed's admin account — where the PAY actually sits. */
+    admin: string;
+    /**
+     * True when the submit right has to be created by the drawer before the
+     * claim — the mainnet shape. False when it was granted directly.
+     */
+    authorize?: boolean;
+    /** Base units of `denom` sitting on the subscription. */
+    credit: string;
+    denom: string;
+}
+/**
+ * The subscriptions this address may draw from, found from the address alone.
+ *
+ * Read from **authz grants**, not from entity ownership. Deeds belong to the
+ * service — one address owns all 147 on testnet — so asking "which deeds does
+ * this person own" is the wrong question and answers nothing. Asking "what has
+ * this person been authorised to do" answers exactly the right one, in a single
+ * query, and only ever returns subscriptions they can actually act on.
+ *
+ * A drawable subscription needs **both** authorisations on the same collection:
+ * one to make the claim, one to approve it.
+ */
+export declare function drawableSubscriptions(address: string, restUrl: string): Promise<Subscription[]>;
+/**
+ * The message that makes our own submit right, for a subscription granted
+ * in the meta shape.
+ *
+ * Signed by the drawer, executed as the admin under the meta-authorisation —
+ * the same wrapping as the claim itself. It grants the drawer one submit on
+ * this collection, capped at exactly the amount about to be drawn, so the
+ * right it leaves behind is worth nothing more than the claim it enabled.
+ * Sits first in the transaction: messages run in order, and the claim needs
+ * the right to exist before it is checked.
+ */
+export declare function authorizeMsg(args: {
+    address: string;
+    did: string;
+    subscription: Subscription;
+    amount: string;
+}): EncodeObject;
+/**
+ * The messages that draw credit onto a key, built to ride in one
+ * transaction — two, or three when the submit right must be made first.
+ *
+ * Order is load-bearing: the claim must exist before it can be evaluated, and
+ * messages in a transaction execute in sequence — so submit then approve works
+ * where the reverse cannot. Both are signed by the same person, because they
+ * hold both authorisations.
+ *
+ * The amount is set on the claim itself. The subscription collections carry
+ * **empty payment legs**, so a custom amount is the only thing that pays out —
+ * proven on chain 2026-08-24 before any of this was built.
+ */
+export declare function drawMsgs(args: {
+    address: string;
+    did: string;
+    subscription: Subscription;
+    claimId: string;
+    amount: string;
+}): EncodeObject[];
+/** Draw credit onto the signed-in key, through whichever door this account signs with. */
+export declare function drawCredit(session: QiSession, subscription: Subscription, args: {
+    claimId: string;
+    amount: string;
+}, prompt?: PhonePrompt): Promise<import("./signWith.ts").SignResult>;
+//# sourceMappingURL=subscription.d.ts.map

package/dist/cjs/chain/subscription.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscription.d.ts","sourceRoot":"","sources":["../../../src/chain/subscription.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAM1D,OAAO,EAAmB,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AAClE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAiC9C,MAAM,WAAW,YAAY;IAC3B,yDAAyD;IACzD,YAAY,EAAE,MAAM,CAAC;IACrB,8DAA8D;IAC9D,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,yDAAyD;IACzD,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAUD;;;;;;;;;;;GAWG;AACH,wBAAsB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAkErG;AAQD;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,YAAY,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,YAAY,CAgB7H;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,YAAY,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,YAAY,EAAE,CAqC5I;AAED,0FAA0F;AAC1F,wBAAsB,UAAU,CAC9B,OAAO,EAAE,SAAS,EAClB,YAAY,EAAE,YAAY,EAC1B,IAAI,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EACzC,MAAM,CAAC,EAAE,WAAW,+CAWrB"}