@lightninglabs/wavelength-core 0.1.0

package/dist/engine/poller.d.ts

@@ -0,0 +1,20 @@
+/**
+ * A fixed-interval async poll with an optional consecutive-failure budget.
+ * The sync poll and the restore readiness poll are both instances of this.
+ */
+export declare class Poller {
+    #private;
+    constructor(opts: {
+        intervalMs: number;
+        /** Run one tick immediately on start, before the first interval. */
+        immediate?: boolean;
+        /** Consecutive rejected ticks before the poll gives up. Unset means never. */
+        failureLimit?: number;
+        tick: () => Promise<void>;
+        onExhausted?: (error: unknown) => void;
+    });
+    get running(): boolean;
+    start(): void;
+    stop(): void;
+}
+//# sourceMappingURL=poller.d.ts.map

package/dist/engine/poller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"poller.d.ts","sourceRoot":"","sources":["../../src/engine/poller.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,qBAAa,MAAM;;gBAcL,IAAI,EAAE;QAChB,UAAU,EAAE,MAAM,CAAC;QACnB,oEAAoE;QACpE,SAAS,CAAC,EAAE,OAAO,CAAC;QACpB,8EAA8E;QAC9E,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;QAC1B,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;KACxC;IAID,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,KAAK,IAAI,IAAI;IAWb,IAAI,IAAI,IAAI;CAwBb"}

package/dist/engine/poller.js

@@ -0,0 +1,51 @@
+/**
+ * A fixed-interval async poll with an optional consecutive-failure budget.
+ * The sync poll and the restore readiness poll are both instances of this.
+ */
+export class Poller {
+    #timer;
+    #failures = 0;
+    #inFlight = false;
+    #opts;
+    constructor(opts) {
+        this.#opts = opts;
+    }
+    get running() {
+        return this.#timer !== undefined;
+    }
+    start() {
+        if (this.#timer) {
+            return;
+        }
+        this.#failures = 0;
+        this.#timer = setInterval(() => void this.#tick(), this.#opts.intervalMs);
+        if (this.#opts.immediate) {
+            void this.#tick();
+        }
+    }
+    stop() {
+        clearInterval(this.#timer);
+        this.#timer = undefined;
+    }
+    async #tick() {
+        // A tick slower than the interval must not stack up behind itself.
+        if (this.#inFlight || !this.#timer) {
+            return;
+        }
+        this.#inFlight = true;
+        try {
+            await this.#opts.tick();
+            this.#failures = 0;
+        }
+        catch (err) {
+            this.#failures += 1;
+            if (this.#opts.failureLimit && this.#failures >= this.#opts.failureLimit) {
+                this.stop();
+                this.#opts.onExhausted?.(err);
+            }
+        }
+        finally {
+            this.#inFlight = false;
+        }
+    }
+}

package/dist/engine/reconcile.d.ts

@@ -0,0 +1,36 @@
+import type { Balance } from '../results.ts';
+/**
+ * Whether two balance snapshots carry the same figures. The settle reconcile
+ * uses it to decide when a post-activity re-read has caught up: once the
+ * balance stops changing across reads there is nothing left to reconcile.
+ */
+export declare function balancesEqual(a: Balance | null, b: Balance | null): boolean;
+/** The outcome of one serialized background refresh; never a rejection. */
+export type BackgroundRefreshResult = {
+    ok: boolean;
+    balance: Balance | null;
+};
+type SettleReconcilerOptions = {
+    refresh: () => Promise<BackgroundRefreshResult>;
+    baseline: () => Balance | null;
+};
+/**
+ * Balance can lag the activity event that announced a settled entry: the
+ * daemon may report the entry complete a beat before balance() reflects the
+ * new funds. A single refresh would then capture a stale balance and, with no
+ * polling while ready, leave it stale until a manual refresh. Each activity
+ * event triggers a cycle: one refresh, then bounded re-reads that stop only
+ * once the balance has moved off the pre-event baseline and then held steady.
+ * Equality of two consecutive reads alone cannot distinguish settled from
+ * still-lagging, so when the balance never moves the whole bounded schedule
+ * is probed. A failed refresh deliberately ends the cycle rather than continuing
+ * the probe schedule; the next activity event or manual refresh converges it.
+ */
+export declare class SettleReconciler {
+    #private;
+    constructor(opts: SettleReconcilerOptions);
+    trigger(): void;
+    cancel(): void;
+}
+export {};
+//# sourceMappingURL=reconcile.d.ts.map

package/dist/engine/reconcile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconcile.d.ts","sourceRoot":"","sources":["../../src/engine/reconcile.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAG7C;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,OAAO,GAAG,IAAI,EAAE,CAAC,EAAE,OAAO,GAAG,IAAI,GAAG,OAAO,CAe3E;AAED,2EAA2E;AAC3E,MAAM,MAAM,uBAAuB,GAAG;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAA;CAAE,CAAC;AAE/E,KAAK,uBAAuB,GAAG;IAC7B,OAAO,EAAE,MAAM,OAAO,CAAC,uBAAuB,CAAC,CAAC;IAChD,QAAQ,EAAE,MAAM,OAAO,GAAG,IAAI,CAAC;CAChC,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,qBAAa,gBAAgB;;gBAQf,IAAI,EAAE,uBAAuB;IAIzC,OAAO,IAAI,IAAI;IAaf,MAAM,IAAI,IAAI;CA+Bf"}

package/dist/engine/reconcile.js

@@ -0,0 +1,81 @@
+import { SETTLE_RECONCILE_DELAYS_MS } from "./constants.js";
+/**
+ * Whether two balance snapshots carry the same figures. The settle reconcile
+ * uses it to decide when a post-activity re-read has caught up: once the
+ * balance stops changing across reads there is nothing left to reconcile.
+ */
+export function balancesEqual(a, b) {
+    if (a === b) {
+        return true;
+    }
+    if (!a || !b) {
+        return false;
+    }
+    const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+    for (const key of keys) {
+        if (a[key] !== b[key]) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Balance can lag the activity event that announced a settled entry: the
+ * daemon may report the entry complete a beat before balance() reflects the
+ * new funds. A single refresh would then capture a stale balance and, with no
+ * polling while ready, leave it stale until a manual refresh. Each activity
+ * event triggers a cycle: one refresh, then bounded re-reads that stop only
+ * once the balance has moved off the pre-event baseline and then held steady.
+ * Equality of two consecutive reads alone cannot distinguish settled from
+ * still-lagging, so when the balance never moves the whole bounded schedule
+ * is probed. A failed refresh deliberately ends the cycle rather than continuing
+ * the probe schedule; the next activity event or manual refresh converges it.
+ */
+export class SettleReconciler {
+    // Monotonic id for the current cycle. Every trigger bumps it, retiring any
+    // cycle still in flight: clearing the timer alone would only cancel a
+    // scheduled probe, not a refresh already in flight.
+    #generation = 0;
+    #timer;
+    #opts;
+    constructor(opts) {
+        this.#opts = opts;
+    }
+    trigger() {
+        this.#generation += 1;
+        const gen = this.#generation;
+        clearTimeout(this.#timer);
+        const baseline = this.#opts.baseline();
+        void this.#opts.refresh().then((first) => {
+            if (gen !== this.#generation || !first.ok) {
+                return;
+            }
+            this.#probe(0, gen, baseline, first.balance);
+        });
+    }
+    cancel() {
+        this.#generation += 1;
+        clearTimeout(this.#timer);
+    }
+    #probe(attempt, gen, baseline, prev) {
+        if (attempt >= SETTLE_RECONCILE_DELAYS_MS.length) {
+            return;
+        }
+        this.#timer = setTimeout(() => {
+            if (gen !== this.#generation) {
+                return;
+            }
+            void this.#opts.refresh().then((res) => {
+                if (gen !== this.#generation || !res.ok) {
+                    return;
+                }
+                const moved = !balancesEqual(baseline, res.balance);
+                const steady = balancesEqual(prev, res.balance);
+                if (moved && steady) {
+                    return;
+                }
+                this.#probe(attempt + 1, gen, baseline, res.balance);
+            });
+        }, SETTLE_RECONCILE_DELAYS_MS[attempt]);
+    }
+}

package/dist/engine/snapshot.d.ts

@@ -0,0 +1,58 @@
+import type { Balance, CreateWalletResult, Entry } from '../results.ts';
+import type { WalletInfo, RuntimePhase } from '../state.ts';
+import type { WavelengthLogPayload } from '../events.ts';
+/**
+ * The state of a background wallet recovery started by restoreWallet, a
+ * discriminated union keyed on `status`: `idle` before any tracked restore
+ * (and after acknowledgeRecovery); `restoring` while the daemon's
+ * server-assisted scan runs; `done` once it completes (carrying the scan's
+ * result counters); `failed` if either the background scan errored on an
+ * already-usable wallet, or the restore itself failed before the wallet came
+ * up at all. In the first case the wallet is still usable and its state just
+ * may be incomplete; in the second the phase falls back to needsWallet, so
+ * read the phase alongside recovery.status to disambiguate. Read it to drive
+ * a "restoring your balance and history" banner, or a failure banner, across
+ * a possible component unmount (the phase and recovery state live in the
+ * snapshot, not hook-local state).
+ */
+export type RecoveryState = {
+    readonly status: 'idle';
+} | {
+    readonly status: 'restoring';
+} | {
+    readonly status: 'done';
+    readonly result: CreateWalletResult;
+} | {
+    readonly status: 'failed';
+    readonly error: Error;
+    /**
+     * True when the recovery scan failed on an already-usable wallet: the
+     * wallet works, but its state may be incomplete. False when the
+     * restore failed before the wallet came up.
+     */
+    readonly walletUsable: boolean;
+};
+/**
+ * The engine's immutable state snapshot. A new object per change; refresh fetches
+ * that changed nothing keep the previous field references, so consumers can
+ * cheaply compare slices with Object.is.
+ */
+export type WalletSnapshot = {
+    /** The current runtime/wallet lifecycle phase. */
+    readonly phase: RuntimePhase;
+    /** The last fatal runtime-level error, or null. */
+    readonly error: Error | null;
+    /** The most recent complete wallet info, or null before the runtime reports it. */
+    readonly info: WalletInfo | null;
+    /** The most recent wallet balance, or null before it is known. */
+    readonly balance: Balance | null;
+    /** The most recent activity entries, newest-first as returned by the daemon. */
+    readonly activity: readonly Entry[];
+    /** The background recovery status set by restoreWallet. */
+    readonly recovery: RecoveryState;
+    /** A bounded tail of 'log' events from the runtime, newest last. */
+    readonly logs: readonly WavelengthLogPayload[];
+};
+/** The snapshot every engine starts from. */
+export declare const INITIAL_SNAPSHOT: WalletSnapshot;
+//# sourceMappingURL=snapshot.d.ts.map

package/dist/engine/snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.d.ts","sourceRoot":"","sources":["../../src/engine/snapshot.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,kBAAkB,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AACxE,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAEzD;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,aAAa,GACrB;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC3B;IAAE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;CAAE,GAChC;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAA;CAAE,GAChE;IACE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;CAChC,CAAC;AAEN;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,kDAAkD;IAClD,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,mDAAmD;IACnD,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAC7B,mFAAmF;IACnF,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,CAAC;IACjC,kEAAkE;IAClE,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACjC,gFAAgF;IAChF,QAAQ,CAAC,QAAQ,EAAE,SAAS,KAAK,EAAE,CAAC;IACpC,2DAA2D;IAC3D,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,oEAAoE;IACpE,QAAQ,CAAC,IAAI,EAAE,SAAS,oBAAoB,EAAE,CAAC;CAChD,CAAC;AAEF,6CAA6C;AAC7C,eAAO,MAAM,gBAAgB,EAAE,cAQ7B,CAAC"}

package/dist/engine/snapshot.js

@@ -0,0 +1,10 @@
+/** The snapshot every engine starts from. */
+export const INITIAL_SNAPSHOT = Object.freeze({
+    phase: 'loading',
+    error: null,
+    info: null,
+    balance: null,
+    activity: [],
+    recovery: { status: 'idle' },
+    logs: [],
+});

package/dist/engine/stabilize.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Returns `prev` when `next` encodes to the same JSON, so refresh fetches that
+ * changed nothing keep the previous object identity and Object.is-based
+ * subscribers (useSyncExternalStore) skip the re-render. JSON comparison is
+ * acceptable at these payload sizes (activity is a bounded page).
+ */
+export declare function stabilize<T>(prev: T, next: T): T;
+//# sourceMappingURL=stabilize.d.ts.map

package/dist/engine/stabilize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stabilize.d.ts","sourceRoot":"","sources":["../../src/engine/stabilize.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,CAShD"}

package/dist/engine/stabilize.js

@@ -0,0 +1,17 @@
+/**
+ * Returns `prev` when `next` encodes to the same JSON, so refresh fetches that
+ * changed nothing keep the previous object identity and Object.is-based
+ * subscribers (useSyncExternalStore) skip the re-render. JSON comparison is
+ * acceptable at these payload sizes (activity is a bounded page).
+ */
+export function stabilize(prev, next) {
+    if (prev === next || prev == null || next == null) {
+        return next;
+    }
+    try {
+        return JSON.stringify(prev) === JSON.stringify(next) ? prev : next;
+    }
+    catch {
+        return next;
+    }
+}

package/dist/engine/store.d.ts

@@ -0,0 +1,21 @@
+import { type WalletSnapshot } from './snapshot.ts';
+/**
+ * A minimal immutable snapshot holder: getSnapshot/subscribe for consumers
+ * (React's useSyncExternalStore contract) and update(patch) for the engine.
+ * getSnapshot and subscribe are arrow-function properties so their identities
+ * are stable across the engine's lifetime.
+ */
+export declare class SnapshotStore {
+    #private;
+    getSnapshot: () => WalletSnapshot;
+    subscribe: (listener: () => void) => (() => void);
+    /**
+     * Shallow-merges the patch into a fresh snapshot and notifies listeners.
+     * Skips the allocation and the notification entirely when every key in the
+     * patch is already Object.is-equal to the current value: a no-op patch
+     * would otherwise still mint a new snapshot object and fire every
+     * subscriber for nothing.
+     */
+    update(patch: Partial<WalletSnapshot>): void;
+}
+//# sourceMappingURL=store.d.ts.map

package/dist/engine/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/engine/store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AAEtE;;;;;GAKG;AACH,qBAAa,aAAa;;IAIxB,WAAW,QAAO,cAAc,CAAmB;IAEnD,SAAS,GAAI,UAAU,MAAM,IAAI,KAAG,CAAC,MAAM,IAAI,CAAC,CAM9C;IAEF;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,cAAc,CAAC,GAAG,IAAI;CAoB7C"}

package/dist/engine/store.js

@@ -0,0 +1,46 @@
+import { INITIAL_SNAPSHOT } from "./snapshot.js";
+/**
+ * A minimal immutable snapshot holder: getSnapshot/subscribe for consumers
+ * (React's useSyncExternalStore contract) and update(patch) for the engine.
+ * getSnapshot and subscribe are arrow-function properties so their identities
+ * are stable across the engine's lifetime.
+ */
+export class SnapshotStore {
+    #snapshot = INITIAL_SNAPSHOT;
+    #listeners = new Set();
+    getSnapshot = () => this.#snapshot;
+    subscribe = (listener) => {
+        this.#listeners.add(listener);
+        return () => {
+            this.#listeners.delete(listener);
+        };
+    };
+    /**
+     * Shallow-merges the patch into a fresh snapshot and notifies listeners.
+     * Skips the allocation and the notification entirely when every key in the
+     * patch is already Object.is-equal to the current value: a no-op patch
+     * would otherwise still mint a new snapshot object and fire every
+     * subscriber for nothing.
+     */
+    update(patch) {
+        let changed = false;
+        for (const key in patch) {
+            if (!Object.is(this.#snapshot[key], patch[key])) {
+                changed = true;
+                break;
+            }
+        }
+        if (!changed) {
+            return;
+        }
+        this.#snapshot = { ...this.#snapshot, ...patch };
+        for (const listener of [...this.#listeners]) {
+            try {
+                listener();
+            }
+            catch {
+                // A throwing listener must not break the store or other listeners.
+            }
+        }
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,55 @@
+/**
+ * A stable, machine-readable classification on {@link WavelengthError} so consumers
+ * can branch without string-matching the message. The SDK's own failures use the
+ * named codes; daemon-originated errors currently fall back to `'wavelength_error'`
+ * (a richer daemon-code mapping is planned). The `(string & {})` arm keeps the
+ * union open for forward compatibility while still offering autocomplete on the
+ * known codes.
+ */
+export type WavelengthErrorCode = 'wavelength_error' | 'runtime_not_ready' | 'asset_load_failed' | 'worker_error' | 'unsupported_facade_method' | 'invalid_cursor' | 'invalid_config' | (string & {});
+/**
+ * The error type thrown by the SDK. Carries a machine-readable {@link code} so
+ * consumers can branch without string-matching the message.
+ */
+export declare class WavelengthError extends Error {
+    /** The machine-readable error classification. */
+    readonly code: WavelengthErrorCode;
+    /**
+     * @param message - The human-readable error message.
+     * @param code - The machine-readable error classification; defaults to `'wavelength_error'`.
+     * @param options - Standard error options; pass `{ cause }` to retain the underlying error for debugging.
+     */
+    constructor(message: string, code?: WavelengthErrorCode, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Extracts a human-readable message from an unknown thrown value. Tries in order:
+ * an Error's message, a string value as-is, a .message property on plain objects,
+ * and finally JSON serialization of anything else.
+ */
+export declare function errorMessage(err: unknown): string;
+/**
+ * Thrown by passkey ceremonies when the user dismisses the OS prompt, so hosts
+ * can suppress cancellation copy without string matching. The React binding's
+ * useWalletPasskey rethrows it without recording it as an error.
+ */
+export declare class PasskeyCancelledError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Reports whether `err` is a passkey cancellation. Checks `instanceof
+ * PasskeyCancelledError` first, then falls back to matching `err.name` on any
+ * Error: a duplicate copy of core (a second bundled instance of this package,
+ * for example one pulled in by a transport with its own dependency graph)
+ * produces a `PasskeyCancelledError` that fails `instanceof` across the
+ * bundle boundary even though it is functionally the same error, and the name
+ * check still recognizes it.
+ */
+export declare function isPasskeyCancelled(err: unknown): boolean;
+/**
+ * Normalizes an unknown thrown value to an Error, preserving an existing
+ * instance (and therefore its stack and cause) unchanged.
+ */
+export declare function toError(value: unknown): Error;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,MAAM,mBAAmB,GAC3B,kBAAkB,GAClB,mBAAmB,GACnB,mBAAmB,GACnB,cAAc,GACd,2BAA2B,GAC3B,gBAAgB,GAChB,gBAAgB,GAChB,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAElB;;;GAGG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACxC,iDAAiD;IACjD,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IAEnC;;;;OAIG;gBAED,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,mBAAwC,EAC9C,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAShC;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CA0BjD;AAED;;;;GAIG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;gBAClC,OAAO,SAAmC;CAIvD;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAExD;AAED;;;GAGG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAE7C"}

package/dist/errors.js

@@ -0,0 +1,80 @@
+/**
+ * The error type thrown by the SDK. Carries a machine-readable {@link code} so
+ * consumers can branch without string-matching the message.
+ */
+export class WavelengthError extends Error {
+    /** The machine-readable error classification. */
+    code;
+    /**
+     * @param message - The human-readable error message.
+     * @param code - The machine-readable error classification; defaults to `'wavelength_error'`.
+     * @param options - Standard error options; pass `{ cause }` to retain the underlying error for debugging.
+     */
+    constructor(message, code = 'wavelength_error', options) {
+        super(message, options);
+        this.name = 'WavelengthError';
+        // Assigned explicitly rather than via a constructor parameter property,
+        // which node's strip-only TypeScript loader (used by the unit tests) does
+        // not support.
+        this.code = code;
+    }
+}
+/**
+ * Extracts a human-readable message from an unknown thrown value. Tries in order:
+ * an Error's message, a string value as-is, a .message property on plain objects,
+ * and finally JSON serialization of anything else.
+ */
+export function errorMessage(err) {
+    if (err instanceof Error && err.message) {
+        return err.message;
+    }
+    if (typeof err === 'string') {
+        return err;
+    }
+    // Duck-typed error-like objects from across serialization boundaries read
+    // better as their message than as JSON.
+    if (err !== null &&
+        typeof err === 'object' &&
+        'message' in err &&
+        typeof err.message === 'string') {
+        return err.message;
+    }
+    try {
+        return JSON.stringify(err);
+    }
+    catch {
+        // JSON.stringify throws on circular structures or BigInt; fall back to a
+        // plain string so the error path never throws a new error.
+        return String(err);
+    }
+}
+/**
+ * Thrown by passkey ceremonies when the user dismisses the OS prompt, so hosts
+ * can suppress cancellation copy without string matching. The React binding's
+ * useWalletPasskey rethrows it without recording it as an error.
+ */
+export class PasskeyCancelledError extends Error {
+    constructor(message = 'passkey ceremony was cancelled') {
+        super(message);
+        this.name = 'PasskeyCancelledError';
+    }
+}
+/**
+ * Reports whether `err` is a passkey cancellation. Checks `instanceof
+ * PasskeyCancelledError` first, then falls back to matching `err.name` on any
+ * Error: a duplicate copy of core (a second bundled instance of this package,
+ * for example one pulled in by a transport with its own dependency graph)
+ * produces a `PasskeyCancelledError` that fails `instanceof` across the
+ * bundle boundary even though it is functionally the same error, and the name
+ * check still recognizes it.
+ */
+export function isPasskeyCancelled(err) {
+    return err instanceof PasskeyCancelledError || (err instanceof Error && err.name === 'PasskeyCancelledError');
+}
+/**
+ * Normalizes an unknown thrown value to an Error, preserving an existing
+ * instance (and therefore its stack and cause) unchanged.
+ */
+export function toError(value) {
+    return value instanceof Error ? value : new Error(errorMessage(value));
+}

package/dist/events.d.ts

@@ -0,0 +1,62 @@
+import type { Entry } from './generated.ts';
+/**
+ * The severity of a `'log'` event emitted by the runtime.
+ */
+export type WavelengthLogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * The payload carried by a `'log'` event.
+ */
+export type WavelengthLogPayload = {
+    /** The severity of the log line. */
+    level: WavelengthLogLevel;
+    /** The human-readable log message. */
+    message: string;
+};
+/**
+ * Whether an activity stream that the consumer did not close ended without an
+ * error ('ended') or failed with one ('failed'). A client-initiated close
+ * emits no event at all.
+ */
+export type ActivityStreamState = 'ended' | 'failed';
+/**
+ * The payload carried by an `'activityStream'` event. `message` is present
+ * exactly when the stream failed, so narrowing on `state` yields it without a
+ * null check.
+ */
+export type ActivityStreamPayload = {
+    state: 'ended';
+} | {
+    state: 'failed';
+    message: string;
+};
+/**
+ * The discriminated union of runtime events delivered to subscribers. Narrow on
+ * `type` to read the payload: `'activity'` carries the changed {@link Entry},
+ * `'log'` carries a level and message, and the lifecycle events
+ * (`'runtimeReady'`, `'runtimeStopped'`) carry none. `'activityStream'` reports
+ * that the activity subscription ended or failed for a reason the consumer did
+ * not initiate.
+ */
+export type WavelengthEvent = {
+    type: 'runtimeReady';
+} | {
+    type: 'runtimeStopped';
+} | {
+    type: 'activity';
+    payload: Entry;
+} | {
+    type: 'activityStream';
+    payload: ActivityStreamPayload;
+} | {
+    type: 'log';
+    payload: WavelengthLogPayload;
+};
+/**
+ * The set of {@link WavelengthEvent} discriminants.
+ */
+export type WavelengthEventType = WavelengthEvent['type'];
+/**
+ * A subscriber callback invoked with each {@link WavelengthEvent}.
+ */
+export type WavelengthListener = (event: WavelengthEvent) => void;
+//# sourceMappingURL=events.d.ts.map

package/dist/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAE5C;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAErE;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,oCAAoC;IACpC,KAAK,EAAE,kBAAkB,CAAC;IAC1B,sCAAsC;IACtC,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG,OAAO,GAAG,QAAQ,CAAC;AAErD;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAC7B;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,GAClB;IAAE,KAAK,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzC;;;;;;;GAOG;AACH,MAAM,MAAM,eAAe,GACvB;IAAE,IAAI,EAAE,cAAc,CAAA;CAAE,GACxB;IAAE,IAAI,EAAE,gBAAgB,CAAA;CAAE,GAC1B;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,KAAK,CAAA;CAAE,GACpC;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,OAAO,EAAE,qBAAqB,CAAA;CAAE,GAC1D;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,oBAAoB,CAAA;CAAE,CAAC;AAEnD;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;AAE1D;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAC"}

package/dist/events.js

@@ -0,0 +1 @@
+export {};