@brass-build/client 0.3.0 → 0.4.1

package/docs/services.md

@@ -0,0 +1,265 @@
+# Calling an outside service
+
+The README's [Calling an outside service](../README.md#calling-an-outside-service)
+covers how to make a call. This page covers what each refusal code means,
+how to read values only the user knows, and which host to pass for a service
+split across several addresses. [`app-manifest.md`](./app-manifest.md) covers
+declaring a host and its authentication method.
+
+## What comes back
+
+`callService` returns the service's response unchanged, within these limits:
+
+- Text only, up to 5 MB, within 25 seconds.
+- No streaming. A streaming endpoint's events all arrive together at the end.
+- For binary data, call an endpoint that returns a URL or base64.
+- Brass does not follow redirects. A `3xx` is returned as
+  `response_redirected`, with the service's `location` in the body.
+
+`options.method` defaults to `'POST'`.
+
+## Refusal codes
+
+When Brass refuses a call rather than sending it, the response body has a
+`code`:
+
+```js
+const res = await Brass.callService(host, path);
+if (!res.ok) {
+  const { code } = await res.json();
+  if (code === 'credential_required') await Brass.connectService(host);
+}
+```
+
+Each code always comes with the same HTTP status, so branching on the code
+is enough. Two answers carry no code, and both mean the hop to the service
+itself did not complete: a `502` where Brass could not reach the service, and
+a `504` where the service did not answer in time. Other `502`s do carry a
+code, so read the body before treating one as unreachable.
+
+**Somebody using your app can supply what is missing.** Call
+`Brass.connectService(host)`. The dialog asks whoever opened it for whatever
+the host needs, and tells anyone who cannot answer who to ask.
+
+| `code`                | What it means                                                                                             |
+| --------------------- | --------------------------------------------------------------------------------------------------------- |
+| `credential_required` | No credential is connected for this host, or the one connected is not approved for your app, no longer covers what your app sends, or carries no value under a name your app reads back. One code, because the dialog is the answer to all of them. The body's sentence says which, for a person to read. |
+
+**Your own key is what is missing.** These are yours to settle on your app's
+settings page, so there is nothing to raise on the page: report the feature as
+unavailable.
+
+| `code`                       | What it means                                                                                             |
+| ---------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `app_credential_not_set`     | You have not entered a key for this service yet. This is the refusal you get by default, until you enter one or hand the service over for whoever runs your app to connect. |
+| `app_credential_incomplete`  | Your own key carries no value under a name your manifest asks for.                                         |
+
+**A stored credential is there and does not work.**
+
+| `code`                       | What it means                                                                                             |
+| ---------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `credential_rejected`        | The service rejected the stored credential.                                                                |
+| `credential_scheme_unusable` | The host's credential is not usable as configured.                                                         |
+| `credential_exchange_failed` | Brass could not reach the service for a token, or got back something that was not one.                     |
+| `credential_unreadable`      | Brass cannot read the credential stored here. Enter it again.                                              |
+
+**The call itself is not allowed.** Fix these in your app.
+
+| `code`                    | What it means                                                                                             |
+| ------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `service_not_declared`    | Your manifest does not declare that host, or your latest publish has not registered it.                    |
+| `path_invalid`            | The path names its own host, escapes the service with `..`, or cannot be decoded.                           |
+| `service_headers_invalid` | A header in `options.headers` is one HTTP itself controls (`content-length`, `host`, `connection` and the like), or its name or value cannot go on a header line. |
+| `host_not_public`         | The host does not resolve to a public IP address.                                                           |
+
+**The call is allowed but cannot go through right now.** Some of these clear
+on their own.
+
+| `code`               | What it means                                                                          |
+| -------------------- | -------------------------------------------------------------------------------------- |
+| `cap_exceeded`       | A cap has been reached. Try again later.                                               |
+| `rate_limited`       | Over Brass's own rate limit. Slow down.                                                |
+| `calls_paused`       | Whoever owns the account being spent set its cap to zero. Waiting will not clear it.   |
+| `vault_unavailable`  | Brass could not read the stored key just now. Nothing is wrong with it; make the same call again. |
+
+**Brass could not return the response.**
+
+| `code`               | What it means                                                       |
+| -------------------- | --------------------------------------------------------------------- |
+| `response_too_large` | The service returned more than 5 MB.                                  |
+| `response_not_text`  | The service returned bytes rather than text. Call an endpoint that returns a URL or base64. |
+| `response_unreadable`| Brass could not read the service's response.                          |
+| `response_redirected`| The service answered with a redirect. The body carries its `location`. |
+| `service_timeout`    | The service did not answer in time.                                   |
+| `service_unreachable`| Brass could not reach the service.                                    |
+
+**The app is not the one that may call.** These are about your app's standing
+rather than the credential.
+
+| `code`               | What it means                                                       |
+| -------------------- | --------------------------------------------------------------------- |
+| `app_not_installed`  | The organization has not installed your app. `requestMissingCredentials: true` raises the install dialog; otherwise the call returns `403`. |
+| `no_acting_app`      | The caller is not acting as an app. |
+
+A call made before the app has an organization returns `409 destination_required`.
+
+## Asking for a missing credential
+
+`Brass.listServices()` returns each declared host, with `ready: true` where
+Brass has a credential for it. It shows no dialog, so you can call it while
+the page loads. It returns `null` while the app is acting nowhere: nobody is
+signed in, the app has no organization, or it is running in one that has not
+installed it.
+
+Each entry also carries `connectable`, which says whether the dialog has
+anything for the person on the page to do at that host. Together the two are
+the whole branch:
+
+```js
+const services = await Brass.listServices();
+const ai = services?.find((s) => s.host === 'api.anthropic.com');
+if (ai?.ready) showSummariseButton();
+else if (ai?.connectable) showConnectCard();
+else showUnavailableCard();
+```
+
+`Brass.connectService(host)` opens the dialog and resolves true once that
+host works. Whoever can supply the credential does it there; anyone else is
+told who to ask. Put it on a button, so the user is asked when they reach for
+the feature:
+
+```js
+if (await Brass.connectService('api.anthropic.com')) showSummariseButton();
+```
+
+Passing `requestMissingCredentials: true` to `callService` opens the same
+dialog from the call, which then goes through once the user answers. It covers
+every refusal the person using your app can answer: `credential_required`, plus
+`credential_rejected` and `credential_scheme_unusable` when the account that
+failed is one they own.
+
+A host still waiting for the key you enter as its author
+(`app_credential_not_set`, `app_credential_incomplete`) is yours to settle on
+the app's own settings page, so the call returns that refusal for you to
+handle:
+
+```js
+const res = await Brass.callService(host, path, { requestMissingCredentials: true });
+```
+
+## Who supplies the credential
+
+You choose on your app's settings page whether a host runs on a key of yours
+or on an account whoever runs your app connects, and they can change that
+under you. A host you have just declared starts on a key of yours, so
+`connectable` is false there until you change it. Either way your call is the
+same one: you name a host, and Brass attaches whichever credential is in
+force.
+
+Your app reads `connectable` rather than the supplier, because that is the
+split it can act on. Where it is true, the person using your app can
+settle it, so a Connect button leads somewhere; where it is false, the host is
+waiting on you, so there is nothing to raise. Leave the wording about who to
+ask to the dialog, which knows both the supplier and who is reading, where
+your app is told neither.
+
+## Values the app reads
+
+Your app sometimes has to include a value in the request it sends, such as
+an account id. Mark that field `readable` in the manifest and Brass returns
+it to your app with the service.
+
+Brass collects the value when somebody connects an account, and offers your app
+only the accounts carrying it, so it is there whenever a call reaches your code.
+
+The field's name is the key your app reads the value back under.
+
+```json
+{
+  "services": [
+    {
+      "host": "api.cloudflare.com",
+      "headers": { "authorization": "Bearer {token}" },
+      "fields": [{ "name": "account_id", "readable": true, "label": "Account ID" }]
+    }
+  ]
+}
+```
+
+```js
+const services = await Brass.listServices();
+const cf = services?.find((s) => s.host === 'api.cloudflare.com');
+const account = cf?.values?.account_id;
+if (cf?.ready && account) {
+  const res = await Brass.callService(
+    'api.cloudflare.com',
+    `client/v4/accounts/${account}/tokens/verify`,
+    { method: 'GET' },
+  );
+}
+```
+
+`values` is present on a `ready` service.
+
+## Providing credential setup instructions
+
+Brass shows your setup instructions on the form that collects a credential,
+and you are strongly encouraged to provide them. Without them the form shows
+your field labels alone, and the person filling it in has to work out what
+to create at the vendor and where.
+
+Declare a `setup` beside the host:
+
+```json
+{
+  "services": [
+    {
+      "host": "api.example.com",
+      "headers": { "authorization": "Bearer {secret}" },
+      "setup": {
+        "credentialName": "API key",
+        "consoleUrl": "https://example.com/settings/keys",
+        "docsUrl": "https://example.com/docs/api",
+        "steps": [
+          "Open Settings, then API keys.",
+          "Create a key with read and write access.",
+          "Copy the key before closing the dialog."
+        ]
+      }
+    }
+  ]
+}
+```
+
+- **`credentialName`** is what the vendor calls the credential, so it
+  matches what they see there.
+- **`consoleUrl`** is the page where they create it. Link to that page
+  rather than the vendor's home page.
+- **`docsUrl`** is where the vendor documents this method.
+- **`steps`** are step-by-step instructions for creating the credential.
+  Up to six, shown in order.
+
+## A service split across addresses
+
+A wildcard host (`*.myshopify.com`) covers every address under it;
+[`app-manifest.md`](./app-manifest.md) covers declaring one. Which `host` you
+pass to `callService` depends on `credentialPerHost`.
+
+Without it, one credential covers every address under the suffix, and
+`listServices` returns a single entry under the declared name. Match on the
+wildcard, not on the address you are about to call.
+
+With it, each secret is entered against a specific address, and
+`listServices` returns one entry per connected address, each with
+`declared_as: '*.myshopify.com'`. Pass the `host` from one of those entries.
+An address you build from a shop name points at a shop nobody has connected.
+Before any address is connected there is one entry for the wildcard itself,
+and `Brass.connectService` takes that `host`:
+
+```js
+const shops = ((await Brass.listServices()) ?? []).filter(
+  (s) => s.declared_as === '*.myshopify.com',
+);
+const connected = shops.filter((s) => s.ready);
+if (connected.length === 0) await Brass.connectService('*.myshopify.com');
+```

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.3.0",
+  "version": "0.4.1",
   "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",