@brass-build/client 0.4.0 → 0.5.0

package/dist/guest-link.js

@@ -5,9 +5,337 @@
 //
 // Pure + search-string-in so it stays testable, mirroring
 // `isExportMode(search)`.
-export const GUEST_LINK_PARAM = 'brass_link';
+const GUEST_LINK_PARAM = 'brass_link';
 export function readGuestLinkToken(search) {
     const value = new URLSearchParams(search).get(GUEST_LINK_PARAM);
     return value && value.trim() !== '' ? value : null;
 }
+// Pin the token into the page URL (`replaceState`, never a history entry):
+// a document created while signed out is reached again only through its
+// token, so a reload restores it from here, and `signIn()` carries this URL
+// as its return address.
+export function writeGuestLinkToken(token) {
+    if (typeof window === 'undefined')
+        return;
+    try {
+        const url = new URL(window.location.href);
+        url.searchParams.set(GUEST_LINK_PARAM, token);
+        const next = url.toString();
+        if (next === window.location.href)
+            return;
+        window.history.replaceState(window.history.state, '', next);
+    }
+    catch {
+        // History API unavailable or URL exotic: leave the URL alone.
+    }
+}
+export function clearGuestLinkToken() {
+    if (typeof window === 'undefined')
+        return;
+    try {
+        const url = new URL(window.location.href);
+        if (!url.searchParams.has(GUEST_LINK_PARAM))
+            return;
+        url.searchParams.delete(GUEST_LINK_PARAM);
+        window.history.replaceState(window.history.state, '', url.toString());
+    }
+    catch {
+        // See `writeGuestLinkToken`.
+    }
+}
+// The last document a visitor created without an account, per app. The URL
+// is that document's only handle, so a visitor who closes the tab and comes
+// back to the app's root would have no way back to it; the app's signed-out
+// gate offers it from here. localStorage, since the return is in a new tab.
+// The expiry is stored beside the token so the gate can say when the work
+// is lost without a request, and an entry past it reads as absent.
+//
+// The token is a credential to an editable document, which is why the
+// session hands an app the expiry alone and opens the document itself.
+const UNSAVED_KEY_PREFIX = 'brass:unsaved:';
+function unsavedStorage() {
+    if (typeof localStorage === 'undefined')
+        return null;
+    try {
+        return localStorage;
+    }
+    catch {
+        return null;
+    }
+}
+function unsavedKey(appId) {
+    return `${UNSAVED_KEY_PREFIX}${appId}`;
+}
+export function storeUnsavedWork(appId, token, expiresAt) {
+    const storage = unsavedStorage();
+    if (!storage)
+        return;
+    try {
+        storage.setItem(unsavedKey(appId), JSON.stringify({ token, expires_at: expiresAt.toISOString() }));
+    }
+    catch {
+        // Quota / disabled storage. The way back is a niceness; the open that
+        // just succeeded must not fail on it.
+    }
+}
+export function readUnsavedWork(appId, now = Date.now()) {
+    const storage = unsavedStorage();
+    if (!storage)
+        return null;
+    let raw;
+    try {
+        raw = storage.getItem(unsavedKey(appId));
+    }
+    catch {
+        return null;
+    }
+    if (raw === null)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    const entry = parsed;
+    const expiresAt = typeof entry?.expires_at === 'string' ? new Date(entry.expires_at) : null;
+    if (typeof entry?.token !== 'string' ||
+        entry.token === '' ||
+        expiresAt === null ||
+        Number.isNaN(expiresAt.getTime())) {
+        return null;
+    }
+    // The platform removes the document at the expiry, so an entry past it
+    // names nothing and is dropped here rather than offered.
+    if (expiresAt.getTime() <= now) {
+        clearUnsavedWork(appId);
+        return null;
+    }
+    return { token: entry.token, expiresAt };
+}
+export function clearUnsavedWork(appId) {
+    const storage = unsavedStorage();
+    if (!storage)
+        return;
+    try {
+        storage.removeItem(unsavedKey(appId));
+    }
+    catch {
+        // See `storeUnsavedWork`.
+    }
+}
+// Whether this browser has edited a document it made without an account. New
+// and Upload ask before replacing one, so the marker outlives a reload; it
+// carries the document's expiry so an entry past it is dropped on read.
+const EDITED_KEY_PREFIX = 'brass:trial-edited:';
+export function markTrialEdited(token, expiresAt) {
+    const storage = unsavedStorage();
+    if (!storage)
+        return;
+    try {
+        storage.setItem(`${EDITED_KEY_PREFIX}${token}`, expiresAt.toISOString());
+    }
+    catch {
+        // See `storeUnsavedWork`.
+    }
+}
+export function trialWasEdited(token, now = Date.now()) {
+    const storage = unsavedStorage();
+    if (!storage)
+        return false;
+    let raw;
+    try {
+        raw = storage.getItem(`${EDITED_KEY_PREFIX}${token}`);
+    }
+    catch {
+        return false;
+    }
+    if (raw === null)
+        return false;
+    const expiresAt = Date.parse(raw);
+    if (Number.isNaN(expiresAt) || expiresAt <= now) {
+        try {
+            storage.removeItem(`${EDITED_KEY_PREFIX}${token}`);
+        }
+        catch {
+            // See `storeUnsavedWork`.
+        }
+        return false;
+    }
+    return true;
+}
+// The claim secret the mint handed this browser, one per document, keyed by
+// the app and the document's link token. Only the browser that made the
+// document has one, so a sign-in here keeps the document and a sign-in
+// wherever its link was shared does not. Written at the mint alone, so opening
+// a shared link leaves it alone. Every mint prunes the secrets whose document
+// has expired, since nothing else removes the secret of a document nobody
+// came back to.
+const CLAIM_KEY_PREFIX = 'brass:claim:';
+function claimKey(appId, token) {
+    return `${CLAIM_KEY_PREFIX}${appId}:${token}`;
+}
+// Collected before any removal, since removing a key renumbers the rest.
+function claimKeys(storage, prefix) {
+    const keys = [];
+    try {
+        for (let i = 0; i < storage.length; i++) {
+            const key = storage.key(i);
+            if (key !== null && key.startsWith(prefix))
+                keys.push(key);
+        }
+    }
+    catch {
+        // See `storeUnsavedWork`.
+    }
+    return keys;
+}
+function readClaimEntry(storage, key, now) {
+    let entry;
+    try {
+        entry = JSON.parse(storage.getItem(key) ?? 'null');
+    }
+    catch {
+        entry = null;
+    }
+    const expiresAt = typeof entry?.expires_at === 'string' ? Date.parse(entry.expires_at) : NaN;
+    if (typeof entry?.secret !== 'string' || Number.isNaN(expiresAt) || expiresAt <= now) {
+        try {
+            storage.removeItem(key);
+        }
+        catch {
+            // See `storeUnsavedWork`.
+        }
+        return null;
+    }
+    return entry.secret;
+}
+function pruneClaimSecrets(storage, now) {
+    for (const key of claimKeys(storage, CLAIM_KEY_PREFIX))
+        readClaimEntry(storage, key, now);
+}
+export function storeClaimSecret(appId, token, secret, expiresAt, now = Date.now()) {
+    const storage = unsavedStorage();
+    if (!storage)
+        return;
+    pruneClaimSecrets(storage, now);
+    try {
+        storage.setItem(claimKey(appId, token), JSON.stringify({ secret, expires_at: expiresAt.toISOString() }));
+    }
+    catch {
+        // See `storeUnsavedWork`.
+    }
+}
+export function readClaimSecret(appId, token, now = Date.now()) {
+    const storage = unsavedStorage();
+    if (!storage)
+        return null;
+    return readClaimEntry(storage, claimKey(appId, token), now);
+}
+// One document's secret, or with no token every secret this browser holds
+// for the app.
+export function clearClaimSecret(appId, token) {
+    const storage = unsavedStorage();
+    if (!storage)
+        return;
+    const keys = token === undefined
+        ? claimKeys(storage, `${CLAIM_KEY_PREFIX}${appId}:`)
+        : [claimKey(appId, token)];
+    for (const key of keys) {
+        try {
+            storage.removeItem(key);
+        }
+        catch {
+            // See `storeUnsavedWork`.
+        }
+    }
+}
+// That this tab started a sign-in from a guest page, and on which token. Per
+// tab (sessionStorage), written by `signIn()` and taken once on the return,
+// so a URL carrying `brass_code` that this tab did not ask for claims nothing.
+const SIGN_IN_INTENT_PREFIX = 'brass:claim-intent:';
+function tabStorage() {
+    if (typeof sessionStorage === 'undefined')
+        return null;
+    try {
+        return sessionStorage;
+    }
+    catch {
+        return null;
+    }
+}
+export function markClaimIntent(appId, token) {
+    try {
+        tabStorage()?.setItem(`${SIGN_IN_INTENT_PREFIX}${appId}`, token);
+    }
+    catch {
+        // See `storeUnsavedWork`.
+    }
+}
+export function takeClaimIntent(appId) {
+    const storage = tabStorage();
+    if (!storage)
+        return null;
+    try {
+        const token = storage.getItem(`${SIGN_IN_INTENT_PREFIX}${appId}`);
+        storage.removeItem(`${SIGN_IN_INTENT_PREFIX}${appId}`);
+        return token;
+    }
+    catch {
+        return null;
+    }
+}
+// The documents this browser claimed, per app, by the mint link each claim
+// revoked. Reading that link again answers 410 for everyone, and a page that
+// holds no session cannot ask the platform where it leads, so this is how a
+// signed-out page on it knows to offer sign-in to the document instead. It
+// confers no access (the open after sign-in is checked like any other), so a
+// sign-out keeps it. Entries lapse after `CLAIMED_LINK_TTL_MS`.
+const CLAIMED_KEY_PREFIX = 'brass:claimed:';
+const CLAIMED_LINK_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+function claimedKey(appId, token) {
+    return `${CLAIMED_KEY_PREFIX}${appId}:${token}`;
+}
+function readClaimedEntry(storage, key, now) {
+    let entry;
+    try {
+        entry = JSON.parse(storage.getItem(key) ?? 'null');
+    }
+    catch {
+        entry = null;
+    }
+    const claimedAt = typeof entry?.claimed_at === 'number' ? entry.claimed_at : NaN;
+    if (typeof entry?.doc_id !== 'string' ||
+        Number.isNaN(claimedAt) ||
+        claimedAt + CLAIMED_LINK_TTL_MS <= now) {
+        try {
+            storage.removeItem(key);
+        }
+        catch {
+            // See `storeUnsavedWork`.
+        }
+        return null;
+    }
+    return entry.doc_id;
+}
+export function storeClaimedLink(appId, token, docId, now = Date.now()) {
+    const storage = unsavedStorage();
+    if (!storage)
+        return;
+    for (const key of claimKeys(storage, CLAIMED_KEY_PREFIX))
+        readClaimedEntry(storage, key, now);
+    try {
+        storage.setItem(claimedKey(appId, token), JSON.stringify({ doc_id: docId, claimed_at: now }));
+    }
+    catch {
+        // See `storeUnsavedWork`.
+    }
+}
+export function readClaimedLink(appId, token, now = Date.now()) {
+    const storage = unsavedStorage();
+    if (!storage)
+        return null;
+    return readClaimedEntry(storage, claimedKey(appId, token), now);
+}
 //# sourceMappingURL=guest-link.js.map

package/dist/guest-link.js.map

@@ -1 +1 @@
-{"version":3,"file":"guest-link.js","sourceRoot":"","sources":["../src/guest-link.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,yEAAyE;AACzE,mEAAmE;AACnE,2EAA2E;AAC3E,EAAE;AACF,0DAA0D;AAC1D,0BAA0B;AAE1B,MAAM,CAAC,MAAM,gBAAgB,GAAG,YAAY,CAAC;AAE7C,MAAM,UAAU,kBAAkB,CAAC,MAAc;IAC/C,MAAM,KAAK,GAAG,IAAI,eAAe,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;IAChE,OAAO,KAAK,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;AACrD,CAAC"}
+{"version":3,"file":"guest-link.js","sourceRoot":"","sources":["../src/guest-link.ts"],"names":[],"mappings":"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"}

package/dist/handle-types.d.ts

@@ -23,8 +23,9 @@ export interface Splice<E> {
     readonly inserted: readonly E[];
 }
 /**
- * What changed in a list. Fires once on registration carrying the whole list
- * as a single splice, then on every change carrying only what moved.
+ * What changed in a list. Fires once on registration carrying the whole list,
+ * then on every change carrying only what moved. No splice inserts more than
+ * 10,000 elements, so a spread apply stays inside the engine's argument limit.
  *
  * A registration fire and a resync are not special cases a subscriber has to
  * recognise: both arrive as splices that replace what it was last told, so
@@ -41,13 +42,36 @@ export interface HandleOwner {
     assertReadable(): void;
     ensureLocalUpdatesSubscribed(): void;
     commitMutate(): void;
+    runMutate(options: MutateOptions | undefined, fn: () => void): void;
     originOf(event: unknown): ChangeSource;
+    reportSubscriberThrow(err: unknown): void;
+}
+/** Options every `mutate` takes. */
+export interface MutateOptions {
+    /**
+     * `false` keeps the write off the reader's Undo stack, for a pass the app
+     * runs on its own rather than one the reader asked for. Defaults to true.
+     */
+    undoable?: boolean;
 }
 export interface MapHandle<T = unknown> {
+    /** Per-entry read. Returns undefined when missing. */
     get(entryKey: string): T | undefined;
+    /** Keys currently in the map. */
     keys(): string[];
+    /** Whether an entry exists at `entryKey`. */
     has(entryKey: string): boolean;
-    mutate(fn: (draft: Record<string, T>) => void): void;
+    /** Every `[key, value]`, as a walk. Each step hands over one entry, so a
+     *  caller that does not keep them never holds the whole map at once. */
+    entries(): IterableIterator<[string, T]>;
+    /** Mutate through a typed JS-proxy, scoped to this container; same
+     *  ergonomics as `doc.mutate(d => { d.entities[id].field = ... })`. */
+    mutate(fn: (draft: Record<string, T>) => void, options?: MutateOptions): void;
+    /** ONE channel for every change whatever produced it (local / remote / undo
+     *  / redo / checkout): the projection reconciles by value. The callback gets
+     *  `change` and optional `origin` a render ignores. Fires once on
+     *  registration with the whole map as `change.set`, then on every change
+     *  (each later fire proportional to what that change wrote). */
     subscribe(cb: MapSubscriber<T>): HandleUnsubscribe;
     /**
      * Report each time this container has been delivered whole: on
@@ -63,6 +87,10 @@ export interface MapHandle<T = unknown> {
      * began, which is the only claim available: more always arrives afterwards.
      */
     onSettled(cb: () => void): HandleUnsubscribe;
+    /** Child handle for `entries[entryKey]` when that entry is itself a map /
+     *  list. Reads see empty until the container exists; the first mutate
+     *  creates it, and a subscription taken before that delivers the container
+     *  whole on whichever write creates it. */
     map<U>(entryKey: string): MapHandle<U>;
     list<U>(entryKey: string): ListHandle<U>;
 }
@@ -84,7 +112,16 @@ export interface ListDraft<T> extends Array<T> {
 }
 export interface ListHandle<T = unknown> {
     length(): number;
-    mutate(fn: (draft: ListDraft<T>) => void): void;
+    /** The element at `index`, or undefined outside the list. */
+    get(index: number): T | undefined;
+    /** Every element in order, as a walk. */
+    values(): IterableIterator<T>;
+    mutate(fn: (draft: ListDraft<T>) => void, options?: MutateOptions): void;
+    /** Fires once on registration carrying the whole list, then on
+     *  every change carrying only what moved, so a subscriber applies splices to
+     *  what it already holds and never re-reads. A keyed collection belongs in a
+     *  map (or `orderedMap`), which reconciles by key; a list is for ordering
+     *  keys and small positional data. */
     subscribe(cb: ListSubscriber<T>): HandleUnsubscribe;
     /**
      * Report each time this container has been delivered whole: on
@@ -121,16 +158,41 @@ export type OrderedMapPosition = {
     index: number;
 };
 export interface OrderedMapHandle<T = unknown> {
+    /** Per-entry read. Returns undefined when missing. */
     get(entryKey: string): T | undefined;
+    /** Whether an entry exists in the map. */
     has(entryKey: string): boolean;
+    /** Keys in order-list order, filtered to keys still present in the map. */
     keys(): string[];
+    /** Every `[key, value]` in order, as a walk. */
+    entries(): IterableIterator<[string, T]>;
+    /** @deprecated Use `entries()`, which walks the same records in the same
+     *  order without building the array. */
     ordered(): {
         key: string;
         value: T;
     }[];
-    mutate(fn: (draft: Record<string, T>) => void): void;
+    /** Mutate the map; the sibling order list reconciles in the same commit
+     *  (new keys appended in insertion order, deleted keys pruned). Drive it
+     *  like `MapHandle.mutate`: `m[key] = record`, `delete m[key]`,
+     *  `m[key].field = ...`. */
+    mutate(fn: (draft: Record<string, T>) => void, options?: MutateOptions): void;
+    /** Write `value` under `entryKey` and put that key at `at`, both in ONE
+     *  commit (one undo step) like every other structural edit here. A key the
+     *  map already holds is written and repositioned rather than named twice. */
     insert(entryKey: string, value: T, at: OrderedMapPosition): void;
+    /** Reposition a key the map already holds, writing the order list alone. A
+     *  key the map does not hold does nothing, so a reorder racing a peer's
+     *  delete of the same key leaves the delete standing. */
     move(entryKey: string, to: OrderedMapPosition): void;
+    /** Fires once on registration (the whole map as `change.set` in order),
+     *  then on every change. A field edit carries only `set` / `deleted`; a
+     *  change that moves the order also carries `change.order` (live keys in
+     *  order) so the app re-sequences the views it holds. A move the map does
+     *  not see (an edit of the sibling order list, a merge that resequences
+     *  keys already present) arrives as an `order` of its own with an empty
+     *  `set`. Content stays proportional to what the change wrote; re-sequencing
+     *  happens only when the order moves, and at most once per change. */
     subscribe(cb: MapSubscriber<T>): HandleUnsubscribe;
     /**
      * Report each time this container has been delivered whole: on

package/dist/handle-types.d.ts.map

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

package/dist/handles.d.ts

@@ -1,24 +1,6 @@
 import { LoroMovableList, LoroMap } from './wasm-runtime.js';
-import { MutateBatcher } from './mutate-batching.js';
 import type { Change, ChangeOrigin, ChangeSource, HandleOwner, HandleUnsubscribe, ListDraft, ListHandle, ListSubscriber, MapHandle, MapSubscriber, OrderedMapHandle, OrderedMapPosition } from './handle-types.js';
 export type { Change, ChangeOrigin, ChangeSource, HandleOwner, ListDraft, HandleUnsubscribe, ListHandle, ListSubscriber, MapHandle, MapSubscriber, OrderedMapHandle, OrderedMapPosition, };
-/**
- * Where a root map's ADDITIONS go once the map has paged itself part-way
- * through a mutation.
- *
- * A mutation large enough to need paging usually starts against a map that
- * is not yet paged, so the decision cannot be made once at the top. The
- * proxy consults this on every assignment; while it declines, the mutation
- * runs exactly as an unpaged one does.
- */
-interface WriteDivert {
-    take(key: string, value: unknown): boolean;
-    holds(key: string): boolean;
-    peek(key: string): unknown;
-    drop(key: string): void;
-    keys(): string[];
-}
-export declare function wrapLoroMapProxy(loroMap: LoroMap, batcher?: MutateBatcher, divert?: WriteDivert, guardKeys?: boolean): Record<string, unknown>;
 /**
  * What a ROOT map handle needs from its owning Document to present a paged
  * store. Bundled rather than passed one by one: every member is read off the
@@ -46,7 +28,21 @@ export interface PagedRootHooks {
     sessionToken(): string;
     stateVersion(): StateVersion;
 }
-export declare function createRootMapHandle<T>(root: LoroMap, owner: HandleOwner, paging?: PagedRootHooks): MapHandle<T>;
+/**
+ * Hide a handle's own fields from enumeration.
+ *
+ * A handle is a VIEW onto a container, not the container, so `Object.keys` on
+ * one is a natural thing to reach for and it type-checks. Enumerable, it
+ * answers with the handle's own fields, which look enough like record keys to
+ * pass and are the same handful whatever the document holds, so the mistake
+ * reads as a small document rather than as a mistake. Hidden, the answer is
+ * empty, and the reader goes looking for `keys()`.
+ *
+ * Every field is declared with an initialiser, so they all exist by the time
+ * this runs and a later assignment keeps the descriptor this sets.
+ */
+export declare function hideOwnFields(handle: object): void;
+export declare function createRootMapHandle<T>(root: LoroMap, owner: HandleOwner, paging?: PagedRootHooks, rootKey?: string): MapHandle<T>;
 export declare function createRootListHandle<T>(root: LoroMovableList, owner: HandleOwner): ListHandle<T>;
 export declare function rebindRootMapAnchor(handle: MapHandle<unknown>, next: LoroMap): void;
 export declare function rebindRootListAnchor(handle: ListHandle<unknown>, next: LoroMovableList): void;

package/dist/handles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handles.d.ts","sourceRoot":"","sources":["../src/handles.ts"],"names":[],"mappings":"AAOA,OAAO,EACL,eAAe,EACf,OAAO,EAIR,MAAM,mBAAmB,CAAC;AA8B3B,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAErD,OAAO,KAAK,EAGV,MAAM,EACN,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,iBAAiB,EAGjB,SAAS,EACT,UAAU,EACV,cAAc,EACd,SAAS,EACT,aAAa,EACb,gBAAgB,EAChB,kBAAkB,EACnB,MAAM,mBAAmB,CAAC;AAE3B,YAAY,EACV,MAAM,EACN,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,SAAS,EACT,iBAAiB,EACjB,UAAU,EACV,cAAc,EACd,SAAS,EACT,aAAa,EACb,gBAAgB,EAChB,kBAAkB,GACnB,CAAC;AAwSF;;;;;;;;GAQG;AACH,UAAU,WAAW;IAInB,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC;IAG3C,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAC5B,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAC3B,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,IAAI,IAAI,MAAM,EAAE,CAAC;CAClB;AAOD,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,OAAO,EAKhB,OAAO,CAAC,EAAE,aAAa,EACvB,MAAM,CAAC,EAAE,WAAW,EAKpB,SAAS,UAAQ,GAChB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA8FzB;AAosED;;;;;GAKG;AACH;;;;;;;;;;GAUG;AACH,MAAM,MAAM,YAAY,GAAG,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,EAAE,CAAC;AAYxE,MAAM,WAAW,cAAc;IAE7B,OAAO,IAAI,OAAO,CAAC;IAGnB,IAAI,IAAI,IAAI,CAAC;IAEb,YAAY,IAAI,MAAM,CAAC;IAEvB,YAAY,IAAI,YAAY,CAAC;CAC9B;AAmiDD,wBAAgB,mBAAmB,CAAC,CAAC,EACnC,IAAI,EAAE,OAAO,EACb,KAAK,EAAE,WAAW,EAClB,MAAM,CAAC,EAAE,cAAc,GACtB,SAAS,CAAC,CAAC,CAAC,CAEd;AAED,wBAAgB,oBAAoB,CAAC,CAAC,EACpC,IAAI,EAAE,eAAe,EACrB,KAAK,EAAE,WAAW,GACjB,UAAU,CAAC,CAAC,CAAC,CAEf;AAgBD,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,SAAS,CAAC,OAAO,CAAC,EAC1B,IAAI,EAAE,OAAO,GACZ,IAAI,CAEN;AAED,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,UAAU,CAAC,OAAO,CAAC,EAC3B,IAAI,EAAE,eAAe,GACpB,IAAI,CAEN;AAcD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,CAAC,OAAO,CAAC,GAAG,IAAI,CAEpE;AAMD,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,SAAS,CAAC,OAAO,CAAC,GAAG,UAAU,CAAC,OAAO,CAAC,GAC/C,IAAI,CAEN;AAOD,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,SAAS,CAAC,OAAO,CAAC,GAAG,UAAU,CAAC,OAAO,CAAC,GAC/C,IAAI,CAEN;AAKD,wBAAgB,sBAAsB,CAAC,CAAC,EACtC,GAAG,EAAE,SAAS,CAAC,CAAC,CAAC,EACjB,KAAK,EAAE,UAAU,CAAC,MAAM,CAAC,EACzB,KAAK,EAAE,WAAW,GACjB,gBAAgB,CAAC,CAAC,CAAC,CAMrB"}
+{"version":3,"file":"handles.d.ts","sourceRoot":"","sources":["../src/handles.ts"],"names":[],"mappings":"AAOA,OAAO,EACL,eAAe,EACf,OAAO,EAIR,MAAM,mBAAmB,CAAC;AAmC3B,OAAO,KAAK,EAGV,MAAM,EACN,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,iBAAiB,EAGjB,SAAS,EACT,UAAU,EACV,cAAc,EACd,SAAS,EACT,aAAa,EAEb,gBAAgB,EAChB,kBAAkB,EACnB,MAAM,mBAAmB,CAAC;AAG3B,YAAY,EACV,MAAM,EACN,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,SAAS,EACT,iBAAiB,EACjB,UAAU,EACV,cAAc,EACd,SAAS,EACT,aAAa,EACb,gBAAgB,EAChB,kBAAkB,GACnB,CAAC;AA8pFF;;;;;GAKG;AACH;;;;;;;;;;GAUG;AACH,MAAM,MAAM,YAAY,GAAG,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,EAAE,CAAC;AAYxE,MAAM,WAAW,cAAc;IAE7B,OAAO,IAAI,OAAO,CAAC;IAGnB,IAAI,IAAI,IAAI,CAAC;IAEb,YAAY,IAAI,MAAM,CAAC;IAEvB,YAAY,IAAI,YAAY,CAAC;CAC9B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAIlD;AAkoDD,wBAAgB,mBAAmB,CAAC,CAAC,EACnC,IAAI,EAAE,OAAO,EACb,KAAK,EAAE,WAAW,EAClB,MAAM,CAAC,EAAE,cAAc,EACvB,OAAO,CAAC,EAAE,MAAM,GACf,SAAS,CAAC,CAAC,CAAC,CAQd;AAED,wBAAgB,oBAAoB,CAAC,CAAC,EACpC,IAAI,EAAE,eAAe,EACrB,KAAK,EAAE,WAAW,GACjB,UAAU,CAAC,CAAC,CAAC,CAEf;AAgBD,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,SAAS,CAAC,OAAO,CAAC,EAC1B,IAAI,EAAE,OAAO,GACZ,IAAI,CAEN;AAED,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,UAAU,CAAC,OAAO,CAAC,EAC3B,IAAI,EAAE,eAAe,GACpB,IAAI,CAEN;AAcD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,CAAC,OAAO,CAAC,GAAG,IAAI,CAEpE;AAMD,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,SAAS,CAAC,OAAO,CAAC,GAAG,UAAU,CAAC,OAAO,CAAC,GAC/C,IAAI,CAEN;AAOD,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,SAAS,CAAC,OAAO,CAAC,GAAG,UAAU,CAAC,OAAO,CAAC,GAC/C,IAAI,CAEN;AAKD,wBAAgB,sBAAsB,CAAC,CAAC,EACtC,GAAG,EAAE,SAAS,CAAC,CAAC,CAAC,EACjB,KAAK,EAAE,UAAU,CAAC,MAAM,CAAC,EACzB,KAAK,EAAE,WAAW,GACjB,gBAAgB,CAAC,CAAC,CAAC,CAMrB"}