@brass-build/client 0.1.0 → 0.2.0

package/src/hosted-runtime.ts

@@ -1,32 +1,28 @@
 // Runtime config resolution for Brass-hosted bundles.
 //
-// A bundle served by app hosting (`https://{slug}.onbrass.app` and non-prod
-// equivalents under `.onbrass.app`) gets its identity and environment from
-// the serving slot, not from code: the api writes
-// `/.well-known/brass-runtime.json` into the served prefix (see CONTRACT.md
-// "App hosting"), and `Brass.init()` reads it back same-origin and adopts
+// A bundle served by app hosting gets its identity and environment from the
+// serving slot, not from code: the platform stamps a runtime descriptor into
+// the served prefix, and `Brass.init()` reads it back same-origin and adopts
 // it wholesale. It is authoritative on a hosted origin, so the same artifact
 // picks up each environment's config from whichever origin serves it and a
 // bundle that hardcodes one environment can't carry it onto another's slot.
 // `isBrassHostedHost` recognizes the default `*.onbrass.app` slots by
 // hostname; a custom serving domain (a vanity URL) is not recognizable that
 // way, so the SDK also reads the descriptor whenever a bundle relies on the
-// slot for its environment (no `env` / `*BaseUrl` passed to `Brass.init`),
-// on any host. A present descriptor is authoritative and overrides even a
+// slot for its environment (no `*BaseUrl` passed to `Brass.init`), on any
+// host. A present descriptor is authoritative and overrides even a
 // baked app id. A developer on their own hosting passes explicit origins and
 // never triggers the fetch.
 
 export const HOSTED_RUNTIME_PATH = '/.well-known/brass-runtime.json';
 
 // The window global a Brass serving slot stamps into the served `index.html`
-// (an inline script the unpack worker injects). This is the primary,
+// as an inline script. This is the primary,
 // fetch-free path: the HOST decides whether a bundle is on a Brass slot by
 // whether the served page carries this global, so the SDK never guesses from
 // the hostname (a custom serving domain is indistinguishable from
-// self-hosting by name) nor makes a request that 404s off a slot. Must match
-// `HOSTED_RUNTIME_GLOBAL` in infra/lambda/lib/hosting-runtime.ts (the
-// published package cannot import the workspace module, so the name is
-// duplicated by necessity).
+// self-hosting by name) nor makes a request that 404s off a slot. The name is
+// part of the serving contract, so it is fixed rather than configurable.
 const HOSTED_RUNTIME_GLOBAL = '__brassRuntime';
 
 // The apex app hosting serves bundles under. Every hosting origin is some

package/src/hosted-ui.ts

@@ -27,12 +27,8 @@
 // page learns the host origin from `init` and targets outbound at it (never
 // `*`).
 
-// Both sides ignore any `message` whose `data[ENVELOPE]` is not this exact
-// value, so unrelated postMessage traffic never reaches the handshake.
 import { BrassError } from './errors.js';
-
-const ENVELOPE = '__brass_embed';
-const PROTOCOL_VERSION = 1;
+import { EMBED_ENVELOPE, EMBED_PROTOCOL_VERSION } from './embed-protocol.js';
 
 // No `ready` within this window means the iframe is unusable (CSP, origin
 // unreachable, bridge threw). What the window is worth is set by what the
@@ -267,14 +263,6 @@ export interface HostedUiLauncherOptions {
   // state instead of parking the remote-eviction error surface. Signalled
   // pre-flight, so the note beats the server's `doc_gone` frame.
   onLocalDelete?: (docId: string, active: boolean) => void;
-  // The SDK's fallback platform-session pointer (`sid`), non-null only when
-  // this browser blocked the cross-site `brass_auth` cookie and the SDK is
-  // running in code / session-token mode. Read at dialog-open time and posted
-  // in the bridge `init` (to the pinned dashboard origin only) so the embed
-  // page can refresh the dashboard's own tokens when its framed cookie is
-  // likewise blocked. Null in a normal browser, where the embed's cookie
-  // carries its session and no hand-off is needed.
-  getSessionToken?: () => string | null;
   // The `sub` of the user this app is currently acting as, read at
   // dialog-open time and posted in the bridge `init`. The embed page
   // authenticates from the dashboard origin's own platform-session cookie,
@@ -314,11 +302,6 @@ function redirectToStandalone(
 ): void {
   const url = new URL(`${baseUrl}/embed/${surface}`);
   for (const [key, value] of Object.entries(params)) {
-    // `sessionToken` is an in-iframe-only credential hand-off (posted over the
-    // bridge to the pinned dashboard origin); never let it reach a URL. On the
-    // redirect fallback the standalone page is top-level and first-party, so
-    // its own cookie carries the session and no hand-off is needed.
-    if (key === 'sessionToken') continue;
     if (value !== undefined && value !== null) {
       url.searchParams.set(key, String(value));
     }
@@ -666,13 +649,13 @@ function openEmbed(
       if (event.origin !== dashboardOrigin) return;
       if (event.source !== iframe.contentWindow) return;
       const data = event.data as Record<string, unknown> | null;
-      if (!data || data[ENVELOPE] !== PROTOCOL_VERSION) return;
+      if (!data || data[EMBED_ENVELOPE] !== EMBED_PROTOCOL_VERSION) return;
 
       switch (data['type']) {
         case 'ready': {
           if (readyTimer !== undefined) clearTimeout(readyTimer);
           iframe.contentWindow?.postMessage(
-            { [ENVELOPE]: PROTOCOL_VERSION, type: 'init', surface, params },
+            { [EMBED_ENVELOPE]: EMBED_PROTOCOL_VERSION, type: 'init', surface, params },
             dashboardOrigin,
           );
           // Embed page mounted; fade the loader out (delayed removal so the
@@ -710,7 +693,7 @@ function openEmbed(
           const docId = typeof params['docId'] === 'string' ? params['docId'] : '';
           const reply = (outcome: ExportSerializeOutcome): void => {
             iframe.contentWindow?.postMessage(
-              { [ENVELOPE]: PROTOCOL_VERSION, type: 'export-result', requestId, ...outcome },
+              { [EMBED_ENVELOPE]: EMBED_PROTOCOL_VERSION, type: 'export-result', requestId, ...outcome },
               dashboardOrigin,
             );
           };
@@ -833,6 +816,23 @@ function openEmbed(
   });
 }
 
+// Warm the connection to the origin the embed pages come from. An app talks to
+// the api and auth origins, never this one, so the first hosted surface a
+// reader opens otherwise pays DNS, TCP and TLS before the iframe's document
+// request can even start. Idempotent, since an app may build more than one
+// launcher.
+function preconnectToDashboard(origin: string): void {
+  if (typeof document === 'undefined') return;
+  const links = document.head.querySelectorAll('link[rel="preconnect"]');
+  for (const link of links) {
+    if (link.getAttribute('href') === origin) return;
+  }
+  const link = document.createElement('link');
+  link.rel = 'preconnect';
+  link.href = origin;
+  document.head.appendChild(link);
+}
+
 export function createHostedUiLauncher(
   opts: HostedUiLauncherOptions,
 ): HostedUiLauncher {
@@ -840,6 +840,7 @@ export function createHostedUiLauncher(
   // Parsed once for the postMessage origin checks; a malformed
   // `dashboardBaseUrl` throws here, at construction, not mid-handshake.
   const dashboardOrigin = new URL(baseUrl).origin;
+  preconnectToDashboard(dashboardOrigin);
   // Watch for activations from here on, so a surface opened later knows which
   // control the reader pressed to get there.
   trackHostedUiActivations();
@@ -847,21 +848,16 @@ export function createHostedUiLauncher(
   // would put a dark embed inside a light host on a dark-OS user.
   const theme: HostedUiTheme = opts.theme ?? 'light';
 
-  // Merge the SDK's fallback session pointer into a surface's bridge params
-  // when this browser blocked the cross-site cookie (so the embed page can
-  // refresh the dashboard's tokens without its own framed cookie). Read at
-  // open time, not launcher-construction time, since the sid is populated by
-  // the first fallback refresh, which may land after the launcher is built.
-  // Every embed surface authenticates the same way, so this is cross-cutting
-  // rather than per-surface like `appId`.
-  const withSession = (
+  // Name the user this app is acting as in every surface's bridge params.
+  // Read at open time, not launcher-construction time, since the app may
+  // authenticate after the launcher is built. Every embed surface checks the
+  // same way, so this is cross-cutting rather than per-surface like `appId`.
+  const withActingSub = (
     params: Record<string, unknown>,
   ): Record<string, unknown> => {
-    const sid = opts.getSessionToken?.();
     const actingSub = opts.getActingSub?.();
     return {
       ...params,
-      ...(sid ? { sessionToken: sid } : {}),
       ...(actingSub ? { actingSub } : {}),
     };
   };
@@ -880,7 +876,7 @@ export function createHostedUiLauncher(
       baseUrl,
       dashboardOrigin,
       surface,
-      withSession(params),
+      withActingSub(params),
       unavailable,
       theme,
       exportDoc ? opts.serializeForExport : undefined,

package/src/importer.ts

@@ -38,6 +38,35 @@ export interface ImportRunner {
   attempt(doc: Document): Promise<void>;
 }
 
+// The claim holder can close its tab mid-import and let its claim expire, so
+// a client that lost the race asks again instead of spending this document's
+// one attempt on it.
+//
+// A holder EXTENDS its claim while it runs (`startClaimRefresh`), so the
+// expiry a loser is waiting out is not the platform's base TTL but
+// `last-refresh + TTL`, up to `CLAIM_REFRESH_MAX` refreshes away. A schedule
+// sized against the base TTL therefore gives up while the claim is still
+// live, and what it leaves behind is a reader sitting on an empty document
+// with no further attempt coming and nothing said. So the tail keeps asking,
+// at an interval, for longer than a holder can hold.
+const PENDING_RETRY_DELAYS_MS = [15_000, 45_000, 135_000];
+const PENDING_RETRY_INTERVAL_MS = 120_000;
+// Enough tail attempts to outlast a holder refreshing to its own bound, and
+// far inside the per-caller claim budget.
+const PENDING_RETRY_TAIL = 18;
+
+// A claim expires while a long import is still parsing or still waiting for
+// its writes to be acked, and the completion needs it, so the runner
+// re-claims on this interval while its own import runs. Bounded so a
+// document whose writes never drain stops re-claiming.
+const CLAIM_REFRESH_MS = 60_000;
+const CLAIM_REFRESH_MAX = 30;
+
+// The status the platform refuses an import the app cannot run with: its
+// `imports` do not claim the file, it declares no schema, or the document
+// holds a half-written import.
+const CLAIM_REFUSED_STATUS = 422;
+
 // Runs the import protocol for one opened document: claim, and on the
 // win fetch + parse + complete. Separated from the client so the
 // protocol is testable against mocked HTTP deps.
@@ -46,12 +75,63 @@ export function createImportRunner(deps: ImportRunnerDeps): ImportRunner {
   // 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>();
-  return {
+  // 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
+  // a second `attempt` call replaces the listener instead of stacking one.
+  //
+  // Replacing rather than returning early is what survives a park. An app's
+  // `close()` parks the Document, which drops every status listener, and the
+  // park cache hands the SAME instance back on reopen; a mark alone would
+  // still say "someone is watching this" when nothing is, and the reopened
+  // document would never attempt its import again for the life of the page.
+  const waiting = new WeakMap<Document, () => void>();
+  // Retries already scheduled against another client's live claim.
+  const pendingRetries = new WeakMap<Document, number>();
+  const runner: ImportRunner = {
     setImporter(fn: DocumentImporter): void {
       importer = fn;
     },
     async attempt(doc: Document): Promise<void> {
       if (importer === null || doc.id === null || attempted.has(doc)) 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
+      // claim taken for one is a claim nothing will ever complete: every other
+      // open client is refused until the platform's claim expires. The retry
+      // timer below and the resumed-open path both reach here with a document
+      // that may have gone since, so the gate belongs at the entry rather than
+      // at each caller.
+      if (!doc._isLive) return;
+      // A document with server-side work in flight has no source file to
+      // read yet. A drive-linked file is fetched from the drive and stored
+      // by a worker AFTER the open returns, so claiming now asks to import
+      // bytes that have not arrived: the platform refuses, and this
+      // document's one attempt is spent on a document that was never
+      // eligible. Wait for the work the server reports, then attempt.
+      if (doc.status?.pending === true) {
+        // Any listener from an earlier attempt goes first, so the document is
+        // watched exactly once whether or not the previous one survived.
+        waiting.get(doc)?.();
+        waiting.delete(doc);
+        try {
+          const off = doc.onStatus((status) => {
+            if (status.pending) return;
+            waiting.get(doc)?.();
+            waiting.delete(doc);
+            void runner.attempt(doc);
+          });
+          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.
+        }
+        return;
+      }
+      // The work finished, so nothing is left to wait for; drop the listener
+      // rather than leave it to fire against a document already past it.
+      waiting.get(doc)?.();
+      waiting.delete(doc);
       attempted.add(doc);
       const run = importer;
       const docId = doc.id;
@@ -59,10 +139,19 @@ export function createImportRunner(deps: ImportRunnerDeps): ImportRunner {
       try {
         claim = await deps.claimImport(docId);
       } catch (err) {
-        // The common no-op outcomes arrive as 4xx: not a stored source
-        // file, read-only access, another client's claim in flight. Only
-        // a server fault surfaces.
-        if (err instanceof BrassError && err.status !== undefined && err.status < 500) {
+        const status = err instanceof BrassError ? err.status : undefined;
+        if (status === 409) {
+          schedulePendingRetry(doc);
+          return;
+        }
+        // A refusal names what the developer has to change, so it reaches
+        // the app's error handler; the rest of the 4xx surface (nothing
+        // stored to import, read-only access) is a no-op.
+        if (
+          status !== undefined &&
+          status < 500 &&
+          status !== CLAIM_REFUSED_STATUS
+        ) {
           return;
         }
         deps.reportError(asError(err));
@@ -71,19 +160,183 @@ export function createImportRunner(deps: ImportRunnerDeps): ImportRunner {
       if (claim.claimed !== true) return;
       // This client won the claim: run the importer, then report
       // completion so the platform stamps the document with the app's
-      // schema. A throw leaves the claim to expire, so another client
-      // can retry rather than the document staying half-claimed.
+      // schema. A throw skips the completion and leaves the claim to
+      // expire; the platform decides what a later claim may do with a
+      // document the failed run already wrote records into.
       try {
         const source = await doc.sourceBlob();
-        await run(source, doc);
+        const stopRefresh = startClaimRefresh(docId, doc);
+        // Whether the importer put anything on the wire. A commit fires the
+        // document's subscribers synchronously and raises `savingCount` as it
+        // does, so a run that wrote is seen here even when its ops ack before
+        // it returns.
+        let wroteRecords = false;
+        const stopWatchingWrites = doc.subscribe(() => {
+          if (doc.savingCount > 0) wroteRecords = true;
+        });
+        try {
+          await run(source, doc);
+          // The importer's ops are still in flight when it returns, and
+          // the completion stamps the version the import produced from
+          // 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);
+        } 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;
+        // 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
+        // document that holds none. `try { parse() } catch { return }` is an
+        // ordinary shape, so this is reachable from app code that looks
+        // correct. Both signals are required before skipping, so an import
+        // that DID write is completed either way and never runs twice.
+        if (!wroteRecords && isEmptyDocument(doc)) {
+          deps.reportError(
+            new Error(
+              'The importer wrote no records, so this file was not imported. ' +
+                'Reload to try again.',
+            ),
+          );
+          return;
+        }
         await deps.completeImport(docId);
       } catch (err) {
         deps.reportError(asError(err));
       }
     },
   };
+
+  function schedulePendingRetry(doc: Document): void {
+    const taken = pendingRetries.get(doc) ?? 0;
+    const delay =
+      PENDING_RETRY_DELAYS_MS[taken] ??
+      (taken < PENDING_RETRY_DELAYS_MS.length + PENDING_RETRY_TAIL
+        ? PENDING_RETRY_INTERVAL_MS
+        : undefined);
+    if (delay === undefined) {
+      // Out of attempts with the file still unimported. The reader is looking
+      // at an empty document, so say so rather than leaving them to conclude
+      // the file was empty.
+      deps.reportError(
+        new Error(
+          'Could not import this file: another window has been importing it ' +
+            'for longer than expected. Reload to try again.',
+        ),
+      );
+      return;
+    }
+    pendingRetries.set(doc, taken + 1);
+    attempted.delete(doc);
+    setTimeout(() => {
+      void runner.attempt(doc);
+    }, delay);
+  }
+
+  function startClaimRefresh(docId: string, doc: Document): () => void {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    let left = CLAIM_REFRESH_MAX;
+    const tick = (): void => {
+      if (left <= 0) return;
+      // A renewal from a document that has gone tells the platform the holder
+      // is still working, when this client can no longer complete the import
+      // at all. Stopping here is what lets the claim expire on its own TTL so
+      // a client that IS open picks the file up, rather than being refused for
+      // the whole refresh budget.
+      if (!doc._isLive) return;
+      left -= 1;
+      // A failed refresh needs no handling: the completion reports
+      // whether the claim survived.
+      void deps.claimImport(docId).catch(() => undefined);
+      timer = setTimeout(tick, CLAIM_REFRESH_MS);
+    };
+    timer = setTimeout(tick, CLAIM_REFRESH_MS);
+    return () => {
+      clearTimeout(timer);
+      left = 0;
+    };
+  }
+
+  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));
 }
+
+// Whether the document holds nothing at all, read only when no write was
+// observed, so the walk is over an empty or near-empty document.
+//
+// A document reports its ROOTS whatever it holds (a fresh one reads
+// `{ entities: {} }`), so emptiness is every root being empty rather than
+// there being no roots.
+function isEmptyDocument(doc: Document): boolean {
+  try {
+    return Object.values(doc.toJSON()).every(
+      (root) =>
+        root === null ||
+        typeof root !== 'object' ||
+        Object.keys(root as object).length === 0,
+    );
+  } catch {
+    // A document that cannot be read is not one to declare empty.
+    return false;
+  }
+}

package/src/index.ts

@@ -1,3 +1,12 @@
+// The app-facing entry (`@brass-build/client`). A type reaches this barrel
+// only when a member of `Brass`, `Document`, or `DocumentSession` names it
+// in a signature, so what an app's autocomplete offers is what an app can
+// call. The plumbing under those members (the session's dependency seam,
+// the document factory, the join and at-version wire shapes) stays exported
+// from its own module for this package's own use, and `./internal` carries
+// the primitives Brass's own dashboard and console import.
+// `__tests__/exports-contract.test.ts` pins both sets.
+
 import { BrassClient } from './client.js';
 import type {
   CreateDocumentOptions,
@@ -14,6 +23,7 @@ import type {
   ErrorListener,
   BrassInitOptions,
   BrassUser,
+  UndoControllerOptions,
   UserChangeListener,
 } from './types.js';
 
@@ -22,13 +32,11 @@ export type {
   ErrorListener,
   BrassInitOptions,
   BrassUser,
+  UndoControllerOptions,
   UserChangeListener,
 };
 export { BrassError, type BrassErrorCode } from './errors.js';
 export {
-  type AcquireOrganizationResult,
-  type HostedUiLauncher,
-  type HostedUiLauncherOptions,
   type HostedUiTheme,
   type SelectDocumentResult,
 } from './hosted-ui.js';
@@ -52,7 +60,6 @@ export {
   type CommandGroup,
   type CommandSurface,
   type DocumentSession,
-  type DocumentSessionDeps,
   type SessionOpenOptions,
   type SessionStatus,
 } from './session.js';
@@ -96,34 +103,38 @@ export type {
   ChangeSource,
   HandleUnsubscribe,
   ListHandle,
+  ListChange,
   ListSubscriber,
+  Splice,
   MapHandle,
   MapSubscriber,
   OrderedMapHandle,
-} from './handles.js';
-export type { UndoControllerOptions } from './undo.js';
-export type { DocumentSerializer } from './serializer.js';
+  OrderedMapPosition,
+} from './handle-types.js';
+
+export type {
+  DocumentSerializer,
+  StoredDocument,
+  StoredList,
+  StoredMap,
+} from './serializer.js';
 export type { DocumentImporter } from './importer.js';
-export { DocumentStream, type StreamRuntime } from './document-streams.js';
+export { DocumentStream } from './document-streams.js';
 export {
-  type CreateDocumentFn,
   type CreateDocumentOptions,
-  type DocumentAtVersionResponse,
-  type DocumentDriveSummaryWire,
-  type DocumentFactory,
-  type DocumentSnapshotResponse,
-  type OpenDocumentFactoryOptions,
-  type OpenDocumentByIdFn,
   type OpenDocumentByIdOptions,
-  type OpenDocumentWsClient,
   type OpenedDocument,
 } from './open-document.js';
+export { PRESENCE_LAYER_MAX_BYTES } from './presence.js';
 export type {
   PresenceChangeListener,
   PresenceClient,
+  PresenceLayer,
   PresenceParticipant,
   PresenceSetInput,
   PresenceState,
+  PresenceStatus,
+  PresenceStatusListener,
 } from './presence.js';
 
 const client = new BrassClient();
@@ -169,8 +180,8 @@ export const Brass = {
   getAccessToken(): Promise<string | null> {
     return client.getAccessToken();
   },
-  // Metadata read for a known id (`get`) plus thumbnails / branches /
-  // pushToDrive. Create / move / list / grant access are hosted-only.
+  // Metadata read for a known id (`get`) plus thumbnails. Create / move /
+  // list / grant access are hosted-only.
   get documents(): DocumentsNamespace {
     return client.documents;
   },

package/src/internal.ts

@@ -16,6 +16,7 @@ export {
   buildSignInUrl,
   refreshTokens,
   type RefreshCredential,
+  type RefreshOutcome,
   type RefreshResult,
   type TokenSet,
 } from './auth-flow.js';

package/src/join-coverage.ts

@@ -0,0 +1,42 @@
+// Which seqs a join response actually delivered.
+//
+// A join carries a snapshot sealed at `snapshot_seq`, the op rows above it,
+// and `current_seq`, the branch's seq counter. The counter is NOT a delivery
+// claim: the server allocates a seq on it before writing that op's row, so
+// while someone is writing in bulk the counter names ops whose rows the
+// tail query cannot see yet. A reader that treats the counter as covered
+// records itself as holding ops it was never sent, and every later prompt
+// for them short-circuits on that record.
+//
+// What a response can vouch for is the snapshot plus the unbroken run of
+// tail seqs above it. Anything past the first gap is applied but not
+// covered, so it parks until the gap fills.
+
+/** The contiguous floor a join delivered: `snapshotSeq` plus its tail run. */
+export function joinCoverageFloor(
+  snapshotSeq: number,
+  tailSeqs: readonly number[],
+): number {
+  const present = new Set(tailSeqs);
+  let floor = snapshotSeq;
+  while (present.has(floor + 1)) floor += 1;
+  return floor;
+}
+
+/**
+ * Where the snapshot in a join response ends, for a response that may not
+ * say. Our server always reports `snapshot_seq`; a response without it
+ * (an older server, a fixture) leaves only the tail's own lower edge, which
+ * is the true boundary except when the first op above the snapshot is one of
+ * the rows still in flight. With no tail at all there is nothing to infer
+ * from, and the counter is all that is on offer.
+ */
+export function snapshotSeqOf(
+  reported: number | undefined,
+  tailSeqs: readonly number[],
+  currentSeq: number,
+): number {
+  if (typeof reported === 'number') return reported;
+  if (tailSeqs.length === 0) return currentSeq;
+  return Math.min(...tailSeqs) - 1;
+}

package/src/jwt.ts

@@ -6,7 +6,14 @@ export function decodeIdToken(idToken: string): BrassUser | null {
   const payloadPart = parts[1];
   if (!payloadPart) return null;
   try {
-    const json = atob(payloadPart.replace(/-/g, '+').replace(/_/g, '/'));
+    // A JWT payload is UTF-8, and `atob` answers one latin1 character per
+    // byte, so a claim with any non-ASCII character (an accented name in
+    // `email`) needs the bytes decoded rather than the string used as is.
+    const bytes = Uint8Array.from(
+      atob(payloadPart.replace(/-/g, '+').replace(/_/g, '/')),
+      (ch) => ch.charCodeAt(0),
+    );
+    const json = new TextDecoder().decode(bytes);
     const claims = JSON.parse(json) as { sub?: unknown; email?: unknown };
     if (typeof claims.sub !== 'string') return null;
     const user: BrassUser = { sub: claims.sub };

package/src/launch-context.ts

@@ -10,8 +10,8 @@
 // collide with an app's own query string, and stripped from the address bar
 // on read so it does not linger in history or a referrer.
 //
-// The dashboard writes this parameter in `src/lib/open-app-url.ts`; the
-// published SDK cannot import the workspace, so the name is spelled in both
+// The dashboard writes this parameter when it opens an app, and the published
+// SDK cannot import the dashboard's source, so the name is spelled in both
 // places.
 
 export const LAUNCH_ORGANIZATION_PARAM = 'brass_org';