@niscorp/moss 0.3.2 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (48) hide show
  1. package/CHANGELOG.md +155 -0
  2. package/DESIGN.md +84 -19
  3. package/DOCS.md +170 -35
  4. package/README.md +2 -2
  5. package/dist/{chunk-J72N3EMJ.js → chunk-4T6KAXBP.js} +45 -27
  6. package/dist/chunk-4T6KAXBP.js.map +1 -0
  7. package/dist/{chunk-ZOEUEMDX.js → chunk-HOZID4EM.js} +131 -16
  8. package/dist/chunk-HOZID4EM.js.map +1 -0
  9. package/dist/{chunk-ZP3C53AC.js → chunk-R3QMJ3JF.js} +744 -661
  10. package/dist/chunk-R3QMJ3JF.js.map +1 -0
  11. package/dist/chunk-U3UR5AOQ.js +103 -0
  12. package/dist/chunk-U3UR5AOQ.js.map +1 -0
  13. package/dist/client/node.cjs +1 -1
  14. package/dist/client/node.cjs.map +1 -1
  15. package/dist/client/node.js +1 -1
  16. package/dist/client/node.js.map +1 -1
  17. package/dist/client.cjs +60 -26
  18. package/dist/client.cjs.map +1 -1
  19. package/dist/client.d.cts +6 -1
  20. package/dist/client.d.ts +6 -1
  21. package/dist/client.js +2 -2
  22. package/dist/{document-D9khv9jI.d.cts → document-DhWxieUc.d.cts} +22 -3
  23. package/dist/{document-D9khv9jI.d.ts → document-DhWxieUc.d.ts} +22 -3
  24. package/dist/index.cjs +786 -583
  25. package/dist/index.cjs.map +1 -1
  26. package/dist/index.d.cts +19 -3
  27. package/dist/index.d.ts +19 -3
  28. package/dist/index.js +2 -2
  29. package/dist/node.cjs +379 -230
  30. package/dist/node.cjs.map +1 -1
  31. package/dist/node.d.cts +2 -1
  32. package/dist/node.d.ts +2 -1
  33. package/dist/node.js +3 -3
  34. package/dist/terminal/index.cjs +60 -26
  35. package/dist/terminal/index.cjs.map +1 -1
  36. package/dist/terminal/index.js +2 -2
  37. package/dist/vite.cjs +103 -28
  38. package/dist/vite.cjs.map +1 -1
  39. package/dist/vite.d.cts +1 -1
  40. package/dist/vite.d.ts +1 -1
  41. package/dist/vite.js +14 -9
  42. package/dist/vite.js.map +1 -1
  43. package/package.json +12 -12
  44. package/dist/chunk-J72N3EMJ.js.map +0 -1
  45. package/dist/chunk-SUVDISEG.js +0 -64
  46. package/dist/chunk-SUVDISEG.js.map +0 -1
  47. package/dist/chunk-ZOEUEMDX.js.map +0 -1
  48. package/dist/chunk-ZP3C53AC.js.map +0 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,160 @@
1
1
  # @niscorp/moss
2
2
 
3
+ ## 0.4.0
4
+
5
+ ### Minor Changes
6
+
7
+ - f834f3f: `evaluate` checks a config object once and only evaluates it after that; `prismTransform` is gone. **Breaking.**
8
+
9
+ BREAKING — approved by moccadroid, 2026-10-09: replace `prismTransform` with `evaluate` (`transform: evaluate`), and pass limits as `{ limits: … }`.
10
+
11
+ Prism had three ways to run a config, and the one a host was told to hand to its seam (`prismTransform`) was the one that reported worst, while the hosts on a hot path each wrapped `evaluate`, which checked the config on every call. There are two now, with one job each.
12
+
13
+ **`evaluate(config, source, options?)`** — for a config a program holds.
14
+ - The first time it is handed a config object it checks it and keeps its tree; the second time it prepares the tree as `compile` would; from then on a call only evaluates. Four fields picked and renamed, the same config object again: 3.5 µs before, 0.4 µs now. A nested choice on two fields: 18 µs before, 0.7 µs now. A config that is a new object on every call costs what it did.
15
+ - It is kept **by the object**: a config changed in place after its first call is not read again. Hand over a new object.
16
+ - Both arguments are `unknown`, so it is what a host's transform seam takes: `createTide({ transform: evaluate })`, `createUpgrader(grammars, { transform: evaluate })`.
17
+ - The third argument is `{ limits?, check? }`. Limits were the third argument themselves: `evaluate(config, source, { maxSteps: 100 })` is now `evaluate(config, source, { limits: { maxSteps: 100 } })`.
18
+ - `check: 'always'` is for writing a config, for tests and for tools: nothing is kept, the config is checked on every call, and the source must be plain JSON (a source holding `undefined`, a function, a `Date` or a non-finite number is refused with `E_TYPE`).
19
+ - An invalid config is a `PrismError` (`E_SCHEMA`) naming the part that is wrong, however deep the config. `prismTransform` threw zod's own error, and a `RangeError` for a config nested far past the limit.
20
+
21
+ `evaluateSafe` takes the same arguments.
22
+
23
+ **`compile` and `execute`** — for a config that is stored. Unchanged.
24
+
25
+ **`prismTransform` is removed**, from `@niscorp/prism` and from `@niscorp/prism/migrations`. What it added over `evaluate` was a check that the source is plain JSON; that check is now `check: 'always'`, and a seam's source is taken as it is.
26
+
27
+ **moss, nova, vex, loom, nisc, create-nisc and the cli move with it.** Each has Prism as a peer or a dependency, or has one of those that do, and a Prism at 0.3 is outside the range their last versions accept: an app takes them together. Nothing in vex, loom or the cli changed beyond that range.
28
+
29
+ moss's shell and nova's `$prism` binding called `evaluate` on every use and so paid the check each time: an endpoint's request and response under moss, and a `$prism` value on each draw and for each row of a list, are 8 to 45 times faster for the configs measured. tide's and strata's documentation name `evaluate` where they named `prismTransform`.
30
+
31
+ **What to change**
32
+ - `import { prismTransform } from '@niscorp/prism'` or `'@niscorp/prism/migrations'` → `import { evaluate } from '@niscorp/prism'`, and `transform: prismTransform` → `transform: evaluate`. Every app made by `create-nisc` has this in `src/dev/strata.ts`; the app's typecheck and `npm run strata` both stop on that line until it is changed.
33
+ - A third argument of limits becomes `{ limits: … }`.
34
+ - A wrapper that parsed the config before calling `evaluate` (`evaluate(ConfigSchema.parse(config), …)`) makes a new object on every call and so is checked on every call: hand `evaluate` the config itself.
35
+ - Code that changes a config object in place and evaluates it again must hand over a new object, or pass `{ check: 'always' }`.
36
+ - A host that relied on `prismTransform` refusing a source that is not plain JSON checks it itself, or passes `{ check: 'always' }`.
37
+
38
+ ### Patch Changes
39
+
40
+ - Updated dependencies [023bcf9]
41
+ - Updated dependencies [1db6df4]
42
+ - Updated dependencies [6d098e4]
43
+ - Updated dependencies [8b4d97e]
44
+ - Updated dependencies [f834f3f]
45
+ - Updated dependencies [b084e30]
46
+ - Updated dependencies [663d724]
47
+ - Updated dependencies [6512d91]
48
+ - Updated dependencies [7d682b9]
49
+ - Updated dependencies [d2e9d22]
50
+ - Updated dependencies [e0e8abc]
51
+ - Updated dependencies [7fe1135]
52
+ - @niscorp/prism@0.3.0
53
+ - @niscorp/nova@0.3.0
54
+ - @niscorp/vex@0.3.0
55
+
56
+ ## 0.3.3
57
+
58
+ ### Patch Changes
59
+
60
+ - 78a563f: A page served by its app no longer holds its session: the browser does, in a cookie no script can read.
61
+
62
+ A session token in a page — in `localStorage`, or in the script-readable cookie copy `browserEnv({ cookie: true })` kept — is there for anything else that runs in that page to take. Now the server writes the session into a cookie the page cannot read (`HttpOnly`, `SameSite=Lax`; `__Host-` prefixed and `Secure` over https) in its answer to the socket's upgrade, and the browser sends it by itself with the two requests that need to know who is asking: the page, and the upgrade. After a reload the page holds nothing.
63
+
64
+ **The setup this stops working for:** code that read the session token out of the page. `localStorage['nisc.token']` is empty once the browser holds the session, and the cookie copy is no longer written, so anything that took the token from there — to call a route with `Authorization: Bearer`, say — finds nothing. No route answers to the new cookie, on purpose: a browser sends a cookie with requests another site makes it send. And `renderDocument` no longer answers a cookie that does not resolve with a `Set-Cookie` that takes it back; the upgrade is the one place the cookie is written.
65
+
66
+ What happens, and to whom:
67
+ - **Only the app's own page.** The cookie is read and written when the upgrade's `Origin` is the host it was addressed to, or one listed in the new `runtime.origins` (for a proxy that rewrites `Host`). A page on another origin — which a browser sends the cookie with all the same — is nobody. A terminal that is not a page of its app (a process on `nodeEnv`, a page served from somewhere else, a browser that refuses cookies) holds its own token and offers it, exactly as before.
68
+ - **Nobody is signed out by the update.** A token an earlier build left in storage is offered once, moved into the cookie by the answer, and removed from storage along with the old copy.
69
+ - **Seats.** The cookie is named by the terminal's `tokenKey`, so several people can be signed in on one origin as before; the terminal names its key in the socket's address (`?key=`), and `renderDocument`'s `tokenKey` reads the same one. The name ends with the port when the page is on one — a browser keeps cookies by host, not port, and two apps on localhost would otherwise sign each other out — so `renderDocument` takes `request.host`; `mountSite` and the vite plugin pass it.
70
+ - **Signing out.** A cookie that no longer resolves is taken back on the next upgrade. Under an app's own identity provider the token may go on resolving, so a terminal that was signed out says so (`?leave=1`) and the cookie is taken back whatever it holds.
71
+ - **A sign-in the app answers over HTTP** (a link redeemed, a provider's callback) sets the cookie itself: `sessionCookies(request, token, { key?, lastsMs? })`, exported from the package root, returns the `Set-Cookie` values. The page that follows is signed in and was never handed the token. The vite plugin's `/dev/as/<who>` does this now.
72
+ - **A transport of your own** passes what the request carried — `connection.upgrade = { offered, origin, host, cookie }` — and, to let the cookie be written, leaves the request unanswered until the connection is first used, answering then with the cookies moss named through `upgrade.answer(cookies)` (moss names them before it uses the connection, and names none when there are none to write). One that has already answered reads the cookie and writes none. `attachSocket` does both.
73
+ - **A `WireEnv` of your own** is unchanged: without `tokens.held` a terminal stores its token as it always did.
74
+
75
+ **What to change:** nothing in an app that uses `createWire` with `browserEnv()` and serves with `serve`, `nisc start`, the vite plugin or `attachSocket`. `browserEnv({ cookie: true })` still compiles and the option now does nothing; drop it when convenient. A sign-in page that writes the token to `localStorage` keeps working (the token is moved on the next upgrade), and is better replaced by `sessionCookies` on the response. Behind a proxy that rewrites `Host`, list the app's origin in `runtime.origins` — until then every page looks like one served from somewhere else, so the app works as it did before this change, each terminal holding its own token, and moss says so once in the log. An app that draws its own pages passes `request.host` to `renderDocument`; behind a proxy that rewrites `Host` to an upstream on another port, `site` is where the port is taken from.
76
+
77
+ - 51dc5ce: DESIGN says what a rebuilt shell holds. "Durability" named a projection as the durable thing, and moss has built none ("Deliberately unbuilt" lists it). It now says the database is the durable thing: a shell is rebuilt on the next connection from definitions and whatever the app reads from rows as it builds, and evicting an idle shell, restarting the process and `reset` each cost what was only in the shell — the screens someone had opened, and what they had typed. Two source comments now say the same. No code changed.
78
+
79
+ **What to change:** nothing.
80
+
81
+ - da42472: With `shellFrameDelta` on, a canvas whose frame is over 64 KB is sent whole, and no longer compared.
82
+
83
+ Encoding a delta costs the server in proportion to the size of the two frames, not of the change, and it does the work on the thread every session shares. Nothing bounded it. Measured on the encoder alone: a 0.3 MB frame held the thread 65 ms for one changed letter, a 2.7 MB frame over a second, and at 20 MB it ran for eight seconds, took a gigabyte and failed — after which the frame was sent whole anyway. Every session on the process waited each time. A large frame needs nothing unusual: a long table, or one long value in a bound field, which any terminal can send. Now a change is sent whole, with no encode, when the frame the terminals hold or the frame replacing it is longer than 64 KB — where an in-place change measured about 7 ms.
84
+
85
+ Nothing moves with `shellFrameDelta` off (the default), for a terminal that did not ask for deltas, or on a canvas whose frames are at most 64 KB: those are byte for byte what they were. The rendered tree is the same in every case.
86
+
87
+ **What to change:** nothing. With deltas on, a change to a canvas over 64 KB now costs that canvas's whole frame on the wire — what a terminal that never asked for deltas is sent — where it had cost a delta, after the encode.
88
+
89
+ - a91b5db: `migrateTables`: the step that changes the tables, and checks the app's entries against what it leaves before it commits. `runtime.tables` hands it the app's own.
90
+
91
+ A deployment whose runtime says `migrations: 'verify'` refuses to start with anything pending, and moss had nothing to run first. An app's own tables were outside that run, so `'verify'` did not cover them.
92
+
93
+ `runtime.tables` takes the app's own table sequences (and another owner's the app keeps — tide's `TIDE_SEQUENCE`). They join moss's one ledgered run, after moss's own. A runtime that hands tables over does not also migrate them itself.
94
+
95
+ `migrateTables(runtime, app, { dryRun? })` applies everything pending in that run and, before it may commit, checks every entry of the manifest against the schema as it would stand: a read is resolved, a write is put to the gates it passes before it runs (vex's `mutationMisfits`). An entry that does not fit refuses the run — strata's `DOES_NOT_FIT`, each reason as `fingerprint: why` — and nothing is applied. It checks when nothing was pending too, so a release that changes an entry and no table is checked.
96
+
97
+ One kind of entry is listed and not refused: one that already did not fit before the run and that the database already holds seeded exactly as it is. A new or changed entry gets no such pass. The report also says which tables and columns a run removed and which column types it changed.
98
+
99
+ It sees entries and nothing else: not SQL written by hand, not a column a scope rule stamps, not what a value means.
100
+
101
+ **What to change:** nothing. A boot applies and verifies exactly what it did: a runtime without `tables` runs the same sequences in the same order.
102
+
103
+ - 812c464: `runtime.vexConfig` hands the query engine its settings.
104
+
105
+ Moss built the vex engine with no `config`, so a deployment ran on vex's defaults — 100 rows for a list that states no limit, 1000 at most, a ten-second read timeout — and had no way to change one.
106
+
107
+ `NiscRuntime` takes an optional `vexConfig`, passed to `createQueryEngine` as its `config` unread: `defaultLimit`, `maxLimit`, `capAuthored`, `statementTimeoutMs` and the rest of `QueryEngineConfig['config']`. Unset, the engine is built exactly as before.
108
+
109
+ **What to change:** nothing. Set `vexConfig` in your runtime to change one of the engine's numbers — for example `vexConfig: { capAuthored: true }` to keep seeded entries under `maxLimit`.
110
+
111
+ - 770f754: A frame the websocket transport refuses closes that connection; it no longer ends the process.
112
+
113
+ `attachSocket` listened for a connection's messages and its close, and not for its errors. `ws` reports what it refuses from a client — a malformed frame, text that is not UTF-8, a message over its size limit — as an `error` on that connection, and Node throws an `error` nobody listens for. So one such frame, from any client that could open the socket, signed in or not, ended the server process and every session on it. The transport now listens: `ws` has already closed the connection with the status that says why (1002, 1007, 1009), one line is logged (`[moss/node] a connection was closed on what it sent: …`), and nothing else is touched. Every host that calls `attachSocket` gets it — `serve`, `nisc start`, the vite plugin, an app's own listener.
114
+
115
+ **What to change:** nothing. An app this had happened to was not running. A process-level `uncaughtException` handler that was catching these no longer hears them.
116
+
117
+ - 61a4060: A sign-in made over the socket no longer hands the page its token. It reaches the page sealed, and only that browser can open it.
118
+
119
+ `session.grant(token)` happens on a socket, and a socket cannot write a cookie — so the token has to travel through the page to the terminal's next upgrade, where the session cookie is written. It used to travel as itself, which for that moment put it where any script in the page could take it. Now it travels encrypted with a key the browser holds in a second cookie no script can read (the _seal_), given by the answer to the browser's first upgrade. The page hands the sealed sign-in back and cannot open it; neither can anybody it is shown to, on this machine or another — without that browser's seal it opens nothing, and after a minute it opens nothing at all.
120
+
121
+ **The setup this stops working for:** none that worked. What is new for a browser: a terminal on `browserEnv()` now names `sealed=1` in the socket's address, and a browser that opens a socket to its app is given one more cookie — `nisc.seal` (`__Http-nisc.seal` over https): `HttpOnly`, `SameSite=Lax`, sent with the socket's path and no other, kept until the browser closes. It is given whether or not anybody signs in. It is a key, not a name: it is not stored or looked up on the server, and no page request carries it, so a page drawn for nobody stays cacheable for everybody.
122
+ - **Any credential, any number of processes.** Nothing is kept on the server between the sign-in and the upgrade that completes it, so it does not matter which process answers either, and the token can be moss's own or an app's provider's.
123
+ - **Terminals that keep their own token are handed it as before:** a process on `nodeEnv`, a page served from another origin, a `WireEnv` without `tokens.held`, a transport that cannot answer an upgrade late. `{ type: 'session', token }` is unchanged for them.
124
+ - **A browser that does not keep the seal** — it sends none back with the sealed sign-in — is told (`seal_not_kept`); its terminal stops asking, and the next sign-in reaches it as a token. That costs such a browser one failed sign-in.
125
+ - **A terminal written by hand** that wants sealed sign-ins: `?sealed=1` on the address from the app's own origin; a `{ type: 'session', sealed }` message is offered back with `offerToken(null, sealed)`.
126
+
127
+ The seal's name over https is what keeps a script from supplying it: the seal is given after the page's script has started, and a script already running then could otherwise set one of its own first and open the sign-in that follows. `__Http-` is a name a browser lets only an HTTP answer set. Not closed: a browser that does not know that prefix treats it as any other name; and a server on a sibling subdomain can still set one, which with a script in the page as well is the same opening.
128
+
129
+ **What to change:** nothing.
130
+
131
+ - 8012cd8: A message a terminal sends over the socket is at most 256 KB; a host that takes larger ones says so with `attachSocket`'s new `maxMessageBytes`.
132
+
133
+ **The setup this stops working for:** an app whose terminal sends a message over 256 KB — in practice a file put into a model value as base64 (a picked picture is megabytes). That message now closes the connection with `1009` and what it carried does not arrive; the terminal reconnects as after any other close, and a signed-in person's shell is as it was. To keep the old behaviour, a host that calls `attachSocket` passes the size it takes: `attachSocket(httpServer, server.socket, '/socket', { maxMessageBytes: 100 * 1024 * 1024 })` is what `ws` did before. `serve()`, `nisc start` and the vite plugin take the default and cannot raise it; an app on one of those that needs more attaches the socket itself. Better than raising it, and what `AGENTS.md` rule 9a says: a file never goes over the socket — the picker sends it to a route the app mounts, and the event carries what the route answered.
134
+
135
+ Why there is a limit. `attachSocket` created its `WebSocketServer` with no `maxPayload`, so the limit was `ws`'s own 100 MiB. Whatever a message carries, the server keeps — the value in the shell, and again in the last frame it sent — and sends back down in every later frame of that canvas. So the limit is what one connection, signed in or not, can make the process hold and re-send. Measured per open connection: 0.2 MB with nothing sent, 1.5 MB after a 256 KB value, 3.3 MB after 1 MiB, 48 MB after 16 MiB. Compression does not bound it — a 64 MB message of one repeated letter is 60 KB on the wire — so the count is of the message once inflated. What a terminal legitimately sends is an event: a press, a typed value, a row handed back. A few KB.
136
+
137
+ **What to change:** nothing, unless a terminal of yours sends more than 256 KB in one message — then one of the two things above. A typed value still has about 250,000 characters of room.
138
+
139
+ - 10875eb: A terminal's session token no longer rides the socket's address. It is offered in a header of the same request, and a token in the address is not read.
140
+
141
+ **The setup this stops working for:** a terminal and a server that are not the same version. The wire protocol is now 2 and the server speaks nothing older, so a terminal built before this is refused with `client_too_old` and a `4426` close — the existing "reload to get the current build" path — and a terminal built after it is refused by an older server with `server_too_old`. An app's terminal and server are one package and deploy together, so in practice this is a tab left open across the deploy: it reloads once. Three things written by hand also change:
142
+ - **A terminal written by hand** (`new WebSocket(`…/socket?token=…`)`, as a check or a script does) names the protocol and offers the token: `new WebSocket(`${base}/socket?protocol=${PROTOCOL}`, offerToken(token))`. `PROTOCOL` and `offerToken` are exported from `@niscorp/moss`; `offerToken(null)` is a terminal that is nobody.
143
+ - **A `WireEnv` of your own**: `socket` takes `{ url, offered }` where it took `url`, and constructs `new WebSocket(url, offered)`. One argument on purpose — an env that kept the old shape would have gone on compiling and connected everybody as nobody; this way it does not compile.
144
+ - **A transport of your own** (anything that is not `attachSocket`) hands over what the request offered: `connection.upgrade = { offered }`, the `Sec-WebSocket-Protocol` header split on commas, and answers the subprotocol `nisc`. Without it every terminal is served as nobody.
145
+
146
+ Why. The token rode the upgrade's query string, and an address is what every proxy, load balancer and access log between a browser and the app writes down. The request has one header every host lets a terminal set, a browser included: the subprotocols it offers. So the terminal offers `nisc`, and beside it its token, base64url (a subprotocol is an HTTP token; a session token need not be); the server answers `nisc` and never the other. Who a terminal is is still decided on the upgrade request, before anything is served, so there is no connection that is open and waiting to be told. A server that kept reading `?token=` for older terminals would have kept the address open for as long as anything used it, which is why protocol 1 is refused rather than served.
147
+
148
+ **What to change:** nothing in an app that uses `createWire` with `browserEnv()` or `nodeEnv()` and serves with `serve`, `nisc start`, the vite plugin or `attachSocket`. Otherwise one of the three above. Anything that read `?token=` off the socket's address — a proxy rule, a check — no longer finds it there.
149
+
150
+ - fc50d20: `AGENTS.md` says where files go. Rule 9a: file pickers live in the kit; a file never goes over the socket; the app saves it wherever it wants. The review pass's "no `fetch` outside the endpoint layer" gains its one exception, to send a file. No code changed.
151
+
152
+ A picker that puts a file in its model value sends it over the socket as base64, and the tree brings it back on every render of that canvas. Measured against a moss server: one 15 MB file was 20 MB up and 100 MB down across five renders. Sent by the picker to a route the app mounts on its server, or to a system the app already has, the same file put nothing on the socket.
153
+
154
+ moss gains a test and nothing else: a route an app adds to the built server reads who is asking, as moss's own surfaces do.
155
+
156
+ **What to change:** nothing for the rule itself. But this release also limits a message a terminal sends to 256 KB (the moss entry on the socket's message limit), so a picker that emits a file's bytes as its model value now works only for a file under about 190 KB: send the file from the picker, as rule 9a says, or raise the limit where the app attaches the socket.
157
+
3
158
  ## 0.3.2
4
159
 
5
160
  ### Patch Changes
package/DESIGN.md CHANGED
@@ -135,9 +135,12 @@ compiles it.
135
135
  ## The socket
136
136
 
137
137
  The authority channel. Transport-blind: the protocol speaks through a
138
- four-function `Connection` seam (`send`/`close`/`onMessage`/`onClose`), and the
139
- RFC 6455 plumbing lives with each runtime's entry (`ws` on Node in `./node`,
140
- Bun-native later). One connection per client carries every canvas — ten open
138
+ four-function `Connection` seam (`send`/`close`/`onMessage`/`onClose`, and what
139
+ the upgrade request offered), and the RFC 6455 plumbing lives with each
140
+ runtime's entry (`ws` on Node in `./node`, Bun-native later). Who a terminal is
141
+ is decided on that request, from its headers — a session cookie its browser
142
+ sent, or a token it offers as a subprotocol beside `nisc` — and never from its
143
+ address, which every proxy on the way logs. One connection per client carries every canvas — ten open
141
144
  canvases are ten canvas ids on one pipe.
142
145
 
143
146
  **Down:** `hello` (the resolved catalog on connect, and the protocol the server speaks — the terminal names its own on the upgrade), `catalog` (declared for
@@ -163,11 +166,12 @@ Operational shape, all falling out of "the message is state, not history":
163
166
  same rule holds before the first connect: nothing is sent on a socket that is
164
167
  not open and nothing is held for when it is. A server-drawn page (below) is on
165
168
  screen before its socket, so a press in that moment is dropped.
166
- - **Durability.** The projection (once built) is the durable thing; the shell is
167
- a warm cache rebuilt from definitions + projection. Evicting an idle shell and
168
- restarting the process are both safe — shells rehydrate on the next connection.
169
- This is why an idle sweep can exist at all, and why `reset` costs nothing but
170
- the screen someone was on.
169
+ - **Durability.** The database is the durable thing; a shell is a warm cache,
170
+ rebuilt on the next connection from definitions and whatever the app reads
171
+ from rows as it builds. Evicting an idle shell, restarting the process and
172
+ `reset` cost the same and nothing more: what was only in the shell — the
173
+ screens someone had opened, and what they had typed. This is why an idle
174
+ sweep can exist at all.
171
175
  - **Recovery.** `reset` (up) throws a session's shell away and serves its
172
176
  replacement. It names no canvas, because it is the recovery for a session
173
177
  whose canvases are the broken thing; it is protocol-level, so no action
@@ -192,6 +196,58 @@ Operational shape, all falling out of "the message is state, not history":
192
196
  - **Size.** Two optional reductions — transport compression and frame deltas —
193
197
  sit under the protocol, both off the app's books. See below.
194
198
 
199
+ ### Where a browser keeps its session
200
+
201
+ A terminal served by the app it talks to does not hold its session. Its browser
202
+ does, in a cookie no script can read, and sends it by itself with the two
203
+ requests that need to know who is asking: the page, and the upgrade that opens
204
+ the socket. A token in the page — in storage, in a cookie script can read — is
205
+ there for anything else that runs in the page to take; one the page never has
206
+ cannot be taken from it.
207
+
208
+ - **The answer to the upgrade is where the cookie is written.** A cookie is set
209
+ by an HTTP response and by nothing else, and the upgrade is the one request
210
+ every terminal already makes. So who is asking is decided *before* the
211
+ request is answered, and the answer carries the cookie.
212
+ - **A sign-in over the socket reaches it sealed.** `session.grant` happens on a
213
+ socket, which cannot write a cookie; the token has to travel through the
214
+ page to the next upgrade. It travels encrypted with a key the browser holds
215
+ in a second cookie no script can read or set — the *seal*, given by the
216
+ answer to the browser's first upgrade under a name (`__Http-`) a browser
217
+ lets only an HTTP answer set. The page can hand a sealed sign-in back and
218
+ cannot open it, and neither can anybody it is shown to: without that
219
+ browser's seal it opens nothing. Nothing is kept here between the two
220
+ requests, so it works whichever process answers the second, and it works
221
+ for any credential — moss's own, or an app's provider's. The seal rides only
222
+ the socket's path, so no page request carries it and a page drawn for nobody
223
+ is still the same for everybody.
224
+ - **Only for the app's own page.** A browser sends a cookie with any page's
225
+ request to this host, a stranger's included, and the socket is the whole
226
+ app. So the cookies are read and written only when the request's `Origin` is
227
+ the host it was addressed to (or one `runtime.origins` lists, behind a proxy
228
+ that rewrites `Host`). From anywhere else a terminal is who the token it
229
+ offers says, or nobody.
230
+ - **No route answers to it.** The HTTP surfaces read `Authorization` and
231
+ nothing else, so no request another site can make a browser send does
232
+ anything as the person. A page request does read it — every site may link to
233
+ a page, and none can read the answer.
234
+ - **Its name is the terminal's token key**, so several people can be signed in
235
+ on one origin, each in a seat. It ends with the port when the page is on
236
+ one: a browser keeps cookies by host, not by port, and two apps on localhost
237
+ would sign each other out. Over https it is `__Host-` prefixed and `Secure`,
238
+ which a browser lets nothing but this host set.
239
+ - **What the page sees is a flag** (`<name>.held=1`), with no secret in it: how
240
+ a terminal knows to let go of a token it was holding, and that a page drawn
241
+ for somebody was drawn for it.
242
+ - **Signing out says so.** moss revokes its own credential, and a cookie that
243
+ no longer resolves is taken back on the next upgrade. An app's own provider's
244
+ token may go on resolving, so a terminal that was signed out says it is
245
+ leaving, and the cookie is taken back whatever it holds.
246
+ - **Any other terminal holds its own token** — a process, a page served from
247
+ somewhere else, a browser that refuses cookies — offers it, and is handed a
248
+ sign-in as its token, as before. A token such a page of the app's own offers
249
+ (one an earlier build left in storage) is moved into the cookie and let go of.
250
+
195
251
  ### What a frame costs
196
252
 
197
253
  A server-authored shell pays for its inversion in bytes: every change re-sends
@@ -236,7 +292,11 @@ Three rules keep it honest:
236
292
  everyone — so one encode serves the whole room.
237
293
  2. **Decisively smaller, or whole.** A delta is only sent at ≤60% of the frame.
238
294
  Below that it wins even after deflate; above it, deflate on the whole frame
239
- does as well and the terminal does less work.
295
+ does as well and the terminal does less work. And a frame over 64 KB is not
296
+ compared at all: the encode's cost follows the size of the frames, not of
297
+ the change, on the thread every session shares — about 7 ms at 64 KB, a
298
+ second at 2.7 MB — so past that length, on either side of the change, the
299
+ canvas is sent whole before anything is spent on finding out.
240
300
  3. **Checksummed, always.** Every delta carries a hash of the frame it should
241
301
  rebuild. A terminal that lands anywhere else discards the result and sends
242
302
  `resync` — the failure this layer must not have is a screen that is silently
@@ -389,11 +449,11 @@ Six things had to be true, and each is a small, separate decision:
389
449
  `initializing`" is the shell saying its first screen is complete — a signal
390
450
  that was always there. The wait is bounded (300 ms by default): a document
391
451
  must not hang on a slow integration, and a skeleton is a legitimate screen.
392
- - **Who is asking comes off a cookie**, because a page request carries nothing
393
- else. The wire keeps a copy of the session token there (`browserEnv`'s
394
- `cookie`), and it is read for exactly one thing — choosing whose screen to
395
- draw. Every other surface still wants the token itself, so the copy opens no
396
- door: a cross-site request that carried it could draw a page it cannot read.
452
+ - **Who is asking comes off the browser's session cookie**, because a page
453
+ request carries nothing else (*Where a browser keeps its session*). It is
454
+ read here and never written: the upgrade is where it is set and taken back,
455
+ and one writer cannot disagree with itself. A cross-site request that carried
456
+ it could draw a page it cannot read.
397
457
  - **An anonymous page and its socket are two shells that must name their
398
458
  instances alike.** A principal's page is drawn from their durable shell and
399
459
  the socket attaches to that same shell — same ids, nothing to arrange. Nobody
@@ -599,11 +659,16 @@ On the record, so nothing reads as finished that isn't:
599
659
  drawn for nobody (a file, on a static host) connects, and is served a page
600
660
  shell for as long as it stays — even when that page turns out not to be live
601
661
  for them either. Closing such a connection once its frames are sent is unbuilt.
602
- - **A stricter cookie.** The cookie is a copy of the token, readable by the
603
- page's script like the token itself. An `HttpOnly` one — with the socket
604
- reading it at the upgrade, the token out of the URL and out of script — needs
605
- login to finish over HTTP (a socket message cannot set a cookie) and an Origin
606
- check on the upgrade that does not exist today.
662
+ - **A seal no script can supply, in every browser.** The seal is given by the
663
+ answer to a browser's first upgrade, after the page's script has started; a
664
+ script already running then could set one of its own first, and open the
665
+ sign-in that follows. Its `__Http-` name is what stops that — a browser lets
666
+ only an HTTP answer set it — and a browser that does not know the prefix
667
+ does not stop it. Nor does the name stop a *server* on a sibling subdomain
668
+ from setting one; with a script in the page as well, that is the same
669
+ opening. `__Host-Http-` would close it, and would put the seal on every page
670
+ request, ending the sharing of pages drawn for nobody. Over plain http there
671
+ is no such name, and nothing on the way is private either.
607
672
 
608
673
  ## Boundaries
609
674
 
package/DOCS.md CHANGED
@@ -222,8 +222,10 @@ type NiscRuntime = {
222
222
  pool: PgPool; // SQL
223
223
  db: MutationClient; // writes
224
224
  cache?: CacheBackend; // defaults to vex's postgres cache on `pool`
225
+ vexConfig?: QueryEngineConfig['config']; // the query engine's settings (limits, read timeout); default vex's own
225
226
  session: SessionVerifier | 'sessions' | 'dev-open'; // REQUIRED — no default
226
227
  migrations?: 'apply' | 'verify'; // the boot's ledgered run; default 'apply'
228
+ tables?: readonly Sequence[]; // the app's own table sequences, in that same run
227
229
  shellIdleMs?: number; // idle shell eviction; default 30 min, `0` disables
228
230
  endpointTimeoutMs?: number; // a server shell's endpoint call; default nova's, 30s
229
231
  sessionRevalidateMs?: number; // live-socket re-verify; default 60s, `0` disables
@@ -271,6 +273,38 @@ refuses to boot if anything is, for a deployment that migrates as a deploy step.
271
273
  `initIntegrations` and `initSessions` remain for hosts that are not moss's
272
274
  server, and go through the same ledger.
273
275
 
276
+ `tables` on the runtime hands over the app's own table sequences. They join
277
+ that run after moss's — one transaction, one lock, one posture, so `'verify'`
278
+ covers them. Absent, the app migrates its own tables itself, as before. Another
279
+ owner's tables the app keeps go in the same list (`TIDE_SEQUENCE`), and a
280
+ runtime that hands tables over does not also migrate them itself.
281
+
282
+ #### `migrateTables(runtime, app, { dryRun? }): Promise<TablesReport>`
283
+
284
+ The step that changes tables, for a deployment that migrates before it starts
285
+ (`nisc migrate` calls it). It applies everything pending in the one run,
286
+ whatever `runtime.migrations` says, and before the run may commit it asks
287
+ whether `app`'s entries fit what it leaves: every read is resolved against the
288
+ schema as the transaction sees it, every write is put to the gate vex puts it
289
+ to before it runs (`mutationMisfits`: its table, the columns it writes, its
290
+ WHERE, its lookups, its conflict target, what it reads from an earlier
291
+ statement). An entry that does not fit refuses the run — strata's
292
+ `DOES_NOT_FIT`, each
293
+ reason as `fingerprint: why` — and nothing was applied. It asks on every run,
294
+ so a release that changes an entry and no table is checked too.
295
+
296
+ One kind of entry is said and not refused: one that already did not fit before
297
+ the run and that the database already holds seeded exactly as it is. That is an
298
+ old fault, not this run's. A new or changed entry gets no such pass.
299
+
300
+ `TablesReport` is strata's `{ applied, plan }` plus `removed` (tables and
301
+ columns the run takes away), `retyped` (columns whose type it changes, as
302
+ `table.column (was → now)`) and `alreadyBroken`. `dryRun` does all of it and
303
+ rolls it back.
304
+
305
+ It sees entries and nothing else: not SQL written by hand, not a column a scope
306
+ rule stamps, not what a value means.
307
+
274
308
  **Documents are read in this code's grammars.** Stored integration actions
275
309
  carry a `grammar` stamp (`INTEGRATION_ACTIONS_STORE`). At boot, after the
276
310
  tables, moss upgrades every stored action that is behind — through nova's and
@@ -470,11 +504,15 @@ const page = await renderDocument({
470
504
  ```
471
505
 
472
506
  - **Which shell**: the page `server.page(path)` names, else the app's.
473
- - **For whom**: the principal behind the cookie named by the wire's token key
474
- (`tokenKey`, default `nisc.token`), or nobody. A cookie that no longer
475
- resolves is nobody, and the response takes it back (`Set-Cookie`, `Max-Age=0`).
476
- A verifier that *throws* is a fault, not a sign-out: the page goes out
477
- undrawn and the cookie stays.
507
+ - **For whom**: the principal behind the browser's session cookie for the
508
+ wire's token key (`tokenKey`, default `nisc.token`), or nobody. The cookie's
509
+ name ends with the port a page is on, so `request.host` (the `Host` header)
510
+ is how a page on a port finds it; `mountSite` and the vite plugin pass it.
511
+ Behind a proxy that rewrites `Host` to its upstream, the port `site` names
512
+ is tried too.
513
+ A cookie that no longer resolves is nobody. Nothing is written here — the
514
+ upgrade is where the cookie is set and taken back. A verifier that *throws*
515
+ is a fault, not a sign-out: the page goes out undrawn.
478
516
  - **`draw`** is a terminal that draws to a string — the app's kit bound to
479
517
  `renderSnapshot` from `terminal/react/server`, `terminal/vue/server` or
480
518
  `terminal/dom/server`. It may be async.
@@ -540,6 +578,28 @@ page. `embedSnapshot` writes the snapshot as a
540
578
  (and U+2028/2029) escaped: a tree carries what people typed, and nothing in it
541
579
  can close the element or open another.
542
580
 
581
+ #### `sessionCookies(page, token, options?)`
582
+
583
+ The `Set-Cookie` values that keep `token` in the browser of the page at this
584
+ origin — or, for `null`, take it back. For a sign-in the app answers over HTTP
585
+ (a link redeemed, a provider's callback): set them on the response, and the
586
+ page that follows is signed in having never held the token.
587
+
588
+ ```typescript
589
+ server.get('/login', async (c) => {
590
+ const token = await mintSession(pool, principal, TTL_MS);
591
+ for (const cookie of sessionCookies(c.req.raw, token, { lastsMs: TTL_MS })) c.header('set-cookie', cookie, { append: true });
592
+ return c.redirect('/');
593
+ });
594
+ ```
595
+
596
+ `page` is the request (its `Origin`, else where it was addressed and the
597
+ `X-Forwarded-Proto` it arrived with) or the page's origin as a string.
598
+ `options.key` is the seat (the terminal's `tokenKey`; default `nisc.token`);
599
+ `options.lastsMs` is how long the browser keeps it — left out, until the
600
+ browser closes. A sign-in made over the socket (`session.grant`) needs none of
601
+ this: the answer to the terminal's next upgrade writes the same cookie.
602
+
543
603
  #### `createPageRouter(pages): PageRouter`
544
604
 
545
605
  `{ match(path): { name, params } | undefined }` — the matching rule above, for a
@@ -777,6 +837,18 @@ measures the end.
777
837
  - `Connection` — the transport seam: `{ send, close, onMessage, onClose }`.
778
838
  - `ServerMessage` — `hello | catalog | frame | render | render-delta | session | error`.
779
839
  - `ClientMessage` — `event | publish | resync | reset | back | popTo`.
840
+ - **A message a terminal sends is at most 256 KB**, counted as it is once
841
+ inflated. One over that closes the connection with `1009` — the transport's
842
+ own close, not one of moss's — and what it carried did not arrive: the
843
+ terminal reconnects as after any other close, and a signed-in person's shell
844
+ is as it was. The limit is the Node transport's (`attachSocket`'s
845
+ `maxMessageBytes`, below), and it is a bound on memory, not on speed: the
846
+ server keeps what a message carried — the value in the shell, and again in
847
+ the last frame it sent — and sends it back down in every later frame of that
848
+ canvas. An event is a press, a typed value, a row handed back. A file never
849
+ goes over the socket (AGENTS.md rule 9a): the picker sends it to a route the
850
+ app mounts, or to a system the app already has, and the event carries what
851
+ came back.
780
852
  - `render-delta` is only ever sent to a connection that advertised `?delta=1`
781
853
  on the upgrade, and only when the server is configured for it. Everything
782
854
  else is served whole frames, unchanged. See [Wire size](#wire-size).
@@ -807,18 +879,59 @@ measures the end.
807
879
  failing definitions, then the close. The refusal is that terminal's alone,
808
880
  and reconnecting later is reasonable.
809
881
  - `error` codes: `invalid_token`, `session_failed`, `client_too_old`,
810
- `server_too_old`, `no_shell` (the app serves no shell), `invalid_message`.
882
+ `server_too_old`, `no_shell` (the app serves no shell), `invalid_message`,
883
+ `seal_not_kept` (a sealed sign-in came back with no seal to open it).
884
+ - **Who a terminal is** is decided on the upgrade request, from a header of
885
+ it — never from its address, which is what every proxy on the way writes
886
+ into its log. A terminal offers the subprotocol `nisc`, and beside it its
887
+ token when it holds one: `offerToken(token | null)` returns the list to
888
+ construct the socket with (`new WebSocket(url, offerToken(token))`), and the
889
+ server answers `nisc`. A token in the address (`?token=`) is not read. A
890
+ transport hands the offer over as `connection.upgrade.offered`
891
+ (`Sec-WebSocket-Protocol`, split); one that leaves it out serves every
892
+ terminal as nobody. `attachSocket` does it.
893
+ - **A browser on the app's own page** is who its session cookie says
894
+ ([`sessionCookies`](#sessioncookiespage-token-options)). The cookie is read
895
+ only when the upgrade's `Origin` is the host it was addressed to, or one
896
+ `runtime.origins` lists. (Behind a proxy that rewrites `Host` and with
897
+ nothing listed, no page is the app's own: terminals hold their own tokens,
898
+ as before, and moss says so once in the log.) A token such a page offers is who it is and is
899
+ moved into the cookie by the answer to the upgrade; one that no longer
900
+ resolves is nobody (served, not refused) and is taken back. `?key=` names
901
+ which of the browser's sessions the terminal is — a seat; the cookie is named
902
+ by it. `?leave=1` is a terminal that was signed out: it is nobody whatever
903
+ its browser holds, and the cookie is taken back. A transport passes what the
904
+ request carried as `connection.upgrade` — `{ offered, origin, host, cookie }`
905
+ — and, when it has not answered the request yet, `answer(cookies)`: moss
906
+ calls it once who is asking is decided, with the `Set-Cookie` values to
907
+ answer with. A transport without `answer` reads cookies and writes none.
908
+ - **A sign-in is handed to such a page sealed.** A terminal whose browser can
909
+ keep a session says so (`?sealed=1`; `browserEnv` does), and the answer to
910
+ its first upgrade gives the browser a *seal*: a key in a second cookie no
911
+ script can read — or, over https, set (`__Http-nisc.seal`; `nisc.seal` over
912
+ plain http) — sent only with the socket's path. `session.grant(token)`
913
+ then reaches that terminal as `{ type: 'session', sealed }` — the token,
914
+ encrypted with the seal and good for a minute — which it offers back on its
915
+ next upgrade (`offerToken(null, sealed)`); the browser's seal opens it there
916
+ and the session cookie is written. Offered with another seal, altered, or
917
+ late, it opens nothing and the terminal is nobody. A browser that sent no
918
+ seal to open it with does not keep cookies: the terminal is told
919
+ (`seal_not_kept`), stops asking, and is handed the next sign-in as a token.
920
+ Any other terminal — a process, a page on another origin — is handed
921
+ `{ type: 'session', token }`, as before.
811
922
  - **Protocol version.** `PROTOCOL` is the wire protocol this server speaks and
812
923
  `PROTOCOL_MIN` the oldest it still serves. A terminal names its protocol on
813
- the upgrade (`?protocol=N`, beside the token); one that names none speaks `1`,
814
- which is every terminal built before the question existed. Outside the range
815
- the connection is refused before anything is served: an `error` frame
816
- (`client_too_old` or `server_too_old`) and a `4426` close. `hello` carries
817
- `protocol`, so a terminal can refuse a server older than it can speak to.
818
- Bump `PROTOCOL` when a message changes shape; raise `PROTOCOL_MIN` only when
819
- the server stops speaking an old one. Both are `1` today. `PROTOCOL`,
820
- `PROTOCOL_MIN` and `CLOSE_PROTOCOL_MISMATCH` are defined in `src/socket.ts`
821
- and are not re-exported from the package root.
924
+ the upgrade (`?protocol=N`); one that names none speaks `1`, which is every
925
+ terminal built before the question existed. Outside the range the connection
926
+ is refused before anything is served: an `error` frame (`client_too_old` or
927
+ `server_too_old`) and a `4426` close. `hello` carries `protocol`, so a
928
+ terminal can refuse a server older than it can speak to. Bump `PROTOCOL` when
929
+ a message changes shape; raise `PROTOCOL_MIN` only when the server stops
930
+ speaking an old one. Both are `2` today: at `1` the token rode the address,
931
+ and a server that went on reading it there would keep that open. `PROTOCOL`
932
+ and `offerToken` are exported from the package root, for a terminal written
933
+ by hand; `PROTOCOL_MIN` and `CLOSE_PROTOCOL_MISMATCH` are defined in
934
+ `src/socket.ts` and are not.
822
935
  - **`?path=`** — the path the terminal is on. A path that leads to a page is
823
936
  served that page's shell, built for this connection alone and seeded with the
824
937
  path's parameters; any other path (and no path) is the app's shell. A
@@ -878,6 +991,12 @@ at most 60% of the whole frame. A terminal that never advertises — including
878
991
  every terminal built before this existed — receives whole frames forever, from
879
992
  the same shell, in the same pass. The two kinds of connection coexist.
880
993
 
994
+ **A canvas whose frame is over 64 KB is always sent whole.** Comparing two
995
+ frames costs the server in proportion to their size, not to what changed, and
996
+ it does that work on the thread every session shares — about 7 ms at 64 KB, a
997
+ second at 2.7 MB. So when the frame a terminal holds, or the one replacing it,
998
+ is longer than 64 KB, the server does not compare them. It is not a setting.
999
+
881
1000
  What it buys, measured on Lyra:
882
1001
 
883
1002
  | change | delta, as a share of the whole frame |
@@ -906,10 +1025,19 @@ Correctness, which matters more than the saving:
906
1025
  in one process. `port` defaults to 8787.
907
1026
  - `attachSocket(httpServer, accept, path?, options?)` — embed the socket on an
908
1027
  existing server (raw `ws`, `noServer`, path-matched — coexists with vite
909
- HMR). `path` defaults to `/socket`. `options = { compression? }` is the same
910
- value as `runtime.socketCompression` and defaults to `true`; `serve()` passes
911
- the runtime's through for you, so only a host running its own listener (a
912
- vite plugin, a dev check) ever needs it.
1028
+ HMR). `path` defaults to `/socket`. `options = { compression?,
1029
+ maxMessageBytes? }`. `compression` is the same value as
1030
+ `runtime.socketCompression` and defaults to `true`; `serve()` passes the
1031
+ runtime's through for you, so only a host running its own listener (a vite
1032
+ plugin, a dev check) ever needs it. `maxMessageBytes` is the largest message
1033
+ a connection may send, in bytes, and defaults to 256 KB (`256 * 1024`); a
1034
+ message over it closes that connection with `1009`. It is handed to `ws` as
1035
+ `maxPayload`, whose own default was 100 MiB. Only a host that calls
1036
+ `attachSocket` itself can raise it: `serve()`, `nisc start` and the dev
1037
+ plugin take the default.
1038
+ - A frame the transport refuses — malformed, not UTF-8, over the limit — ends
1039
+ that connection (`1002`, `1007`, `1009`) and logs one line; no other
1040
+ connection is touched.
913
1041
 
914
1042
  - `mountSite(server, { dist, draw, htmlAttributes?, site?, tokenKey?, waitMs?, owned? })`
915
1043
  — the built terminal, served by the same process as the app. Every GET that
@@ -946,8 +1074,8 @@ Requires the optional `vite` peer.
946
1074
  - `options.app(load): Promise<DevApp>` — stand the app up. `load` is vite's
947
1075
  `ssrLoadModule`. `DevApp = { server, close?, draw?, htmlAttributes?,
948
1076
  site?, tokenKey?, signIn? }`; absent `draw`, pages go out undrawn.
949
- - `signIn(who)` enables `/dev/as/<who>`: it stores the returned token (and
950
- its cookie copy) and goes to `/`. `null` is nobody of that name.
1077
+ - `signIn(who)` enables `/dev/as/<who>`: it puts the returned token in the
1078
+ browser's session cookie and goes to `/`. `null` is nobody of that name.
951
1079
  - `watch?: RegExp` (default: `src/app`, `src/server`, `src/db`, `src/ui` and
952
1080
  the nisc config), `index?` (default `index.html`), `owned?` (default
953
1081
  `MOSS_PATHS`), `label?` (default `moss`).
@@ -959,19 +1087,26 @@ Requires the optional `vite` peer.
959
1087
  host-shaped comes in as a `WireEnv`. `delta` (default `false`) advertises
960
1088
  that this terminal can rebuild frame deltas; the snapshot it produces is
961
1089
  identical either way. See [Wire size](#wire-size).
962
- - `WireEnv` — the host seam: `{ tokens: { load, save, clear }, socket(url),
963
- defaultUrl() }`. The socket API is WHATWG-standard in every host (browser,
964
- Node ≥22, Bun); an env only constructs it.
965
- - `browserEnv({ tokenKey?, cookie? }?): WireEnv` — the default host: token in
966
- localStorage (`nisc.token`), url derived from `window.location`, the
967
- page's WebSocket. `cookie: true` keeps a **copy** of the token in a cookie of
968
- the same name (`Path=/; SameSite=Lax`, `Secure` on https), written and
969
- cleared with the stored one and levelled with it on every load — so a token
970
- put in localStorage by something else (a sign-in handoff page) reaches the
971
- cookie on the first load after it. A page request carries cookies and nothing
972
- else; this is what lets a server draw the page for whoever is asking. The
973
- cookie is only ever read to draw a page — every other surface still wants the
974
- token itself — so it adds no way in.
1090
+ - `WireEnv` — the host seam: `{ tokens: { load, save, clear, held?, key? },
1091
+ socket({ url, offered }), defaultUrl() }`. The socket API is WHATWG-standard
1092
+ in every host (browser, Node ≥22, Bun); an env only constructs it —
1093
+ `new WebSocket(url, offered)`. What is offered is who the terminal is, so an
1094
+ env that drops it connects as nobody. `held()` is for a host whose browser
1095
+ may keep the session itself: asked after an upgrade is answered, `true`
1096
+ makes the wire let go of the token it offered, `false` makes it store it. A
1097
+ host with `held` also asks to be handed sign-ins sealed. A host without it
1098
+ stores a token as soon as it is handed one. `key` names the terminal's seat
1099
+ in the socket's address.
1100
+ - `browserEnv({ tokenKey?, cookie? }?): WireEnv` — the default host: url
1101
+ derived from `window.location`, the page's WebSocket, and the session
1102
+ wherever the page can have it kept. Served by the app it talks to, the page
1103
+ does not keep it: the browser does, in a cookie the page cannot read, and
1104
+ `held` reads the flag beside it. Anywhere else — another origin, a browser
1105
+ that refuses cookies — the token is in localStorage under `tokenKey`
1106
+ (default `nisc.token`). `tokenKey` is also the seat, and the cookie's name.
1107
+ `cookie` is accepted and does nothing: it kept a script-readable copy of the
1108
+ token for the server to draw the page from, and the page is now drawn from
1109
+ the browser's own cookie.
975
1110
  - `readDocumentSnapshot(doc?): DocumentSnapshot | undefined` — the snapshot a
976
1111
  server-drawn page carries (`{ frame, trees, principal, seed?, path?, live? }`),
977
1112
  or `undefined` for a page that carries none. Never throws. `principal` is a
@@ -1029,7 +1164,7 @@ outage ago.
1029
1164
 
1030
1165
  ```typescript
1031
1166
  import { createWire } from '@niscorp/moss/client';
1032
- const wire = createWire(); // browser host; token from localStorage
1167
+ const wire = createWire(); // browser host; the session is the browser's to keep
1033
1168
  wire.subscribe(() => render(wire.snapshot()));
1034
1169
  wire.dispatch('main', { type: 'ui:click', ref: 'save' });
1035
1170
  ```