@brass-build/client 0.3.0 → 0.4.1

package/dist/client.js

@@ -1,4 +1,6 @@
 import { buildSignInUrl, buildSignedOutOfAppUrl, refreshTokens, revokeAppApproval, } from './auth-flow.js';
+import { applyAppAssertionHeader, applyClientVersionHeader } from './api-headers.js';
+import { ensureWasmReady } from './wasm-runtime.js';
 import { decodeIdToken } from './jwt.js';
 import { createEmitter } from './emitter.js';
 import { clearParkedDocuments, createOpenDocument, } from './open-document.js';
@@ -9,7 +11,9 @@ import { createImportRunner, } from './importer.js';
 import { isExportMode, startExportGuest, } from './export-guest.js';
 import { readGuestLinkToken } from './guest-link.js';
 import { consumeLaunchOrganizationId } from './launch-context.js';
+import { callService, normalizeServiceHost, listAppServices, } from './call-service.js';
 import { clearAll as clearLastSelections, readLastDocument, storeLastDocument, } from './selection-persistence.js';
+import { clearActingOrganization, fetchActingOrganization, readActingOrganization, resolveActingOrganization, switchActingOrganization, storeActingOrganization, visibleOrganization, } from './acting-organization.js';
 import { DEFAULT_BRANCH_URL_PARAM, DEFAULT_DOC_URL_PARAM, PICK_BRANCH_PARAM, PICK_DOC_PARAM, clearUrlSelection, readUrlSelection, subscribePopState, takePickFromUrl, writeDocIdToUrl, writeUrlSelection, } from './doc-url-sync.js';
 import { composePageTitle, setPageTitle } from './page-title.js';
 import { clearSessionToken, readSessionToken, storeSessionToken, } from './session-persistence.js';
@@ -178,6 +182,35 @@ export class BrassClient {
     // when the app was reached some other way. A create that names no
     // destination of its own lands here; see `launch-context.ts`.
     launchOrganizationId = null;
+    // The organization this page has resolved to act in, and the name the
+    // server gave it. Held for the life of the page load so repeated acts
+    // resolve once; dropped on sign-out, and replaced by a later switch.
+    actingOrganization = null;
+    // Pushed to the account menu, which names the organization once one has a
+    // name. Resolution happens at the first act that needs one, and a document
+    // arrives later still, so the menu is rendered before there is anything to
+    // show and has to hear about it rather than poll.
+    documentWatchForActingOrganization = null;
+    // The open document's organization, named. Null while no document is open,
+    // while its organization is one this reader is not a member of, and until
+    // the name has been read.
+    chromeDocumentOrganization = null;
+    // Drops a name that arrived after the document it was for moved on.
+    chromeOrganizationToken = 0;
+    // Names by organization id, so opening five documents in one organization
+    // reads it once. A null value records that the server did not confirm the
+    // id, which is as durable an answer as a name.
+    organizationNames = new Map();
+    actingOrganizationListeners = new Set();
+    // The resolve in flight, so concurrent acts share one answer and the
+    // chooser opens once. Keyed by whether the caller may be asked, because a
+    // read that answers null where the chooser would open must not settle an
+    // act that is waiting for the person, and an act must not take that null.
+    actingOrganizationResolve = null;
+    // One document's organization, by document id. A document's placement
+    // does not move under an open app, so the read behind it runs once per
+    // id; the in-flight promise is shared so concurrent acts make one call.
+    documentOrganizationIds = new Map();
     // The app's export backend (`Brass.registerSerializer`), invoked by the
     // platform when a hosted surface downloads an app-owned blob doc. One
     // per app; a later registration replaces the earlier.
@@ -213,6 +246,15 @@ export class BrassClient {
         // the click handler that opens a surface, so it would miss the press that
         // opened it and have nothing to hand focus back to on dismissal.
         trackHostedUiActivations();
+        // The WASM this package runs on is fetched from here, so the download
+        // overlaps the auth round-trip below and is usually ready before anything
+        // asks for it. It is deliberately NOT awaited here: an app's sign-in
+        // screen needs no engine, and gating `init` on the download puts several
+        // megabytes in front of the first paint of every app that has one. The
+        // paths that construct a document await it instead. The rejection is
+        // absorbed because this call is only the head start; a failure has to
+        // surface at the open that needs it, which retries the fetch.
+        void ensureWasmReady().catch(() => undefined);
         try {
             // A Brass-hosted bundle resolves its app id and all four origins from
             // the serving slot's runtime descriptor, which is authoritative: the
@@ -321,10 +363,7 @@ export class BrassClient {
         }
         catch (err) {
             const error = err instanceof Error ? err : new Error(String(err));
-            // console.error so the failure is visible in DevTools even when no
-            // onError listener was registered. Prefixed for grep-ability.
-            console.error('[Brass]', error.message);
-            this.fireError(error);
+            this.reportUncatchable(error);
             // Deliberately do not re-throw: callers using
             // `void Brass.init(...).then(setup)` should see .then() fire so the
             // page transitions out of its loading state. signIn() etc. continue
@@ -355,7 +394,21 @@ export class BrassClient {
         }
     }
     signIn() {
-        const appId = this.requireAppId();
+        // Reported rather than thrown, because this is the one gesture an app
+        // offers in a state the SDK itself invited. A failed init resolves with
+        // `authStatus === 'signed-out'`, indistinguishable from a reader who is
+        // genuinely signed out, so every app renders its sign-in control and the
+        // reader clicks it. `signIn` returns void and runs from a click handler,
+        // so a throw there is an uncaught error the app has no way to catch,
+        // raised over a decision the app did not get wrong. The error channel
+        // carries it to the same places, and to the listener the app registered.
+        if (!this.initialized || !this.appId) {
+            this.reportUncatchable(new Error(this.initialized
+                ? 'Brass.init was called without an app ID'
+                : 'Call Brass.init(appId) first'));
+            return;
+        }
+        const appId = this.appId;
         if (typeof window === 'undefined') {
             throw new Error('Brass.signIn must be called in a browser');
         }
@@ -409,6 +462,11 @@ export class BrassClient {
         // Clear the per-app selection-persistence layer so the next user
         // on this tab doesn't see the previous user's last selection.
         clearLastSelections(appId);
+        // Same for the organization this app was acting in: the next user's
+        // memberships are their own, so both the stored choice and this page
+        // load's resolution go with the session.
+        clearActingOrganization(appId);
+        this.retireActingOrganizationState();
         const signedOutUrl = buildSignedOutOfAppUrl(this.authBaseUrl, appId, window.location.href);
         // On a Brass-hosted origin, route the sign-out through the edge's
         // /__brass/leave so the first-party brass_site gate cookie is cleared
@@ -449,9 +507,15 @@ export class BrassClient {
             return 'guest';
         return this.user !== null ? 'signed-in' : 'signed-out';
     }
-    // The anonymous public-link token this page was opened with
-    // (`?brass_link=`), or null on the ordinary signed-in path. Set during
-    // `init` and read by the session to boot the read-only guest document.
+    // The organization this app is acting in, as far as this page load already
+    // knows. Synchronous, so nothing is resolved to answer it: the open
+    // document's organization outranks the rest for the same reason it does in
+    // the chrome, since it is what every act made while it is open spends.
+    knownOrganizationId() {
+        return (this.chromeDocumentOrganization?.id ??
+            this.actingOrganization?.id ??
+            this.launchOrganizationId);
+    }
     get isGuest() {
         return this.guestLinkTokenValue !== null;
     }
@@ -612,6 +676,21 @@ export class BrassClient {
             signIn: () => this.signIn(),
             signOut: () => this.signOut(),
             dashboardBaseUrl: this._dashboardBaseUrl,
+            getActingOrganization: () => this.visibleActingOrganization(),
+            subscribeActingOrganization: (listener) => {
+                this.actingOrganizationListeners.add(listener);
+                this.watchDocumentForActingOrganization();
+                // A toolbar mounted after a document opened missed the watch's edge,
+                // so ask once on the way in. This is what makes the read pay only for
+                // an app that renders the chrome.
+                void this.refreshChromeOrganization();
+                return () => {
+                    this.actingOrganizationListeners.delete(listener);
+                };
+            },
+            switchOrganization: () => {
+                void this.switchActingOrganization();
+            },
             getDocument: (docId) => this.documents.get(docId),
             // The version-preview bar is a hosted embed; it takes the same theme
             // as the other hosted surfaces.
@@ -672,6 +751,9 @@ export class BrassClient {
             this.hostedUiLauncher = createHostedUiLauncher({
                 dashboardBaseUrl: this._dashboardBaseUrl,
                 callingAppId: appId,
+                // The organization the picker opens on: the one this app is working
+                // in, and otherwise the choice this tab carries for it.
+                actingOrganizationId: () => this.knownOrganizationId() ?? this.preferredOrganizationId(),
                 theme: this.hostedUiTheme,
                 serializeForExport: (docId) => this.serializeForExport(docId),
                 // The hosted delete surface reports a local delete over the bridge so
@@ -869,9 +951,21 @@ export class BrassClient {
     async offerInstallConsent(err) {
         if (!isAppNotInstalled(err) || !err.organizationId)
             return false;
+        const organizationId = err.organizationId;
         try {
-            const result = await this.getHostedUiLauncher().installApp(err.organizationId);
-            return result !== null;
+            const result = await this.getHostedUiLauncher().installApp(organizationId);
+            if (result === null) {
+                // Declining abandons the choice, the way declining the install behind
+                // a switch abandons the switch. Kept, it would pin every later act,
+                // and every later visit, to an organization this app cannot serve,
+                // with the chooser only reachable through the account menu.
+                this.forgetActingOrganization(organizationId);
+                return false;
+            }
+            // The choice became one the app can act in, so now it carries past this
+            // page load.
+            storeActingOrganization(this.requireAppId(), organizationId);
+            return true;
         }
         catch {
             // Hosted UI unavailable here (no DOM, or the dialog failed); the
@@ -879,6 +973,39 @@ export class BrassClient {
             return false;
         }
     }
+    // Everything this page load holds about which organization it acts in, and
+    // what it is called. Enumerated here rather than at each transition,
+    // because the memberships behind every one of these belong to the person
+    // who was signed in: a name, a launch, an open document's organization and
+    // a resolution are all answers about them. A caller that clears a subset
+    // hands the next person the rest, which is what the account menu reads.
+    retireActingOrganizationState() {
+        this.actingOrganization = null;
+        this.launchOrganizationId = null;
+        this.chromeDocumentOrganization = null;
+        this.chromeOrganizationToken += 1;
+        this.organizationNames.clear();
+        this.documentOrganizationIds.clear();
+        this.actingOrganizationResolve = null;
+        this.emitActingOrganization();
+    }
+    // Drop a resolution that never became one the app can act in. Scoped to the
+    // organization named, so a resolution the app has moved on from is left
+    // alone.
+    forgetActingOrganization(organizationId) {
+        if (this.actingOrganization?.id !== organizationId)
+            return;
+        this.actingOrganization = null;
+        // The tab's stored choice is a separate answer from this page load's
+        // resolution: the memo may hold an organization the launch or an open
+        // document supplied while the slot holds a deliberate choice made
+        // earlier, so it is cleared only when it names the same organization.
+        const appId = this.requireAppId();
+        if (readActingOrganization(appId) === organizationId) {
+            clearActingOrganization(appId);
+        }
+        this.emitActingOrganization();
+    }
     // Register the app's export backend. The platform calls it when a
     // hosted surface downloads an app-owned (blob) document: it receives
     // the open Document and returns the source file's bytes, the inverse of
@@ -1105,7 +1232,7 @@ export class BrassClient {
                     // against it.
                     acquireOrganization: () => this.getHostedUiLauncher().acquireOrganization(),
                 },
-                launchOrganizationId: () => this.launchOrganizationId,
+                preferredOrganizationId: () => this.knownOrganizationId(),
                 reportError: (err) => this.fireError(err),
             });
         }
@@ -1163,6 +1290,430 @@ export class BrassClient {
     // calls `getAccessToken()` then this reads the same (possibly just
     // refreshed) token set without forcing a second refresh. Rejects on a
     // transient outage for the same reason `getAccessToken` does.
+    // Which organization the next act spends, resolved at the act rather than
+    // at boot: the open document's organization, one already resolved on this
+    // page load, and otherwise the server's answer from the caller's context,
+    // with the hosted dialog asking where context cannot decide. An app never
+    // names one, so this is the only place the answer comes from.
+    // `ask: false` answers null where the chooser would open, for a read an app
+    // makes before the person has pressed anything.
+    //
+    // One resolve at a time per mode: concurrent acts share the in-flight one,
+    // so the chooser opens once and every caller hears the same answer. The two
+    // modes stay apart, since a read must not wait on a dialog and an act must
+    // not take a read's null as its answer.
+    resolveActingOrganizationId(options) {
+        const ask = options === undefined;
+        const inFlight = this.actingOrganizationResolve;
+        if (inFlight !== null && inFlight.ask === ask)
+            return inFlight.promise;
+        const promise = this.runActingOrganizationResolve(ask).finally(() => {
+            if (this.actingOrganizationResolve?.promise === promise) {
+                this.actingOrganizationResolve = null;
+            }
+        });
+        this.actingOrganizationResolve = { ask, promise };
+        return promise;
+    }
+    runActingOrganizationResolve(ask) {
+        const appId = this.requireAppId();
+        return resolveActingOrganization({
+            activeDocumentOrganizationId: () => this.activeDocumentOrganizationId(),
+            cachedResolution: () => this.actingOrganization?.id ?? null,
+            // The launch value is written into the same slot at boot, so this one
+            // read carries both the stored choice and the launch.
+            launchPreference: () => this.launchOrganizationId,
+            storedPreference: () => readActingOrganization(appId),
+            forgetPreference: () => clearActingOrganization(appId),
+            fetchResolved: (prefer) => this.fetchActingOrganization(prefer),
+            pickOrganization: () => this.pickActingOrganization(this.actingOrganization?.id),
+            remember: (organizationId, organizationName, persist) => {
+                this.setActingOrganization(organizationId, organizationName, persist);
+            },
+        }, ask ? {} : { ask: false });
+    }
+    // The same resolve for a caller that has nowhere to put a null: the ladder
+    // asks, and a person who dismisses the chooser is a BrassError rather than
+    // an organization.
+    async requireActingOrganizationId() {
+        const resolved = await this.resolveActingOrganizationId();
+        // `resolveActingOrganization` throws rather than answering null while it
+        // may ask, so this is a type narrowing rather than a reachable branch.
+        if (resolved === null)
+            throw new BrassError('No organization chosen.', { status: 400 });
+        return resolved;
+    }
+    fetchActingOrganization(prefer) {
+        return fetchActingOrganization({
+            apiBaseUrl: this.apiBaseUrl,
+            getAccessToken: () => this.getAccessToken(),
+            getAppAssertion: () => this.getAppAssertion(),
+        }, prefer);
+    }
+    // The hosted organization picker: it lists the caller's own organizations
+    // and offers to create or join one, which is the whole question being asked
+    // here. An install is a consequence of the answer rather than the question,
+    // so it is left to the act that needs one: the call the resolution feeds
+    // refuses `app_not_installed` and raises the install dialog against the
+    // organization just chosen. Null when the person closed it.
+    //
+    // The surface is iframe-only, since a chosen organization cannot survive a
+    // redirect fallback, so a context that cannot host one (a browser
+    // partitioning third-party storage) cannot ask this question at all. That
+    // reaches the caller as a rejection rather than a dismissal: an act
+    // refuses with it, and a deliberate switch reports it, which is what keeps
+    // the menu's own control from reading as dead.
+    async pickActingOrganization(current) {
+        const result = await this.getHostedUiLauncher().selectOrganization(current);
+        return result?.organization_id ?? null;
+    }
+    // The account menu's switch. The same hosted dialog the resolution opens,
+    // reached deliberately rather than from a refused act, so the reader can
+    // move an app to another organization without going to the dashboard.
+    // Dismissal leaves the current one standing.
+    async switchActingOrganization() {
+        try {
+            await switchActingOrganization({
+                current: () => this.knownOrganizationId(),
+                pickOrganization: (current) => this.pickActingOrganization(current),
+                fetchResolved: (prefer) => this.fetchActingOrganization(prefer),
+                offerInstall: (organizationId) => this.getHostedUiLauncher()
+                    .installApp(organizationId)
+                    .then((r) => r !== null),
+                remember: (organizationId, organizationName) => {
+                    this.setActingOrganization(organizationId, organizationName);
+                },
+                reload: () => {
+                    // A document belongs to one organization, and it decides every act
+                    // made while it is open, so it cannot survive a move to another
+                    // one: leaving it open would put the reader in an organization they
+                    // did not switch to for everything they then did. Closing it is the
+                    // switch, rather than a side effect of it.
+                    //
+                    // The tab's remembered pick goes whether or not one is open, and
+                    // that is the half a close alone does not cover. A reload restores
+                    // the last document a person picked, so a switch made with nothing
+                    // open reopens the document the reader just moved away from, whose
+                    // organization then outranks the one they chose. The switch would
+                    // read as a page reload that changed nothing.
+                    if (this.appId)
+                        clearLastSelections(this.appId);
+                    if (this.session.document !== null)
+                        this.session.close();
+                    if (typeof window !== 'undefined')
+                        window.location.reload();
+                },
+            });
+        }
+        catch (err) {
+            this.fireError(err instanceof Error ? err : new Error(String(err)));
+        }
+    }
+    // The open document's organization. The Document itself does not carry one,
+    // so this reads the record once per document id and remembers it; a
+    // document picked through the hosted picker already named its organization
+    // on the way in, which answers with no request at all.
+    activeDocumentOrganizationId() {
+        // A link guest holds no API credential, so there is nothing to read with.
+        if (this.guestLinkTokenValue !== null)
+            return Promise.resolve(null);
+        const docId = this.session.document?.id;
+        if (!docId)
+            return Promise.resolve(null);
+        const known = this.documentOrganizationIds.get(docId);
+        if (known)
+            return known;
+        const lastPicked = readLastDocument(this.requireAppId());
+        const pending = lastPicked?.doc_id === docId
+            ? Promise.resolve(lastPicked.organization_id)
+            : this.documents
+                .get(docId)
+                .then((record) => record.organization_id)
+                .catch(() => {
+                // The server resolves an organization from the caller's context
+                // without this, so a failed read costs a request rather than the
+                // act that needed one. It is dropped rather than remembered,
+                // since what the read would have answered still outranks that
+                // fallback for every later act on this document.
+                this.documentOrganizationIds.delete(docId);
+                return null;
+            });
+        this.documentOrganizationIds.set(docId, pending);
+        return pending;
+    }
+    // Record the organization this app acts in, from a surface where the person
+    // chose it. Replaces whatever this page load had resolved, so the next act
+    // spends the new one rather than a memo of the old.
+    // @internal
+    // The one writer of the memo, the stored slot and the menu, so a resolution
+    // and a switch cannot report different things to the chrome.
+    // What this tab would offer the server as its preference: the launch value
+    // first, since it is the freshest thing this tab knows, then the choice a
+    // previous act on this page confirmed. Neither is an answer; the server
+    // validates both.
+    preferredOrganizationId() {
+        if (this.launchOrganizationId)
+            return this.launchOrganizationId;
+        return this.appId ? readActingOrganization(this.appId) : null;
+    }
+    setActingOrganization(organizationId, organizationName, 
+    // False while the app is not installed there: the choice holds for this
+    // page load, so the install the refusal raises is about the organization
+    // the reader just picked, and it is written to the slot once that install
+    // lands rather than before. False again for a resolution taken from an
+    // open document, which is where the app is working rather than a choice
+    // the person made.
+    persist = true) {
+        const appId = this.requireAppId();
+        // An id can arrive with no name, from a resolution an open document
+        // answered. Keep a name the chrome has already read for that same
+        // organization rather than blanking the line the reader is looking at.
+        const name = organizationName === '' && this.actingOrganization?.id === organizationId
+            ? this.actingOrganization.name
+            : organizationName;
+        this.actingOrganization = { id: organizationId, name };
+        if (persist)
+            storeActingOrganization(appId, organizationId);
+        this.emitActingOrganization();
+    }
+    visibleActingOrganization() {
+        return visibleOrganization(this.session.document === null
+            ? null
+            : { organization: this.chromeDocumentOrganization }, this.actingOrganization);
+    }
+    // Opening or closing a document changes which organization the next act
+    // spends, so the chrome has to hear about it. Keyed on the document's id
+    // rather than on the session event, which also fires on every mutation.
+    watchDocumentForActingOrganization() {
+        if (this.documentWatchForActingOrganization)
+            return;
+        let lastDocId = this.session.document?.id ?? null;
+        this.documentWatchForActingOrganization = this.session.subscribe(() => {
+            const docId = this.session.document?.id ?? null;
+            if (docId === lastDocId)
+                return;
+            lastDocId = docId;
+            void this.refreshChromeOrganization();
+        });
+    }
+    // Name the organization the chrome would show, where one is already known.
+    //
+    // This never RESOLVES an organization: it asks the server to name an id the
+    // app already holds, and takes the answer only when the server names the
+    // same one back. An app reached by its own URL with nothing stored has no
+    // id, so nothing is asked and the menu stays silent, which is the state a
+    // person who has not acted yet is genuinely in.
+    //
+    // The mismatch case is the load-bearing half. A document can live in an
+    // organization the reader reaches through a directly shared project and is
+    // not a member of; the route then resolves something else, and naming that
+    // would put an organization on screen that has nothing to do with what is
+    // open. So a name is shown only when the server confirms the id asked
+    // about.
+    async refreshChromeOrganization() {
+        const token = ++this.chromeOrganizationToken;
+        const documentOrganizationId = await this.activeDocumentOrganizationId();
+        const named = documentOrganizationId === null
+            ? null
+            : await this.namedOrganization(documentOrganizationId);
+        // A later document (or a switch) started its own resolve while this one
+        // was in flight, and its answer is the current one.
+        if (token !== this.chromeOrganizationToken)
+            return;
+        this.chromeDocumentOrganization = named;
+        // The document is where this app is working, so its organization is what
+        // the next act spends once the document closes: a reader who opens a
+        // model, closes it and creates another would otherwise be asked where to
+        // put the second one, having just worked in the answer. Held for the page
+        // load rather than written to the tab's slot, because it is where the app
+        // was taken rather than a choice the person made.
+        if (named !== null && named.installed) {
+            this.setActingOrganization(named.id, named.name, false);
+        }
+        this.emitActingOrganization();
+        if (documentOrganizationId === null)
+            await this.nameStoredOrganization(token);
+    }
+    // An organization can reach this app as an id with no name: a launch
+    // parameter, the choice this tab carries, or the organization of a document
+    // the reader has just closed. Each is what a cold create and every service
+    // call spend until something else resolves, so the menu owes it a name once
+    // an app renders the chrome, and this is where the memo learns one.
+    //
+    // Nothing happens without an id in hand, which is the case the design turns
+    // on: an app reached by its own URL has none, and asking the server to pick
+    // one so a menu has something to say is the boot-time question this refuses.
+    async nameStoredOrganization(token) {
+        if (!this.appId)
+            return;
+        // A memo carrying a name was named by the server already.
+        if (this.actingOrganization !== null && this.actingOrganization.name !== '') {
+            return;
+        }
+        const stored = this.actingOrganization?.id ?? this.preferredOrganizationId();
+        if (stored === null)
+            return;
+        const named = await this.namedOrganization(stored);
+        // A stored id the caller has since left resolves as some OTHER
+        // organization, which `namedOrganization` refuses. Staying silent is the
+        // right answer: adopting what the server picked would be resolving one to
+        // decorate a menu.
+        if (named === null || token !== this.chromeOrganizationToken)
+            return;
+        // An organization this app is no longer installed on is not one it is
+        // acting in, whatever the tab is carrying. Adopting it here would be the
+        // chrome deciding where acts land: the memo it writes is what the
+        // resolver answers from before it asks the server anything, so the
+        // staleness check on the way in never runs and every act is refused for
+        // an organization somebody deliberately removed this app from. Drop the
+        // carried value and stay silent, which is the state the reader is in.
+        if (!named.installed) {
+            this.forgetActingOrganization(named.id);
+            clearActingOrganization(this.appId);
+            return;
+        }
+        this.setActingOrganization(named.id, named.name);
+    }
+    async namedOrganization(organizationId) {
+        const cached = this.organizationNames.get(organizationId);
+        if (cached !== undefined)
+            return cached;
+        let named = null;
+        try {
+            const outcome = await this.fetchActingOrganization(organizationId);
+            if (outcome.kind === 'resolved' && outcome.organizationId === organizationId) {
+                named = {
+                    id: outcome.organizationId,
+                    name: outcome.organizationName,
+                    installed: outcome.installed,
+                };
+            }
+        }
+        catch {
+            // A name is decoration. A failed read leaves the menu quiet rather than
+            // costing the app anything, and is not cached, so the next document
+            // change asks again.
+            return null;
+        }
+        // A name is durable; whether this app is installed there is not, since an
+        // admin can install it while the page is open. So an answer carrying
+        // `installed: false` is returned and not kept, and the next read asks
+        // again rather than reporting what was true once.
+        if (named === null || named.installed) {
+            this.organizationNames.set(organizationId, named);
+        }
+        return named;
+    }
+    emitActingOrganization() {
+        const visible = this.visibleActingOrganization();
+        for (const listener of this.actingOrganizationListeners) {
+            try {
+                listener(visible);
+            }
+            catch (err) {
+                this.fireError(err instanceof Error ? err : new Error(String(err)));
+            }
+        }
+    }
+    // One brokered call to an outside service the app's manifest declares.
+    // Brass attaches the credential, so the app holds none and the key never
+    // reaches the browser.
+    //
+    // Returns the service's own answer rather than throwing on it: a `401` from
+    // the service, a `409` for a service nobody has keyed yet, and a `429` at a
+    // cap are all results the app renders differently.
+    async callService(host, path, options) {
+        this.requireInit();
+        const service = normalizeServiceHost(host);
+        return callService({
+            apiBaseUrl: this.apiBaseUrl,
+            getAccessToken: () => this.getAccessToken(),
+            getAppAssertion: () => this.getAppAssertion(),
+            resolveOrganization: (ask) => ask
+                ? this.requireActingOrganizationId()
+                : this.resolveActingOrganizationId({ ask: false }),
+            offerInstallConsent: (err) => this.offerInstallConsent(err),
+            offerServiceCredential: (organizationId, serviceHost) => this.offerServiceCredential(organizationId, serviceHost),
+        }, service, path, options);
+    }
+    // Which of the services this app declares would serve a call right now, for
+    // the organization it is acting in. An app whose credential is optional
+    // renders the feature as available or as an upgrade from this, instead of
+    // learning by making a call the reader has already pressed for.
+    //
+    // `ready: false` carries the same `code` the call itself answers with, so an
+    // app branches on one vocabulary rather than two.
+    async listServices() {
+        this.requireInit();
+        // A reader with no session is acting nowhere, which is the state null
+        // reports, so a page that calls this while it loads gets an answer to
+        // render on rather than a rejection. A transient outage rejects from
+        // here, since that is not an answer about where the app is acting.
+        if ((await this.getAccessToken()) === null)
+            return null;
+        // Resolved without the chooser: an app calls this to decide what to
+        // render, before the reader has pressed anything, so a question put here
+        // is one they did not ask for. `callService` is the act, and the act is
+        // where a question belongs.
+        const orgId = await this.resolveActingOrganizationId({ ask: false });
+        // Null is a state the app renders on: it is acting nowhere yet.
+        if (orgId === null)
+            return null;
+        const deps = {
+            apiBaseUrl: this.apiBaseUrl,
+            getAccessToken: () => this.getAccessToken(),
+            getAppAssertion: () => this.getAppAssertion(),
+        };
+        try {
+            return await listAppServices(deps, orgId);
+        }
+        catch (err) {
+            // An organization that has not installed this app is the same kind of
+            // answer as having none resolved: something only a person can settle, so
+            // it is reported here and raised by `callService`, where the reader has
+            // acted.
+            if (isAppNotInstalled(err))
+                return null;
+            throw err;
+        }
+    }
+    // Open the hosted dialog for one service, from the app's own affordance
+    // rather than from a refused call. Resolves true when that host became
+    // usable, which is when a caller re-reads or retries.
+    //
+    // Takes a host the manifest declares, or a pattern it declares where the
+    // address names the account (`*.myshopify.com`). One method rather than two,
+    // because what the caller is asking for is the same in both: an account this
+    // app can spend at a service it declared.
+    async connectService(host) {
+        this.requireInit();
+        const orgId = await this.requireActingOrganizationId();
+        return this.offerServiceCredential(orgId, normalizeServiceHost(host));
+    }
+    // A brokered call was refused for a credential somebody using the app can
+    // supply, which the platform states on the refusal rather than the SDK
+    // reading it off the code. Open the hosted dialog, which asks whoever is
+    // there for whatever the host is missing and tells anyone who cannot answer
+    // who to ask. Resolves true only when this host became usable, in which case
+    // the caller sends the refused call again.
+    async offerServiceCredential(organizationId, host) {
+        try {
+            const result = await this.getHostedUiLauncher().serviceCredential(organizationId, host);
+            if (result === null)
+                return false;
+            // A pattern names a host per account, so what became usable is the
+            // account the reader named rather than the term the app asked under.
+            // Anything under the pattern is what the app can now call.
+            return host.startsWith('*.')
+                ? result.ready.some((ready) => ready.endsWith(host.slice(1)))
+                : result.ready.includes(host);
+        }
+        catch {
+            // Hosted UI unavailable here (no DOM, or the dialog failed); the
+            // original refusal stands.
+            return false;
+        }
+    }
     async getAppAssertion() {
         this.requireInit();
         // Paired with `getAccessToken`: a link guest holds no token to assert
@@ -1203,6 +1754,12 @@ export class BrassClient {
         // and strip it here, so a client-side navigation later in the session
         // cannot lose it and the address bar stays the app's own.
         this.launchOrganizationId = consumeLaunchOrganizationId();
+        // The launch value is held rather than stored. It names the organization
+        // the person was standing in when they clicked Open, so it outranks an
+        // older choice from an earlier load, but nothing has validated it yet:
+        // written straight to the slot, a launch naming an organization this app
+        // cannot act in would be carried by the tab for as long as it lives. The
+        // first resolve that confirms it is what writes it.
         this.pendingAuthCode = consumeAuthCodeParam();
         if (this.pendingAuthCode) {
             // A fresh sign-in just landed. Burn any previously-stored
@@ -1348,6 +1905,25 @@ export class BrassClient {
             nextUser !== null &&
             this.user.sub !== nextUser.sub) {
             this.setTokens(null);
+            this.retireActingOrganizationState();
+        }
+        // A session ENDING, which is where the per-app stashes are dropped.
+        //
+        // They are keyed by app and survive the token set, so they describe the
+        // previous person's pick: their document's name, organization and role,
+        // answered out of storage with no request the server could refuse. The
+        // session's `start()` restores from them, so a stash left behind puts
+        // whoever signs in next into the document the previous person chose.
+        //
+        // On the transition to null rather than on the sub changing, because the
+        // two identities need never meet: a refresh that settles `no_session` in
+        // between (an expiry, a reconnect) drops the tokens, and the arriving
+        // person is then a null-to-user transition that has nothing to compare
+        // against. This branch is also what the retirement above reaches, so the
+        // sub-change path clears through here too.
+        if (this.user !== null && nextUser === null && this.appId) {
+            clearLastSelections(this.appId);
+            clearActingOrganization(this.appId);
         }
         this.tokens = next;
         if (sameUser(this.user, nextUser))
@@ -1381,8 +1957,20 @@ export class BrassClient {
         const token = this.tokens?.accessToken;
         if (!token)
             return;
+        // The same headers every other data-API call carries. The bearer names
+        // the person and never the app, so a platform that requires the acting
+        // app refuses a request holding only it, and this one degrades silently
+        // (see the catch below), which would leave a reader looking at a raw sub
+        // where their name belongs with nothing reporting why.
+        //
+        // Read straight off the held token set rather than through
+        // `getAppAssertion()`, mirroring the access token above: this is
+        // best-effort hydration, so it must not drive a refresh of its own.
         try {
-            const res = await fetch(`${this.apiBaseUrl}/users/${encodeURIComponent(this.user.sub)}`, { headers: { Authorization: `Bearer ${token}` } });
+            const headers = { authorization: `Bearer ${token}` };
+            applyClientVersionHeader(headers);
+            await applyAppAssertionHeader(headers, () => Promise.resolve(this.tokens?.appAssertion ?? null));
+            const res = await fetch(`${this.apiBaseUrl}/users/${encodeURIComponent(this.user.sub)}`, { headers });
             if (!res.ok)
                 return;
             const profile = (await res.json());
@@ -1397,6 +1985,17 @@ export class BrassClient {
             // Profile hydration is best-effort; the app works without it.
         }
     }
+    // One failure reaches a reader exactly once: the listener when one is
+    // registered, the console otherwise. Used by `init`, which resolves rather
+    // than rejecting, and by the void gestures that cannot throw usefully.
+    // Logging unconditionally would double-report, since the README's own
+    // sample logs under this same `[Brass]` prefix. `_reportError` in
+    // documents.ts and open-document.ts is the same rule.
+    reportUncatchable(error) {
+        if (this.errorListeners.size === 0)
+            console.error('[Brass]', error.message);
+        this.fireError(error);
+    }
     requireInit() {
         if (!this.initialized)
             throw new Error('Call Brass.init(appId) first');