@interop/wallet-core 0.1.0

package/LICENSE.md

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2026 Interop Alliance
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,83 @@
+# Wallet Core _(@interop/wallet-core)_
+
+[![Node.js CI](https://github.com/interop-alliance/wallet-core/workflows/CI/badge.svg)](https://github.com/interop-alliance/wallet-core/actions?query=workflow%3A%22CI%22)
+[![NPM Version](https://img.shields.io/npm/v/@interop/wallet-core.svg)](https://npm.im/@interop/wallet-core)
+
+> Shared wallet-domain logic (WAS sync engine core and wallet Space layout
+> contracts) for Interop wallet apps.
+
+## Table of Contents
+
+- [Background](#background)
+- [Install](#install)
+- [Usage](#usage)
+- [Contribute](#contribute)
+- [License](#license)
+
+## Background
+
+`@interop/wallet-core` is the shared, correctness-critical code two WAS-enabled
+wallet apps (a React Native mobile wallet and a browser wallet) hold in common:
+the cross-replica byte-compatibility surface both must agree on to converge on
+identical bytes. It is isomorphic (browser, Node.js, React Native) and has no
+UI, storage, or crypto-key dependencies -- every side effect is injected.
+
+Two subpaths:
+
+- **`@interop/wallet-core/sync`** -- the Wallet Attached Storage (WAS)
+  replication engine core: the `SyncEngine` orchestration (single-flight,
+  migrate-once, backoff), the `runPull` / `runPush` algorithms, the replica-side
+  `SyncStore` seam, and the generic `SyncedCollectionSpec` shape. The wire
+  contract and port (`WasSyncPort`, `WireDoc`, `DocCipher`, ...) are re-exported
+  from [`@interop/was-client`](https://npm.im/@interop/was-client) so an engine
+  consumer imports one package.
+
+- **`@interop/wallet-core/space`** -- the wallet Space layout contract: the
+  shared collection ids and descriptive specs (`private-credentials`,
+  `public-credentials`, `wallet-activity`), the `wallet-activity` wire shape
+  with its pure `addHistory*` payload builders, the `publicCredentialUrl`
+  derivation, and the `was-link` QR hand-off contract. Contacts collection specs
+  live in [`@interop/social-core`](https://npm.im/@interop/social-core).
+
+## Install
+
+- Node.js 24+ is recommended.
+
+```
+pnpm install @interop/wallet-core
+```
+
+### Development
+
+```
+git clone https://github.com/interop-alliance/wallet-core.git
+cd wallet-core
+pnpm install
+```
+
+## Usage
+
+```ts
+import { SyncEngine, runPull, runPush } from '@interop/wallet-core/sync'
+import {
+  PRIVATE_CREDENTIALS_COLLECTION,
+  publicCredentialUrl,
+  buildWasLinkPayload,
+  parseWasLinkPayload,
+  addHistoryCredentialCreated
+} from '@interop/wallet-core/space'
+```
+
+Both subpaths are re-exported from the package root as well.
+
+## Contribute
+
+PRs accepted. See [CONTRIBUTING.md](CONTRIBUTING.md) for editor setup (Prettier,
+ESLint, and EditorConfig) and how it maps to CI.
+
+If editing the Readme, please conform to the
+[standard-readme](https://github.com/RichardLitt/standard-readme) specification.
+
+## License
+
+[MIT License](LICENSE.md) © 2026 Interop Alliance.

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * `@interop/wallet-core` -- shared wallet-domain logic for Interop wallet apps.
+ * The two subpaths are canonical and can be imported directly:
+ *
+ * - `@interop/wallet-core/sync` -- the WAS replication engine core.
+ * - `@interop/wallet-core/space` -- the wallet Space layout contract.
+ *
+ * This root re-exports both for convenience.
+ */
+export * from './sync/index.js';
+export * from './space/index.js';
+//# 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;;GAEG;AACH;;;;;;;;GAQG;AACH,cAAc,iBAAiB,CAAA;AAC/B,cAAc,kBAAkB,CAAA"}

package/dist/index.js

@@ -0,0 +1,15 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * `@interop/wallet-core` -- shared wallet-domain logic for Interop wallet apps.
+ * The two subpaths are canonical and can be imported directly:
+ *
+ * - `@interop/wallet-core/sync` -- the WAS replication engine core.
+ * - `@interop/wallet-core/space` -- the wallet Space layout contract.
+ *
+ * This root re-exports both for convenience.
+ */
+export * from './sync/index.js';
+export * from './space/index.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;;GAEG;AACH;;;;;;;;GAQG;AACH,cAAc,iBAAiB,CAAA;AAC/B,cAAc,kBAAkB,CAAA"}

package/dist/space/activity.d.ts

@@ -0,0 +1,175 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * The `wallet-activity` wire shape and the pure payload builders for it.
+ *
+ * {@link WalletActivity} is the decrypted body of one `wallet-activity`
+ * document: an ActivityStreams-shaped record (a typed action carrying a
+ * human-readable summary and a creation timestamp). Both wallet replicas read
+ * and write this exact shape, so each reads the other's entries. Every field is
+ * optional because a payload arrives from the storage server and is not
+ * schema-validated on read.
+ *
+ * The builders are pure: each returns the activity payload object only -- no
+ * storage, no port calls. `id` and `created` are injectable (a caller that wants
+ * a specific resource id or timestamp passes them); otherwise `id` defaults to
+ * `crypto.randomUUID()` and `created` to `new Date().toISOString()`. The
+ * `type` strings and `summary` phrasings are byte-significant: two replicas that
+ * build the same activity must produce the same `type` / `summary`, so these are
+ * kept verbatim.
+ */
+/**
+ * The decrypted body of one `wallet-activity` document. Reconciles the web
+ * wallet's `WalletActivity` interface and the mobile wallet's
+ * `WalletActivityPayload`, which are the same shape.
+ */
+export interface WalletActivity {
+    id?: string;
+    type?: string[];
+    summary?: string;
+    actor?: unknown;
+    object?: unknown;
+    created?: string;
+}
+/** The activity `type` strings the wallet uses, verbatim on the wire. */
+export declare const ACTIVITY_TYPE: {
+    readonly Create: "Create";
+    readonly Delete: "Delete";
+    readonly Share: "Share";
+    readonly Unshare: "Unshare";
+    readonly Login: "Login";
+    readonly Revoke: "Revoke";
+    readonly CollectionShare: "CollectionShare";
+    readonly CollectionUnshare: "CollectionUnshare";
+};
+/** A minimal actor descriptor; the wallet records the user's email. */
+type Actor = {
+    email?: string;
+    id?: string;
+};
+/**
+ * The Create activity for a freshly generated bootstrap `did:key` DID.
+ *
+ * @param options {object}
+ * @param options.user {Actor}
+ * @param [options.id] {string}
+ * @param [options.created] {string}
+ * @returns {WalletActivity}
+ */
+export declare function addHistoryNewAccount({ user, id, created }: {
+    user: Actor;
+    id?: string;
+    created?: string;
+}): WalletActivity;
+/**
+ * The Create activity for the wallet's storage collections (and, when a remote
+ * replica is configured, the remote Space). `object` -- the created Space /
+ * Collection descriptors -- is supplied by the caller (it comes from the app's
+ * storage layer); `remote` selects the summary phrasing.
+ *
+ * @param options {object}
+ * @param options.actor {unknown}   recorded as the activity actor
+ * @param options.object {unknown}   the created Space / Collection descriptors
+ * @param [options.remote] {boolean}   whether a remote Space was created
+ * @param [options.id] {string}
+ * @param [options.created] {string}
+ * @returns {WalletActivity}
+ */
+export declare function addHistorySpaceCreated({ actor, object, remote, id, created }: {
+    actor: unknown;
+    object: unknown;
+    remote?: boolean;
+    id?: string;
+    created?: string;
+}): WalletActivity;
+/** The Create activity for a credential. */
+export declare function addHistoryCredentialCreated({ cid, user, id, created }: {
+    cid: string;
+    user: Actor;
+    id?: string;
+    created?: string;
+}): WalletActivity;
+/** The Delete activity for a credential. */
+export declare function addHistoryCredentialDeleted({ cid, user, id, created }: {
+    cid: string;
+    user: Actor;
+    id?: string;
+    created?: string;
+}): WalletActivity;
+/** The Share activity for a credential (a public link created). */
+export declare function addHistoryCredentialShared({ cid, user, id, created }: {
+    cid: string;
+    user: Actor;
+    id?: string;
+    created?: string;
+}): WalletActivity;
+/** The Unshare activity for a credential (a public link revoked). */
+export declare function addHistoryCredentialUnshared({ cid, user, id, created }: {
+    cid: string;
+    user: Actor;
+    id?: string;
+    created?: string;
+}): WalletActivity;
+/** One capability grant recorded on a Login activity. `zcap` is kept verbatim. */
+export interface ActivityGrant {
+    id: string;
+    target: string;
+    allowedActions: string[];
+    expires: string;
+    zcap?: unknown;
+}
+/**
+ * The Login activity: the user logged in to a relying party (or connected an
+ * app) via "Login with Wallet", granting the listed capabilities. The recorded
+ * zcap ids are the hook for a later revocation UI.
+ *
+ * @param options {object}
+ * @param options.user {Actor}
+ * @param options.origin {string}   the relying party's origin
+ * @param options.grants {ActivityGrant[]}
+ * @param [options.appConnect] {{ name: string; firstRun: boolean }}   set for an
+ *   App Connect login: the app's display name and whether the app key was minted
+ *   on this connect (first run) or matched (returning)
+ * @param [options.id] {string}
+ * @param [options.created] {string}
+ * @returns {WalletActivity}
+ */
+export declare function addHistoryLogin({ user, origin, grants, appConnect, id, created }: {
+    user: Actor;
+    origin: string;
+    grants: ActivityGrant[];
+    appConnect?: {
+        name: string;
+        firstRun: boolean;
+    };
+    id?: string;
+    created?: string;
+}): WalletActivity;
+/**
+ * The Revoke activity: the user revoked a connected app's access, retiring its
+ * app-key credential and its storage grants.
+ *
+ * @param options {object}
+ * @param options.user {Actor}
+ * @param options.origin {string}   the connected app's origin
+ * @param options.name {string}   the connected app's display name
+ * @param [options.cid] {string}   the retired app-key credential's cid
+ * @param [options.revoked] {number}   how many storage grants were revoked
+ * @param [options.skipped] {number}   how many grants needed no revocation
+ * @param [options.id] {string}
+ * @param [options.created] {string}
+ * @returns {WalletActivity}
+ */
+export declare function addHistoryAppRevoke({ user, origin, name, cid, revoked, skipped, id, created }: {
+    user: Actor;
+    origin: string;
+    name: string;
+    cid?: string;
+    revoked?: number;
+    skipped?: number;
+    id?: string;
+    created?: string;
+}): WalletActivity;
+export {};
+//# sourceMappingURL=activity.d.ts.map

package/dist/space/activity.d.ts.map

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

package/dist/space/activity.js

@@ -0,0 +1,209 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * The `wallet-activity` wire shape and the pure payload builders for it.
+ *
+ * {@link WalletActivity} is the decrypted body of one `wallet-activity`
+ * document: an ActivityStreams-shaped record (a typed action carrying a
+ * human-readable summary and a creation timestamp). Both wallet replicas read
+ * and write this exact shape, so each reads the other's entries. Every field is
+ * optional because a payload arrives from the storage server and is not
+ * schema-validated on read.
+ *
+ * The builders are pure: each returns the activity payload object only -- no
+ * storage, no port calls. `id` and `created` are injectable (a caller that wants
+ * a specific resource id or timestamp passes them); otherwise `id` defaults to
+ * `crypto.randomUUID()` and `created` to `new Date().toISOString()`. The
+ * `type` strings and `summary` phrasings are byte-significant: two replicas that
+ * build the same activity must produce the same `type` / `summary`, so these are
+ * kept verbatim.
+ */
+/** The activity `type` strings the wallet uses, verbatim on the wire. */
+export const ACTIVITY_TYPE = {
+    Create: 'Create',
+    Delete: 'Delete',
+    Share: 'Share',
+    Unshare: 'Unshare',
+    Login: 'Login',
+    Revoke: 'Revoke',
+    CollectionShare: 'CollectionShare',
+    CollectionUnshare: 'CollectionUnshare'
+};
+/** Fills in the id / created defaults shared by every builder. */
+function stamp(id, created) {
+    return {
+        id: id ?? crypto.randomUUID(),
+        created: created ?? new Date().toISOString()
+    };
+}
+/**
+ * The Create activity for a freshly generated bootstrap `did:key` DID.
+ *
+ * @param options {object}
+ * @param options.user {Actor}
+ * @param [options.id] {string}
+ * @param [options.created] {string}
+ * @returns {WalletActivity}
+ */
+export function addHistoryNewAccount({ user, id, created }) {
+    const stamped = stamp(id, created);
+    return {
+        id: stamped.id,
+        type: [ACTIVITY_TYPE.Create],
+        summary: 'Account Sign Up. did:key DID generated.',
+        actor: { email: user.email },
+        object: user.id,
+        created: stamped.created
+    };
+}
+/**
+ * The Create activity for the wallet's storage collections (and, when a remote
+ * replica is configured, the remote Space). `object` -- the created Space /
+ * Collection descriptors -- is supplied by the caller (it comes from the app's
+ * storage layer); `remote` selects the summary phrasing.
+ *
+ * @param options {object}
+ * @param options.actor {unknown}   recorded as the activity actor
+ * @param options.object {unknown}   the created Space / Collection descriptors
+ * @param [options.remote] {boolean}   whether a remote Space was created
+ * @param [options.id] {string}
+ * @param [options.created] {string}
+ * @returns {WalletActivity}
+ */
+export function addHistorySpaceCreated({ actor, object, remote, id, created }) {
+    const stamped = stamp(id, created);
+    return {
+        id: stamped.id,
+        type: [ACTIVITY_TYPE.Create],
+        summary: remote
+            ? 'Account space created on remote storage server, collections initialized.'
+            : 'Wallet collections initialized in local storage.',
+        actor,
+        object,
+        created: stamped.created
+    };
+}
+/**
+ * The shared shape behind the four credential builders, which differ only in the
+ * activity type and the summary verb.
+ */
+function credentialActivity({ cid, user, type, verb, id, created }) {
+    const stamped = stamp(id, created);
+    return {
+        id: stamped.id,
+        type: [type],
+        summary: `Credential ${verb}: ${cid}`,
+        actor: { email: user.email },
+        object: cid,
+        created: stamped.created
+    };
+}
+/** The Create activity for a credential. */
+export function addHistoryCredentialCreated({ cid, user, id, created }) {
+    return credentialActivity({
+        cid,
+        user,
+        type: ACTIVITY_TYPE.Create,
+        verb: 'created',
+        id,
+        created
+    });
+}
+/** The Delete activity for a credential. */
+export function addHistoryCredentialDeleted({ cid, user, id, created }) {
+    return credentialActivity({
+        cid,
+        user,
+        type: ACTIVITY_TYPE.Delete,
+        verb: 'deleted',
+        id,
+        created
+    });
+}
+/** The Share activity for a credential (a public link created). */
+export function addHistoryCredentialShared({ cid, user, id, created }) {
+    return credentialActivity({
+        cid,
+        user,
+        type: ACTIVITY_TYPE.Share,
+        verb: 'shared',
+        id,
+        created
+    });
+}
+/** The Unshare activity for a credential (a public link revoked). */
+export function addHistoryCredentialUnshared({ cid, user, id, created }) {
+    return credentialActivity({
+        cid,
+        user,
+        type: ACTIVITY_TYPE.Unshare,
+        verb: 'unshared',
+        id,
+        created
+    });
+}
+/**
+ * The Login activity: the user logged in to a relying party (or connected an
+ * app) via "Login with Wallet", granting the listed capabilities. The recorded
+ * zcap ids are the hook for a later revocation UI.
+ *
+ * @param options {object}
+ * @param options.user {Actor}
+ * @param options.origin {string}   the relying party's origin
+ * @param options.grants {ActivityGrant[]}
+ * @param [options.appConnect] {{ name: string; firstRun: boolean }}   set for an
+ *   App Connect login: the app's display name and whether the app key was minted
+ *   on this connect (first run) or matched (returning)
+ * @param [options.id] {string}
+ * @param [options.created] {string}
+ * @returns {WalletActivity}
+ */
+export function addHistoryLogin({ user, origin, grants, appConnect, id, created }) {
+    const stamped = stamp(id, created);
+    const summary = appConnect
+        ? `Connected ${appConnect.name} (${origin}) to wallet` +
+            `${appConnect.firstRun ? ', minting a new app key' : ''}.`
+        : `Logged in to ${origin} with wallet.`;
+    return {
+        id: stamped.id,
+        type: [ACTIVITY_TYPE.Login],
+        summary,
+        actor: { email: user.email },
+        object: appConnect
+            ? { origin, zcaps: grants, appConnect }
+            : { origin, zcaps: grants },
+        created: stamped.created
+    };
+}
+/**
+ * The Revoke activity: the user revoked a connected app's access, retiring its
+ * app-key credential and its storage grants.
+ *
+ * @param options {object}
+ * @param options.user {Actor}
+ * @param options.origin {string}   the connected app's origin
+ * @param options.name {string}   the connected app's display name
+ * @param [options.cid] {string}   the retired app-key credential's cid
+ * @param [options.revoked] {number}   how many storage grants were revoked
+ * @param [options.skipped] {number}   how many grants needed no revocation
+ * @param [options.id] {string}
+ * @param [options.created] {string}
+ * @returns {WalletActivity}
+ */
+export function addHistoryAppRevoke({ user, origin, name, cid, revoked, skipped, id, created }) {
+    const stamped = stamp(id, created);
+    const summary = typeof revoked === 'number'
+        ? `Revoked ${name} (${origin}) app access: ${revoked} grant(s) ` +
+            `revoked${skipped ? `, ${skipped} skipped` : ''}.`
+        : `Revoked ${name} (${origin}) app access.`;
+    return {
+        id: stamped.id,
+        type: [ACTIVITY_TYPE.Revoke],
+        summary,
+        actor: { email: user.email },
+        object: { origin, appConnect: { name }, cid, revoked, skipped },
+        created: stamped.created
+    };
+}
+//# sourceMappingURL=activity.js.map

package/dist/space/activity.js.map

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

package/dist/space/collections.d.ts

@@ -0,0 +1,65 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * The shared wallet Space layout: the collection ids and descriptive specs both
+ * wallet replicas provision, so a credential written by one is found and read by
+ * the other. Both replicas MUST agree on every field here -- `collectionId`
+ * decides where a document lands on the server, `idDerivation` and `mutable`
+ * decide whether it is overwritten in place or only appended, and `encryption` /
+ * `isPublic` decide how it is stored and who can read it. A disagreement splits
+ * the feed into separate or incompatibly-shaped collections that never converge.
+ *
+ * The contacts collections (`contacts`, `contacts-history`) are NOT declared
+ * here: their ids and specs live in `@interop/social-core`
+ * (`CONTACTS_COLLECTION_SPEC` / `CONTACTS_HISTORY_COLLECTION_SPEC`), which apps
+ * import directly. The field vocabulary below mirrors that spec.
+ */
+/** The immutable, content-addressed, EDV-encrypted credential replica. */
+export declare const PRIVATE_CREDENTIALS_COLLECTION = "private-credentials";
+/** The plaintext, world-readable copies of publicly shared credentials. */
+export declare const PUBLIC_CREDENTIALS_COLLECTION = "public-credentials";
+/** The append-only, EDV-encrypted wallet activity log. */
+export declare const WALLET_ACTIVITY_COLLECTION = "wallet-activity";
+/**
+ * A declarative descriptor of a synced wallet Space collection, aligned with
+ * `@interop/social-core`'s `CONTACTS_COLLECTION_SPEC` vocabulary and extended
+ * with the storage attributes the wallet Space needs:
+ *
+ * - `idDerivation` -- `'content'` for an append-only, content-addressed log (the
+ *   id IS the hash of the stored body) or `'random'` for a mutable head (a
+ *   stable id whose body is overwritten).
+ * - `mutable` -- whether a document is overwritten in place (`true`) or only
+ *   ever appended (`false`).
+ * - `encryption` -- `'edv'` stores each document as an EDV envelope; `'plaintext'`
+ *   stores it verbatim.
+ * - `isPublic` -- whether the collection is granted collection-level world read
+ *   on the server.
+ */
+export interface SpaceCollectionSpec {
+    collectionId: string;
+    idDerivation: 'content' | 'random';
+    mutable: boolean;
+    encryption: 'edv' | 'plaintext';
+    isPublic: boolean;
+}
+/**
+ * The immutable credential replica: each credential stored as an EDV envelope,
+ * addressed by the envelope's content hash, never overwritten, never public.
+ */
+export declare const PRIVATE_CREDENTIALS_COLLECTION_SPEC: SpaceCollectionSpec;
+/**
+ * The plaintext, world-readable copies of shared credentials, keyed by the
+ * credential's content cid (the same id every replica mints, so a share
+ * converges), granted collection-level world read on the server.
+ */
+export declare const PUBLIC_CREDENTIALS_COLLECTION_SPEC: SpaceCollectionSpec;
+/**
+ * The append-only activity log: each entry stored as an EDV envelope, addressed
+ * by content hash, never overwritten, never public. Shared with the web wallet's
+ * `wallet-activity` collection, so each replica reads the other's entries.
+ */
+export declare const WALLET_ACTIVITY_COLLECTION_SPEC: SpaceCollectionSpec;
+/** The wallet Space's own (non-contacts) collection specs, in provision order. */
+export declare const WALLET_SPACE_COLLECTION_SPECS: SpaceCollectionSpec[];
+//# sourceMappingURL=collections.d.ts.map

package/dist/space/collections.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collections.d.ts","sourceRoot":"","sources":["../../src/space/collections.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;GAaG;AAEH,0EAA0E;AAC1E,eAAO,MAAM,8BAA8B,wBAAwB,CAAA;AACnE,2EAA2E;AAC3E,eAAO,MAAM,6BAA6B,uBAAuB,CAAA;AACjE,0DAA0D;AAC1D,eAAO,MAAM,0BAA0B,oBAAoB,CAAA;AAE3D;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,MAAM,CAAA;IACpB,YAAY,EAAE,SAAS,GAAG,QAAQ,CAAA;IAClC,OAAO,EAAE,OAAO,CAAA;IAChB,UAAU,EAAE,KAAK,GAAG,WAAW,CAAA;IAC/B,QAAQ,EAAE,OAAO,CAAA;CAClB;AAED;;;GAGG;AACH,eAAO,MAAM,mCAAmC,EAAE,mBAMjD,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,kCAAkC,EAAE,mBAMhD,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,+BAA+B,EAAE,mBAM7C,CAAA;AAED,kFAAkF;AAClF,eAAO,MAAM,6BAA6B,EAAE,mBAAmB,EAI9D,CAAA"}