@cef-ai/widget-runtime 2.1.1 → 2.2.0

package/dist/cef-wallet.d.ts

@@ -0,0 +1,80 @@
+/** A connected standalone identity plus the credentials the runtime needs. */
+export interface CefWalletSession {
+    /** 0x-prefixed hex public key. */
+    pubkey(): string;
+    /** Signature scheme. The CEF wallet's raw-signing key is ed25519. */
+    sigType: 'ed25519';
+    /** Sign raw bytes. May raise a step-up when the wallet is keyless. */
+    signRawBytes(bytes: Uint8Array): Promise<Uint8Array>;
+    /**
+     * A bearer delegation for vault reads, minted lazily and replaced before it
+     * expires. Prefer it over {@link signRawBytes} for every request — see the
+     * header note on keyless sessions.
+     */
+    delegation(): Promise<string>;
+}
+/**
+ * How a ceremony would be surfaced right now. `'popup'` means the call MUST
+ * happen inside a user gesture, because `window.open` needs transient
+ * activation even though the passkey ceremony itself does not.
+ */
+export type CeremonySurface = 'iframe' | 'popup';
+/** The standalone sign-in surface the runtime drives. */
+export interface CefWalletGate {
+    /** Silent, keyless, gesture-free. `null` when there is no session to resume. */
+    resume(): Promise<CefWalletSession | null>;
+    /** Authenticate an existing passkey. CALL FROM A CLICK. */
+    signIn(): Promise<CefWalletSession>;
+    /** Create an account (email → one-time code → passkey). CALL FROM A CLICK. */
+    register(): Promise<CefWalletSession>;
+    /** Which surface a ceremony would use right now. */
+    ceremonySurface(): CeremonySurface;
+}
+export interface CefWalletConfig {
+    /** Origin the wallet SPA is deployed to, e.g. https://wallet.compute.test.ddcdragon.com */
+    walletOrigin: string;
+    /** Shown to the reader on the wallet's consent surface. */
+    appName?: string;
+    /**
+     * Which surface the ceremony uses.
+     *
+     * `'iframe'` (the SDK's default over https) embeds the wallet inline and is
+     * the better experience — it is the only transport where a session can be
+     * resumed silently on the next page load. It requires the page's origin to be
+     * in wallet-api's embed allowlist.
+     *
+     * `'popup'` opens a top-level wallet window, which is NOT framing, so it
+     * works from an origin the allowlist does not name — a widget served off the
+     * shared content gateway, say, where allowlisting would admit every bundle
+     * anyone has ever published. The cost is that nothing resumes silently: the
+     * reader clicks once per page load.
+     */
+    transport?: CeremonySurface;
+}
+/**
+ * The browser refused to open the wallet window — `window.open` outside a user
+ * gesture, on a page that has not been told to allow popups.
+ *
+ * Named so the caller can tell "no popup" from "the wallet said no": the first
+ * is answered by asking for a click, the second is not.
+ */
+export declare class PopupBlockedError extends Error {
+    constructor();
+}
+/**
+ * A widget published to the content CDN has no wallet origin of its own to
+ * fall back on, and guessing one would point the reader's passkey at a host
+ * nobody vetted. Absent config is therefore an error with a fix in it, raised
+ * where a person can act on it rather than as a silent no-sign-in-button.
+ */
+export declare class WidgetWalletUnconfiguredError extends Error {
+    constructor();
+}
+/**
+ * Build the standalone sign-in gate.
+ *
+ * ONE WALLET PER PAGE. Two `EmbedWallet`s would mean two transports racing over
+ * one session — the same reason ROC keeps a single connector for the page
+ * lifetime.
+ */
+export declare function createCefWalletGate(cfg: CefWalletConfig): CefWalletGate;

package/dist/cef-wallet.js

@@ -0,0 +1,186 @@
+// packages/widget-runtime/src/cef-wallet.ts
+//
+// The standalone (top-level) identity source: the SAME passkey wallet the rest
+// of CEF signs in with.
+//
+// ── Why this replaced the Cere embed-wallet ────────────────────────────────
+// The old standalone path built a `@cere/embed-wallet` from
+// `manifest.wallet.{appId,env}`, which resolves to `wallet.stage.cere.io` — the
+// Cere consumer (Torus) wallet. ROC, Vault and the marketplace authenticate
+// against `@cef-ai/wallet` at `walletOrigin` (e.g.
+// `https://wallet.compute.test.ddcdragon.com`). Those are different identity
+// systems: a person who signs in to the Cere wallet is a DIFFERENT principal,
+// with no membership of the org whose vault the widget reads, so even a
+// successful connect could only ever show them an empty database.
+//
+// Observed before the change: opening a published widget by direct link loaded
+// `wallet.stage.cere.io`, left its popup iframe at 0x0 `display:none`, and
+// `connect()` never settled — the widget sat on "Loading…" forever with no
+// sign-in prompt at all.
+//
+// ── The three things this gets right that the old path did not ─────────────
+//
+//  1. SILENT RESUME FIRST. `resume()` is keyless and gesture-free, so a reader
+//     who already has a session sees data with no ceremony. Only when it
+//     returns null does the runtime show a sign-in control.
+//
+//  2. A GESTURE FOR THE CEREMONY. `login()`/`register()` open the wallet
+//     surface, and `window.open` outside user activation is blocked — which is
+//     precisely how the old path hung. Both are therefore exposed as separate
+//     calls for the runtime to make FROM A CLICK, never at boot.
+//
+//  3. A DELEGATION, NOT A SIGNATURE, FOR READS. After any page load the wallet
+//     is authenticated but KEYLESS, so a raw signature raises a step-up popup —
+//     once per request for a polling widget. `requestDelegation` needs no key
+//     material and settles bearer-active, so the runtime authenticates every
+//     cubby read with a bearer token and signs nothing. This is the same
+//     credential, minted with the same capabilities and the same `cef-widget`
+//     app id, that ROC hands a framed widget today.
+import { EmbedWallet } from '@cef-ai/wallet';
+/** Capabilities a widget's delegation carries: it reads cubbies and publishes events. */
+const WIDGET_CAPABILITIES = ['ddc-read', 'ddc-write'];
+/**
+ * The wallet app id a widget's delegation is minted under.
+ *
+ * NOT the widget's own id, and not the host's. vault-api reads the app id off
+ * the delegation, and ROC already mints the token it hands a framed widget
+ * under `cef-widget` — so a widget that mints its own uses the same one, and
+ * the server sees one kind of credential however the widget was opened.
+ */
+const WIDGET_APP_ID = 'cef-widget';
+/** Delegation lifetime requested from the wallet, and when to replace one. */
+const TOKEN_TTL = '1h';
+const TOKEN_TTL_MS = 60 * 60 * 1000;
+const RENEW_BEFORE_MS = 10 * 60 * 1000;
+/**
+ * The browser refused to open the wallet window — `window.open` outside a user
+ * gesture, on a page that has not been told to allow popups.
+ *
+ * Named so the caller can tell "no popup" from "the wallet said no": the first
+ * is answered by asking for a click, the second is not.
+ */
+export class PopupBlockedError extends Error {
+    constructor() {
+        super('PopupBlockedError: the browser did not open the wallet window');
+        this.name = 'PopupBlockedError';
+    }
+}
+/**
+ * Open the wallet window, and SAY SO AT ONCE when the browser will not.
+ *
+ * The wallet's own opener hands back whatever `window.open` returns, and a
+ * blocked popup returns null — which the transport then waits out as "surface
+ * never signalled ready", ten seconds of blank page before the reader is
+ * offered a button. A popup the browser refused is known the instant it is
+ * refused; this turns that null into a rejection the same tick.
+ */
+const openPopupOrThrow = (url, features) => {
+    const opened = window.open(url, '_blank', features);
+    if (!opened)
+        throw new PopupBlockedError();
+    return opened;
+};
+/**
+ * A widget published to the content CDN has no wallet origin of its own to
+ * fall back on, and guessing one would point the reader's passkey at a host
+ * nobody vetted. Absent config is therefore an error with a fix in it, raised
+ * where a person can act on it rather than as a silent no-sign-in-button.
+ */
+export class WidgetWalletUnconfiguredError extends Error {
+    constructor() {
+        super('WidgetWalletUnconfiguredError: this widget was published without a '
+            + '`wallet.origin`, so there is no wallet to sign in to. Rebuild and '
+            + 'republish it with a CLI new enough to stamp one (`cef push --kind widget`).');
+        this.name = 'WidgetWalletUnconfiguredError';
+    }
+}
+function hexPubkey(signer) {
+    const bytes = signer.publicKey;
+    let out = '0x';
+    for (const b of bytes)
+        out += b.toString(16).padStart(2, '0');
+    return out;
+}
+/**
+ * Build the standalone sign-in gate.
+ *
+ * ONE WALLET PER PAGE. Two `EmbedWallet`s would mean two transports racing over
+ * one session — the same reason ROC keeps a single connector for the page
+ * lifetime.
+ */
+export function createCefWalletGate(cfg) {
+    if (!cfg.walletOrigin)
+        throw new WidgetWalletUnconfiguredError();
+    const wallet = new EmbedWallet({
+        appId: WIDGET_APP_ID,
+        appName: cfg.appName ?? 'CEF widget',
+        walletOrigin: cfg.walletOrigin,
+        ...(cfg.transport ? { transport: cfg.transport } : {}),
+        ...(cfg.transport === 'popup' ? { popupOpener: openPopupOrThrow } : {}),
+    });
+    /*
+     * ONE TOKEN, REPLACED BEFORE IT DIES — not one per read and not one per page.
+     *
+     * A widget that polls would otherwise mint a delegation per request; a widget
+     * left open longer than the hour would otherwise present the same dead one
+     * forever, and its 401s happen inside the frame where nothing else can notice.
+     * Minting is silent, so an age check costs nothing and removes both.
+     */
+    let held = null;
+    const delegation = () => {
+        const current = held;
+        if (current && Date.now() - current.mintedAt < TOKEN_TTL_MS - RENEW_BEFORE_MS) {
+            return current.token;
+        }
+        const token = wallet
+            .requestDelegation({
+            capabilities: [...WIDGET_CAPABILITIES],
+            appId: WIDGET_APP_ID,
+            ttl: TOKEN_TTL,
+        })
+            .then((r) => r.token)
+            .catch((err) => {
+            // A rejected promise left in the cache would brick every later read
+            // after one network blip or one dismissed ceremony.
+            held = null;
+            throw err;
+        });
+        held = { token, mintedAt: Date.now() };
+        return token;
+    };
+    const session = () => {
+        const signer = wallet.asSigner();
+        const pub = hexPubkey(signer);
+        return {
+            pubkey: () => pub,
+            sigType: 'ed25519',
+            signRawBytes: (bytes) => signer.sign(bytes),
+            delegation,
+        };
+    };
+    return {
+        async resume() {
+            const result = await wallet.resume();
+            if (!result)
+                return null;
+            held = null; // a new session invalidates any token minted for the old one
+            return session();
+        },
+        async signIn() {
+            await wallet.login();
+            held = null;
+            return session();
+        },
+        async register() {
+            await wallet.register();
+            held = null;
+            return session();
+        },
+        // A GETTER ON THE WALLET, read live. Its value is only knowable once a
+        // framed ceremony has actually been refused, so anything cached at
+        // construction would be wrong for exactly the case it exists for.
+        ceremonySurface() {
+            return wallet.ceremonySurface;
+        },
+    };
+}

package/dist/entry.js

@@ -3,6 +3,9 @@ import { VaultSDK } from '@cef-ai/vault-sdk';
 import { createHostBridge } from './host-bridge.js';
 import { toVaultSdkSigner } from './bridge-wallet.js';
 import { connectStandaloneWallet } from './standalone-wallet.js';
+import { createCefWalletGate } from './cef-wallet.js';
+import { autoSignIn } from './sign-in-ui.js';
+import { currentLinkContext } from './share-link.js';
 import { createIdentityResolver } from './resolve-identity.js';
 import { createVaultClient } from './vault-client.js';
 import { toVaultSdkConfig } from './vault-sdk-config.js';
@@ -23,30 +26,64 @@ function onDomReady(fn) {
         fn();
     }
 }
+/**
+ * Sign the reader in for a STANDALONE (direct-link) widget.
+ *
+ * RESUME, THEN ASK — in that order, and the order is the feature. `resume()` is
+ * keyless and needs no gesture, so a reader who already has a session never
+ * sees a prompt at all; only when there is nothing to resume does the runtime
+ * put a control on screen. The ceremony then starts inside that button's own
+ * click, because `window.open` outside user activation is blocked — which is
+ * exactly how the previous standalone path hung: it called connect() at boot,
+ * the browser swallowed the popup, and the promise never settled.
+ *
+ * Falls back to the legacy Cere embed-wallet only for a bundle published
+ * before `wallet.origin` existed, so old widgets keep whatever behaviour they
+ * had rather than losing their sign-in to this change.
+ */
+async function connectStandaloneWalletForReader(manifest) {
+    const origin = manifest.wallet?.origin;
+    if (!origin)
+        return connectStandaloneWallet(manifest.wallet);
+    const build = (transport) => createCefWalletGate({
+        walletOrigin: origin,
+        appName: manifest.name,
+        ...(transport ? { transport } : {}),
+    });
+    // Framed first: it is the only transport that resumes silently, and the one
+    // that needs no click of ours. The popup is the retry for an origin wallet-api
+    // will not frame, and a button is the retry for a popup the browser will not
+    // open on its own. See `autoSignIn`.
+    return autoSignIn(build(), () => build('popup'));
+}
 function boot() {
     const manifest = window.WidgetSandbox?.manifest;
     if (!manifest)
         return;
     const bridge = createHostBridge();
     // ── Multi-source identity ─────────────────────────────────────────────────
-    // Framed → the embedding host (Cere Vault, or any page mounting
-    // `createWidgetHost`) answers the postMessage handshake. Top-level → an
-    // interactive Cere embed-wallet built from `manifest.wallet.{appId,env}`.
-    // Both paths yield a pubkey + raw-bytes signer feeding the SAME vault-sdk
-    // client. A framed widget whose handshake fails throws WidgetSignedOutError
-    // rather than downgrading to the wallet — see ./resolve-identity.
+    // Framed → the embedding host (Cere Vault, ROC, or any page mounting
+    // `createWidgetHost`) answers the postMessage handshake. Top-level → the CEF
+    // passkey wallet at `manifest.wallet.origin`. Both paths yield a pubkey + a
+    // credential feeding the SAME vault-sdk client. A framed widget whose
+    // handshake fails throws WidgetSignedOutError rather than downgrading to the
+    // wallet — see ./resolve-identity.
     const resolveSigningIdentity = createIdentityResolver({
         bridge,
-        connectWallet: () => connectStandaloneWallet(manifest.wallet),
+        connectWallet: () => connectStandaloneWalletForReader(manifest),
+        linkContext: currentLinkContext,
     });
     /** The host's delegation, captured when identity resolved. See resolveIdentity. */
     let hostDelegation;
+    /** The wallet's renewing mint, when the wallet minted that delegation. */
+    let renewDelegation;
     const deps = {
         resolveIdentity: async () => {
             const id = await resolveSigningIdentity();
             // Remembered for buildVaultClient, which is synchronous and runs after
             // this. The resolver is memoised, so this is the same identity.
             hostDelegation = id.token;
+            renewDelegation = id.renewToken;
             /*
              * THE CONTEXT TRAVELS THE LAST STEP TOO.
              *
@@ -68,6 +105,7 @@ function boot() {
         buildVaultClient: (m, id) => {
             const sigType = id.sigType ?? 'ed25519';
             const hostToken = hostDelegation;
+            const renewToken = renewDelegation;
             // Defer to the memoized identity for signing — resolveIdentity() has
             // already run by the time buildVaultClient is called, so this resolves
             // to the same (host or wallet) signer without a second handshake/popup.
@@ -84,7 +122,7 @@ function boot() {
             // session steps up on every signature, so a widget that polls a query
             // asked for a passkey forever. `sign` stays wired for hosts that supply
             // no token.
-            const makeSdk = () => new VaultSDK(toVaultSdkConfig(m.endpoints, vaultSdkSigner, hostToken));
+            const makeSdk = () => new VaultSDK(toVaultSdkConfig(m.endpoints, vaultSdkSigner, hostToken, renewToken));
             // WHICH VAULT, when the host named one. It rides `context` rather than
             // a field of its own because it is the same kind of fact as the run id —
             // why this widget was opened — and because an optional key on an
@@ -121,7 +159,7 @@ function boot() {
                 // Same config builder as the main vault client above — in particular
                 // the same `chainUrl`, since this `ensure({ onboard: false })` runs
                 // the vault-delegate grant step too.
-                const sdk = new VaultSDK(toVaultSdkConfig(manifest.endpoints, vaultSdkSigner, id.token));
+                const sdk = new VaultSDK(toVaultSdkConfig(manifest.endpoints, vaultSdkSigner, id.token, id.renewToken));
                 // With a token that SDK has no signer, and `ensure()` does not read
                 // `auth`: it needs the token handed to it, or it throws before the
                 // first chunk. Without one the key stays absent so the signer path runs.

package/dist/index.d.ts

@@ -29,3 +29,6 @@ export { createWidgetHost, type WidgetHostOptions, type WidgetHostIdentity } fro
 export { WidgetSignedOutError, type ResolvedSigningIdentity } from './resolve-identity.js';
 export { toVaultSdkSigner, toClientSdkWallet, toUploaderSignerPair, type VaultSignedWallet } from './bridge-wallet.js';
 export { connectStandaloneWallet, type StandaloneWallet } from './standalone-wallet.js';
+export { createCefWalletGate, WidgetWalletUnconfiguredError, type CefWalletGate, type CefWalletSession, type CefWalletConfig, type CeremonySurface } from './cef-wallet.js';
+export { requestSignIn, autoSignIn, type SignInCopy } from './sign-in-ui.js';
+export { contextFromLocation, currentLinkContext } from './share-link.js';

package/dist/index.js

@@ -29,3 +29,6 @@ export { createWidgetHost } from './widget-host.js';
 export { WidgetSignedOutError } from './resolve-identity.js';
 export { toVaultSdkSigner, toClientSdkWallet, toUploaderSignerPair } from './bridge-wallet.js';
 export { connectStandaloneWallet } from './standalone-wallet.js';
+export { createCefWalletGate, WidgetWalletUnconfiguredError } from './cef-wallet.js';
+export { requestSignIn, autoSignIn } from './sign-in-ui.js';
+export { contextFromLocation, currentLinkContext } from './share-link.js';

package/dist/manifest.d.ts

@@ -8,6 +8,7 @@ export interface BuildManifestInput {
     wallet: {
         appId: string;
         env: string;
+        origin?: string;
     };
     endpoints: WidgetManifest['endpoints'];
     /** Single-query shorthand — kept for backwards compat. Either query or queries may be supplied. */

package/dist/resolve-identity.d.ts

@@ -22,6 +22,18 @@ export interface ResolvedSigningIdentity {
      * genuinely cannot carry.
      */
     token?: string;
+    /**
+     * A fresh delegation on demand, when the WALLET minted `token`.
+     *
+     * `token` is one string minted at boot, and it dies after an hour. A widget
+     * left open longer — a polling query, a dashboard on a wall — would present
+     * the dead one forever, as a 401 inside the frame that nothing else notices.
+     * The wallet's mint already caches the token and replaces it before expiry,
+     * so asking on every request costs nothing and is what keeps it alive.
+     *
+     * Absent on the host path: the host owns its token's lifetime.
+     */
+    renewToken?: () => Promise<string>;
     /**
      * Why the host opened this widget — the run being viewed, or the record.
      *
@@ -41,6 +53,14 @@ export interface IdentityResolverDeps {
     bridge: HostBridge;
     /** Opens the interactive wallet. Only ever called when NOT framed. */
     connectWallet: () => Promise<StandaloneWallet>;
+    /**
+     * Why this widget was opened, as the LINK said it — the standalone twin of
+     * the handshake's `context`, and only consulted on the standalone path.
+     *
+     * Absent (or returning undefined) leaves a link-less standalone boot behaving
+     * exactly as it did before: the reader's own vault, the latest record.
+     */
+    linkContext?: () => WidgetHostContext | undefined;
 }
 /** Build the memoized identity resolver. A failure clears the memo so a later action can retry. */
 export declare function createIdentityResolver(deps: IdentityResolverDeps): () => Promise<ResolvedSigningIdentity>;

package/dist/resolve-identity.js

@@ -45,11 +45,35 @@ export function createIdentityResolver(deps) {
                 throw new WidgetSignedOutError();
             // Top-level boot → interactive wallet.
             const wallet = await deps.connectWallet();
+            /*
+             * THE DELEGATION, WHERE THE WALLET MINTS ONE — for the same reason the
+             * framed path prefers the host's. A passkey session is keyless after
+             * every page load, so a widget that signs each request raises a step-up
+             * each request, and a polling query asks forever.
+             *
+             * Best-effort on purpose: a wallet with no delegation concept, or a mint
+             * that fails, leaves `sign` wired and the widget behaves as it did
+             * before — a ceremony where a token would have been. Failing boot over a
+             * missing optimisation would turn a slower path into no path.
+             */
+            let token;
+            const mint = wallet.delegation?.bind(wallet);
+            if (mint) {
+                try {
+                    token = await mint();
+                }
+                catch (err) {
+                    console.warn('[widget-runtime] no delegation minted; falling back to signing', err);
+                }
+            }
+            const context = deps.linkContext?.();
             return {
                 source: 'wallet',
                 publicKey: wallet.pubkey(),
                 sigType: wallet.sigType,
                 sign: (bytes) => wallet.signRawBytes(bytes),
+                ...(token && mint ? { token, renewToken: mint } : {}),
+                ...(context ? { context } : {}),
             };
         })().catch((err) => {
             identityP = null; // let a later action retry (e.g. user reopens the wallet)

package/dist/share-link.d.ts

@@ -0,0 +1,15 @@
+import type { WidgetHostContext } from './host-bridge.js';
+/**
+ * Parse the link's own parameters into a host context.
+ *
+ * Returns `undefined` rather than `{}` when the link names nothing, for the
+ * reason the handshake does: a widget doing `'context' in id` must be able to
+ * tell "nobody told me anything" from "I was told something empty", and the
+ * standalone-with-no-link case has to stay byte-identical to what shipped.
+ */
+export declare function contextFromLocation(loc: {
+    search?: string;
+    hash?: string;
+}): WidgetHostContext | undefined;
+/** Convenience for the browser: the current page's link context. */
+export declare function currentLinkContext(): WidgetHostContext | undefined;

package/dist/share-link.js

@@ -0,0 +1,72 @@
+// packages/widget-runtime/src/share-link.ts
+//
+// The third source of {@link WidgetHostContext} — a link.
+//
+// A framed widget is told why it was opened over the postMessage handshake. A
+// widget opened by a shared URL has no host to ask, and the two facts it is
+// missing are exactly the two the handshake carries: WHICH VAULT to read, and
+// WHICH RUN to show. So a share link supplies the same structure by another
+// route, and nothing downstream has to learn a second concept — the runtime
+// hands `context` to `identity()` and `vaultId` to the vault client either way.
+//
+// WHY THE VAULT ID IS SAFE IN A URL. It is an identifier, not a credential.
+// Every read is still authorised by vault-api against the READER's own
+// signed-in identity, so naming a vault in a link grants nothing: a person who
+// is not a member gets the same refusal they would get by typing the id in
+// themselves. What the link removes is the guessing — the sharer knows which
+// vault they mean, and making the reader pick from a list is a worse product
+// than being told.
+//
+// Read from the FRAGMENT by preference and the query as a fallback. The
+// fragment is not sent to the CDN that serves the bundle, which keeps the run
+// a reader is looking at out of someone else's access logs; the query is
+// accepted because links get rewritten by tools that do not preserve fragments.
+/** Accepted spellings, in precedence order, for each field of the context. */
+const KEYS = {
+    vaultId: ['vaultId', 'vault'],
+    runId: ['runId', 'run'],
+    recordId: ['recordId', 'record'],
+};
+function firstOf(params, names) {
+    for (const name of names) {
+        const v = params.get(name);
+        if (v && v.trim())
+            return v.trim();
+    }
+    return undefined;
+}
+/**
+ * Parse the link's own parameters into a host context.
+ *
+ * Returns `undefined` rather than `{}` when the link names nothing, for the
+ * reason the handshake does: a widget doing `'context' in id` must be able to
+ * tell "nobody told me anything" from "I was told something empty", and the
+ * standalone-with-no-link case has to stay byte-identical to what shipped.
+ */
+export function contextFromLocation(loc) {
+    const hash = loc.hash ?? '';
+    // `#a=b`, and also `#/route?a=b` — take whatever follows the first `?` when
+    // the fragment carries one, else the fragment itself.
+    const q = hash.indexOf('?');
+    const fragment = q >= 0 ? hash.slice(q + 1) : hash.replace(/^#/, '');
+    const fromHash = new URLSearchParams(fragment);
+    const fromQuery = new URLSearchParams((loc.search ?? '').replace(/^\?/, ''));
+    const pick = (names) => firstOf(fromHash, names) ?? firstOf(fromQuery, names);
+    const ctx = {};
+    const vaultId = pick(KEYS.vaultId);
+    const runId = pick(KEYS.runId);
+    const recordId = pick(KEYS.recordId);
+    if (vaultId)
+        ctx.vaultId = vaultId;
+    if (runId)
+        ctx.runId = runId;
+    if (recordId)
+        ctx.recordId = recordId;
+    return Object.keys(ctx).length > 0 ? ctx : undefined;
+}
+/** Convenience for the browser: the current page's link context. */
+export function currentLinkContext() {
+    if (typeof window === 'undefined' || !window.location)
+        return undefined;
+    return contextFromLocation(window.location);
+}

package/dist/sign-in-ui.d.ts

@@ -0,0 +1,55 @@
+import type { CefWalletGate, CefWalletSession } from './cef-wallet.js';
+export interface SignInCopy {
+    title: string;
+    body: string;
+    signIn: string;
+    register: string;
+}
+/**
+ * Show the sign-in overlay and resolve once the reader is authenticated.
+ *
+ * Never rejects on a dismissed or failed ceremony: the reader is still sitting
+ * in front of the widget and can try the other button, so the overlay reports
+ * what went wrong and stays up. It settles only on success — or when
+ * `resume()`, retried on each attempt, turns out to have a session after all.
+ */
+export declare function requestSignIn(gate: CefWalletGate, copy?: Partial<SignInCopy>, 
+/**
+ * A second gate to try once, when the first one's ceremony is refused.
+ *
+ * WHAT THIS IS FOR: the framed ceremony needs the page's origin in
+ * wallet-api's embed allowlist, and a widget served off the shared content
+ * gateway is not going to be in it — allowlisting that origin would admit
+ * every bundle anyone has ever published, which is a much larger grant than a
+ * sharing feature should ask for. A popup is not framing, so it works
+ * unlisted. Retried rather than chosen up front because a widget cannot know
+ * whether its own origin is listed, and the listed case is worth having: it
+ * is the only one where a session resumes without a click.
+ */
+fallback?: () => CefWalletGate): Promise<CefWalletSession>;
+/**
+ * Sign the reader in WITHOUT ASKING FIRST.
+ *
+ * The overlay above collects a click so a popup can open under it. That made
+ * the shared-link experience two ceremonies deep: a card saying "Sign in to
+ * view this" with a button, and then the wallet's own panel with ITS button.
+ * The first of those is not the wallet's requirement — it is this file's,
+ * and only for the popup. So it is now the last resort, not the front door.
+ *
+ * In order, stopping at the first that works:
+ *
+ *   1. `resume()` — a session from an earlier visit. No ceremony at all.
+ *   2. The framed ceremony, started immediately. An iframe needs no gesture,
+ *      and the wallet's panel carries its own "Continue" — one click, the
+ *      wallet's, not two. This is what a listed origin gets.
+ *   3. The popup ceremony, also started immediately. A browser that has been
+ *      told to allow popups here opens it; one that has not refuses, and the
+ *      refusal comes back as a rejection rather than a hang.
+ *   4. The overlay, on the popup gate — the one case a gesture is genuinely
+ *      needed, because the browser demands one for `window.open`.
+ *
+ * A `resume()` that THROWS, as opposed to resolving null, is a surface that
+ * never came up (origin not in the embed allowlist, most likely). Step 2 is
+ * skipped then: it would only wait out the same handshake a second time.
+ */
+export declare function autoSignIn(gate: CefWalletGate, fallback: () => CefWalletGate, copy?: Partial<SignInCopy>): Promise<CefWalletSession>;