@brass-build/client 0.2.0 → 0.4.0

package/src/session-toolbar.ts

@@ -19,7 +19,10 @@ import type { BrassUser } from './types.js';
 import type { Command, Document as BrassDocument } from './documents.js';
 import type { DocumentSession } from './session.js';
 import type { PresenceParticipant } from './presence.js';
-import type { DocumentDriveStatus } from './document-signals.js';
+import type {
+  DocumentDriveStatus,
+  DrivePublishTarget,
+} from './document-signals.js';
 import {
   createVersionBarFrame,
   type VersionBarDeps,
@@ -70,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 &
@@ -197,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
@@ -264,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); }
@@ -309,6 +327,10 @@ const CSS = `
 .b-drive-source { font-size:12px; color:var(--brass-accent); text-decoration:none; white-space:nowrap; }
 .b-drive-source:hover { text-decoration:underline; }
 .b-drive-detail { margin:0; padding:0 10px 6px; font-size:12px; color:var(--brass-fg-muted); }
+/* The drive rejecting a published file is the one line in this panel that
+   reports a problem, so it carries the danger tone rather than the muted one
+   every other line uses. */
+.b-drive-unreadable { margin:0; padding:0 10px 6px; font-size:12px; color:var(--brass-danger, #b3261e); }
 /* Historical-version preview bar: a full-width strip the toolbar shows below
    the bar whenever the active doc is previewing an earlier version. The strip
    itself is the platform-served version-bar iframe (the SDK owns only this
@@ -958,6 +980,7 @@ function buildDriveSync(deps: DriveSyncDeps): PieceInternal {
   // document that was closed.
   let boundDoc: DocumentSession['document'] = null;
   let statusOff: (() => void) | null = null;
+  let publishOff: (() => void) | null = null;
 
   // A publish runs on a server worker and reaches `synced` only after the
   // worker (and, on a file-roundtrip, the drive's importer) confirms. In that
@@ -971,24 +994,111 @@ function buildDriveSync(deps: DriveSyncDeps): PieceInternal {
   let publishing = false;
   let publishError = false;
   let publishTimer: ReturnType<typeof setTimeout> | null = null;
+  // Set on a click, cleared by the next publish-state frame. Between the two,
+  // the held state describes the PREVIOUS attempt, and rendering it would
+  // report the last failure over the publish just started.
+  let publishStateStale = false;
   let currentStatus: DocumentDriveStatus | null = null;
   const clearPublishing = (): void => {
     publishing = false;
+    // The stale mark is cleared with the hold it belongs to. It is otherwise
+    // cleared only by a publish-state frame, so a publish that draws none
+    // would leave the panel reading the target's resting sentence for the
+    // life of the document.
+    publishStateStale = false;
     if (publishTimer !== null) {
       clearTimeout(publishTimer);
       publishTimer = null;
     }
   };
 
+  // The panel for a document with no source item: the server's sentence about
+  // where the file lands, and the publish that puts it there. The first
+  // publish creates the artifact and makes the document its mirror, at which
+  // point the drive status arrives and the mirror panel above replaces this
+  // one.
+  const renderPublishOffer = (target: DrivePublishTarget): void => {
+    root.hidden = false;
+    // A document the drive has never received is as far out of sync as one
+    // whose edits have not been published, so the icon carries the same
+    // attention an `ahead` document's does. What separates them is what the
+    // panel offers, not how much the reader is told to look.
+    root.classList.add('has-changes');
+    root.classList.remove('is-broken');
+    const state = publishStateStale ? null : (boundDoc?._publishState ?? null);
+    const inFlight =
+      publishing || state?.publishing === true || target.publishing;
+    button.title = inFlight
+      ? 'Publishing...'
+      : state?.failed
+        ? `Publish to ${target.driveName} failed`
+        : `Publish to ${target.driveName}`;
+
+    const failed =
+      !inFlight && (state?.failed === true || target.publishFailed === true);
+
+    const rows: HTMLElement[] = [];
+    // One line, server-authored either way: the worker's phase copy while it
+    // runs, its account of the failure when it stopped, and the resting
+    // sentence otherwise. Marked as a problem when it is one, since nothing
+    // else in this panel distinguishes a document whose publish failed from
+    // one that has simply never published.
+    const p = el('p', failed ? 'b-drive-unreadable' : 'b-drive-detail');
+    p.textContent = inFlight
+      ? (state?.publishing === true ? (state.detail ?? 'Publishing...') : 'Publishing...')
+      : (state?.detail ?? target.detail);
+    rows.push(p);
+
+    const pub = el('button');
+    pub.type = 'button';
+    pub.disabled = inFlight;
+    pub.textContent = inFlight
+      ? 'Publishing...'
+      : publishError || failed
+        ? `Publish to ${target.driveName}, retry`
+        : `Publish to ${target.driveName}`;
+    pub.onclick = () => {
+      const doc = deps.session.document;
+      if (!doc) return;
+      publishError = false;
+      publishing = true;
+      publishStateStale = true;
+      // The same safety net the mirror panel keeps: a publish that neither
+      // errors nor lands leaves the panel offering the action again rather
+      // than held forever.
+      publishTimer = setTimeout(() => {
+        clearPublishing();
+        render(currentStatus);
+      }, PUBLISH_HOLD_MS);
+      render(currentStatus);
+      void doc.pushToDrive().catch(() => {
+        clearPublishing();
+        publishError = true;
+        render(currentStatus);
+      });
+    };
+    rows.push(pub);
+    pop.replaceChildren(...rows);
+  };
+
   const render = (status: DocumentDriveStatus | null): void => {
     currentStatus = status;
-    // Hidden only when the doc is not drive-linked.
+    // A document that mirrors nothing can still have somewhere to go: its
+    // project may be linked to a drive that takes it as a new file, which is
+    // what an upload into a linked project sits waiting for. Offer that
+    // publish here, so an app gets it by mounting this piece rather than by
+    // building a surface of its own.
     if (status === null) {
-      root.hidden = true;
-      menu.close();
-      clearPublishing();
-      root.classList.remove('has-changes', 'is-broken');
-      pop.replaceChildren();
+      const target = boundDoc?._publishTarget ?? null;
+      if (target === null) {
+        root.hidden = true;
+        menu.close();
+        clearPublishing();
+        root.classList.remove('has-changes', 'is-broken');
+        pop.replaceChildren();
+        return;
+      }
+      renderPublishOffer(target);
       return;
     }
     // The publish settles once the doc actually reaches synced; drop the
@@ -1054,6 +1164,15 @@ function buildDriveSync(deps: DriveSyncDeps): PieceInternal {
       rows.push(p);
     }
 
+    // The drive could not read what the last publish delivered. Shown in the
+    // drive's own words, above the commands: the publish succeeded, so
+    // nothing else in this panel says anything is wrong.
+    if (status.sourceUnreadable) {
+      const warn = el('p', 'b-drive-unreadable');
+      warn.textContent = status.sourceUnreadable;
+      rows.push(warn);
+    }
+
     if (isPublishing) {
       // Held while the publish is in flight (a local click hold, or the doc's
       // pending work-status), until it reaches synced (see `isPublishing`).
@@ -1063,8 +1182,9 @@ function buildDriveSync(deps: DriveSyncDeps): PieceInternal {
       pub.disabled = true;
       rows.push(pub);
     } else if (status.canPush) {
-      // `canPush` already encodes two-way + not broken + local edits, so this
-      // never offers a no-op publish.
+      // `canPush` already encodes two-way + not broken + local edits + a
+      // server-writable format, so this never offers a publish the server
+      // would refuse.
       const pub = el('button');
       pub.type = 'button';
       pub.textContent = publishError ? 'Publish failed, retry' : 'Publish changes';
@@ -1112,6 +1232,8 @@ function buildDriveSync(deps: DriveSyncDeps): PieceInternal {
   function bind(): void {
     statusOff?.();
     statusOff = null;
+    publishOff?.();
+    publishOff = null;
     const doc = deps.session.document;
     if (!doc) {
       render(null);
@@ -1122,6 +1244,17 @@ function buildDriveSync(deps: DriveSyncDeps): PieceInternal {
     // started from any surface (the dashboard card, the app) flips it and the
     // indicator holds "Publishing..." without a local click.
     statusOff = doc.onDriveStatus(render);
+    // The same signal for a document that mirrors nothing yet, which has no
+    // drive status to carry it: its first publish is the one that creates the
+    // artifact, and this is how its progress and its failure arrive.
+    publishOff = doc._onPublishState(() => {
+      publishStateStale = false;
+      // A publish the server has finished with ends the local click hold:
+      // holding "Publishing..." for the rest of it would report a push that
+      // is over as one still running.
+      if (!doc._publishState.publishing) clearPublishing();
+      render(currentStatus);
+    });
   }
 
   const onSession = (): void => {
@@ -1138,6 +1271,7 @@ function buildDriveSync(deps: DriveSyncDeps): PieceInternal {
     destroy(): void {
       unsub();
       statusOff?.();
+      publishOff?.();
       clearPublishing();
       menu.destroy();
     },
@@ -1153,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(
@@ -1182,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'),
@@ -1204,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 ?? '';
@@ -1227,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();
     },
   };
@@ -1334,8 +1521,18 @@ function buildVersionPreview(deps: VersionPreviewDeps): PieceInternal {
       // left it checked out would leave an app read-only with nothing to
       // clear it. A document pinned to its version has no head to return to
       // and keeps showing it; `dismissedAt` is what keeps the bar dismissed.
+      // Once the return lands, the dismissal has nothing left to hold
+      // against: the doc is live, and a LATER pick of the same version in
+      // the history dialog is a fresh preview that must latch the bar (its
+      // pick sets only `version`, so a stale `dismissedAt` equal to it would
+      // otherwise leave the reader checked out, read-only, with no bar and
+      // no exit).
       if (doc && doc.version !== null) {
-        void attempt(doc, () => doc.returnToHead()).catch(() => {});
+        void attempt(doc, () => doc.returnToHead())
+          .then(() => {
+            if (session.document === doc) dismissedAt = undefined;
+          })
+          .catch(() => {});
       }
       hideBar();
     },

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(() => {
@@ -239,11 +272,25 @@ export function createVersionBarFrame(
     );
   }
 
+  // Intents still awaiting their answer. While one is in flight, `update()`
+  // stays quiet: the checkout it runs fires the host's subscribers before its
+  // promise resolves, so a render lands here ahead of `confirmIntent`, and an
+  // uncorrelated `version-changed` posted then reaches the embed as a phantom
+  // external move one message before the answer to its own step. The answer
+  // reads the live version at settle time, so nothing the quiet window saw is
+  // lost.
+  let intentsInFlight = 0;
+
   function runIntent(requestId: unknown, intent: () => Promise<void>): void {
-    void intent().then(
-      () => confirmIntent(requestId, true),
-      () => confirmIntent(requestId, false),
-    );
+    intentsInFlight += 1;
+    const settle = (ok: boolean) => (): void => {
+      // Decremented in every outcome. A count this leaves above zero silences
+      // `update()` for the life of the bar, so an external version change
+      // would never reach the embed again.
+      intentsInFlight -= 1;
+      confirmIntent(requestId, ok);
+    };
+    void intent().then(settle(true), settle(false));
   }
 
   function onMessage(event: MessageEvent): void {
@@ -253,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`;
@@ -322,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 = '';
@@ -336,7 +397,9 @@ export function createVersionBarFrame(
       }
       // Only an actual version change reaches the embed (dedup), so a
       // re-render that didn't move the version can't clobber the bar's state.
-      if (ready && next.version !== deliveredVersion) {
+      // A change while an intent is in flight is that intent's own doing and
+      // is delivered by its answer instead.
+      if (ready && intentsInFlight === 0 && next.version !== deliveredVersion) {
         deliveredVersion = next.version;
         iframe.contentWindow?.postMessage(
           { [EMBED_ENVELOPE]: EMBED_PROTOCOL_VERSION, type: 'version-changed', version: next.version },
@@ -346,10 +409,17 @@ export function createVersionBarFrame(
     },
     destroy(): void {
       destroyed = true;
+      // A bar torn down mid-intent leaves the count standing; a rebuilt bar
+      // gets a fresh closure, but this keeps the teardown total.
+      intentsInFlight = 0;
       if (readyTimer !== undefined) {
         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.2.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;
+  };
+}