@brass-build/client 0.3.0 → 0.4.1

package/dist/wasm-ready-gate.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Build a function that runs `inits` once and hands every caller the same
+ * result.
+ *
+ * A rejection is NOT retained. Each init is a multi-megabyte fetch over
+ * whatever connection the reader has, and a page navigating away mid-download
+ * aborts it, so a retained rejection would answer every later call with a
+ * failure the network has long since recovered from. Dropping it makes the
+ * next call start over, which is what a reader who opens a document a minute
+ * later needs.
+ */
+export declare function createReadyGate(inits: readonly (() => Promise<unknown>)[]): () => Promise<void>;
+//# sourceMappingURL=wasm-ready-gate.d.ts.map

package/dist/wasm-ready-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wasm-ready-gate.d.ts","sourceRoot":"","sources":["../src/wasm-ready-gate.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,SAAS,CAAC,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC,EAAE,GACzC,MAAM,OAAO,CAAC,IAAI,CAAC,CAWrB"}

package/dist/wasm-ready-gate.js

@@ -0,0 +1,28 @@
+// The once-only gate the browser runtime half readies its WASM behind, kept
+// separate from it so it can be exercised without a real engine: the half
+// itself names a WASM-shipping dependency, which pins it to an environment
+// that can load one.
+/**
+ * Build a function that runs `inits` once and hands every caller the same
+ * result.
+ *
+ * A rejection is NOT retained. Each init is a multi-megabyte fetch over
+ * whatever connection the reader has, and a page navigating away mid-download
+ * aborts it, so a retained rejection would answer every later call with a
+ * failure the network has long since recovered from. Dropping it makes the
+ * next call start over, which is what a reader who opens a document a minute
+ * later needs.
+ */
+export function createReadyGate(inits) {
+    let readying = null;
+    return () => {
+        readying ??= Promise.all(inits.map((init) => init()))
+            .then(() => undefined)
+            .catch((err) => {
+            readying = null;
+            throw err;
+        });
+        return readying;
+    };
+}
+//# sourceMappingURL=wasm-ready-gate.js.map

package/dist/wasm-ready-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wasm-ready-gate.js","sourceRoot":"","sources":["../src/wasm-ready-gate.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,0EAA0E;AAC1E,2EAA2E;AAC3E,qBAAqB;AAErB;;;;;;;;;;GAUG;AACH,MAAM,UAAU,eAAe,CAC7B,KAA0C;IAE1C,IAAI,QAAQ,GAAyB,IAAI,CAAC;IAC1C,OAAO,GAAG,EAAE;QACV,QAAQ,KAAK,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC;aAClD,IAAI,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC;aACrB,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;YACtB,QAAQ,GAAG,IAAI,CAAC;YAChB,MAAM,GAAG,CAAC;QACZ,CAAC,CAAC,CAAC;QACL,OAAO,QAAQ,CAAC;IAClB,CAAC,CAAC;AACJ,CAAC"}

package/dist/wasm-runtime.browser.d.ts

@@ -0,0 +1,11 @@
+export * from 'loro-crdt/web';
+/**
+ * Resolve once every WASM module this package needs is ready to run.
+ *
+ * `Brass.init()` starts it and every path that constructs a document awaits
+ * it, so an app that follows the documented boot never calls it. It is
+ * idempotent and concurrent-safe for the paths that construct documents
+ * without one (a test, an in-repo tool).
+ */
+export declare const ensureWasmReady: () => Promise<void>;
+//# sourceMappingURL=wasm-runtime.browser.d.ts.map

package/dist/wasm-runtime.browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wasm-runtime.browser.d.ts","sourceRoot":"","sources":["../src/wasm-runtime.browser.ts"],"names":[],"mappings":"AA8BA,cAAc,eAAe,CAAC;AAS9B;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,EAAE,MAAM,OAAO,CAAC,IAAI,CAA0B,CAAC"}

package/dist/wasm-runtime.browser.js

@@ -0,0 +1,44 @@
+// The browser half of the WASM runtime seam: the ONE module in this package
+// that names a WASM-shipping dependency, and the only place a new one is
+// added. Everything else imports `./wasm-runtime.js`, whose node half this
+// one replaces in a browser build, so no other file in the SDK (and no line of
+// an app's own config) names a WASM dep or its loader.
+//
+// Each entry is loaded through its package's WEB build, which readies its
+// module asynchronously behind an explicit init and locates its bytes with
+// `new URL(..., import.meta.url)`. That combination is what makes the whole
+// package build with no bundler plugins: every major bundler rewrites that URL
+// into an emitted asset on its own, and nothing here emits a top-level await,
+// so no build target has to accept one.
+//
+// The alternative each package offers by default is worse in a way nothing
+// reports. A default browser entry fetches its module with a SYNCHRONOUS
+// XMLHttpRequest while it evaluates, so an app freezes its main thread for the
+// whole download before it paints, whether or not anyone opens a document, and
+// the freeze grows with the reader's latency rather than with the app. That is
+// what a browser build resolves to unless something selects otherwise, it
+// builds clean, and the only tell is the chunk count.
+// The init comes from the deeper path because the package's web entry
+// re-exports its module with `export *`, which does not carry a default, so
+// the entry's types do not declare the init its JavaScript exports. The two
+// specifiers resolve to the same module instance (the entry imports this
+// file), so readying through one readies the classes taken from the other.
+import initEngine from 'loro-crdt/web/loro_wasm.js';
+import { createReadyGate } from './wasm-ready-gate.js';
+export * from 'loro-crdt/web';
+// Every WASM module this package needs ready before it runs, as the init each
+// one exports. Add an entry rather than replacing the list: a consumer with
+// two installed during a migration window needs both readied, and the gate
+// below is what every caller already awaits, so a new entry costs no new call
+// anywhere.
+const INITS = [initEngine];
+/**
+ * Resolve once every WASM module this package needs is ready to run.
+ *
+ * `Brass.init()` starts it and every path that constructs a document awaits
+ * it, so an app that follows the documented boot never calls it. It is
+ * idempotent and concurrent-safe for the paths that construct documents
+ * without one (a test, an in-repo tool).
+ */
+export const ensureWasmReady = createReadyGate(INITS);
+//# sourceMappingURL=wasm-runtime.browser.js.map

package/dist/wasm-runtime.browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wasm-runtime.browser.js","sourceRoot":"","sources":["../src/wasm-runtime.browser.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,yEAAyE;AACzE,2EAA2E;AAC3E,+EAA+E;AAC/E,uDAAuD;AACvD,EAAE;AACF,0EAA0E;AAC1E,2EAA2E;AAC3E,4EAA4E;AAC5E,+EAA+E;AAC/E,8EAA8E;AAC9E,wCAAwC;AACxC,EAAE;AACF,2EAA2E;AAC3E,yEAAyE;AACzE,+EAA+E;AAC/E,+EAA+E;AAC/E,+EAA+E;AAC/E,0EAA0E;AAC1E,sDAAsD;AAEtD,sEAAsE;AACtE,4EAA4E;AAC5E,4EAA4E;AAC5E,yEAAyE;AACzE,2EAA2E;AAC3E,OAAO,UAAU,MAAM,4BAA4B,CAAC;AAEpD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAEvD,cAAc,eAAe,CAAC;AAE9B,8EAA8E;AAC9E,4EAA4E;AAC5E,2EAA2E;AAC3E,8EAA8E;AAC9E,YAAY;AACZ,MAAM,KAAK,GAAwC,CAAC,UAAU,CAAC,CAAC;AAEhE;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,eAAe,GAAwB,eAAe,CAAC,KAAK,CAAC,CAAC"}

package/dist/wasm-runtime.d.ts

@@ -0,0 +1,6 @@
+export * from 'loro-crdt';
+/** Resolve once every WASM module this package needs is ready to run. Already
+ *  true here: a node build readies its module during import, so the callers
+ *  that await it on the browser half wait for nothing on this one. */
+export declare function ensureWasmReady(): Promise<void>;
+//# sourceMappingURL=wasm-runtime.d.ts.map

package/dist/wasm-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wasm-runtime.d.ts","sourceRoot":"","sources":["../src/wasm-runtime.ts"],"names":[],"mappings":"AAaA,cAAc,WAAW,CAAC;AAE1B;;sEAEsE;AACtE,wBAAgB,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC,CAE/C"}

package/dist/wasm-runtime.js

@@ -0,0 +1,20 @@
+// The node half of the WASM runtime seam. Node resolves each WASM-shipping
+// dependency to its own node build, which readies its module as it is
+// imported, so there is nothing to await and `ensureWasmReady` is the same
+// call answering immediately.
+//
+// This is the half every importer names, so a build that applies no
+// substitution at all (tsc, a node-targeting esbuild, the test runner) is
+// already correct, and the browser half's `import.meta.url` asset resolution
+// never reaches a bundler targeting node. `package.json`'s `browser` map
+// swaps in the browser half for a bundler building this package for one, and
+// `ensureWasmReady` exists so a caller awaits readiness the same way whichever
+// half it got.
+export * from 'loro-crdt';
+/** Resolve once every WASM module this package needs is ready to run. Already
+ *  true here: a node build readies its module during import, so the callers
+ *  that await it on the browser half wait for nothing on this one. */
+export function ensureWasmReady() {
+    return Promise.resolve();
+}
+//# sourceMappingURL=wasm-runtime.js.map

package/dist/wasm-runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wasm-runtime.js","sourceRoot":"","sources":["../src/wasm-runtime.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,sEAAsE;AACtE,2EAA2E;AAC3E,8BAA8B;AAC9B,EAAE;AACF,oEAAoE;AACpE,0EAA0E;AAC1E,6EAA6E;AAC7E,yEAAyE;AACzE,6EAA6E;AAC7E,+EAA+E;AAC/E,eAAe;AAEf,cAAc,WAAW,CAAC;AAE1B;;sEAEsE;AACtE,MAAM,UAAU,eAAe;IAC7B,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;AAC3B,CAAC"}

package/docs/app-manifest.md

@@ -8,9 +8,14 @@ a download button on the documents your app writes out.
 ## Where it goes
 
 Put `brass-app.json` in a `/.well-known/` directory at your bundle
-root, next to `index.html`. Some bundlers skip dot-directories when
-they copy static assets, so confirm the manifest is in your `dist/`
-directory after you build.
+root, next to `index.html`. In Vite, `public/.well-known/brass-app.json`
+builds to `dist/.well-known/brass-app.json`. Check it is there after you
+build: a bundler that skips dot-directories drops it silently.
+
+`brass publish` reads that same path out of the directory it publishes
+(`<dir>/.well-known/brass-app.json`), falling back to `brass-app.json` in
+the working directory, so it takes your `name` and `client_token` from the
+manifest you already ship.
 
 The platform re-reads the manifest after each deploy, so publishing
 your bundle is what registers it. If Brass hosts your bundle
@@ -32,7 +37,11 @@ no access, so you declare them yourself.
   "creates": "tracker",
   "exports": { "content_type": "text/csv", "file_extension": ".csv" },
   "icon": "/icon.svg",
-  "schema": { "...": "see schemas.md" }
+  "services": [{ "host": "api.anthropic.com", "headers": { "x-api-key": "{secret}" } }],
+  "schema": {
+    "family": "tracker",
+    "streams": { "default": { "type": "object", "required": ["rows"] } }
+  }
 }
 ```
 
@@ -59,6 +68,327 @@ Every field is optional, so ship only the ones your app uses.
   (`"icon": "/icon.svg"`, resolved against your origin), or give an
   absolute `https://` URL. An emoji (`"icon": "🏗️"`) also renders,
   though apps in one domain tend to land on the same few.
+- **`services`** names the third-party APIs your app calls. Brass proxies
+  each call, using either your credentials or the user's. See
+  [Services](#services-for-calling-third-party-apis) below.
 - **`schema`** declares the record shape your app works with, whether
-  you invented it or adopted an existing one. See
+  you designed it or adopted an existing one. See
   [`schemas.md`](./schemas.md).
+
+## Services, for calling third-party APIs
+
+`services` names the third-party APIs that your app calls. Each service
+declaration includes a host name and an authentication method. Brass then
+proxies each call, using either your credentials or the user's, so no secret
+is exposed in the client.
+
+```json
+{
+  "services": [
+    { "host": "api.anthropic.com", "headers": { "x-api-key": "{secret}" } },
+    { "host": "api.example.com", "headers": { "authorization": "Bearer {secret}" } }
+  ]
+}
+```
+
+[`services.md`](./services.md) covers the calling side: what each refusal code
+means, how to prompt for a missing credential, which host to pass for a
+service split across addresses, and how to provide setup instructions for
+the people who supply your credentials.
+
+### Specifying a host
+
+`host` is the host name your app passes to `Brass.callService`. It must be a
+public https host: no scheme, no port, no path.
+
+Use a wildcard where a service is split across subdomains (`*.example.com`).
+Your app can then call any address under that suffix.
+
+Set `credentialPerHost` to give each address its own credential. Without it,
+one credential covers every address under the wildcard. With it, the user
+enters a separate credential for each address, which is what a vendor that
+hosts a separate address per account requires.
+
+```json
+{
+  "services": [
+    { "host": "*.example.com", "headers": { "authorization": "Bearer {secret}" } },
+    {
+      "host": "*.myshopify.com",
+      "credentialPerHost": true,
+      "headers": { "x-shopify-access-token": "{secret}" }
+    }
+  ]
+}
+```
+
+`credentialPerHost` is required for a suffix that anyone can register a name
+under. One credential covering `*.herokuapp.com` or `*.pages.dev` could be
+used at an address a stranger created, so Brass rejects that declaration and
+reports it on your next publish. The same rule limits a shared wildcard:
+`*.amazonaws.com` can call `sts.amazonaws.com` and
+`lambda.us-west-2.amazonaws.com`, but not `any-bucket.s3.amazonaws.com`,
+because that name belongs to whoever created the bucket.
+
+### Credential fields
+
+A field is one value the person connecting a credential is asked for. Each one
+is a box on the form they fill in.
+
+Some authentication methods declare their own fields, and each method below
+lists the ones it declares. Declare any others in `fields`:
+
+| Property | |
+| --- | --- |
+| `name` | Required. Identifies the field. |
+| `secret` | `true` by default. Brass encrypts the value and shows only its last few characters afterwards. `false` stores it in the clear and shows it in full. |
+| `label` | What the form calls the field. Use the vendor's own word for it, since that is what the person is reading from. Defaults to the name. |
+| `readable` | `false` by default. `true` returns the value to your app with the service, for a value your app has to include in the request. Such a field is not secret, so `secret` defaults to `false` for it and declaring both is refused. See [Values the app reads](./services.md#values-the-app-reads). |
+
+```json
+{
+  "services": [
+    {
+      "host": "api.example.com",
+      "headers": { "x-app": "{app_id}", "x-region": "{region}", "x-key": "{key}" },
+      "fields": [
+        { "name": "app_id", "secret": false, "label": "Application ID" },
+        { "name": "region", "secret": false, "label": "Region" }
+      ]
+    }
+  ]
+}
+```
+
+An entry naming a field the method already declared changes that field's
+properties instead of adding a new one, which is how you relabel one. A field
+the method declares secret stays secret.
+
+### Choosing an authentication method
+
+A credential sent in a plain header needs no `auth` block. Every other method
+is an `auth` block naming its `type`.
+
+#### `headers`, for a credential sent in a header
+
+Each header value is a template, and Brass substitutes a field into each
+placeholder you write. The fields are the names in those placeholders; this
+method declares none of its own.
+
+```json
+{
+  "services": [
+    {
+      "host": "production.plaid.com",
+      "headers": {
+        "plaid-client-id": "{client_id}",
+        "plaid-secret": "{secret}"
+      },
+      "fields": [{ "name": "client_id", "secret": false, "label": "Client ID" }]
+    }
+  ]
+}
+```
+
+#### `basic`, for HTTP basic auth
+
+Brass sends `authorization: Basic base64(username:password)`.
+
+The fields are `username` and `password`.
+
+```json
+{ "host": "api.twilio.com", "auth": { "type": "basic" } }
+```
+
+Some services take a fixed word as the user half rather than an account name,
+such as `api` for Mailgun. Set it as `username` on the `auth` block and the
+person is asked for the password alone.
+
+```json
+{ "host": "api.mailgun.net", "auth": { "type": "basic", "username": "api" } }
+```
+
+#### `query`, for a credential sent as a query parameter
+
+Brass appends these parameters to the query your app wrote, substituting a
+field into each placeholder you write. The fields are the names in those
+placeholders; this method declares none of its own.
+
+```json
+{
+  "host": "maps.example.com",
+  "auth": { "type": "query", "params": { "key": "{secret}" } }
+}
+```
+
+#### `aws_sigv4`, for a signed AWS request
+
+Brass signs the request, so the secret never leaves Brass.
+
+The fields are `access_key_id` and `secret_access_key`.
+
+```json
+{ "host": "*.amazonaws.com", "auth": { "type": "aws_sigv4" } }
+```
+
+AWS puts the region and the service in most of its host names, and Brass signs
+for whichever the address names. Set `region` and `service` for addresses that
+name neither, such as a bucket or an account id before the service name. Brass
+uses them only where the host name does not say, so one credential still
+covers a whole suffix.
+
+#### `oauth2_client_credentials`, for a token from your client credentials
+
+You register a client with the vendor. Brass posts the client id and secret to
+the token endpoint, receives a short-lived token, and sends that token with
+each call. Set `clientAuth` to `body` or `basic` to say where the id and
+secret go; vendors differ, and many accept only one.
+
+The fields are `client_id` and `client_secret`.
+
+```json
+{
+  "host": "api.xero.com",
+  "auth": {
+    "type": "oauth2_client_credentials",
+    "tokenHost": "identity.xero.com",
+    "tokenPath": "/connect/token",
+    "clientAuth": "basic",
+    "scope": "accounting.transactions"
+  }
+}
+```
+
+#### `jwt_bearer`, for a token from a signed assertion
+
+Brass signs a short-lived assertion with a private key, so the key never
+leaves Brass. Set `audience` to the string the vendor requires in the
+assertion. Vendors are strict about this value, so declare it rather than
+letting Brass build one.
+
+The fields are `issuer` and `private_key`.
+
+```json
+{
+  "host": "oauth2.googleapis.com",
+  "auth": {
+    "type": "jwt_bearer",
+    "tokenPath": "/token",
+    "audience": "https://oauth2.googleapis.com/token",
+    "algorithm": "RS256"
+  }
+}
+```
+
+Both token methods take two more fields:
+
+- `tokenPath` names the path on the credential's own host. Set `tokenUrl`
+  instead to name the whole address. `tokenHost` defaults to the credential's
+  own host.
+  Set it to post the exchange to a different host. Brass allows this for a
+  credential you supply, and rejects it for one the user supplies, unless the
+  user chose the method. Otherwise your manifest would decide where their
+  secret is sent.
+- `tokenBody` sets how the exchange is posted: `form` (the default) or `json`.
+  Set `json` when your vendor's token endpoint takes a JSON body.
+
+#### `oauth2_authorization_code`, for a per-user approval at the vendor
+
+Each user approves at the vendor, and Brass stores the result for that user
+alone. Your app then reaches only what that user can reach. Use this at a host
+whose permissions differ per user, where one shared account would reach
+everything.
+
+The fields are `client_id` and `client_secret`, which are your registered
+OAuth client rather than anything the approving user enters.
+
+```json
+{
+  "host": "api.example.com",
+  "auth": {
+    "type": "oauth2_authorization_code",
+    "authorizationUrl": "https://app.example.com/oauth/authorize",
+    "tokenUrl": "https://api.example.com/oauth/token",
+    "clientAuth": "basic"
+  }
+}
+```
+
+- `clientAuth` sets where your client id and secret go on the exchange: `body`
+  or `basic`.
+- `authorizeParams` adds parameters the vendor requires on the approval
+  request. Many vendors issue no refresh token without one, and the connection
+  then stops working when the first token expires. Google requires
+  `{"access_type": "offline", "prompt": "consent"}`. Read your vendor's
+  documentation on refresh tokens before you ship this.
+- `pkce` defaults to `true`. Set `false` for a vendor that rejects the
+  challenge.
+
+You supply an OAuth client registered with the vendor, entering its id and
+secret like any other credential. Register
+`https://brass.build/services/oauth/callback` as the redirect URL. That one
+address serves every service, and there is nothing to configure in Brass.
+
+Calls return `409` with `credential_required` until the user approves.
+[`services.md`](./services.md) covers prompting them.
+
+#### An OpenAPI security scheme
+
+`auth` also accepts an OpenAPI `securityScheme`, so you can paste what your
+vendor's spec already says. Brass reads it as the equivalent method above:
+`apiKey` and `http` `bearer` take a single `secret` field, sent in the place
+the spec names; `http` `basic` reads as `basic`; and the `clientCredentials`
+and `authorizationCode` flows read as their OAuth methods, with those methods'
+fields.
+
+```json
+{ "host": "api.example.com", "auth": { "type": "apiKey", "in": "header", "name": "X-API-Key" } }
+```
+
+The `authorizationCode` flow is the same grant as `oauth2_authorization_code`
+above. A spec carries no `clientAuth`, `authorizeParams` or `pkce`, so set
+those alongside `flows`:
+
+```json
+{
+  "host": "api.example.com",
+  "auth": {
+    "type": "oauth2",
+    "flows": {
+      "authorizationCode": {
+        "authorizationUrl": "https://app.example.com/oauth/authorize",
+        "tokenUrl": "https://api.example.com/oauth/token",
+        "scopes": { "contacts.read": "Read contacts" }
+      }
+    }
+  }
+}
+```
+
+#### More than one method at one host
+
+Set `auth` to an array where a host accepts more than one kind of credential.
+A user with an API key can then use it at a host you declared for approval:
+
+```json
+{
+  "host": "api.example.com",
+  "auth": [
+    { "type": "oauth2", "flows": { "authorizationCode": { "...": "..." } } },
+    { "type": "apiKey", "in": "header", "name": "X-API-Key" }
+  ]
+}
+```
+
+Brass uses your first entry by default. The user can choose another when they
+enter their credential, and Brass then asks for whatever that method needs.
+
+Set `authorOnly` on an entry to keep it out of the user's choices. Use it for
+a credential only you can obtain, such as a vendor's internal-integration
+secret, which authenticates as your account rather than theirs.
+
+A host often accepts several kinds of credential. A vendor that issues both
+personal tokens and OAuth clients takes either, and they are different
+credentials at one address. Declare the method your app is built around. A
+user who pastes an OAuth client pair where you declared a bearer token is
+asked for the client id as well, and your app keeps calling one host.

package/docs/custom-chrome.md

@@ -130,6 +130,9 @@ hook for keyboard shortcuts).
 Reading the list and calling `run()` wires all of it. You render and
 invoke, and the SDK owns the behavior:
 
+- **`new`** creates a document and binds it, asking the platform where
+  to put it (`Brass.session.create()` under the hood).
+- **`open`** opens the hosted picker and binds what the user chooses.
 - **`history`** drives version preview end to end. During a preview
   `doc.readOnly` is `true`, so gate your own edit controls on it;
   returning to live is the chrome's job (the `mountVersionPreview`

package/docs/presence.md

@@ -67,9 +67,21 @@ interface PresenceState {
   // The entity ids the user has selected. Use to highlight remote
   // selections so collaborators see what each other is working on.
   selection?: string[];
+  // Where the user's caret sits in a text container. `key` names the
+  // container (`doc.text(key)`), and both offsets count UTF-16 code
+  // units into its value: `anchor` where the selection began, `head`
+  // where it is now, equal for a plain caret. Use it to draw remote
+  // carets in prose, the way `selection` highlights picked entities.
+  textCaret?: { key: string; anchor: number; head: number };
 }
 ```
 
+A caret belongs in `state` rather than in `ext` for the same reason a
+selection does: a document of prose is often open in more than one app,
+and a reader wants to see where the other person is working whichever
+app they are each in. Publish it on every selection change, which the
+10 Hz debounce already paces.
+
 App-specific state (the current tool, a chat bubble, a typing
 indicator) goes under `ext` instead so it stays namespaced and out of
 the cross-app conventions. The `ext` block is otherwise free-form: