@brass-build/client 0.2.0 → 0.4.0

package/docs/text-fields.md

@@ -0,0 +1,191 @@
+# Text fields
+
+`doc.text(key)` is the container for prose several people edit at once. The
+[README](../README.md#prose-several-people-edit) covers what it is and how
+to wire a field to it. This page covers what a real editor needs on top:
+painting a peer's edit without throwing away the caret, the IME window,
+what a keystroke costs, and where a text container belongs in a document.
+
+## Paint a peer's edit without losing the caret
+
+Assigning `field.value` moves the caret to the end, so an editor that
+assigns unconditionally throws away the reader's place on every peer
+keystroke, and one that skips a focused field never shows a peer's typing
+to anyone who is typing themselves. Find the span the incoming value
+replaced, and move the caret across it:
+
+```ts
+const report = doc.text('report');
+let painted = report.read();
+field.value = painted;
+
+report.subscribe((value, origin) => {
+  if (origin?.source === 'local') { painted = value; return; }
+  if (value === painted) return;
+
+  // The one span that differs, found by trimming the common prefix and
+  // the common suffix. A keystroke, a paste, and a peer's edit each look
+  // like this.
+  const max = Math.min(painted.length, value.length);
+  let start = 0;
+  while (start < max && painted.charCodeAt(start) === value.charCodeAt(start)) start += 1;
+  let tail = 0;
+  while (tail < max - start
+         && painted.charCodeAt(painted.length - 1 - tail)
+            === value.charCodeAt(value.length - 1 - tail)) tail += 1;
+  const removed = painted.length - tail - start;
+  const inserted = value.length - tail - start;
+
+  // The caret binds to the text on its right, so a peer typing where it
+  // sits pushes it past what they wrote and leaves it in front of the same
+  // words. One before the span does not move, one after it shifts by the
+  // span's change in length.
+  const carry = (caret: number): number =>
+    caret < start ? caret
+    : caret >= start + removed ? caret + inserted - removed
+    : start + Math.min(caret - start, inserted);
+
+  // A reader with text selected has two offsets, and `selectionDirection`
+  // says which of them their next keystroke extends from.
+  const focused = document.activeElement === field;
+  const anchor = carry(field.selectionStart ?? 0);
+  const head = carry(field.selectionEnd ?? field.selectionStart ?? 0);
+  const direction = field.selectionDirection;
+  // Assigning `value` resets the scroll, which throws a reader who is
+  // partway down a long field back to the top on every peer keystroke.
+  const scroll = field.scrollTop;
+
+  field.value = value;
+  painted = value;
+  field.scrollTop = scroll;
+  if (focused) {
+    field.setSelectionRange(nudgeOffPair(value, anchor), nudgeOffPair(value, head), direction);
+  }
+});
+```
+
+Offsets count UTF-16 code units, which is what a text field's
+`selectionStart` reports, so the two agree with no conversion. The same
+units are why an offset needs one more check before it is used: a character
+outside the Basic Multilingual Plane, an emoji above all, is two code units,
+and the `charCodeAt` walk above stops between them whenever the edit sits
+next to one. `nudgeOffPair` moves such an offset off the seam:
+
+```ts
+function nudgeOffPair(text: string, at: number): number {
+  const bounded = Math.max(0, Math.min(at, text.length));
+  if (bounded <= 0 || bounded >= text.length) return bounded;
+  const before = text.charCodeAt(bounded - 1);
+  const after = text.charCodeAt(bounded);
+  const splits = before >= 0xd800 && before <= 0xdbff && after >= 0xdc00 && after <= 0xdfff;
+  return splits ? bounded - 1 : bounded;
+}
+```
+
+Restoring the selection only while the field is focused keeps the paint
+from setting a selection nobody asked for, and from scrolling an offscreen
+field into view.
+
+`origin` carries who wrote the change, the way a map subscriber's does:
+`local`, `remote`, `undo`, or `redo`, and undefined on a fire describing no
+authored transition (registration, and the catch-up a version checkout
+produces). Splitting on `local` is what keeps this work off the typing
+path, where it would otherwise run on every keystroke.
+
+## Defer the paint, not the write, while an IME is open
+
+Assigning to the field while an IME is open discards what it is holding,
+which costs a reader typing Japanese, Chinese, or Korean the word they were
+in the middle of. So track `compositionstart` / `compositionend` and skip
+the paint in between.
+
+Keep writing through `update` the whole time. `input` fires during a
+composition, the write touches no DOM, and the container merges it with
+whatever a peer sends meanwhile:
+
+```ts
+let composing = false;
+let missed = false;
+
+field.addEventListener('compositionstart', () => { composing = true; });
+field.addEventListener('compositionend', () => {
+  composing = false;
+  painted = field.value;
+  report.update(painted);
+  // What arrived while the composition was open is older than what the
+  // reader just committed, so paint the container's own value, which
+  // carries both.
+  if (missed) {
+    missed = false;
+    const latest = report.read();
+    if (latest !== painted) paintPeerEdit(latest);
+  }
+});
+```
+
+Holding the incoming value and applying it at `compositionend` is the
+version that looks right and loses data: that value predates the
+composition, so painting it discards the word the reader just committed.
+Deferring the write instead has the same shape of bug one layer down, since
+the field's value then has no record of the peer's edit and `update` diffs
+it back out.
+
+## Publish the caret too
+
+`state.textCaret` in [`presence.md`](./presence.md) is
+`{ key, anchor, head }`: the container the caret sits in, and its two
+offsets in the same UTF-16 code units this page uses. Publishing it on
+every selection change lets peers draw where you are working, and the 10 Hz
+presence debounce already paces it.
+
+## What a keystroke costs
+
+`update` compares against the whole stored string to find the smallest
+edit, so its cost scales with the field's own length. Measured through the
+handle on a 2.1 GHz core, after 20,000 edits, typing at a realistic
+revision pattern:
+
+| field | ms per keystroke |
+| --- | --- |
+| 20 KB | 0.72 |
+| 100 KB | 1.72 |
+| 300 KB | 4.09 |
+
+One paragraph, one description, or one report is far inside a frame at
+typing speed. A field holding a book is not, and an app whose document
+grows that large wants its prose split across containers, one per section,
+so an edit compares against a section rather than the book.
+
+A second, smaller term grows with the document's accumulated edit history,
+because materializing a text container costs more as its rope fragments.
+Composing sentences barely fragments it (20,000 keystrokes on a 20 KB field
+stay at 0.46 ms and leave a 2 KB snapshot); revising in short runs across
+the field reaches 0.64 ms. The history term is permanent rather than
+per-session, since a snapshot carries the history.
+
+## One root per document-shaped thing, not per row
+
+A text container is a top-level root, and no nested-text surface exists, so
+per-element prose that merges costs one root per element. Loro prices a
+container against how many the document holds, so that does not stay flat
+the way the record store does, where paging holds container count down past
+`UNPAGED_MAX_RECORDS`. Creating one text root per element against the same
+elements written as records:
+
+| elements | a root each | as records | roots heap | records heap |
+| --- | --- | --- | --- | --- |
+| 5,000 | 599 ms | 403 ms | 27 MB | 3 MB |
+| 10,000 | 1,460 ms | 182 ms | 52 MB | 2 MB |
+| 20,000 | 9,318 ms | 404 ms | 104 MB | 3 MB |
+| 40,000 | 26,419 ms | 1,206 ms | 194 MB | 10 MB |
+
+Registering a subscriber costs the same per root, so an editor that shows
+every row's note pays that cost again on every open.
+
+So prose that belongs to each row of a repeated collection stays in the
+row's record, where the row is the merge unit. Two people typing in one
+row's note then keep one of the two, which is the trade a repeated
+collection makes. Where one particular row is the thing people write
+together, give that row's prose a root of its own and leave the rest in the
+store. Roots in the hundreds are cheap; the curve is what decides, not a
+fixed cap.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brass-build/client",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Client SDK for Brass",
   "type": "module",
   "main": "./dist/index.js",
@@ -11,16 +11,15 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
-    "./vite": {
-      "types": "./dist/vite.d.ts",
-      "import": "./dist/vite.js"
-    },
     "./internal": {
       "types": "./dist/internal.d.ts",
       "import": "./dist/internal.js"
     },
     "./package.json": "./package.json"
   },
+  "browser": {
+    "./dist/wasm-runtime.js": "./dist/wasm-runtime.browser.js"
+  },
   "files": [
     "dist",
     "src",

package/src/acting-organization.ts

@@ -0,0 +1,396 @@
+// Which organization an act that has no document spends.
+//
+// An app opened from a dashboard is launched with one, and an app holding an
+// open document inherits that document's. Everything else is resolved by the
+// server from the caller's own context at the first act that needs it, so the
+// app is never handed a list and never asks at boot.
+//
+// The per-app sessionStorage slot below carries the answer forward within a
+// tab: keys are namespaced per app id so integrations on one origin don't
+// collide, and the slot is cleared on sign-out (session storage also drops on
+// tab close).
+
+import { applyAppAssertionHeader, applyClientVersionHeader } from './api-headers.js';
+import { BrassError } from './errors.js';
+
+const KEY_PREFIX = '__brass_acting_org_';
+
+// Single per-page-load warn: a resolve runs on every act that needs an
+// organization, 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, so the organization this app acts in is resolved again on every page load.',
+  );
+}
+
+function orgKey(appId: string): string {
+  return `${KEY_PREFIX}${appId}`;
+}
+
+export function storeActingOrganization(appId: string, organizationId: string): void {
+  const storage = getStorage();
+  if (!storage) {
+    warnOnceUnavailable();
+    return;
+  }
+  try {
+    storage.setItem(orgKey(appId), organizationId);
+  } catch {
+    // Quota / disabled storage; drop silently. The stored value is a
+    // preference the server re-derives without it, so losing it costs a
+    // resolve rather than the act that needed one.
+  }
+}
+
+export function readActingOrganization(appId: string): string | null {
+  const storage = getStorage();
+  let raw: string | null;
+  if (!storage) return null;
+  try {
+    raw = storage.getItem(orgKey(appId));
+  } catch {
+    // A storage that holds a handle but refuses reads (a partitioned or
+    // locked-down context). See `storeActingOrganization`.
+    return null;
+  }
+  const trimmed = raw?.trim() ?? '';
+  return trimmed === '' ? null : trimmed;
+}
+
+export function clearActingOrganization(appId: string): void {
+  const storage = getStorage();
+  if (!storage) return;
+  try {
+    storage.removeItem(orgKey(appId));
+  } catch {
+    // See `storeActingOrganization`.
+  }
+}
+
+// What the server answers when asked which organization this caller acts in:
+// one organization, or the reason it cannot name one. Never a list.
+export type ResolveOutcome =
+  | {
+      kind: 'resolved';
+      organizationId: string;
+      organizationName: string;
+      /**
+       * Whether this app is installed on the organization. A deliberate
+       * switch reads it so the install is raised before the switch takes
+       * effect, rather than leaving the reader acting somewhere the next call
+       * is refused.
+       */
+      installed: boolean;
+    }
+  | { kind: 'needs-choice' }
+  | { kind: 'no-organization' };
+
+export interface ResolveDeps {
+  /** The open document's organization, where one is open. */
+  activeDocumentOrganizationId: () => Promise<string | null>;
+  /** An organization already resolved on this page load. */
+  cachedResolution: () => string | null;
+  /**
+   * The organization the launch named, where this page load carried one. A
+   * person clicking Open from an organization's dashboard has just said where
+   * they are working, so it outranks a carried choice and is never read as
+   * stale: an app the organization has not installed is what the install
+   * consent behind the refusal is for.
+   */
+  launchPreference: () => string | null;
+  /** The choice this tab carries for this app, from an earlier act. */
+  storedPreference: () => string | null;
+  fetchResolved: (prefer: string | null) => Promise<ResolveOutcome>;
+  /** The hosted dialog that asks the person; null when they dismissed it. */
+  pickOrganization: () => Promise<string | null>;
+  /**
+   * Drop the stored choice, for one the app can no longer act in. The server
+   * validates a preference against MEMBERSHIP, so a choice naming an
+   * organization the app has since been uninstalled from stays resolvable
+   * forever while serving nothing.
+   */
+  forgetPreference: () => void;
+  remember: (
+    organizationId: string,
+    /** Empty where the resolution carried an id and no name. */
+    organizationName: string,
+    /**
+     * Whether to carry the choice past this page load. An organization this
+     * app is not installed on has not become one the app can act in yet: the
+     * act that resolved it is about to be refused, and the reader may decline
+     * the install that follows. Recording it anyway pins every later visit to
+     * an organization nothing they press can work in, with the chooser out of
+     * reach. It is persisted when the install lands instead.
+     */
+    persist: boolean,
+  ) => void;
+}
+
+/**
+ * Which organization the next act uses.
+ *
+ * `ask: false` runs the same ladder and stops where it would raise the hosted
+ * chooser, answering null instead. That is what an app reading its own state
+ * before it acts needs: the question the chooser asks is one only the person
+ * can answer, and asking it unbidden takes the page over for something the
+ * reader never pressed.
+ */
+export async function resolveActingOrganization(
+  deps: ResolveDeps,
+  options: { ask?: boolean } = {},
+): Promise<string | null> {
+  const fromDocument = await deps.activeDocumentOrganizationId();
+  if (fromDocument) {
+    // Recorded, not merely returned. This is where the app is working, so it
+    // is what the next act spends once the document closes; without it a
+    // reader who opens a document, closes it and creates another is asked
+    // where to put the second one, having just worked in the answer. It carries no name (the
+    // document named an id) and does not reach the tab's slot: a document
+    // can live in an organization the reader reaches through a shared
+    // project and is not a member of, which is a place to act from while it
+    // is open rather than a choice to carry.
+    deps.remember(fromDocument, '', false);
+    return fromDocument;
+  }
+  const cached = deps.cachedResolution();
+  if (cached) return cached;
+
+  // The stored choice is a preference rather than an answer: the server
+  // validates it against membership and ignores one that no longer holds, so
+  // a stale value self-heals into whatever the caller's context resolves to.
+  const launch = deps.launchPreference();
+  const stored = launch === null ? deps.storedPreference() : null;
+  const first = await deps.fetchResolved(launch ?? stored);
+  if (first.kind === 'resolved') {
+    // Membership is not the whole of what makes a choice usable. An
+    // organization the app has been uninstalled from still resolves, so a
+    // stored choice naming one would raise the install for a place somebody
+    // deliberately removed this app from, on every load, for as long as the
+    // tab lives. Read as stale instead: drop it and ask again with no
+    // preference, which reaches whatever this caller's context resolves to
+    // and otherwise the chooser, where the reader says where to work now.
+    //
+    // Only for a choice this tab was CARRYING. A launch, a resolution the
+    // reader just made, or their single membership is the answer either way,
+    // and the install is what it needs.
+    if (!first.installed && stored !== null && first.organizationId === stored) {
+      deps.forgetPreference();
+      const healed = await deps.fetchResolved(null);
+      if (healed.kind === 'resolved') return keep(deps, healed);
+    } else {
+      return keep(deps, first);
+    }
+  }
+
+  // Context could not answer. Only the person can, so a caller that asked not
+  // to raise a surface is told that rather than asked.
+  if (options.ask === false) return null;
+
+  // The surface offers their own memberships and creates one where they have
+  // none, so the answer it gives is always one the server can resolve: asking
+  // twice would be asking the same question again rather than making progress.
+  const picked = await deps.pickOrganization();
+  if (!picked) {
+    throw new BrassError(
+      first.kind === 'no-organization'
+        ? 'No organization yet. Create one to continue.'
+        : 'No organization chosen.',
+      { status: 400 },
+    );
+  }
+  const second = await deps.fetchResolved(picked);
+  if (second.kind === 'resolved') return keep(deps, second);
+  throw new BrassError('Brass could not use the organization you chose.', {
+    status: 400,
+  });
+}
+
+function keep(
+  deps: ResolveDeps,
+  outcome: Extract<ResolveOutcome, { kind: 'resolved' }>,
+): string {
+  deps.remember(outcome.organizationId, outcome.organizationName, outcome.installed);
+  return outcome.organizationId;
+}
+
+/**
+ * What the chrome names: the organization the NEXT act would spend.
+ *
+ * An open document takes it over, because the document's organization is what
+ * every act made while it is open spends. That holds even when the name is
+ * unknown, which is a document in an organization this reader reaches through
+ * a directly shared project: the menu says nothing rather than naming the memo
+ * over it. Closing the document hands it back, so the two never disagree with
+ * what the app is about to do.
+ *
+ * Named whether or not the caller belongs to anywhere else. The menu offers a
+ * switch, and the surface behind it is also how a first or a second
+ * organization gets created, so what a caller with one has is a choice they
+ * have not made yet rather than no choice; naming the organization is what
+ * makes that switch legible instead of an offer to change something the menu
+ * never states.
+ *
+ * Null where neither is known, which is an ordinary state rather than a gap
+ * to fill: an app reached by its own URL, holding no document and nothing
+ * stored, has no organization until an act needs one, and resolving one to
+ * decorate a menu is exactly the boot-time question this design refuses.
+ */
+export function visibleOrganization(
+  openDocument: { organization: Named | null } | null,
+  memo: Named | null,
+): { id: string; name: string } | null {
+  // An open document takes the menu over ENTIRELY, naming its organization
+  // or nothing. Falling back to the memo here would be the exact fault this
+  // exists to prevent: the document's organization is what its acts spend,
+  // so a menu naming the memo over an open document names an organization
+  // the app is not using.
+  if (openDocument) return named(openDocument.organization);
+  return named(memo);
+}
+
+interface Named {
+  id: string;
+  name: string;
+}
+
+function named(organization: Named | null): { id: string; name: string } | null {
+  // An id with no name is a resolution taken from an open document, which
+  // names no organization. There is nothing to draw until the chrome asks the
+  // server for one.
+  if (!organization || organization.name === '') return null;
+  return { id: organization.id, name: organization.name };
+}
+
+export interface ActingOrganizationFetchDeps {
+  apiBaseUrl: string;
+  getAccessToken: () => Promise<string | null>;
+  getAppAssertion: () => Promise<string | null>;
+  fetchImpl?: typeof fetch;
+}
+
+// The refusals that are a question for the person rather than a fault: the
+// caller belongs to several organizations and none of the context named one,
+// or belongs to none at all.
+const OUTCOME_CODES: ReadonlyMap<string, 'needs-choice' | 'no-organization'> = new Map([
+  ['destination_required', 'needs-choice'],
+  ['no_organization', 'no-organization'],
+]);
+
+export async function fetchActingOrganization(
+  deps: ActingOrganizationFetchDeps,
+  prefer: string | null,
+): Promise<ResolveOutcome> {
+  const token = await deps.getAccessToken();
+  if (!token) throw new BrassError('Not signed in', { status: 401 });
+  const headers: Record<string, string> = { authorization: `Bearer ${token}` };
+  applyClientVersionHeader(headers);
+  await applyAppAssertionHeader(headers, deps.getAppAssertion);
+  const base = deps.apiBaseUrl.replace(/\/$/, '');
+  const query = prefer ? `?prefer=${encodeURIComponent(prefer)}` : '';
+  const doFetch = deps.fetchImpl ?? fetch;
+  const response = await doFetch(`${base}/me/acting-organization${query}`, {
+    method: 'GET',
+    headers,
+  });
+  type Body = {
+    organization_id?: unknown;
+    organization_name?: unknown;
+    installed?: unknown;
+    error?: unknown;
+    code?: unknown;
+  };
+  let body: Body = {};
+  try {
+    body = (await response.json()) as Body;
+  } catch {
+    // Leaves the generic message below, which the status already qualifies.
+  }
+  if (response.ok && typeof body.organization_id === 'string') {
+    return {
+      kind: 'resolved',
+      organizationId: body.organization_id,
+      organizationName:
+        typeof body.organization_name === 'string' ? body.organization_name : '',
+      // Absent reads as installed, so an older api that does not send it
+      // leaves the act to raise the refusal as it always did rather than
+      // asking for an install nothing established was missing.
+      installed: body.installed !== false,
+    };
+  }
+  const kind =
+    typeof body.code === 'string' ? OUTCOME_CODES.get(body.code) : undefined;
+  if (response.status === 409 && kind) return { kind };
+  throw new BrassError(
+    typeof body.error === 'string' ? body.error : 'Could not resolve an organization',
+    { status: response.status },
+  );
+}
+
+/**
+ * A deliberate switch, as the account menu drives it. Separate from
+ * `resolveActingOrganization` because the two differ in what follows the
+ * choice: a resolve is followed by the act that asked for it, which raises
+ * its own refusal, while a switch is followed by nothing at all. So the
+ * switch has to establish for itself that the app can act where the reader
+ * sent it, and has to tell the app that everything it read is now about a
+ * different organization.
+ */
+export interface SwitchDeps {
+  /** The organization being acted in now, so the surface can mark it. */
+  current: () => string | null;
+  pickOrganization: (current: string | undefined) => Promise<string | null>;
+  fetchResolved: (prefer: string) => Promise<ResolveOutcome>;
+  /** The hosted install dialog, pinned; null when the reader declined. */
+  offerInstall: (organizationId: string) => Promise<boolean>;
+  remember: (organizationId: string, organizationName: string) => void;
+  /** Re-reads the app under the new organization. */
+  reload: () => void;
+}
+
+export async function switchActingOrganization(deps: SwitchDeps): Promise<boolean> {
+  const current = deps.current() ?? undefined;
+  const picked = await deps.pickOrganization(current);
+  if (!picked) return false;
+  // Re-picking the organization the app is already acting in is a valid
+  // answer to the question the surface asks, and it moves nothing. The
+  // ordinary way to reach it is a caller with one organization opening the
+  // chooser to see what is there, so it must not cost them their open
+  // document and a page reload to say where they already are.
+  if (picked === current) return false;
+  // The pick goes back to the server, which names the organization as the
+  // platform holds it and refuses one the caller cannot act in.
+  const named = await deps.fetchResolved(picked);
+  if (named.kind !== 'resolved') return false;
+  // An organization this app is not installed on cannot serve it, so the
+  // install is asked for here rather than left to the next act. Without this
+  // the switch appears to succeed and the refusal arrives later, or on a
+  // reload, against work the reader has already started.
+  if (!named.installed && !(await deps.offerInstall(named.organizationId))) {
+    // Declining abandons the switch. Recording an organization the app cannot
+    // act in leaves the reader on one organization's screen with nothing they
+    // press able to work.
+    return false;
+  }
+  deps.remember(named.organizationId, named.organizationName);
+  // Everything the app read under the previous organization is about a
+  // different one now, and the app has no way to know which of its own state
+  // that covers. The reader asked for this, so re-reading the app is the
+  // expected consequence of their own act rather than a surprise, and the
+  // choice is already recorded so it survives.
+  deps.reload();
+  return true;
+}

package/src/api-headers.ts

@@ -16,13 +16,13 @@ export async function applyAppAssertionHeader(
   if (assertion) headers['x-brass-app-assertion'] = assertion;
 }
 
-// Attaches the SDK's version as `x-brass-client` (`sdk/<version>`), the same
-// value reported on /refresh and the WS connect URL, so the server sees the
-// deployed SDK version at the data-API surface too. The minimum-version gate
-// reads it at document open to serve a too-old client an upgrade message
-// (rendered verbatim through `session.error`). Same boundary as the
-// app-assertion header: data API only, never a presigned URL. Unconditional, so the
-// version distribution covers read-only apps that never refresh.
+// Names the SDK and its version. Brass answers a build too old to serve with
+// an upgrade message, which reaches the app as `session.error` and is
+// rendered verbatim.
+//
+// Same boundary as the app-assertion header: Brass's own API calls carry it,
+// a presigned URL never does. Attached unconditionally, so an app that only
+// ever reads carries it too.
 export function applyClientVersionHeader(headers: Record<string, string>): void {
   headers['x-brass-client'] = SDK_CLIENT_ID;
 }