@mdbase-dev/sdk 0.0.0-stage → 0.1.0-beta.153

package/dist/holds.js

@@ -0,0 +1,118 @@
+export const HOLD_TITLE = "mdbase protected your edit";
+const CAUSES = {
+    conflict: {
+        cause: "This file was also changed on another device while you were editing it.",
+        detail: "Your version is kept here and is not synced until you choose what to keep.",
+    },
+    unknown_provenance: {
+        cause: "This file changed on disk in a way mdbase could not trace to an app or a sync.",
+        detail: "The bytes on disk are kept here and are not synced until you confirm them.",
+    },
+    deleted_elsewhere: {
+        cause: "This file was deleted on another device after you edited it.",
+        detail: "Your version is kept here; nothing is deleted until you choose.",
+    },
+    read_only: {
+        cause: "Changed with view access.",
+        detail: "Edit access will not sync these changes. Submit or discard them.",
+    },
+    editor_busy: {
+        cause: "An editor still has this file open with unsaved changes.",
+        detail: "mdbase waits so that it never overwrites what you are typing.",
+    },
+    suspect_write: {
+        cause: "The last write to this file looked incomplete, for example after a crash.",
+        detail: "The file is kept aside and is not synced until you confirm it.",
+    },
+};
+const OPTIONS = {
+    keep_mine: { label: "Keep mine", description: "Sync the version on this device.", resolution: "keep_mine", needs: "records.edit", discardsMine: false },
+    take_theirs: { label: "Take theirs", description: "Replace this file with the synced version.", resolution: "take_theirs", needs: "records.edit", discardsMine: true },
+    keep_both: { label: "Keep both", description: "Save your version as a copy next to the synced one.", resolution: "keep_both", needs: "records.edit", discardsMine: false },
+    delete: { label: "Delete", description: "Accept the deletion and remove this file here too.", resolution: "delete", needs: "records.delete", discardsMine: true },
+    use: { label: "Use merged", description: "Sync the document you merged.", resolution: "use", needs: "records.edit", discardsMine: false },
+    compare: { label: "Compare side by side", description: "Open both versions to merge them.", discardsMine: false },
+};
+/** Which actions apply to each reason, in display order. `compare` and `take_theirs` need a confirmed version. */
+const ACTIONS = {
+    conflict: ["keep_mine", "take_theirs", "compare", "keep_both"],
+    unknown_provenance: ["keep_mine", "take_theirs", "compare", "keep_both"],
+    deleted_elsewhere: ["keep_mine", "delete"],
+    read_only: ["keep_mine", "take_theirs", "compare", "keep_both"],
+    editor_busy: ["keep_mine", "take_theirs", "compare"],
+    suspect_write: ["keep_mine", "take_theirs", "compare", "keep_both"],
+};
+export const HOLD_COMPARE_SCHEME = "mdbase://hold/compare";
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** The compare hand-off the daemon tray opens and apps register: `mdbase://hold/compare?collection=<uuid>&id=<uuid>`. */
+export function holdCompareLink(collectionId, id) {
+    if (!UUID.test(collectionId) || !UUID.test(id))
+        throw new Error("holdCompareLink: collection and id are UUIDs");
+    return `${HOLD_COMPARE_SCHEME}?collection=${collectionId.toLowerCase()}&id=${id.toLowerCase()}`;
+}
+/** Parse a compare hand-off; `null` for anything else (never throws on untrusted input). */
+export function parseHoldCompareLink(url) {
+    if (typeof url !== "string" || url.length > 512 || !url.startsWith(`${HOLD_COMPARE_SCHEME}?`))
+        return null;
+    const q = new URLSearchParams(url.slice(HOLD_COMPARE_SCHEME.length + 1));
+    const collectionId = q.get("collection") ?? "";
+    const id = q.get("id") ?? "";
+    if (!UUID.test(collectionId) || !UUID.test(id))
+        return null;
+    return { collectionId: collectionId.toLowerCase(), id: id.toLowerCase() };
+}
+/** Present one hold: cause, detail, applicable actions and the compare link. */
+export function describeHold(h, o) {
+    const readOnly = h.reason === "read_only";
+    const hasTheirs = h.theirs !== undefined;
+    const canCompare = (o.canCompare ?? true) && hasTheirs;
+    const can = (needs) => !needs || !o.capabilities || o.capabilities.includes(needs);
+    const actions = ACTIONS[h.reason]
+        .filter((a) => a === "compare" ? canCompare : (!readOnly || o.host === true) && (a !== "take_theirs" || hasTheirs || readOnly))
+        .map((action) => {
+        const option = { action, ...OPTIONS[action] };
+        if (readOnly && action === "take_theirs") {
+            option.label = "Discard local changes";
+            option.description = "Discard unsynced changes on this device.";
+            option.needs = "collection.read";
+        }
+        return option;
+    })
+        .filter((a) => can(a.needs));
+    const text = CAUSES[h.reason];
+    return {
+        id: h.id,
+        path: h.path,
+        reason: h.reason,
+        title: HOLD_TITLE,
+        cause: text.cause,
+        detail: text.detail,
+        since: h.since,
+        saves: h.saves,
+        hasTheirs,
+        actions,
+        reversible: !readOnly,
+        reversibleNote: readOnly ? "Copy before discarding." : "You can change your mind later: resolving is an ordinary change, and the previous version stays in the collection's history. Keep both if you want your version kept as a file as well.",
+        compareLink: canCompare ? holdCompareLink(o.collectionId, h.id) : null,
+    };
+}
+/** Banner text for a list of holds, or `null` when there are none. */
+export function holdNotice(holds) {
+    if (!holds.length)
+        return null;
+    if (holds.length === 1)
+        return `${HOLD_TITLE}: ${holds[0].path} is waiting for your choice.`;
+    return `${HOLD_TITLE}: ${holds.length} files are waiting for your choice.`;
+}
+/**
+ * The sync status line every client shows: "Confirmed through N, plus P pending, plus H
+ * held". Holds are never "stuck"; they are the user's pending choices.
+ */
+export function syncStatusText(s) {
+    const n = (count, word) => `${count} ${word}`;
+    const tail = `, plus ${n(s.pending, "pending")}, plus ${n(s.holds, "held")}`;
+    if (s.mode === "local_only")
+        return `Saved on this device${tail}`;
+    return `Confirmed through ${s.confirmedThrough}${tail}`;
+}
+//# sourceMappingURL=holds.js.map

package/dist/holds.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @mdbase-dev/sdk: the TS SDK for replicas
+ * (`docs/contracts/replica-client-api.md`).
+ *
+ * The root entry is the thin client (`./thin-client.js`) plus the application
+ * entry (`MdbaseConnect`, which validates the app's manifest declaration),
+ * people, timers, notifications, holds and error copy, and the in-browser runtime.
+ */
+export * from "./thin-client.js";
+export { MdbasePeopleClient, PERSON_CONTRACT, sameIdentity } from "./people.js";
+export type { AccountIdentity, AccountProfile, CurrentAccount, CollectionMemberProfile, PersonRecord, InvalidPersonRecord, PersonResolution, PeopleDirectory, PeopleRequestOptions, PeopleDirectoryOptions, PeopleAuthority } from "./people.js";
+export { TimersApi } from "./timers.js";
+export type { AppTimersPort, DesiredTimer, Timer, TimerRequestOptions, TimerReconcileInput, TimerList, TimerReconciliation, TimerCancellation, TimerChannelRegistration, TimerOperationIdentity, TimerRecoverableReconcileInput, TimerOperationReceipt, TimerOperationLookup, WebPushChannelOptions, FcmChannelOptions, } from "./timers.js";
+export { MDBASE_NOTIFICATION_TYPE, MDBASE_NOTIFICATION_CLICK, parseMdbasePush, parseMdbaseNativeNotification, readMdbaseNotificationData, showMdbaseNotification, handleMdbasePush, handleMdbaseNotificationClick, } from "./notifications.js";
+export type { MdbaseNotification, MdbaseNotificationPresentation, MdbaseNotificationClickMessage, MdbaseNotificationDisplayOptions, HandleMdbasePushOptions, HandleMdbaseNotificationClickOptions, } from "./notifications.js";
+export { inProcessConnector } from "./transport/inprocess.js";
+export type { InProcessConnectOptions, InProcessRuntime } from "./transport/inprocess.js";
+export { WasmRuntime } from "./runtime/wasm.js";
+export type { OpenConfig, QueryExecutionProfile, RuntimeInfo } from "./runtime/wasm.js";
+export { HOLD_COMPARE_SCHEME, HOLD_TITLE, describeHold, holdCompareLink, holdNotice, parseHoldCompareLink, syncStatusText } from "./holds.js";
+export type { DescribeHoldOptions, HoldAction, HoldActionOption, HoldPresentation } from "./holds.js";
+export { describeError, describeDiagnostic, problemCodeOf, PROBLEM_CODES, type ProblemCode, type DescribeErrorOptions, type MdbaseProblemMessages, type MdbaseErrorAction, type MdbaseErrorDescription, } from "./describe-error.js";
+export { parseVersion, compareVersions, versionRelation } from "./semver.js";
+export type { MdbaseVersion, MdbaseVersionRelation } from "./semver.js";
+export { applicationPhase, isReadyPhase, SLOW_OPENING_MS } from "./application/phase.js";
+export type { MdbasePhase, MdbasePhaseKind, MdbaseProblem, MdbaseCollectionSummary, MdbaseApprovalOutcome, ApplicationPhaseOptions as MdbasePhaseOptions } from "./application/phase.js";
+export { MdbaseConnect, MdbaseApplicationUnavailableError } from "./application/entry.js";
+export { createMdbase } from "./application/front-door.js";
+export type { Mdbase, MdbaseSnapshot, MdbaseSetupResult } from "./application/front-door.js";
+export { effectiveCapabilities } from "./application/capabilities.js";
+export type { MdbaseApplicationCapability, MdbaseApplicationCapabilities } from "./application/capabilities.js";
+export type { MdbaseApplicationEntry, MdbaseApplication, MdbaseApplicationConnection, MdbaseApplicationSnapshot, MdbaseApplicationRequestOptions, MdbaseCollectionDeleteOptions, MdbaseSignOutOptions, MdbaseConnectOptions, MdbaseSignInOpener, MdbaseApplicationFacet, MdbaseApplicationProblem, MdbaseApplicationAssessment, MdbaseUnavailableType, MdbaseApplicationFacetSnapshot, MdbaseApplicationReadinessSnapshot, MdbaseLinks } from "./application/entry.js";
+export type { MdbaseApplicationSetup, MdbaseSetupPlan, MdbaseSetupPlanOptions, MdbaseSetupRecord, MdbaseSetupChange, MdbaseSetupChangeKind, MdbaseSetupConflict, MdbaseSetupRefusalCode } from "./application/setup.js";
+export type { MdbaseAccessRequest, MdbaseAccessRequestOptions, MdbaseAccessResult } from "./application/file-access.js";
+export type { ApplicationCollectionSelectionSnapshot as MdbaseApplicationSelectionSnapshot, ApplicationCollectionSelectionState as MdbaseApplicationSelectionState } from "./application/collection-selection.js";
+export type { MdbaseApplicationDeclaration, ApplicationStorageDeclaration, ApplicationJson } from "./application/declaration.js";

package/dist/index.js

@@ -0,0 +1,22 @@
+/**
+ * @mdbase-dev/sdk: the TS SDK for replicas
+ * (`docs/contracts/replica-client-api.md`).
+ *
+ * The root entry is the thin client (`./thin-client.js`) plus the application
+ * entry (`MdbaseConnect`, which validates the app's manifest declaration),
+ * people, timers, notifications, holds and error copy, and the in-browser runtime.
+ */
+export * from "./thin-client.js";
+export { MdbasePeopleClient, PERSON_CONTRACT, sameIdentity } from "./people.js";
+export { TimersApi } from "./timers.js";
+export { MDBASE_NOTIFICATION_TYPE, MDBASE_NOTIFICATION_CLICK, parseMdbasePush, parseMdbaseNativeNotification, readMdbaseNotificationData, showMdbaseNotification, handleMdbasePush, handleMdbaseNotificationClick, } from "./notifications.js";
+export { inProcessConnector } from "./transport/inprocess.js";
+export { WasmRuntime } from "./runtime/wasm.js";
+export { HOLD_COMPARE_SCHEME, HOLD_TITLE, describeHold, holdCompareLink, holdNotice, parseHoldCompareLink, syncStatusText } from "./holds.js";
+export { describeError, describeDiagnostic, problemCodeOf, PROBLEM_CODES, } from "./describe-error.js";
+export { parseVersion, compareVersions, versionRelation } from "./semver.js";
+export { applicationPhase, isReadyPhase, SLOW_OPENING_MS } from "./application/phase.js";
+export { MdbaseConnect, MdbaseApplicationUnavailableError } from "./application/entry.js";
+export { createMdbase } from "./application/front-door.js";
+export { effectiveCapabilities } from "./application/capabilities.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;;;;;;;GAOG;AACH,cAAc,kBAAkB,CAAC;AACjC,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhF,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAOxC,OAAO,EACL,wBAAwB,EAAE,yBAAyB,EAAE,eAAe,EAAE,6BAA6B,EACnG,0BAA0B,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,6BAA6B,GACpG,MAAM,oBAAoB,CAAC;AAK5B,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAE9D,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD,OAAO,EAAE,mBAAmB,EAAE,UAAU,EAAE,YAAY,EAAE,eAAe,EAAE,UAAU,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE9I,OAAO,EACL,aAAa,EACb,kBAAkB,EAClB,aAAa,EACb,aAAa,GAMd,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE7E,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAEzF,OAAO,EAAC,aAAa,EAAC,iCAAiC,EAAC,MAAM,wBAAwB,CAAC;AACvF,OAAO,EAAC,YAAY,EAAC,MAAM,6BAA6B,CAAC;AAEzD,OAAO,EAAC,qBAAqB,EAAC,MAAM,+BAA+B,CAAC"}

package/dist/keys.d.ts

@@ -0,0 +1,40 @@
+import type { StaticKey } from "./transport/noise.js";
+export interface ClientKey extends StaticKey {
+    /** True when the private key can't be exported by page script. */
+    readonly nonExtractable: boolean;
+}
+/** What a key store persists for one key. CryptoKeys are structured-cloneable. */
+export type StoredKey = {
+    kind: "webcrypto";
+    privateKey: CryptoKey;
+    publicKey: Uint8Array;
+} | {
+    kind: "raw";
+    secretKey: Uint8Array;
+    publicKey: Uint8Array;
+};
+export interface KeyStorage {
+    get(name: string): Promise<StoredKey | undefined>;
+    put(name: string, key: StoredKey): Promise<void>;
+    /** Atomically keep the existing identity or commit this candidate. Persistent
+     * stores shared across contexts should implement this; no silent replacement. */
+    putIfAbsent?(name: string, key: StoredKey): Promise<StoredKey>;
+    delete(name: string): Promise<void>;
+}
+/** Keys in memory only (tests, short-lived scripts). */
+export declare function memoryKeyStorage(): KeyStorage;
+/** Keys in IndexedDB (browsers, extensions, Obsidian). */
+export declare function indexedDbKeyStorage(dbName?: string, storeName?: string): KeyStorage;
+export interface LoadKeyOptions {
+    /** Where keys live. Default: IndexedDB when available, else memory. */
+    storage?: KeyStorage;
+    /** Require non-extractable X25519 custody, including for existing keys. */
+    requireNonExtractable?: boolean;
+}
+/**
+ * Load one committed identity. Existing raw/extractable keys are never silently
+ * replaced when stricter custody is requested. Same-store creation coalesces;
+ * built-in IndexedDB also chooses one winner across contexts atomically.
+ * Custom shared persistent stores need putIfAbsent for cross-context safety.
+ */
+export declare function loadOrCreateClientKey(name: string, o?: LoadKeyOptions): Promise<ClientKey>;

package/dist/keys.js

@@ -0,0 +1,181 @@
+/**
+ * Client static keys (`replica-client-api.md` §12.3, "Keys for web apps").
+ *
+ * A browser app generates its X25519 static key once and registers the public key in
+ * its grant at consent time. Where the platform supports it, the private key is a
+ * **non-extractable WebCrypto key kept in IndexedDB**: page script can use it for the
+ * handshake but cannot read it out. Otherwise the raw key is kept in IndexedDB, scoped
+ * to the app's origin, and `nonExtractable` is false so the app can tell.
+ */
+import { x25519 } from "@noble/curves/ed25519.js";
+import { mdbaseError } from "./errors.js";
+/** Keys in memory only (tests, short-lived scripts). */
+export function memoryKeyStorage() {
+    const m = new Map();
+    return {
+        get: async (n) => m.get(n),
+        put: async (n, k) => void m.set(n, k),
+        putIfAbsent: async (n, k) => {
+            const existing = m.get(n);
+            if (existing)
+                return existing;
+            m.set(n, k);
+            return k;
+        },
+        delete: async (n) => void m.delete(n),
+    };
+}
+/** Keys in IndexedDB (browsers, extensions, Obsidian). */
+export function indexedDbKeyStorage(dbName = "mdbase-keys", storeName = "keys") {
+    const idb = globalThis.indexedDB;
+    if (!idb)
+        throw mdbaseError("invalid_request", "IndexedDB is not available here; pass another KeyStorage");
+    const open = () => new Promise((resolve, reject) => {
+        const req = idb.open(dbName, 1);
+        req.onupgradeneeded = () => req.result.createObjectStore(storeName);
+        req.onsuccess = () => resolve(req.result);
+        req.onerror = () => reject(req.error);
+    });
+    const transaction = async (mode, work) => {
+        const db = await open();
+        try {
+            return await new Promise((resolve, reject) => {
+                const t = db.transaction(storeName, mode);
+                let result;
+                let captured = false;
+                t.oncomplete = () => captured
+                    ? resolve(result)
+                    : reject(mdbaseError("unavailable", "key storage transaction completed without a result", "key_storage"));
+                t.onabort = () => reject(t.error ?? mdbaseError("unavailable", "key storage transaction aborted", "key_storage"));
+                t.onerror = () => reject(t.error ?? mdbaseError("unavailable", "key storage transaction failed", "key_storage"));
+                try {
+                    work(t.objectStore(storeName), value => { result = value; captured = true; });
+                }
+                catch (error) {
+                    t.abort();
+                    reject(error);
+                }
+            });
+        }
+        finally {
+            db.close();
+        }
+    };
+    const tx = (mode, fn) => transaction(mode, (s, capture) => {
+        const req = fn(s);
+        req.onsuccess = () => capture(req.result);
+    });
+    return {
+        get: (n) => tx("readonly", (s) => s.get(n)),
+        put: (n, k) => tx("readwrite", (s) => s.put(k, n)).then(() => { }),
+        putIfAbsent: (n, k) => transaction("readwrite", (s, capture) => {
+            const req = s.get(n);
+            req.onsuccess = () => {
+                if (req.result !== undefined) {
+                    capture(req.result);
+                    return;
+                }
+                try {
+                    const added = s.add(k, n);
+                    added.onsuccess = () => capture(k);
+                }
+                catch {
+                    s.transaction.abort();
+                }
+            };
+        }),
+        delete: (n) => tx("readwrite", (s) => s.delete(n)).then(() => { }),
+    };
+}
+function subtle() {
+    return globalThis.crypto?.subtle;
+}
+async function webCryptoX25519() {
+    const s = subtle();
+    if (!s)
+        return null;
+    try {
+        const pair = (await s.generateKey({ name: "X25519" }, false, ["deriveBits"]));
+        const pub = new Uint8Array(await s.exportKey("raw", pair.publicKey));
+        return { kind: "webcrypto", privateKey: pair.privateKey, publicKey: pub };
+    }
+    catch {
+        return null; // X25519 not supported by this engine
+    }
+}
+function toClientKey(k) {
+    if (k.kind === "raw") {
+        return {
+            publicKey: k.publicKey,
+            nonExtractable: false,
+            dh: (pk) => x25519.getSharedSecret(k.secretKey, pk),
+        };
+    }
+    return {
+        publicKey: k.publicKey,
+        nonExtractable: !k.privateKey.extractable,
+        dh: async (pk) => {
+            const s = subtle();
+            const pub = await s.importKey("raw", pk, { name: "X25519" }, false, []);
+            const bits = await s.deriveBits({ name: "X25519", public: pub }, k.privateKey, 256);
+            return new Uint8Array(bits);
+        },
+    };
+}
+const memoryDefault = memoryKeyStorage();
+const creating = new WeakMap();
+function requireCustody(k, required) {
+    if (required && (k.kind !== "webcrypto" || k.privateKey.extractable !== false ||
+        k.privateKey.type !== "private" || k.privateKey.algorithm.name !== "X25519" ||
+        !k.privateKey.usages.includes("deriveBits"))) {
+        throw mdbaseError("invalid_request", "a non-extractable X25519 key is required; explicitly reauthorize incompatible stored identities", "key_storage");
+    }
+}
+/**
+ * Load one committed identity. Existing raw/extractable keys are never silently
+ * replaced when stricter custody is requested. Same-store creation coalesces;
+ * built-in IndexedDB also chooses one winner across contexts atomically.
+ * Custom shared persistent stores need putIfAbsent for cross-context safety.
+ */
+export async function loadOrCreateClientKey(name, o = {}) {
+    const storage = o.storage ?? (globalThis.indexedDB ? indexedDbKeyStorage() : memoryDefault);
+    const required = o.requireNonExtractable;
+    let pending = creating.get(storage);
+    if (!pending) {
+        pending = new Map();
+        creating.set(storage, pending);
+    }
+    let work = pending.get(name);
+    if (!work) {
+        work = (async () => {
+            const existing = await storage.get(name);
+            if (existing)
+                return existing;
+            let k = await webCryptoX25519();
+            if (!k) {
+                if (required)
+                    throw mdbaseError("invalid_request", "this platform cannot keep a non-extractable X25519 key", "key_storage");
+                const secretKey = x25519.utils.randomSecretKey();
+                k = { kind: "raw", secretKey, publicKey: x25519.getPublicKey(secretKey) };
+            }
+            requireCustody(k, required);
+            if (storage.putIfAbsent)
+                return storage.putIfAbsent(name, k);
+            await storage.put(name, k);
+            return k;
+        })();
+        pending.set(name, work);
+    }
+    try {
+        const k = await work;
+        // Enforce each caller's captured requirement, including the existing/atomic
+        // winner and concurrent callers whose options differ from the creator's.
+        requireCustody(k, required);
+        return toClientKey(k);
+    }
+    finally {
+        if (pending.get(name) === work)
+            pending.delete(name);
+    }
+}
+//# sourceMappingURL=keys.js.map

package/dist/keys.js.map

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

package/dist/live.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Live query state (`replica-client-api.md` §4): the first push is a `snapshot`, then
+ * `diff`s; `reset` means "a new snapshot follows". Because updates describe state,
+ * applying them in order always gives the replica's current result.
+ */
+import type { QueryMetadata, QueryUpdate, RecordView, Uuid } from "./wire.js";
+export interface LiveQueryState {
+    /** The current result, in result order. */
+    readonly records: readonly RecordView[];
+    /** False while the replica installs a snapshot (rows may be missing). */
+    readonly complete: boolean;
+    /** Local view version of this result. */
+    readonly asOf: number;
+    /** Current full metadata at asOf; absent while stale or when not supplied. */
+    readonly metadata?: QueryMetadata | undefined;
+    /**
+     * True until the first snapshot, and between a `reset` (or a reconnect) and the
+     * next snapshot. The previous records stay visible meanwhile.
+     */
+    readonly stale: boolean;
+}
+export type LiveListener = (state: LiveQueryState, update: QueryUpdate | null) => void;
+/** Applies `query-update` pushes to an ordered record set. */
+export declare class LiveResult implements LiveQueryState {
+    private byId;
+    private order;
+    private cached;
+    complete: boolean;
+    asOf: number;
+    stale: boolean;
+    metadata: QueryMetadata | undefined;
+    get records(): readonly RecordView[];
+    get(id: Uuid): RecordView | undefined;
+    /** Mark stale (reconnect); records stay until the next snapshot replaces them. */
+    markStale(): void;
+    apply(u: QueryUpdate): void;
+    private reorder;
+}

package/dist/live.js

@@ -0,0 +1,82 @@
+/** Applies `query-update` pushes to an ordered record set. */
+export class LiveResult {
+    byId = new Map();
+    order = [];
+    cached = [];
+    complete = false;
+    asOf = 0;
+    stale = true;
+    metadata;
+    get records() {
+        return (this.cached ??= this.order.map((id) => this.byId.get(id)).filter(Boolean));
+    }
+    get(id) {
+        return this.byId.get(id);
+    }
+    /** Mark stale (reconnect); records stay until the next snapshot replaces them. */
+    markStale() {
+        this.stale = true;
+        this.metadata = undefined;
+    }
+    apply(u) {
+        switch (u.kind) {
+            case "reset":
+                this.stale = true;
+                break;
+            case "snapshot": {
+                this.byId.clear();
+                this.order = [];
+                for (const r of u.added ?? []) {
+                    if (!this.byId.has(r.id))
+                        this.order.push(r.id);
+                    this.byId.set(r.id, r);
+                }
+                if (u.order)
+                    this.reorder(u.order);
+                this.stale = false;
+                break;
+            }
+            case "diff": {
+                if (u.removed?.length) {
+                    const gone = new Set(u.removed);
+                    for (const id of gone)
+                        this.byId.delete(id);
+                    this.order = this.order.filter((id) => !gone.has(id));
+                }
+                for (const r of u.changed ?? []) {
+                    if (!this.byId.has(r.id))
+                        this.order.push(r.id);
+                    this.byId.set(r.id, r);
+                }
+                for (const r of u.added ?? []) {
+                    if (!this.byId.has(r.id))
+                        this.order.push(r.id);
+                    this.byId.set(r.id, r);
+                }
+                if (u.order)
+                    this.reorder(u.order);
+                break;
+            }
+        }
+        // Metadata is a full replacement at THIS update's asOf, never a delta.
+        // Reset/reconnect or omission must not present an older count/group as current.
+        this.metadata = u.kind === "reset" || this.stale ? undefined : u.metadata;
+        this.complete = u.complete;
+        this.asOf = u.asOf;
+        this.cached = null;
+    }
+    reorder(order) {
+        // The full ordered list. IDs we don't hold are skipped; rows missing from it keep
+        // their place at the end (they will be corrected by the next diff).
+        const seen = new Set();
+        const next = [];
+        for (const id of order)
+            if (this.byId.has(id) && !seen.has(id))
+                (seen.add(id), next.push(id));
+        for (const id of this.order)
+            if (!seen.has(id))
+                next.push(id);
+        this.order = next;
+    }
+}
+//# sourceMappingURL=live.js.map

package/dist/live.js.map

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

package/dist/local-build.d.ts

@@ -0,0 +1,13 @@
+/** Managed artifact literal. Only a signature-verified per-stack local build
+ * replaces this literal; never a runtime environment/config option. Thin-safe. */
+export declare const LOCAL_APPLICATION_BUILD: boolean;
+/** Transport admission only: never authenticates release context or authority.
+ * Kept behind the compiled literal so runtime flags cannot relax managed TLS. */
+export declare function localApplicationHttpOrigin(value: string): boolean;
+/** LAB loopback HTTP admission, only behind a caller's explicit LAB flag; local
+ * builds narrow it to {@link localApplicationHttpOrigin}. Not the native
+ * exception, which is canonical 127.0.0.1 only (`isNativeLoopbackOrigin`). */
+export declare function labLoopbackHttpOrigin(value: string): boolean;
+/** The relay's local equivalent of TLS; credentials still travel in the first
+ * frame, never in a URL. Managed relays continue to require wss. */
+export declare function localApplicationWebSocketUrl(value: string): boolean;

package/dist/local-build.js

@@ -0,0 +1,47 @@
+/** Managed artifact literal. Only a signature-verified per-stack local build
+ * replaces this literal; never a runtime environment/config option. Thin-safe. */
+export const LOCAL_APPLICATION_BUILD = false;
+/** Transport admission only: never authenticates release context or authority.
+ * Kept behind the compiled literal so runtime flags cannot relax managed TLS. */
+export function localApplicationHttpOrigin(value) {
+    if (!LOCAL_APPLICATION_BUILD)
+        return false;
+    try {
+        const url = new URL(value);
+        return url.protocol === "http:" && ["127.0.0.1", "localhost", "[::1]"].includes(url.hostname)
+            && Number(url.port) > 0 && url.origin === value && !url.username && !url.password;
+    }
+    catch {
+        return false;
+    }
+}
+/** LAB loopback HTTP admission, only behind a caller's explicit LAB flag; local
+ * builds narrow it to {@link localApplicationHttpOrigin}. Not the native
+ * exception, which is canonical 127.0.0.1 only (`isNativeLoopbackOrigin`). */
+export function labLoopbackHttpOrigin(value) {
+    if (LOCAL_APPLICATION_BUILD)
+        return localApplicationHttpOrigin(value);
+    try {
+        const url = new URL(value);
+        return url.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+    }
+    catch {
+        return false;
+    }
+}
+/** The relay's local equivalent of TLS; credentials still travel in the first
+ * frame, never in a URL. Managed relays continue to require wss. */
+export function localApplicationWebSocketUrl(value) {
+    if (!LOCAL_APPLICATION_BUILD)
+        return false;
+    try {
+        const url = new URL(value);
+        return url.protocol === "ws:" && !url.username && !url.password && !url.hash
+            && (url.origin === value || url.href === value)
+            && localApplicationHttpOrigin(`http://${url.host}`);
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=local-build.js.map

package/dist/local-build.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-build.js","sourceRoot":"","sources":["../src/local-build.ts"],"names":[],"mappings":"AAAA;kFACkF;AAClF,MAAM,CAAC,MAAM,uBAAuB,GAAY,KAAK,CAAC;AAEtD;iFACiF;AACjF,MAAM,UAAU,0BAA0B,CAAC,KAAa;IACtD,IAAI,CAAC,uBAAuB;QAAE,OAAO,KAAK,CAAC;IAC3C,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;QAC3B,OAAO,GAAG,CAAC,QAAQ,KAAK,OAAO,IAAI,CAAC,WAAW,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC;eACxF,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,MAAM,KAAK,KAAK,IAAI,CAAC,GAAG,CAAC,QAAQ,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC;IACtF,CAAC;IAAC,MAAM,CAAC;QAAC,OAAO,KAAK,CAAC;IAAC,CAAC;AAC3B,CAAC;AAED;;8EAE8E;AAC9E,MAAM,UAAU,qBAAqB,CAAC,KAAa;IACjD,IAAI,uBAAuB;QAAE,OAAO,0BAA0B,CAAC,KAAK,CAAC,CAAC;IACtE,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;QAC3B,OAAO,GAAG,CAAC,QAAQ,KAAK,OAAO,IAAI,CAAC,WAAW,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAChG,CAAC;IAAC,MAAM,CAAC;QAAC,OAAO,KAAK,CAAC;IAAC,CAAC;AAC3B,CAAC;AAED;oEACoE;AACpE,MAAM,UAAU,4BAA4B,CAAC,KAAa;IACxD,IAAI,CAAC,uBAAuB;QAAE,OAAO,KAAK,CAAC;IAC3C,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;QAC3B,OAAO,GAAG,CAAC,QAAQ,KAAK,KAAK,IAAI,CAAC,GAAG,CAAC,QAAQ,IAAI,CAAC,GAAG,CAAC,QAAQ,IAAI,CAAC,GAAG,CAAC,IAAI;eACvE,CAAC,GAAG,CAAC,MAAM,KAAK,KAAK,IAAI,GAAG,CAAC,IAAI,KAAK,KAAK,CAAC;eAC5C,0BAA0B,CAAC,UAAU,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;IACxD,CAAC;IAAC,MAAM,CAAC;QAAC,OAAO,KAAK,CAAC;IAAC,CAAC;AAC3B,CAAC"}