@brass-build/client 0.1.0

package/src/record-paging.ts

@@ -0,0 +1,270 @@
+// The record-store paging codec: how a large record-graph document packs its
+// `instances` map into page containers, and how to undo that back to a flat
+// `key -> { type, params }` lookup.
+//
+// It lives in the SDK (not in `formats/core`, where the record store lives)
+// because the published `@brass-build/client` ships unbundled and can only
+// import published packages and its own relative files; `formats/core` is
+// neither. The substrate imports these helpers back from here, so the codec is
+// defined ONCE and the SDK's paged read / edit cannot drift from how the store
+// is written. Deliberately loro-free (fflate, a stable hash, JSON), so it
+// stays a pure value codec on both sides.
+//
+// Wire recap (full rationale in `formats/core/src/record-store.ts`): the root
+// `instances` LoroMap is EITHER unpaged (key -> `{ type, params }`, params a
+// plain value) or, above `UNPAGED_MAX_RECORDS` records, PAGED: keyed
+// `p0,p1,...` -> a `{ type: '__page__', params: <string> }` container whose
+// params is a gzipped latin1 string of a JSON array of `[key, tag, body]`
+// triples. `meta.page_count` carries the count; `instance_order` lists record
+// keys in order in both shapes. A record's page is a hash of its key, so it is
+// resolved with no stored index.
+
+import { gzipSync, gunzipSync, strToU8, strFromU8 } from 'fflate';
+
+// Gzip backend: native `node:zlib` when the runtime provides it, fflate
+// otherwise. The page codec must stay a pure isomorphic value codec (the
+// published SDK runs in browsers, where fflate is the only option), but
+// fflate's JS inflate is several times slower than zlib's native one on a
+// server-grade page walk, and a server's constrained cores amplify that. The
+// module is reached through `process.getBuiltinModule` (Node 22+) via a
+// structural `globalThis` read, so no `node:` import ever appears in the
+// browser bundle and the SDK compiles without Node types. Both backends
+// speak standard gzip, so pages written by one decode under the other.
+interface GzipBackend {
+  gzipSync(bytes: Uint8Array): Uint8Array;
+  gunzipSync(bytes: Uint8Array): Uint8Array;
+}
+
+let nativeZlib: GzipBackend | null | undefined;
+
+function zlibBackend(): GzipBackend | null {
+  if (nativeZlib === undefined) {
+    try {
+      const proc = (
+        globalThis as {
+          process?: { getBuiltinModule?: (id: string) => unknown };
+        }
+      ).process;
+      nativeZlib =
+        (proc?.getBuiltinModule?.('node:zlib') as GzipBackend | undefined) ??
+        null;
+    } catch {
+      nativeZlib = null;
+    }
+  }
+  return nativeZlib;
+}
+
+function gzip(bytes: Uint8Array): Uint8Array {
+  const zlib = zlibBackend();
+  return zlib ? zlib.gzipSync(bytes) : gzipSync(bytes);
+}
+
+function gunzip(bytes: Uint8Array): Uint8Array {
+  const zlib = zlibBackend();
+  return zlib ? zlib.gunzipSync(bytes) : gunzipSync(bytes);
+}
+
+/** Field names inside a stored record container: `type` is the tag, `params`
+ *  the body. Verbatim so the substrate and SDK name the same fields. */
+export const TAG_FIELD = 'type';
+export const BODY_FIELD = 'params';
+
+/** Root container keys the record store occupies on a document. */
+export const META_KEY = 'meta';
+export const RECORDS_KEY = 'instances';
+export const ORDER_KEY = 'instance_order';
+
+/** `meta` key holding a paged store's page count; absent (or 0) means
+ *  unpaged. The read path detects pages by tag; only an in-place edit needs
+ *  the count, to hash a key to its page. */
+export const PAGE_COUNT_KEY = 'page_count';
+
+/** `meta` key holding the paging codec's scheme number, stamped on a paged
+ *  write. The scheme fixes the page-key hash (`pageKeyFor`), the `p<n>` key
+ *  format, and the packed-record layout together: a reader that hashes a key
+ *  with a different scheme than the store was written under targets the wrong
+ *  page on an in-place edit, silently writing a record into a page it does not
+ *  belong to. The stamp lets a pinned reader detect a store written under a
+ *  scheme it does not implement and refuse the edit instead of corrupting it.
+ *  Absent means the current scheme (paged stores written before the stamp
+ *  existed used scheme 1's hash and layout). */
+export const PAGING_SCHEME_KEY = 'paging_scheme';
+
+/** The paging scheme this build writes and can edit. Bump ONLY alongside a
+ *  change to `pageKeyFor`'s hash, the `p<n>` key format, or the packed-record
+ *  layout, so an older pinned reader trips `isPagingSchemeEditable` and fails
+ *  loud rather than editing a store it would mis-hash. */
+export const CURRENT_PAGING_SCHEME = 1;
+
+/** Whether a store stamped with `scheme` can be edited in place by this build.
+ *  Absent / non-numeric / `0` is a scheme-1 store (the stamp postdates it), so
+ *  editable; any scheme at or below the current one is editable; a higher
+ *  scheme is not (this reader would hash into the wrong page). Reads stay
+ *  best-effort and are not gated here; only an in-place edit can persist the
+ *  mis-hash, so the edit path is where the guard belongs. */
+export function isPagingSchemeEditable(scheme: unknown): boolean {
+  if (typeof scheme !== 'number' || !Number.isFinite(scheme) || scheme <= 0) {
+    return true;
+  }
+  return scheme <= CURRENT_PAGING_SCHEME;
+}
+
+/** Above this many records the store is written paged; at or below it it keeps
+ *  the one-container-per-record shape. */
+export const UNPAGED_MAX_RECORDS = 50_000;
+
+// Target records per page and a page-count ceiling so even the 2M-record cap
+// stays out of the slow zone. Mirrored from the substrate's write path so
+// `pageCountFor` agrees with how the store was written.
+const TARGET_PAGE_SIZE = 64;
+const MAX_PAGES = 50_000;
+
+/** The tag a page container carries in place of a record tag, so a reader
+ *  tells a page (body = record triples) from a single record (body = one
+ *  plain value). */
+export const PAGE_TAG = '__page__';
+
+/** A record packed inside a page body: `[key, tag, body]`. The tuple form
+ *  keeps a paged snapshot compact. */
+export type PackedRecord<B> = [key: string, tag: string, body: B];
+
+/** Encode a page's triples as its stored body: JSON-serialised, gzipped, held
+ *  as a latin1 string. A STRING body avoids loro's superlinear per-value
+ *  conversion of a deeply nested triple array; gzipping keeps a heavy file in
+ *  memory + export budget. (Full rationale in the substrate's `encodePageBody`.) */
+export function encodePageBody<B>(triples: PackedRecord<B>[]): string {
+  return encodePageBodyFromEncoded(triples.map((t) => JSON.stringify(t)));
+}
+
+/** Encode one record's `[key, tag, body]` triple as the JSON string it
+ *  occupies inside a page body. Split from page assembly so a large write can
+ *  stringify each record as it buckets and release the parsed body before the
+ *  gzip loop, rather than holding the whole parsed model live through it (see
+ *  `writeRecordStoreConsuming` for why that release keeps the encode fast). */
+export function encodeRecordForPage<B>(
+  key: string,
+  tag: string,
+  body: B,
+): string {
+  return JSON.stringify([key, tag, body] as PackedRecord<B>);
+}
+
+/** Assemble a page body from records already JSON-encoded by
+ *  `encodeRecordForPage`: wrap in a JSON array, gzip, hold as a latin1 string.
+ *  Byte-identical to `encodePageBody` over the same triples, so the wire shape
+ *  is unchanged; the split exists only so the writer frees each parsed body
+ *  first. */
+export function encodePageBodyFromEncoded(encoded: string[]): string {
+  return strFromU8(gzip(strToU8('[' + encoded.join(',') + ']')), true);
+}
+
+/** Decode a page body back to its record triples. Returns [] for anything that
+ *  does not decompress to a JSON array, so a reader tolerates a corrupt or
+ *  stray page rather than throwing. */
+export function decodePageBody(body: unknown): PackedRecord<unknown>[] {
+  if (typeof body !== 'string') return [];
+  try {
+    const json = strFromU8(gunzip(strToU8(body, true)));
+    const parsed = JSON.parse(json);
+    return Array.isArray(parsed) ? (parsed as PackedRecord<unknown>[]) : [];
+  } catch {
+    return [];
+  }
+}
+
+/** The page count for a record population: 0 (unpaged) at or below
+ *  `UNPAGED_MAX_RECORDS`, else ~`TARGET_PAGE_SIZE` records per page, capped at
+ *  `MAX_PAGES`. */
+export function pageCountFor(recordCount: number): number {
+  if (recordCount <= UNPAGED_MAX_RECORDS) return 0;
+  return Math.min(Math.ceil(recordCount / TARGET_PAGE_SIZE), MAX_PAGES);
+}
+
+/** FNV-1a (32-bit) assigning a record key to a page. Stable and
+ *  engine-independent: the same key resolves to the same page on write, read,
+ *  and edit across processes, which is what lets the page be found with no
+ *  stored index. */
+function hashKey(key: string): number {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < key.length; i += 1) {
+    h ^= key.charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  return h >>> 0;
+}
+
+/** The page key a record key lives in, for a store of `pageCount` pages. */
+export function pageKeyFor(key: string, pageCount: number): string {
+  return `p${hashKey(key) % pageCount}`;
+}
+
+/** A stored container's tag (`type`), or null for any value not in the
+ *  `{ type, params }` shape, so a reader skips a corrupt entry. A page carries
+ *  `PAGE_TAG`. */
+export function peekRecordTag(value: unknown): string | null {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  const tag = (value as Record<string, unknown>)[TAG_FIELD];
+  return typeof tag === 'string' ? tag : null;
+}
+
+/** Decode a stored container (`{ type, params }`) to its tag + raw body,
+ *  or null when it is not in the record shape. */
+export function decodeRecordValue(
+  value: unknown,
+): { tag: string; body: unknown } | null {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  const o = value as Record<string, unknown>;
+  const tag = o[TAG_FIELD];
+  if (typeof tag !== 'string' || !(BODY_FIELD in o)) return null;
+  return { tag, body: o[BODY_FIELD] };
+}
+
+/** Whether a `meta.page_count` value denotes a PAGED store. The writer sets
+ *  it to a positive count only when it pages, and never on an unpaged write,
+ *  so a positive finite number is the authoritative "is paged" signal. */
+export function isPagedByPageCount(pageCount: unknown): boolean {
+  return typeof pageCount === 'number' && Number.isFinite(pageCount) && pageCount > 0;
+}
+
+/** Flatten a possibly-PAGED `instances` lookup to the flat
+ *  `key -> { type, params }` lookup a reader consumes. An unpaged lookup is
+ *  returned unchanged (no allocation). The single place paging is undone on the
+ *  read side.
+ *
+ *  `paged` is the AUTHORITATIVE page state, read from `meta.page_count` by the
+ *  caller (`isPagedByPageCount`). Page interpretation MUST be gated on it, not
+ *  on whether some entry is `PAGE_TAG`-tagged: a genuine record whose codec tag
+ *  happens to equal `PAGE_TAG` in an UNPAGED store is a real record, not a
+ *  page. Treating it as a page decodes its plain body as `decodePageBody`
+ *  (which returns `[]` for a non-page body), silently DROPPING the record, and
+ *  a crafted page-shaped body could forge records into the lookup. */
+export function flattenPagedLookup(
+  lookup: Record<string, unknown>,
+  paged: boolean,
+): Record<string, unknown> {
+  if (!paged) return lookup;
+
+  const flat: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(lookup)) {
+    if (peekRecordTag(value) !== PAGE_TAG) {
+      flat[key] = value; // tolerate a stray non-page entry by its own key
+      continue;
+    }
+    const body = decodePageBody(decodeRecordValue(value)?.body);
+    for (const packed of body) {
+      if (
+        Array.isArray(packed) &&
+        packed.length >= 3 &&
+        typeof packed[0] === 'string' &&
+        typeof packed[1] === 'string'
+      ) {
+        flat[packed[0]] = {
+          [TAG_FIELD]: packed[1],
+          [BODY_FIELD]: packed[2],
+        };
+      }
+    }
+  }
+  return flat;
+}

package/src/schema-conflict-dialog.ts

@@ -0,0 +1,176 @@
+// The prompt shown when the platform refuses to open a document this app's
+// declared schema cannot read.
+//
+// SDK-rendered rather than a hosted iframe: it asks one question about a
+// document already named on this page, needs no session of its own, and has
+// to appear on a cold boot from a bookmark, which is the moment an iframe
+// round-trip is least welcome. The hosted dialogs exist for surfaces that
+// read the person's whole account; this reads nothing.
+//
+// Both strings are the server's own, rendered verbatim. A client compiles
+// into an app's bundle and freezes there, so a word this file holds itself
+// can only be corrected by every app republishing, while a word it is handed
+// reaches every app the moment the platform deploys. The fallback below is
+// for a platform that predates the title, not a second opinion about wording.
+
+export interface SchemaConflictChoice {
+  openAnyway: boolean;
+}
+
+const STYLE = `
+/* A dialog opened with showModal(), so the browser holds the keyboard inside
+   the prompt. The UA box styles for a dialog (content-sized, centered,
+   bordered, padded, max-width capped) are all wrong for a full-viewport
+   backdrop, so each is zeroed, and the UA backdrop is cleared because this
+   element paints the dim itself. */
+.brass-sc-backdrop {
+  position: fixed;
+  inset: 0;
+  margin: 0;
+  border: 0;
+  width: auto;
+  height: auto;
+  max-width: none;
+  max-height: none;
+  z-index: 2147483646;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 1rem;
+  background: rgba(20, 18, 13, 0.45);
+  font: 15px/1.5 system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif;
+}
+.brass-sc-backdrop::backdrop {
+  background: transparent;
+}
+.brass-sc-panel {
+  background: Canvas;
+  color: CanvasText;
+  color-scheme: light dark;
+  max-width: 26rem;
+  width: 100%;
+  padding: 1.25rem;
+  border-radius: 0.75rem;
+  box-shadow: 0 16px 40px rgba(0, 0, 0, 0.28);
+}
+.brass-sc-title {
+  margin: 0 0 0.5rem;
+  font-size: 1.0625rem;
+  font-weight: 600;
+}
+.brass-sc-body {
+  margin: 0 0 1.25rem;
+}
+.brass-sc-actions {
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: flex-end;
+  gap: 0.5rem;
+}
+.brass-sc-actions button {
+  font: inherit;
+  min-height: 2.5rem;
+  padding: 0 0.875rem;
+  border-radius: 0.375rem;
+  border: 1px solid rgba(128, 128, 128, 0.4);
+  background: transparent;
+  color: inherit;
+  cursor: pointer;
+}
+.brass-sc-actions button.brass-sc-go {
+  border-color: transparent;
+  background: CanvasText;
+  color: Canvas;
+}
+`;
+
+/**
+ * Ask whether to open the document anyway. Resolves `openAnyway: false` on
+ * Close, on Escape, and when there is no DOM to ask in: every one of those is
+ * an open nobody agreed to, and the refusal stands.
+ */
+export function askSchemaConflict(
+  message: string,
+  title?: string,
+): Promise<SchemaConflictChoice> {
+  if (typeof document === 'undefined') {
+    return Promise.resolve({ openAnyway: false });
+  }
+  return new Promise<SchemaConflictChoice>((resolve) => {
+    const host = document.createElement('div');
+    const shadow = host.attachShadow({ mode: 'open' });
+    const style = document.createElement('style');
+    style.textContent = STYLE;
+
+    const backdrop = document.createElement('dialog');
+    backdrop.className = 'brass-sc-backdrop';
+    const panel = document.createElement('div');
+    panel.className = 'brass-sc-panel';
+    panel.setAttribute('role', 'alertdialog');
+    panel.setAttribute('aria-modal', 'true');
+    panel.setAttribute('aria-labelledby', 'brass-sc-title');
+
+    const titleEl = document.createElement('h2');
+    titleEl.className = 'brass-sc-title';
+    titleEl.id = 'brass-sc-title';
+    titleEl.textContent = title ?? 'This app may not read this file correctly';
+
+    const body = document.createElement('p');
+    body.className = 'brass-sc-body';
+    body.textContent = message;
+
+    const actions = document.createElement('div');
+    actions.className = 'brass-sc-actions';
+    const close = document.createElement('button');
+    close.type = 'button';
+    close.textContent = 'Close';
+    const go = document.createElement('button');
+    go.type = 'button';
+    go.className = 'brass-sc-go';
+    go.textContent = 'Open anyway';
+
+    // Where the reader was when the prompt opened. Answering it detaches the
+    // prompt rather than closing it in place, so putting them back is this
+    // function's job.
+    const opener =
+      document.activeElement instanceof HTMLElement ? document.activeElement : null;
+
+    let settled = false;
+    const settle = (openAnyway: boolean): void => {
+      if (settled) return;
+      settled = true;
+      document.removeEventListener('keydown', onKey, true);
+      if (backdrop.open) backdrop.close();
+      host.remove();
+      if (opener?.isConnected) opener.focus();
+      resolve({ openAnyway });
+    };
+    function onKey(event: KeyboardEvent): void {
+      if (event.key === 'Escape') settle(false);
+    }
+
+    close.addEventListener('click', () => settle(false));
+    go.addEventListener('click', () => settle(true));
+    document.addEventListener('keydown', onKey, true);
+    // An open dialog answers Escape itself, which would close it without
+    // resolving. Route it into the one answer path; `onKey` above normally
+    // gets there first.
+    backdrop.addEventListener('cancel', (event) => {
+      event.preventDefault();
+      settle(false);
+    });
+
+    actions.append(close, go);
+    panel.append(titleEl, body, actions);
+    backdrop.append(panel);
+    shadow.append(style, backdrop);
+    document.body.append(host);
+    // The call that holds the keyboard inside the prompt: without it Tab keeps
+    // walking the app behind it. Guarded so a browser without the top layer
+    // still gets the prompt, non-modal, rather than none.
+    if (typeof backdrop.showModal === 'function') backdrop.showModal();
+    // Close is the safe answer, so it takes focus: Enter on a dialog nobody
+    // read declines rather than opening a document the platform refused.
+    close.focus();
+  });
+}

package/src/selection-persistence.ts

@@ -0,0 +1,98 @@
+// Per-app sessionStorage layer that stashes the last value returned by
+// `Brass.selectDocument()`; the session's boot restore reads it back as
+// the bare-URL fallback.
+//
+// Keys are namespaced per-app id so integrations on one origin don't
+// collide. Cleared on sign-out (`clearAll`); session storage also drops on
+// tab close.
+
+import type { SelectDocumentResult } from './hosted-ui.js';
+
+const KEY_PREFIX = '__brass_';
+const DOC_KEY = `${KEY_PREFIX}last_doc_`;
+
+// Single per-page-load warn: `storeLastDocument` runs on every successful pick,
+// so without the latch a server-rendered host would flood its logs.
+let warnedUnavailable = false;
+
+function getStorage(): Storage | null {
+  if (typeof sessionStorage === 'undefined') return null;
+  try {
+    return sessionStorage;
+  } catch {
+    return null;
+  }
+}
+
+function warnOnceUnavailable(): void {
+  if (warnedUnavailable) return;
+  warnedUnavailable = true;
+  console.warn(
+    'Brass: sessionStorage is unavailable; selection persistence is disabled.',
+  );
+}
+
+function docKey(appId: string): string {
+  return `${DOC_KEY}${appId}`;
+}
+
+function isSelectDocumentResult(value: unknown): value is SelectDocumentResult {
+  if (!value || typeof value !== 'object') return false;
+  const v = value as Record<string, unknown>;
+  return (
+    typeof v['doc_id'] === 'string' &&
+    // `project_id: string | null` (loose docs have no project).
+    (typeof v['project_id'] === 'string' || v['project_id'] === null) &&
+    typeof v['organization_id'] === 'string' &&
+    typeof v['role'] === 'string' &&
+    typeof v['name'] === 'string' &&
+    typeof v['created_at'] === 'string' &&
+    typeof v['updated_at'] === 'string'
+  );
+}
+
+export function storeLastDocument(
+  appId: string,
+  value: SelectDocumentResult,
+): void {
+  const storage = getStorage();
+  if (!storage) {
+    warnOnceUnavailable();
+    return;
+  }
+  try {
+    storage.setItem(docKey(appId), JSON.stringify(value));
+  } catch {
+    // Quota / disabled storage; drop silently so a recall-on-reload
+    // niceness never breaks the launcher path that just succeeded.
+  }
+}
+
+export function readLastDocument(
+  appId: string,
+): SelectDocumentResult | null {
+  const storage = getStorage();
+  if (!storage) return null;
+  const raw = storage.getItem(docKey(appId));
+  if (raw === null) return null;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  // A value written by an older SDK version may not match the current
+  // shape; ignore it rather than hand the caller a half-typed object.
+  if (!isSelectDocumentResult(parsed)) return null;
+  return parsed;
+}
+
+export function clearAll(appId: string): void {
+  const storage = getStorage();
+  if (!storage) return;
+  try {
+    storage.removeItem(docKey(appId));
+  } catch {
+    // See `storeLastDocument`.
+  }
+}

package/src/serializer.ts

@@ -0,0 +1,15 @@
+import type { Document } from './documents.js';
+
+// A per-app serializer that turns an app-owned (blob) document's records
+// back into the source file's bytes: the inverse of the parse the app ran
+// on `doc.sourceBlob()` when it opened the file. Register one at boot with
+// `Brass.registerSerializer`.
+//
+// The platform invokes it, never the app: on a download from a hosted Brass
+// surface, the platform asks the running app to serialise, then handles
+// staging, naming, and delivery. Producing the bytes is the serializer's
+// whole job. An app with no registered serializer cannot export its blob
+// documents (the platform falls back to the stale-original passthrough).
+export type DocumentSerializer = (
+  doc: Document,
+) => Uint8Array | Promise<Uint8Array>;

package/src/session-persistence.ts

@@ -0,0 +1,69 @@
+// Per-app sessionStorage layer for the incognito / third-party-cookie
+// fallback session token: the opaque `sid` from a `brass_code` exchange, so
+// a hard reload in a cookie-blocked browser (incognito, Safari ITP) keeps
+// the user signed in. In a normal browser the cross-site cookie carries the
+// session and nothing is written here.
+//
+// The value is no more sensitive than the cookie it mirrors: an opaque
+// pointer, useless off an allowlisted Origin, gated by `approved_apps`
+// server-side, same 30-day TTL. `sessionStorage` (per-tab, dropped on tab
+// close) matches the cookie-channel UX. Keyed per-app id.
+
+const KEY_PREFIX = '__brass_session_';
+
+let warnedUnavailable = false;
+
+function getStorage(): Storage | null {
+  if (typeof sessionStorage === 'undefined') return null;
+  try {
+    return sessionStorage;
+  } catch {
+    return null;
+  }
+}
+
+function warnOnceUnavailable(): void {
+  if (warnedUnavailable) return;
+  warnedUnavailable = true;
+  console.warn(
+    'Brass: sessionStorage is unavailable; the incognito session-token fallback will not survive reloads.',
+  );
+}
+
+function key(appId: string): string {
+  return `${KEY_PREFIX}${appId}`;
+}
+
+export function storeSessionToken(appId: string, token: string): void {
+  const storage = getStorage();
+  if (!storage) {
+    warnOnceUnavailable();
+    return;
+  }
+  try {
+    storage.setItem(key(appId), token);
+  } catch {
+    // Quota / disabled storage; drop rather than fail a /refresh that
+    // already succeeded (reload-survival is a niceness).
+  }
+}
+
+export function readSessionToken(appId: string): string | null {
+  const storage = getStorage();
+  if (!storage) return null;
+  try {
+    return storage.getItem(key(appId));
+  } catch {
+    return null;
+  }
+}
+
+export function clearSessionToken(appId: string): void {
+  const storage = getStorage();
+  if (!storage) return;
+  try {
+    storage.removeItem(key(appId));
+  } catch {
+    // See `storeSessionToken`.
+  }
+}