@parity/product-sdk-host 0.11.0 → 0.13.0

package/src/testing.ts

@@ -0,0 +1,386 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Test fakes for `@parity/product-sdk-host`.
+ *
+ * The host reaches its container through one cached `TrUApiClient`.
+ * `createFakeHost()` injects a fake via `setTruApiClient` so every accessor
+ * (`getHostLocalStorage`, `getAccountsProvider`, `getStatementStore`, `getTruApi`,
+ * …) resolves against it and `isInsideContainer()` reports `true` — which also
+ * makes a default `SignerManager`, `local-storage` auto-detection, and the
+ * `statement-store` / `cloud-storage` host paths testable.
+ *
+ * Not modeled: the PAPI `chain` JSON-RPC surface behind `getHostProvider()` —
+ * there's no chain-read fake, by design; the host owns RPC selection — and the
+ * `chat` / `entropy` / `notifications` / `payment` / `permissions` /
+ * `resourceAllocation` / `theme` domains. Touching an unmodeled domain throws a
+ * descriptive error rather than failing with `undefined is not a function`.
+ *
+ * @packageDocumentation
+ */
+import type { ObservableLike, Observer, Subscription, TrUApiClient } from "@parity/truapi";
+import { okAsync } from "neverthrow";
+
+import { setTruApiClient } from "./transport.js";
+
+export { setTruApiClient };
+
+/**
+ * The public surface of a generated truapi domain client. `keyof` skips private
+ * members, so this is the shape a plain object can implement — the classes
+ * themselves are unimplementable outside truapi because of their
+ * `private transport`.
+ */
+type PublicSurface<C> = { [K in keyof C]: C[K] };
+
+/**
+ * `TrUApiClient` seen through public surfaces only. The fake is checked against
+ * this member-by-member, so drift from the generated client — a renamed method,
+ * a changed request or response type — fails compilation here instead of
+ * surfacing as a runtime mismatch in consumers' tests.
+ */
+type PublicTruApiClient = { [D in keyof TrUApiClient]: PublicSurface<TrUApiClient[D]> };
+
+/** Inlined to keep the `truapi` facade out of this entry's bundle. */
+function toHex(bytes: Uint8Array): `0x${string}` {
+    return `0x${Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("")}`;
+}
+
+function fakeSubscription(): Subscription {
+    return { unsubscribe: () => {}, subscriptionId: "fake-subscription" };
+}
+
+/**
+ * Wrap a `subscribe` implementation into a full `ObservableLike`. The
+ * `Symbol.observable` interop member only lands on the object when the symbol
+ * is polyfilled (e.g. by rxjs) — same as the generated client — and nothing in
+ * the SDK reads it; it exists to satisfy the interface.
+ */
+function makeObservable<Item, Reason = never>(
+    subscribe: (observer?: Partial<Observer<Item, Reason>>) => Subscription,
+): ObservableLike<Item, Reason> {
+    const observable: ObservableLike<Item, Reason> = {
+        subscribe,
+        [Symbol.observable]() {
+            return observable;
+        },
+    };
+    return observable;
+}
+
+/** An `ObservableLike` that never emits. Drive statement delivery with `createFakeStatementTransport`. */
+function inertObservable<Item, Reason = never>(): ObservableLike<Item, Reason> {
+    return makeObservable(() => fakeSubscription());
+}
+
+/**
+ * An `ObservableLike` that emits `item` once, asynchronously. The microtask defer
+ * matters: the caller assigns its subscription handle from the return value, so
+ * the item must arrive after `subscribe()` returns, not during it.
+ */
+function oneShotObservable<Item>(item: Item): ObservableLike<Item> {
+    return makeObservable((observer) => {
+        queueMicrotask(() => observer?.next?.(item));
+        return fakeSubscription();
+    });
+}
+
+/**
+ * A domain the fake deliberately doesn't model (see the module header). Any
+ * member access throws with a pointer here, instead of the bare TypeError an
+ * empty stub would give. The empty-object cast is the one concession a Proxy
+ * needs; every modeled domain is checked structurally.
+ */
+function notModeled<D extends keyof TrUApiClient>(domain: D): PublicSurface<TrUApiClient[D]> {
+    return new Proxy({} as PublicSurface<TrUApiClient[D]>, {
+        get(_target, member) {
+            // Stay quiet for inspection probes (console.log, await-resolution).
+            if (typeof member === "symbol" || member === "then") return undefined;
+            throw new Error(
+                `createFakeTruApiClient: \`${domain}.${member}\` is not modeled by the fake. See the @parity/product-sdk-host/testing module docs for what is covered.`,
+            );
+        },
+    });
+}
+
+/** Deterministic `0x`-prefixed preimage key derived from a hex value (FNV-1a). */
+function preimageKey(hexValue: string): `0x${string}` {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < hexValue.length; i++) {
+        h ^= hexValue.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
+    }
+    return `0x${(h >>> 0).toString(16).padStart(8, "0")}`;
+}
+
+/** Options for {@link createFakeTruApiClient}. */
+export interface CreateFakeTruApiClientOptions {
+    /** `account.getUserId` primary username. Default `"alice.dot"`. */
+    primaryUsername?: string;
+    /** Product-account public key. Default 32 bytes of `0x11`. */
+    publicKey?: Uint8Array;
+    /** Bytes returned by the signing domain (signatures / proofs / transactions). Default 64 bytes of `0x22`. */
+    signature?: Uint8Array;
+    /** Whether `system.featureSupported` reports the chain supported. Default `true`. */
+    chainSupported?: boolean;
+    /** Seed the in-memory host localStorage, keyed by storage key. */
+    localStorage?: Record<string, Uint8Array>;
+    /** Legacy accounts returned by `account.getLegacyAccounts`. Default none. */
+    legacyAccounts?: Array<{ publicKey: Uint8Array; name: string }>;
+    /** Seed the in-memory preimage store, keyed by the `0x` preimage key. */
+    preimages?: Record<string, Uint8Array>;
+}
+
+/**
+ * Build a fake `TrUApiClient` covering the domains the host accessors use:
+ * `localStorage` (real in-memory KV), `account` / `signing` (canned data),
+ * `statementStore`, `preimage`, and `system`. Unmodeled domains (`chain` et al —
+ * see the module header) throw on member access.
+ */
+export function createFakeTruApiClient(options?: CreateFakeTruApiClientOptions): TrUApiClient {
+    const primaryUsername = options?.primaryUsername ?? "alice.dot";
+    const publicKey = toHex(options?.publicKey ?? new Uint8Array(32).fill(0x11));
+    const signature = toHex(options?.signature ?? new Uint8Array(64).fill(0x22));
+    const chainSupported = options?.chainSupported ?? true;
+
+    // Real in-memory KV (hex values) so getHostLocalStorage()/createLocalKvStore() round-trip.
+    const kv = new Map<string, `0x${string}`>();
+    for (const [key, value] of Object.entries(options?.localStorage ?? {})) {
+        kv.set(key, toHex(value));
+    }
+
+    const legacyAccounts = (options?.legacyAccounts ?? []).map((a) => ({
+        publicKey: toHex(a.publicKey),
+        name: a.name,
+    }));
+
+    // Preimage store (hex key -> hex value), for getPreimageManager() and submit/lookup round-trips.
+    const preimages = new Map<string, `0x${string}`>();
+    for (const [key, value] of Object.entries(options?.preimages ?? {})) {
+        preimages.set(key, toHex(value));
+    }
+
+    // Typed against the generated client's public surface: every method below is
+    // structurally checked, so a truapi signature change breaks this file's build,
+    // not a consumer's test run.
+    const client: PublicTruApiClient = {
+        localStorage: {
+            read: ({ key }) => okAsync({ value: kv.get(key) }),
+            write: ({ key, value }) => {
+                kv.set(key, value);
+                return okAsync(undefined);
+            },
+            clear: ({ key }) => {
+                kv.delete(key);
+                return okAsync(undefined);
+            },
+        },
+        account: {
+            getUserId: () => okAsync({ primaryUsername }),
+            requestLogin: () => okAsync("Success"),
+            getAccount: () => okAsync({ account: { publicKey } }),
+            getAccountAlias: () =>
+                okAsync({ context: toHex(new Uint8Array([1])), alias: toHex(new Uint8Array([2])) }),
+            getLegacyAccounts: () => okAsync({ accounts: legacyAccounts }),
+            createAccountProof: () => okAsync({ proof: signature }),
+            connectionStatusSubscribe: () => inertObservable(),
+        },
+        signing: {
+            createTransaction: () => okAsync({ transaction: signature }),
+            createTransactionWithLegacyAccount: () => okAsync({ transaction: signature }),
+            signRaw: () => okAsync({ signature }),
+            signRawWithLegacyAccount: () => okAsync({ signature }),
+            signPayload: () => okAsync({ signature }),
+            signPayloadWithLegacyAccount: () => okAsync({ signature }),
+        },
+        statementStore: {
+            subscribe: () => inertObservable(),
+            createProof: () =>
+                okAsync({ proof: { tag: "Sr25519", value: { signature, signer: publicKey } } }),
+            createProofAuthorized: () =>
+                okAsync({ proof: { tag: "Sr25519", value: { signature, signer: publicKey } } }),
+            submit: () => okAsync(undefined),
+        },
+        system: {
+            handshake: () => okAsync(undefined),
+            featureSupported: () => okAsync({ supported: chainSupported }),
+            navigateTo: () => okAsync(undefined),
+        },
+        preimage: {
+            lookupSubscribe: ({ request: { key } }) =>
+                oneShotObservable({ value: preimages.get(key) }),
+            submit: (value) => {
+                const key = preimageKey(value);
+                preimages.set(key, value);
+                return okAsync(key);
+            },
+        },
+        chain: notModeled("chain"),
+        chat: notModeled("chat"),
+        entropy: notModeled("entropy"),
+        notifications: notModeled("notifications"),
+        payment: notModeled("payment"),
+        permissions: notModeled("permissions"),
+        resourceAllocation: notModeled("resourceAllocation"),
+        theme: notModeled("theme"),
+    };
+
+    // A plain downcast, not an `unknown` bridge: each generated class is
+    // assignable to its `PublicSurface`, and TS has already verified every fake
+    // member against the generated signatures in the annotation above.
+    return client as TrUApiClient;
+}
+
+/**
+ * A `beforeEach`-registered test hook, e.g. Vitest's `onTestFinished`. Read off
+ * `globalThis` so we couple to no test framework: present under Vitest's globals
+ * mode, absent everywhere else (Jest, `node:test`, plain scripts).
+ */
+type TestFinishedHook = (fn: () => void) => void;
+
+/** Handle returned by {@link createFakeHost}. */
+export interface FakeHost extends Disposable {
+    /** The injected fake client (also what `getTruApi()` returns). */
+    client: TrUApiClient;
+    /** Clear the override. Idempotent; safe to call more than once. */
+    dispose(): void;
+    /** `using host = createFakeHost()` restores the real client at scope end. */
+    [Symbol.dispose](): void;
+}
+
+/**
+ * Inject a fake client via {@link setTruApiClient} and return a disposer.
+ *
+ * Cleanup is guaranteed three ways, so a forgotten reset can't leak the override
+ * into the next test or file: prefer `using` (scope-end disposal), otherwise the
+ * handle self-registers `onTestFinished` when created inside a Vitest run, and
+ * `dispose()` is always there to call by hand.
+ *
+ * @example
+ * ```ts
+ * import { createFakeHost } from "@parity/product-sdk-host/testing";
+ *
+ * test("host storage is reachable", async () => {
+ *   using host = createFakeHost({ primaryUsername: "carol.dot" });
+ *   // getHostLocalStorage(), getAccountsProvider(), a default SignerManager, etc.
+ *   // resolve the fake; the real client is restored when the test scope ends.
+ * });
+ * ```
+ */
+export function createFakeHost(options?: CreateFakeTruApiClientOptions): FakeHost {
+    const client = createFakeTruApiClient(options);
+    setTruApiClient(client);
+
+    let disposed = false;
+    const dispose = () => {
+        if (disposed) return;
+        disposed = true;
+        setTruApiClient(null);
+    };
+
+    // Best-effort auto-cleanup for the common case (a bare `const host =
+    // createFakeHost()` with no `using` and no manual reset). Under Vitest's
+    // globals mode `onTestFinished` is on `globalThis`; elsewhere it's absent and
+    // we quietly rely on `using` / manual `dispose()`.
+    const onTestFinished = (globalThis as { onTestFinished?: TestFinishedHook }).onTestFinished;
+    if (typeof onTestFinished === "function") {
+        try {
+            onTestFinished(dispose);
+        } catch {
+            // Not inside a running test (e.g. called at module scope) — ignore.
+        }
+    }
+
+    return {
+        client,
+        dispose,
+        [Symbol.dispose]: dispose,
+    };
+}
+
+if (import.meta.vitest) {
+    // Round-trip guard: drive the fake through the *real* host accessors.
+    const { describe, test, expect, afterEach } = import.meta.vitest;
+    const { getHostLocalStorage, getStatementStore, isInsideContainer } = await import(
+        "./container.js"
+    );
+    const { getAccountsProvider } = await import("./accounts.js");
+    const { getPreimageManager } = await import("./truapi.js");
+
+    const lookupOnce = (
+        manager: NonNullable<Awaited<ReturnType<typeof getPreimageManager>>>,
+        key: `0x${string}`,
+    ) =>
+        new Promise<Uint8Array | null>((resolve) => {
+            manager.lookup(key, (preimage) => {
+                if (preimage !== null) resolve(preimage);
+            });
+        });
+
+    afterEach(() => setTruApiClient(null));
+
+    describe("createFakeHost / createFakeTruApiClient", () => {
+        test("host localStorage round-trips through the real adapter", async () => {
+            createFakeHost();
+            const ls = await getHostLocalStorage();
+            expect(ls).not.toBeNull();
+            await ls?.writeString("k", "v");
+            expect(await ls?.readString("k")).toBe("v");
+            await ls?.writeJSON("j", { a: 1 });
+            expect(await ls?.readJSON("j")).toEqual({ a: 1 });
+            expect(await ls?.readString("missing")).toBe("");
+        });
+
+        test("seeded localStorage is readable", async () => {
+            createFakeHost({ localStorage: { greeting: new TextEncoder().encode("hi") } });
+            const ls = await getHostLocalStorage();
+            expect(await ls?.readString("greeting")).toBe("hi");
+        });
+
+        test("accounts provider resolves the configured user", async () => {
+            createFakeHost({ primaryUsername: "carol.dot" });
+            const accounts = await getAccountsProvider();
+            expect(accounts).not.toBeNull();
+            const userId = await accounts?.getUserId().match(
+                (v) => v,
+                () => null,
+            );
+            expect(userId?.primaryUsername).toBe("carol.dot");
+        });
+
+        test("statement store resolves", async () => {
+            createFakeHost();
+            expect(await getStatementStore()).not.toBeNull();
+        });
+
+        test("preimage manager reads seeded bytes and round-trips submit -> lookup", async () => {
+            createFakeHost({ preimages: { "0xabc": new Uint8Array([1, 2, 3]) } });
+            const pm = await getPreimageManager();
+            expect(pm).not.toBeNull();
+
+            const seeded = await lookupOnce(pm!, "0xabc");
+            expect(Array.from(seeded ?? [])).toEqual([1, 2, 3]);
+
+            const key = await pm!.submit(new Uint8Array([9, 9]));
+            const back = await lookupOnce(pm!, key);
+            expect(Array.from(back ?? [])).toEqual([9, 9]);
+        });
+
+        test("isInsideContainer is true while set, false after dispose", async () => {
+            const host = createFakeHost();
+            expect(await isInsideContainer()).toBe(true);
+            host.dispose();
+            expect(await isInsideContainer()).toBe(false);
+            expect(await getHostLocalStorage()).toBeNull();
+        });
+
+        test("Symbol.dispose clears the override and dispose is idempotent", async () => {
+            {
+                using host = createFakeHost();
+                expect(await isInsideContainer()).toBe(true);
+                host.dispose(); // explicit + scope-end Symbol.dispose must not double-clear badly
+            }
+            expect(await isInsideContainer()).toBe(false);
+        });
+    });
+}

package/src/theme.ts

@@ -1,74 +1,52 @@
 // Copyright 2026 Parity Technologies (UK) Ltd.
 // SPDX-License-Identifier: Apache-2.0
 /**
- * Higher-level wrapper for the host's theme subscription.
+ * Higher-level wrapper for the host's theme subscription, backed by
+ * `truApi.theme.subscribe`.
  *
- * `hostApi.themeSubscribe` is reachable via {@link getTruApi}, but consumers
- * have to wire the subscription envelope themselves. `getThemeProvider`
- * returns the `@novasamatech/host-api-wrapper` theme provider object directly,
- * giving callers a `subscribeTheme(cb)` method that resolves to a typed
- * {@link ThemeMode} — a `{ name, variant }` struct where `variant` is
- * `"Light" | "Dark"` — and yields a `Subscription<void>` handle.
- *
- * @remarks
- * As of `host-api(-wrapper)` v0.8 the theme payload is a struct, not a flat
- * `"light" | "dark"` string: read {@link ThemeMode.variant} for the
- * light/dark value (now capitalized) and {@link ThemeMode.name} for the
- * active theme name (`Default`, or `Custom` carrying a string id).
+ * `getThemeProvider` returns a handle whose `subscribeTheme(cb)` delivers a
+ * typed {@link ThemeMode} — a `{ name, variant }` struct where `variant` is
+ * `"Light" | "Dark"` and `name` is `{ tag: "Default" }` or
+ * `{ tag: "Custom", value }` — and yields a {@link HostSubscription}
+ * (`unsubscribe` + `onInterrupt`).
  *
  * @module
  */
 
-import { createLogger } from "@parity/product-sdk-logger";
-
-import type {
-    createThemeProvider,
-    ThemeMode as NovasamaThemeMode,
-} from "@novasamatech/host-api-wrapper";
-
-const log = createLogger("host:theme");
+import type { HostThemeSubscribeItem, TrUApiClient } from "@parity/truapi";
 
-/**
- * Host theme provider handle. Exposes `subscribeTheme(callback)` which
- * receives a typed {@link ThemeMode} struct on every change and returns a
- * `Subscription<void>` (`unsubscribe` + `onInterrupt`).
- *
- * Type identical to `createThemeProvider()` from
- * `@novasamatech/host-api-wrapper`.
- */
-export type ThemeProvider = ReturnType<typeof createThemeProvider>;
+import { getClient, subscribeWithInterrupt } from "./transport.js";
+import type { HostSubscription } from "./types.js";
 
 /**
- * Host theme value. Re-exported from `@novasamatech/host-api-wrapper`.
- *
- * A `{ name, variant }` struct as of v0.8 (previously a flat
- * `"light" | "dark"` string).
+ * Host theme value. A `{ name, variant }` struct re-exported from
+ * `@parity/truapi`.
  */
-export type ThemeMode = NovasamaThemeMode;
+export type ThemeMode = HostThemeSubscribeItem;
 
-/** Light/dark variant of the active theme: `"Light" | "Dark"`. */
-export type ThemeVariant = ThemeMode["variant"];
+/** Light/dark variant of the active theme (`"Light" | "Dark"`) and the active theme name. Re-exported from `@parity/truapi`. */
+export type { ThemeName, ThemeVariant } from "@parity/truapi";
 
 /**
- * Active theme name: `{ tag: "Default" }`, or `{ tag: "Custom", value }`
- * carrying the custom theme's string id.
+ * Host theme provider handle. `subscribeTheme(callback)` receives a typed
+ * {@link ThemeMode} on every change and returns a {@link HostSubscription}.
  */
-export type ThemeName = ThemeMode["name"];
+export interface ThemeProvider {
+    subscribeTheme(callback: (theme: ThemeMode) => void): HostSubscription;
+}
+
+/** Build a {@link ThemeProvider} over a TruAPI client's `theme` domain. */
+function adaptThemeProvider(client: TrUApiClient): ThemeProvider {
+    return {
+        subscribeTheme(callback) {
+            return subscribeWithInterrupt(client.theme.subscribe(), callback);
+        },
+    };
+}
 
 /**
- * Get the host theme provider.
- *
- * Returns the theme-subscription handle exported by
- * `@novasamatech/host-api-wrapper`, or `null` if the package is unavailable
- * (running outside a host container or the optional peer dep isn't
- * installed).
- *
- * Implementation note: upstream `@novasamatech/host-api-wrapper` exports only
- * the `createThemeProvider` factory and no `themeProvider` singleton, so
- * this getter constructs a fresh instance on each call (unlike
- * {@link getPreimageManager} or {@link getHostLocalStorage}, which return
- * upstream singletons). The constructed provider is cheap to allocate; it
- * only opens a subscription when `subscribeTheme` is called.
+ * Get the host theme provider, backed by `truApi.theme.*`. Returns `null` when
+ * running outside a host container.
  *
  * @returns The theme provider, or `null` if unavailable.
  *
@@ -87,20 +65,14 @@ export type ThemeName = ThemeMode["name"];
  * ```
  */
 export async function getThemeProvider(): Promise<ThemeProvider | null> {
-    try {
-        const sdk = await import("@novasamatech/host-api-wrapper");
-        return sdk.createThemeProvider();
-    } catch (err) {
-        log.debug("getThemeProvider unavailable", err);
-        return null;
-    }
+    const client = await getClient();
+    return client ? adaptThemeProvider(client) : null;
 }
 
 if (import.meta.vitest) {
     const { test, expect } = import.meta.vitest;
 
-    test("getThemeProvider returns provider when SDK is available", async () => {
-        const provider = await getThemeProvider();
-        expect(provider === null || typeof provider === "object").toBe(true);
+    test("getThemeProvider returns null outside a container", async () => {
+        expect(await getThemeProvider()).toBeNull();
     });
 }

package/src/transport.ts

@@ -0,0 +1,159 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Access to the in-house TruAPI client (`@parity/truapi`) for the host package.
+ *
+ * Environment detection and the lazily-built, cached client come from
+ * `@parity/truapi/sandbox`; this module layers the product-sdk-specific glue on
+ * top — an async {@link getClient} accessor and {@link subscribeWithInterrupt},
+ * which adapts a truapi stream into the host's {@link HostSubscription} shape.
+ *
+ * @module
+ */
+
+import type { ObservableLike, TrUApiClient } from "@parity/truapi";
+import {
+    getClientSync as sandboxGetClientSync,
+    isCorrectEnvironment as sandboxIsCorrectEnvironment,
+} from "@parity/truapi/sandbox";
+
+import type { HostSubscription } from "./types.js";
+
+// Test-only override. When set — via `setTruApiClient`, exposed through
+// `@parity/product-sdk-host/testing` — every host accessor resolves this client
+// instead of the sandbox one. `null` in production, so the branches below are
+// no-ops there.
+let clientOverride: TrUApiClient | null = null;
+
+function isProductionBuild(): boolean {
+    try {
+        // Must stay a plain `process.env.NODE_ENV` member expression: bundlers
+        // (Vite, esbuild, webpack) substitute it textually, which is how this
+        // check works in browser builds where `process` doesn't exist.
+        return process.env.NODE_ENV === "production";
+    } catch {
+        // No `process` and no bundler define — can't tell, stay quiet.
+        return false;
+    }
+}
+
+/**
+ * Test-only seam: force {@link getClient} / {@link getClientSync} to return
+ * `client`, and {@link isCorrectEnvironment} to report `true`. Pass `null` to
+ * restore normal detection. Exposed through `@parity/product-sdk-host/testing`,
+ * not the package's main entry.
+ *
+ * Calling this in a production build silently reroutes every host accessor to
+ * the injected client, so we warn — it almost always means a `/testing` import
+ * leaked into a production path.
+ */
+export function setTruApiClient(client: TrUApiClient | null): void {
+    if (client !== null && isProductionBuild()) {
+        console.warn(
+            "[product-sdk] setTruApiClient() was called in a production build. This is a test-only seam from @parity/product-sdk-host/testing; a leaked import will silently reroute all host access to the injected client.",
+        );
+    }
+    clientOverride = client;
+}
+
+/**
+ * Synchronous TruAPI client accessor. Returns the injected test client when one
+ * is set, otherwise the sandbox client (`null` outside a host container).
+ */
+export function getClientSync(): TrUApiClient | null {
+    return clientOverride ?? sandboxGetClientSync();
+}
+
+/**
+ * Host-container detection. `true` when a test client is injected, otherwise the
+ * sandbox heuristic (iframe / webview marker / injected message port).
+ */
+export function isCorrectEnvironment(): boolean {
+    return clientOverride !== null || sandboxIsCorrectEnvironment();
+}
+
+/**
+ * Get the TruAPI client. Returns `null` outside a host container. Async wrapper
+ * over {@link getClientSync} for the host wrappers that already `await` it.
+ */
+export async function getClient(): Promise<TrUApiClient | null> {
+    return getClientSync();
+}
+
+/**
+ * Adapt a truapi `ObservableLike` stream into the host's callback-style
+ * {@link HostSubscription} (`unsubscribe` + `onInterrupt`). `onNext` fires for
+ * each item; the registered `onInterrupt` callback fires when the host ends the
+ * subscription server-side — which the generated client surfaces as either
+ * `complete` (a host interrupt frame) or `error` (transport close). Shared by
+ * the statement-store and preimage adapters, which both expose this shape.
+ */
+export function subscribeWithInterrupt<Item, Reason = never>(
+    observable: ObservableLike<Item, Reason>,
+    onNext: (item: Item) => void,
+): HostSubscription {
+    let interruptCallback: ((reason?: unknown) => void) | undefined;
+    const sub = observable.subscribe({
+        next: onNext,
+        error: (reason) => interruptCallback?.(reason),
+        complete: () => interruptCallback?.(),
+    });
+    return {
+        unsubscribe: () => sub.unsubscribe(),
+        onInterrupt: (callback) => {
+            interruptCallback = callback;
+            return () => {
+                if (interruptCallback === callback) interruptCallback = undefined;
+            };
+        },
+    };
+}
+
+if (import.meta.vitest) {
+    const { test, expect, afterEach } = import.meta.vitest;
+
+    afterEach(() => setTruApiClient(null));
+
+    // Environment detection and client building are covered by `@parity/truapi`'s
+    // own sandbox tests; here we only assert the local glue degrades outside a
+    // host container.
+    test("getClientSync returns null outside a container", () => {
+        expect(getClientSync()).toBeNull();
+    });
+
+    test("getClient resolves null outside a container", async () => {
+        expect(await getClient()).toBeNull();
+    });
+
+    test("setTruApiClient overrides the client and container detection", async () => {
+        const fake = {} as TrUApiClient;
+        setTruApiClient(fake);
+        expect(getClientSync()).toBe(fake);
+        expect(await getClient()).toBe(fake);
+        expect(isCorrectEnvironment()).toBe(true);
+
+        setTruApiClient(null);
+        expect(getClientSync()).toBeNull();
+        expect(isCorrectEnvironment()).toBe(false);
+    });
+
+    test("setTruApiClient warns when injecting in a production build", () => {
+        const original = process.env.NODE_ENV;
+        const warnings: string[] = [];
+        const realWarn = console.warn;
+        console.warn = (...args: unknown[]) => void warnings.push(String(args[0]));
+        try {
+            process.env.NODE_ENV = "production";
+            setTruApiClient({} as TrUApiClient);
+            expect(warnings).toHaveLength(1);
+            expect(warnings[0]).toContain("production build");
+
+            // Clearing the override must not warn.
+            setTruApiClient(null);
+            expect(warnings).toHaveLength(1);
+        } finally {
+            console.warn = realWarn;
+            process.env.NODE_ENV = original;
+        }
+    });
+}