@lightninglabs/wavelength-core 0.1.0 → 0.1.1-rc2

package/README.md

@@ -7,8 +7,9 @@ and no inbound liquidity to manage, while their keys stay on their own device.
 
 This package is transport- and framework-agnostic. It carries the
 `WavelengthClient` interface, the request/response types, `RuntimeConfig` and
-its per-network endpoint defaults, the errors and enums, and the generated
-daemon types. It has no DOM and no transport of its own.
+its per-network endpoint defaults, the errors and enums, the generated daemon
+types, and the `WalletEngine` that the framework bindings build on. It has no
+DOM and no transport of its own.
 
 You usually don't install this package directly. Each transport re-exports
 everything here, so an app imports the client and its types from one place:
@@ -16,6 +17,8 @@ everything here, so an app imports the client and its types from one place:
 - [`@lightninglabs/wavelength-web`](https://www.npmjs.com/package/@lightninglabs/wavelength-web) for the browser (WebAssembly).
 - [`@lightninglabs/wavelength-react-native`](https://www.npmjs.com/package/@lightninglabs/wavelength-react-native) for React Native.
 
+## Install
+
 Install it on its own only when you need the types or the client contract
 without a transport, for example in shared code:
 
@@ -23,6 +26,8 @@ without a transport, for example in shared code:
 npm install @lightninglabs/wavelength-core
 ```
 
+## Use
+
 ```ts
 import type { WavelengthClient, RuntimeConfig } from "@lightninglabs/wavelength-core";
 ```

package/dist/base-client.d.ts

@@ -17,6 +17,7 @@ import { type ActivityStreamOptions } from './activity-options.ts';
  * normalization remain separate synchronization points.
  */
 export declare abstract class BaseWavelengthClient implements WavelengthClient {
+    #private;
     protected readonly listeners: Set<WavelengthListener>;
     abstract ready(): Promise<void>;
     protected abstract invokeFacade<T = unknown>(method: FacadeMethod, params?: unknown): Promise<T>;
@@ -25,10 +26,45 @@ export declare abstract class BaseWavelengthClient implements WavelengthClient {
     /** How this transport's daemon dials the Ark and swap servers. */
     protected abstract readonly serverTransport: ServerTransport;
     callFacade<T = unknown>(method: FacadeMethod, params?: unknown): Promise<T>;
+    protected callFacadeInternal<T = unknown>(method: FacadeMethod, params?: unknown): Promise<T>;
     isRunning(): Promise<boolean>;
     startActivity(opts?: ActivityStreamOptions): Promise<void>;
+    /**
+     * Runs a runtime lifecycle operation serialized against every other one on
+     * this client, in invocation order. A transport that owns an exclusive
+     * resource for the daemon's lifetime (the web transport's cross-tab runtime
+     * lock) routes its start()/stop() through this so overlapping host calls
+     * cannot interleave: two starts cannot share one lock lease, and a stop cannot
+     * release the lock while a start is still opening the databases. A failed
+     * operation does not poison the queue for the next caller.
+     */
+    protected enqueueLifecycle<T>(op: () => Promise<T>): Promise<T>;
     start(config: RuntimeConfig): Promise<WalletInfo>;
     stop(): Promise<void>;
+    /**
+     * Called at the very start of a stop, before the daemon RPC, so a transport
+     * can capture whatever identifies the session being stopped (the web
+     * transport's runtime-lock lease). The value is handed back to
+     * {@link afterDaemonStopped}. Default: nothing to capture.
+     */
+    protected beforeDaemonStop(): unknown;
+    /**
+     * Called once the daemon has acknowledged a stop and before subscribers are
+     * told about it. A transport holding an exclusive resource for the daemon's
+     * lifetime (the web transport's cross-tab runtime lock, say) releases it
+     * here: the acknowledgement is the proof the daemon let its storage go, and
+     * running before the event means a subscriber that restarts the runtime
+     * cannot race the release. Not called when the stop call fails, because an
+     * unacknowledged stop is no evidence the daemon is down.
+     *
+     * Receives the token {@link beforeDaemonStop} captured, so the release can be
+     * scoped to the session this stop belongs to and a stop whose start has
+     * already been superseded frees nothing. Awaited, so a transport whose
+     * release only completes asynchronously (the Web Locks API frees a lock when
+     * the holder's promise settles, not when it is asked to) can resolve once the
+     * resource is genuinely free.
+     */
+    protected afterDaemonStopped(_token?: unknown): void | Promise<void>;
     getInfo(): Promise<WalletInfo>;
     status(): Promise<WalletStatus>;
     balance(): Promise<Balance>;

package/dist/base-client.d.ts.map

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

package/dist/base-client.js

@@ -1,6 +1,6 @@
 import { validateRuntimeConfig } from "./config.js";
 import { assertFacadeMethod, toGoCreateWalletReq, toGoUnlockWalletReq, toMobileConfig, } from "./facade.js";
-import { errorMessage } from "./errors.js";
+import { WavelengthError, errorMessage } from "./errors.js";
 import { normalizeEntry, normalizeFacadeResult, } from "./response-normalization.js";
 import { validateActivityStreamOptions, } from "./activity-options.js";
 /**
@@ -14,7 +14,28 @@ import { validateActivityStreamOptions, } from "./activity-options.js";
  */
 export class BaseWavelengthClient {
     listeners = new Set();
+    // Serializes runtime lifecycle operations for transports that route start and
+    // stop through enqueueLifecycle, so a host's overlapping calls (a double
+    // click, a stop issued mid-start) run one at a time in invocation order
+    // instead of interleaving at the transport's exclusive resources.
+    #lifecycleTail = Promise.resolve();
+    // The raw facade escape hatch. It rejects the lifecycle verbs 'start' and
+    // 'stop' so they can only run through the typed start()/stop(): those are
+    // where the web transports take and release the cross-tab runtime lock, and a
+    // raw call would bypass it. The typed methods dispatch through
+    // callFacadeInternal, which carries no such guard.
     async callFacade(method, params = {}) {
+        if (method === 'start' || method === 'stop') {
+            throw new WavelengthError(`Call ${method}() instead of callFacade('${method}'): the ${method} ` +
+                'lifecycle verb runs through the typed method, which manages the ' +
+                'cross-tab runtime lock.');
+        }
+        return this.callFacadeInternal(method, params);
+    }
+    // The unguarded facade dispatch behind callFacade. The typed lifecycle verbs
+    // (start/stop) call this directly so callFacade's guard does not reject the
+    // very verbs they exist to issue.
+    async callFacadeInternal(method, params = {}) {
         assertFacadeMethod(method);
         const raw = await this.invokeFacade(method, params);
         return normalizeFacadeResult(method, raw);
@@ -26,19 +47,65 @@ export class BaseWavelengthClient {
         validateActivityStreamOptions(opts);
         await this.openActivityStream(opts);
     }
+    /**
+     * Runs a runtime lifecycle operation serialized against every other one on
+     * this client, in invocation order. A transport that owns an exclusive
+     * resource for the daemon's lifetime (the web transport's cross-tab runtime
+     * lock) routes its start()/stop() through this so overlapping host calls
+     * cannot interleave: two starts cannot share one lock lease, and a stop cannot
+     * release the lock while a start is still opening the databases. A failed
+     * operation does not poison the queue for the next caller.
+     */
+    enqueueLifecycle(op) {
+        const run = this.#lifecycleTail.then(op, op);
+        // The tail tracks only completion, never the value or a rejection.
+        this.#lifecycleTail = run.then(() => undefined, () => undefined);
+        return run;
+    }
     // start boots the embedded daemon and returns the post-boot WalletInfo. The
     // facade's start verb resolves nothing useful on its own, so the client
     // fetches getInfo afterwards; the React provider derives the runtime phase
     // from it.
     async start(config) {
         validateRuntimeConfig(config, this.serverTransport);
-        await this.callFacade('start', toMobileConfig(config, this.serverTransport));
+        await this.callFacadeInternal('start', toMobileConfig(config, this.serverTransport));
         return this.getInfo();
     }
     async stop() {
-        await this.callFacade('stop');
+        // Snapshot any per-session teardown token before the stop is issued, so
+        // afterDaemonStopped acts on the session this stop belongs to even if a new
+        // start takes over while the stop RPC is in flight.
+        const token = this.beforeDaemonStop();
+        await this.callFacadeInternal('stop');
+        await this.afterDaemonStopped(token);
         this.emit({ type: 'runtimeStopped' });
     }
+    /**
+     * Called at the very start of a stop, before the daemon RPC, so a transport
+     * can capture whatever identifies the session being stopped (the web
+     * transport's runtime-lock lease). The value is handed back to
+     * {@link afterDaemonStopped}. Default: nothing to capture.
+     */
+    beforeDaemonStop() {
+        return undefined;
+    }
+    /**
+     * Called once the daemon has acknowledged a stop and before subscribers are
+     * told about it. A transport holding an exclusive resource for the daemon's
+     * lifetime (the web transport's cross-tab runtime lock, say) releases it
+     * here: the acknowledgement is the proof the daemon let its storage go, and
+     * running before the event means a subscriber that restarts the runtime
+     * cannot race the release. Not called when the stop call fails, because an
+     * unacknowledged stop is no evidence the daemon is down.
+     *
+     * Receives the token {@link beforeDaemonStop} captured, so the release can be
+     * scoped to the session this stop belongs to and a stop whose start has
+     * already been superseded frees nothing. Awaited, so a transport whose
+     * release only completes asynchronously (the Web Locks API frees a lock when
+     * the holder's promise settles, not when it is asked to) can resolve once the
+     * resource is genuinely free.
+     */
+    afterDaemonStopped(_token) { }
     getInfo() {
         return this.callFacade('getInfo');
     }

package/dist/client.d.ts

@@ -13,7 +13,12 @@ import type { Balance, CreateWalletResult, DepositResult, ExitResult, ExitStatus
 export interface WavelengthClient {
     /** Resolves once the runtime assets are loaded and the client is usable. */
     ready(): Promise<void>;
-    /** Starts the embedded daemon with the given config and resolves with its initial info. */
+    /**
+     * Starts the embedded daemon with the given config and resolves with its
+     * initial info. Calling start() while a session is already running coalesces
+     * onto it and resolves with the current info; the passed config is ignored,
+     * so stop() first to start under a different one.
+     */
     start(config: RuntimeConfig): Promise<WalletInfo>;
     /** Stops the embedded daemon. */
     stop(): Promise<void>;
@@ -65,7 +70,17 @@ export interface WavelengthClient {
      * `broadcast: false` first to preview; `broadcast: true` moves funds.
      */
     sweepWallet(req: SweepWalletRequest): Promise<SweepWalletResult>;
-    /** Invokes a portable daemon facade method with a normalized response. */
+    /**
+     * Invokes a portable daemon facade method with a normalized response. A
+     * low-level escape hatch for facade verbs the typed methods do not cover;
+     * prefer the typed methods wherever they exist.
+     *
+     * Rejects the lifecycle verbs `'start'` and `'stop'`: use the typed
+     * {@link start} and {@link stop} instead. On the web transports those verbs
+     * take and release the cross-tab runtime lock, so allowing a raw
+     * `callFacade('start')` or `callFacade('stop')` would bypass it, defeat the
+     * multi-tab guard, and could strand the lock until the page reloads.
+     */
     callFacade<T = unknown>(method: FacadeMethod, params?: unknown): Promise<T>;
     /** Reports whether the embedded daemon is running. */
     isRunning(): Promise<boolean>;

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC3D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AACnE,OAAO,KAAK,EACV,mBAAmB,EACnB,cAAc,EACd,WAAW,EACX,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,EAClB,WAAW,EACX,4BAA4B,EAC5B,cAAc,EACd,WAAW,EACX,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EACV,OAAO,EACP,kBAAkB,EAClB,aAAa,EACb,UAAU,EACV,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,UAAU,EACV,2BAA2B,EAC3B,iBAAiB,EACjB,aAAa,EACb,UAAU,EACV,iBAAiB,EACjB,kBAAkB,EACnB,MAAM,cAAc,CAAC;AAEtB;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,4EAA4E;IAC5E,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB;;;;;OAKG;IACH,KAAK,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAClD,iCAAiC;IACjC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,kDAAkD;IAClD,OAAO,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC;IAC/B,oDAAoD;IACpD,MAAM,IAAI,OAAO,CAAC,YAAY,CAAC,CAAC;IAChC,0CAA0C;IAC1C,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAC5B,mDAAmD;IACnD,YAAY,CAAC,GAAG,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IACpE,0DAA0D;IAC1D,YAAY,CAAC,GAAG,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IACpE,+CAA+C;IAC/C,qBAAqB,CACnB,GAAG,EAAE,4BAA4B,GAChC,OAAO,CAAC,2BAA2B,CAAC,CAAC;IACxC,6CAA6C;IAC7C,OAAO,CAAC,GAAG,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IACtD,4DAA4D;IAC5D,OAAO,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IACrD;;;;OAIG;IACH,WAAW,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAC1D,qEAAqE;IACrE,YAAY,CAAC,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAC/D,wDAAwD;IACxD,IAAI,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAC5C,sDAAsD;IACtD,IAAI,CAAC,GAAG,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAC7C,2FAA2F;IAC3F,IAAI,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAC5C,qCAAqC;IACrC,UAAU,CAAC,GAAG,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC9D;;;;OAIG;IACH,WAAW,CAAC,GAAG,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAClE;;;OAGG;IACH,WAAW,CAAC,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IACjE;;;OAGG;IACH,WAAW,CAAC,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IACjE;;;;;;;;;;OAUG;IACH,UAAU,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAC5E,sDAAsD;IACtD,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9B,gFAAgF;IAChF,SAAS,CAAC,QAAQ,EAAE,kBAAkB,GAAG,MAAM,IAAI,CAAC;IACpD;;;OAGG;IACH,aAAa,CAAC,IAAI,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3D,kEAAkE;IAClE,YAAY,IAAI,IAAI,CAAC;IACrB;;;;;;OAMG;IACH,OAAO,IAAI,IAAI,CAAC;CACjB"}

package/dist/engine/engine.d.ts

@@ -50,8 +50,13 @@ export interface WalletEngine {
     subscribe(listener: () => void): () => void;
     /**
      * Starts the runtime. Falls back to the engine's configured config when
-     * called without an argument; throws if neither exists. A failure moves the
-     * phase to 'error' and rejects.
+     * called without an argument; throws if neither exists. On success it
+     * dispatches the info and best-effort refreshes; a failure moves the phase to
+     * 'error' and rejects. Either way, a stop() the host issued while the start
+     * was in flight takes precedence: that stop governs the phase, and the start
+     * leaves the snapshot to it (no info dispatch and no refresh on success, no
+     * error surfaced on failure). The promise still settles the ordinary way,
+     * resolving with the info or rejecting.
      */
     start(config?: RuntimeConfig): Promise<WalletInfo>;
     /** Stops the runtime and clears the in-memory snapshot (info, balance, activity, error); persisted wallet data is untouched. A failure moves the phase to 'error'. */

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

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

package/dist/engine/engine.js

@@ -17,6 +17,9 @@ class WavelengthEngine {
     #store = new SnapshotStore();
     #config;
     #disposed = false;
+    // Counts stops the host asked for, so a start that rejects afterwards can
+    // tell an intentional shutdown from a runtime that died underneath it.
+    #deliberateStops = 0;
     #unsubscribe;
     // Background refreshes are serialized: two concurrent reads would race on
     // the snapshot, and the slower one would win with the staler data.
@@ -110,9 +113,20 @@ class WavelengthEngine {
             throw new Error('cannot start while the runtime is stopping');
         }
         this.#refreshFailures = 0;
+        const stopsBefore = this.#deliberateStops;
         this.#dispatch({ type: 'startRequested' }, { error: null });
         try {
             const info = await this.client.start(cfg);
+            // A stop the host issued while this start was in flight owns the outcome,
+            // the same precedence the catch below applies to a rejected start. The
+            // phase has already moved to stopping or stopped; dispatching infoReceived
+            // would ignore-transition through the machine but still apply the { info }
+            // patch, repopulating a snapshot the host asked to tear down (the hazard
+            // #fetchAll guards on its sibling path). Hand the caller the info the RPC
+            // returned without touching the snapshot, and skip the refresh with it.
+            if (this.#deliberateStops !== stopsBefore) {
+                return info;
+            }
             this.#dispatch({ type: 'infoReceived', info }, { info });
             try {
                 await this.refresh();
@@ -124,12 +138,34 @@ class WavelengthEngine {
         }
         catch (err) {
             const error = toError(err);
+            // A stop the host asked for while this start was in flight owns the
+            // outcome. Reporting the abandoned start's failure would drag the
+            // phase back off 'stopped' and show an error the host already moved
+            // past. A runtime that died on its own is different: it reaches
+            // 'stopped' without a stop request, and the failure still has to
+            // surface (see the machine's startFailed transition).
+            if (this.#deliberateStops !== stopsBefore) {
+                // The phase intentionally stays 'stopped', so the cause is dropped
+                // from the snapshot; log it so it is still recoverable. The promise
+                // rejection below carries it too.
+                const logs = [
+                    ...this.getSnapshot().logs,
+                    {
+                        level: 'debug',
+                        message: 'start failed but a deliberate stop took precedence; error ' +
+                            `kept off the phase: ${error.message}`,
+                    },
+                ].slice(-MAX_LOGS);
+                this.#store.update({ logs });
+                throw error;
+            }
             this.#dispatch({ type: 'startFailed' }, { error });
             throw error;
         }
     }
     async stop() {
         this.#assertNotDisposed();
+        this.#deliberateStops += 1;
         this.#dispatch({ type: 'stopRequested' });
         try {
             await this.client.stop();

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

@@ -1 +1 @@
-{"version":3,"file":"machine.d.ts","sourceRoot":"","sources":["../../src/engine/machine.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,YAAY,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAEhF;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GACzB;IAAE,IAAI,EAAE,cAAc,CAAA;CAAE,GACxB;IAAE,IAAI,EAAE,eAAe,CAAA;CAAE,GACzB;IAAE,IAAI,EAAE,gBAAgB,CAAA;CAAE,GAC1B;IAAE,IAAI,EAAE,gBAAgB,CAAA;CAAE,GAC1B;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,GACvB;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,IAAI,EAAE,UAAU,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,kBAAkB,CAAA;CAAE,GAC5B;IAAE,IAAI,EAAE,mBAAmB,CAAA;CAAE,GAC7B;IAAE,IAAI,EAAE,uBAAuB,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,yBAAyB,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,sBAAsB,CAAA;CAAE,GAChC;IAAE,IAAI,EAAE,YAAY,CAAA;CAAE,GACtB;IAAE,IAAI,EAAE,mBAAmB,CAAA;CAAE,GAC7B;IAAE,IAAI,EAAE,4BAA4B,CAAA;CAAE,GACtC;IAAE,IAAI,EAAE,eAAe,CAAA;CAAE,GACzB;IAAE,IAAI,EAAE,eAAe,CAAA;CAAE,GACzB;IAAE,IAAI,EAAE,YAAY,CAAA;CAAE,CAAC;AAE3B;;;;;GAKG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,YAAY,EACnB,KAAK,EAAE,iBAAiB,GACvB,YAAY,CA+Dd"}
+{"version":3,"file":"machine.d.ts","sourceRoot":"","sources":["../../src/engine/machine.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,YAAY,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAEhF;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GACzB;IAAE,IAAI,EAAE,cAAc,CAAA;CAAE,GACxB;IAAE,IAAI,EAAE,eAAe,CAAA;CAAE,GACzB;IAAE,IAAI,EAAE,gBAAgB,CAAA;CAAE,GAC1B;IAAE,IAAI,EAAE,gBAAgB,CAAA;CAAE,GAC1B;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,GACvB;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,IAAI,EAAE,UAAU,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,kBAAkB,CAAA;CAAE,GAC5B;IAAE,IAAI,EAAE,mBAAmB,CAAA;CAAE,GAC7B;IAAE,IAAI,EAAE,uBAAuB,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,yBAAyB,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,sBAAsB,CAAA;CAAE,GAChC;IAAE,IAAI,EAAE,YAAY,CAAA;CAAE,GACtB;IAAE,IAAI,EAAE,mBAAmB,CAAA;CAAE,GAC7B;IAAE,IAAI,EAAE,4BAA4B,CAAA;CAAE,GACtC;IAAE,IAAI,EAAE,eAAe,CAAA;CAAE,GACzB;IAAE,IAAI,EAAE,eAAe,CAAA;CAAE,GACzB;IAAE,IAAI,EAAE,YAAY,CAAA;CAAE,CAAC;AAE3B;;;;;GAKG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,YAAY,EACnB,KAAK,EAAE,iBAAiB,GACvB,YAAY,CA4Fd"}

package/dist/engine/machine.js

@@ -10,15 +10,44 @@ export function transition(phase, event) {
         case 'runtimeReady':
             return phase === 'loading' ? 'runtimeReady' : phase;
         case 'runtimeFailed':
-            return phase === 'loading' ? 'error' : phase;
+            // 'stopped' is accepted alongside 'loading' for the same reason startFailed
+            // accepts it: a runtime that dies before ready() settles announces its stop
+            // (moving loading -> stopped) before the ready() rejection dispatches
+            // runtimeFailed. Without this the boot failure would be swallowed by the
+            // stop it caused, leaving the host on a generic stopped screen. Unlike a
+            // start failure, a runtime that failed to load is a genuine error worth
+            // surfacing even if a stop coincided, so this needs no deliberate-stop
+            // guard: a clean stop during loading never produces a runtimeFailed.
+            return phase === 'loading' || phase === 'stopped' ? 'error' : phase;
         case 'runtimeStopped':
             // A clean stop or a runtime crash; either way the engine is gone, so
-            // this always wins.
-            return 'stopped';
+            // this wins over every phase except 'error'. An error outranks the stop
+            // that caused it: a runtime dying because a start failed announces both
+            // the failure and the stop, in an order that depends on transport timing
+            // (a synchronous emit lands before the rejection, one deferred behind an
+            // async lock release lands after), and the host must end on the failure
+            // either way. Preserving 'error' here is what frees transports from
+            // ordering their rejection against their stop event. A clean stop never
+            // passes through 'error', so it is unaffected, and startRequested still
+            // exits 'error', so retry flows are too.
+            //
+            // This preserves 'error' for every error, not only a start failure: a
+            // live-runtime error (a lost activity stream, refresh-budget exhaustion)
+            // followed by a runtime death also stays on 'error' rather than moving to
+            // 'stopped'. That is intentional: an error screen is a safe terminal state
+            // the host recovers from with a retry (startRequested exits it), and
+            // scoping the rule to start failures would mean tracking which error is in
+            // flight for a difference the user does not feel.
+            return phase === 'error' ? phase : 'stopped';
         case 'startRequested':
             return phase === 'stopping' ? phase : 'starting';
         case 'startFailed':
-            return phase === 'starting' ? 'error' : phase;
+            // 'stopped' is accepted alongside 'starting' because a runtime that dies
+            // mid-start announces the stop before the start rejection has finished
+            // propagating. Without this the failure would be swallowed by the stop
+            // that it caused, leaving the host on a generic stopped screen with no
+            // way to show (for instance) that the wallet is open in another tab.
+            return phase === 'starting' || phase === 'stopped' ? 'error' : phase;
         case 'infoReceived':
             switch (phase) {
                 case 'starting':

package/dist/errors.d.ts

@@ -1,12 +1,18 @@
 /**
  * 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.
+ * named codes; most daemon-originated errors fall back to `'wavelength_error'`
+ * (a richer daemon-code mapping is planned), except storage-contention failures
+ * on `start()`, which the web transports map to `'wallet_locked'`. `'wallet_locked'` means the wallet
+ * runtime is already open in another tab or window of the same origin: the
+ * daemon's OPFS databases are exclusive, so a start attempt fails fast with this
+ * code until the other tab stops the runtime or closes. `'runtime_lock_unavailable'`
+ * means the browser refused or dropped the lock request itself (for example
+ * while the document is shutting down), which says nothing about another tab.
+ * 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 & {});
+export type WavelengthErrorCode = 'wavelength_error' | 'runtime_not_ready' | 'asset_load_failed' | 'worker_error' | 'wallet_locked' | 'runtime_lock_unavailable' | '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.

package/dist/errors.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,mBAAmB,GAC3B,kBAAkB,GAClB,mBAAmB,GACnB,mBAAmB,GACnB,cAAc,GACd,eAAe,GACf,0BAA0B,GAC1B,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/version.d.ts

@@ -7,12 +7,12 @@
  * Hosted runtime assets live in a directory named after this value
  * (`<assets root>/<RUNTIME_MANIFEST_VERSION>/<file>`), so every asset set gets
  * a unique URL and a browser can never serve a stale cached runtime. Bump it
- * together with regenerating the daemon types and publishing the matching
- * asset set.
+ * together with regenerating the daemon types, and only to a published
+ * wavelength release: the matching asset set is attached to that release.
  *
  * Build tooling reads this value from the source text via
  * scripts/runtime-version.mjs, so keep the declaration in this exact
  * single-quoted literal form.
  */
-export declare const RUNTIME_MANIFEST_VERSION = "v0.1.0";
+export declare const RUNTIME_MANIFEST_VERSION = "v0.1.1-rc2";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,wBAAwB,WAAW,CAAC"}
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,wBAAwB,eAAe,CAAC"}

package/dist/version.js

@@ -7,11 +7,11 @@
  * Hosted runtime assets live in a directory named after this value
  * (`<assets root>/<RUNTIME_MANIFEST_VERSION>/<file>`), so every asset set gets
  * a unique URL and a browser can never serve a stale cached runtime. Bump it
- * together with regenerating the daemon types and publishing the matching
- * asset set.
+ * together with regenerating the daemon types, and only to a published
+ * wavelength release: the matching asset set is attached to that release.
  *
  * Build tooling reads this value from the source text via
  * scripts/runtime-version.mjs, so keep the declaration in this exact
  * single-quoted literal form.
  */
-export const RUNTIME_MANIFEST_VERSION = 'v0.1.0';
+export const RUNTIME_MANIFEST_VERSION = 'v0.1.1-rc2';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightninglabs/wavelength-core",
-  "version": "0.1.0",
+  "version": "0.1.1-rc2",
   "private": false,
   "description": "Transport- and framework-agnostic contract for the Wavelength self-custodial Lightning wallet SDK.",
   "license": "MIT",