@brass-build/client 0.1.0

package/docs/presence.md

@@ -0,0 +1,129 @@
+# Presence (live cursors, who's-here)
+
+`doc.presence` is the ephemeral "who is here right now" layer over an
+open document: the roster of other live participants plus a
+lightweight per-user `state` (cursor / camera / selection) and an
+app-namespaced `ext` blob. It is non-null on any open
+writable `Document`, and `null` otherwise. Presence is fully
+ephemeral: nothing survives a disconnect.
+
+```ts
+import type { PresenceParticipant } from '@brass-build/client';
+
+const doc = await Brass.openDocumentById('doc_abc');
+
+// Publish your own cursor. `set` is a partial shallow-merge and is
+// throttled to ~10 Hz internally, so call it as often as you like
+// (e.g. on every pointermove).
+doc.presence?.set({ state: { cursor: { x, y, z } } });
+doc.presence?.set({ ext: { myApp: { tool: 'select' } } });
+
+// React to everyone else. `roster` is the other participants; each
+// carries a server-stamped `displayName` + `color` (CSS-ready string,
+// e.g. `'#a4c8ff'`, assign directly to `style.background` or pass to
+// canvas APIs without parsing) and their last `state`. Interpolate
+// between updates in your render loop.
+//
+// `on('change', ...)` fires once on subscribe with the current roster
+// when peers are already present (you opened a document others are
+// already in), then on every join, leave, or `state` / `ext` update.
+// It does not fire on subscribe when you are the only one here, and an
+// empty roster is the default paint anyway, so one listener covers both
+// the initial render and every change.
+const renderRoster = (roster: PresenceParticipant[]) => {
+  for (const p of roster) renderAvatar(p.connectionId, p.color, p.state);
+};
+const stop = doc.presence?.on('change', renderRoster);
+
+// `doc.close()` tears presence down for you; call `leave()` directly
+// only if you want to drop presence while keeping the doc open.
+doc.presence?.leave();
+```
+
+## Coordinate convention
+
+The `state` block uses a fixed coordinate convention so participants
+stay legible across different apps over the same document: **meters,
+right-handed, Z-up, document world space**. Map your engine's
+coordinates into it before `set` and back out when rendering remote
+participants. The `roster` is keyed on `connectionId`, so one user
+in two tabs shows as two participants.
+
+## Reserved `state` sub-keys
+
+App-set but reserved-by-convention so two apps subscribed to the
+same document agree on what each key means. Pick from this set in
+preference to inventing new ones:
+
+```ts
+interface PresenceState {
+  // The user's primary pointer position in the document's world
+  // space. Use for "this is where my cursor is right now" in a 2D
+  // or 3D editor. Omit if your app has no cursor concept.
+  cursor?: { x: number; y: number; z: number };
+  // Where the user is looking from in 3D. Use to render a
+  // "Bob is viewing the south facade" gizmo at the camera's
+  // position. Omit in 2D apps; use `cursor` instead.
+  camera?: {
+    position: { x: number; y: number; z: number };
+    target?: { x: number; y: number; z: number };
+  };
+  // The entity ids the user has selected. Use to highlight remote
+  // selections so collaborators see what each other is working on.
+  selection?: string[];
+}
+```
+
+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:
+`ext.myApp = { tool: 'select', chatBubble: 'hi' }`.
+
+## Types
+
+`doc.presence` is typed `PresenceClient | null`; each `roster` entry
+is a `PresenceParticipant` with
+`{ connectionId, sub, displayName, avatarUrl, color, joinedAt, lastSeen,
+state, ext }`. `displayName`, `avatarUrl`, and `color` are always
+present as strings; `avatarUrl` is `''` when the user has no picture.
+Both types are exported from `@brass-build/client` (alongside
+`PresenceSetInput` and `PresenceChangeListener`) so you can annotate
+handlers and roster state without source-reading the SDK.
+
+## Hand-rolling the header roster (custom shell)
+
+`Brass.mountToolbar` and `Brass.mountPresenceRoster` render the
+who's-here roster of coloured initials for you, so prefer those. When
+you build a fully custom shell and want the roster in your own element,
+render it from `doc.presence.roster`, a small list of coloured
+initials that renders the same way for every app:
+
+```ts
+import type { PresenceParticipant } from '@brass-build/client';
+
+const renderRoster = (roster: readonly PresenceParticipant[]): void => {
+  const el = document.getElementById('roster')!;
+  el.replaceChildren(...roster.map((p) => {
+    const pip = document.createElement('span');
+    pip.className = 'pip';
+    pip.style.background = p.color;
+    pip.title = p.displayName ?? p.sub ?? '';
+    if (p.avatarUrl) {
+      const img = document.createElement('img');
+      img.src = p.avatarUrl;
+      img.alt = '';
+      img.style.cssText = 'width:100%;height:100%;object-fit:cover;border-radius:50%';
+      pip.appendChild(img);
+    } else {
+      pip.textContent = (p.displayName ?? p.sub ?? '?').slice(0, 1).toUpperCase();
+    }
+    return pip;
+  }));
+};
+```
+
+Drive it from the same `change` subscription as the in-surface remote
+cursors (see the README's "Presence" section). The listener fires on
+subscribe whenever peers are already present, so it paints the initial
+roster for you; render `doc.presence?.roster ?? []` yourself only if you
+want the empty state on screen before anyone joins.

package/docs/schemas.md

@@ -0,0 +1,135 @@
+# Schemas
+
+A schema declares what your app expects a document to hold. Declaring one
+in your `brass-app.json` routes matching documents to your app, and lets
+any developer who can open one of those documents build against the same
+shape.
+
+## Declaring a schema
+
+A schema is a `family` and a `streams` map. Each entry is a plain
+[JSON Schema](https://json-schema.org) (draft 2020-12) describing that
+stream's root collections and records.
+
+- **`family`** is a short word naming what the artifact is: the domain or
+  standard it projects. Use the word the standards world already uses when
+  there is one, and the domain's own word when there is not, so a CNC
+  toolpath is `gcode` and a shift schedule is `roster`. It is the identity
+  other apps converge on, so it names the artifact rather than your app or
+  your version: `gcode`, not `acme-cam` and not `gcode-2`. Lowercase
+  `a-z 0-9 . _ -`, up to 64 characters, the same rule a stream name follows,
+  so a namespaced `acme.roster` works and a URL does not. A declaration whose family is missing or not a word is
+  not recorded, and your app's dashboard page says so.
+- **`streams`** maps each stream name your app expects a document to hold
+  to that stream's contract. `default` is the stream a document opens
+  without asking for one, and takes an entry like any other name. Two
+  streams that carry the same shape carry the same body.
+- **A collection of records** is an object whose `additionalProperties`
+  is the record schema, so the keys are record ids. An ordered collection
+  is an array, or an array of keys alongside the map.
+- **Foreign keys** ride as an `x-brass-ref` extension on the referring
+  field, an object with a `to` naming the collection referred to.
+  Standard validators ignore an `x-` keyword.
+- **The `x-brass-` prefix is reserved for Brass.** Give your own extensions
+  their own prefix (`x-acme-`), so a name you choose keeps its meaning when
+  Brass defines a keyword later. A keyword in a pulled body describes the
+  data rather than your app, so keep the body verbatim rather than dropping
+  keywords you do not recognise.
+- **`description`** carries the conventions structure cannot: an
+  ordering, a unit, an invariant. Put it wherever the convention belongs.
+
+Brass never keys on `$id`, and never enforces a schema against a
+document. It validates that each body is well-formed JSON Schema when
+your manifest is ingested, and nothing after that.
+
+To work with documents that already exist, take their schema rather than
+writing your own: open one in the dashboard and use **Download
+brass-app.json**, or run `npx @brass-build/cli schema pull --doc <docId>`.
+Keep it verbatim. Your copy is the contract your code is built against,
+and an approximation reads as a different contract.
+
+## Creating a stream
+
+Streams let one document load in parts, so an app pays for what it opens
+rather than the document's total size. `doc.getOrCreateStream(name)`
+opens the document's stream of that name and makes it when the document
+does not hold it yet; `doc.stream(name)` opens one the document already
+holds and rejects any other name.
+
+```ts
+const stream = await doc.getOrCreateStream(name);
+stream.map('records').mutate((m) => {
+  m[id] = record;
+});
+```
+
+`getOrCreateStream` is idempotent, and concurrent callers converge on one
+stream, so an app reaches for the stream it expects on every open without
+checking first. Only that call writes, so a read-only open reads through
+`doc.stream` and handles the rejection when the document does not hold
+the stream. Names follow the same rule a family does: `a-z 0-9 . _ -`, 1 to
+64 characters, starting with a letter or digit.
+
+A separate stream suits records only some opens need to load, or that an
+exporter should leave out. Name it in `streams` and its shape is
+declared, so any app that expects it reads the same contract. See
+[Streams](./streams.md) for partitioning, undo, and reading a document
+spread across several.
+
+## What an app can open
+
+An app opens a document when they share a family and **everything the app
+requires the document already guarantees.** That is the whole test, and
+it runs per stream, over the streams both sides name.
+
+It is deliberately loose. Your schema does not have to match a document's
+exactly, only ask no more of it, so an app opens documents written
+against shapes it was never built for.
+
+An exporter composes the streams it declares, so an app exporting a
+document writes the parts it knows about and leaves the rest. Two apps
+can export the same document differently, each emitting what it
+understands.
+
+## What breaks compatibility
+
+Because the test is about `required`, that is the only part of a schema
+that can break anything.
+
+- **Removing a required property breaks other apps.** Your documents stop
+  guaranteeing that field, so apps requiring it stop opening them. Your
+  own app keeps working, so you will not see it.
+- **Adding a required property narrows what you can open**, since older
+  documents never promised it.
+- **Adding an optional property is safe** in both directions.
+
+Two habits follow. Keep records open (no `additionalProperties: false`)
+so your app preserves fields it does not recognise rather than dropping
+them on write, and handle a missing field gracefully, since Brass
+enforces nothing and a writer may not have written it.
+
+## Adding a required property anyway
+
+Declare a `writes` map beside `streams` when the two sides differ. It
+takes the same stream names and the same bodies, and it is what your app
+guarantees when it writes, where `streams` is what it expects to read.
+
+```json
+{
+  "family": "building",
+  "streams": { "default": { "type": "object", "required": ["walls"] } },
+  "writes": {
+    "default": { "type": "object", "required": ["walls", "site"] }
+  }
+}
+```
+
+That app opens every document guaranteeing `walls`, including ones
+written before `site` existed, and every document it saves guarantees
+`site` as well. An app still on the old shape reads the result, because
+the document now guarantees more than that app expects. Leave `writes`
+out and one contract covers both sides, which is what most apps want.
+
+The two directions are the whole rule: an app opens a document that
+guarantees at least what the app expects, and writes one whose guarantees
+its own writes cover.

package/docs/streams.md

@@ -0,0 +1,248 @@
+# Streams: partitioning a document for lazy loading
+
+A document is a container of **streams**: named units of document
+state that load independently. Opening a document costs only the
+streams your app touches: snapshot download, CRDT import, and memory
+all scale with what you use, not with the document's total size. The
+motivating shape is a multi-discipline design: architectural,
+plumbing, HVAC, and structural as four streams of one document, where
+a plumbing tool opens one of them and pays a quarter of the cost.
+Every stream is collaborative CRDT state.
+
+Every document has a stream named **`default`**, and an open that names
+no stream opens that one, so the doc-level handles (`doc.map(...)`,
+`doc.orderedMap(...)`) read it. An unpartitioned document is just a
+document whose content lives entirely there: nothing about streams needs
+to be known or paid for until you partition. Name another stream on the
+open (below) and the doc-level handles read that one instead.
+
+## Opening and editing a stream
+
+```ts
+const stream = await doc.stream(name);
+const records = stream.orderedMap('instances', 'instance_order');
+records.mutate((m) => {
+  m[id] = { type, params };
+});
+records.subscribe((change) => render(change));
+```
+
+`doc.stream(name)` resolves once per name: the first call downloads the
+stream's snapshot and subscribes it live, and repeat calls return the same
+open. It only reads, so a name the document does not hold rejects rather
+than being created. `doc.getOrCreateStream(name)` is the call that makes
+one. It is idempotent and concurrent callers converge on one stream, so an
+app reaches for the stream it expects on every open without checking
+first. A `DocumentStream` carries the document's own reading and writing
+surface scoped to that stream: `map` / `list` / `orderedMap` handles,
+`mutate`, `subscribe`, and `undo` / `redo`.
+
+## Opening at a stream
+
+`Brass.openDocumentById(docId, { stream })` opens the document with that
+stream as its own state, so `doc.map(...)` reads it and the rest of the
+document is never downloaded. An app that works in one part of a large
+document pays for that part alone:
+
+```ts
+const doc = await Brass.openDocumentById(docId, { stream: 'hvac' });
+doc.orderedMap('instances', 'instance_order').read(); // hvac's records
+```
+
+`stream` defaults to `'default'`, the stream every document has, so an
+open always names a stream and the usual one needs no argument.
+`doc.stream(name)` resolves the name the document was opened at back to
+the document itself, with no second join, and any other name to its own
+line. So the loop below reads the same whichever stream you opened at:
+
+```ts
+for (const info of await doc.listStreams()) {
+  const stream = await doc.stream(info.name);
+  summarize(stream.map('instances').read());
+}
+```
+
+`listStreams()` includes it like any other name, so a loop over the
+manifest needs no separate step for the stream you opened at. Names are
+`a-z 0-9 . _ -`, 1 to 64 chars, starting with a letter or digit, the same
+rule a schema family follows. `default` is
+one of them: every document already holds it, so `getOrCreateStream`
+resolves it without a request, and a loop over the names your schema
+declares needs no case for it. `getOrCreateStream` writes, so a read-only
+open reads with `doc.stream` instead and shows a degraded view when the
+document does not hold the stream.
+
+## Undo and editing model
+
+Each stream is its own collaborative unit: concurrent edits merge per
+stream, and each stream keeps its own local undo stack
+(`stream.undo()` / `stream.redo()`). The doc-level `doc.undo()` covers
+only the default stream.
+
+A stream's local edits group into one undo step until the group is
+**sealed** with `stream.sealUndoStep()`, the same same-stroke
+collapsing doc-level undo gets from checkpoints, exposed directly
+because streams carry no checkpoint machinery. Seal when a user
+operation completes; an app that never seals gets one giant step per
+session.
+
+### Undoing an operation that spans streams
+
+When one user action writes to several streams (move a wall in
+`architectural`, reroute its duct in `hvac`), keep an app-level
+operation journal and undo each touched stream once per journal entry.
+Two rules make the stacks line up:
+
+1. **Seal every touched stream when the operation completes.** The
+   seal is what makes the operation exactly one undo step in each
+   stream, however many mutates it took.
+2. **Route every local edit through the journal.** The alignment
+   argument is LIFO: if every operation is journaled and sealed, each
+   stream's stack top always belongs to the most recent journaled
+   operation that touched it. An edit that bypasses the journal
+   breaks that.
+
+```ts
+type Op = { label: string; streams: string[] };
+const undoJournal: Op[] = [];
+const redoJournal: Op[] = [];
+
+// Wrap every user operation: run the writes, then seal + journal.
+async function operation(
+  label: string,
+  streams: string[],
+  run: (open: Map<string, DocumentStream>) => void,
+) {
+  const open = new Map(
+    await Promise.all(
+      streams.map(async (n) => [n, await doc.stream(n)] as const),
+    ),
+  );
+  run(open);
+  for (const s of open.values()) s.sealUndoStep();
+  undoJournal.push({ label, streams });
+  redoJournal.length = 0; // a fresh edit clears redo, as usual
+}
+
+await operation('Move wall', ['architectural', 'hvac'], (open) => {
+  open.get('architectural')!.map('instances').mutate((m) => {
+    /* move the wall */
+  });
+  open.get('hvac')!.map('instances').mutate((m) => {
+    /* reroute the attached duct */
+  });
+});
+
+async function undoOperation() {
+  const op = undoJournal.pop();
+  if (!op) return;
+  // Reverse application order, so dependent changes unwind last-first.
+  for (const name of [...op.streams].reverse()) {
+    (await doc.stream(name)).undo();
+  }
+  redoJournal.push(op);
+}
+
+async function redoOperation() {
+  const op = redoJournal.pop();
+  if (!op) return;
+  for (const name of op.streams) {
+    (await doc.stream(name)).redo();
+  }
+  undoJournal.push(op);
+}
+```
+
+Bind your keyboard shortcut and undo button to `undoOperation()`
+rather than `doc.undo()` (which covers only the default stream).
+Collaborators' edits do not disturb the alignment: undo stacks are
+local-peer-scoped, and each stream's undo rebases your reverted step
+over remote changes the same way single-document undo does.
+
+Two properties to design around rather than against. The cross-stream
+undo is **not atomic**: each stream's revert is its own commit, so a
+collaborator can briefly observe one stream reverted before the other
+(the same window any multi-stream operation has). And the journal is
+**in-memory**: a reload starts it empty, exactly like single-document
+undo. If an operation genuinely cannot tolerate the window, that is
+the signal its data belongs in one stream: partition by load unit, and
+keep records that must change together in the same stream.
+
+## When to partition
+
+Opening a stream costs a request for its snapshot, and the first one on a
+document also reads the stream manifest, so add a stream when it carries
+real content that some opens can skip. Partition by **load unit** (a
+discipline, a heavy layer, a dataset a specific tool reads), not by
+concept. A handful of streams with megabytes each works best; dozens of
+tiny streams make opening everything slower
+than a monolith, and content every open needs belongs in the default
+stream.
+
+Branches and streams compose: creating a branch forks every stream, so a
+branch is fully isolated from its source across all of them, exactly like an
+unpartitioned document, and each forked stream keeps the shape its records
+conform to. Branching from a historical version addresses the default
+stream's timeline; the other streams fork at their current state. Deleting a
+branch deletes its streams with it. Two branches that then diverge in shape
+report different contracts, because a contract belongs to a stream on a
+branch rather than to the document.
+
+## Reading a document spread across streams
+
+Your schema names the streams it expects a document to be spread over,
+under `streams`. A small document keeps every record in its default
+stream; a large one moves the bulk (an IFC's geometry, an index most opens
+skip) onto the streams the schema names, so an app that reads only part of
+the content loads only that part. The declaration is the same either way,
+because it says which streams your app expects, not what any one document
+turned out to hold.
+
+If your app follows references between records, read every stream the
+DOCUMENT holds, because a referenced record may live in one the default
+stream does not. `doc.listStreams()` is that list, so merge by id:
+
+```ts
+const store: Record<string, { type: string; params: unknown }> = {
+  ...doc.orderedMap('instances', 'instance_order').read(),
+};
+for (const info of await doc.listStreams()) {
+  const stream = await doc.stream(info.name);
+  Object.assign(store, stream.orderedMap('instances', 'instance_order').read());
+}
+// store['#137'] resolves wherever #137 lives.
+```
+
+The loop opens the stream the document was opened at without a second
+join, so it reads the same for an unpartitioned document as for a split
+one. Open only what you read: an app that needs just the default view's
+records reads the default stream alone; one that resolves references
+reads them all and pays for the streams it opens.
+
+A document can hold streams your schema does not name (computed results,
+review notes, a cache), so the merge above skips them and an exporter that
+does not declare them writes nothing from them. Name a stream in your
+schema to read it, and `doc.getOrCreateStream` makes it when the document
+does not hold it yet.
+
+## Exporting across streams
+
+A registered serializer receives the live document and opens streams
+like any other code, so an exporter collects from wherever the content
+lives:
+
+```ts
+Brass.registerSerializer(async (doc) => {
+  const arch = await doc.stream('architectural');
+  const hvac = await doc.stream('hvac');
+  return encodeMyFormat(
+    arch.orderedMap('instances', 'instance_order').ordered(),
+    hvac.orderedMap('instances', 'instance_order').ordered(),
+  );
+});
+```
+
+Collect everything from the document itself. Brass may run your
+serializer detached from your app (a dashboard download, or a drive
+publish with your app not open), so open the streams you need rather
+than reach for your app's UI state.

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@brass-build/client",
+  "version": "0.1.0",
+  "description": "Client SDK for Brass",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "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"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/__tests__/**",
+    "scripts",
+    "README.md",
+    "AGENTS.md",
+    "CHANGELOG.md",
+    "docs",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -b",
+    "type-check": "tsc -b",
+    "prepare": "node ./scripts/prepare.mjs",
+    "prepublishOnly": "tsc -b --force"
+  },
+  "dependencies": {
+    "fflate": "^0.8.3",
+    "loro-crdt": "^1.12.1"
+  },
+  "devDependencies": {
+    "typescript": "~6.0.0"
+  },
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/brass-build/client.git"
+  },
+  "homepage": "https://brass.build",
+  "license": "MIT"
+}

package/scripts/prepare.mjs

@@ -0,0 +1,50 @@
+// `prepare` runs on `npm install`, both for direct installs (`npm i`
+// in `sdk/` itself) and for file-dep consumers (`"@brass-build/client":
+// "file:../sdk"`). We want one script that:
+//
+// 1. Skips the build when `dist/index.js` already exists. A consumer
+//    that installs a prebuilt SDK should not have to re-run `tsc` on
+//    every `npm install`, and an environment without a resolvable
+//    `tsc` (a fresh sandbox, a CI runner that doesn't install the
+//    SDK's own devDeps when pulling it as a file dep) would otherwise
+//    fail the consumer's `npm install` outright.
+// 2. Runs `tsc -b` from this directory when `dist/` is missing, so a
+//    direct `npm install` in `sdk/` still emits the bundle.
+//
+// `tsc` is resolved through `node_modules/.bin/` of this package, so
+// it works whether the consumer has a global `tsc` or not, as long as
+// the SDK's own devDeps installed (which they will under a plain
+// `npm i` in `sdk/`). When this script runs from a file-dep consumer
+// install, dist/ is already present in the file: target and we exit
+// before invoking tsc.
+
+import { existsSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const sdkRoot = dirname(here);
+const builtEntry = join(sdkRoot, 'dist', 'index.js');
+
+if (existsSync(builtEntry)) {
+  process.exit(0);
+}
+
+const tscBin = process.platform === 'win32' ? 'tsc.cmd' : 'tsc';
+const localTsc = join(sdkRoot, 'node_modules', '.bin', tscBin);
+const command = existsSync(localTsc) ? localTsc : tscBin;
+
+const result = spawnSync(command, ['-b'], { stdio: 'inherit', cwd: sdkRoot });
+if (result.error || (result.status ?? 0) !== 0) {
+  // Don't fail the install: a consumer who pulled the SDK as a file
+  // dep without dist/ and without typescript available can still
+  // import `src/` via the `files` whitelist, and the SDK's primary
+  // consumption path is the prebuilt `dist/`. A loud warning here
+  // lets the operator notice; a hard exit would block the whole
+  // dependency install for a working setup.
+  console.warn(
+    '[@brass-build/client] prepare: tsc -b did not run cleanly; ' +
+      'install is continuing without rebuilding dist/.',
+  );
+}