@quo-systems/dock 0.2.2 → 0.2.4

package/human/quo-human.md

@@ -19,10 +19,89 @@ gets a screen it did not describe.
 Three sides, one describe. The CLI, the model side and the screen are three
 views of the same beings, and the screen adds no vocabulary of its own:
 what a being can be asked is her blueprint, how she wants to be shown is
-her `look`, and both are values that travel through the relation. A world
-that wants a page of its own writes any HTML, CSS and JavaScript it likes on
-its own origin, against the avatar's handles and nothing else; a world that
-writes none gets this screen.
+her `look`, and both are values that travel through the relation. A being
+who wants more than forms answers `page`, her page as a tree of values in
+one closed grammar, and the screen paints it; a being who answers nothing
+gets the forms. A world that wants a page of its own writes any HTML, CSS
+and JavaScript it likes on its own origin, against the avatar's handles and
+nothing else; a world that writes none gets this screen.
+
+## The page
+
+The front end is a ward, and the first move towards it: a page is a tree of
+values in a closed grammar the dock owns, `tree.ts`, and a far being
+answers it from `page` the way she answers `look`, values only. One
+grammar, two sources: the same tree will be computed in the tab by a being
+running there, from her cells, and painted by the same painter.
+
+- **The grammar.** `stack` and `row` hold children, one under another or
+  side by side; `text` is words with a role, `title`, `lead`, `body`,
+  `quiet` or `label`; `image` is a picture as a data URI, never a URL;
+  `form` is one of her asks by name, painted as the form the schema gives;
+  `answer` is one of her asks' last answer, shown as `auto`, `text`,
+  `table`, `cards` or `list`; `standing` is one standing she carries,
+  painted as its section; `standings` is every one of them. No selector, no
+  URL, no stylesheet, no script, and no node beyond these: a node that fails
+  its shape is dropped, not fixed, and a container with nothing left is kept
+  empty, since an empty region is a design and not a fault.
+- **A page adds no right.** Every name a tree uses, an ask or a standing,
+  is looked up in her describe for this asker; a name that is not there
+  paints as nothing. Her page says what is shown and where, and her gate
+  says what may be asked; a device that may not wake sees no `push` form
+  however her page names it, and an ask her describe holds but her page
+  does not name has no form. `hello` and `report` are wiring, a device's
+  first word and an agent's callback, and stay under the gate and off her
+  page.
+- **What opens with the page.** The answers a tree shows are run on open
+  when the ask needs nothing typed, beside the read-only asks her look
+  marks, so the page opens with what it shows.
+- **The page is presentation.** `page` is asked once per digest, like
+  `look`; it is never a form, never a tool, and a carrier never carries it.
+  The user being answers one: her name as the title, who this device is as
+  an answer, her standings as sections, and the two things a human does
+  here by hand, waking another device and calling her by a name, as forms.
+  A being does not know her own key, so her name is given: by the desk's
+  first hello at the root's setup, or by a device the root minted, through
+  her `name` ask, the trunk's rule.
+- **The door is the first page in the grammar**, painted with nobody behind
+  it: no ask, no answer, no standing, only the mark, a word and a sentence.
+
+## The tab ward
+
+A world's code runs in the tab, as beings. The second source of the one
+grammar: a being booted in the tab's local ward for a world answers `page`
+from her cells, and the same side paints her with the same painter. No
+second verb, no framework, no script of the world's on the page: only
+classes, and the ward runs them.
+
+- **The world's code is a module the harbor folder holds**, `tab/index.ts`,
+  the twin of `classes/index.ts`: the classes meant for the tab, exported
+  by name. The web route bundles it as `beings.js` on the world's origin
+  and tells the page it exists; a folder with none has no such path. Code
+  crosses the origin, never a relation, and one origin is one world's code.
+- **The boot at join.** The tab loads the world's classes before its harbor
+  boots, since a being kept from the last visit is booted by her class
+  name. When a relation goes on screen, the tab boots one being of each
+  class under that relation's key, `r1-Notes`, the first time, and finds
+  her there after: her cells are in the ward, kept in the tab's store after
+  every ask and migrating with the ward. Two relations in one world are two
+  of each, since what she keeps is one person's.
+- **A subject with no standing.** The side holds her object and speaks to
+  her door in-process under the tab's own asker, `local.ts`, the way it
+  holds an avatar: no relation, no key rotation, since the local ward is
+  the human's and she is on it. Her describe is what she shows the tab, her
+  forms are her asks, and a push never reaches her, since nothing outside
+  the tab holds her.
+- **Her page follows every ask.** `page` is asked again after each call
+  and the answers it shows are run again with it, so a cell moved is a page
+  moved whether or not her describe moved. The describe, the look and the
+  read-only asks off the page stay once per digest. A far being pays the
+  same: her page is never more than one ask behind her.
+- **One section each.** Under the far being's page, each being of the world
+  has her own section and her own side; the shell's own heading is dropped
+  wherever a page carries its title. Slots that bind her page to a
+  standing she holds, and the shadow root that isolates a far page, are
+  the next part of the same design.
 
 ## How a screen is made
 
@@ -47,12 +126,13 @@ Read with the trunk's "Carrying" and "The look", which this applies.
   and acme sees the human, never the device. The same section appears on
   acme's own web, under the same look: one component, two relations.
 - **The page follows the digest.** The side asks the describe again after
-  every call and asks `look` once per digest; a digest that moved is a page
-  that moved. A read-only ask with nothing to type is run on open, so a page
-  can open with what it shows and not only with buttons. Every one of those
-  asks rotates her keys, so the side saves after each, not only after a
-  form: a relation brought back from a reload with a stale count is refused
-  at the far door and hears silence.
+  every call, asks `look` once per digest and `page` after every call; a
+  digest that moved is a page that moved, and so is a cell that moved
+  behind a page. A read-only ask with nothing to type is run on open,
+  so a page can open with what it shows and not only with buttons. Every one
+  of those asks rotates her keys, so the side saves after each, not only
+  after a form: a relation brought back from a reload with a stale count is
+  refused at the far door and hears silence.
 - **What a look may carry, and never.** The trunk's table is the whole
   list: a name, a logo as a data URI, three colours, a font, a radius, an
   order, a hint per ask. No CSS, no URL, no script, ever. A token that fails
@@ -104,18 +184,29 @@ Read with the trunk's "Carrying" and "The look", which this applies.
 
 ## The pieces
 
-Eight files under `packages/dock/human/`:
+Ten files under `packages/dock/human/`:
+
+- `local.ts` is a being of the world in the tab's own ward as a subject:
+  her door spoken to in-process under the tab's asker, no standing.
 
+- `tree.ts` is the page grammar and its painter, pure: `sanitiseTree`
+  holds a value to the grammar or drops it, `answersIn` names what a tree
+  shows the answers of, `paint` writes a tree as HTML through a painter,
+  and `nobody` is the painter with nothing behind it.
 - `html.ts` is pure, strings in and strings out, and is the screen's whole
   vocabulary: `form`, `values`, `view`, `face`, `look`, `page`. It reads the
-  look's vocabulary from `beings/look.ts` and adds none.
+  look's vocabulary from `beings/look.ts` and the grammar from `tree.ts`
+  and adds none; its painter looks every name a tree uses up in her
+  describe.
 - `screen.ts` is the side: one avatar and one surface, where a surface can
   only show a page and hand back a submitted form. It keeps the model,
   speaks it as a page after every change, calls her when a form comes back,
-  re-asks her describe after every call, asks her look once per digest, and
-  runs her read-only asks on open. A push is appended and shown as it
-  lands. A describe that fails leaves the last page standing and says so in
-  the notice.
+  re-asks her describe after every call, asks her look once per digest and
+  her page after every call, and runs her read-only asks once per digest
+  and the ones her page shows the answers of after every call. A push is
+  appended and shown as it lands. A
+  describe that fails leaves the last page standing and says so in the
+  notice.
 - `dom.ts` is the surface on an element, the one file that touches one.
 - `guest.ts` is a world's public being as a subject the screen renders:
   her describe for a stranger, a form as a knock on the public invitation.
@@ -123,7 +214,8 @@ Eight files under `packages/dock/human/`:
   sight: the local ward for a far pk, the relations in it, and a fresh
   avatar for the next way in.
 - `door.ts` is the door page, pure: what a stranger sees where nothing
-  lets them in, Quo's page and not the estate's, asking for nothing.
+  lets them in, Quo's page and not the estate's, asking for nothing,
+  written as a tree and painted with nobody behind it.
 - `tab.ts` is the shell: the harbor in the tab, the config, the two
   switchers and the two ways in, and hands one avatar at a time to the
   side.
@@ -134,7 +226,10 @@ Eight files under `packages/dock/human/`:
   it does not take fall through to the exchange pages.
 
 Proven in `packages/dock/test/human.test.ts` on the memory harbor with a fake
-surface and no browser: the user being carrying a shop with a look, a guest
+surface and no browser: the grammar held and painted, the user being's page
+with what her gate hides painted as nothing, a being of the world in the
+tab's ward paged from her cells and kept with them, the user being
+carrying a shop with a look, a guest
 at a door that is not a desk let in by a form, the link read, stripped and
 refused, and the worlds and relations on a harbor core over the memory
 store, two invitations into one world being two avatars; and in
@@ -148,7 +243,7 @@ door, and a link at the root.
 ## Security, by structure
 
 - Nothing executable crosses. What a screen receives is I-JSON, by the
-  spec: asks, args, answers, the three words, and a look. Every string is
+  spec: asks, args, answers, the three words, a look and a page. Every string is
   escaped before it is written into the page; a JSON box is parsed and never
   evaluated.
 - A look is a closed vocabulary held to shapes. A logo is a data URI, so no

package/human/screen.ts

@@ -12,6 +12,7 @@ import { word, type Serving, type Subject } from '../beings/side.ts';
 import { isInvitation } from '../beings/link.ts';
 import type { Invitation } from '@quo-systems/quo';
 import { page, values, hintFor, type Model, type Raw } from './html.ts';
+import { sanitiseTree, answersIn } from './tree.ts';
 import { sanitise } from '../beings/look.ts';
 import { isSilence, isWord } from '@quo-systems/quo';
 import type { Json } from '@quo-systems/quo';
@@ -35,7 +36,7 @@ export type Options = { after?: () => Promise<void>; notice?: string; admit?: (i
 export async function screenSide(avatar: Subject, surface: Surface, options: Options = {}): Promise<Serving & { model: Model; refresh(): Promise<void> }> {
   const after = options.after ?? (async () => {});
   const notice = options.notice ?? '';
-  const model: Model = { blueprint: null, look: {}, notice, answers: {}, pushes: [] };
+  const model: Model = { blueprint: null, look: {}, tree: null, notice, answers: {}, pushes: [] };
   let seen: string | null = null;
   const show = () => surface.show(page(model));
 
@@ -48,7 +49,8 @@ export async function screenSide(avatar: Subject, surface: Surface, options: Opt
       model.notice = `not in: ${bp.error}`;
     } else {
       const d = await digest(bp as Blueprint);
-      if (d !== seen) {
+      const moved = d !== seen;
+      if (moved) {
         seen = d;
         model.blueprint = bp as Blueprint;
         for (const k of Object.keys(model.answers)) if (!(bp as Blueprint).asks.some((a) => a.name === k)) delete model.answers[k];
@@ -57,11 +59,23 @@ export async function screenSide(avatar: Subject, surface: Surface, options: Opt
           const l = await avatar.call('look');
           model.look = isSilence(l) || isWord(l) ? {} : sanitise(l as Json);
         } else model.look = {};
-        // a read-only ask that needs nothing typed is run on her behalf, so the page opens with what it shows
-        for (const a of (bp as Blueprint).asks) {
-          const needs = ((a.input as { required?: string[] }).required ?? []).length > 0;
-          if (hintFor(bp as Blueprint, model.look, a.name).readOnly && !needs && !(a.name in model.answers)) model.answers[a.name] = word(await avatar.call(a.name, {}));
-        }
+      }
+      // her page, after every ask: a tree of values from what she holds now, or nothing and her asks
+      // are forms. A cell moved is a page moved, and her describe need not have; so the answers the
+      // page shows are run again with it, and the page never stands more than one ask behind her
+      const shows = new Set(model.tree ? answersIn(model.tree) : []);
+      if ((bp as Blueprint).asks.some((a) => a.name === 'page')) {
+        const t = await avatar.call('page');
+        model.tree = isSilence(t) || isWord(t) ? null : sanitiseTree(t as Json);
+      } else model.tree = null;
+      const wanted = new Set(model.tree ? answersIn(model.tree) : []);
+      for (const n of shows) if (wanted.has(n)) delete model.answers[n];
+      // a read-only ask that needs nothing typed is run on her behalf once per digest, and one her page
+      // shows the answer of after every ask, so the page opens and stays with what it shows
+      for (const a of (bp as Blueprint).asks) {
+        const needs = ((a.input as { required?: string[] }).required ?? []).length > 0;
+        const run = wanted.has(a.name) || (moved && hintFor(bp as Blueprint, model.look, a.name).readOnly);
+        if (run && !needs && !(a.name in model.answers)) model.answers[a.name] = word(await avatar.call(a.name, {}));
       }
     }
     await after();

package/human/tab.ts

@@ -33,11 +33,14 @@ import { domSurface } from './dom.ts';
 import { guest } from './guest.ts';
 import { door } from './door.ts';
 import { world, relations, fresh, type Relation } from './worlds.ts';
+import { local } from './local.ts';
+import type { BeingClass } from '@quo-systems/quo';
 
 // What the page is told by the daemon that served it: the world's routes,
 // every ward on that harbor by name, its pk and whether a public being is
-// at its door, and which of them this page is, if it is one's.
-export type Config = { quo: string; web: string; wards: Record<string, { pk: string; public: boolean }>; ward?: string };
+// at its door, which of them this page is, if it is one's, and whether the
+// world serves code for the tab.
+export type Config = { quo: string; web: string; wards: Record<string, { pk: string; public: boolean }>; ward?: string; beings?: boolean };
 
 // What the tab remembers between pages, beside the harbor: the worlds it
 // has joined, by pk, where each lives and what it is called; which relation
@@ -85,7 +88,20 @@ export async function start(cfg: Config, root: HTMLElement = document.body): Pro
   const say = (s: string) => (status.textContent = s);
 
   // The harbor in the tab: one database per origin, one ward per world.
+  // The world's code first, when its origin serves any: the classes for
+  // the tab, handed to the harbor beside the built-in ones before any ward
+  // boots, since a being kept from the last visit is booted by class name.
+  // A world that serves none has no beings in the tab, and the page is the
+  // far being's alone.
   const harbor = new BrowserHarbor('quo');
+  const classes = cfg.beings
+    ? await import(`${cfg.web}/beings.js`).then((mod: Record<string, unknown>) => {
+        const out: Record<string, BeingClass> = {};
+        for (const [name, v] of Object.entries(mod)) if (typeof v === 'function' && 'prototype' in v) out[name] = v as BeingClass;
+        return out;
+      })
+    : {};
+  Object.assign(harbor.classes, classes);
   await harbor.boot();
   harbor.dial(cfg.quo);
 
@@ -138,16 +154,43 @@ export async function start(cfg: Config, root: HTMLElement = document.body): Pro
     }
   };
 
-  // In, as one relation: her page. Every call rotates her keys and a
-  // same-ward ask never crosses the harbor, so the side saves after each.
+  // The world's beings in the tab, for one relation: one of each class,
+  // booted under her key the first time and found there after, since their
+  // cells are in the ward and come back with it. Each is a subject of her
+  // own with her own side in her own section, so a note she keeps and a
+  // form she shows are hers, painted by the same painter as the far page.
+  const locals: { close(): Promise<void> }[] = [];
+  const boot = async (rel: Relation) => {
+    const beings = (ward.partition as { beings?: Record<string, unknown> }).beings ?? {};
+    for (const name of Object.keys(classes)) {
+      const key = `${rel.key}-${name}`;
+      if (!beings[key]) {
+        const out = (await ward.ask('boot', { key, class: name })) as { error?: string };
+        if (out.error) continue;
+        await ward.save();
+      }
+      const being = ward.being(key) as Parameters<typeof local>[0] | undefined;
+      if (!being) continue;
+      const section = el('section', '', { class: 'local', 'data-being': key });
+      screen.append(section);
+      locals.push(await screenSide(local(being), domSurface(section), { after: () => ward.save() }));
+    }
+  };
+
+  // In, as one relation: her page, then the world's beings for her. Every
+  // call rotates her keys and a same-ward ask never crosses the harbor, so
+  // the side saves after each.
   const inside = async (rel: Relation, notice: string, called: string) => {
     await side?.close();
+    for (const l of locals.splice(0)) await l.close();
     status.remove();
     root.querySelector('form.password')?.remove();
     screen.replaceChildren();
     current = rel;
     keep(AT(pk), rel.key);
-    const s = await screenSide(rel.avatar, domSurface(screen), { after: () => ward.save(), notice });
+    const mine = el('div', '', { class: 'far' });
+    screen.append(mine);
+    const s = await screenSide(rel.avatar, domSurface(mine), { after: () => ward.save(), notice });
     side = s;
     const bp = s.model.blueprint;
     const notesName = typeof (bp?.notes as JsonObject | null)?.name === 'string' ? ((bp!.notes as JsonObject).name as string) : '';
@@ -155,6 +198,7 @@ export async function start(cfg: Config, root: HTMLElement = document.body): Pro
     if (!names()[rel.key]) keep(NAMES(pk), { ...names(), [rel.key]: called });
     switcher();
     people();
+    await boot(rel);
   };
 
   // The way in, from any of the three: a fresh avatar joins, the ward is
@@ -177,6 +221,7 @@ export async function start(cfg: Config, root: HTMLElement = document.body): Pro
   // there, the door page: a link is the only way in, and nothing to type.
   const atDoor = async () => {
     await side?.close();
+    for (const l of locals.splice(0)) await l.close();
     side = null;
     current = null;
     screen.replaceChildren();

package/human/tree.ts

@@ -0,0 +1,129 @@
+// SPDX-License-Identifier: Apache-2.0
+// The page grammar: a page as a tree of values, and its painter. One
+// grammar, two sources: a far being answers `page` with a tree, values
+// only, the way she answers `look`; a being running in the tab computes one
+// from her cells. The screen paints either with the painter below, and a
+// being that answers nothing gets the forms `html.ts` paints on its own.
+//
+// The vocabulary is closed, and a node that fails its shape is dropped, not
+// fixed: nothing here can carry a selector, a URL, a stylesheet or a
+// script, so a far being can design her page and can never reach out of
+// it. What a node names, an ask or a standing, must exist in her describe
+// for this asker, or it paints as nothing: a page adds no right.
+//
+//   stack      children one under another            { kind: 'stack', of: [...] }
+//   row        children side by side, wrapping       { kind: 'row', of: [...] }
+//   text       words with a role                     { kind: 'text', text, role?: title | lead | body | quiet | label }
+//   image      a picture as a data URI, never a URL  { kind: 'image', src, alt? }
+//   form       one of her asks as a form             { kind: 'form', ask }
+//   answer     one of her asks' last answer, shown   { kind: 'answer', ask, as?: auto | text | table | cards | list }
+//   standing   one standing she carries, a section   { kind: 'standing', id }
+//   standings  every standing she carries            { kind: 'standings' }
+import type { Json } from '@quo-systems/quo';
+import { escape } from './html.ts';
+
+export type Role = 'title' | 'lead' | 'body' | 'quiet' | 'label';
+export type As = 'auto' | 'text' | 'table' | 'cards' | 'list';
+export type Node =
+  | { kind: 'stack'; of: Node[] }
+  | { kind: 'row'; of: Node[] }
+  | { kind: 'text'; text: string; role?: Role }
+  | { kind: 'image'; src: string; alt?: string }
+  | { kind: 'form'; ask: string }
+  | { kind: 'answer'; ask: string; as?: As }
+  | { kind: 'standing'; id: string }
+  | { kind: 'standings' };
+
+const ROLES = new Set<Role>(['title', 'lead', 'body', 'quiet', 'label']);
+const AS = new Set<As>(['auto', 'text', 'table', 'cards', 'list']);
+const TEXT = 4000; // characters a text node may carry
+const DEPTH = 12; // how deep a tree may nest
+const WIDE = 200; // children a container may have
+const NAME = /^[\w.-]{1,80}$/;
+
+// A value held to the grammar, or null. Children that fail are dropped and
+// the container kept; a container with nothing left is kept empty, since an
+// empty region is a design and not a fault.
+export function sanitiseTree(v: Json, depth = 0): Node | null {
+  if (depth > DEPTH || v === null || typeof v !== 'object' || Array.isArray(v)) return null;
+  const o = v as Record<string, Json>;
+  switch (o.kind) {
+    case 'stack':
+    case 'row': {
+      const of = Array.isArray(o.of) ? o.of.slice(0, WIDE).map((c) => sanitiseTree(c, depth + 1)).filter((c): c is Node => c !== null) : [];
+      return { kind: o.kind, of };
+    }
+    case 'text': {
+      if (typeof o.text !== 'string') return null;
+      const n: Node = { kind: 'text', text: o.text.slice(0, TEXT) };
+      if (typeof o.role === 'string' && ROLES.has(o.role as Role)) n.role = o.role as Role;
+      return n;
+    }
+    case 'image': {
+      if (typeof o.src !== 'string' || !/^data:image\/[a-z0-9.+-]+;base64,[A-Za-z0-9+/=]+$/i.test(o.src)) return null;
+      const n: Node = { kind: 'image', src: o.src };
+      if (typeof o.alt === 'string') n.alt = o.alt.slice(0, 200);
+      return n;
+    }
+    case 'form':
+      return typeof o.ask === 'string' && NAME.test(o.ask) ? { kind: 'form', ask: o.ask } : null;
+    case 'answer': {
+      if (typeof o.ask !== 'string' || !NAME.test(o.ask)) return null;
+      const n: Node = { kind: 'answer', ask: o.ask };
+      if (typeof o.as === 'string' && AS.has(o.as as As)) n.as = o.as as As;
+      return n;
+    }
+    case 'standing':
+      return typeof o.id === 'string' && NAME.test(o.id) ? { kind: 'standing', id: o.id } : null;
+    case 'standings':
+      return { kind: 'standings' };
+    default:
+      return null;
+  }
+}
+
+// The names a tree asks the answers of: what a side runs on her behalf so
+// the page opens with what it shows, when the ask needs nothing typed.
+export function answersIn(n: Node, out: string[] = []): string[] {
+  if (n.kind === 'answer') out.push(n.ask);
+  if (n.kind === 'stack' || n.kind === 'row') for (const c of n.of) answersIn(c, out);
+  return out;
+}
+
+// What the painter needs from whoever holds the describe and the answers:
+// each returns HTML for a name it knows, and the empty string for one it
+// does not, so a page can never show what the gate did not.
+export type Painter = {
+  form(ask: string): string;
+  answer(ask: string, as: As): string;
+  standing(id: string): string;
+  standings(): string;
+};
+
+const ROLE_TAG: Record<Role, string> = { title: 'h1', lead: 'p', body: 'p', quiet: 'p', label: 'p' };
+
+export function paint(n: Node, p: Painter): string {
+  switch (n.kind) {
+    case 'stack':
+    case 'row':
+      return `<div class="${n.kind}">${n.of.map((c) => paint(c, p)).join('')}</div>`;
+    case 'text': {
+      const role = n.role ?? 'body';
+      return `<${ROLE_TAG[role]} class="t-${role}">${escape(n.text)}</${ROLE_TAG[role]}>`;
+    }
+    case 'image':
+      return `<img class="picture" alt="${escape(n.alt ?? '')}" src="${n.src}">`;
+    case 'form':
+      return p.form(n.ask);
+    case 'answer':
+      return p.answer(n.ask, n.as ?? 'auto');
+    case 'standing':
+      return p.standing(n.id);
+    case 'standings':
+      return p.standings();
+  }
+}
+
+// A painter with nothing behind it: for a page that names no ask, the door
+// page and any page painted before anyone is in.
+export const nobody: Painter = { form: () => '', answer: () => '', standing: () => '', standings: () => '' };

package/human/web.ts

@@ -23,6 +23,8 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import { existsSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
+import process from 'node:process';
 import { build } from 'esbuild';
 import type { DiskHarbor, Hosted } from '../harbor/disk.ts';
 import { door } from './door.ts';
@@ -33,16 +35,28 @@ export type WebOptions = {
 };
 
 // The paths under `/web` that are the exchange's, never a ward's name.
-const RESERVED_PATHS = new Set(['login', 'allow', 'tab.js']);
+const RESERVED_PATHS = new Set(['allow', 'tab.js', 'beings.js']);
+
+// The world's code for the tab: a module in the harbor folder, the twin of
+// `classes/index.ts`, exporting by name the classes the tab boots into its
+// local ward for a world of this harbor. Served bundled as `beings.js` on
+// this origin, and one origin is one world's code.
+export const TAB_CODE = 'tab/index.ts';
 
 export function webRoute(harbor: DiskHarbor, o: WebOptions): (req: IncomingMessage, res: ServerResponse, rest: string) => Promise<boolean> {
   const tabEntry = () => {
     const js = fileURLToPath(new URL('./tab.js', import.meta.url));
     return existsSync(js) ? js : fileURLToPath(new URL('./tab.ts', import.meta.url));
   };
+  const beingsEntry = join(harbor.dir, TAB_CODE);
+  const bundled = (entry: string) =>
+    // the entry may sit in a harbor folder with no node_modules of its own, as on a droplet whose
+    // estate folder is the working directory: what it imports is resolved from there too
+    build({ entryPoints: [entry], bundle: true, format: 'esm', platform: 'browser', target: 'es2023', write: false, nodePaths: [join(process.cwd(), 'node_modules')] }).then((out) => out.outputFiles[0]!.text);
   let bundle: Promise<string> | undefined;
-  const built = () =>
-    (bundle ??= build({ entryPoints: [tabEntry()], bundle: true, format: 'esm', platform: 'browser', target: 'es2023', write: false }).then((out) => out.outputFiles[0]!.text));
+  const built = () => (bundle ??= bundled(tabEntry()));
+  let beings: Promise<string> | undefined;
+  const builtBeings = () => (beings ??= bundled(beingsEntry));
   const quoOrigin = (() => {
     try {
       const u = new URL(o.at.quo);
@@ -71,7 +85,7 @@ export function webRoute(harbor: DiskHarbor, o: WebOptions): (req: IncomingMessa
   };
   const wards = () => Object.fromEntries([...harbor.wards].map(([n, h]) => [n, { pk: h.pk, public: publicOf(h) !== null }]));
   const tab = (ward?: string) => {
-    const cfg = { quo: o.at.quo, web: o.at.web, wards: wards(), ...(ward ? { ward } : {}) };
+    const cfg = { quo: o.at.quo, web: o.at.web, wards: wards(), beings: existsSync(beingsEntry), ...(ward ? { ward } : {}) };
     return `<script id="quo" type="application/json">${JSON.stringify(cfg).replace(/</g, '\\u003c')}</script><script type="module" src="${o.at.web}/tab.js"></script>`;
   };
   return async (req, res, rest) => {
@@ -88,6 +102,13 @@ export function webRoute(harbor: DiskHarbor, o: WebOptions): (req: IncomingMessa
       res.end(await built());
       return true;
     }
+    // the world's code for the tab, when the harbor folder holds any; a harbor with none has no such path
+    if (rest === '/beings.js' && req.method === 'GET') {
+      if (!existsSync(beingsEntry)) return false;
+      res.writeHead(200, { 'content-type': 'text/javascript; charset=utf-8', 'cache-control': 'no-store' });
+      res.end(await builtBeings());
+      return true;
+    }
     const wardName = parts[0] ?? '';
     if (!wardName || RESERVED_PATHS.has(wardName)) return false;
     const hosted = harbor.wards.get(wardName);
@@ -110,14 +131,20 @@ const CSS = [
   'header,main{background:var(--bg);color:var(--fg);font-family:var(--font)}header{display:flex;flex-wrap:wrap;align-items:center;gap:.5rem 1rem}header .notice{width:100%;margin:0}',
   'input,select,textarea,button{font:inherit;padding:.4rem;margin:.2rem;border-radius:var(--radius)}button{background:var(--accent);color:#fff;border:0;padding:.4rem .9rem}',
   'fieldset{border:1px solid color-mix(in srgb,currentColor 20%,transparent);border-radius:var(--radius);margin:.5rem 0}',
+  // a being of the world running in the tab: her own section under the far page
+  'section.local{border-top:1px solid color-mix(in srgb,currentColor 15%,transparent);margin:1.5rem 0;padding-top:.5rem}section.local header:empty{display:none}',
   'section.standing{background:var(--bg);color:var(--fg);font-family:var(--font);border-left:4px solid var(--accent);border-radius:var(--radius);padding:.25rem 1rem;margin:1.5rem 0}section.standing h2{display:flex;align-items:center;gap:.5rem;font-size:1.1rem}img.logo{height:1.6rem}',
   'table{border-collapse:collapse}td,th{padding:.15rem .5rem;text-align:left}.answer{margin:.5rem 0 1rem;padding:.5rem;border-left:3px solid var(--accent)}.answer.error{border-color:#c33}.answer.silence,.answer.word,.answer.unreached{border-color:#c93}pre{padding:.75rem;overflow:auto}',
+  // a page in the grammar: regions, roles, cards
+  '.page .stack{display:flex;flex-direction:column;gap:.5rem}.page .row{display:flex;flex-wrap:wrap;gap:.5rem 1rem;align-items:baseline}',
+  '.page .t-title{font-size:2rem;font-weight:600;letter-spacing:-.02em;margin:.5rem 0}.page .t-lead{font-size:1.25rem;margin:.25rem 0}.page .t-label{font-size:.8rem;letter-spacing:.06em;text-transform:uppercase;color:var(--mute);margin:0}.page .t-quiet{color:var(--mute);font-size:.9rem}.page .t-body{margin:.25rem 0}',
+  '.page .picture{max-height:6rem}.cards{display:flex;flex-wrap:wrap;gap:.75rem}.card{border:1px solid color-mix(in srgb,currentColor 20%,transparent);border-radius:var(--radius);padding:.5rem .75rem}',
   // the door page: one column, generous air, the mark, a word, a sentence
   'main.door{min-height:70vh;display:flex;flex-direction:column;justify-content:center;align-items:flex-start;max-width:32rem;margin:0 auto;padding:3rem 0;font-family:ui-serif,Georgia,"Times New Roman",serif}',
-  'main.door .mark{width:3.5rem;height:3.5rem;color:var(--ink);opacity:.9;margin-bottom:1.25rem}',
-  'main.door h1{font-size:3rem;font-weight:400;letter-spacing:-.02em;line-height:1;margin:0 0 .5rem}',
-  'main.door .where{font-family:system-ui,sans-serif;font-size:.85rem;letter-spacing:.08em;text-transform:uppercase;color:var(--mute);margin:0 0 2rem}main.door .where span{text-transform:none;letter-spacing:0}',
-  'main.door .lead{font-size:1.5rem;line-height:1.3;margin:0 0 1rem}',
+  'main.door .picture{width:3.5rem;height:3.5rem;color:var(--ink);opacity:.9;margin-bottom:1.25rem}',
+  'main.door .t-title{font-size:3rem;font-weight:400;letter-spacing:-.02em;line-height:1;margin:0 0 .5rem}',
+  'main.door .t-label{font-family:system-ui,sans-serif;font-size:.85rem;letter-spacing:.08em;text-transform:uppercase;color:var(--mute);margin:0 0 2rem}main.door .t-label span{text-transform:none;letter-spacing:0}',
+  'main.door .t-lead{font-size:1.5rem;line-height:1.3;margin:0 0 1rem}',
   'main.door p{font-size:1.05rem;line-height:1.6;margin:0 0 1rem;max-width:30rem}',
-  'main.door .quiet{color:var(--mute);font-size:.95rem;border-top:1px solid color-mix(in srgb,currentColor 15%,transparent);padding-top:1rem;margin-top:1rem}',
+  'main.door .t-quiet{color:var(--mute);font-size:.95rem;border-top:1px solid color-mix(in srgb,currentColor 15%,transparent);padding-top:1rem;margin-top:1rem}',
 ].join('');

package/mcp/oauth.ts

@@ -14,8 +14,8 @@
 //   POST /token                                       code or refresh for an access token
 //
 // The web route finishes a request by calling `complete(request, identity)`
-// after its own login and allow pages; that returns the redirect that
-// carries the code back to the client. Step 8 builds those pages.
+// after its allow page, where the human hands the invitation the root minted;
+// that returns the redirect that carries the code back to the client.
 import { randomBytes, createHash } from 'node:crypto';
 import type { IncomingMessage, ServerResponse } from 'node:http';