@crosslink/sdk-browser 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1491 @@
+import { ConnectionKind, CrosslinkTransport, Logger, ConnectionState, PairedAppRecord, RpcClient, ClientLink, NotificationPayload } from '@crosslink/core';
+export { ConnectionState, LogLevel, LogRecord, Logger, MemoryLogSink, PairedAppRecord, RpcClient, consoleLogger, createLogger, noopLogger } from '@crosslink/core';
+
+/**
+ * Pluggable secure storage. Browsers use localStorage (origin-scoped);
+ * tests/embedders inject memory or native secure storage.
+ */
+interface SecureStorage {
+    get(key: string): string | null;
+    set(key: string, value: string): void;
+    delete(key: string): void;
+}
+declare class MemorySecureStorage implements SecureStorage {
+    private map;
+    get(key: string): string | null;
+    set(key: string, value: string): void;
+    delete(key: string): void;
+}
+declare class LocalStorageSecureStorage implements SecureStorage {
+    private readonly ls;
+    constructor(ls: Storage);
+    get(key: string): string | null;
+    set(key: string, value: string): void;
+    delete(key: string): void;
+}
+/** Minimal typed wrapper used by the SDK internals. */
+declare class JsonStore<T> {
+    private readonly storage;
+    private readonly key;
+    constructor(storage: SecureStorage, key: string);
+    load(defaults: T): T;
+    save(value: T): void;
+}
+
+/**
+ * Structural subset implemented by both the DOM WebSocket and the `ws`
+ * package, so the same adapter runs in browsers and under Node.
+ */
+interface WsLike {
+    readyState: number;
+    send(data: unknown): unknown;
+    close(code?: number, reason?: string): unknown;
+    removeEventListener?(type: string, cb: (ev?: unknown) => void): unknown;
+    addEventListener(type: "open" | "close" | "error", cb: (ev?: unknown) => void): unknown;
+    addEventListener(type: "message", cb: (ev: {
+        data: unknown;
+    }) => void): unknown;
+    binaryType?: string;
+}
+/** Wraps any WsLike socket as a CrosslinkTransport (binary frames only). */
+declare function wsTransport(ws: WsLike, kind: ConnectionKind): CrosslinkTransport;
+
+interface PairingConfirmRequest {
+    sas: string;
+    hostName: string;
+    hostFp16: string;
+    grantedCaps: string[];
+    /** Host-signed device-link session; framework callbacks auto-accept these. */
+    link: boolean;
+}
+interface CrosslinkClientOptions {
+    storage?: SecureStorage;
+    deviceName?: string;
+    /** Human confirmation of the SAS + granted capabilities. Defaults to approve. */
+    onConfirmPairing?(req: PairingConfirmRequest): boolean | Promise<boolean>;
+    onStateChange?(state: ConnectionState, detail?: Record<string, unknown>): void;
+    requestTimeoutMs?: number;
+    /** Structured log sink. Defaults to a no-op; pass `consoleLogger()` in dev. */
+    logger?: Logger;
+    /**
+     * Shared secret for a private relay that also gates client attach. Most
+     * relays do not: knowledge of the 128-bit channel id already gates it, and
+     * a browser cannot hold a shared secret safely.
+     */
+    relayToken?: string;
+    /**
+     * WebSocket factory, so tests and non-DOM runtimes can inject their own.
+     * Defaults to `globalThis.WebSocket`.
+     */
+    webSocket?: (url: string) => WsLike;
+    /** `fetch` override, used for presence lookups. */
+    fetch?: typeof fetch;
+    /**
+     * Max time to wait for a WebSocket (signaling or transport) to open before
+     * giving up. A dead relay/signaling host can otherwise leave a socket in
+     * `CONNECTING` forever with no `open` or `error` event, which shows up as
+     * the client hanging on "connecting". Default 10s.
+     */
+    dialTimeoutMs?: number;
+    /**
+     * WebRTC upgrade configuration. When set, the client will automatically
+     * try to upgrade a relayed session to a direct WebRTC DataChannel after
+     * connecting. The relay remains as a fallback if the upgrade fails.
+     *
+     * Requires a `createPeer` factory that creates an `RTCPeerConnection`
+     * with the desired ICE servers.
+     *
+     * Example with TURN for CGNAT:
+     * ```ts
+     * webrtc: {
+     *   createPeer: () => new RTCPeerConnection({
+     *     iceServers: [
+     *       { urls: "stun:stun.l.google.com:19302" },
+     *       { urls: "turn:your-turn-server.com", username: "user", credential: "pass" }
+     *     ]
+     *   })
+     * }
+     * ```
+     */
+    webrtc?: {
+        /**
+         * Factory that creates a new RTCPeerConnection for each upgrade attempt.
+         * The factory should include any ICE servers (STUN/TURN) in the config.
+         */
+        createPeer(): unknown;
+        /** Timeout for the SDP exchange. Default 15s. */
+        timeoutMs?: number;
+    };
+    /** Connection preference: controls candidate selection. */
+    networkMode?: "auto" | "local-only" | "lan-and-relay";
+    /** Hybrid X25519 + ML-KEM-768 session exchange. Default `disabled`. */
+    hybridPq?: "disabled" | "preferred" | "required";
+}
+declare class CrosslinkClient {
+    private readonly options;
+    readonly log: Logger;
+    private identity;
+    private appStore;
+    private hints;
+    private link?;
+    private readonly storage;
+    private deviceCryptoStorage?;
+    private readonly stateListeners;
+    constructor(options?: CrosslinkClientOptions);
+    /**
+     * Builds a client whose identity and paired-app records are encrypted at
+     * rest with a non-extractable WebCrypto key, rather than sitting in
+     * `localStorage` in the clear. Prefer this over `new CrosslinkClient()` in
+     * browsers; the constructor stays synchronous for embedders that supply
+     * their own storage.
+     */
+    static create(options?: Omit<CrosslinkClientOptions, "storage"> & {
+        storage?: SecureStorage;
+        allowPlaintextFallback?: boolean;
+    }): Promise<CrosslinkClient>;
+    get deviceId(): string;
+    listApps(): PairedAppRecord[];
+    forget(appId: string): void;
+    /**
+     * Runs the full pairing flow against a scanned QR / URI: resolve code via
+     * signaling, verify pinned fingerprint, verify challenge signature, confirm
+     * SAS, persist the paired-app record.
+     *
+     * Accepts either a raw `crosslink://pair?…` manifest URI or a hosted
+     * bootstrap URL (`https://…/…&pair=<manifest>`), because iOS Safari has no
+     * handler for the custom scheme — the phone's camera produces the hosted
+     * link and this call transparently unwraps it.
+     */
+    pairFromQr(text: string, requestedCaps?: string[], codeOverride?: string): Promise<PairedAppRecord>;
+    /**
+     * Picks how to carry out the pairing exchange.
+     *
+     * Direct endpoints are tried first and in QR order: a socket straight to the
+     * host is faster, keeps the exchange off any third party, and — crucially —
+     * needs no service to be deployed anywhere. Only when every direct endpoint
+     * refuses does this fall back to a signaling service, and if there is no
+     * signaling endpoint either, the error names every route that was tried
+     * rather than blaming a missing signaling URL.
+     */
+    private openPairingChannel;
+    /**
+     * The origin of the page this client is running in, or null off-browser.
+     *
+     * Used to decide which advertised endpoints the browser will actually permit;
+     * a Node or native client has no such restriction and gets null.
+     */
+    private pageOrigin;
+    /** Connects to a previously paired app; returns the RPC client when online. */
+    connect(appId?: string): Promise<RpcClient>;
+    /**
+     * Attempts to upgrade a relayed session to a direct WebRTC DataChannel.
+     * Runs asynchronously — the relayed session stays active regardless.
+     */
+    private tryWebrtcUpgrade;
+    rpc(): RpcClient;
+    /**
+     * Mints a single-use device-link continuation URI over the current
+     * connection, so this same identity can silently re-establish trust from a
+     * fresh, storage-isolated context (e.g. after "Add to Home Screen" on iOS,
+     * which does not share IndexedDB/localStorage with the Safari tab that
+     * paired). Requires an active, authorized connection.
+     */
+    createDeviceLink(): Promise<{
+        handoffId: string;
+        uri: string;
+        expiresAt: number;
+    }>;
+    /** The live connection, exposed for adapters that upgrade the transport. */
+    get connection(): ClientLink | undefined;
+    /**
+     * Convenience for the iOS / Add-to-Home-Screen flow: accepts the long
+     * `https://…#pair=<uri>` link a phone camera produces, unwraps it, and
+     * delegates to `pairFromQr`.
+     */
+    pairFromBootstrap(bootstrapUrl: string, requestedCaps?: string[], codeOverride?: string): Promise<PairedAppRecord>;
+    /**
+     * Explicit pairing method taking a target host URI/manifest and entered 9-digit code.
+     */
+    pairWithCode(targetUri: string, code: string, requestedCaps?: string[]): Promise<PairedAppRecord>;
+    /** True when the identity seed is encrypted at rest. */
+    get storageEncrypted(): boolean;
+    private ws;
+    get state(): ConnectionState;
+    /**
+     * Subscribes to connection-state changes; returns an unsubscribe function.
+     *
+     * Framework bindings need this. Without it the only way to observe state is
+     * the `onStateChange` constructor option — a single callback fixed at
+     * construction, which a React provider cannot use without polling.
+     */
+    onStateChange(listener: (state: ConnectionState, detail?: Record<string, unknown>) => void): () => void;
+    private publishState;
+    close(): void;
+}
+
+/**
+ * An in-memory `WsLike` pair for tests.
+ *
+ * `WsLike` is the seam the browser SDK is written against, so a fake that
+ * satisfies it lets the pairing flow, transport handling and reconnect logic
+ * be exercised without a network, a server, or a DOM.
+ *
+ * Shipped in the package (rather than kept in a test file) so downstream
+ * embedders can test their own integrations against the same seam.
+ */
+
+interface MockSocketOptions {
+    /** Delay before the socket reports itself open. Default: next microtask. */
+    openDelayMs?: number;
+    /** Fail the connection instead of opening it. */
+    failToOpen?: boolean;
+}
+/** One end of a mock connection. Messages written here surface on its peer. */
+declare class MockSocket implements WsLike {
+    readonly url: string;
+    readyState: number;
+    binaryType: string;
+    /** Everything this end has sent, in order. */
+    readonly sent: unknown[];
+    private readonly listeners;
+    private peer?;
+    constructor(url: string, options?: MockSocketOptions);
+    /** Joins two mock sockets so each one's sends arrive at the other. */
+    static pair(urlA?: string, urlB?: string): [MockSocket, MockSocket];
+    attach(peer: MockSocket): void;
+    addEventListener(type: "open" | "close" | "error", cb: (ev?: unknown) => void): void;
+    addEventListener(type: "message", cb: (ev: {
+        data: unknown;
+    }) => void): void;
+    removeEventListener(type: string, cb: (ev?: unknown) => void): void;
+    send(data: unknown): void;
+    close(code?: number, reason?: string): void;
+    /** Simulates a transport-level failure (not a clean close). */
+    fail(reason?: string): void;
+    /** Pushes a message into this end as though the peer had sent it. */
+    deliver(data: unknown): void;
+    private remoteClosed;
+    private emit;
+}
+
+/**
+ * Encrypted-at-rest storage for browser clients.
+ *
+ * A browser client's identity seed grants access to every app it has paired
+ * with. In `localStorage` that seed is a plain string: readable by any script
+ * that gets a foothold on the origin, visible in devtools, and trivially
+ * exfiltrated by an XSS payload in one line.
+ *
+ * `IndexedDbSecureStorage` encrypts every value with AES-256-GCM under a key
+ * that is generated **non-extractable** and stored as a live `CryptoKey` in
+ * IndexedDB. The browser will hand that key back to this origin's scripts to
+ * *use*, but never to read: `crypto.subtle.exportKey` on it rejects. Stolen
+ * ciphertext is therefore useless off-origin, and an attacker who can run
+ * script on the origin has to stay resident and use the key in place rather
+ * than copying the seed out.
+ *
+ * This is meaningfully stronger than `localStorage` and it is not a vault: a
+ * script running on the origin can still ask the key to decrypt. The honest
+ * summary is that it removes the copy-and-leave attack, not the code-execution
+ * one - see docs/security/threat-model.mdx.
+ *
+ * The synchronous `SecureStorage` interface the SDK uses internally is served
+ * by `hydrate()`, which decrypts everything once into memory and writes back
+ * through asynchronously.
+ */
+
+/** Async counterpart of {@link SecureStorage}. */
+interface AsyncSecureStorage {
+    readonly kind: string;
+    /** True when values are encrypted at rest. */
+    readonly encrypted: boolean;
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<void>;
+    delete(key: string): Promise<void>;
+    keys(): Promise<string[]>;
+}
+declare class IndexedDbSecureStorage implements AsyncSecureStorage {
+    private readonly db;
+    private readonly key;
+    readonly kind = "indexeddb-aes-gcm";
+    readonly encrypted = true;
+    private constructor();
+    /**
+     * Opens the store, generating the non-extractable master key on first use.
+     * Rejects when IndexedDB or WebCrypto is unavailable (private-mode Safari,
+     * insecure origins) so the caller can choose its own fallback rather than
+     * being silently downgraded to plaintext.
+     */
+    static open(): Promise<IndexedDbSecureStorage>;
+    get(name: string): Promise<string | null>;
+    set(name: string, value: string): Promise<void>;
+    delete(name: string): Promise<void>;
+    keys(): Promise<string[]>;
+    /** Destroys every stored value and the master key. */
+    wipe(): Promise<void>;
+}
+/** Adapts an existing synchronous {@link SecureStorage} to the async shape. */
+declare class AsyncStorageAdapter implements AsyncSecureStorage {
+    private readonly inner;
+    private readonly knownKeys;
+    readonly kind: string;
+    readonly encrypted = false;
+    constructor(inner: SecureStorage, kind?: string, knownKeys?: Set<string>);
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<void>;
+    delete(key: string): Promise<void>;
+    keys(): Promise<string[]>;
+}
+/**
+ * A synchronous `SecureStorage` view over an async backend.
+ *
+ * Reads are served from the in-memory cache filled by `hydrate()`. Writes
+ * update the cache immediately and are flushed to the backend in order; a
+ * failed flush is surfaced through `onWriteError` rather than swallowed, since
+ * a silently-unpersisted identity seed means the device loses every pairing on
+ * the next reload.
+ */
+declare class HydratedSecureStorage implements SecureStorage {
+    private readonly backend;
+    private readonly onWriteError?;
+    private readonly cache;
+    /** serializes writes so a rapid set/delete pair cannot land out of order */
+    private flushChain;
+    private pendingWrites;
+    private constructor();
+    static hydrate(backend: AsyncSecureStorage, options?: {
+        onWriteError?(err: unknown, key: string): void;
+    }): Promise<HydratedSecureStorage>;
+    get kind(): string;
+    get encrypted(): boolean;
+    get(key: string): string | null;
+    set(key: string, value: string): void;
+    delete(key: string): void;
+    /** Resolves once every queued write has reached the backend. */
+    flushed(): Promise<void>;
+    get pending(): number;
+    private enqueue;
+}
+interface CreateSecureStorageOptions {
+    /**
+     * Fall back to localStorage when IndexedDB/WebCrypto are unavailable.
+     * Defaults to true - a client that cannot start at all is worse than one
+     * that starts with weaker at-rest protection - but the result reports
+     * `encrypted: false` so the application can tell the user.
+     */
+    allowPlaintextFallback?: boolean;
+    onWriteError?(err: unknown, key: string): void;
+}
+interface SecureStorageResult {
+    storage: SecureStorage;
+    /** Which backend was selected. */
+    kind: string;
+    /** False when the fallback was used and values are stored in the clear. */
+    encrypted: boolean;
+}
+/**
+ * Builds the strongest available client storage: IndexedDB + AES-GCM under a
+ * non-extractable key, falling back to localStorage, then to memory.
+ */
+declare function createSecureStorage(options?: CreateSecureStorageOptions): Promise<SecureStorageResult>;
+
+/**
+ * Client-side signaling peer: resolves a pairing code to a host connection
+ * and shuttles opaque pairing blobs. Never sees keys or SAS material.
+ */
+declare class SignalingPeer {
+    private readonly ws;
+    private queue;
+    private resolvers;
+    private failure?;
+    private failureWaiters;
+    private constructor();
+    static open(wsFactory: () => WsLike, timeoutMs?: number): Promise<SignalingPeer>;
+    /** Resolves a pairing code; returns psid, host connection id, and presence. */
+    resolve(code: string): Promise<{
+        psid: string;
+        hostConn: string;
+        app: {
+            appId: string;
+            name: string;
+            fingerprint: string;
+            pubEdB64: string;
+            pubXB64: string;
+            relay?: {
+                url: string;
+                channel: string;
+            };
+            lan?: {
+                host: string;
+                port: number;
+            };
+        };
+    }>;
+    /** Sends an opaque blob to a connected peer (host or waiter). */
+    sendTo(connId: string, blob: string): void;
+    /** Awaits the next blob delivered from `fromConnId`. */
+    nextBlob(fromConnId: string, timeoutMs?: number): Promise<string>;
+    close(): void;
+    private send;
+    private fail;
+}
+
+/**
+ * Browser-side notification handler.
+ *
+ * Subscribes to the Crosslink notification event over an established session
+ * and surfaces payloads via the Web Notifications API (or a custom handler).
+ * Falls back gracefully when Notifications are unavailable (e.g. SSR, denied
+ * permission).
+ */
+
+interface NotificationHandlerOptions {
+    /** If true, automatically request Notification.permission on construction. */
+    autoRequestPermission?: boolean;
+    /** Custom handler; when provided, bypasses the Web Notifications API. */
+    onNotification?(payload: NotificationPayload): void;
+    /** Called when a notification is clicked (Web Notifications click event). */
+    onClick?(payload: NotificationPayload): void;
+}
+declare class NotificationHandler {
+    private readonly options;
+    private unsub?;
+    private seen;
+    constructor(options?: NotificationHandlerOptions);
+    /**
+     * Begin listening for notifications over an RPC client.
+     * Returns an unsubscribe function.
+     */
+    start(rpc: RpcClient): () => void;
+    stop(): void;
+    private deliver;
+}
+
+/**
+ * Where a pairing card gets its pairing sessions.
+ *
+ * `PairingCard` is the canonical Crosslink pairing UI and stays that. This
+ * module is the other half of the same story: the thing that asks the host for
+ * a session, so the card can drive itself instead of every application writing
+ * the same fetch-and-refresh loop beside it.
+ *
+ * The default source talks to the control surface `createCrosslinkServer`
+ * exposes, so an application that changes nothing gets the whole flow from
+ * `createPairingCard({ target })`. A host the page cannot reach
+ * over HTTP — an Electron renderer behind a preload bridge — supplies its own
+ * object instead. The source decides where a session comes from, never what
+ * the pairing screen looks like.
+ */
+
+/**
+ * The application the host is pairing for, as the host declares it.
+ *
+ * The desktop page does not repeat any of this: `createCrosslinkServer` is
+ * already given an `application` block, and the card renders whatever the host
+ * reports so the widget stays correct when the application is re-branded in
+ * one place.
+ */
+interface PairingApplication {
+    id?: string;
+    name?: string;
+    icon?: string | null;
+    accentColor?: string;
+    backgroundColor?: string;
+    textColor?: string;
+    appearance?: "light" | "dark" | "auto";
+}
+/** A pairing session as the host describes it. */
+interface PairingSession {
+    /** The nine-digit code shown on screen. */
+    code: string;
+    /** Epoch ms after which the code stops working. */
+    expiresAt: number;
+    /** Pre-rendered QR, produced host-side from the bootstrap URL. */
+    qrSvg?: string | null;
+    /** URL the QR encodes, for the "open on this device" fallback. */
+    bootstrapUrl?: string | null;
+    /** Raw `crosslink://pair?…` URI, when the host advertises one. */
+    uri?: string | null;
+    /** Routes this session advertises. */
+    endpoints?: PairingCardEndpoint[] | null;
+    /** Mode the host actually applied, which may differ from the request. */
+    networkMode?: NetworkMode;
+    /** Why remote access produced no public route, when it did not. */
+    remoteNote?: string | null;
+    /** Application identity and palette, so the card needs no local copy. */
+    application?: PairingApplication | null;
+}
+/** How a pairing card reaches the host. */
+interface PairingSource {
+    /** Mints (or returns) the current pairing session. */
+    getSession(mode?: NetworkMode): Promise<PairingSession>;
+    /** Applies a network-mode change before the next session is minted. */
+    setNetworkMode?(mode: NetworkMode): Promise<void>;
+    /**
+     * Notifies the card that the displayed session is stale — a device
+     * redeemed the code, or one was revoked. Returns an unsubscribe function.
+     */
+    subscribe?(listener: (event: PairingSourceEvent) => void): () => void;
+    /** Endpoint the connected-devices dialog reads. */
+    devicesEndpoint?: string;
+    /** Endpoint the devices dialog posts revocations to. */
+    revokeEndpoint?: string;
+}
+type PairingSourceEvent = {
+    type: "invalidate";
+} | {
+    type: "connected";
+    deviceId?: string;
+} | {
+    type: "disconnected";
+    deviceId?: string;
+};
+/** Paths the built-in control surface serves, relative to its base path. */
+declare const CONTROL_ROUTES: {
+    readonly pairing: "/pairing";
+    readonly networkMode: "/network-mode";
+    readonly devices: "/devices";
+    readonly revoke: "/revoke";
+    readonly events: "/events";
+};
+/**
+ * The default source: the HTTP control surface `createCrosslinkServer` exposes.
+ *
+ * It is bound to a base path rather than an origin because that surface is
+ * loopback-only by design — it mints pairing codes and revokes devices, so it
+ * must not be reachable from the network the QR is scanned on.
+ */
+declare function createHttpPairingSource(basePath?: string): PairingSource;
+
+/**
+ * Crosslink brand assets and theming primitives — the single source of truth
+ * for the Crosslink identity rendered by every Crosslink-owned screen.
+ *
+ * The mark is an SVG filled with `currentColor`, so it takes the colour of the
+ * Crosslink surface around it. That is how an application accent tints the logo
+ * without anybody shipping a recoloured copy: `resolveCrosslinkTheme` derives a
+ * logo colour from the accent and then lifts it until it clears the WCAG
+ * contrast floor for graphical objects against the surface behind it.
+ *
+ * Nothing here can remove the mark or the attribution. The helpers always
+ * return a logo and always return attribution text; only colour, size and
+ * placement are configurable.
+ */
+/** `viewBox` of the Crosslink wordmark. */
+declare const CROSSLINK_LOGO_VIEWBOX = "105 363 1060 222";
+/** Path data of the Crosslink wordmark. Always filled with `currentColor`. */
+declare const CROSSLINK_LOGO_PATH = "M233.73 383.42C254.47 380.94 275.68 386.3 293.3 397.22C298.36 400.36 310.34 407.06 306.92 414.39C305.05 418.41 299.18 424.66 294.5 424.16C290.7 423.75 283.6 416.8 279.92 414.57C271.58 409.53 262.05 406.61 252.45 405.27C210.49 399.39 171.23 433.96 172.83 476.5C174.51 521.08 215.67 550.01 258.38 541.73C267.91 539.88 276.87 535.81 284.85 530.38C288.81 527.68 292.08 522.77 297.47 523.95C299.49 524.39 307.14 531.68 307.85 533.67C308.39 535.19 308.34 536.9 307.92 538.44C307.04 541.58 302.8 544.02 300.34 545.88C285.61 557.02 267.9 563.4 249.5 564.79C194.73 568.93 147.61 523.68 151.02 468.5C152.07 451.5 158.16 436.04 167.48 421.97C173.81 412.42 182.42 403.72 192.26 397.74C205.14 389.9 218.77 385.21 233.73 383.42ZM791.59 387.27C795.36 386.55 802.6 386.03 805.44 389.07C807.56 391.34 807.21 394.63 807.24 397.5C807.3 404.17 807.27 410.83 807.25 417.5C807.15 451.5 807.23 485.5 807.25 519.5C807.26 529.5 807.29 539.5 807.27 549.5C807.26 554.33 807.43 559.18 801.47 559.66C797.97 559.94 791 560.91 788.25 558.23C786.05 556.09 786.66 552.28 786.64 549.5C786.6 542.17 786.66 534.83 786.64 527.5C786.54 494.5 786.59 461.5 786.65 428.5C786.67 418.17 786.7 407.83 786.62 397.5C786.59 393.48 786.61 388.22 791.59 387.27ZM1047.5 490.33C1049.96 490.3 1052.92 490.63 1055.26 489.73C1058.8 488.37 1065.75 479.23 1068.61 476.12C1077.64 466.3 1086.84 456.19 1096.5 447C1100.43 443.26 1119.54 442.69 1123.5 445.8C1123.66 451.35 1115.32 457.13 1111.53 461.04C1099.51 473.43 1087.04 485.6 1075.57 498.5C1077.87 503.34 1082.73 507.17 1086.35 511.17C1095.38 521.13 1104.32 531.19 1113.52 541C1115.75 543.37 1125.96 553.61 1126.66 555.81C1127.01 556.89 1126.75 557.43 1126.8 558.5C1123.25 560.55 1118.53 559.73 1114.5 559.69C1110.76 559.66 1106.1 560.51 1102.63 558.88C1098.64 557 1095.59 552.04 1092.65 548.84C1085.62 541.2 1078.7 533.45 1071.74 525.76C1063.43 516.58 1060.8 509.28 1046.79 512.5C1044.96 522.02 1046.59 534.66 1046.57 544.5C1046.57 548.23 1047.48 553.75 1045.59 557.14C1043.49 560.88 1026.82 562.35 1025.95 554.5C1024.58 542.11 1025.96 527.16 1025.95 514.5C1025.94 486.17 1025.87 457.83 1025.93 429.5C1025.95 418.83 1025.94 408.17 1025.9 397.5C1025.89 393.57 1025.68 388.29 1030.61 387.24C1032.49 386.84 1034.59 387.09 1036.5 387.09C1038.56 387.1 1040.88 386.81 1042.81 387.66C1048.5 390.17 1046.49 406.98 1046.51 412.56C1046.56 430.21 1046.47 447.85 1046.53 465.5C1046.56 473.31 1045.12 482.95 1047.5 490.33ZM844.74 395.34C862.3 390.41 870.21 415.48 853.62 421.22C835.59 427.47 827.09 400.31 844.74 395.34ZM463.67 441.41C471.92 440.68 480.11 442.01 487.94 444.53C494.65 446.69 500.51 450.23 506.18 454.35C510.98 457.84 514.79 462.48 518.32 467.22C546.74 505.4 518.83 560.06 472.5 563.08C464.08 563.63 455.77 562.3 447.8 559.63C440.61 557.23 433.85 553.39 428.12 548.4C387.12 512.7 410.35 446.13 463.67 441.41ZM938.73 441.43C964.07 438.8 988.77 454.5 996.81 478.63C1001.03 491.31 999.84 505.34 999.82 518.5C999.8 528.5 999.67 538.5 999.8 548.5C999.85 552.1 1000.71 557.37 996.66 559.21C994.79 560.06 992.49 559.69 990.5 559.67C987.56 559.65 983.54 560.44 981.08 558.44C978.66 556.48 979.13 553.29 979.15 550.5C979.17 544.5 979.16 538.5 979.16 532.5C979.15 506.82 985.32 474.05 954.7 463.73C950.67 462.38 946.75 461.96 942.5 462.04C938.21 462.13 934.22 463.12 930.27 464.75C909.54 473.31 908.83 490.84 908.83 510.5C908.83 519.5 908.79 528.5 908.78 537.5C908.78 543.14 909.77 549.73 908.6 555.26C907.36 561.17 892.64 561.43 889.51 557.98C887.34 555.6 888.08 551.45 888.05 548.5C887.98 539.83 888.06 531.17 888.07 522.5C888.08 510.07 886.92 496.94 889.34 484.69C894.17 460.27 914.52 443.93 938.73 441.43ZM370.81 444.44C378.29 443.39 385.96 443.92 393.5 443.91C396.8 443.91 400.83 443.49 403.26 446.23C405.44 448.69 404.78 452.49 404.76 455.5C404.75 457.24 404.95 459.11 404.32 460.76C401.95 466.94 387.89 464.88 382.5 464.89C368.82 464.9 356.04 469.36 350.54 483.06C345.38 495.93 347.67 523.81 347.69 538.5C347.7 543.73 349 550.79 347.34 555.78C345.69 560.75 334.22 560.97 330.2 559.33C326.24 557.72 327 552.92 327 549.5C327 540.5 326.98 531.5 327 522.5C327.02 510.28 326.04 497.62 328.16 485.54C331.95 463.92 349.33 447.47 370.81 444.44ZM632.82 448.5C630.99 452.96 625.86 456.37 622.98 460.46C622.01 461.84 620.99 464.11 619.29 464.68C614.01 466.44 601.31 464.28 594.65 465.33C578.59 467.86 566.31 480.49 563.75 496.48C562.92 501.66 563.12 506.77 564.57 511.83C566.29 517.82 569.39 523.27 573.67 527.82C584.18 538.98 597.17 538.99 611.5 539.08C626.5 539.17 640.93 539.33 651.61 527.14C656.22 521.88 659.71 515.44 660.73 508.46C661.28 504.62 660.22 499.75 661.65 496.17C663.77 490.82 677.12 490.22 680.29 494.22C682.78 497.37 681.9 502.8 681.67 506.5C680.91 518.95 675.64 530.73 667.69 540.21C651.84 559.1 633.43 559.88 610.5 559.75C595.85 559.66 582.93 559.16 570.01 551.47C529.05 527.1 536.59 463.2 580.88 447.43C593.12 443.07 605.72 444 618.5 443.95C623.82 443.92 630.4 442.77 632.82 448.5ZM672.17 556.5C672.3 555.53 672.1 554.9 672.51 553.96C673.37 551.95 676.41 550 677.9 548.38C680.43 545.62 682.15 542.33 684.5 539.46C697.35 538.01 711.53 541.69 723.35 534.86C748.05 520.57 750.19 485.59 725.32 470.15C716.44 464.64 706.56 464.92 696.5 464.91C681.72 464.89 667.28 463.66 655.36 473.89C648.93 479.41 644.84 487.35 643.27 495.62C642.39 500.25 644.05 506.55 640.99 510.49C636.17 516.71 623.36 514.7 622.14 506.47C618.6 482.48 637.65 455.23 659.96 447.48C671.89 443.34 684.08 443.97 696.5 443.96C712.53 443.94 727.02 445.31 740.35 455.09C776.51 481.63 768.28 540.25 726.62 556.17C714.11 560.95 700.63 559.64 687.5 559.74C682.23 559.78 675.73 561.11 672.17 556.5ZM843.71 444.37C848.02 443.53 856.53 442.92 858.52 447.96C860.51 453 859.14 467.45 859.13 473.5C859.09 492.83 859.08 512.17 859.13 531.5C859.15 538.17 859.16 544.83 859.1 551.5C859.07 555.16 858.76 558.98 854.37 559.61C850.62 560.16 841.54 561.12 839.26 557.25C836.93 553.29 838.56 539.46 838.55 534.5C838.47 514.17 838.44 493.83 838.52 473.5C838.55 467.55 837.15 452.54 839.22 447.7C839.97 445.93 841.87 444.73 843.71 444.37ZM461.77 462.42C418.77 469.25 416.23 530.16 458.13 541.44C464.19 543.07 470.34 543.03 476.49 541.92C517.97 534.45 519.66 475.76 479.83 463.58C474.06 461.82 467.74 461.46 461.77 462.42Z";
+/** Where the attribution link points. */
+declare const CROSSLINK_REPOSITORY = "https://github.com/jacobpowaza/crosslink";
+/** Attribution wording. Not configurable — every Crosslink screen says this. */
+declare const CROSSLINK_ATTRIBUTION_TEXT = "Powered by";
+declare const CROSSLINK_ATTRIBUTION_LINK_TEXT = "Crosslink";
+/**
+ * The whole of what an application may say about how Crosslink-owned screens
+ * look. There is intentionally no slot for markup, templates or renderers: an
+ * application supplies its name, its icon and a few colours, and Crosslink
+ * renders the same pairing, bootstrap, install, offline and revoked screens it
+ * renders everywhere else.
+ */
+interface CrosslinkTheme {
+    /** Application name shown as the screen's title. */
+    appName?: string;
+    /** URL (or data URI) of the application icon. */
+    appIcon?: string;
+    /** Application accent, used for actions and to tint the Crosslink mark. */
+    accentColor?: string;
+    /** Page background behind Crosslink-owned screens. */
+    backgroundColor?: string;
+    /** Primary text colour. Derived from the background when omitted. */
+    textColor?: string;
+    /** Forces a palette instead of deriving one from `backgroundColor`. */
+    appearance?: "light" | "dark" | "auto";
+}
+interface ResolvedCrosslinkTheme {
+    appName: string;
+    appIcon: string | null;
+    accentColor: string;
+    backgroundColor: string;
+    surfaceColor: string;
+    textColor: string;
+    mutedColor: string;
+    dividerColor: string;
+    /** Colour the Crosslink mark is drawn in — accent, lifted for contrast. */
+    logoColor: string;
+    /** Colour the attribution text is drawn in. */
+    attributionColor: string;
+    appearance: "light" | "dark";
+}
+/** WCAG 2.1 minimum contrast for a graphical object such as the logo. */
+declare const LOGO_MIN_CONTRAST = 3;
+/** WCAG 2.1 minimum contrast for the attribution, which is small body text. */
+declare const ATTRIBUTION_MIN_CONTRAST = 4.5;
+interface Rgb {
+    r: number;
+    g: number;
+    b: number;
+}
+/**
+ * Parses `#rgb`, `#rrggbb`, `#rrggbbaa` and `rgb()/rgba()`.
+ *
+ * Anything else — a named colour, a gradient, a CSS variable — returns null,
+ * and callers fall back to a palette default rather than compute a contrast
+ * ratio against a colour they could not read.
+ */
+declare function parseColor(input: string | undefined | null): Rgb | null;
+/** WCAG contrast ratio between two colours, 1 (identical) to 21 (max). */
+declare function contrastRatio(a: Rgb, b: Rgb): number;
+/**
+ * Resolves the application's branding metadata into the complete token set the
+ * Crosslink screens draw with.
+ *
+ * Every field has a Crosslink default, so an application that configures
+ * nothing still gets the standard experience; and every colour that carries
+ * brand meaning — the mark, the attribution — is contrast-checked here rather
+ * than at each call site.
+ */
+declare function resolveCrosslinkTheme(theme?: CrosslinkTheme): ResolvedCrosslinkTheme;
+interface CrosslinkLogoOptions {
+    /** CSS width. A number is treated as pixels. Default `140px`. */
+    width?: string | number;
+    /** Explicit colour. Defaults to `currentColor` so the surface decides. */
+    color?: string;
+    /** Extra class on the `<svg>`. */
+    className?: string;
+    /** Extra inline styles appended after the defaults. */
+    style?: string;
+    /** Accessible name. Default "Crosslink". */
+    title?: string;
+}
+/**
+ * Renders the Crosslink wordmark as an SVG string.
+ *
+ * It is `role="img"` with a `<title>` rather than a decorative graphic: on the
+ * offline and revoked screens the mark is the only thing naming what is trying
+ * to reconnect, so a screen reader has to reach it.
+ */
+declare function crosslinkLogoSvg(options?: CrosslinkLogoOptions): string;
+/** Builds the wordmark as a live DOM node. */
+declare function createCrosslinkLogo(options?: CrosslinkLogoOptions): HTMLElement;
+
+/**
+ * Canonical reusable Crosslink Pairing Widget (CrosslinkConnect).
+ *
+ * Provides a standardized, brand-consistent 3-column pairing card:
+ * [ App Logo & Blurb ] | [ Scan QR ] | [ Pairing Code Pills ]
+ *
+ * The settings cog exposes the host's own `networkMode` values and nothing
+ * else. There is deliberately no tunnel-provider setup here: Crosslink needs no
+ * ngrok token, no Cloudflare account, and no port forwarding, so a UI that asks
+ * for them would be advertising configuration the framework does not require.
+ *
+ * The card also shows which routes the current QR actually advertises, because
+ * "remote" either produced a public endpoint or it did not — the widget never
+ * implies reachability the host has not confirmed.
+ *
+ * Fully customizable via options and CSS custom properties:
+ *   --cl-bg, --cl-fg, --cl-muted, --cl-divider, --cl-pill, --cl-pill-text,
+ *   --cl-border, --cl-radius
+ */
+
+interface PairingCardTheme {
+    bg?: string;
+    fg?: string;
+    muted?: string;
+    divider?: string;
+    pill?: string;
+    pillText?: string;
+    /** CSS border shorthand. Default: `1px solid #000000`. */
+    border?: string;
+    radius?: string;
+}
+/**
+ * The host's network mode. These are the same four values `createCrosslinkServer`
+ * accepts, so what the user picks here can be handed straight back to the host.
+ */
+type NetworkMode = "auto" | "local-only" | "lan-and-relay" | "remote";
+/** Endpoint kinds as advertised in a v2 pairing URI. */
+interface PairingCardEndpoint {
+    kind: "lan" | "wan" | "sig" | "relay" | "tunnel";
+    url: string;
+}
+interface PairingCardOptions {
+    /** Target DOM container element or selector to mount into */
+    target?: HTMLElement | string;
+    /** Application or framework name (e.g. "Crosslink Notes", "Crosslink Chat") */
+    appName?: string;
+    /** Informational blurb describing security and app pairing */
+    blurb?: string;
+    /**
+     * URL or inline SVG of the *application's* icon, shown beside the app name.
+     *
+     * It never replaces the Crosslink mark: the card renders both, so a paired
+     * device sees which application it is joining and which framework is
+     * securing the connection.
+     */
+    appIcon?: string;
+    /**
+     * Application branding — name, icon, and colours. These are the only visual
+     * knobs the card exposes; there is no renderer or markup slot, because every
+     * Crosslink application is meant to present the same pairing experience.
+     */
+    brand?: CrosslinkTheme;
+    /** Initial pairing code (e.g. "938472910") */
+    code?: string;
+    /** Initial QR code SVG string or image URL */
+    qr?: string;
+    /** Expiration timestamp (epoch ms) or descriptive string */
+    expiresAt?: number | string;
+    /** Callback triggered when the user clicks 'Refresh code' */
+    onRefresh?: () => void | Promise<void>;
+    /** Callback triggered when connection network mode changes */
+    onNetworkModeChange?: (mode: NetworkMode) => void | Promise<void>;
+    /** Current active network mode */
+    networkMode?: NetworkMode;
+    /** Security doc hyperlink for Open LAN info knob */
+    securityGuideUrl?: string;
+    /** LAN only guide hyperlink */
+    lanGuideUrl?: string;
+    /** Remote-access guide hyperlink */
+    remoteGuideUrl?: string;
+    /** Custom theme color overrides */
+    theme?: PairingCardTheme;
+    /** Endpoint URL to fetch paired device info. Default: /api/devices */
+    devicesEndpoint?: string;
+    /** Endpoint URL to revoke device access. Default: /api/revoke */
+    revokeEndpoint?: string;
+    /**
+     * Where the self-driving card gets pairing sessions.
+     *
+     * Omit this option for the canonical Crosslink system endpoints at
+     * `/__crosslink` on the page's own origin. `true` is retained as a legacy
+     * alias for that default; a string names a different base path; an object is
+     * a custom transport for a host the page cannot reach over HTTP. With any of them the
+     * card mints its own pairing session, renders the QR and code, replaces the
+     * code before it expires, mints a fresh one when a device redeems the old
+     * one, and applies connection-mode changes — the loop every application used
+     * to write beside it.
+     *
+     * Set `false` to keep the card controlled: `update()` is then the only way
+     * state changes, which is what a host that already owns its own pairing loop
+     * wants. This explicit opt-out keeps the ordinary integration zero-config.
+     */
+    source?: false | true | string | PairingSource;
+    /** Seconds of headroom before expiry at which a new code is minted. Default 15. */
+    refreshLeadSeconds?: number;
+    /** Called after the card mints a session. Self-driving mode only. */
+    onSession?: (session: PairingSession) => void;
+    /** Called when a paired device connects. Self-driving mode only. */
+    onDeviceConnected?: (deviceId?: string) => void;
+    /** Called after the card renders a minting failure. Self-driving mode only. */
+    onError?: (error: Error) => void;
+    /** Initial connection status line shown under the pairing code. */
+    status?: string;
+    /** Whether to inject default CSS styles into document head. Default true */
+    injectStyles?: boolean;
+}
+interface PairingCardState {
+    code?: string | null;
+    qr?: string | null;
+    expiresAt?: number | string | null;
+    error?: string | null;
+    /** Short stable identifier rendered in the QR slot (for example `CL-P409`). */
+    errorCode?: string | null;
+    loading?: boolean;
+    networkMode?: NetworkMode;
+    /** Routes the current QR advertises, straight from `PairingCodeInfo.endpoints`. */
+    endpoints?: PairingCardEndpoint[] | null;
+    /** Host-side note about remote access, e.g. why no `wan` endpoint exists. */
+    remoteNote?: string | null;
+    /** Connection status line, e.g. "Waiting for a device to scan". */
+    status?: string | null;
+    /** True once a paired device is connected; the status line turns positive. */
+    connected?: boolean;
+}
+declare function injectPairingCardStyles(): void;
+declare class PairingCard {
+    readonly element: HTMLElement;
+    private options;
+    private logoEl;
+    private blurbEl;
+    private refreshBtn;
+    private qrWrapEl;
+    private codePillsEl;
+    private hintEl;
+    private settingsPopover;
+    private routeSummaryEl;
+    private modePendingEl;
+    private appRowEl;
+    private statusEl;
+    private brand;
+    private currentMode;
+    private expiryTimer;
+    private source;
+    private refreshTimer;
+    private unsubscribeSource;
+    private destroyed;
+    private inFlight;
+    private refreshQueued;
+    private connectedDevices;
+    constructor(options?: PairingCardOptions);
+    /**
+     * Connects the card to a session source and starts the loop.
+     *
+     * Called from the constructor when `options.source` is set. Split out so a
+     * card built before its transport exists — an Electron renderer waiting for
+     * a preload bridge, say — can start driving later without a second class.
+     */
+    attachSource(source: true | string | PairingSource): void;
+    /**
+     * Mints a fresh pairing session and renders it.
+     *
+     * Concurrent calls collapse onto the one in flight. The expiry timer, the
+     * refresh button and a host-side invalidation can all fire inside the same
+     * second, and three codes minted back to back would invalidate two of them
+     * before anybody could finish scanning.
+     *
+     * Collapsing cannot simply drop the extra calls, though. A request that
+     * arrives mid-flight may be the one that matters — the host reporting that a
+     * device just redeemed the code being minted — so it is remembered and run
+     * once the current mint settles, leaving the card showing a live code rather
+     * than one that is already spent.
+     */
+    refresh(): Promise<void>;
+    private mintSession;
+    /**
+     * Takes the application's identity from the host.
+     *
+     * `createCrosslinkServer` is already configured with an `application` block —
+     * name, icon, accent, background — so a page that mounts the card needs to
+     * repeat none of it. Options still win where they are given: an application
+     * that wants the pairing screen to differ from its host metadata says so
+     * explicitly, and nothing here overrides that.
+     */
+    private adoptHostApplication;
+    private sessionStatusText;
+    private scheduleSessionRefresh;
+    private clearRefreshTimer;
+    private handleSourceEvent;
+    private normalizeMode;
+    private createSettingsPopover;
+    toggleSettings(open?: boolean): void;
+    setNetworkMode(mode: NetworkMode): void;
+    private applyNetworkMode;
+    /**
+     * Shows the popover as busy and refuses further changes until it settles.
+     *
+     * The radios keep their state rather than being re-rendered: the user has
+     * already chosen, and the question is only whether the host agrees yet.
+     */
+    private setSettingsPending;
+    getNetworkMode(): NetworkMode;
+    mount(target: HTMLElement | string): this;
+    update(state: PairingCardState): this;
+    applyTheme(theme?: PairingCardTheme): this;
+    setBlurb(html: string): this;
+    private syncNetworkMode;
+    /**
+     * Draws the Crosslink mark. It takes no argument on purpose: the mark is the
+     * one element of this card an application cannot swap out, so there is no
+     * code path here that renders something else in its place.
+     */
+    private renderBrandMark;
+    /** The application's own icon and name, beside the framework mark. */
+    private renderAppRow;
+    private renderStatus;
+    /**
+     * Applies the application palette to the card's CSS variables.
+     *
+     * The mark inherits `--cl-logo`. On this card that is the card's own
+     * foreground rather than the application accent: the pairing card is a
+     * Crosslink surface, and drawing the wordmark in the app's colour reads as
+     * the application's logo instead of the framework's. The application accent
+     * still drives the card's own accented elements. `resolveCrosslinkTheme`
+     * derives the foreground from the background, so it clears contrast on a
+     * light card as well as a dark one.
+     */
+    private applyBrand;
+    /** Re-themes a mounted card; the mark and attribution are unaffected. */
+    setBrand(brand: CrosslinkTheme): this;
+    /** The palette actually in use, after contrast correction. */
+    getBrand(): ResolvedCrosslinkTheme;
+    private renderQr;
+    private renderCode;
+    private renderLoading;
+    private renderQrSkeleton;
+    private renderCodeSkeleton;
+    private renderError;
+    private openErrorModal;
+    private renderExpiry;
+    /**
+     * Shows the routes the current QR advertises.
+     *
+     * Naming them is the honest version of a connectivity indicator: if the host
+     * asked for remote access and the router said no, there is simply no `wan`
+     * route in the list, and the note says why.
+     */
+    private renderRoutes;
+    private handleRefresh;
+    private openConnectedDevicesModal;
+    private renderConnectedDevicesModal;
+    destroy(): void;
+}
+/**
+ * Maps whatever a host reports into one of the four supported modes.
+ *
+ * Older builds persisted names like `open-lan-remote` and `ngrok` in
+ * localStorage; those are folded onto their nearest current meaning so an
+ * upgraded app does not start with a broken selection.
+ */
+declare function normalizeNetworkMode(mode: string | undefined | null): NetworkMode;
+/** Convenience factory for creating a pairing card */
+declare function createPairingCard(options?: PairingCardOptions): PairingCard;
+
+/**
+ * The Crosslink attribution badge shown on Crosslink-owned mobile screens.
+ *
+ * It renders the mark and the wording together and offers no option that
+ * removes either: an application chooses colour, size and placement, and the
+ * attribution is what is left. Colour defaults come from the shared brand
+ * resolver, so the badge lands on the right side of the WCAG contrast floor
+ * against whatever background the application configured.
+ */
+type PoweredByPlacement = "top-left" | "top-center" | "top-right" | "bottom-left" | "bottom-center" | "bottom-right" | "inline";
+interface PoweredByCrosslinkOptions {
+    /** Container or selector to mount into. Defaults to document.body. */
+    target?: HTMLElement | string;
+    /** Text before the Crosslink link. */
+    text?: string;
+    /** Linked product name. */
+    linkText?: string;
+    /** Optional text after the link. */
+    suffix?: string;
+    /** CSS color for the attribution. */
+    color?: string;
+    /** Any CSS font-size value, or a pixel number. */
+    size?: string | number;
+    /** Screen placement, or `inline` to participate in the target's layout. */
+    placement?: PoweredByPlacement;
+    /** Distance from the selected screen edges. */
+    offset?: string | number;
+    /** Optional background behind the attribution. */
+    background?: string;
+    /** Optional extra class for application-specific styling. */
+    className?: string;
+    /** Stacking order for fixed placements. */
+    zIndex?: number;
+    /** Application accent, used to tint the mark. */
+    accentColor?: string;
+    /** Background the badge sits on, used for the contrast correction. */
+    backgroundColor?: string;
+    /** Height of the mark. Default scales with `size`. */
+    logoWidth?: string | number;
+}
+/**
+ * Small reusable attribution shown by Crosslink mobile bootstrap applications.
+ * It is also exported for apps that own their lifecycle UI directly.
+ */
+declare class PoweredByCrosslink {
+    readonly element: HTMLElement;
+    private options;
+    constructor(options?: PoweredByCrosslinkOptions);
+    mount(target?: HTMLElement | string): this;
+    update(options: Partial<PoweredByCrosslinkOptions>): this;
+    destroy(): void;
+    private render;
+}
+declare function createPoweredByCrosslink(options?: PoweredByCrosslinkOptions): PoweredByCrosslink;
+
+/**
+ * Crosslink Offline Shell — Framework-level offline/fail-state system for PWAs.
+ *
+ * This module provides a cached PWA shell that launches when the Crosslink host
+ * is completely unreachable. It handles:
+ * - Offline UI display with developer-customizable branding
+ * - Periodic reconnection attempts with exponential backoff
+ * - Silent cryptographic authentication when host returns
+ * - Automatic transition to developer app on successful auth
+ * - Proper distinction between "host offline" vs "pairing required"
+ */
+
+interface OfflineConfig {
+    /** Title shown in offline state. Default: "<AppName> is unavailable" or "Crosslink is inactive" */
+    title?: string;
+    /** Message shown in offline state. Default mentions opening desktop app */
+    message?: string;
+    /** App icon URL for offline screen. Defaults to PWA manifest icon */
+    icon?: string;
+    /** App name for offline screen. Defaults to PWA name */
+    appName?: string;
+    /** Theme color for offline screen */
+    themeColor?: string;
+    /** Background color for offline screen */
+    bgColor?: string;
+    /** Application accent. Tints the Crosslink mark and the retry action. */
+    accentColor?: string;
+    /** Primary text colour. Derived from the background when omitted. */
+    textColor?: string;
+    /** Forces a palette instead of deriving one from the background. */
+    appearance?: "light" | "dark" | "auto";
+    /** Troubleshooting guide shown after the retry action. */
+    debuggingUrl?: string;
+}
+type OfflineConnectionState = "connecting" | "connected" | "host-offline" | "authentication-required" | "authentication-failed" | "reconnecting";
+interface HostReachabilityResult {
+    reachable: boolean;
+    hostInfo?: {
+        relay?: {
+            url: string;
+            channel: string;
+        };
+        lan?: {
+            host: string;
+            port: number;
+        };
+        fingerprint?: string;
+    };
+}
+interface OfflineShellOptions {
+    /** Crosslink client options */
+    clientOptions?: CrosslinkClientOptions;
+    /** Existing or custom client instance */
+    client?: CrosslinkClient;
+    /** Offline UI configuration */
+    offline?: OfflineConfig;
+    /** Called when transitioning to connected state - load the developer app */
+    onConnected: (rpc: RpcClient, client: CrosslinkClient) => Promise<void> | void;
+    /** Called when authentication is required (revoked, unknown device, missing key, etc.) */
+    onAuthRequired: () => Promise<void> | void;
+    /** Called when connection state changes */
+    onStateChange?: (state: OfflineConnectionState, detail?: Record<string, unknown>) => void;
+    /** Minimum time between reconnection attempts (ms). Default: 1000 */
+    minRetryDelay?: number;
+    /** Maximum time between reconnection attempts (ms). Default: 30000 */
+    maxRetryDelay?: number;
+    /** Check host reachability interval when offline (ms). Default: 10000 */
+    reachabilityCheckInterval?: number;
+    /** Service Worker script URL to register. Default: "/sw.js" */
+    serviceWorkerUrl?: string;
+    /** Auto-register service worker in browser. Default: true */
+    autoRegisterServiceWorker?: boolean;
+    /** Auto-mount offline UI when host-offline. Default: true */
+    autoMountOfflineUI?: boolean;
+    /** Custom DOM container for offline UI. Defaults to document.body */
+    container?: HTMLElement;
+}
+/**
+ * Default offline configuration values
+ */
+declare const DEFAULT_OFFLINE_CONFIG: Required<OfflineConfig>;
+declare class CrosslinkOfflineShell {
+    private client;
+    private options;
+    private currentState;
+    private reachabilityTimer;
+    private reconnectTimer;
+    private visibilityHandler;
+    private onlineHandler;
+    private isPageVisible;
+    private attemptCount;
+    private isAttempting;
+    private offlineElement;
+    constructor(options: OfflineShellOptions);
+    /**
+     * Initialize and start the offline shell. This should be called early
+     * in the PWA lifecycle, before attempting any connection.
+     */
+    start(): Promise<void>;
+    /**
+     * Attempt silent cryptographic authentication with the paired host.
+     * This is the core "trusted device" flow - no user interaction required.
+     */
+    private attemptSilentAuth;
+    /**
+     * Handle connection state changes from underlying ClientLink.
+     */
+    private handleClientStateChange;
+    /**
+     * Handle connection errors and determine the correct state.
+     * Critical: distinguish between "host offline" vs "authentication required / revoked".
+     */
+    private handleConnectionError;
+    /**
+     * Show the host-offline UI and start periodic reconnection attempts.
+     */
+    private showHostOffline;
+    /**
+     * Schedule a reconnection attempt with exponential backoff and jitter.
+     */
+    private scheduleReconnect;
+    /**
+     * Immediately trigger a silent reconnection attempt.
+     */
+    reconnectNow(): Promise<void>;
+    /**
+     * Start periodic reachability checks while in host-offline state.
+     */
+    private startReachabilityChecks;
+    private cancelReachabilityChecks;
+    /**
+     * Check if the host signaling/relay is reachable.
+     */
+    checkHostReachability(appId: string): Promise<HostReachabilityResult>;
+    private cancelTimers;
+    private setState;
+    private getHints;
+    private setupVisibilityHandlers;
+    private setupOnlineHandler;
+    /**
+     * Mount the offline UI into the DOM
+     */
+    mountOfflineUI(): void;
+    /**
+     * Unmount the offline UI from the DOM
+     */
+    unmountOfflineUI(): void;
+    /**
+     * Update the status text shown in the offline UI
+     */
+    updateOfflineStatus(text: string): void;
+    /**
+     * Get current connection state
+     */
+    getState(): OfflineConnectionState;
+    /**
+     * Force a reconnection attempt immediately (e.g. user taps "Retry")
+     */
+    forceReconnect(): Promise<void>;
+    /**
+     * Clean up resources, event listeners, and timers
+     */
+    destroy(): void;
+    /**
+     * Get the underlying CrosslinkClient
+     */
+    getClient(): CrosslinkClient;
+}
+/**
+ * Create the offline shell UI element.
+ * Returns a DOM element that can be mounted into the document.
+ */
+declare function createOfflineUI(config: OfflineConfig, onRetry?: () => void): HTMLElement;
+/**
+ * Update the offline UI status text
+ */
+declare function updateOfflineStatus(text: string): void;
+/**
+ * Remove the offline UI
+ */
+declare function removeOfflineUI(): void;
+
+/**
+ * What this browser origin actually permits.
+ *
+ * Crosslink's mobile promise — pair once, add to home screen, launch later and
+ * see a Crosslink reconnect screen instead of the browser's error page —
+ * depends on browser capabilities that are gated on the *origin*, not on the
+ * framework. A page served from `http://192.168.1.110:8787` gets none of them:
+ *
+ *  - `navigator.serviceWorker.register` rejects outside a secure context, so
+ *    there is no cached shell and an offline launch shows the browser's own
+ *    "cannot connect to server" page.
+ *  - `crypto.subtle` is undefined outside a secure context, so device keys
+ *    cannot be wrapped in a non-extractable WebCrypto key and fall back to
+ *    plaintext at rest.
+ *  - Chromium's install prompt requires https.
+ *
+ * And the inverse trade-off is just as real: from an https origin the browser
+ * refuses `ws://` entirely, so the LAN shortcut that makes Crosslink fast is
+ * unavailable to exactly the origins that can install.
+ *
+ * This module reports those facts rather than hiding them. Everything above is
+ * a browser rule; no amount of framework code changes it, so the honest thing
+ * is to name which parts of the experience a given origin can deliver.
+ */
+interface BootstrapEnvironment {
+    /** Origin of the page, or null when not running in a browser. */
+    origin: string | null;
+    /** `window.isSecureContext`. The gate on nearly everything below. */
+    secureContext: boolean;
+    /** A service worker can be registered, so an offline shell can be cached. */
+    serviceWorkerAvailable: boolean;
+    /** `crypto.subtle` exists, so device keys can be non-extractable. */
+    webCryptoAvailable: boolean;
+    /** The page is already running as an installed app. */
+    standalone: boolean;
+    /** An install to the home screen will behave like an app, not a bookmark. */
+    installable: boolean;
+    /** Insecure `ws://` endpoints are unusable from this origin. */
+    insecureTransportBlocked: boolean;
+    /** One plain sentence per capability this origin cannot provide. */
+    limitations: string[];
+}
+/**
+ * Describes the current origin's capabilities.
+ *
+ * Safe to call anywhere: outside a browser every capability reads false and
+ * `origin` is null, which is the correct answer for a Node or native client
+ * rather than a reason to throw.
+ */
+declare function describeBootstrapEnvironment(): BootstrapEnvironment;
+
+/**
+ * Crosslink Mobile Bootstrap & Lifecycle State Machine
+ *
+ * Implements the authoritative framework-level onboarding and authorization flow:
+ *   1. Host Offline -> Prebuilt Offline Screen (auto-reconnect with backoff)
+ *   2. No Valid Credential -> Prebuilt Pairing Screen (9-digit code entry + host validation)
+ *   3. First Successful Pairing -> Prebuilt Add to Home Screen Screen (nudge + Continue in Browser)
+ *   4. Authorized -> Developer Mobile Application mounted & revealed
+ *   5. Revocation -> Device immediately revoked, credentials cleared, returns to Pairing Screen
+ *
+ * The developer application is never exposed before authorization is established.
+ */
+
+declare const INSTALL_HANDOFF_QUERY_KEY = "crosslink_install";
+declare const INSTALL_HANDOFF_COOKIE = "crosslink_install";
+declare const INSTALL_HANDOFF_CONTEXT_COOKIE = "crosslink_install_context";
+type MobileBootstrapState = "initializing" | "offline" | "pairing-required" | "pairing" | "add-to-home-screen" | "authorized";
+interface OnboardingConfig {
+    appName?: string;
+    icon?: string;
+    themeColor?: string;
+    instructions?: string;
+}
+interface MobileBootstrapOptions {
+    /** Target DOM container for prebuilt screens. Defaults to document.body */
+    container?: HTMLElement;
+    /** Application metadata */
+    appId?: string;
+    appName?: string;
+    capabilities?: string[];
+    /** Client options or existing client instance */
+    client?: CrosslinkClient;
+    clientOptions?: CrosslinkClientOptions;
+    /** Offline screen branding */
+    offline?: OfflineConfig;
+    /** Add to home screen onboarding branding */
+    onboarding?: OnboardingConfig;
+    /** Called ONLY when the device is authorized and connected */
+    onAuthorized: (rpc: RpcClient, client: CrosslinkClient) => Promise<void> | void;
+    /** Called when authorization is lost (revoked, offline, reset) to hide/unmount developer app */
+    onUnauthorized?: () => Promise<void> | void;
+    /** Called on state machine transitions */
+    onStateChange?: (state: MobileBootstrapState, detail?: Record<string, unknown>) => void;
+    /** Service worker options */
+    autoRegisterServiceWorker?: boolean;
+    serviceWorkerUrl?: string;
+    /** Pairing URI override; otherwise read from `#pair=` / `?pair=` or storage. */
+    pairingUri?: string;
+    /** Styling and placement for the mandatory Crosslink attribution. */
+    poweredBy?: PoweredByCrosslinkOptions;
+    /**
+     * Called once with what this origin can actually deliver.
+     *
+     * Lets a host surface the same truth the bootstrap logs — for example that an
+     * http LAN origin cannot cache the offline screen — rather than leaving it
+     * to be found on a phone.
+     */
+    onEnvironment?: (environment: BootstrapEnvironment) => void;
+}
+/** Check if running as a standalone installed PWA */
+declare function isStandalone(): boolean;
+/** Wipe all credentials, pairing tokens, and caches on the phone */
+declare function resetDeviceStorage(): Promise<void>;
+declare function injectBootstrapStyles(): void;
+declare class CrosslinkMobileBootstrap {
+    private client;
+    private options;
+    private state;
+    private currentScreenElement;
+    private reconnectTimer;
+    private reachabilityTimer;
+    private visibilityHandler;
+    private onlineHandler;
+    private isAttempting;
+    private attemptCount;
+    private activeRpc;
+    private targetPairingUri;
+    private poweredBy;
+    private environment;
+    constructor(options: MobileBootstrapOptions);
+    /**
+     * Start the authoritative bootstrap state machine.
+     * This is the single entry point controlling what the mobile device sees.
+     */
+    start(): Promise<void>;
+    private extractPairingUriFromLocation;
+    private discoverInstallHandoff;
+    private clearInstallState;
+    private getEffectiveAppId;
+    private completedOnboardingApps;
+    private isOnboardingCompleted;
+    private markOnboardingCompleted;
+    private clearOnboarding;
+    /** Prepares the cookie-first Safari -> standalone install boundary. */
+    private prepareDeviceLinkHandoff;
+    /**
+     * Silent cryptographic authentication with stored credentials.
+     */
+    private attemptSilentAuth;
+    private handleAuthError;
+    private handleClientStateChange;
+    /**
+     * Transition state machine to a new state and mount appropriate UI.
+     */
+    private transitionTo;
+    private unmountCurrentScreen;
+    private ensurePoweredBy;
+    /**
+     * Handle user submitting pairing code on Pairing Screen (Screen A).
+     */
+    private handlePairingSubmit;
+    /**
+     * Create prebuilt Pairing Screen UI (Screen A).
+     */
+    private createPairingScreen;
+    /**
+     * Create prebuilt Add to Home Screen UI (Screen B).
+     */
+    private createAddToHomeScreen;
+    /**
+     * Prebuilt SAS Confirmation Modal.
+     */
+    private showSasConfirmation;
+    private scheduleReconnect;
+    forceReconnect(): Promise<void>;
+    private cancelTimers;
+    private setupListeners;
+    /** What this origin permits, once `start()` has probed it. */
+    getEnvironment(): BootstrapEnvironment | null;
+    getState(): MobileBootstrapState;
+    getClient(): CrosslinkClient;
+    destroy(): void;
+}
+
+/**
+ * Crosslink Service Worker Template & Generator
+ *
+ * Implements the framework-level offline shell caching strategy:
+ * - Caches the minimum bootstrap shell (HTML, JS, CSS, manifest, icons)
+ * - Network-first for navigation requests with fallback to cached shell on offline/timeout
+ * - Cache-first with network fallback for static shell assets
+ * - Strictly excludes API, RPC, WebSocket, and pairing/auth endpoints from caching
+ * - Versioned cache namespaces with automatic cleanup of old caches
+ */
+interface ServiceWorkerConfig {
+    /** Cache version - increment to invalidate old caches */
+    version: string;
+    /** Assets to precache - the minimum shell for offline launch */
+    precacheAssets: string[];
+    /** Maximum navigation wait before showing the cached reconnect shell. */
+    navigationTimeoutMs?: number;
+}
+declare const DEFAULT_SERVICE_WORKER_CONFIG: ServiceWorkerConfig;
+/**
+ * Generate the standalone Service Worker JavaScript code.
+ */
+declare function generateServiceWorker(config?: Partial<ServiceWorkerConfig>): string;
+/**
+ * Default generated Service Worker script
+ */
+declare const DEFAULT_SERVICE_WORKER: string;
+/**
+ * Create a Service Worker config from PWA config
+ */
+declare function createServiceWorkerConfig(pwaConfig: {
+    version?: string;
+    icons?: Array<{
+        src: string;
+        sizes?: string;
+    }>;
+    startUrl?: string;
+    manifestPath?: string;
+}): ServiceWorkerConfig;
+
+/**
+ * The two ways a phone can carry out the pairing exchange with a host.
+ *
+ * The cryptographic protocol is identical either way — claim, challenge, SAS,
+ * complete — so the client speaks to a `PairingChannel` and does not care which
+ * one it got. What differs is only who moves the frames:
+ *
+ * - `DirectPairingChannel` opens a WebSocket straight to the host, using an
+ *   endpoint from the QR (`lan~ws://…` on the same Wi-Fi, `wan~ws://…` through
+ *   a router port mapping). No service in the middle, nothing to deploy, and
+ *   nothing to pay for — this is the zero-infrastructure path.
+ * - `BrokeredPairingChannel` relays frames through a signaling service, for
+ *   hosts that are only reachable that way.
+ *
+ * Direct is tried first; brokered is the fallback.
+ */
+
+interface PairingHostInfo {
+    appId: string;
+    name: string;
+    fingerprint: string;
+    pubEdB64: string;
+    pubXB64: string;
+    relay?: {
+        url: string;
+        channel: string;
+    };
+    lan?: {
+        host: string;
+        port: number;
+    };
+}
+interface ResolvedPairingSession {
+    psid: string;
+    app: PairingHostInfo;
+}
+interface PairingChannel {
+    readonly kind: "direct" | "brokered";
+    /** Turns the scanned 9-digit code into a session id plus host presence. */
+    resolve(code: string): Promise<ResolvedPairingSession>;
+    send(frame: object): void;
+    /** Next frame from the host. Rejects if the channel fails first. */
+    next(): Promise<Record<string, unknown>>;
+    close(): void;
+}
+/** Pairing over a WebSocket opened straight to the host. */
+declare class DirectPairingChannel implements PairingChannel {
+    private readonly ws;
+    readonly kind: "direct";
+    private queue;
+    private waiters;
+    private failure?;
+    private constructor();
+    static open(url: string, wsFactory: (url: string) => WsLike, timeoutMs: number): Promise<DirectPairingChannel>;
+    resolve(code: string): Promise<ResolvedPairingSession>;
+    send(frame: object): void;
+    next(): Promise<Record<string, unknown>>;
+    close(): void;
+    private deliver;
+    private fail;
+}
+/** Pairing relayed through a signaling service. */
+declare class BrokeredPairingChannel implements PairingChannel {
+    private readonly peer;
+    readonly kind: "brokered";
+    private hostConn;
+    constructor(peer: SignalingPeer);
+    resolve(code: string): Promise<ResolvedPairingSession>;
+    send(frame: object): void;
+    next(): Promise<Record<string, unknown>>;
+    close(): void;
+}
+
+declare function createCrosslinkClient(options?: Omit<CrosslinkClientOptions, "storage"> & {
+    storage?: SecureStorage;
+}): CrosslinkClient;
+/**
+ * Preferred browser entry point: identity and paired-app records are encrypted
+ * at rest under a non-extractable WebCrypto key. Use `createCrosslinkClient`
+ * only when you are supplying your own storage or need a synchronous factory.
+ */
+declare function createSecureCrosslinkClient(options?: Omit<CrosslinkClientOptions, "storage"> & {
+    allowPlaintextFallback?: boolean;
+}): Promise<CrosslinkClient>;
+
+export { ATTRIBUTION_MIN_CONTRAST, type AsyncSecureStorage, AsyncStorageAdapter, type BootstrapEnvironment, BrokeredPairingChannel, CONTROL_ROUTES, CROSSLINK_ATTRIBUTION_LINK_TEXT, CROSSLINK_ATTRIBUTION_TEXT, CROSSLINK_LOGO_PATH, CROSSLINK_LOGO_VIEWBOX, CROSSLINK_REPOSITORY, type CreateSecureStorageOptions, CrosslinkClient, type CrosslinkClientOptions, type CrosslinkLogoOptions, CrosslinkMobileBootstrap, CrosslinkOfflineShell, type CrosslinkTheme, DEFAULT_OFFLINE_CONFIG, DEFAULT_SERVICE_WORKER, DEFAULT_SERVICE_WORKER_CONFIG, DirectPairingChannel, type HostReachabilityResult, HydratedSecureStorage, INSTALL_HANDOFF_CONTEXT_COOKIE, INSTALL_HANDOFF_COOKIE, INSTALL_HANDOFF_QUERY_KEY, IndexedDbSecureStorage, JsonStore, LOGO_MIN_CONTRAST, LocalStorageSecureStorage, MemorySecureStorage, type MobileBootstrapOptions, type MobileBootstrapState, MockSocket, type NetworkMode, NotificationHandler, type NotificationHandlerOptions, type OfflineConfig, type OfflineConnectionState, type OfflineShellOptions, type OnboardingConfig, PairingCard, type PairingCardEndpoint, type PairingCardOptions, type PairingCardState, type PairingCardTheme, type PairingChannel, type PairingConfirmRequest, type PairingHostInfo, type PairingSession, type PairingSource, type PairingSourceEvent, PoweredByCrosslink, type PoweredByCrosslinkOptions, type PoweredByPlacement, type ResolvedCrosslinkTheme, type ResolvedPairingSession, type SecureStorage, type SecureStorageResult, type ServiceWorkerConfig, SignalingPeer, type WsLike, contrastRatio, createCrosslinkClient, createCrosslinkLogo, createHttpPairingSource, createOfflineUI, createPairingCard, createPoweredByCrosslink, createSecureCrosslinkClient, createSecureStorage, createServiceWorkerConfig, crosslinkLogoSvg, describeBootstrapEnvironment, generateServiceWorker, injectBootstrapStyles, injectPairingCardStyles, isStandalone, normalizeNetworkMode, parseColor, removeOfflineUI, resetDeviceStorage, resolveCrosslinkTheme, updateOfflineStatus, wsTransport };