nervur 0.22.2-3 → 0.22.2-4

package/AUTHORING.md

@@ -144,6 +144,12 @@ and TypeScript reads from it the types of her cells and her needs.
 | `roles` | named tests over the asker and her cells |
 | `state` | a function of the being that names her current state |
 | `asks` | one entry per method she answers |
+| `view` | markup as text over her asks, which a screen renders |
+
+A view is data, at most 64 KiB, carried in her describe to every asker.
+It holds no script, and a renderer loads nothing it names, so a view
+neither acts nor tracks. The library defines no markup: a renderer
+speaks its own.
 
 Every field is optional but `kind` and `asks`. A class with no `state`
 has one state, named `ready`. The kind is how the house finds her code
@@ -195,7 +201,7 @@ nothing lands.
 | `this.house.alarm({ at, ask, args, key })` | one of her asks, at that time |
 | `this.house.cancelAlarm({ key })` | an alarm removed |
 | `this.<need>.<method>({…}, { reply? })` | an awaited call, or an effect |
-| `this.held(id, Need).<ask>({…}, { reply? })` | the same, on a standing |
+| `this.held(id, Need).<ask>({…}, { reply?, after? })` | the same, on a standing, and a watch where `after` is given |
 | `this.standings` | `list()`, `note(id, notes)` and `drop(id)` |
 | `this.handle(ask, { bind?, notes?, once?, expires? })` | a handle to one of her asks |
 | `this.invite(id, { notes?, expires? })` | a new occupant, as a handle |
@@ -239,6 +245,29 @@ one receiver leave one at a time, in the order she called them.
 Asks to one being run one at a time, in the order they arrive. A
 `readOnly` ask runs beside that queue, on the cells last landed.
 
+### Watching an answer
+
+A watch is a `readOnly` ask asked with `after`, the answer you already
+hold. The house answers at once where the answer differs. Where it is
+the same, the house holds the ask and runs it again each time an ask of
+that being lands. It answers the first answer that differs, or the same
+one when the wait runs out. So a chat, an order's status or a dashboard
+is a loop of watches, and nothing polls.
+
+Through the hand, pass `after` beside the method, as the answer you
+hold: `{ result: [...] }`. From a being, pass the result she holds:
+`this.held(room, Messages).messages({}, { after: seen })`, inside a
+`readOnly` ask of her own, so she stays free while she waits. Only a
+`readOnly` ask is watched, and a watch on anything else is refused where
+she makes it.
+
+A watch moves only on what its asker could read, since it runs as that
+asker. One asker holds one watch on one ask with the same args, and a
+second answers the first at once. A watch across a door holds its
+relation until it answers, since Quo moves a relation one ask at a time.
+So watch a far being through a handle to the watched ask alone, a
+relation of its own, and ask everything else on your other standing.
+
 ### Relations
 
 An **occupant** is someone who may ask her. She mints one with
@@ -719,6 +748,50 @@ A user unit stops when its user logs out, unless lingering is enabled
 with `loginctl enable-linger`. On macOS, the agent goes to
 `~/Library/LaunchAgents/` and is started with `launchctl bootstrap`.
 
+### In a page
+
+`BrowserGround.open({ recipe })` from `nervur/browser` runs the same
+houses in a page. Every tab and the service worker of one origin share
+one ground: the one holding the Web Lock runs it, and the others reach
+its hand over a `BroadcastChannel`. When it closes, the next opens the
+ground from the same storage. `hand` answers the same three requests
+the command sends: `describe`, a faculty's method, and an ask of a being
+in a named house.
+
+Its bodies are the browser's. Seeds are sealed under an AES key that
+IndexedDB holds unextractable, and memory is IndexedDB, named
+`indexeddb` in an entry. Classes load from the page's own origin through
+the `origin` body, `{ body: 'origin', at: '/house/index.js' }`, and a
+path off the origin is refused. The recipe is the object you pass: its
+faculties, made by a function, and any custom body.
+
+Any script on the origin can use the ground's keys, so the ground is
+whoever serves the origin's script. Give it an origin of its own, serve
+nothing a stranger wrote there, and set a strict content security
+policy. The page and the house's module must share one copy of
+`nervur/being`, since a house knows a class by a mark that module gives.
+A bundler's shared chunk or an import map gives the one copy.
+
+A service worker opens the ground the same way, on a push, where no tab
+runs it. It may not `import()`, so hand it the modules it imported
+itself: `platform: { load: (href) => modules[new URL(href).pathname] }`.
+
+### In an app
+
+`AppGround.open({ shell })` from `nervur/app` is a BrowserGround in the
+app's web view, on two interfaces the shell fills in native code:
+
+- `NativeSecrets`: `get(name)` and `set(name, value)`, text kept by the
+  iOS Keychain or the Android Keystore on this device alone.
+- `NativeStore`: `get(key)`, `keys(prefix)`, and `swap(writes, expect)`,
+  which lands every write only where each key in `expect` still holds
+  what it names, and answers whether it landed.
+
+The library holds the rest. Each house's seed goes into the secret
+store, and each memory into the native store, which the system never
+evicts as it may a web view's storage. A push token reaches the ground
+through a faculty your recipe makes.
+
 ## What the house guarantees
 
 1. **Every need is covered, or she is absent.** An absent being answers

package/README.md

@@ -107,6 +107,39 @@ the house's seed, its ledger and its record in `state/`, readable by
 you alone. Keep that folder secret: a house opens on no other seed.
 `npx nervur help` lists everything the ground offers.
 
+## A ground in a page
+
+The same house runs in a browser. Bundle the house's module and serve it
+on your origin, beside a page that opens the ground.
+
+```ts
+// page.ts
+import { BrowserGround } from 'nervur/browser';
+
+// Every tab of this origin joins one ground, and the tab holding its lock runs it.
+const ground = await BrowserGround.open();
+
+// The house's code is a module on this origin, and its rows live in IndexedDB.
+await ground.hand({
+  faculty: 'houses',
+  method: 'add',
+  args: { name: 'main', memory: { body: 'indexeddb' }, classes: { body: 'origin', at: '/house/index.js' } },
+});
+
+console.log(await ground.hand({ house: 'main', method: 'hello', args: { name: 'Ada' } }));
+```
+
+Every tab of the origin reaches the one ground, and when the tab running
+it closes, the next opens it from the same storage. Its seeds are sealed
+under a key the browser never hands out. Any script on the origin can
+use them, so give the ground an origin of its own, with a strict content
+security policy. The page and the house's module must share one copy of
+`nervur/being`, as a bundler's shared chunk gives.
+
+An app on a phone opens the same ground with `AppGround` from
+`nervur/app`, on the Keychain or the Keystore and a store the system
+keeps. `AUTHORING.md` shows both.
+
 ## Entries
 
 | Entry | For |
@@ -114,6 +147,9 @@ you alone. Keep that folder secret: a house opens on no other seed.
 | `nervur/being` | writing a being: `Being`, `s`, `need`, `Args`, `Result` |
 | `nervur` | any engine: `Ground`, `House` and the bodies they take |
 | `nervur/node` | a ground on Node: `NodeGround`, the `nervur` command, and its bodies |
+| `nervur/browser` | a ground in a page or its service worker: `BrowserGround` and its bodies |
+| `nervur/app` | a ground in a phone's app: `AppGround`, and the two interfaces its shell fills |
+| `nervur/serve` | a faculty's program in JavaScript: `serve` |
 | `nervur/bench` | tests: `Bench`, `BenchGround`, `FakeNetwork` and the fakes of every body |
 
 ## License

package/dist/browser/browser-ground.js

@@ -40,6 +40,8 @@ export class BrowserGround {
     // Asks sent to another page's ground, by id, with the page they went to.
     #pending = new Map();
     #ground;
+    // The custody and the memories its boot opened, each closed when it closes.
+    #opened = [];
     #persisted = false;
     #leader;
     #waiting = [];
@@ -178,8 +180,13 @@ export class BrowserGround {
         const name = this.#name;
         const platform = this.#platform;
         const recipe = this.#options.recipe ?? {};
-        const custody = await platform.custody(`${name}-custody`);
-        const memory = await platform.memory(`${name}-ground`);
+        // Every store it opens is kept, so its close lets each go before the lock passes.
+        const kept = (opened) => {
+            this.#opened.push(opened);
+            return opened;
+        };
+        const custody = kept(await platform.custody(`${name}-custody`));
+        const memory = kept(await platform.memory(`${name}-ground`));
         this.#persisted = await platform.persist().catch(() => false);
         // It only dials, so it writes no address into an invitation.
         const web = new WebCarry({ allowPrivate: this.#options.allowPrivate === true });
@@ -188,7 +195,7 @@ export class BrowserGround {
         for (const [faculty, made] of Object.entries(recipe.faculties?.() ?? {}))
             faculties[faculty] = await made;
         const bodies = {
-            memory: joined({ indexeddb: ({ house }) => platform.memory(`${name}-house-${house}`) }, recipe.bodies?.memory),
+            memory: joined({ indexeddb: async ({ house }) => kept(await platform.memory(`${name}-house-${house}`)) }, recipe.bodies?.memory),
             classes: joined({
                 origin: ({ args }) => {
                     if (typeof args.at !== 'string')
@@ -209,6 +216,9 @@ export class BrowserGround {
         const ground = this.#ground;
         this.#ground = undefined;
         await ground?.close();
+        // Its IndexedDB connections go with it, so the next ground in this page opens on none of its.
+        for (const opened of this.#opened.splice(0))
+            opened.close?.();
         this.#release?.();
         this.#orphan(() => true);
         for (const resolve of this.#waiting)

package/dist/browser/locked-custody.d.ts

@@ -19,6 +19,8 @@ export declare class LockedCustody implements Custody {
     constructor(shelf: Shelf, subtle?: SubtleCrypto);
     /** The custody of the origin, on a shelf in IndexedDB named `name`. */
     static open(name?: string, factory?: IDBFactory): Promise<LockedCustody>;
+    /** Its shelf let go, where the shelf holds a connection. */
+    close(): void;
     keys({ house }: {
         house: string;
     }): Promise<Keys>;

package/dist/browser/locked-custody.js

@@ -54,6 +54,10 @@ export class LockedCustody {
     static async open(name = 'nervur-custody', factory = indexedDB) {
         return new LockedCustody(await IndexedDbShelf.open(name, factory));
     }
+    /** Its shelf let go, where the shelf holds a connection. */
+    close() {
+        this.#shelf.close?.();
+    }
     keys({ house }) {
         if (!NAME.test(house))
             return Promise.reject(new TypeError(`no house is named ${house}`));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nervur",
-  "version": "0.22.2-3",
+  "version": "0.22.2-4",
   "description": "Nervur's kit of Quo: write beings and faculties, and open the house that holds them on any ground.",
   "keywords": [
     "quo",
@@ -69,7 +69,7 @@
     "build": "rm -rf dist && tsc -p tsconfig.build.json",
     "prepack": "npm run build",
     "check": "tsc -p tsconfig.json && tsc -p tsconfig.pure.json && node test.mjs \"test/**/*.test.ts\"",
-    "deep": "tsc -p tsconfig.deep.json && NERVUR_TEST_CAP=900000 node test.mjs \"deep/**/*.test.ts\"",
+    "deep": "tsc -p deep && NERVUR_TEST_CAP=900000 node test.mjs \"deep/**/*.test.ts\"",
     "prepublishOnly": "test \"$NERVUR_GATED\" = 1 || { echo 'a publish is /release, from the root, on the human'\"'\"'s word' >&2; exit 1; }"
   },
   "engines": {