@brass-build/client 0.2.0 → 0.3.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,
@@ -309,6 +312,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 +965,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 +979,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 +1149,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 +1167,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 +1217,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 +1229,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 +1256,7 @@ function buildDriveSync(deps: DriveSyncDeps): PieceInternal {
     destroy(): void {
       unsub();
       statusOff?.();
+      publishOff?.();
       clearPublishing();
       menu.destroy();
     },
@@ -1334,8 +1453,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/version-bar.ts

@@ -239,11 +239,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 {
@@ -336,7 +350,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,6 +362,9 @@ 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;

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.3.0';
 
 export const SDK_CLIENT_ID = `sdk/${SDK_VERSION}`;

package/src/when-saved.ts

@@ -0,0 +1,66 @@
+// Waiting out a document's own unsaved ops.
+//
+// `savingCount` counts the ops this client has committed locally and the
+// server has not acked, so a caller that needs the server to hold what the
+// app just wrote waits on it: the import completion, and the checkpoint
+// anchor, both of which describe a state rather than an intention.
+
+import type { Document } from './documents.js';
+
+// How often the wait re-checks. A closing document drops its subscribers
+// without firing them, so this is the only thing that ends the wait for one
+// that goes while writes are draining.
+const SAVED_POLL_MS = 1_000;
+
+// How long the OLDEST outstanding op may go unacked before the wait gives
+// up. An op the server never received is never acked and never re-sent
+// beyond the transport's own attempts, and `savingCount` then stays above
+// zero for the document's life, so a wait with no bound hangs its caller
+// forever. Read off the oldest op rather than off elapsed time, so a bulk
+// write that takes minutes never trips it: there, every op acks promptly
+// and the oldest is always young. Three forced-resend cycles wide (the
+// transport forces one at 60s), so the wait outlasts the recovery it is
+// waiting on.
+const SAVED_STALL_MS = 180_000;
+
+/**
+ * Resolve `true` once the document has no locally-issued op waiting for its
+ * server ack; `false` when the document is no longer live, or the acks
+ * stopped arriving.
+ *
+ * `false` does not say the writes were lost, only that this wait cannot say
+ * they landed. A caller about to record something permanent against them (an
+ * import completion, a checkpoint anchor) has to stop on it.
+ *
+ * @internal
+ */
+export function whenSaved(doc: Document): Promise<boolean> {
+  if (doc.savingCount === 0) return Promise.resolve(true);
+  return new Promise<boolean>((resolve) => {
+    let off: (() => void) | undefined;
+    let poll: ReturnType<typeof setInterval> | undefined;
+    const settle = (saved: boolean): void => {
+      off?.();
+      if (poll !== undefined) clearInterval(poll);
+      resolve(saved);
+    };
+    try {
+      off = doc.subscribe(() => {
+        if (doc.savingCount === 0) settle(true);
+      });
+    } catch {
+      // The document closed, so nothing more is going to be acked.
+      resolve(false);
+      return;
+    }
+    poll = setInterval(() => {
+      if (doc.savingCount === 0) return settle(true);
+      if (!doc._isLive) return settle(false);
+      if (doc.diagnostics().oldestUnackedMs >= SAVED_STALL_MS) settle(false);
+    }, SAVED_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(true);
+  });
+}

package/src/ws-client.ts

@@ -17,7 +17,11 @@
 // 10-minute idle timeout (only client-originated frames do), and it is the
 // presence liveness signal (the server refreshes `last_seen` on each ping;
 // the staleness threshold is 3 missed heartbeats). The server replies
-// `pong`. A topic-less `{ type: 'error', reason: 'bad_message' }` is the
+// `pong`. The same interval notices a socket that has stopped carrying
+// anything at all (`SOCKET_SILENCE_LIMIT_MS`), since on an idle connection
+// it is the only thing running; such a socket is retired here so the
+// reconnect loop can replace it, because a dead path does not reliably close
+// itself. A topic-less `{ type: 'error', reason: 'bad_message' }` is the
 // server's catch-all rejection, so it is swallowed rather than surfaced (a
 // deploy without the `ping` handler answers a heartbeat with it) but never
 // counted as the connection working. Both are dropped.
@@ -103,6 +107,29 @@ const HEARTBEAT_INTERVAL_MS = 60_000;
 // rather than wrong: it parks, and returning to it clears the count. A
 // hidden page doing WORK is unaffected, because its ops draw `op_ack`.
 const HEARTBEAT_FIRST_MS = 10_000;
+// How long a socket may carry nothing at all before this client treats it as
+// gone. A dead path does not always close: when a phone changes network
+// neither end sends a FIN, so a socket that will never carry another byte
+// still reads as OPEN, and nothing downstream notices, because the reconnect
+// loop is driven by `close` and an op's resend goes out on the same socket.
+// ANY inbound frame answers this, not just the `pong` the reconnect count
+// credits: the question is whether the path still carries bytes. Two missed
+// replies plus slack, so one dropped `pong` is not enough.
+const SOCKET_SILENCE_LIMIT_MS = 150_000;
+// Spread added to that limit, because the condition is SHARED: the server
+// answers a `ping` after an awaited presence refresh and reap sweep, so its
+// replies slow under exactly the load that makes sockets fragile, and every
+// client goes silent at once. An unjittered threshold turns one degradation
+// into a synchronized wave of reconnects landing on a service already
+// shedding.
+//
+// Drawn PER SOCKET, not once per client. Clients that retire together
+// reconnect together, so their next silence window is tighter than the last;
+// a fixed per-client offset keeps its phase inside that convergence, where a
+// fresh draw on every open scatters the schedule the wave just aligned. Two
+// heartbeat intervals wide, since the check rides the 60s tick and a spread
+// under one tick is quantized away.
+const SOCKET_SILENCE_JITTER_MS = 120_000;
 // Cap on the frames held for one topic's unacked subscribe, matching the
 // `outboundQueue` bound. A disconnect rolls every wanted topic back to
 // `subscribing`, so both queues hold the same kind of mid-reconnect frame
@@ -218,6 +245,14 @@ export class BrassWsClient {
   // so a second outage after a recovery would go unreported for the life of
   // the process.
   private creditsThisSocket = 0;
+  // When this socket last carried anything inbound, set on open so a socket
+  // that never speaks is measured from the moment it opened. Zero while no
+  // socket is up, which stops a silence check firing against a connection
+  // that does not exist.
+  private lastInboundAt = 0;
+  // This socket's silence threshold, redrawn on every open. Held as state so
+  // one socket cannot move its own deadline every time the check looks at it.
+  private silenceLimitMs = SOCKET_SILENCE_LIMIT_MS;
   private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
   // Sockets this client has opened. Every topic and every open document
   // rides this one socket, so the count is a fact about the client rather
@@ -617,6 +652,9 @@ export class BrassWsClient {
     this.connecting = false;
     this.socketsOpened += 1;
     this.creditsThisSocket = 0;
+    this.lastInboundAt = Date.now();
+    this.silenceLimitMs =
+      SOCKET_SILENCE_LIMIT_MS + Math.random() * SOCKET_SILENCE_JITTER_MS;
     // `socket_open` per topic: re-subscribes every wanted topic (in
     // subscription order) with a fresh retry grant, and prunes `tornDown`
     // leftovers. Runs before the outbound drain so the server sees the
@@ -649,6 +687,9 @@ export class BrassWsClient {
   }
 
   private onMessage(ev: MessageEvent): void {
+    // Stamped before the parse: garbage the server sent is still the server
+    // reaching us, and the path carrying bytes is the whole question.
+    this.lastInboundAt = Date.now();
     let frame: unknown;
     try {
       frame = JSON.parse(typeof ev.data === 'string' ? ev.data : String(ev.data));
@@ -757,6 +798,7 @@ export class BrassWsClient {
   private onClose(): void {
     this.stopHeartbeat();
     this.ws = null;
+    this.lastInboundAt = 0;
     // Held frames are tied to the connection's unacked subscribes;
     // `socket_closed` drops them and preserves wantedness for the replay.
     for (const topic of this.topics.keys()) {
@@ -917,6 +959,12 @@ export class BrassWsClient {
     // from the cadence without a second timer to keep in step.
     const arm = (delay: number): void => {
       this.heartbeatTimer = setTimeout(() => {
+        // The one thing running on an idle connection, so it is also what
+        // notices the socket stopped carrying anything.
+        if (this.socketHasGoneSilent()) {
+          this.dropSilentSocket();
+          return;
+        }
         this.sendIfOpen({ type: 'ping' });
         arm(HEARTBEAT_INTERVAL_MS);
       }, delay);
@@ -924,6 +972,27 @@ export class BrassWsClient {
     arm(HEARTBEAT_FIRST_MS);
   }
 
+  private socketHasGoneSilent(): boolean {
+    if (!this.ws || this.lastInboundAt === 0) return false;
+    return Date.now() - this.lastInboundAt >= this.silenceLimitMs;
+  }
+
+  // Retire a socket the server has stopped answering on. `onClose` runs
+  // directly rather than being waited for: closing a dead path has nothing to
+  // complete the handshake with, so the socket can sit in CLOSING and never
+  // fire `close`, which is the state this exists to escape. Running the
+  // teardown first also lets the identity guard drop a late `close`, so the
+  // reconnect is scheduled once.
+  private dropSilentSocket(): void {
+    const dead = this.ws;
+    this.onClose();
+    try {
+      dead?.close();
+    } catch {
+      // Closing an already-dead socket is fine; the teardown already ran.
+    }
+  }
+
   private stopHeartbeat(): void {
     if (this.heartbeatTimer) {
       clearTimeout(this.heartbeatTimer);

package/src/ws-frame-limit.ts

@@ -1,18 +1,17 @@
 // The ceilings an op can hit, measured before it is sent.
-//
-// Duplicated from the server's `frameExceedsWsLimit` / `op-blob.ts`
-// rather than imported: this package ships unbundled and can only import
-// its own relative files. The server owns the contract; these follow it.
 
-// A frame over this closes the connection, taking every other op and
-// presence down with it, and the reconnect re-sends the oversized frame, so
-// the document never saves anything. The transport also caps a message at
-// 128 KiB, but the frame binds first in a browser: it negotiates
+// The client's own SEND bound, deliberately smaller than the platform's
+// 128 KiB server-push bound: the two are different limits, not one shared
+// constant. A frame over this closes the connection, taking every other op
+// and presence down with it, and the reconnect re-sends the oversized
+// frame, so the document never saves anything. The transport also caps a
+// message at 128 KiB, but the frame binds first in a browser: it negotiates
 // `permessage-deflate` and Chromium sends a message as one frame, so what
 // gets through depends on how the op compresses (43,264 bytes for
 // incompressible base64, measured). Staying at the frame limit is what makes
 // the bound independent of the content.
-const WS_FRAME_MAX_BYTES = 32 * 1024;
+/** @internal Exported so a test can pin it against the server's bound. */
+export const WS_SEND_FRAME_MAX_BYTES = 32 * 1024;
 
 // Past this the blob is uploaded to storage and the write names the staged
 // object instead of carrying it. Set by what a request body delivers
@@ -43,7 +42,7 @@ export interface OpFrame {
  */
 export function opFrameExceedsWsLimit(frame: OpFrame): boolean {
   const envelopeChars = JSON.stringify({ ...frame, op_blob: '' }).length;
-  return envelopeChars + frame.op_blob.length > WS_FRAME_MAX_BYTES;
+  return envelopeChars + frame.op_blob.length > WS_SEND_FRAME_MAX_BYTES;
 }
 
 /** True when the blob is too large to ride in a request body, so it is