@brass-build/client 0.1.0 → 0.2.0

package/AGENTS.md

@@ -1,37 +1,36 @@
 # Instructions for AI coding agents
 
 You are likely an AI coding agent building an app on
-`@brass-build/client`. The [README](./README.md) teaches the API;
-this file is addressed to you specifically and carries two things the
-README does not: how to verify your work, and the UX baseline a
-generated app is expected to meet. Apply both.
+`@brass-build/client`. The [README](./README.md) teaches the API. This
+page covers how to verify your work and the UX baseline a generated app
+should meet. Apply both.
 
 ## Find out where the app's data comes from
 
 **The request names a format, a corpus, or an export.** Our IFC models,
 the GPX tracks off my watch, the change orders our subs email us. Ask
 for one real example as your first action, before you design anything.
-That file decides your record shape, and an app built ahead of it
+You take your record shape from that file, and an app built ahead of it
 guesses at a shape the real files contradict.
 
 **The work has a customary shape in the user's trade.** A punch list, a
 timesheet, an RFI, a site diary: people in that line of work pass these
 around as documents whose fields they all expect, so a shape for it
 exists and the user probably holds a copy. Ask for theirs before you
-design a schema. A schema you invent for a shape that already exists
-forks it: the picker routes documents to apps by their declared schema,
-so each app's documents stop opening in the other, and the split
-stands. Ask the user rather than looking, because a shape reaches you
-through a document that already carries it.
+design a schema. Inventing a schema for a shape that already exists
+forks that shape: the picker routes documents to apps by their declared
+schema, so each app's documents stop opening in the other, and the split
+stands. Ask the user rather than searching for the shape yourself: it
+reaches you as a document they already hold.
 
 Ask as well whenever the user brings up another application. What that
 product can hand over decides whether you adopt a shape or integrate,
 and only the user knows.
 
-A product you assumed rather than one they named is the other way
-round. Data a product holds reaches you through its API rather than as
-a document, so a sprint board, a sales pipeline, or a ticket queue you
-guess lives in some tool leaves you no shape to adopt. Build it as
+A product you assumed, rather than one the user named, works the other
+way round. Data a product holds reaches you through its API rather than
+as a document, so a sprint board, a sales pipeline, or a ticket queue
+you guess lives in some tool leaves you no shape to adopt. Build it as
 below until the user names the tool.
 
 **The data starts in your app.** A canvas, a poll, a garden planner, a
@@ -42,10 +41,9 @@ Design the records from the request, declare their schema in
 has none behind it, and it reads to the user as though their request
 was incomplete.
 
-Either question runs alongside the work that does not depend on the
-answer, rather than idling: drive the sign-in, fetch the organization's
-instructions (next section), and scaffold the app shell while the user
-answers.
+Ask either question and keep working on what does not depend on the
+answer: drive the sign-in, fetch the organization's instructions (next
+section), and scaffold the app shell while the user answers.
 
 With an example in hand: the user adds it at their Brass dashboard
 (`https://app.brass.build`) and sends you back the document's link,
@@ -79,18 +77,17 @@ npx @brass-build/cli agents pull --stdout
 
 It prints the organization's own conventions for apps built on Brass
 (its `AGENTS.md` / `CLAUDE.md`) to stdout. Read them inline and treat
-them as an instruction file for this task; they take precedence over
-the generic defaults here. Run it rather than deciding up front whether
-the org has any: if it has set none the command prints nothing and you
-proceed with the defaults below, but that is something you learn by
-running it, not by assuming it, so this is a step you take, not a box
-you skip. The pull needs a signed-in session, so if `brass agents pull`
-reports no credential, run the sign-in yourself first (`brass login
---start`, relay the printed URL and code to the human, then `brass
-login --check` until it reports approved), and it is the same
-credential you will use to publish (see "Ship the app"), so drive that
-sign-in now rather than skipping the fetch. `brass agents pull` is detailed in the
-`@brass-build/cli` package's `AGENTS.md`.
+them as an instruction file for this task. They take precedence over
+the generic defaults here. Run the command rather than deciding up
+front whether the org has any: an org that set none prints nothing, and
+you proceed with the defaults below.
+
+The pull needs a signed-in session, so when `brass agents pull` reports
+no credential, run the sign-in yourself first (`brass login --start`,
+relay the printed URL and code to the human, then `brass login --check`
+until it reports approved). That is the same credential you will use to
+publish (see "Ship the app"), so drive the sign-in now. `brass agents
+pull` is detailed in the `@brass-build/cli` package's `AGENTS.md`.
 
 ## Have a second agent review your work
 
@@ -98,33 +95,35 @@ Brass documents are persistent and shared: a write that compiles and
 looks right on screen can still be subtly wrong in the stored
 document, and once saved it syncs to every collaborator and reopens
 later. You share the blind spot that produced any such bug, so
-reviewing your own work tends to reconfirm it. Build with a review
-loop instead of treating one as optional polish.
+reviewing your own work reconfirms it. Build with a review loop.
 
 Once the integration builds, have a **separate** agent (not you)
 adversarially review it and drive it in a real browser against the
 live backend. Hold that reviewer to implementation-independent checks:
 
-- It should read the document back through the handles
-  (`doc.map(...).read()` / `doc.list(...).read()`) and validate the
-  result against the data spec itself, rather than trusting the app's
-  own helpers.
+- It should take the document's own records from a subscriber of its
+  own (`doc.map(...).subscribe(...)` / `doc.list(...).subscribe(...)`)
+  and validate them against the data spec itself, rather than trusting
+  the app's own helpers.
 - It should push the negative, zero, and boundary inputs of every
   operation.
 - It should confirm each edit round-trips and leaves the document
   consistent.
-
-Driving it on a touch device, not just a desktop mouse, tends to be
-where the surprising bugs are: interactive gestures (drags,
-multi-point taps, anything pointer-driven) commonly work under a mouse
-but break under touch, and layout looking fine at a narrow width says
-nothing about whether the gesture still functions there. Worth a pass
-on real touch when the app has any.
-
-Fix what the reviewer finds and iterate until the reviewer's own
-checks pass. A single build pass routinely ships writes that are wrong
-but plausible; this loop is what catches them, and it is worth a round
-before you call an integration done.
+- It should open the same document as **two** signed-in readers and put
+  them in the same field at once: with one reader's caret sitting in a
+  field, the other edits it. The first reader's screen has to show that
+  value once their caret leaves, and a reader whose own edit goes over a
+  peer's has to be told so. Both halves fail silently, and a single
+  session never reaches either.
+
+Have the reviewer drive any gesture on a touch device as well as a
+desktop mouse. Drags, multi-point taps, and anything else
+pointer-driven commonly work under a mouse and break under touch, and a
+layout that looks right at a narrow width says nothing about whether
+the gesture still works there.
+
+Fix what the reviewer finds and iterate until the reviewer's own checks
+pass, before you call the integration done.
 
 ## Apply these UX defaults
 
@@ -154,11 +153,24 @@ the baseline for when there is no design.
   where it bites.
 - **Make touch targets at least 40px**: `padding: 12px 16px` on
   tappable controls.
+- **Draw the `<select>` arrow yourself.** A native `<select>` puts the
+  browser's own arrow tight against the control's right edge, at a gap
+  that differs per browser, so a select carrying your border and radius
+  still reads as a stock control beside your other inputs. Set
+  `appearance: none`, draw the chevron as a `background-image` at
+  `background-position: right 0.75rem center`, and reserve
+  `padding-right: 2.25rem` so a long option cannot run under it.
 - **Disable, don't hide, on read-only documents.** When
-  `doc.readOnly` is true (a viewer-role grant, or a historical-version
-  preview), render the editor and share controls disabled with a
-  `title` explaining why, rather than removing them. `doc.readOnly` is
-  the public signal; gate on it, not on a role field.
+  `doc.readOnly` is true, render the editor and share controls disabled
+  with a `title` explaining why, rather than removing them. It covers
+  every reason this reader cannot write: a view-only grant, a view-only
+  share link, a historical-version preview, and a document still
+  loading. Re-read it in your `doc.subscribe` handler rather than
+  reading it once at bind: it also flips when someone withdraws the
+  reader's access while the document is open, which is what closes the
+  editor at the moment writing stops working. Pair it with
+  `Brass.onError`, where the sentence explaining a refused write
+  arrives.
 - **Name the next action in empty states.** "No document open. Use
   Open to pick or create one."
 - **Gate edit affordances on an open document.** When
@@ -168,9 +180,10 @@ the baseline for when there is no design.
   user produce work that silently cannot be persisted and is discarded
   when the first document opens.
 - **Render the `error` status.** When `session.status` is `error` (a
-  document the user opened could not be opened: deleted, or an access
-  the platform collapses to a non-disclosing 404; or a document that was
-  open being deleted out from under the user), render
+  document the user opened could not be opened: deleted, an access the
+  platform collapses to a non-disclosing 404, or a file the platform
+  could not prepare; or a document that was open being deleted out from
+  under the user), render
   `session.error.message` verbatim, surrounded by your own New / Open
   actions, not the plain empty state. Falling through to "No document
   open" reads as if the user asked for nothing and hides the failure.
@@ -210,13 +223,10 @@ npx @brass-build/cli status
 
 It inspects the credential and app state for this environment and ends
 in a `Next:` line naming the one command to run. Follow that line, then
-run `brass status` again. It is the control surface for the rest of this
-section: rather than reasoning about publishing from prose, you run it
-and do what it says.
+run `brass status` again, for the rest of this section.
 
 Two steps need the human's Brass account, and you cannot stand in for
-it. Both are steps you drive to completion, not blockers you note and
-stop at:
+it. Drive both to completion rather than noting them and stopping:
 
 - **Getting an app id.** `Brass.init` needs the `app_id` of a
   registered app. Run the first `brass publish` (below): it creates the
@@ -227,11 +237,10 @@ stop at:
   on the dashboard and gives you the id.)
 - **A publish credential.** When `brass status` reports no credential,
   drive the sign-in: run `brass login`. In a local session it opens the
-  human's browser to approve and completes on approval; on a headless
+  human's browser to approve and completes on approval. On a headless
   box it prints a URL and short code the human approves from any device.
   Running it and getting the human through approval is your step. For CI
-  the human supplies `BRASS_SERVICE_TOKEN` instead. You cannot mint
-  either, but neither is a wall you stop at.
+  the human supplies `BRASS_SERVICE_TOKEN` instead.
 
 Once `brass status` reports a credential, publish:
 

package/CHANGELOG.md

@@ -6,6 +6,92 @@ and the package follows [semantic versioning](https://semver.org/spec/v2.0.0.htm
 While the version is below `1.0.0`, minor releases may introduce
 breaking changes.
 
+## 0.2.0
+
+### Added
+
+- Large collections page themselves. A map an app fills past 5,000 records
+  stores them in compressed pages instead of one container per record, which
+  keeps a bulk write and a reload viable at hundreds of thousands of records.
+  `get()`, `has()` and `mutate()` read and edit a paged map exactly as they do
+  a small one.
+- A map keeps its own bookkeeping beside your records, under keys beginning
+  with `brass:`, so a write under one of those keys is refused. Any other key
+  is yours.
+- `doc.atCapacity` (and `stream.atCapacity`) reports that the platform has
+  refused a write because the document reached its ceiling. A document gets
+  there through a band where ordinary editing still lands and a bulk write is
+  refused, so this is the signal to stop offering the bulk work (an import, a
+  generate pass) while leaving the rest of the app alone. Edits keep applying
+  to the local copy while it reads `true`, so an app can show the reader what
+  they did alongside the fact that it is not saved. `doc.subscribe` fires when
+  it flips, once rather than once per refused change.
+- `onSettled(cb)` on the map, list and ordered-map handles fires when a
+  delivery of the whole collection finishes, so the work that follows on the
+  collection (framing the camera on what arrived, a first pass over it) has
+  somewhere to live other than a single change.
+- `orderedMap.insert(key, value, at)` and `orderedMap.move(key, to)` place and
+  reposition an entry against a neighbour, through the new `OrderedMapPosition`
+  type.
+- A list draft carries `move(from, to)`. Two people repositioning the same
+  entry with it converge on one entry, where a removal paired with an
+  insertion keeps both insertions and leaves the entry in the list twice.
+- Presence layers carry a 2,048-byte cap (`PRESENCE_LAYER_MAX_BYTES`). Watch
+  `presence.onStatus` to know when Brass is withholding a layer that is over
+  it; a `selection` crosses the cap at roughly 130 to 140 typical entity ids,
+  so publish a bounded summary when a selection can get large.
+- The browser's own "leave site?" prompt appears while a document holds edits
+  the server has not acknowledged, so a reload cannot silently drop them.
+
+### Changed
+
+- `session.status` reaches `error` for a file Brass could not prepare, on top
+  of a deleted or inaccessible document. One error screen still covers them
+  all.
+- `doc.readOnly` now also reads `true` for a document that could not be
+  loaded, so edit affordances gated on it stay disabled there as well as
+  during loading.
+- A store pages at 5,000 records rather than 50,000, where paging starts
+  paying for itself: it writes about 3x faster, opens about 5x faster and
+  stores about 1.7x smaller. What it costs is merge granularity. Below the
+  threshold two people editing different fields of one record both keep their
+  edit; above it the record is the merge unit, so one of the two wins.
+- Two tabs of one app are two claimants for an import, so only one of them
+  parses the file.
+- A list subscriber receives the splices its change made, applied in the order
+  they arrive, so a render costs what the change carried rather than what the
+  list holds.
+- `SyntheticSubscribeEvent` names a move through version history `history`
+  rather than `checkout`. `ChangeSource` no longer lists it: a version move
+  swaps the whole container instead of writing into it, so it reaches a handle
+  subscriber as a whole-container fire with no origin, and `doc.subscribe` is
+  where that move is reported.
+- A `Document` is reached through `Brass.session`, `Brass.openDocumentById`, or
+  `Brass.createDocument`. The class no longer constructs.
+- The capability manifest names the files an app imports under `imports`,
+  which is the word the platform and the dashboard use for them.
+
+### Removed
+
+- `read()` on the map, list and ordered-map handles. A handle feeds an app
+  through `subscribe`, which costs what a change carried rather than what the
+  document holds, so a collection large enough to page never pays an
+  O(document) walk to render. A registered serializer runs detached with no
+  subscription behind it, and is handed a `StoredMap` / `StoredList` that
+  keeps `read()`.
+- The barrel no longer exports plumbing types that no `Brass`, `Document`, or
+  `DocumentSession` member names: `AcquireOrganizationResult`,
+  `HostedUiLauncher`, `HostedUiLauncherOptions`, `DocumentSessionDeps`,
+  `StreamRuntime`, `CreateDocumentFn`, `DocumentFactory`,
+  `DocumentAtVersionResponse`, `DocumentSnapshotResponse`,
+  `DocumentDriveSummaryWire`, `OpenDocumentFactoryOptions`,
+  `OpenDocumentByIdFn`, and `OpenDocumentWsClient`. What autocomplete offers
+  is now what an app can call.
+- `doc.pushToDrive` and `doc.resolveDrive` are internal. Publishing a document
+  back to its drive source, and resolving a diverged one, are the hosted
+  toolbar's controls. `doc.driveStatus` still reports the sync state, so an
+  app can tell the reader they have unpublished edits.
+
 ## 0.1.0
 
 Initial public release. The SDK turns a document into a live,