@graview/ship 0.1.0

package/dist/photos.d.ts

@@ -0,0 +1,89 @@
+import type { GraphReader } from "@graview/core";
+/**
+ * PHOTOGRAPHS, AND THE QUOTA THEY WILL OTHERWISE EAT.
+ *
+ * A photograph off a modern phone is three to six megabytes. The browser
+ * adapter in this package keeps the whole graph — snapshot, log and meta —
+ * in `localStorage`, which is about five megabytes in total. So the failure
+ * mode of doing nothing is not "photographs are big"; it is that the
+ * twelfth photograph throws a `QuotaExceededError` somewhere inside a save
+ * and **the graph does not persist** — every node, every op, every hour
+ * anyone logged, gone on the next reload, because somebody photographed a
+ * gutter.
+ *
+ * That is a trap this package sets and therefore a trap this package should
+ * spring. Three defences, in order:
+ *
+ * 1. **Downscale before anything is stored** (`downscale`, in
+ *    `@graview/primitives` where a canvas is at hand). Nothing a model is
+ *    asked to look at needs 4032 pixels.
+ * 2. **A declared budget**, checked before the write, with the number and
+ *    the reason both written down rather than discovered.
+ * 3. **A loud, catchable refusal** when the budget is gone — never a
+ *    silently truncated graph. The person is told which photograph could
+ *    not be kept and how much room is left.
+ *
+ * Everything here is pure, so it runs in the domain tier where the check
+ * belongs: before the act, not after the write.
+ *
+ * Found by a product that stores a photograph on a sighting. Its numbers
+ * are the defaults, and any of them can be said again.
+ */
+/**
+ * What to spend on photographs, in bytes.
+ *
+ * `localStorage` is ~5 MB per origin and the adapter stores a snapshot AND
+ * an append-only log, so a graph's own text can easily be another megabyte
+ * after a few seasons. 2 MB for photographs leaves room for both and for
+ * the log to keep growing, which matters more: a lost photograph is an
+ * annoyance and a lost log is the whole record.
+ */
+export declare const PHOTO_BUDGET_BYTES: number;
+/** A single photograph over this is refused outright, before the budget. */
+export declare const PHOTO_MAX_BYTES: number;
+export declare class PhotoTooLarge extends Error {
+    readonly bytes: number;
+    readonly remaining: number;
+    constructor(message: string, bytes: number, remaining: number);
+}
+/**
+ * How many bytes a data URL actually costs in storage.
+ *
+ * Base64 is 4 characters per 3 bytes, and `localStorage` stores UTF-16, so
+ * a data URL costs roughly TWICE its character count in real terms on some
+ * engines. Counting characters and doubling is the pessimistic reading, and
+ * pessimistic is the right direction for a budget whose overrun destroys
+ * the graph.
+ */
+export declare function storageBytes(dataUrl: string): number;
+/** Where a graph keeps its photographs: a kind, and a field on it. */
+export interface PhotoField {
+    readonly kind: string;
+    readonly field: string;
+}
+/** What every photograph in the graph is costing, together. */
+export declare function photosUsed(graph: GraphReader<{
+    id: string;
+    kind: string;
+} & Record<string, unknown>>, where: readonly PhotoField[]): number;
+export interface PhotoBudget {
+    readonly total?: number;
+    readonly each?: number;
+    /** What the installation is called, for the refusal's own sentence. */
+    readonly of?: string;
+    /**
+     * What to do about it, in the product's own words — "Remove a photograph
+     * from an older sighting". A refusal that does not say what to do next is
+     * half a refusal, and only the product knows what the older thing is
+     * called.
+     */
+    readonly advice?: string;
+}
+/**
+ * Whether one more photograph fits, and a readable refusal if it does not.
+ *
+ * Called BEFORE the act that would store it. Throwing after the write is
+ * the bug this exists to prevent.
+ */
+export declare function assertPhotoFits(dataUrl: string, alreadyUsed: number, budget?: PhotoBudget): void;
+//# sourceMappingURL=photos.d.ts.map

package/dist/photos.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"photos.d.ts","sourceRoot":"","sources":["../src/photos.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,QAAkB,CAAC;AAElD,4EAA4E;AAC5E,eAAO,MAAM,eAAe,QAAa,CAAC;AAE1C,qBAAa,aAAc,SAAQ,KAAK;IAGpC,QAAQ,CAAC,KAAK,EAAE,MAAM;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM;gBAF1B,OAAO,EAAE,MAAM,EACN,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM;CAK7B;AAID;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,sEAAsE;AACtE,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,+DAA+D;AAC/D,wBAAgB,UAAU,CACxB,KAAK,EAAE,WAAW,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAC1E,KAAK,EAAE,SAAS,UAAU,EAAE,GAC3B,MAAM,CAUR;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,uEAAuE;IACvE,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,GAAE,WAAgB,GAAG,IAAI,CAuBpG"}

package/dist/photos.js

@@ -0,0 +1,102 @@
+/**
+ * PHOTOGRAPHS, AND THE QUOTA THEY WILL OTHERWISE EAT.
+ *
+ * A photograph off a modern phone is three to six megabytes. The browser
+ * adapter in this package keeps the whole graph — snapshot, log and meta —
+ * in `localStorage`, which is about five megabytes in total. So the failure
+ * mode of doing nothing is not "photographs are big"; it is that the
+ * twelfth photograph throws a `QuotaExceededError` somewhere inside a save
+ * and **the graph does not persist** — every node, every op, every hour
+ * anyone logged, gone on the next reload, because somebody photographed a
+ * gutter.
+ *
+ * That is a trap this package sets and therefore a trap this package should
+ * spring. Three defences, in order:
+ *
+ * 1. **Downscale before anything is stored** (`downscale`, in
+ *    `@graview/primitives` where a canvas is at hand). Nothing a model is
+ *    asked to look at needs 4032 pixels.
+ * 2. **A declared budget**, checked before the write, with the number and
+ *    the reason both written down rather than discovered.
+ * 3. **A loud, catchable refusal** when the budget is gone — never a
+ *    silently truncated graph. The person is told which photograph could
+ *    not be kept and how much room is left.
+ *
+ * Everything here is pure, so it runs in the domain tier where the check
+ * belongs: before the act, not after the write.
+ *
+ * Found by a product that stores a photograph on a sighting. Its numbers
+ * are the defaults, and any of them can be said again.
+ */
+/**
+ * What to spend on photographs, in bytes.
+ *
+ * `localStorage` is ~5 MB per origin and the adapter stores a snapshot AND
+ * an append-only log, so a graph's own text can easily be another megabyte
+ * after a few seasons. 2 MB for photographs leaves room for both and for
+ * the log to keep growing, which matters more: a lost photograph is an
+ * annoyance and a lost log is the whole record.
+ */
+export const PHOTO_BUDGET_BYTES = 2 * 1024 * 1024;
+/** A single photograph over this is refused outright, before the budget. */
+export const PHOTO_MAX_BYTES = 400 * 1024;
+export class PhotoTooLarge extends Error {
+    bytes;
+    remaining;
+    constructor(message, bytes, remaining) {
+        super(message);
+        this.bytes = bytes;
+        this.remaining = remaining;
+        this.name = "PhotoTooLarge";
+    }
+}
+const kb = (bytes) => `${Math.round(bytes / 1024)} kB`;
+/**
+ * How many bytes a data URL actually costs in storage.
+ *
+ * Base64 is 4 characters per 3 bytes, and `localStorage` stores UTF-16, so
+ * a data URL costs roughly TWICE its character count in real terms on some
+ * engines. Counting characters and doubling is the pessimistic reading, and
+ * pessimistic is the right direction for a budget whose overrun destroys
+ * the graph.
+ */
+export function storageBytes(dataUrl) {
+    return dataUrl.length * 2;
+}
+/** What every photograph in the graph is costing, together. */
+export function photosUsed(graph, where) {
+    let total = 0;
+    for (const node of graph.allNodes()) {
+        for (const at of where) {
+            if (node.kind !== at.kind)
+                continue;
+            const photo = node[at.field];
+            if (typeof photo === "string")
+                total += storageBytes(photo);
+        }
+    }
+    return total;
+}
+/**
+ * Whether one more photograph fits, and a readable refusal if it does not.
+ *
+ * Called BEFORE the act that would store it. Throwing after the write is
+ * the bug this exists to prevent.
+ */
+export function assertPhotoFits(dataUrl, alreadyUsed, budget = {}) {
+    const total = budget.total ?? PHOTO_BUDGET_BYTES;
+    const each = budget.each ?? PHOTO_MAX_BYTES;
+    const bytes = storageBytes(dataUrl);
+    if (bytes > each) {
+        throw new PhotoTooLarge(`That photograph is ${kb(bytes)} and the most one may take is ${kb(each)}. ` +
+            `It should have been made smaller before it got here — this is a bug rather than your fault.`, bytes, total - alreadyUsed);
+    }
+    const remaining = total - alreadyUsed;
+    if (bytes > remaining) {
+        throw new PhotoTooLarge(`There is no room for this photograph: it needs ${kb(bytes)} and ${kb(remaining)} is left of ` +
+            `the ${kb(total)} ${budget.of ?? "this installation"} keeps for photographs. ` +
+            `Everything else you have written down is safe. ` +
+            `${budget.advice ?? "Remove a photograph from an older one to make room."}`, bytes, remaining);
+    }
+}
+//# sourceMappingURL=photos.js.map

package/dist/photos.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"photos.js","sourceRoot":"","sources":["../src/photos.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;AAElD,4EAA4E;AAC5E,MAAM,CAAC,MAAM,eAAe,GAAG,GAAG,GAAG,IAAI,CAAC;AAE1C,MAAM,OAAO,aAAc,SAAQ,KAAK;IAG3B;IACA;IAHX,YACE,OAAe,EACN,KAAa,EACb,SAAiB;QAE1B,KAAK,CAAC,OAAO,CAAC,CAAC;QAHN,UAAK,GAAL,KAAK,CAAQ;QACb,cAAS,GAAT,SAAS,CAAQ;QAG1B,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAC9B,CAAC;CACF;AAED,MAAM,EAAE,GAAG,CAAC,KAAa,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;AAE/D;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY,CAAC,OAAe;IAC1C,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC;AAC5B,CAAC;AAQD,+DAA+D;AAC/D,MAAM,UAAU,UAAU,CACxB,KAA0E,EAC1E,KAA4B;IAE5B,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,QAAQ,EAAE,EAAE,CAAC;QACpC,KAAK,MAAM,EAAE,IAAI,KAAK,EAAE,CAAC;YACvB,IAAI,IAAI,CAAC,IAAI,KAAK,EAAE,CAAC,IAAI;gBAAE,SAAS;YACpC,MAAM,KAAK,GAAG,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC;YAC7B,IAAI,OAAO,KAAK,KAAK,QAAQ;gBAAE,KAAK,IAAI,YAAY,CAAC,KAAK,CAAC,CAAC;QAC9D,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAgBD;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,OAAe,EAAE,WAAmB,EAAE,SAAsB,EAAE;IAC5F,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,IAAI,kBAAkB,CAAC;IACjD,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,IAAI,eAAe,CAAC;IAC5C,MAAM,KAAK,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;IACpC,IAAI,KAAK,GAAG,IAAI,EAAE,CAAC;QACjB,MAAM,IAAI,aAAa,CACrB,sBAAsB,EAAE,CAAC,KAAK,CAAC,iCAAiC,EAAE,CAAC,IAAI,CAAC,IAAI;YAC1E,6FAA6F,EAC/F,KAAK,EACL,KAAK,GAAG,WAAW,CACpB,CAAC;IACJ,CAAC;IACD,MAAM,SAAS,GAAG,KAAK,GAAG,WAAW,CAAC;IACtC,IAAI,KAAK,GAAG,SAAS,EAAE,CAAC;QACtB,MAAM,IAAI,aAAa,CACrB,kDAAkD,EAAE,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC,SAAS,CAAC,cAAc;YAC5F,OAAO,EAAE,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,EAAE,IAAI,mBAAmB,0BAA0B;YAC9E,iDAAiD;YACjD,GAAG,MAAM,CAAC,MAAM,IAAI,qDAAqD,EAAE,EAC7E,KAAK,EACL,SAAS,CACV,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/presence.d.ts

@@ -0,0 +1,33 @@
+import { type PresenceChannel } from "@graview/core";
+/**
+ * WHO IS HERE, BETWEEN THE TABS OF ONE ORIGIN.
+ *
+ * A BroadcastChannel is multiplayer for free: two tabs on the same app see
+ * each other with no server, and a driven browser's pages share one when
+ * they share a context, which is what makes the harness deterministic. It
+ * sits beside `createBrowserAdapter` and, like it, never touches the store,
+ * the adapter or the log — presence is a fact about a person at a screen,
+ * and the graph is not where those go.
+ *
+ * Scoped by the store's scope, because a channel is per origin: a launcher
+ * with three apps mounted would otherwise put Things' keeper in the Colts'
+ * dressing room.
+ */
+/** What this needs of a channel — the browser's own, or Node's, or a fake. */
+export interface ChannelLike {
+    postMessage(message: unknown): void;
+    onmessage: ((event: {
+        readonly data: unknown;
+    }) => void) | null;
+    close(): void;
+}
+export interface BroadcastPresenceOptions {
+    /** How long a presence stands after its last word. Three heartbeats by default. */
+    readonly ttlMs?: number;
+    /** The channel itself, for a test or a host with its own. Defaults to `new BroadcastChannel(name)`. */
+    readonly channel?: ChannelLike;
+    readonly now?: () => number;
+}
+export declare const presenceChannelName: (scope: string) => string;
+export declare function createBroadcastPresence(scope: string, options?: BroadcastPresenceOptions): PresenceChannel;
+//# sourceMappingURL=presence.d.ts.map

package/dist/presence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"presence.d.ts","sourceRoot":"","sources":["../src/presence.ts"],"names":[],"mappings":"AAAA,OAAO,EAA8D,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AAEjH;;;;;;;;;;;;;GAaG;AAEH,8EAA8E;AAC9E,MAAM,WAAW,WAAW;IAC1B,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACpC,SAAS,EAAE,CAAC,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IAChE,KAAK,IAAI,IAAI,CAAC;CACf;AAED,MAAM,WAAW,wBAAwB;IACvC,mFAAmF;IACnF,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,uGAAuG;IACvG,QAAQ,CAAC,OAAO,CAAC,EAAE,WAAW,CAAC;IAC/B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAID,eAAO,MAAM,mBAAmB,GAAI,OAAO,MAAM,KAAG,MAAgC,CAAC;AAWrF,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,wBAA6B,GAAG,eAAe,CA8E9G"}

package/dist/presence.js

@@ -0,0 +1,99 @@
+import { foldPresence, PRESENCE_TTL_MS, samePresence } from "@graview/core";
+export const presenceChannelName = (scope) => `graview:who:${scope}`;
+function openChannel(name) {
+    const Channel = globalThis.BroadcastChannel;
+    if (!Channel)
+        return null;
+    const channel = new Channel(name);
+    // Node's channel keeps the process alive; a presence channel must not.
+    channel.unref?.();
+    return channel;
+}
+export function createBroadcastPresence(scope, options = {}) {
+    const ttl = options.ttlMs ?? PRESENCE_TTL_MS;
+    const now = options.now ?? (() => Date.now());
+    const channel = options.channel ?? openChannel(presenceChannelName(scope));
+    const listeners = new Set();
+    let known = new Map();
+    let self;
+    let sweep = null;
+    const tell = () => {
+        const who = [...known.values()];
+        for (const listener of listeners)
+            listener(who);
+    };
+    const changed = (next) => {
+        if (next.size !== known.size)
+            return true;
+        for (const [participant, presence] of next)
+            if (!samePresence(presence, known.get(participant)))
+                return true;
+        return false;
+    };
+    const fold = (arrived) => {
+        const next = foldPresence(known, arrived, now(), ttl, self);
+        // The fresh timestamps are kept EVEN WHEN nothing else moved: a heartbeat
+        // that says nothing new is exactly what keeps somebody here past the TTL.
+        const moved = changed(next);
+        known = next;
+        if (moved)
+            tell();
+    };
+    /* The sweep only runs while somebody is listening and somebody is here: a quiet page holds no timer. */
+    const keep = () => {
+        if (sweep || listeners.size === 0)
+            return;
+        sweep = setInterval(() => {
+            if (known.size === 0 && sweep) {
+                clearInterval(sweep);
+                sweep = null;
+                return;
+            }
+            fold([]);
+        }, Math.max(100, Math.floor(ttl / 2)));
+        sweep.unref?.();
+    };
+    if (channel) {
+        channel.onmessage = (event) => {
+            const word = event.data;
+            if (word?.type === "here") {
+                fold([word.presence]);
+                keep();
+            }
+            else if (word?.type === "leave") {
+                if (!known.has(word.participant))
+                    return;
+                known = new Map(known);
+                known.delete(word.participant);
+                tell();
+            }
+        };
+    }
+    return {
+        here(presence) {
+            self = presence.participant;
+            // Never a word about yourself in your own map.
+            if (known.has(presence.participant))
+                fold([]);
+            channel?.postMessage({ type: "here", presence });
+        },
+        onWho(listener) {
+            listeners.add(listener);
+            keep();
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        leave() {
+            if (self !== undefined)
+                channel?.postMessage({ type: "leave", participant: self });
+            if (sweep)
+                clearInterval(sweep);
+            sweep = null;
+            listeners.clear();
+            known = new Map();
+            channel?.close();
+        },
+    };
+}
+//# sourceMappingURL=presence.js.map

package/dist/presence.js.map

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

package/dist/remote.d.ts

@@ -0,0 +1,73 @@
+import { Store, type AnySchema, type GraviewApp, type MutationCall, type Operation, type PresenceChannel, type Principal } from "@graview/core";
+/**
+ * THE OTHER END OF THE WIRE: a store whose graph lives on a server.
+ *
+ * The browser still holds a real `Store` — the scene, the strip, the rules
+ * and the routed face all read it the way they always have — but it does not
+ * own the truth. A call goes to the server, which judges it under this
+ * seat's principal and answers with the op it produced; the op is `receive`d
+ * here, so it lands with its own id, author and sequence and the interface
+ * updates exactly as it does for a local change.
+ *
+ * Everyone else's ops arrive the same way, on a poll. Two browsers open on
+ * the same roster see each other within a second, and neither of them has a
+ * second way to write the graph.
+ *
+ * Undo is the interesting case and it needed no special handling: `undo`
+ * produces ordinary calls, and they go down the same wire and are judged by
+ * the same policy — what you may undo is what you may have done, decided on
+ * the server rather than trusted from the client.
+ */
+export interface RemoteOptions<S extends AnySchema> {
+    readonly app: GraviewApp<S>;
+    /** Where the server is: `http://localhost:5196`, say. */
+    readonly url: string;
+    /** Who is at this keyboard. Sent with every call; the server judges by it. */
+    readonly principal?: Principal;
+    /** How often to ask for everybody else's ops, in milliseconds. 0 never asks. */
+    readonly pollMs?: number;
+    readonly fetch?: typeof fetch;
+    readonly storeOptions?: Record<string, unknown>;
+    /**
+     * Headers sent with every request — a gateway's `authorization`, a
+     * tenant, whatever the host in front of `graview serve` asks for. The
+     * framework never reads them; the host's `seatOf` does. This is the seam
+     * where a hosted store's own auth goes without the framework knowing it.
+     */
+    readonly headers?: Readonly<Record<string, string>>;
+}
+export interface RemoteStore<S extends AnySchema> {
+    readonly store: Store<S>;
+    /** The server's version, and what opening it had to migrate. */
+    readonly version: number;
+    readonly migrated: readonly string[];
+    /** Send calls to the server and take back the ops it made. Throws the policy's own sentence. */
+    send(calls: readonly MutationCall[], options?: {
+        intent?: string;
+        batch?: string;
+    }): Promise<readonly Operation[]>;
+    /** Ask for everything appended since this browser last looked. */
+    pull(): Promise<readonly Operation[]>;
+    /**
+     * Told when the server refused something this browser had already shown.
+     * The change is taken back before the listener runs; what is left is
+     * saying so, in the policy's own words.
+     */
+    onRefusal(listener: (reason: string) => void): () => void;
+    /**
+     * Resolves once every call sent so far has been answered — accepted and
+     * landed, or refused and taken back. A browser never waits for this; a
+     * host that must report the server's verdict before it exits (an MCP
+     * seat, `graview apply`) does.
+     */
+    settled(): Promise<void>;
+    /**
+     * WHO IS HERE, over the same poll. Saying where you are rides on the next
+     * heartbeat and the answer carries everybody else — no round trip of its
+     * own, nothing written to the store, the adapter or the log.
+     */
+    readonly presence: PresenceChannel;
+    close(): void;
+}
+export declare function openRemote<S extends AnySchema>(options: RemoteOptions<S>): Promise<RemoteStore<S>>;
+//# sourceMappingURL=remote.d.ts.map

package/dist/remote.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote.d.ts","sourceRoot":"","sources":["../src/remote.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,EACL,KAAK,SAAS,EACd,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,SAAS,EAEd,KAAK,eAAe,EACpB,KAAK,SAAS,EACf,MAAM,eAAe,CAAC;AAGvB;;;;;;;;;;;;;;;;;;GAkBG;AAEH,MAAM,WAAW,aAAa,CAAC,CAAC,SAAS,SAAS;IAChD,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC;IAC5B,yDAAyD;IACzD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;IAC/B,gFAAgF;IAChF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IAC9B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChD;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACrD;AAED,MAAM,WAAW,WAAW,CAAC,CAAC,SAAS,SAAS;IAC9C,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;IACzB,gEAAgE;IAChE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,gGAAgG;IAChG,IAAI,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,EAAE,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,SAAS,SAAS,EAAE,CAAC,CAAC;IACnH,kEAAkE;IAClE,IAAI,IAAI,OAAO,CAAC,SAAS,SAAS,EAAE,CAAC,CAAC;IACtC;;;;OAIG;IACH,SAAS,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IAC1D;;;;;OAKG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IACnC,KAAK,IAAI,IAAI,CAAC;CACf;AAgBD,wBAAsB,UAAU,CAAC,CAAC,SAAS,SAAS,EAAE,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CA0QxG"}