@brass-build/client 0.3.0 → 0.4.0

package/src/open-document.ts

@@ -18,6 +18,7 @@ import {
   type ReadOnlyReason,
   type ResyncPushOutcome,
 } from './documents.js';
+import { ensureWasmReady } from './wasm-runtime.js';
 import { createPresenceController } from './presence.js';
 import type { WsTopicCallback } from './ws-client.js';
 import { applyAppAssertionHeader, applyClientVersionHeader } from './api-headers.js';
@@ -372,10 +373,10 @@ export interface OpenDocumentFactoryOptions {
   // Backs the Document's built-in 'history' / 'manage' / 'share'
   // commands. When absent (tests), those commands render disabled.
   hostedUiProvider?: HostedUiProvider;
-  // The organization this page was launched from (`?brass_org=`), read
-  // through a getter because `init` resolves it after the factory's
-  // options are written. See `createDocumentId`.
-  launchOrganizationId?: () => string | null;
+  // The organization this app is already acting in, read through a getter
+  // because `init` resolves it after the factory's options are written and
+  // because it moves as the reader works. See `createDocumentId`.
+  preferredOrganizationId?: () => string | null;
   // Who is signed in, as the park cache's ownership stamp (see
   // `ParkedDocEntry.identity`). Read at park and at take, so a Document only
   // ever comes back to the person it was opened for. Absent (tests, the
@@ -1192,16 +1193,16 @@ export function createOpenDocument(
     // open on something that clears on its own.
     //
     // Longer than the default handful of attempts because of what a 503 means
-    // on this route: the document is intact and its storage is busy. Every op
-    // row a document has shares one partition, so the document most likely to
-    // answer 503 is one that was just written hard, which is exactly the
+    // on this route: the document is intact and its storage is busy. A
+    // document's own writes contend with each other, so the one most likely
+    // to answer 503 is one that was just written hard, which is exactly the
     // moment a person reloads to see their work. That pressure clears over
     // tens of seconds, not the one second the default budget spans, and the
     // cost of giving up early is telling someone their document will not open
     // when waiting would have opened it.
     //
     // A thrown request gets a short budget of its own: it never reached the
-    // API, so the busy partition is not what is wrong, and a blocked origin
+    // API, so busy storage is not what is wrong, and a blocked origin
     // or a host that does not resolve answers the seventh attempt as it
     // answered the first, with the reader watching a loading surface
     // throughout.
@@ -1344,7 +1345,7 @@ export function createOpenDocument(
   // piped through `open` to materialise the editable Document.
   // What the app hears when an op the socket could not carry also failed
   // over HTTP. The server's message is preferred where it has one, since it
-  // names the actual refusal (too large for the durable row, a revoked
+  // names the actual refusal (too large to store inline, a revoked
   // role); the status-shaped fallbacks cover a response that carries none.
   function opWriteFailureMessage(status: number, parsed: unknown): string {
     const serverMessage = (parsed as { error?: unknown } | undefined)?.error;
@@ -1356,12 +1357,12 @@ export function createOpenDocument(
     return `This change could not be saved (${status}).`;
   }
 
-  // Write one op over HTTP. The socket carries an op only up to API
-  // Gateway's message cap; past it the message is not delivered and the
-  // connection is closed, so `wireDocTransport` sends the large ones here.
+  // Write one op over HTTP. The socket carries an op only up to its own
+  // message cap; past it the message is not delivered and the connection is
+  // closed, so `wireDocTransport` sends the large ones here.
   // Not retried on a transient failure: the caller holds the op in its
   // outstanding tracker and re-asserts it, and a blind replay would write a
-  // second durable row for the same edit.
+  // second stored copy of the same edit.
   // Mint a presigned PUT and upload the blob to it, returning the staging
   // key the op write names. The PUT carries no Brass headers: the URL is
   // signed, and an extra header falls outside that signature.
@@ -1433,9 +1434,9 @@ export function createOpenDocument(
     };
     applyClientVersionHeader(headers);
     await applyAppAssertionHeader(headers, opts.getAppAssertion);
-    // Past what a durable row holds, the blob goes to storage directly
-    // and the write names the staged object, so a multi-megabyte op
-    // never travels through a request body.
+    // Past the size an op can carry inline, the blob is uploaded first and
+    // the write names what was staged, so a multi-megabyte op never travels
+    // through a request body.
     let stagedKey: string | undefined;
     if (opBlobNeedsStaging(opBlobB64)) {
       stagedKey = await stageOpBlob(docId, opBlobB64, token);
@@ -1525,32 +1526,36 @@ export function createOpenDocument(
   // a needed destination / organization before showing a loading state; any
   // other non-2xx throws.
   //
-  // A create that names no placement of its own inherits the organization
-  // the page was launched from, so a member of several organizations who
-  // opened this app from one of them is not asked to name a destination
-  // they already chose. An explicit `siblingOf` / `destination` outranks it:
-  // placing a document beside the open one is the more specific answer.
+  // A create that names no placement of its own lands in the organization the
+  // app is already acting in: the one a launch named, the one a document the
+  // reader just closed lives in, or the one they chose in the account menu's
+  // switch. Without it a member of several organizations is asked to name a
+  // destination they have already answered, once per create. An explicit
+  // `siblingOf` / `destination` outranks it: placing a document beside the
+  // open one is the more specific answer.
   const createDocumentId = async (
     args: CreateDocumentArgs,
   ): Promise<CreateDocumentResult> => {
-    const launchOrganizationId =
+    const preferred =
       args.siblingOf === undefined && args.destination === undefined
-        ? (opts.launchOrganizationId?.() ?? null)
+        ? (opts.preferredOrganizationId?.() ?? null)
         : null;
-    if (launchOrganizationId === null) return postAndClassify(args);
+    if (preferred === null) return postAndClassify(args);
     try {
       return await postAndClassify({
         ...args,
-        destination: { organization_id: launchOrganizationId },
+        destination: { organization_id: preferred },
       });
     } catch (err) {
-      // The launch organization is a hint carried on a URL, so it can name
-      // an organization the person has since left, which the server answers
-      // with a plain 404. Drop the hint and let the server resolve the
-      // destination on its own, which routes a multi-organization caller to
-      // the picker. A coded rejection (`app_not_installed`) belongs to the
-      // caller's own consent flow and passes through untouched, as does the
-      // 404 for an organization that exists but denies the app.
+      // Every source of this value is a preference rather than an answer: a
+      // URL parameter, a document open in an organization reached through a
+      // shared project, a choice made before the person left. Each can name
+      // an organization the caller no longer has, which the server answers
+      // with a plain 404. Drop it and let the server resolve the destination
+      // on its own, which routes a multi-organization caller to the picker. A
+      // coded rejection (`app_not_installed`) belongs to the caller's own
+      // consent flow and passes through untouched, as does the 404 for an
+      // organization that exists but denies the app.
       if (err instanceof BrassError && err.status === 404 && !err.code) {
         return postAndClassify(args);
       }
@@ -1792,6 +1797,7 @@ export function createOpenDocument(
         resyncFromSnapshot,
         skipPresence: true,
         parkable: false,
+        capacityReloadsDocument: false,
       });
     }
     return doc;
@@ -2307,6 +2313,11 @@ export function createOpenDocument(
       }
     }
     if (opts.reportError) doc.setErrorReporter(opts.reportError);
+    // No socket on a document the caller can write to: the write path reaches
+    // no server, so the document reports the first attempt rather than
+    // discarding it. Outside tests this is `wsBaseUrl` left unset, which
+    // naming any other base URL does.
+    if (!opts.wsClient && !doc.readOnly) doc.markTransportUnavailable();
     return doc;
   }
 
@@ -2594,7 +2605,12 @@ export function createOpenDocument(
     canEdit: boolean,
   ): void {
     const wsClient = opts.wsClient;
-    if (!wsClient) return;
+    if (!wsClient) {
+      // No socket: a write would change local state and reach no server, so
+      // the document reports the first one instead of discarding it quietly.
+      if (canEdit) doc.markTransportUnavailable();
+      return;
+    }
     const topic = `doc:${docId}:${lineId}`;
 
     // Ops on the socket awaiting an answer, keyed by `client_op_id`. An
@@ -2932,11 +2948,12 @@ export function createOpenDocument(
   // create + obtain the doc_id, then `open(docId)`); they aren't fused
   // because the create response is metadata-only and the open path already
   // handles the empty-snapshot case via `Document.create()`. This is the
-  // low-level path (`Brass.createDocument`): the server places the doc in
-  // the caller's single organization; a caller with none is routed to the
-  // hosted acquire-organization surface and the create retries; a multi-org
-  // caller rejects with a 409 (no hosted picker here, that is the session's
-  // `create()`).
+  // low-level path (`Brass.createDocument`): the doc lands in the
+  // organization the app is acting in, and otherwise in the caller's single
+  // organization; a caller with none is routed to the hosted
+  // acquire-organization surface and the create retries; a multi-org caller
+  // whose app is acting nowhere rejects with a 409 (no hosted picker here,
+  // that is the session's `create()`).
   const create: CreateDocumentFn = async (options) => {
     const args: CreateDocumentArgs = { name: options?.name ?? 'Untitled' };
     if (options?.app_metadata !== undefined) args.app_metadata = options.app_metadata;
@@ -3031,6 +3048,13 @@ interface WireDocTransportArgs {
   // by the parent Document (closed on parent close), so it bypasses the
   // park cache and `close()` tears down immediately.
   parkable?: boolean;
+  // True for the session-owned top-level document: an unhealable capacity
+  // refusal tells the user and reloads, because the session reopens the id
+  // and rebinds the app to the platform's copy. False for a stream line,
+  // which has no such owner and is only one part of a document: it marks
+  // itself read-only at capacity and surfaces `stream.atCapacity` instead
+  // of alerting the reader and reloading a document the stream is part of.
+  capacityReloadsDocument?: boolean;
   // The branch the caller REQUESTED (`options.branch`), undefined for a
   // default-branch open. Distinct from `branchId`, which is the branch the
   // server RESOLVED. The park cache keys on this (symmetric with
@@ -3809,6 +3833,18 @@ function wireDocTransport(args: WireDocTransportArgs): void {
       clearTimeout(gapTimer);
       gapTimer = null;
     }
+    // A stream line reaches this only at capacity, and it has no owner to
+    // reopen it: the session reopens the top-level id, but a stream is one
+    // part of a document nothing reloads on its behalf. So it stops the
+    // divergence (above) and marks itself read-only at capacity, which
+    // `stream.readOnly` / `stream.atCapacity` already surface to the app,
+    // rather than alerting the reader and reloading a document it is part
+    // of. The diverged edit stays visible until the app reopens the stream;
+    // it reached no other reader, so nothing is lost by leaving it.
+    if (args.capacityReloadsDocument === false) {
+      args.doc._markReadOnly('capacity');
+      return;
+    }
     args.doc._markReadOnly('unsaved');
     // The user is told by the SDK, not by each app, because an app that
     // renders nothing is exactly the case this has to cover: a document that
@@ -4762,6 +4798,11 @@ async function materialise(
   documentOptions?: DocumentOptions,
   onSnapshotProgress?: (loaded: number, total: number | null) => void,
 ): Promise<OpenedDocument> {
+  // Constructing the document is the first thing in this package that runs the
+  // WASM, and `Brass.init` only starts the fetch, so this is where it is
+  // waited on. Usually it resolved during the auth round-trip and this costs
+  // nothing.
+  await ensureWasmReady();
   // Stamp the server-minted doc_id onto the Document (via DocumentOptions, so
   // it threads through the LoroDoc constructor without changing the static
   // factory signatures) so callers can read `doc.id` to correlate.

package/src/presence.ts

@@ -78,6 +78,12 @@ export interface PresenceState {
   /** Entity ids the user has selected. Use to highlight remote
    * selections so collaborators see what each other is working on. */
   selection?: string[];
+  /** Where the user's caret sits in a text container. `key` names the
+   * container (`doc.text(key)`), and both offsets count UTF-16 code
+   * units into its value: `anchor` where the selection began, `head`
+   * where it is now, equal for a plain caret. Use it to draw remote
+   * carets in prose, the way `selection` highlights picked entities. */
+  textCaret?: { key: string; anchor: number; head: number };
 }
 
 // A live participant on a presence topic. Keyed on `connectionId` (one

package/src/session-toolbar.ts

@@ -73,6 +73,17 @@ export interface AccountMenuDeps {
   // dashboard" link. The client's resolved dashboard origin (picks the
   // environment), with no trailing slash.
   dashboardBaseUrl: string;
+  // The organization this app is currently acting in, or null while none has
+  // been resolved or the one resolved has no name yet.
+  getActingOrganization?: () => { id: string; name: string } | null;
+  // Push-based, because the value is resolved lazily at the first act that
+  // needs it and can change when the reader switches.
+  subscribeActingOrganization?: (
+    listener: (organization: { id: string; name: string } | null) => void,
+  ) => () => void;
+  // Opens the hosted surface that picks the organization to act in, which is
+  // also where one gets created.
+  switchOrganization?: () => void;
 }
 
 export type SessionToolbarDeps = FileMenuDeps &
@@ -200,7 +211,8 @@ const CSS = `
   margin:4px 2px; }
 /* [hidden] must beat the block rule above (the account menu swaps its body
    between signed-in actions and the guest's "Sign in"). */
-.b-pop button[hidden], .b-pop a[hidden], .b-pop .b-email[hidden] { display:none; }
+.b-pop button[hidden], .b-pop a[hidden], .b-pop .b-email[hidden],
+.b-pop .b-account-org[hidden] { display:none; }
 .b-identity { display:flex; flex-direction:column; align-items:flex-start;
   gap:1px; min-width:0; }
 /* Cancels the horizontal padding the title and location carry for their focus
@@ -267,9 +279,12 @@ const CSS = `
 /* minmax(0,1fr) so a long name or email ellipsizes instead of widening the
    menu: a grid item's default min-width is its content's intrinsic size. */
 .b-account-id { display:grid; grid-template-columns:minmax(0,1fr); gap:1px; min-width:0; }
-.b-account-name, .b-email { overflow:hidden; text-overflow:ellipsis; white-space:nowrap; }
+.b-account-name, .b-email, .b-account-org {
+  overflow:hidden; text-overflow:ellipsis; white-space:nowrap; }
 .b-account-name { font-size:13px; font-weight:600; line-height:1.3; }
-.b-email { color:var(--brass-fg-muted); font-size:12px; line-height:1.3; }
+/* The organization line qualifies the identity rather than naming it, so it
+   sits at the address's quiet tier and never competes with the name above. */
+.b-email, .b-account-org { color:var(--brass-fg-muted); font-size:12px; line-height:1.3; }
 .b-account .b-pop button, .b-account .b-pop a {
   display:flex; align-items:center; gap:10px; font-size:13px; }
 .b-account .b-pop svg { flex:0 0 auto; color:var(--brass-fg-muted); }
@@ -1272,22 +1287,25 @@ function buildAccountMenu(deps: AccountMenuDeps): PieceInternal {
     align: 'end',
   });
   // The menu opens on the identity it acts for: the avatar at reading size,
-  // the display name, and the email under it. The name line drops out when the
-  // user has none, leaving the email as the single identifying line.
+  // the display name, the email under it, and the organization the app acts in
+  // under that. The name line drops out when the user has none, leaving the
+  // email as the single identifying line.
   const head = el('div', 'b-account-head');
   const headFace = buildAvatarFace();
   const faceEl = el('span', 'b-account-face');
   faceEl.append(...headFace.nodes);
   const nameEl = el('div', 'b-account-name');
   const emailEl = el('div', 'b-email');
+  const orgEl = el('div', 'b-account-org');
   const identity = el('div', 'b-account-id');
-  identity.append(nameEl, emailEl);
+  identity.append(nameEl, emailEl, orgEl);
   head.append(faceEl, identity);
   const headSep = el('hr', 'b-sep');
   headSep.setAttribute('role', 'separator');
   // Opens the dashboard in a new tab, so the user keeps the app open in the
-  // current one. `/home` is the authenticated landing (resolves the active
-  // org); the bare origin is the sign-in page.
+  // current one, and lands in the organization the app is working in rather
+  // than wherever the dashboard was left. `/home` is the authenticated
+  // landing and stands in when the app is working in none.
   const dashboardLink = el('a');
   dashboardLink.append(
     strokeIcon(
@@ -1301,6 +1319,23 @@ function buildAccountMenu(deps: AccountMenuDeps): PieceInternal {
   dashboardLink.target = '_blank';
   dashboardLink.rel = 'noopener noreferrer';
   dashboardLink.onclick = () => menu.close();
+  // Sits directly above the dashboard link, so the organization the header
+  // names and the action that changes it read as one block.
+  const switchOrgBtn = el('button');
+  switchOrgBtn.type = 'button';
+  switchOrgBtn.append(
+    strokeIcon(
+      'm17 2 4 4-4 4',
+      'M3 11v-1a4 4 0 0 1 4-4h14',
+      'm7 22-4-4 4-4',
+      'M21 13v1a4 4 0 0 1-4 4H3',
+    ),
+    'Switch organization...',
+  );
+  switchOrgBtn.onclick = () => {
+    menu.close();
+    deps.switchOrganization?.();
+  };
   const signOutBtn = el('button');
   signOutBtn.append(
     strokeIcon('M9 21H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h4', 'm16 17 5-5-5-5', 'M21 12H9'),
@@ -1323,12 +1358,18 @@ function buildAccountMenu(deps: AccountMenuDeps): PieceInternal {
     menu.close();
     deps.signIn();
   };
-  menu.pop.append(head, headSep, dashboardLink, signOutBtn, signInBtn);
+  menu.pop.append(head, headSep, switchOrgBtn, dashboardLink, signOutBtn, signInBtn);
 
   const triggerFace = buildAvatarFace();
   menu.trigger.append(...triggerFace.nodes);
 
-  const renderUser = (user: BrassUser | null): void => {
+  // The menu acts for a (user, organization) pair, and each half arrives on
+  // its own listener, so both are held here and one render draws them.
+  let currentUser = deps.getUser();
+  let organization = deps.getActingOrganization?.() ?? null;
+
+  const render = (): void => {
+    const user = currentUser;
     triggerFace.render(user);
     headFace.render(user);
     nameEl.textContent = user?.display_name ?? '';
@@ -1346,13 +1387,40 @@ function buildAccountMenu(deps: AccountMenuDeps): PieceInternal {
     dashboardLink.hidden = !signedIn;
     signOutBtn.hidden = !signedIn;
     signInBtn.hidden = signedIn;
+    // The organization line names what the app is acting in, so it is drawn
+    // only when there is something to name: an app that has not needed an
+    // organization yet has not resolved one, and resolving one to fill this
+    // line is the boot-time question the platform refuses.
+    const organizationName = signedIn ? (organization?.name ?? '') : '';
+    orgEl.textContent = organizationName;
+    orgEl.title = organizationName;
+    orgEl.hidden = organizationName === '';
+    dashboardLink.href =
+      signedIn && organization
+        ? `${deps.dashboardBaseUrl}/organizations/${encodeURIComponent(organization.id)}`
+        : `${deps.dashboardBaseUrl}/home`;
+    // Offered to every signed-in reader, including one the line has nothing
+    // to name and one who belongs to a single organization. The surface
+    // behind it both moves the app and creates an organization, so gating it
+    // on already having somewhere else to go would withhold it from exactly
+    // the person it is for; and an app reached by its own URL has resolved
+    // nothing to name, which is the state a deliberate choice settles.
+    switchOrgBtn.hidden = !signedIn || deps.switchOrganization === undefined;
   };
-  renderUser(deps.getUser());
-  const unsub = deps.onUserChange(renderUser);
+  render();
+  const unsub = deps.onUserChange((user) => {
+    currentUser = user;
+    render();
+  });
+  const unsubOrganization = deps.subscribeActingOrganization?.((next) => {
+    organization = next;
+    render();
+  });
   return {
     root: menu.root,
     destroy(): void {
       unsub();
+      unsubOrganization?.();
       menu.destroy();
     },
   };

package/src/tail-ops.ts

@@ -1,7 +1,7 @@
 // Tail ops arrive in one of two shapes and are used in only one.
 //
-// An op that fit its durable row carries its bytes inline. One that
-// spilled to storage carries a short-lived signed URL instead, because a
+// An op small enough to store inline carries its bytes. A larger one
+// carries a short-lived signed URL instead, because a
 // join response holding several megabytes of base64 is a response the
 // server cannot build. Both mean the same thing to a reader: bytes to
 // apply, in seq order.

package/src/types.ts

@@ -87,10 +87,12 @@ export interface UndoControllerOptions {
  * A document's own view of how its sync is going, as the client sees it.
  *
  * The server records what reached it, so the facts that separate a write
- * that was lost from a client that is merely slow live only here. Read it
- * when a save is taking longer than it should; `Brass.onError` reports
- * failures, and this reports the state a failure has not yet been declared
- * for.
+ * that was lost from a client that is merely slow live only here.
+ *
+ * @internal Read on demand by Brass's own surfaces, through the `@internal`
+ * `Document.diagnostics()`. An app reads `savingCount` to know a save is
+ * outstanding and `Brass.onError` to hear a failure; the SDK resolves a
+ * stuck save itself.
  */
 export interface DocSyncDiagnostics {
   /** Ops committed locally that the server has not acknowledged. */

package/src/undo.ts

@@ -2,7 +2,7 @@
 // local-peer-scoped (reverts only this peer's ops), group bracketing collapses
 // same-stroke edits into one entry, and remote-import bookkeeping keeps the
 // redo stack honest across other peers' edits.
-import { UndoManager, type LoroDoc } from 'loro-crdt';
+import { UndoManager, type LoroDoc } from './wasm-runtime.js';
 
 import type { UndoControllerOptions } from './types.js';
 

package/src/version-bar.ts

@@ -88,6 +88,10 @@ function clampHeight(h: number): number {
 // takes the strip. Matches the hosted-UI launcher's own long window.
 const VERSION_BAR_READY_TIMEOUT_MS = 10_000;
 
+// How long a frame that answered gets to draw its strip before the
+// placeholder comes off anyway. See `armRevealTimer`.
+const VERSION_BAR_REVEAL_TIMEOUT_MS = 10_000;
+
 export function createVersionBarFrame(
   root: HTMLElement,
   deps: VersionBarDeps,
@@ -164,6 +168,10 @@ export function createVersionBarFrame(
   // one that never answers, which is why this is a timer rather than a
   // handler.
   let readyTimer: ReturnType<typeof setTimeout> | undefined;
+  // The placeholder holds the strip's height until the embed has drawn its
+  // own, which `booted` reports and this timer backstops.
+  let revealed = false;
+  let revealTimer: ReturnType<typeof setTimeout> | undefined;
 
   // Hand the strip to the SDK-drawn fallback, which carries the two controls
   // that need no timeline (return to latest, close).
@@ -174,12 +182,37 @@ export function createVersionBarFrame(
       clearTimeout(readyTimer);
       readyTimer = undefined;
     }
+    if (revealTimer !== undefined) {
+      clearTimeout(revealTimer);
+      revealTimer = undefined;
+    }
     placeholder.style.display = 'none';
     iframe.style.height = '0';
     fallback.hidden = false;
     renderFallback();
   }
 
+  // Give the embed's strip the height the placeholder was holding.
+  function revealFrame(): void {
+    if (destroyed || failed || revealed) return;
+    revealed = true;
+    if (revealTimer !== undefined) {
+      clearTimeout(revealTimer);
+      revealTimer = undefined;
+    }
+    placeholder.style.display = 'none';
+    iframe.style.height = `${READY_HEIGHT}px`;
+  }
+
+  // A frame that answers and then draws nothing (a boot that dies past its
+  // first script, an embed page older than `booted`) holds the placeholder
+  // otherwise. The swap is what the reader's controls arrive with, so take
+  // it on the timer rather than leaving the strip inert.
+  function armRevealTimer(): void {
+    if (revealed || revealTimer !== undefined) return;
+    revealTimer = setTimeout(revealFrame, VERSION_BAR_REVEAL_TIMEOUT_MS);
+  }
+
   function armReadyTimer(): void {
     if (readyTimer !== undefined) clearTimeout(readyTimer);
     readyTimer = setTimeout(() => {
@@ -267,16 +300,23 @@ export function createVersionBarFrame(
     if (!data || data[EMBED_ENVELOPE] !== EMBED_PROTOCOL_VERSION) return;
     switch (data['type']) {
       case 'ready': {
+        // The frame is alive. It says nothing about the embed having drawn
+        // its strip yet, so the placeholder stays until `booted`: the embed
+        // posts this from a script that runs before its application, and
+        // swapping here would trade the themed placeholder for an empty one.
         ready = true;
         if (readyTimer !== undefined) {
           clearTimeout(readyTimer);
           readyTimer = undefined;
         }
-        placeholder.style.display = 'none';
-        iframe.style.height = `${READY_HEIGHT}px`;
+        armRevealTimer();
         postInit();
         break;
       }
+      case 'booted': {
+        revealFrame();
+        break;
+      }
       case 'resize': {
         const h = data['height'];
         if (typeof h === 'number') iframe.style.height = `${clampHeight(h)}px`;
@@ -336,6 +376,13 @@ export function createVersionBarFrame(
         // page gets a fresh verdict, so the failed state resets with it.
         ready = false;
         failed = false;
+        // The placeholder is back up, so the swap the new page's `booted`
+        // asks for is one this bar has not made yet.
+        revealed = false;
+        if (revealTimer !== undefined) {
+          clearTimeout(revealTimer);
+          revealTimer = undefined;
+        }
         deliveredVersion = undefined;
         fallback.hidden = true;
         placeholder.style.display = '';
@@ -369,6 +416,10 @@ export function createVersionBarFrame(
         clearTimeout(readyTimer);
         readyTimer = undefined;
       }
+      if (revealTimer !== undefined) {
+        clearTimeout(revealTimer);
+        revealTimer = undefined;
+      }
       window.removeEventListener('message', onMessage);
       iframe.remove();
       placeholder.remove();

package/src/version.ts

@@ -3,6 +3,6 @@
 // can measure the version distribution of deployed apps and time
 // compatibility windows against it. A unit test pins this to
 // package.json's version; the release bump touches both together.
-export const SDK_VERSION = '0.3.0';
+export const SDK_VERSION = '0.4.0';
 
 export const SDK_CLIENT_ID = `sdk/${SDK_VERSION}`;

package/src/wasm-ready-gate.ts

@@ -0,0 +1,30 @@
+// The once-only gate the browser runtime half readies its WASM behind, kept
+// separate from it so it can be exercised without a real engine: the half
+// itself names a WASM-shipping dependency, which pins it to an environment
+// that can load one.
+
+/**
+ * Build a function that runs `inits` once and hands every caller the same
+ * result.
+ *
+ * A rejection is NOT retained. Each init is a multi-megabyte fetch over
+ * whatever connection the reader has, and a page navigating away mid-download
+ * aborts it, so a retained rejection would answer every later call with a
+ * failure the network has long since recovered from. Dropping it makes the
+ * next call start over, which is what a reader who opens a document a minute
+ * later needs.
+ */
+export function createReadyGate(
+  inits: readonly (() => Promise<unknown>)[],
+): () => Promise<void> {
+  let readying: Promise<void> | null = null;
+  return () => {
+    readying ??= Promise.all(inits.map((init) => init()))
+      .then(() => undefined)
+      .catch((err: unknown) => {
+        readying = null;
+        throw err;
+      });
+    return readying;
+  };
+}

package/src/wasm-runtime.browser.ts

@@ -0,0 +1,48 @@
+// The browser half of the WASM runtime seam: the ONE module in this package
+// that names a WASM-shipping dependency, and the only place a new one is
+// added. Everything else imports `./wasm-runtime.js`, whose node half this
+// one replaces in a browser build, so no other file in the SDK (and no line of
+// an app's own config) names a WASM dep or its loader.
+//
+// Each entry is loaded through its package's WEB build, which readies its
+// module asynchronously behind an explicit init and locates its bytes with
+// `new URL(..., import.meta.url)`. That combination is what makes the whole
+// package build with no bundler plugins: every major bundler rewrites that URL
+// into an emitted asset on its own, and nothing here emits a top-level await,
+// so no build target has to accept one.
+//
+// The alternative each package offers by default is worse in a way nothing
+// reports. A default browser entry fetches its module with a SYNCHRONOUS
+// XMLHttpRequest while it evaluates, so an app freezes its main thread for the
+// whole download before it paints, whether or not anyone opens a document, and
+// the freeze grows with the reader's latency rather than with the app. That is
+// what a browser build resolves to unless something selects otherwise, it
+// builds clean, and the only tell is the chunk count.
+
+// The init comes from the deeper path because the package's web entry
+// re-exports its module with `export *`, which does not carry a default, so
+// the entry's types do not declare the init its JavaScript exports. The two
+// specifiers resolve to the same module instance (the entry imports this
+// file), so readying through one readies the classes taken from the other.
+import initEngine from 'loro-crdt/web/loro_wasm.js';
+
+import { createReadyGate } from './wasm-ready-gate.js';
+
+export * from 'loro-crdt/web';
+
+// Every WASM module this package needs ready before it runs, as the init each
+// one exports. Add an entry rather than replacing the list: a consumer with
+// two installed during a migration window needs both readied, and the gate
+// below is what every caller already awaits, so a new entry costs no new call
+// anywhere.
+const INITS: readonly (() => Promise<unknown>)[] = [initEngine];
+
+/**
+ * Resolve once every WASM module this package needs is ready to run.
+ *
+ * `Brass.init()` starts it and every path that constructs a document awaits
+ * it, so an app that follows the documented boot never calls it. It is
+ * idempotent and concurrent-safe for the paths that construct documents
+ * without one (a test, an in-repo tool).
+ */
+export const ensureWasmReady: () => Promise<void> = createReadyGate(INITS);