@brass-build/client 0.2.0 → 0.4.0

package/src/export-guest.ts

@@ -13,6 +13,7 @@
 // (framer -> guest carries the snapshot; guest -> framer the bytes).
 
 import { Document } from './documents.js';
+import { ensureWasmReady } from './wasm-runtime.js';
 import type { DocumentStreamInfo } from './documents-namespace.js';
 import type { StreamRuntime } from './document-streams.js';
 import type { DocumentSerializer, StoredDocument } from './serializer.js';
@@ -120,6 +121,7 @@ export function startExportGuest(): ExportGuestController {
         return res.streams;
       },
       openLine: async (lineId: string) => {
+        await ensureWasmReady();
         const res = (await fetchFromFramer(hostOrigin, 'stream-snapshot-request', {
           lineId,
         })) as { snapshot: Uint8Array | null; tailOps: Uint8Array[] };
@@ -161,6 +163,9 @@ export function startExportGuest(): ExportGuestController {
       // partitioned document's other streams (`doc.stream(name)`) resolves
       // them over the bridge through the runtime below, so a partitioned
       // document exports in full headless, not just its default stream.
+      // The engine runs for the first time here, and `Brass.init` only starts
+      // its fetch, so a guest that has just booted waits for it once.
+      await ensureWasmReady();
       const doc = snapshot
         ? Document.openFromSnapshot(snapshot, identity)
         : Document.create(identity);

package/src/handle-types.ts

@@ -301,3 +301,38 @@ export interface OrderedMapHandle<T = unknown> {
    */
   onSettled(cb: () => void): HandleUnsubscribe;
 }
+
+
+/**
+ * A handle on a top-level text container. `roots()` reports such a container
+ * as kind `'text'`; this is what reads and writes one.
+ *
+ * Deliberately small. The record surface (`map` / `list` / `orderedMap`) is
+ * where an app models its own data, and a text root is what a document
+ * authored elsewhere may carry, so this covers reading it and replacing it
+ * rather than growing a rich-text editing surface.
+ */
+export interface TextHandle {
+  /** The container's current contents. */
+  read(): string;
+  /**
+   * Replace the contents. Loro diffs against what is stored and applies the
+   * smallest edit that gets there, so a concurrent edit elsewhere in the text
+   * survives, where writing the whole string as one replacement would discard
+   * it.
+   */
+  update(next: string): void;
+  /** Fires once on registration with the current contents, then on every change. */
+  subscribe(cb: TextSubscriber): HandleUnsubscribe;
+}
+
+// A text subscriber. Fires once on registration with the current contents,
+// then on every change. `origin` carries who authored the change, the way
+// `MapSubscriber`'s does, and is undefined on a fire that describes no
+// authored transition (registration, and the whole-container catch-up a
+// checkout or a return to head produces).
+//
+// A field bound to a text container needs it: the value arrives on the app's
+// own keystroke as well as on a peer's, and only the two peers' fires ask
+// the app to move a caret that a person is sitting in.
+export type TextSubscriber = (value: string, origin?: ChangeOrigin) => void;

package/src/handles.ts

@@ -11,7 +11,7 @@ import {
   type LoroEventBatch,
   isContainer,
   type Delta,
-} from 'loro-crdt';
+} from './wasm-runtime.js';
 
 import {
   PAGE_TAG,
@@ -816,9 +816,10 @@ function wrapLoroListProxy(
 // reading / editing `doc.map('instances')` works unchanged. Only a root
 // the `meta` markers name reaches here.
 
-// A flattened entry: whatever the map stores under one key. A codec's record
-// store holds `{ type, params }`; an app's map holds whatever the app assigns,
-// which is any JSON value and which the paged path carries through unchanged.
+// A flattened entry: whatever the map stores under one key. A store of typed
+// records holds `{ type, params }`; an app's map holds whatever the app
+// assigns, which is any JSON value and which the paged path carries through
+// unchanged.
 // Deliberately not narrowed to an object: a write path that assumes fields is
 // what turns `5` into an empty container and `'hello'` into one entry per
 // character.
@@ -2034,8 +2035,8 @@ function rewritePage(
   const page = plainEntry(m, pageKey);
   if (page === undefined) return false;
   // The RAW triples, not the memo's unpacked records: a triple carries either
-  // a codec's tag beside its body or one whole value, and `repackRecord` needs
-  // the original to keep each one in the shape its readers expect.
+  // a tag beside a body or one whole value, and `repackRecord` needs the
+  // original to keep each one in the shape its readers expect.
   const held = decodePageRecords(page);
   if (held.length === 0) return false;
   const next = new Map(group);

package/src/hosted-ui.ts

@@ -19,8 +19,10 @@
 //     document picker).
 //
 // Bridge protocol (envelope `__brass_embed: 1`):
-//   iframe -> host:  ready | resize{height} | result{payload} | cancel |
-//                    error{code,message}
+//   iframe -> host:  ready | booted | resize{height} | result{payload} |
+//                    cancel | error{code,message}
+// `ready` says the frame is alive and answers the timeout below; `booted`
+// says the embed page has drawn something and is what takes the loader off.
 //   host -> iframe:  init{surface,params}
 // The host validates `event.origin === dashboardOrigin` and
 // `event.source === iframe.contentWindow` on every inbound message; the embed
@@ -36,17 +38,28 @@ import { EMBED_ENVELOPE, EMBED_PROTOCOL_VERSION } from './embed-protocol.js';
 //
 // 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.
+// their place, so eating four 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.
+// routed home through a URL round trip), so they wait longer.
+//
+// The embed page answers from a script that runs before its application, so
+// what either window measures is a round trip to the dashboard origin rather
+// than a boot. That is what keeps a slow link on the iframe path: the reader
+// waits out the load inside the app they are in, which is the point of the
+// iframe, instead of being handed a fallback on the strength of how long the
+// embed took to render.
 const READY_TIMEOUT_LONG_MS = 10_000;
 const READY_TIMEOUT_SHORT_MS = 4_000;
 
+// How long a frame that answered `ready` gets to draw something before the
+// spinner comes off anyway. `booted` is what normally takes it off; this
+// covers a boot that dies after the script that pings, and an embed page
+// older than that message. Long, because the cost of being early here is the
+// blank panel the spinner exists to prevent, and the reader can dismiss.
+const REVEAL_TIMEOUT_MS = 10_000;
+
 // What a launcher does when the handshake never completes. See the timeout
 // constants above for the window each one gets.
 type UnavailableMode = 'reject' | 'redirect' | 'redirect-with-value';
@@ -106,6 +119,15 @@ export interface AcquireOrganizationResult {
   organization_id: string;
 }
 
+// Result of the internal select-organization launcher: the organization the
+// person chose, and the name to show for it. The surface answers the question
+// on its own, so a caller that needs the app installed there raises the
+// install dialog after this one settles.
+export interface SelectOrganizationResult {
+  organization_id: string;
+  name: string;
+}
+
 // Result of the internal document-history launcher (opened by the
 // session's `history` file-menu command). Three outcomes:
 //   - `{ branch_id }`: forked a NEW branch; open editable with
@@ -143,6 +165,14 @@ export interface InstallAppResult {
   app_name: string | null;
 }
 
+// Result of the internal service-credential launcher: the hosts that became
+// usable, so a caller retries the call the refusal interrupted only when the
+// host it named is among them. A reader may settle one host of two and leave
+// the other, so a plain "the dialog closed" says less than this.
+export interface ServiceCredentialResult {
+  ready: string[];
+}
+
 // Result of the `drive-resolve` surface (from `Document.resolveDrive()`):
 // how a `behind` / `diverged` drive-linked doc was resolved. `null` when
 // dismissed.
@@ -223,6 +253,16 @@ export interface HostedUiLauncher {
     docId: string,
     options?: { branch?: string },
   ): Promise<{ branch_id: string } | null>;
+  // Hosted organization picker: one row per organization the caller belongs
+  // to, plus an entry that creates or joins one. It asks which organization
+  // and nothing else, so a caller whose act then needs an install raises the
+  // install dialog against the answer. `currentOrganizationId` marks the one
+  // the app is acting in now, where there is one. Resolves with the choice or
+  // `null` on cancel. Iframe-only with a `BrassError` reject (the caller needs
+  // the id back).
+  selectOrganization(
+    currentOrganizationId?: string,
+  ): Promise<SelectOrganizationResult | null>;
   // Hosted install-consent UI: the org admin reviews the requested scopes in
   // plain language and confirms / rejects; on confirm the backend writes the
   // `ORGANIZATION#/INSTALL#` row. Resolves with the row or `null` on cancel.
@@ -236,12 +276,26 @@ export interface HostedUiLauncher {
   // switch onto); publish-over resolves in place (`newDocId: null`). Resolves
   // with the outcome or `null`. Iframe-only with a `BrassError` reject.
   driveResolve(docId: string): Promise<DriveResolveResult | null>;
+  // Hosted surface for a service credential this app is waiting on. Whoever
+  // can supply it connects the account and admits this app to it; anyone else
+  // is told who to ask. Resolves with the hosts that became usable, or `null`
+  // on cancel.
+  // Iframe-only with a `BrassError` reject (the caller needs the hosts back).
+  serviceCredential(
+    organizationId: string,
+    host: string,
+  ): Promise<ServiceCredentialResult | null>;
 }
 
 export interface HostedUiLauncherOptions {
   // Origin the embed pages are served from. `Brass.init`'s `dashboardBaseUrl`,
   // defaulted by the client.
   dashboardBaseUrl: string;
+  // The organization the app is working in, read at launch time rather than
+  // captured, since a document opening moves it. Scopes the picker's opening
+  // list; absent leaves it on everything the caller can reach, which is what
+  // an app that has not resolved one yet should show.
+  actingOrganizationId?: () => string | null;
   // Threaded into param payloads for surfaces that need it (`installApp`).
   // Every Brass app shares one sign-in client, so the JWT can't
   // disambiguate the asking app; the embed page reads `appId` off the bridge.
@@ -407,6 +461,21 @@ export function trackHostedUiActivations(): void {
   document.addEventListener('keydown', trackActivation, true);
 }
 
+// Whether this surface is the one on top. An app can open a second surface
+// over the first (a toolbar command while a picker is up, a trigger pressed
+// twice), and each one listens for Escape on `window`, where
+// `stopPropagation` does not reach a sibling listener on the same target, so
+// one Escape would dismiss every surface at once and resolve `null` to
+// callers whose dialog the reader never touched. Read off the document rather
+// than a registry the launcher maintains: the surfaces are appended in the
+// order they open, so the last one in document order is the last one in the
+// top layer, and an overlay removed by anything at all stops counting the
+// moment it leaves.
+function isTopmostSurface(overlay: HTMLElement): boolean {
+  const open = document.querySelectorAll('[data-brass-hosted-ui]');
+  return open[open.length - 1] === overlay;
+}
+
 // 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(): HTMLElement | null {
@@ -555,11 +624,11 @@ function openEmbed(
     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`.
+    // Loading spinner over the iframe until the embed page reports `booted`.
+    // Without it the user sees a blank panel 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.
     const loader = document.createElement('div');
     Object.assign(loader.style, {
       position: 'absolute',
@@ -596,6 +665,8 @@ function openEmbed(
 
     let settled = false;
     let readyTimer: ReturnType<typeof setTimeout> | undefined;
+    let revealTimer: ReturnType<typeof setTimeout> | undefined;
+    let revealed = false;
 
     // 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
@@ -624,11 +695,31 @@ function openEmbed(
       window.removeEventListener('keydown', onKeydown, true);
       overlay.removeEventListener('cancel', onCancel);
       if (readyTimer !== undefined) clearTimeout(readyTimer);
+      if (revealTimer !== undefined) clearTimeout(revealTimer);
       if (overlay.open) overlay.close();
       overlay.remove();
       restoreFocus();
     }
 
+    // Hand the frame to the reader: the embed page has drawn something, so
+    // the spinner comes off and the keyboard goes in.
+    function revealFrame(): void {
+      if (revealed) return;
+      revealed = true;
+      if (revealTimer !== undefined) clearTimeout(revealTimer);
+      // Delayed removal so the last 120ms is a fade, not a snap.
+      loader.style.opacity = '0';
+      window.setTimeout(() => {
+        loader.style.display = 'none';
+      }, 150);
+      // Opening the dialog leaves focus on the close button, which is the
+      // right place to wait out the load and the wrong place to stay once
+      // there is something inside to receive the keyboard. 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.
+      if (document.activeElement === closeButton) iframe.focus();
+    }
+
     function settleResolve(value: EmbedOutcome | null): void {
       if (settled) return;
       settled = true;
@@ -653,24 +744,26 @@ function openEmbed(
 
       switch (data['type']) {
         case 'ready': {
+          // The frame is alive, which is the whole of what the window above
+          // asks. The embed page posts this from a pre-boot script, so it
+          // arrives while the application behind it is still loading and
+          // there is nothing to look at yet.
           if (readyTimer !== undefined) clearTimeout(readyTimer);
           iframe.contentWindow?.postMessage(
             { [EMBED_ENVELOPE]: EMBED_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();
+          if (revealTimer === undefined && !revealed) {
+            // A frame that comes alive and then draws nothing (a boot that
+            // dies past its first script) would otherwise sit under the
+            // spinner for as long as the reader waits. Show them what is
+            // there instead, and let them close it.
+            revealTimer = setTimeout(revealFrame, REVEAL_TIMEOUT_MS);
+          }
+          break;
+        }
+        case 'booted': {
+          revealFrame();
           break;
         }
         case 'resize': {
@@ -765,10 +858,9 @@ function openEmbed(
     // 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: KeyboardEvent): void {
-      if (event.key === 'Escape' && !settled) {
-        event.stopPropagation();
-        settleResolve(null);
-      }
+      if (event.key !== 'Escape' || settled || !isTopmostSurface(overlay)) return;
+      event.stopPropagation();
+      settleResolve(null);
     }
     window.addEventListener('keydown', onKeydown, true);
 
@@ -778,6 +870,7 @@ function openEmbed(
     // the backstop for an Escape it does not see.
     function onCancel(event: Event): void {
       event.preventDefault();
+      if (!isTopmostSurface(overlay)) return;
       settleResolve(null);
     }
     overlay.addEventListener('cancel', onCancel);
@@ -904,6 +997,14 @@ export function createHostedUiLauncher(
       // this app can open" filter.
       const params: Record<string, unknown> = {};
       if (opts.callingAppId !== undefined) params['appId'] = opts.callingAppId;
+      // Where the app is working, so the picker opens there rather than on
+      // every document the person can reach. Without it the first list an app
+      // shows spans organizations the app is not installed on, and picking
+      // one of those moves the app somewhere the person did not choose to be.
+      // The picker's own Go-to still reaches everywhere, including work
+      // shared directly from an organization they do not belong to.
+      const actingOrganizationId = opts.actingOrganizationId?.();
+      if (actingOrganizationId) params['organizationId'] = actingOrganizationId;
       // 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
@@ -999,6 +1100,20 @@ export function createHostedUiLauncher(
       if (options?.branch !== undefined) params['branch'] = options.branch;
       return launch<{ branch_id: string }>('select-branch', params, 'reject');
     },
+    async selectOrganization(
+      currentOrganizationId?: string,
+    ): Promise<SelectOrganizationResult | null> {
+      // The list is read on the dashboard origin and never crosses the
+      // bridge; only the chosen organization comes back. `appId` rides it for
+      // the same reason the install dialog needs it: one sign-in client
+      // serves every app, so the JWT cannot say which app is asking.
+      const params: Record<string, unknown> = {};
+      if (opts.callingAppId !== undefined) params['appId'] = opts.callingAppId;
+      if (currentOrganizationId !== undefined) {
+        params['organizationId'] = currentOrganizationId;
+      }
+      return launch<SelectOrganizationResult>('select-organization', params, 'reject');
+    },
     async installApp(organizationId?: string): Promise<InstallAppResult | null> {
       // 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
@@ -1012,5 +1127,16 @@ export function createHostedUiLauncher(
     async driveResolve(docId: string): Promise<DriveResolveResult | null> {
       return launch<DriveResolveResult>('drive-resolve', { docId }, 'reject');
     },
+    async serviceCredential(
+      organizationId: string,
+      host: string,
+    ): Promise<ServiceCredentialResult | null> {
+      // `appId` rides the bridge for the same reason the install dialog needs
+      // it: one sign-in client serves every app, so the JWT cannot say which
+      // app is asking, and this screen grants that app in particular.
+      const params: Record<string, unknown> = { organizationId, host };
+      if (opts.callingAppId !== undefined) params['appId'] = opts.callingAppId;
+      return launch<ServiceCredentialResult>('service-credential', params, 'reject');
+    },
   };
 }

package/src/importer.ts

@@ -1,6 +1,7 @@
 import type { Document } from './documents.js';
 import type { DocumentSourceBlob } from './documents-namespace.js';
 import { BrassError } from './errors.js';
+import { whenSaved } from './when-saved.js';
 
 // The app's import half for a file Brass does not parse: given the stored
 // source file and the open document, parse the bytes and write the records
@@ -72,9 +73,17 @@ const CLAIM_REFUSED_STATUS = 422;
 // protocol is testable against mocked HTTP deps.
 export function createImportRunner(deps: ImportRunnerDeps): ImportRunner {
   let importer: DocumentImporter | null = null;
-  // One attempt per Document instance; a reopen mints a new instance,
-  // whose claim resolves `already_imported` as a no-op.
-  const attempted = new WeakSet<Document>();
+  // One attempt per OPEN, recorded as the open generation the attempt was
+  // made in. The mark cannot be per-instance: an app's `close()` parks the
+  // Document and the park cache hands the SAME instance back on reopen, so a
+  // bare mark says "this document already had its attempt" for the life of the
+  // page. Every path that leaves the file unimported (the claim failing, the
+  // importer throwing, the writes never draining) is then unrecoverable
+  // without a reload, and the reopen the reader reaches for does nothing and
+  // says nothing. Keyed on the open, a reopen attempts again; a document whose
+  // import already finished spends one claim that resolves `already_imported`,
+  // which is what a reopen has always cost on a fresh instance.
+  const attempted = new WeakMap<Document, number>();
   // Documents waiting on server-side work, holding the detach for the status
   // listener that is watching it. Kept apart from `attempted` so the wait does
   // not consume the attempt, and holding the DETACH rather than a bare mark so
@@ -93,7 +102,10 @@ export function createImportRunner(deps: ImportRunnerDeps): ImportRunner {
       importer = fn;
     },
     async attempt(doc: Document): Promise<void> {
-      if (importer === null || doc.id === null || attempted.has(doc)) return;
+      if (importer === null || doc.id === null) return;
+      if (attempted.has(doc) && attempted.get(doc) === doc._openGeneration) {
+        return;
+      }
       // Claiming an import binds the document to THIS client for the claim's
       // lifetime, and only this client can complete it. A document that is
       // closed or parked can no longer read its source or write records, so a
@@ -124,7 +136,7 @@ export function createImportRunner(deps: ImportRunnerDeps): ImportRunner {
           waiting.set(doc, off);
         } catch {
           // The document closed while attaching; nothing left to import
-          // into, and a reopen mints a fresh instance that attempts again.
+          // into, and the attempt is unspent, so the reopen attempts again.
         }
         return;
       }
@@ -132,7 +144,7 @@ export function createImportRunner(deps: ImportRunnerDeps): ImportRunner {
       // rather than leave it to fire against a document already past it.
       waiting.get(doc)?.();
       waiting.delete(doc);
-      attempted.add(doc);
+      attempted.set(doc, doc._openGeneration);
       const run = importer;
       const docId = doc.id;
       let claim: ImportClaimResponse;
@@ -174,6 +186,7 @@ export function createImportRunner(deps: ImportRunnerDeps): ImportRunner {
         const stopWatchingWrites = doc.subscribe(() => {
           if (doc.savingCount > 0) wroteRecords = true;
         });
+        let saved = false;
         try {
           await run(source, doc);
           // The importer's ops are still in flight when it returns, and
@@ -181,19 +194,19 @@ export function createImportRunner(deps: ImportRunnerDeps): ImportRunner {
           // the head it lands on. Completing before they are acked stamps
           // a version below the records' own, which reads as a document
           // edited since it was uploaded from then on.
-          await whenSaved(doc);
+          saved = await whenSaved(doc);
         } finally {
           stopRefresh();
           stopWatchingWrites();
         }
-        // The wait above ends on the document going as well as on its writes
-        // draining, and only one of those means the records are stored. The
-        // completion stamps the document with the app's schema at the version
-        // it lands on, so running it over writes that never reached the server
-        // records an import of records the document does not hold. Abandoning
-        // instead leaves the claim to expire, and a client that is still open
-        // imports the file properly.
-        if (!doc._isLive) return;
+        // The wait ends on the document going, and on the acks stopping, as
+        // well as on the writes draining, and only the last of those means
+        // the records are stored. The completion stamps the document with the
+        // app's schema at the version it lands on, so running it over writes
+        // that never reached the server records an import of records the
+        // document does not hold. Abandoning instead leaves the claim to
+        // expire, and a client that is still open imports the file properly.
+        if (!saved) return;
         // An importer that returns without writing anything must not stamp the
         // document imported: the stamp is permanent, a later open reads
         // `already_imported`, and the file's records then have no path into a
@@ -270,53 +283,6 @@ export function createImportRunner(deps: ImportRunnerDeps): ImportRunner {
   return runner;
 }
 
-// How often the wait below re-checks that the document is still live. A
-// closing document drops its subscribers without firing them, so this is the
-// only thing that ends the wait for one that goes mid-import; it runs solely
-// while an import's writes are draining.
-const SAVED_LIVENESS_POLL_MS = 1_000;
-
-// Resolves once the document has no locally-issued op waiting for its
-// server ack, or once the document is no longer live.
-//
-// The liveness half is not belt-and-braces. Closing a Document CLEARS its
-// subscribers rather than firing them, so a wait that watched the ack count
-// alone would never settle for a document closed with writes outstanding, and
-// the caller's `finally` (which stops renewing the platform's import claim)
-// would never run. Resolving here does not claim the writes landed: the
-// completion that follows is what asserts that, and it fails against a
-// document this client can no longer write.
-function whenSaved(doc: Document): Promise<void> {
-  if (doc.savingCount === 0) return Promise.resolve();
-  return new Promise<void>((resolve) => {
-    let off: (() => void) | undefined;
-    let poll: ReturnType<typeof setInterval> | undefined;
-    const settle = (): void => {
-      off?.();
-      if (poll !== undefined) clearInterval(poll);
-      resolve();
-    };
-    try {
-      off = doc.subscribe(() => {
-        if (doc.savingCount > 0) return;
-        settle();
-      });
-    } catch {
-      // The document closed, so nothing more is going to be acked.
-      resolve();
-      return;
-    }
-    poll = setInterval(() => {
-      if (doc._isLive && doc.savingCount > 0) return;
-      settle();
-    }, SAVED_LIVENESS_POLL_MS);
-    // Node keeps the process alive for a pending interval; this one is
-    // bookkeeping for a wait that ends on its own, so it must not.
-    (poll as { unref?: () => void }).unref?.();
-    if (doc.savingCount === 0) settle();
-  });
-}
-
 function asError(err: unknown): Error {
   return err instanceof Error ? err : new Error(String(err));
 }

package/src/index.ts

@@ -14,6 +14,7 @@ import type {
   OpenedDocument,
 } from './open-document.js';
 import type { SelectDocumentResult } from './hosted-ui.js';
+import type { AppServiceState, CallServiceOptions } from './call-service.js';
 import type { DocumentsNamespace } from './documents-namespace.js';
 import type { DocumentImporter } from './importer.js';
 import type { DocumentSerializer } from './serializer.js';
@@ -36,6 +37,11 @@ export type {
   UserChangeListener,
 };
 export { BrassError, type BrassErrorCode } from './errors.js';
+export type {
+  AppServiceState,
+  CallServiceBody,
+  CallServiceOptions,
+} from './call-service.js';
 export {
   type HostedUiTheme,
   type SelectDocumentResult,
@@ -94,6 +100,7 @@ export {
   type DocumentDriveTrackingState,
   type DriveMirrorDirection,
   type EntityProxy,
+  type RootKind,
   type UndoState,
   type UndoStateSubscriber,
 } from './documents.js';
@@ -110,6 +117,8 @@ export type {
   MapSubscriber,
   OrderedMapHandle,
   OrderedMapPosition,
+  TextHandle,
+  TextSubscriber,
 } from './handle-types.js';
 
 export type {
@@ -140,16 +149,21 @@ export type {
 const client = new BrassClient();
 
 // A Brass-hosted bundle (`*.onbrass.app`) resolves its app id and
-// environment from the serving slot, so it uses the zero-argument form;
-// everywhere else the app id is required.
+// environment from the serving slot, so it takes no id; everywhere else the
+// id is supplied. One bundle does both, so the id argument accepts
+// `undefined` and an app can pass whatever its build resolved to without
+// branching on it.
 function init(options?: BrassInitOptions): Promise<void>;
-function init(appId: string, options?: BrassInitOptions): Promise<void>;
+function init(appId: string | undefined, options?: BrassInitOptions): Promise<void>;
 function init(
   appIdOrOptions?: string | BrassInitOptions,
   options?: BrassInitOptions,
 ): Promise<void> {
   if (typeof appIdOrOptions === 'string') return client.init(appIdOrOptions, options);
-  return client.init(undefined, appIdOrOptions);
+  // With no id in the first position the options are in whichever argument
+  // the caller used: `init(options)` on a hosted bundle, `init(undefined,
+  // options)` from an app that resolves its id at build time.
+  return client.init(undefined, appIdOrOptions ?? options);
 }
 
 export const Brass = {
@@ -180,6 +194,31 @@ export const Brass = {
   getAccessToken(): Promise<string | null> {
     return client.getAccessToken();
   },
+  // One call to an outside service the app's manifest declares, under a
+  // credential Brass holds. Returns the service's own response.
+  callService(
+    host: string,
+    path: string,
+    options?: CallServiceOptions,
+  ): Promise<Response> {
+    return client.callService(host, path, options);
+  },
+  // Which of this app's declared services would serve a call right now, so a
+  // feature that works better with an account connected renders as available
+  // or as an upgrade before the reader presses anything.
+  //
+  // Null while the app is acting in no organization yet, or in one that has
+  // not installed it, which is a state to render the feature as available on.
+  // `connectService` asks when the reader reaches for it.
+  listServices(): Promise<AppServiceState[] | null> {
+    return client.listServices();
+  },
+  // Open the hosted dialog for one service from the app's own affordance.
+  // Whoever can supply the credential does it there; anyone else reads who to
+  // ask. Resolves true when that host became usable.
+  connectService(host: string): Promise<boolean> {
+    return client.connectService(host);
+  },
   // Metadata read for a known id (`get`) plus thumbnails. Create / move /
   // list / grant access are hosted-only.
   get documents(): DocumentsNamespace {