@dreamteamer/web 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,198 @@
-# Temporary Holding Version
+# @dreamteamer/web
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`dt web` serves the dreamteamer UI in your browser, over a dreamteamer workspace on your own machine.
+You get the same nav, lists, boards and record pages as the VS Code extension. Records change as they
+change on disk, with no reload. Nothing leaves the machine: the server listens on loopback only.
+
+![The Northwind sample workspace in dt web: the nav on the left, a projects board on the right](docs/screenshot.png)
+
+> **Not released yet.** This README is written ahead of the code and is the contract the package is
+> built to. It is `0.x`: any minor version may change the command line, and `UPDATING.md` says what to do.
+> Apache-2.0. Issues: https://github.com/dreamteamer/dreamteamer-modules/issues
+
+## quick start
+
+You need Node 20 or newer, git, and a compiled dreamteamer workspace. If you don't have one yet:
+
+```bash
+mkdir northwind && cd northwind
+npx dreamteamer init
+npx dreamteamer compile
+```
+
+Then, in the workspace:
+
+```bash
+npm install --save-dev @dreamteamer/web
+npx dt web
+```
+
+```text
+✔ dreamteamer web at http://127.0.0.1:53817/sign-in/7Qx2…k9Fa
+```
+
+The first line on stdout is always the sign-in URL. Your browser opens it. The page that loads is the
+workspace.
+
+The package ships the built app inside its tarball. The first run needs no network, and nothing is
+written into `node_modules`.
+
+To try it without adding a dependency, run it through `npx -p`, which works for every subcommand below:
+
+```bash
+npx -p @dreamteamer/web dt-web .            # start
+npx -p @dreamteamer/web dt-web . status     # the same as `npx dt web status`
+```
+
+Uninstall: `npm uninstall @dreamteamer/web`. `dt web` leaves no files behind in the workspace once it
+has stopped.
+
+## commands
+
+| command | does |
+|---|---|
+| `npx dt web` | starts the server on a free loopback port, prints the sign-in URL, opens your browser |
+| `npx dt web --no-open` | the same, but opens nothing. Only the URL is printed |
+| `npx dt web --port 4870` | listens on 4870, or refuses to start if it is taken. `DT_WEB_PORT` does the same. The default is `0`, a free port |
+| `npx dt web --idle 30` | stops after 30 minutes with no page connected. `0` never stops for idleness. The default is 30 |
+| `npx dt web --owner-pid 4242` | stops within 5 seconds of process 4242 exiting |
+| `npx dt web url` | prints a fresh sign-in URL for the running server |
+| `npx dt web status` | `running at http://127.0.0.1:<port> · pid <n> · since <time>` and exit 0, or `not running` and exit 1. It writes nothing |
+| `npx dt web stop` | stops the running server |
+
+One server serves one workspace. `npx dt doctor` shows a `web` row saying whether a server is running.
+
+For an agent session: the `serving-the-web-ui` skill, shipped in this package, says how a session starts
+`dt web`, reads the first stdout line, and hands the URL to whatever shows it. `dt web` itself promises
+only what is above: `--no-open`, `--owner-pid`, and the URL as the first line.
+
+## what you see
+
+- **The nav** on the left, built from the same model as the extension's tree: module folders, collections
+  with their record counts, saved views, and a Layers folder for the workspaces under `git_modules/`. It
+  follows the workspace's `.vscode/settings.json` (`dreamteamer.navGroups`, `navOrder`, `navHidden`,
+  `layersFolder`).
+- **The pages** are the extension's own: lists, boards, calendars, record pages, and the schema and
+  activity pages.
+- **Live updates.** A record written by `dt set`, by an agent or by a `git pull` appears within a second.
+  So does a `dt compile` run while the server is up.
+- **Light or dark** follows your system's setting.
+
+Not drawn in the browser: the gestures that belong to the editor, such as New Module…, New Skill… and
+running an editor command.
+
+## security
+
+### what it protects against, and what it does not
+
+| | |
+|---|---|
+| **protects against** | web pages on other origins, including DNS names rebound to `127.0.0.1` (Host and Origin checks); a page on another site making your browser read or write here (`Sec-Fetch-Site: cross-site` is refused, and a write needs an `Origin` naming this server or a token); a hostile image, SVG or `.html` file a record points at running script as you (record files come from a second, sandboxed origin); other users on the machine reading your token (it is in your per-user runtime directory, mode `0600`); a module's app — from an npm package or a workspace under `git_modules/` — using your session: it runs in a sandboxed frame on the second origin with no cookie and no network API (`connect-src 'none'`); every record it asks for, every value it is shown and every change it sends back goes through a bridge that allows only its own collections, plus the collections and the writes YOU grant it in this workspace's own `.vscode/settings.json` (`dreamteamer.moduleApps` — the same entry in your user settings or in a `.code-workspace` file grants nothing), never anything a layer's own files declare; without a grant it is read-only; it writes only in its own repository, and it cannot commit, change the schema or replace another module's or the editor's own controls |
+| **does not protect against** | **Another loopback server your browser visits.** Cookies are not port-scoped, so your browser sends this session to any server on `127.0.0.1`, whatever its port; a program serving one of those ports receives it and, not being a browser, can send any `Origin` it likes. **Another process running as you**: it can read your runtime directory, as it can read your files. **A browser extension** with access to `127.0.0.1`: the cookies API reads `HttpOnly` cookies. **Where the sign-in URL is written down** before it is used or expires: a session transcript, a desktop pane's logs, your shell history. **What a module's app does inside its reach**: it can copy what it may read into the collections you let it write, and a layer's records leave the machine when you push the layer; and, as for any web page, a peer connection (WebRTC) to a server it names and your browser's DNS prefetch of a link's host, which no page policy governs. **Your grant is the workspace's**: `.vscode/settings.json` is a file git tracks, so a grant is shared with everyone who clones the workspace and can be changed by anyone who can push to it |
+
+Found a hole? See [SECURITY.md](../../SECURITY.md). Do not open a public issue.
+
+### how it works
+
+- **Loopback only.** The server binds `127.0.0.1` and has no `--host` option. There is no tunnel and no
+  multi-user mode. To serve the API alone on another address, use `dt serve --host … --token …` from
+  `@dreamteamer/http`.
+- **Host and Origin.** A request's `Host` must be `127.0.0.1:<port>`, `localhost:<port>` or
+  `[::1]:<port>`, with this server's port. An `Origin`, when sent, must be `http://` plus one of those.
+  Anything else gets `403`.
+- **A token per start, and a single-use sign-in.** Each start mints a new random token. It lives as long
+  as the server and is kept in your per-user runtime directory (on Linux `$XDG_RUNTIME_DIR/dreamteamer-web/`,
+  on macOS `~/Library/Application Support/dreamteamer/web/runtime/`): the directory is mode `0700`, the
+  file `0600`, and nothing goes into the workspace, so it never lands in a synced folder. The printed URL
+  carries a **single-use sign-in code**, not the token. The first visit exchanges it for a session cookie
+  (`HttpOnly; SameSite=Strict; Path=/`) and redirects to `/`. A used code is refused, a code not used within
+  10 minutes expires, and `dt web url` mints a new one. An agent session should mint the URL right before
+  opening it and never write it into a chat.
+- **Cookies are not port-scoped.** Your browser sends this cookie to every server on `127.0.0.1`, whatever
+  the port (see the table above). So a write authenticated by the cookie must also carry an `Origin`, or
+  `Sec-Fetch-Site: same-origin`, naming this server; a write without either needs `Authorization: Bearer
+  <token>`. Every modern browser sends one or the other. Any request, read or write, marked
+  `Sec-Fetch-Site: cross-site` is refused.
+- **Headers.** Every response carries `Referrer-Policy: no-referrer` and `X-Content-Type-Options: nosniff`,
+  and no `X-Powered-By`. The app page carries exactly
+  `Content-Security-Policy: default-src 'self'; script-src 'self' 'nonce-<new per response>'; style-src 'self' 'unsafe-inline'; img-src 'self' <files origin> data: blob:; font-src 'self' data:; connect-src 'self'; frame-src <files origin>/<key>/_dt/frame/ <files origin>/<key>/w/; frame-ancestors 'none'; base-uri 'none'; form-action 'none'`.
+  The only inline script is the boot script, which carries that nonce. Scripts otherwise load only from
+  the app's own built files; no module's code is ever served by the app origin.
+- **Module apps.** A module's `ui/app.js` runs in a frame (`sandbox="allow-scripts"`, never
+  `allow-same-origin`) whose one document the second origin serves at `/<key>/_dt/frame/<module>/<kind>.html`:
+  the module's code embedded as data, a guest that loads it, and the policy `default-src 'none'; script-src
+  'unsafe-inline' blob:; style-src 'unsafe-inline'; img-src data: blob:; font-src data:; connect-src 'none';
+  frame-src 'none'; form-action 'none'; base-uri 'none'; object-src 'none'; worker-src 'none'` — no host, no
+  hash, no nonce, so no script can load from anywhere. The frame asks the page for records by message; the
+  page answers through the bridge under the module's scope, which a grant in this workspace's own
+  `.vscode/settings.json` widens:
+  `"dreamteamer.moduleApps": { "<module>": { "reads": ["users"], "writes": ["<one of its own collections>"] } }`.
+  A refusal names the collection or route, the module or root that owns it, and what the app may reach.
+- **Links in record text.** A link in a markdown field is drawn as a link only for `http:`, `https:` and
+  `mailto:` addresses and the app's own routes; anything else, such as `javascript:`, is drawn as text.
+- **Revisions are checked.** A commit named in a request (`?hash=` on a record's history, `hash` on a
+  revert) must be `HEAD` or 4 to 40 hexadecimal characters; anything else is `400` and never reaches git.
+- **Record files on a second origin.** Images, SVGs and `.html` pages a record points at are served from a
+  second loopback port. That port has no cookie and no API, and the address of each file carries its own
+  per-start key. Every response there carries `Content-Security-Policy: sandbox` (scripts off, unique
+  origin), and SVG and HTML are sent with `Content-Disposition: attachment` unless they are shown inside a
+  sandboxed frame. A hostile file can therefore never reach your records.
+- **Writes go through the engine.** A record edited in the page is validated and written exactly as
+  `dt set` writes it. A refusal shows the engine's own sentence beside the control.
+
+### served
+
+- **The app origin** serves the UI's built files and the protocol at `/api/` over the workspace's records.
+- **The files origin** also serves each module app's frame document (from `.dreamteamer/ui/`), and nothing
+  of a module's code by any other path.
+- **The files origin** serves files inside the folders that declared variables render to (for example
+  `${env:FILES_FOLDER}/…` on a record), and `.html` pages inside the workspace that a record names. A path
+  with `..`, an absolute path, or a link pointing out of its root is refused.
+- **Listing a record's folder** (the carousel) answers only for a folder inside those declared roots, and
+  names its files relative to the root, never by absolute path.
+- **Importing a file as a record** reads it only from inside those declared roots.
+
+Nothing else is served: no other file on disk, no `.env` value, and no credential.
+
+## the editor marker
+
+`npx dt status` prints an `editor:` line from `.dreamteamer/editor.json`, which an editor writes when it
+opens the workspace. Whether `dt web` should show there, and how, is **an open question**. Today the
+engine reads only that one file, so showing a second editor means either sharing the file with the VS Code
+extension or an engine change. The answer goes into `UPDATING.md`. Until then, `npx dt web status` is the
+way to ask whether a server is running.
+
+## versions
+
+| @dreamteamer/web | @dreamteamer/protocol | @dreamteamer/ui | engine (`dreamteamer`) |
+|---|---|---|---|
+| 0.1.x | ^0.1.0 | ^0.1.0 | `>=0.43.0`, tested on 0.43 and 0.44 |
+
+The app is `@dreamteamer/ui`'s browser page (`dist/app/` in that package), the same UI the VS Code
+extension mounts, built when `@dreamteamer/ui` is published and served as it is. It reaches the server
+through the UI's HTTP transport, so this package carries no app and no host emulation of its own. Known
+advisories in dependencies, and whether they reach a request, are listed in `SECURITY.md`.
+
+## limits
+
+- One workspace per server, and one person per machine.
+- The nav reads the workspace's `.vscode/settings.json` only. A setting kept in your VS Code user settings
+  is not seen.
+- Browsers: current Chrome, Edge, Firefox and Safari. Live updates use server-sent events, which Safari
+  supports.
+- Linux: live updates need Node 20 or newer (recursive file watching). A workspace with very many files can
+  hit the inotify watch limit (`fs.inotify.max_user_watches`).
+- macOS and Linux only. Windows is untested.
+
+## troubleshooting
+
+- **"Sign in with the URL `dt web` printed"**: you opened the bare address, or reused a sign-in URL. Run
+  `npx dt web url` and open the new one.
+- **A page at `[::1]`**: `[::1]` is redirected to `127.0.0.1`, because module frames cannot name an IPv6
+  address as their ancestor.
+- **`403`**: the address is not one this server answers. Use `127.0.0.1`, `localhost` or `[::1]` with the
+  printed port.
+- **"port 4870 is in use"**: drop `--port` (or `DT_WEB_PORT`) to take a free port.
+- **The page doesn't change when a record does**: check that the server is still running (`npx dt web
+  status`). On Linux, check the Node version and the inotify limit.
+- **"the app is missing"**: the installed package is incomplete. Reinstall it.

package/bin/dt-web.mjs

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+// dt-web <workspace root> [url|status|stop] [flags] — dt web without adding a dependency to the workspace.
+import fs from 'node:fs';
+import path from 'node:path';
+import { main } from '../src/cli.js';
+
+const [rootArg, ...rest] = process.argv.slice(2);
+const root = path.resolve(rootArg ?? '.');
+if (!fs.existsSync(path.join(root, 'package.json'))) {
+	console.error(`${root} is not a dreamteamer workspace (no package.json) — npx dreamteamer init`);
+	process.exit(2);
+}
+main(root, rest).then((code) => process.exit(code), (e) => { console.error(`✖ ${e.message}`); process.exit(2); });

package/package.json

@@ -1,6 +1,40 @@
 {
-  "name": "@dreamteamer/web",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@dreamteamer/web",
+	"version": "0.1.0",
+	"description": "dt web: the dreamteamer UI in your browser over a workspace on your machine — loopback, a sign-in URL, live updates",
+	"license": "Apache-2.0",
+	"type": "module",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/dreamteamer/dreamteamer-modules.git",
+		"directory": "modules/web"
+	},
+	"keywords": [
+		"dreamteamer",
+		"dreamteamer-module"
+	],
+	"bin": {
+		"dt-web": "bin/dt-web.mjs"
+	},
+	"exports": {
+		".": "./src/server.js",
+		"./extension": "./src/extension.js",
+		"./package.json": "./package.json"
+	},
+	"files": [
+		"README.md",
+		"bin",
+		"src",
+		"skills"
+	],
+	"dependencies": {
+		"@dreamteamer/protocol": "^0.1.0",
+		"@dreamteamer/ui": "^0.1.0"
+	},
+	"dreamteamer": {
+		"extension": "./src/extension.js",
+		"title": "Web",
+		"description": "dt web: the dreamteamer UI in a browser over a workspace on your own machine — the extension's nav, lists, boards and record pages, served on loopback behind a single-use sign-in, with record files on a second sandboxed origin and live updates as records change on disk. Adds the dt web verb and a web row in dt doctor.",
+		"engine": ">=0.43.0"
+	}
+}

package/skills/serving-the-web-ui/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: serving-the-web-ui
+description: >-
+  use when a person asks a session to show the workspace, open the web UI, see the records in a browser or in the Browser pane beside the chat — "show me the workspace", "open dt web", "give me the URL", "stop the web UI", "is the web UI running" — in Claude Code desktop, Codex, a terminal or a cloud session. How to start `dt web` in the background, read its sign-in URL, hand the URL to whatever shows it, and stop it.
+---
+
+# serving-the-web-ui
+
+`dt web` serves the dreamteamer UI over this workspace on loopback. It prints ONE thing you need: its first
+stdout line, `✔ dreamteamer web at http://127.0.0.1:<port>/sign-in/<code>`. The code in that URL signs in
+once and expires after 10 minutes; `dt web url` mints a fresh one from the running server.
+
+## 1. Is one already running?
+
+```bash
+npx dt web status        # exit 0: "running at http://127.0.0.1:<port> · pid <n> · since <time>"; exit 1: "not running"
+```
+
+Running: go to step 3 with a fresh URL from `npx dt web url`. A second `dt web` in the same workspace refuses
+to start and names the running one.
+
+## 2. Start it in the background
+
+Run it as a background command, never in the foreground: it serves until it is stopped.
+
+```bash
+npx dt web --no-open                      # Claude Code: CLAUDE_PID is read on its own, and the server stops when the session ends
+npx dt web --no-open --owner-pid "$PPID"  # Codex, or any harness without CLAUDE_PID: stops when that process exits
+```
+
+Read the URL from the first line of the command's output. Without the package installed, the same works through
+`npx -p @dreamteamer/web dt-web . --no-open`.
+
+The server also stops after 30 minutes with no page connected (`--idle <minutes>`, `0` never).
+
+## 3. Hand the URL to what shows it
+
+- **Claude Code desktop:** open it in the Browser pane beside the chat with `preview_start` and the URL as
+  `url`. Mint the URL right before opening it (`npx dt web url`): a code used once, or older than 10 minutes,
+  shows a sign-in page instead of the workspace.
+- **Codex, a terminal session, or any harness without a browser pane:** give the person the URL and say it
+  signs in once; `npx dt web url` gives another.
+- **A cloud session (Claude Code on the web, Codex cloud):** the capability is unavailable. The server listens
+  on the cloud machine's loopback, which the person's browser cannot reach, and `dt web` has no tunnel and no
+  other address by design. Say so, and suggest running it on their own machine.
+
+Never paste the URL into a file, a commit, a record or a note: until it is used it is a key to the workspace.
+
+## 4. Stop it
+
+```bash
+npx dt web stop          # "stopped", exit 0 — or "not running", exit 1
+```
+
+## A launch entry for the Browser pane
+
+A workspace may keep a `.claude/launch.json` entry so the pane can start the server by name. `dt web` takes
+its port from `--port` (or `DT_WEB_PORT`), not from `PORT`, so give it a fixed port rather than `autoPort`:
+
+```json
+{
+  "version": "0.0.1",
+  "configurations": [
+    { "name": "dreamteamer-web", "runtimeExecutable": "npx", "runtimeArgs": ["dt", "web", "--no-open", "--port", "4870"], "port": 4870 }
+  ]
+}
+```
+
+The pane opens `http://localhost:4870/`, which answers the sign-in page: then open a fresh URL from
+`npx dt web url` (or the entry's output in `preview_logs`) in the same pane.
+
+## What the page reads
+
+- The nav follows the workspace's `.vscode/settings.json` (`dreamteamer.navGroups`, `navOrder`, `navHidden`,
+  `layersFolder`). A setting kept in the person's VS Code user settings is not seen by the browser.
+- Records change on the page as they change on disk — a `dt set`, an agent's write, a `git pull` — with no
+  reload.

package/src/cli.js

@@ -0,0 +1,86 @@
+// `dt web` and `dt-web <root>`: start · url · status · stop (README § commands). One argv grammar for both
+// entries; `main` resolves to the process exit code.
+import { spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { claimStart, readState, removeState, running, stateFile, writeState, alive } from './runtime.js';
+
+// the browser page @dreamteamer/ui builds, served as it is
+const appDirOf = () => path.join(path.dirname(createRequire(import.meta.url).resolve('@dreamteamer/ui/package.json')), 'dist', 'app');
+
+export function parseArgs(argv, env = process.env) {
+	const out = { cmd: 'start', port: env.DT_WEB_PORT !== undefined ? Number(env.DT_WEB_PORT) : 0, open: true, idle: 30, ownerPid: undefined };
+	const args = [...argv];
+	if (['url', 'status', 'stop'].includes(args[0])) out.cmd = args.shift();
+	for (let i = 0; i < args.length; i++) {
+		const a = args[i];
+		const m = /^--(port|idle|owner-pid)(?:=(.*))?$/.exec(a);
+		if (a === '--no-open') { out.open = false; continue; }
+		if (!m) throw new Error(`dt web does not take "${a}" — usage: dt web [url|status|stop] [--port <n>] [--no-open] [--idle <minutes>] [--owner-pid <pid>]`);
+		const v = m[2] ?? args[++i];
+		if (v === undefined || !/^\d+$/.test(v)) throw new Error(`--${m[1]} needs a whole number`);
+		if (m[1] === 'port') { if (Number(v) > 65535) throw new Error('--port must be 0..65535'); out.port = Number(v); }
+		if (m[1] === 'idle') out.idle = Number(v);
+		if (m[1] === 'owner-pid') out.ownerPid = Number(v);
+	}
+	if (!Number.isInteger(out.port) || out.port < 0 || out.port > 65535) throw new Error('DT_WEB_PORT must be 0..65535');
+	return out;
+}
+
+export async function main(root, argv, { log = console.log, env = process.env, appDir = env.DT_WEB_APP_DIR ?? appDirOf() } = {}) {
+	const o = parseArgs(argv, env);
+	const now = running(root);
+	if (o.cmd === 'status') {
+		if (!now) { log('not running'); return 1; }
+		log(`running at http://127.0.0.1:${now.port} · pid ${now.pid}${now.owner ? ` · owner ${now.owner}` : ''} · since ${now.started}`);
+		return 0;
+	}
+	if (o.cmd === 'stop') {
+		if (!now) { log('not running'); return 1; }
+		process.kill(now.pid, 'SIGTERM');
+		// stopped = the server removed its state file (a process its parent has not reaped yet still answers kill 0)
+		const gone = () => !readState(now.file) || !alive(now.pid);
+		for (let i = 0; i < 50 && !gone(); i++) await new Promise((r) => setTimeout(r, 100));
+		log(gone() ? 'stopped' : `pid ${now.pid} did not stop`);
+		return gone() ? 0 : 1;
+	}
+	if (o.cmd === 'url') {
+		if (!now) { log('not running'); return 1; }
+		const r = await fetch(`http://127.0.0.1:${now.port}/_dt/sign-in`, { method: 'POST', headers: { authorization: `Bearer ${now.token}` }, signal: AbortSignal.timeout(10_000) });
+		if (!r.ok) { log(`the server refused: ${r.status}`); return 1; }
+		log((await r.json()).url);
+		return 0;
+	}
+	if (now) { log(`already running at http://127.0.0.1:${now.port} (pid ${now.pid}) — npx dt web url`); return 1; }
+	const { startWeb } = await import('./server.js');
+	const ownerPid = o.ownerPid ?? (env.CLAUDE_PID ? Number(env.CLAUDE_PID) : undefined);
+	const file = stateFile(root);
+	const lock = claimStart(file);
+	if (!lock.ok) { log(`already running or starting${lock.pid ? ` (pid ${lock.pid})` : ''} — npx dt web status`); return 1; }
+	let web;
+	try {
+		web = await startWeb({ root, appDir, port: o.port, idleMinutes: o.idle, ownerPid, onStop: () => { removeState(file); lock.release(); } });
+	} catch (e) {
+		lock.release();
+		throw e;
+	}
+	writeState(file, { pid: process.pid, port: web.appPort, filesPort: web.filesPort, started: new Date().toISOString(), owner: ownerPid ?? null, token: web.token });
+	// the handlers before the first line: a caller may signal the moment it reads the URL
+	const stop = () => web.close('signal');
+	process.once('SIGINT', stop);
+	process.once('SIGTERM', stop);
+	const url = web.signInUrl();
+	log(`✔ dreamteamer web at ${url}`);
+	if (o.open) openBrowser(url);
+	await web.closed;
+	removeState(file);
+	lock.release();
+	return 0;
+}
+
+function openBrowser(url) {
+	const cmd = process.platform === 'darwin' ? 'open' : 'xdg-open';
+	try { spawn(cmd, [url], { stdio: 'ignore', detached: true }).unref(); } catch { /* print-only */ }
+}
+
+export { readState };

package/src/extension.js

@@ -0,0 +1,21 @@
+// The engine extension: `dt web [url|status|stop] [flags]`, and a `web` row in `dt doctor`.
+import { main, parseArgs } from './cli.js';
+import { running } from './runtime.js';
+
+export const apiVersion = 1;
+const USAGE = '  web [url|status|stop] [--port <n>] [--no-open] [--idle <minutes>] [--owner-pid <pid>]   the UI in your browser over this workspace (loopback; prints a sign-in URL)';
+
+export default function activate() {
+	return {
+		commands: {
+			web: {
+				usage: USAGE,
+				async run(ws, argv) { parseArgs(argv); return main(ws.root, argv); },
+			},
+		},
+		doctor({ root }) {
+			const r = running(root);
+			return [{ label: 'web', state: 'ok', detail: r ? `running at http://127.0.0.1:${r.port} · pid ${r.pid}` : 'not running' }];
+		},
+	};
+}

package/src/headers.js

@@ -0,0 +1,24 @@
+// The headers every response carries, and the app page's exact Content-Security-Policy (README § security).
+export function baseHeaders(res) {
+	res.setHeader('Referrer-Policy', 'no-referrer');
+	res.setHeader('X-Content-Type-Options', 'nosniff');
+	res.removeHeader('X-Powered-By');
+}
+
+export function appCsp(nonce, filesOrigin, filesKey) {
+	return [
+		"default-src 'self'",
+		`script-src 'self' 'nonce-${nonce}'`,
+		"style-src 'self' 'unsafe-inline'",
+		`img-src 'self' ${filesOrigin} data: blob:`,
+		"font-src 'self' data:",
+		"connect-src 'self'",
+		filesKey ? `frame-src ${filesOrigin}/${filesKey}/_dt/frame/ ${filesOrigin}/${filesKey}/w/` : `frame-src ${filesOrigin}`,
+		"frame-ancestors 'none'",
+		"base-uri 'none'",
+		"form-action 'none'",
+	].join('; ');
+}
+
+/** A record file on the files origin: script off, a unique origin. */
+export const FILE_CSP = 'sandbox';

package/src/module-frames.js

@@ -0,0 +1,42 @@
+// cr-modules-008 task 6: the files origin serves each module surface as ONE self-contained frame document —
+// the module's app.js read once and embedded as data, the guest (Vue + the guest runtime) from @dreamteamer/ui,
+// the frame policy with no host, hash or nonce. Nothing in the frame is fetched afterwards.
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { buildFrameDocument, FRAME_POLICY } from '@dreamteamer/protocol/frame-document';
+
+export const FRAME_KINDS = new Set(['registry', 'app', 'list', 'edit', 'view', 'panel']);
+const NAME = /^[a-z0-9@][a-z0-9._-]*$/i;
+
+/** The guest @dreamteamer/ui builds (dist/guest/guest.js + guest.css), or null when that package is absent. */
+export function resolveGuest(from) {
+	try {
+		const req = createRequire(path.join(from, 'package.json'));
+		const js = req.resolve('@dreamteamer/ui/dist/guest/guest.js');
+		const css = path.join(path.dirname(js), 'guest.css');
+		return { guestText: fs.readFileSync(js, 'utf8'), styleText: fs.existsSync(css) ? fs.readFileSync(css, 'utf8') : '' };
+	} catch { return null; }
+}
+
+/**
+ * A frame route for startWeb's addFrameRoute: segments after /_dt/frame/ are [module, "<kind>.html"].
+ * @param {{ root: string, appPort: () => number, guest: {guestText: string, styleText?: string} | null }} o
+ */
+export function moduleFrameRoute({ root, appPort, guest }) {
+	return (segments) => {
+		if (segments.length !== 2) return null;
+		const [module, file] = segments;
+		const kind = file.endsWith('.html') ? file.slice(0, -5) : '';
+		if (!NAME.test(module) || !FRAME_KINDS.has(kind)) return null;
+		const bundleFile = path.join(root, '.dreamteamer', 'ui', module, 'app.js');
+		if (!fs.existsSync(bundleFile)) return null;
+		if (!guest) return { status: 503, body: 'module apps need the frame guest from @dreamteamer/ui, which is not installed — reinstall @dreamteamer/web' };
+		const { html } = buildFrameDocument({ guestText: guest.guestText, styleText: guest.styleText ?? '', bundleText: fs.readFileSync(bundleFile, 'utf8') });
+		const p = appPort();
+		return {
+			body: html, type: 'text/html; charset=utf-8',
+			headers: { 'Content-Security-Policy': `sandbox allow-scripts; ${FRAME_POLICY}; frame-ancestors http://127.0.0.1:${p} http://localhost:${p}`, 'Cache-Control': 'no-store' },
+		};
+	};
+}

package/src/runtime.js

@@ -0,0 +1,82 @@
+// Where a running server keeps its state and its token: the per-user runtime directory, never the
+// workspace (README: "nothing goes into the workspace, so it never lands in a synced folder"). One file per
+// workspace, named by a hash of the workspace's real path; the directory is 0700 and the file 0600.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+/** The per-user runtime directory: $DT_WEB_RUNTIME_DIR, else $XDG_RUNTIME_DIR/dreamteamer-web on Linux,
+ *  ~/Library/Application Support/dreamteamer/web/runtime on macOS, ~/.local/share/dreamteamer/web/runtime otherwise. */
+export function runtimeDir(env = process.env, platform = process.platform, home = os.homedir()) {
+	if (env.DT_WEB_RUNTIME_DIR) return env.DT_WEB_RUNTIME_DIR;
+	if (platform === 'linux' && env.XDG_RUNTIME_DIR) return path.join(env.XDG_RUNTIME_DIR, 'dreamteamer-web');
+	if (platform === 'darwin') return path.join(home, 'Library', 'Application Support', 'dreamteamer', 'web', 'runtime');
+	return path.join(home, '.local', 'share', 'dreamteamer', 'web', 'runtime');
+}
+
+/** The state file of one workspace's server. */
+export function stateFile(root, dir = runtimeDir()) {
+	const key = crypto.createHash('sha256').update(fs.realpathSync(root)).digest('hex').slice(0, 16);
+	return path.join(dir, `${key}.json`);
+}
+
+export function writeState(file, state) {
+	fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+	fs.chmodSync(path.dirname(file), 0o700);
+	const tmp = `${file}.${process.pid}.tmp`;
+	fs.writeFileSync(tmp, JSON.stringify(state, null, '\t') + '\n', { mode: 0o600 });
+	fs.renameSync(tmp, file);
+}
+
+export function readState(file) {
+	try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return null; }
+}
+
+export function removeState(file, pid = process.pid) {
+	const s = readState(file);
+	if (s && s.pid === pid) fs.rmSync(file, { force: true });
+}
+
+export function alive(pid) {
+	if (!Number.isInteger(pid) || pid <= 0) return false;
+	try { process.kill(pid, 0); return true; } catch (e) { return e.code === 'EPERM'; }
+}
+
+/** The running server of a workspace, or null — a state file whose process is gone is removed. */
+export function running(root) {
+	const file = stateFile(root);
+	const s = readState(file);
+	if (!s) return null;
+	if (!alive(s.pid)) { fs.rmSync(file, { force: true }); return null; }
+	return { ...s, file };
+}
+
+/**
+ * Claim the right to serve this workspace: a lock file created exclusively beside the state file, holding
+ * this pid for the server's whole life. Two starts at the same moment cannot both pass the "already
+ * running" check — only one creates the lock. A lock whose process is gone is taken over by one starter
+ * only: the takeover itself is an exclusive file, so two starters after a crash cannot both clear it.
+ */
+export function claimStart(file, pid = process.pid) {
+	const lock = `${file}.lock`;
+	const take = `${lock}.takeover`;
+	const holder = (f) => { try { return Number(fs.readFileSync(f, 'utf8')); } catch { return null; } };
+	fs.mkdirSync(path.dirname(lock), { recursive: true, mode: 0o700 });
+	for (let attempt = 0; attempt < 2; attempt++) {
+		try {
+			fs.writeFileSync(lock, String(pid), { flag: 'wx', mode: 0o600 });
+			let released = false;
+			return { ok: true, release: () => { if (released) return; released = true; if (holder(lock) === pid) fs.rmSync(lock, { force: true }); } };
+		} catch (e) {
+			if (e.code !== 'EEXIST') throw e;
+			const held = holder(lock);
+			if (held !== null && alive(held)) return { ok: false, pid: held };
+			const taker = holder(take);
+			if (taker !== null && !alive(taker)) fs.rmSync(take, { force: true });
+			try { fs.writeFileSync(take, String(pid), { flag: 'wx', mode: 0o600 }); } catch { return { ok: false, pid: held }; }
+			try { if (holder(lock) === held) fs.rmSync(lock, { force: true }); } finally { fs.rmSync(take, { force: true }); }
+		}
+	}
+	return { ok: false, pid: null };
+}

package/src/server.js

@@ -0,0 +1,306 @@
+// dt web's two loopback listeners. The APP origin serves the UI, the protocol at /api/ and the live channel;
+// the FILES origin serves the record files a record points at, sandboxed, with no cookie and no API, under a
+// per-start key (README § security). Every rule here is written in modules/web/README.md.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import http from 'node:http';
+import path from 'node:path';
+import { createHandler } from '@dreamteamer/protocol/handler';
+import { engine } from '@dreamteamer/protocol/host/engine';
+import { envRoots } from '@dreamteamer/protocol/host/folder-images';
+import { changeScope, invalidateMessage } from '@dreamteamer/protocol/host/changes';
+import { appCsp, baseHeaders, FILE_CSP } from './headers.js';
+import { readModuleGrantResult } from '@dreamteamer/protocol/module-grant';
+import { moduleFrameRoute, resolveGuest } from './module-frames.js';
+
+const SIGN_IN_TTL_MS = 10 * 60_000;
+const DEBOUNCE_MS = 150;
+const random = (n = 24) => crypto.randomBytes(n).toString('base64url');
+const same = (a, b) => typeof a === 'string' && typeof b === 'string' && a.length === b.length && crypto.timingSafeEqual(Buffer.from(a), Buffer.from(b));
+const MIME = { '.html': 'text/html; charset=utf-8', '.js': 'text/javascript; charset=utf-8', '.mjs': 'text/javascript; charset=utf-8', '.css': 'text/css; charset=utf-8', '.json': 'application/json', '.svg': 'image/svg+xml', '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif', '.webp': 'image/webp', '.ttf': 'font/ttf', '.woff': 'font/woff', '.woff2': 'font/woff2', '.ico': 'image/x-icon', '.pdf': 'application/pdf', '.txt': 'text/plain; charset=utf-8' };
+
+/** `file` under `root` after resolving every link, or null — `..`, absolute paths and links out are refused. */
+export function contained(root, rel) {
+	if (typeof rel !== 'string' || !rel || rel.includes('\0') || path.isAbsolute(rel) || rel.split(/[\\/]/).includes('..')) return null;
+	let realRoot, real;
+	try { realRoot = fs.realpathSync(root); real = fs.realpathSync(path.join(root, rel)); } catch { return null; }
+	return real === realRoot || real.startsWith(realRoot + path.sep) ? real : null;
+}
+
+const hostNames = (port) => new Set([`127.0.0.1:${port}`, `localhost:${port}`, `[::1]:${port}`]);
+
+/**
+ * Start dt web for the workspace at `root`. `appDir` holds the built app (index.html + assets/) — @dreamteamer/ui's dist/app.
+ * Resolves `{ appUrl, filesOrigin, token, signInUrl(), close(), closed }`.
+ */
+export async function startWeb({ root, appDir, port = 0, idleMinutes = 30, ownerPid, onStop, signInTtlMs = SIGN_IN_TTL_MS, moduleGuest } = {}) {
+	if (!fs.existsSync(path.join(appDir, 'index.html'))) {
+		throw new Error(`the app is missing: ${path.join(appDir, 'index.html')} — @dreamteamer/ui is installed without its build (see the README)`);
+	}
+	const handler = await createHandler({ root });
+	const token = random(32);
+	const filesKey = random(18);
+	const signIns = new Map(); // code → expiry
+	const sessions = new Set();
+	const clients = new Set();
+	let appPort, filesPort;
+
+	// ---- the files origin --------------------------------------------------------------------
+	const varRoots = () => { try { const e = engine(); return envRoots(e.declaredVars ?? [], e.renderEnv); } catch { return []; } };
+	const fileBases = () => {
+		const out = [];
+		try {
+			const { isBinary, storageOf } = engine().descriptor;
+			for (const d of handler.api.descriptors().values()) if (isBinary(d) && storageOf(d).path) out.push({ collection: String(d.name), path: storageOf(d).path, suffix: String(storageOf(d).suffix ?? '') });
+		} catch { /* no binary collections */ }
+		return out;
+	};
+	const frameRoutes = [];
+	// cr-modules-008: module apps run in frames served here; `moduleGuest: null` forces the missing-guest path in tests
+	frameRoutes.push(moduleFrameRoute({ root, appPort: () => appPort, guest: moduleGuest === undefined ? resolveGuest(path.dirname(new URL(import.meta.url).pathname)) : moduleGuest }));
+	const files = http.createServer((req, res) => {
+		try {
+			serveFile(req, res);
+		} catch {
+			if (res.headersSent) return void res.destroy();
+			send(res, 400, 'bad request');
+		}
+	});
+	const serveFile = (req, res) => {
+		baseHeaders(res);
+		res.setHeader('Content-Security-Policy', FILE_CSP);
+		if (!hostNames(filesPort).has(String(req.headers.host ?? '').toLowerCase())) return send(res, 403, 'not this server');
+		if (req.headers['sec-fetch-site'] === 'cross-site') return send(res, 403, 'cross-site');
+		if (req.method !== 'GET' && req.method !== 'HEAD') return send(res, 405, 'read only');
+		const url = new URL(req.url, 'http://x');
+		const parts = url.pathname.split('/').slice(1);
+		if (!same(parts[0], filesKey)) return send(res, 404, 'not found');
+		const kind = parts[1];
+		const rest = parts.slice(2).map((p) => { try { return decodeURIComponent(p); } catch { return '\0'; } });
+		if (kind === '_dt' && rest[0] === 'frame') {
+			for (const r of frameRoutes) { const out = r(rest.slice(1), req); if (out) return out.status ? send(res, out.status, out.body) : sendFile(res, out.body, out.type ?? 'text/html; charset=utf-8', out.headers); }
+			return send(res, 404, 'no frame');
+		}
+		let file = null;
+		if (kind === 'v') {
+			const r = varRoots().find((x) => x.name === rest[0]);
+			if (r) file = contained(r.path, rest.slice(1).join('/'));
+		} else if (kind === 'w') {
+			const rel = rest.join('/');
+			const allowed = rel.endsWith('.html') && !rel.split('/').some((s) => s.startsWith('.') || s === 'node_modules')
+				|| fileBases().some((b) => rel.startsWith(b.path.replace(/\\/g, '/') + '/'));
+			if (allowed) file = contained(root, rel);
+		}
+		if (!file || !fs.statSync(file).isFile()) return send(res, 404, 'not found');
+		const ext = path.extname(file).toLowerCase();
+		const headers = {};
+		if ((ext === '.svg' || ext === '.html') && url.searchParams.get('frame') !== '1') headers['Content-Disposition'] = 'attachment';
+		return sendFile(res, fs.readFileSync(file), MIME[ext] ?? 'application/octet-stream', headers);
+	};
+
+
+	// ---- the app origin ----------------------------------------------------------------------
+	const appHtml = fs.readFileSync(path.join(appDir, 'index.html'), 'utf8');
+	// the files origin on the host the page was opened at: a page at localhost framing 127.0.0.1 would be cross-site,
+	// which the files origin refuses (cr-modules-008 t13)
+	const filesOrigin = (pageHost = '') => `http://${/^localhost(:|$)/i.test(pageHost) ? 'localhost' : '127.0.0.1'}:${filesPort}`;
+	const boot = (nonce, pageHost) => {
+		const base = `${filesOrigin(pageHost)}/${filesKey}`;
+		const globals = {
+			__DT_HOST__: { nav: 'app', commands: false, openFile: 'tab', tabs: false, history: 'hash', moduleFrames: 'url' },
+			...((g) => ({ __DT_MODULE_GRANTS__: g.grant, __DT_MODULE_GRANT_PROBLEM__: g.problem }))(readModuleGrantResult(root)),
+			__DT_FILE_BASES__: fileBases().map((b) => ({ ...b, uri: `${base}/w/${b.path}` })),
+			__DT_VAR_ROOTS__: varRoots().map((r) => ({ ...r, uri: `${base}/v/${encodeURIComponent(r.name)}` })),
+			__DT_FILES__: base,
+		};
+		const json = JSON.stringify(globals).replace(/</g, '\\u003c');
+		return `<script nonce="${nonce}">Object.assign(window, ${json});</script>`;
+	};
+
+	const authed = (req) => {
+		const m = /^Bearer (.+)$/.exec(req.headers.authorization ?? '');
+		if (m && same(m[1], token)) return 'bearer';
+		const sid = new RegExp(`(?:^|;\\s*)dt_session_${appPort}=([^;]+)`).exec(req.headers.cookie ?? '')?.[1];
+		return sid && sessions.has(sid) ? 'cookie' : null;
+	};
+	// a request that throws — a malformed percent-escape, a client gone mid-body — answers or is dropped, never
+	// takes the server down with it
+	const app = http.createServer((req, res) => {
+		handle(req, res).catch((err) => {
+			if (res.headersSent || req.destroyed) return void res.destroy();
+			json(res, err instanceof URIError ? 400 : 500, { error: err instanceof URIError ? 'a malformed percent-escape in the path' : 'the request failed' });
+		});
+	});
+	const handle = async (req, res) => {
+		baseHeaders(res);
+		const host = String(req.headers.host ?? '').toLowerCase();
+		if (!hostNames(appPort).has(host)) return send(res, 403, `Host "${req.headers.host ?? ''}" is not this server — use 127.0.0.1:${appPort}`);
+		if (req.headers['sec-fetch-site'] === 'cross-site') return send(res, 403, 'a request from another site is refused');
+		const origin = req.headers.origin;
+		if (origin !== undefined && !(origin.startsWith('http://') && hostNames(appPort).has(origin.slice(7).toLowerCase()))) return send(res, 403, `Origin "${origin}" may not call this server`);
+		const url = new URL(req.url, 'http://x');
+		// CSP has no IPv6 host-source, so module frames cannot name [::1] as an ancestor: the page moves to 127.0.0.1
+		if (host.startsWith('[::1]') && req.method === 'GET' && !url.pathname.startsWith('/api/')) {
+			res.writeHead(302, { Location: `http://127.0.0.1:${appPort}${req.url}` });
+			return res.end();
+		}
+
+		if (req.method === 'GET' && url.pathname.startsWith('/sign-in/')) {
+			const code = url.pathname.slice('/sign-in/'.length);
+			const exp = signIns.get(code);
+			signIns.delete(code);
+			if (!exp || exp < Date.now()) return page(res, 401, 'Sign in with the URL <code>dt web</code> printed — run <code>npx dt web url</code> for a new one.');
+			const sid = random(32);
+			sessions.add(sid);
+			res.setHeader('Set-Cookie', `dt_session_${appPort}=${sid}; HttpOnly; SameSite=Strict; Path=/`);
+			res.writeHead(302, { Location: '/' });
+			return res.end();
+		}
+		if (req.method === 'POST' && url.pathname === '/_dt/sign-in') {
+			if (authed(req) !== 'bearer') return send(res, 401, 'a new sign-in URL needs the bearer token');
+			return json(res, 200, { url: signInUrl() });
+		}
+		const who = authed(req);
+		if (!who) {
+			if (url.pathname.startsWith('/api/')) { res.setHeader('WWW-Authenticate', 'Bearer'); return json(res, 401, { error: 'sign in with the URL dt web printed, or send Authorization: Bearer <token>' }); }
+			return page(res, 401, 'Sign in with the URL <code>dt web</code> printed — run <code>npx dt web url</code> for a new one.');
+		}
+		const write = !['GET', 'HEAD', 'OPTIONS'].includes(req.method);
+		if (write && who === 'cookie') {
+			const named = (origin !== undefined) || req.headers['sec-fetch-site'] === 'same-origin';
+			if (!named) return json(res, 403, { error: 'a write with the session cookie must carry this server\'s Origin or Sec-Fetch-Site: same-origin — or send Authorization: Bearer <token>' });
+		}
+
+		if (req.method === 'GET' && (url.pathname === '/' || url.pathname === '/index.html')) {
+			const nonce = random(16);
+			res.setHeader('Content-Security-Policy', appCsp(nonce, filesOrigin(host), filesKey));
+			res.setHeader('Cache-Control', 'no-store');
+			return sendFile(res, appHtml.replace(/<head>/i, `<head>${boot(nonce, host)}`), 'text/html; charset=utf-8');
+		}
+		if (req.method === 'GET' && url.pathname.startsWith('/assets/')) {
+			const f = contained(path.join(appDir, 'assets'), decodeURIComponent(url.pathname.slice(8)));
+			if (!f) return send(res, 404, 'not found');
+			return sendFile(res, fs.readFileSync(f), MIME[path.extname(f).toLowerCase()] ?? 'application/octet-stream');
+		}
+		if (req.method === 'GET' && url.pathname === '/api/events') {
+			res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-store', Connection: 'keep-alive' });
+			res.write(': open\n\n');
+			clients.add(res);
+			idle.reset();
+			req.on('close', () => { clients.delete(res); idle.reset(); });
+			return;
+		}
+		if (url.pathname.startsWith('/api/')) {
+			let raw = '';
+			for await (const chunk of req) raw += chunk;
+			let body;
+			if (write && raw.length) {
+				try { body = JSON.parse(raw); } catch { return json(res, 415, { error: `${req.method} ${url.pathname} takes a JSON body` }); }
+			}
+			const log = console.log;
+			console.log = () => {};
+			try {
+				const out = await handler.handle(req.method, req.url.slice(4), body);
+				return json(res, out.status, out.body ?? null);
+			} catch (e) {
+				return json(res, 500, { error: String(e?.message ?? e) });
+			} finally { console.log = log; }
+		}
+		return send(res, 404, 'not found');
+	};
+
+
+	// ---- live updates ------------------------------------------------------------------------
+	let pending = null;
+	let timer = null;
+	const broadcast = (scope) => {
+		const data = `data: ${JSON.stringify(invalidateMessage(scope))}\n\n`;
+		for (const c of clients) c.write(data);
+	};
+	const changed = (file) => {
+		const scope = changeScope(root, file);
+		pending = pending === 'schema' || scope === 'schema' ? 'schema' : 'data';
+		clearTimeout(timer);
+		timer = setTimeout(() => { const s = pending; pending = null; broadcast(s); }, DEBOUNCE_MS);
+	};
+	const watchers = [];
+	const watchDir = (dir) => {
+		if (!fs.existsSync(dir)) return;
+		try { watchers.push(fs.watch(dir, { recursive: true }, (_e, f) => f && changed(path.join(dir, String(f))))); } catch { /* unwatchable */ }
+	};
+	for (const d of ['data', 'state', '.dreamteamer']) watchDir(path.join(root, d));
+	try { for (const l of fs.readdirSync(path.join(root, 'git_modules'))) watchDir(path.join(root, 'git_modules', l, 'data')); } catch { /* no layers */ }
+
+	// ---- lifetime ----------------------------------------------------------------------------
+	let stopped = false;
+	let resolveClosed;
+	const closed = new Promise((r) => { resolveClosed = r; });
+	let v6 = null;
+	const close = async (why = 'stopped') => {
+		try { v6?.close(); } catch { /* not listening */ }
+		if (stopped) return closed;
+		stopped = true;
+		clearTimeout(timer); idle.clear(); clearInterval(ownerTimer);
+		for (const w of watchers) w.close();
+		for (const c of clients) c.end();
+		const done = Promise.all([new Promise((r) => app.close(r)), new Promise((r) => files.close(r))]);
+		app.closeAllConnections?.(); files.closeAllConnections?.();
+		await done;
+		onStop?.(why);
+		resolveClosed(why);
+		return closed;
+	};
+	const idle = {
+		t: null,
+		clear() { clearTimeout(this.t); this.t = null; },
+		reset() {
+			this.clear();
+			if (idleMinutes > 0 && clients.size === 0) this.t = setTimeout(() => close('idle'), idleMinutes * 60_000);
+		},
+	};
+	const ownerTimer = ownerPid ? setInterval(() => { try { process.kill(ownerPid, 0); } catch (e) { if (e.code !== 'EPERM') close('owner gone'); } }, 5_000) : null;
+	ownerTimer?.unref?.();
+
+	const listen = (srv, p) => new Promise((resolve, reject) => { srv.once('error', reject); srv.listen(p, '127.0.0.1', () => { srv.off('error', reject); resolve(srv.address().port); }); });
+	appPort = await listen(app, port);
+	// [::1] answers only to send the page to 127.0.0.1: CSP cannot name an IPv6 ancestor for module frames (cr-modules-008 t13)
+	v6 = http.createServer((req, res) => { baseHeaders(res); res.writeHead(302, { Location: `http://127.0.0.1:${appPort}${req.url ?? '/'}` }); res.end(); });
+	v6.on('error', () => { /* no IPv6 loopback here: nothing to redirect */ });
+	v6.listen(appPort, '::1');
+	filesPort = await listen(files, 0);
+	idle.reset();
+	const signInUrl = () => {
+		const code = random(24);
+		signIns.set(code, Date.now() + signInTtlMs);
+		return `http://127.0.0.1:${appPort}/sign-in/${code}`;
+	};
+	return {
+		appUrl: `http://127.0.0.1:${appPort}`,
+		appPort,
+		filesPort,
+		filesOrigin: filesOrigin(),
+		token,
+		signInUrl,
+		/** cr-modules-008's frame document plugs in here: (segments after /_dt/frame/, req) → { body, type?, headers? } | null */
+		addFrameRoute: (fn) => frameRoutes.push(fn),
+		close,
+		closed,
+	};
+}
+
+function send(res, status, text) {
+	res.writeHead(status, { 'Content-Type': 'text/plain; charset=utf-8' });
+	res.end(text);
+}
+function json(res, status, body) {
+	res.writeHead(status, { 'Content-Type': 'application/json' });
+	res.end(JSON.stringify(body));
+}
+function page(res, status, html) {
+	res.writeHead(status, { 'Content-Type': 'text/html; charset=utf-8', 'Content-Security-Policy': "default-src 'none'" });
+	res.end(`<!doctype html><meta charset="utf-8"><title>dreamteamer</title><p style="font:14px system-ui;margin:2em">${html}</p>`);
+}
+function sendFile(res, body, type, headers = {}) {
+	res.writeHead(200, { 'Content-Type': type, ...headers });
+	res.end(body);
+}