@brass-build/client 0.1.0

package/dist/hosted-ui.js

@@ -0,0 +1,673 @@
+// The hosted-UI launcher core.
+//
+// "Hosted UI" surfaces are Brass-owned pages (document picker, share dialog) a
+// third-party app opens without building the UI. The app calls e.g.
+// `Brass.selectDocument()`; this loads `${dashboardBaseUrl}/embed/<surface>`
+// in a modal iframe, runs a postMessage handshake with the embed page's
+// bridge, and resolves with whatever the user did.
+//
+// Iframe-first. When the iframe can't complete the handshake (CSP
+// `frame-ancestors`, a partitioned third-party auth cookie, ...) the launcher
+// falls back per surface:
+//   - `reject`: throw `BrassError` `code: 'iframe_unavailable'`. Used by
+//     value-returning launchers with nowhere else to send the user.
+//   - `redirect`: navigate the top window to the standalone
+//     `/embed/<surface>?...&return_to=<here>` page. Used by fire-and-forget
+//     launchers; the returned promise never settles (the page is gone).
+//   - `redirect-with-value`: the same navigation for a surface that still
+//     owes the caller a value, which comes home on one-shot URL params (the
+//     document picker).
+//
+// Bridge protocol (envelope `__brass_embed: 1`):
+//   iframe -> host:  ready | resize{height} | result{payload} | cancel |
+//                    error{code,message}
+//   host -> iframe:  init{surface,params}
+// The host validates `event.origin === dashboardOrigin` and
+// `event.source === iframe.contentWindow` on every inbound message; the embed
+// page learns the host origin from `init` and targets outbound at it (never
+// `*`).
+// Both sides ignore any `message` whose `data[ENVELOPE]` is not this exact
+// value, so unrelated postMessage traffic never reaches the handshake.
+import { BrassError } from './errors.js';
+const ENVELOPE = '__brass_embed';
+const PROTOCOL_VERSION = 1;
+// No `ready` within this window means the iframe is unusable (CSP, origin
+// unreachable, bridge threw). What the window is worth is set by what the
+// fallback costs the user, not by which fallback runs.
+//
+// Only a plain `redirect` can afford the short window: the surface returns
+// nothing, the standalone page finishes the same job, and the user keeps
+// their place, so eating ten seconds of blank modal is the bigger cost.
+//
+// `reject` and `redirect-with-value` both end with the caller worse off (a
+// thrown error, or the user navigated out of the host app with the value
+// routed home through a URL round trip), so they wait long enough that only
+// a genuinely unusable iframe times out. The embed page is a full
+// application boot behind a cross-origin request, so a merely slow link
+// clears the short window while the iframe is perfectly capable.
+const READY_TIMEOUT_LONG_MS = 10_000;
+const READY_TIMEOUT_SHORT_MS = 4_000;
+// The embed page posts `resize` with its measured height; the host clamps to
+// this range so a malformed or hostile height can't collapse the dialog or
+// paint the whole viewport.
+const INITIAL_IFRAME_HEIGHT = 480;
+const MIN_IFRAME_HEIGHT = 160;
+const MAX_IFRAME_HEIGHT = 760;
+// Full-page fallback when the iframe can't be hosted: navigate the top
+// window to the standalone embed page, threading the surface params plus a
+// `return_to` so the standalone page can send the user home when done.
+function redirectToStandalone(baseUrl, surface, params, theme) {
+    const url = new URL(`${baseUrl}/embed/${surface}`);
+    for (const [key, value] of Object.entries(params)) {
+        // `sessionToken` is an in-iframe-only credential hand-off (posted over the
+        // bridge to the pinned dashboard origin); never let it reach a URL. On the
+        // redirect fallback the standalone page is top-level and first-party, so
+        // its own cookie carries the session and no hand-off is needed.
+        if (key === 'sessionToken')
+            continue;
+        if (value !== undefined && value !== null) {
+            url.searchParams.set(key, String(value));
+        }
+    }
+    url.searchParams.set('return_to', window.location.href);
+    // Thread the theme only when it overrides the `'light'` default, keeping the
+    // URL stable for the no-config path (mirrors the iframe-src construction).
+    if (theme !== 'light') {
+        url.searchParams.set('theme', theme);
+    }
+    window.location.assign(url.toString());
+}
+// Resolved light/dark for the modal chrome. `'auto'` reads the host's
+// `prefers-color-scheme` once on open; the embed page still receives the
+// unresolved `'auto'` so its own rule keeps tracking OS preference.
+function resolveChromeTheme(theme) {
+    if (theme === 'light' || theme === 'dark')
+        return theme;
+    const mql = window.matchMedia?.('(prefers-color-scheme: dark)');
+    return mql?.matches ? 'dark' : 'light';
+}
+function chromeTokensFor(resolved) {
+    if (resolved === 'dark') {
+        return {
+            backdrop: 'rgba(0, 0, 0, 0.65)',
+            cardBackground: '#11141b',
+            cardShadow: '0 20px 60px rgba(0, 0, 0, 0.55)',
+            closeButtonColor: '#e7eaf0',
+            spinnerTrack: 'rgba(231, 234, 240, 0.18)',
+            spinnerAccent: '#e7eaf0',
+        };
+    }
+    return {
+        backdrop: 'rgba(15, 23, 42, 0.55)',
+        cardBackground: '#fff',
+        cardShadow: '0 20px 60px rgba(15, 23, 42, 0.35)',
+        closeButtonColor: '#0f172a',
+        spinnerTrack: 'rgba(15, 23, 42, 0.12)',
+        spinnerAccent: '#0f172a',
+    };
+}
+const CHROME_STYLE_ID = 'brass-hosted-ui-chrome';
+// The chrome dims the page with the dialog element's own themed background, so
+// the UA's `::backdrop` would stack a second, unthemed dim beneath it. A
+// pseudo-element cannot be styled inline, which is why the chrome injects a
+// stylesheet at all; everything else it paints is an inline style.
+const CHROME_CSS = `dialog[data-brass-hosted-ui]::backdrop { background: transparent; }`;
+function injectChromeStyles(doc) {
+    if (doc.getElementById(CHROME_STYLE_ID))
+        return;
+    const style = doc.createElement('style');
+    style.id = CHROME_STYLE_ID;
+    style.textContent = CHROME_CSS;
+    doc.head.appendChild(style);
+}
+// The control the reader last acted on, which is who a dismissed surface hands
+// focus back to. `document.activeElement` when the launcher is called looks
+// like the answer and is often `<body>` by then: a host that disables its
+// trigger for the life of the dialog does so before calling, and disabling a
+// focused control blurs it. Tracking the activation instead survives that.
+let lastActivated = null;
+let trackingActivations = false;
+const ACTIVATABLE = 'button, a[href], input, select, textarea, [tabindex]:not([tabindex="-1"])';
+function trackActivation(event) {
+    // Enter and Space are the keys that press a control; every other keystroke
+    // is someone typing, and typing is not what a dialog returns focus to.
+    if (event instanceof KeyboardEvent && event.key !== 'Enter' && event.key !== ' ') {
+        return;
+    }
+    const target = event.target;
+    if (!(target instanceof HTMLElement))
+        return;
+    lastActivated = target.closest(ACTIVATABLE) ?? target;
+}
+/**
+ * Start recording which control the reader last pressed, so a dismissed
+ * surface can hand the keyboard back to it. Idempotent.
+ *
+ * @internal
+ */
+export function trackHostedUiActivations() {
+    if (trackingActivations || typeof document === 'undefined')
+        return;
+    trackingActivations = true;
+    document.addEventListener('pointerdown', trackActivation, true);
+    document.addEventListener('keydown', trackActivation, true);
+}
+// Who a dismissal should put the keyboard back on: whatever holds focus when
+// the surface opens, or the last control the reader pressed when nothing does.
+function resolveOpener() {
+    const active = document.activeElement;
+    if (active instanceof HTMLElement && active !== document.body)
+        return active;
+    return lastActivated;
+}
+// Opens `${baseUrl}/embed/<surface>` in a modal iframe and drives the bridge
+// handshake. Resolves with the `result` payload or `null` on cancel; rejects
+// on not-in-browser / embed error. On the ready timeout it rejects
+// (`unavailable: 'reject'`) or redirects and never settles (the two
+// `redirect` modes).
+function openEmbed(baseUrl, dashboardOrigin, surface, params, unavailable, theme, 
+// Handles an `export-request`: serialise the surface's `docId` and post the
+// bytes back. Only the document surfaces (with a Download button) pass it.
+onExportRequest, 
+// Notified when the delete surface reports a local delete (or its
+// retraction) for a doc id, so the session can classify the matching
+// `doc_gone`. Only the document-settings / share surface emits it.
+onLocalDelete, 
+// Notified when the user takes the refusal surface's sign-in action.
+onSignInRequested) {
+    return new Promise((resolve, reject) => {
+        if (typeof window === 'undefined' || typeof document === 'undefined') {
+            reject(new BrassError('Hosted UI requires a browser environment.', {
+                code: 'not_in_browser',
+            }));
+            return;
+        }
+        const resolvedChrome = resolveChromeTheme(theme);
+        const tokens = chromeTokensFor(resolvedChrome);
+        injectChromeStyles(document);
+        // A `<dialog>` opened with `showModal()` (below), which is what makes the
+        // host page inert while the surface is up: the reader tabs around the
+        // dialog instead of through the app behind it, and the browser enforces
+        // that rather than a key handler here. The UA box styles for a dialog (a
+        // content-sized, centered, bordered, padded box with a max-width) are all
+        // wrong for a full-viewport backdrop, so each is zeroed.
+        const overlay = document.createElement('dialog');
+        overlay.setAttribute('data-brass-hosted-ui', surface);
+        overlay.setAttribute('data-brass-theme', theme);
+        Object.assign(overlay.style, {
+            position: 'fixed',
+            inset: '0',
+            margin: '0',
+            padding: '0',
+            border: '0',
+            width: 'auto',
+            height: 'auto',
+            maxWidth: 'none',
+            maxHeight: 'none',
+            // Above effectively everything; this is a foreground modal. The top
+            // layer already outranks any z-index, so this is what keeps the chrome
+            // in front on the fallback path where `showModal` is unavailable.
+            zIndex: '2147483647',
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            background: tokens.backdrop,
+        });
+        const card = document.createElement('div');
+        // Expose the frame as a labelled modal dialog: the overlay behind it is
+        // the backdrop, and the embed page inside the iframe carries its own
+        // heading. The close button / Escape dismiss it (below); a backdrop
+        // click does not.
+        card.setAttribute('role', 'dialog');
+        card.setAttribute('aria-modal', 'true');
+        card.setAttribute('aria-label', 'Brass');
+        Object.assign(card.style, {
+            position: 'relative',
+            width: 'min(420px, calc(100vw - 32px))',
+            background: tokens.cardBackground,
+            borderRadius: '12px',
+            overflow: 'hidden',
+            boxShadow: tokens.cardShadow,
+        });
+        const iframe = document.createElement('iframe');
+        // Thread the theme on the iframe URL (not the bridge `init` payload) so
+        // the embed page pins its `color-scheme` before it paints, avoiding a
+        // wrong-theme flash while the handshake is in flight. Omit the `'light'`
+        // default to keep the URL stable for the no-config path.
+        if (theme === 'light') {
+            iframe.src = `${baseUrl}/embed/${surface}`;
+        }
+        else {
+            const iframeUrl = new URL(`${baseUrl}/embed/${surface}`);
+            iframeUrl.searchParams.set('theme', theme);
+            iframe.src = iframeUrl.toString();
+        }
+        iframe.title = 'Brass';
+        // The dialogs offer copy-to-clipboard actions (the share surface's
+        // document link); a cross-origin iframe only gets the Clipboard API
+        // when its embedder delegates it, so writeText throws NotAllowedError
+        // without this.
+        iframe.allow = 'clipboard-write';
+        // `colorScheme` + `background` on the iframe ELEMENT defend against a
+        // flash through the OS color while the embed HTML + JS loads: until the
+        // embed page's `applyEmbedTheme()` pins `color-scheme` on its own
+        // `<html>`, the browser paints the iframe's default background from the OS
+        // `prefers-color-scheme` (a black flash on a dark-OS phone opening a
+        // light modal). Pinning here paints the resolved color before any request
+        // leaves the wire. `'auto'` follows OS preference, matching the embed page
+        // once loaded.
+        Object.assign(iframe.style, {
+            display: 'block',
+            border: '0',
+            width: '100%',
+            height: `${INITIAL_IFRAME_HEIGHT}px`,
+            colorScheme: theme === 'auto' ? 'light dark' : resolvedChrome,
+            background: tokens.cardBackground,
+        });
+        const closeButton = document.createElement('button');
+        closeButton.type = 'button';
+        closeButton.setAttribute('aria-label', 'Close');
+        closeButton.textContent = '×';
+        Object.assign(closeButton.style, {
+            position: 'absolute',
+            top: '6px',
+            right: '8px',
+            width: '28px',
+            height: '28px',
+            border: '0',
+            borderRadius: '6px',
+            background: 'transparent',
+            color: tokens.closeButtonColor,
+            fontSize: '20px',
+            lineHeight: '1',
+            cursor: 'pointer',
+        });
+        card.appendChild(closeButton);
+        card.appendChild(iframe);
+        // Loading spinner over the iframe until the `ready` handshake. Without it
+        // the user sees a blank panel for ~300-1000ms while the iframe boots,
+        // reading as "the click did nothing". It can't sit BEHIND the iframe
+        // because the iframe paints its own background synchronously (the
+        // OS-color-flash defense above), so it goes on top and hides on `ready`.
+        const loader = document.createElement('div');
+        Object.assign(loader.style, {
+            position: 'absolute',
+            inset: '0',
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            background: tokens.cardBackground,
+            zIndex: '1',
+            // Brief fade so the spinner-to-content transition isn't abrupt.
+            transition: 'opacity 120ms ease-out',
+        });
+        const spinner = document.createElement('div');
+        Object.assign(spinner.style, {
+            width: '32px',
+            height: '32px',
+            borderRadius: '50%',
+            border: `3px solid ${tokens.spinnerTrack}`,
+            borderTopColor: tokens.spinnerAccent,
+            boxSizing: 'border-box',
+        });
+        // Web Animations API rather than a `<style>` @keyframes, so no CSS is
+        // injected into the host page (which would need scoping to avoid leaking).
+        if (typeof spinner.animate === 'function') {
+            spinner.animate([{ transform: 'rotate(0deg)' }, { transform: 'rotate(360deg)' }], { duration: 800, iterations: Infinity, easing: 'linear' });
+        }
+        loader.appendChild(spinner);
+        card.appendChild(loader);
+        overlay.appendChild(card);
+        let settled = false;
+        let readyTimer;
+        // Where to put the reader back. Dismissal detaches the dialog rather than
+        // closing it in place, so this is the launcher's job; a reader left on
+        // `<body>` resumes tabbing from the top of the page instead of from the
+        // control that opened the surface.
+        const opener = resolveOpener();
+        function restoreFocus() {
+            if (!opener?.isConnected)
+                return;
+            opener.focus();
+            if (document.activeElement === opener)
+                return;
+            // A host that disabled its trigger for the life of the dialog re-enables
+            // it when the launcher settles, which happens after this runs, so the
+            // press above landed on a disabled control and did nothing. Try again
+            // past the caller's own reaction, and only while nothing has taken focus
+            // since, so a host that moves focus itself on the result keeps it.
+            setTimeout(() => {
+                const active = document.activeElement;
+                if (active !== null && active !== document.body)
+                    return;
+                if (opener.isConnected)
+                    opener.focus();
+            }, 0);
+        }
+        function teardown() {
+            window.removeEventListener('message', onMessage);
+            window.removeEventListener('keydown', onKeydown, true);
+            overlay.removeEventListener('cancel', onCancel);
+            if (readyTimer !== undefined)
+                clearTimeout(readyTimer);
+            if (overlay.open)
+                overlay.close();
+            overlay.remove();
+            restoreFocus();
+        }
+        function settleResolve(value) {
+            if (settled)
+                return;
+            settled = true;
+            teardown();
+            resolve(value);
+        }
+        function settleReject(error) {
+            if (settled)
+                return;
+            settled = true;
+            teardown();
+            reject(error);
+        }
+        function onMessage(event) {
+            // Origin + source pinning: only the embed page we opened, in the
+            // dashboard origin, can drive this handshake.
+            if (event.origin !== dashboardOrigin)
+                return;
+            if (event.source !== iframe.contentWindow)
+                return;
+            const data = event.data;
+            if (!data || data[ENVELOPE] !== PROTOCOL_VERSION)
+                return;
+            switch (data['type']) {
+                case 'ready': {
+                    if (readyTimer !== undefined)
+                        clearTimeout(readyTimer);
+                    iframe.contentWindow?.postMessage({ [ENVELOPE]: PROTOCOL_VERSION, type: 'init', surface, params }, dashboardOrigin);
+                    // Embed page mounted; fade the loader out (delayed removal so the
+                    // last 120ms is a fade, not a snap).
+                    loader.style.opacity = '0';
+                    window.setTimeout(() => {
+                        loader.style.display = 'none';
+                    }, 150);
+                    // Hand the keyboard to the embed now that there is something inside
+                    // to receive it: opening the dialog leaves focus on the close
+                    // button, which is the right place to wait while the frame boots and
+                    // the wrong place to stay once it has. Only when the reader has not
+                    // moved in the meantime, since taking focus back off a control they
+                    // tabbed to during the load is worse than leaving it where it is.
+                    if (document.activeElement === closeButton)
+                        iframe.focus();
+                    break;
+                }
+                case 'resize': {
+                    const height = data['height'];
+                    if (typeof height === 'number' && Number.isFinite(height)) {
+                        const clamped = Math.min(MAX_IFRAME_HEIGHT, Math.max(MIN_IFRAME_HEIGHT, Math.round(height)));
+                        iframe.style.height = `${clamped}px`;
+                    }
+                    break;
+                }
+                case 'export-request': {
+                    // The Download button asks this host to serialise its open doc. The
+                    // docId is the surface's own param, not the child's to choose, so
+                    // the app never serialises a doc the page wasn't opened for. The
+                    // dialog stays open; do not settle the promise.
+                    const requestId = data['requestId'];
+                    const docId = typeof params['docId'] === 'string' ? params['docId'] : '';
+                    const reply = (outcome) => {
+                        iframe.contentWindow?.postMessage({ [ENVELOPE]: PROTOCOL_VERSION, type: 'export-result', requestId, ...outcome }, dashboardOrigin);
+                    };
+                    if (!onExportRequest) {
+                        reply({ ok: false, code: 'no_serializer', message: 'Export is not supported.' });
+                        break;
+                    }
+                    void onExportRequest(docId).then(reply, (err) => {
+                        reply({
+                            ok: false,
+                            code: 'serializer_failed',
+                            message: err instanceof Error ? err.message : 'Serializer failed.',
+                        });
+                    });
+                    break;
+                }
+                case 'request-sign-in': {
+                    // The user clicked the refusal surface's sign-in action. Settle the
+                    // launcher first (this dialog is over; the host is about to
+                    // navigate) so the caller's promise does not dangle on a page that
+                    // is going away, then run the host's sign-in.
+                    settleResolve(null);
+                    onSignInRequested?.();
+                    break;
+                }
+                case 'document-deleted':
+                case 'document-delete-failed': {
+                    // The delete surface reports that the local user is deleting a doc
+                    // (or that the attempt failed). Fire-and-forget: the dialog settles
+                    // separately through its own `result` / `cancel`, so do not settle
+                    // the promise here.
+                    const docId = data['docId'];
+                    if (onLocalDelete && typeof docId === 'string' && docId) {
+                        onLocalDelete(docId, data['type'] === 'document-deleted');
+                    }
+                    break;
+                }
+                case 'result': {
+                    settleResolve({ payload: data['payload'] });
+                    break;
+                }
+                case 'cancel': {
+                    settleResolve(null);
+                    break;
+                }
+                case 'error': {
+                    const message = typeof data['message'] === 'string' && data['message']
+                        ? data['message']
+                        : 'The hosted UI could not be opened.';
+                    settleReject(new BrassError(message, { code: 'embed_error' }));
+                    break;
+                }
+                default:
+                    break;
+            }
+        }
+        // The close button dismisses. A backdrop click does NOT: these surfaces
+        // hold in-progress work (connecting a drive, sharing, picking a
+        // destination), so a stray click outside the card must not throw it away.
+        // Dismissal is the explicit close button or Escape only.
+        closeButton.addEventListener('click', () => settleResolve(null));
+        // Escape dismisses too, matching the close button. This host-side
+        // listener fires for an Escape landing on the modal chrome (the close
+        // button) or the host page behind it; an Escape pressed while focus is
+        // inside the cross-origin iframe never reaches the host, so the embed
+        // page relays it as a `cancel` over the bridge. Capture phase so the
+        // foreground modal wins over any Escape handler the host app registered.
+        function onKeydown(event) {
+            if (event.key === 'Escape' && !settled) {
+                event.stopPropagation();
+                settleResolve(null);
+            }
+        }
+        window.addEventListener('keydown', onKeydown, true);
+        // An open dialog answers Escape itself, and closing it that way would
+        // leave the launcher's promise unsettled. Route it into the one dismissal
+        // path instead; `onKeydown` above normally gets there first, so this is
+        // the backstop for an Escape it does not see.
+        function onCancel(event) {
+            event.preventDefault();
+            settleResolve(null);
+        }
+        overlay.addEventListener('cancel', onCancel);
+        window.addEventListener('message', onMessage);
+        const readyTimeoutMs = unavailable === 'redirect'
+            ? READY_TIMEOUT_SHORT_MS
+            : READY_TIMEOUT_LONG_MS;
+        readyTimer = setTimeout(() => {
+            if (unavailable !== 'reject') {
+                // Graceful fallback: tear down the never-loaded modal and navigate to
+                // the standalone page. The promise never settles (this page is about
+                // to be replaced).
+                if (settled)
+                    return;
+                settled = true;
+                teardown();
+                redirectToStandalone(baseUrl, surface, params, theme);
+                return;
+            }
+            settleReject(new BrassError('The Brass hosted UI did not load. This browser or app context ' +
+                'may block third-party iframes.', { code: 'iframe_unavailable' }));
+        }, readyTimeoutMs);
+        document.body.appendChild(overlay);
+        // The call that makes the dialog modal: without it the chrome paints
+        // identically and Tab keeps walking the host app behind it. Guarded so a
+        // browser without the top layer still gets the chrome, non-modal, rather
+        // than no dialog at all.
+        if (typeof overlay.showModal === 'function')
+            overlay.showModal();
+    });
+}
+export function createHostedUiLauncher(opts) {
+    const baseUrl = opts.dashboardBaseUrl.replace(/\/$/, '');
+    // Parsed once for the postMessage origin checks; a malformed
+    // `dashboardBaseUrl` throws here, at construction, not mid-handshake.
+    const dashboardOrigin = new URL(baseUrl).origin;
+    // Watch for activations from here on, so a surface opened later knows which
+    // control the reader pressed to get there.
+    trackHostedUiActivations();
+    // Default `'light'`: most hosts are light-only, and an `'auto'` default
+    // would put a dark embed inside a light host on a dark-OS user.
+    const theme = opts.theme ?? 'light';
+    // Merge the SDK's fallback session pointer into a surface's bridge params
+    // when this browser blocked the cross-site cookie (so the embed page can
+    // refresh the dashboard's tokens without its own framed cookie). Read at
+    // open time, not launcher-construction time, since the sid is populated by
+    // the first fallback refresh, which may land after the launcher is built.
+    // Every embed surface authenticates the same way, so this is cross-cutting
+    // rather than per-surface like `appId`.
+    const withSession = (params) => {
+        const sid = opts.getSessionToken?.();
+        const actingSub = opts.getActingSub?.();
+        return {
+            ...params,
+            ...(sid ? { sessionToken: sid } : {}),
+            ...(actingSub ? { actingSub } : {}),
+        };
+    };
+    // Open a hosted surface and unwrap its bridge outcome: `null` is a user
+    // dismissal, otherwise the payload. `exportDoc` threads the export
+    // serializer for the document surfaces whose page offers a Download
+    // action.
+    const launch = async (surface, params, unavailable, exportDoc) => {
+        const outcome = await openEmbed(baseUrl, dashboardOrigin, surface, withSession(params), unavailable, theme, exportDoc ? opts.serializeForExport : undefined, 
+        // Only the document-settings / share surface deletes; harmless to pass
+        // for all, since the message arrives only from that surface.
+        opts.onLocalDelete, opts.onSignInRequested);
+        if (!outcome)
+            return null;
+        return outcome.payload;
+    };
+    // Every Brass app shares one sign-in client, so a request's JWT
+    // does not say which app made it. Surfaces that must name the caller
+    // (its scopes on the install screen, its documents in the picker, the app
+    // a share link should open in) read this off the bridge instead.
+    const callerAppParam = () => opts.callingAppId !== undefined ? { appId: opts.callingAppId } : {};
+    return {
+        async selectDocument() {
+            // Thread the calling app id over the bridge (every Brass app shares one
+            // sign-in client, so the origin can't otherwise tell which
+            // app opened the picker). The embed page uses it for a "only documents
+            // this app can open" filter.
+            const params = {};
+            if (opts.callingAppId !== undefined)
+                params['appId'] = opts.callingAppId;
+            // Where the iframe can't be hosted (cookie-partitioning browsers), the
+            // picker falls back to a full-page redirect: the standalone page returns
+            // the pick on these one-shot params, which the SDK consumes on boot to
+            // open the document, first-party and top-level, the context the iframe
+            // fails in. A returned value can't survive that navigation, so the raw
+            // promise resolves only on the in-iframe path; the pick otherwise
+            // arrives through the session.
+            //
+            // That fallback ejects the user from the host app, so the picker takes
+            // the long handshake window (`redirect-with-value`): degrading early on
+            // a slow-but-working iframe costs the user their place for nothing.
+            const pickReturn = opts.pickReturn;
+            if (pickReturn) {
+                params['docParam'] = pickReturn.docParam;
+                params['branchParam'] = pickReturn.branchParam;
+            }
+            return launch('select-document', params, pickReturn ? 'redirect-with-value' : 'reject');
+        },
+        async selectCreateDestination(options) {
+            // The `select-document` surface opened on its New panel via
+            // `intent: 'create'`: the embed page resolves a destination and sends
+            // it back instead of creating the doc, so the create stays on the SDK's
+            // credential path. `name` pre-fills the dialog.
+            const params = { intent: 'create' };
+            if (opts.callingAppId !== undefined)
+                params['appId'] = opts.callingAppId;
+            if (options?.name !== undefined)
+                params['name'] = options.name;
+            return launch('select-document', params, 'reject');
+        },
+        async acquireOrganization() {
+            const params = {};
+            if (opts.callingAppId !== undefined)
+                params['appId'] = opts.callingAppId;
+            return launch('acquire-organization', params, 'reject');
+        },
+        async shareDocument(docId) {
+            // The share-focused dialog, on the same surface `documentSettings`
+            // reaches with `focus: 'share'`. It discards the outcome, so it passes
+            // no `canOpenCopy`: that flag says the caller will route a duplicate's
+            // `newDocId` into `openSiblingDoc`, and this one cannot.
+            await launch('share-document', { ...callerAppParam(), docId, focus: 'share' }, 'redirect', true);
+        },
+        async documentSettings(docId, options) {
+            // The embed page reads `focus` from `init.params`. Defaults to
+            // `'share'` so passing only docId matches the `shareDocument(docId)`
+            // surface.
+            const focus = options?.focus ?? 'share';
+            return launch(
+            // The surface names one dialog with two entry points, and it is what
+            // the overlay carries as `data-brass-hosted-ui`, so it follows what
+            // is on screen rather than which method was called. A host that
+            // selects the share dialog matches it whether the app opened it or
+            // the toolbar's Share did.
+            focus === 'share' ? 'share-document' : 'document-settings', 
+            // `canOpenCopy` tells the surface this caller routes a duplicate's
+            // `newDocId` into `openSiblingDoc`. The hosted page is served
+            // fresh against pinned SDKs, so it offers the Open only to a host
+            // that says it will honour it.
+            { ...callerAppParam(), docId, focus, canOpenCopy: true }, 'redirect', true);
+        },
+        async documentHistory(docId, options) {
+            const params = { docId };
+            if (options?.branch !== undefined)
+                params['branch'] = options.branch;
+            return launch('document-history', params, 'reject');
+        },
+        async selectBranch(docId, options) {
+            const params = { docId };
+            if (options?.branch !== undefined)
+                params['branch'] = options.branch;
+            return launch('select-branch', params, 'reject');
+        },
+        async installApp(organizationId) {
+            // Thread the caller's `appId` over the bridge so the embed page renders
+            // the right app's name + scopes (every Brass app shares one sign-in
+            // user-pool client, so the JWT can't disambiguate). On confirm the
+            // embed page POSTs the install server-side and forwards the response.
+            const params = {};
+            if (opts.callingAppId !== undefined)
+                params['appId'] = opts.callingAppId;
+            if (organizationId !== undefined)
+                params['organizationId'] = organizationId;
+            return launch('install-app', params, 'reject');
+        },
+        async driveResolve(docId) {
+            return launch('drive-resolve', { docId }, 'reject');
+        },
+    };
+}
+//# sourceMappingURL=hosted-ui.js.map