prolog-notebook 0.4.2 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,70 @@
 # Changelog
 
+## [0.5.0] — 2026-08-30
+
+**The CLI can show a notebook.** Until now the only way to see one running was to clone this
+repository, start a dev server, symlink your file into `notebooks/` and pass `?src=`. A
+notebook tool whose notebooks could only be read from its own source tree was not finished.
+
+### Added
+
+- **`prolog-notebook view <file>`** — serves the chapter and opens it, cells live. It serves
+  exactly what `build` writes, from memory, streaming the runtime and the engine out of the
+  installed package: no temp directory, nothing to clean up, and no chance of the page you look
+  at differing from the page you would publish. `--port` (8777 by default, and it says so when
+  it has to take another), `--no-open`.
+
+- **`prolog-notebook build <file> --out <dir>`** — a plain static directory you can host, zip
+  or send:
+
+      index.html  app.js  notebook.css  lib/*.js  swipl/swipl-bundle.js
+
+  No bundler. The runtime is already plain ES modules with relative imports, so the build is a
+  prerender and a copy.
+
+  **What the page does not contain** is the half worth stating. No markdown library — the prose
+  is HTML by the time it is written, which is why `page.js` and `notebook.js` are separate
+  files, and a test now enforces that neither the parser nor the renderer reaches a reader. And
+  no engine on the path to *reading*: the 6.2 MB sits in the directory untouched until somebody
+  presses Run.
+
+### Changed
+
+- `editsOf()` moved from `page.js` to `notebook.js`. A built page needs it and must not import
+  the renderer — and so 137 kB of markdown parser — to get it.
+- `viewer/` is now what it always should have been: the shell for working on the renderer
+  itself. Everyone else uses `view`.
+
+## [0.4.3] — 2026-08-30
+
+### Added
+
+- **It offers to update itself, and then carries on** — one command, no re-run:
+
+      $ prolog-notebook run ch04.prolog.md
+      You have Prolog Notebook 0.4.2. The latest is 0.4.3.
+      Update and continue on the new version? [Y/n] y
+      Updating with npm i -g prolog-notebook@0.4.3
+      You now have Prolog Notebook 0.4.3.
+      Continuing on the new version.
+        ✓ p-family
+        ✓ q-is-son — 6 solutions
+
+  The offer comes **before** the work, because that is the only point at which the answer can
+  change anything. It costs a network round trip once a day rather than once a run, since the
+  answer is cached. Continuing is a child process on the same path — npm replaces the contents
+  of the package directory, so the command the reader typed now holds the new version — with
+  stdio inherited, the exit code proxied, and an environment marker that stops the new process
+  checking again.
+
+- **`prolog-notebook upgrade`**, for when you already know. It replaces this copy only where
+  it can prove how it was installed: a global `npm i -g` it will do, a dependency of somebody's
+  project it will not touch, and a source checkout is git's business. It installs the exact
+  version you were told about rather than `@latest`, which can move in between.
+
+  Both only where there is somebody to ask — stdin and stderr must be terminals. In a pipe, a
+  script or CI the notice comes after the work, with the command to type.
+
 ## [0.4.2] — 2026-08-30
 
 ### Fixed

package/README.md

@@ -40,6 +40,27 @@ So a query cell gives you the first solution, and then you step.
 
 ## Try it
 
+```sh
+npm i -g prolog-notebook
+prolog-notebook view notebooks/ch04-cut.prolog.md
+```
+
+That is a chapter — the `once/1` placement puzzle, a real worked section rather than a widget
+demo. It opens in your browser with the cells live: press Run, then `; next`. Nothing is
+installed but the command, and the chapter is readable before the engine arrives.
+
+To send it to somebody, or host it:
+
+```sh
+prolog-notebook build ch04-cut.prolog.md --out site/
+```
+
+A plain directory: prerendered HTML with the saved answers in it, the runtime beside it, and
+the 6.2 MB engine that is fetched only when a reader presses Run. No bundler, no build step of
+your own, nothing to configure.
+
+### Or from a checkout
+
 ```sh
 git clone https://github.com/jarecsni/prolog-notebook
 cd prolog-notebook
@@ -59,7 +80,7 @@ are all in it, and there is no HTML anywhere. Point the viewer at any other note
 | | |
 |---|---|
 | `notebooks/` | chapters. The product. |
-| `viewer/` | one shell page that renders any of them. Replaced by `build` in v0.3. |
+| `viewer/` | the development shell, for working on the renderer itself. `view` and `build` are what everyone else uses. |
 
 The chapter also reads on the repo page, [as a file](notebooks/ch04-cut.prolog.md), with no
 build step and no site: prose as prose, Prolog syntax-highlighted, the saved answers in place,
@@ -93,6 +114,10 @@ chapter changes nothing.
 | `--version` | the tool's version, **the SWI-Prolog version it will run your chapters with**, and the copyright |
 | `--check-update` | ask npm whether a newer one exists, and say so either way |
 
+```sh
+prolog-notebook upgrade      # fetch the latest
+```
+
 Two things it will not do. A query stopped at the limit is written **without** a terminator,
 which is the format's way of saying the search was never exhausted — `false.` there would be a
 forgery. And if a program cell fails to load, nothing is written at all: every answer below it
@@ -105,6 +130,29 @@ reach is reported once a day rather than on every command — silence there woul
 indistinguishable from *you are up to date*. Ask outright with `--check-update` and it answers
 either way.
 
+When it finds something newer **and you are at a terminal**, it offers to fetch it *before*
+doing the work — and if you say yes it upgrades, then runs your command on the new version.
+One command, no re-run:
+
+```
+$ prolog-notebook run ch04.prolog.md
+You have Prolog Notebook 0.4.0. The latest is 0.4.2.
+Update and continue on the new version? [Y/n] y
+Updating with npm i -g prolog-notebook@0.4.2
+You now have Prolog Notebook 0.4.2.
+Continuing on the new version.
+  ✓ p-family
+  ✓ q-is-son — 6 solutions
+```
+
+That costs a network round trip once a day rather than once a run, because the answer is
+cached. Down a pipe or in a script there is nobody to ask, so it prints `Update with:
+prolog-notebook upgrade` after the work instead — a question nobody can answer is a hang.
+
+`upgrade` replaces this copy only when it can prove how it was installed. A global `npm i -g`
+it will do; a dependency of somebody's project it will not touch, and a source checkout is
+git's business. Guessing wrong there breaks a project while trying to help.
+
 It has no defence against a non-terminating goal yet — the engine runs in this process, so
 `loop :- loop.` hangs the command. Say the word `--limit` all you like; a runaway *consult* is
 not a solution count. Fixing it properly means a worker thread, and it is the prerequisite for
@@ -220,8 +268,8 @@ Working and tested:
 - program cells and query cells with `Run` / `; next` / `all` / `stop`, per-cell reset, and a
   page that says what the engine is holding
 - `hold` and `rerun="auto"` — the author decides what a reader may see and when it refreshes
-- **the CLI runner**: `prolog-notebook run` executes a chapter headlessly and writes its
-  answers back
+- **the CLI**: `run` executes a chapter headlessly and writes its answers back, `view` opens it
+  in a browser, `build` writes a page you can host or send
 - download your own copy of a chapter, answers and all
 - 186 passing tests
 
@@ -229,7 +277,6 @@ Not built yet:
 
 - `--check` — run a chapter in CI and fail the build when its answers have drifted. Needs a
   timeout first: a test suite that can hang forever is not a test suite.
-- `build` — a static page a reader can open, without a dev server
 - custom elements (`<prolog-program>`, `<prolog-query>`) so notebooks drop into any static site
 - a VS Code notebook controller — VS Code supplies the UI, this supplies the kernel, still no Python
 - persistence, so a reader's edits survive a reload

package/bin/prolog-notebook.mjs

@@ -4,15 +4,19 @@
 // Code "run all" and a future --check get the same behaviour without going
 // through a shell (869ectt38, 869ectt3e).
 import { createRequire } from 'node:module';
-import { readFileSync, writeFileSync } from 'node:fs';
-import { basename } from 'node:path';
+import { spawn } from 'node:child_process';
+import { copyFileSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
 import { parse, NotebookError } from '../src/format.js';
 import { prologVersion } from '../src/engine.js';
 import { buildLine, currentBuild } from '../src/build-info.js';
 import { banner, VERSION } from '../src/version.js';
 import { updateNotice } from '../src/update.js';
+import { confirm, describeInstall, globalRoot, install, relaunch, upgradePlan } from '../src/upgrade.js';
 import { exportSource } from '../src/export.js';
 import { runNotebook, DEFAULT_LIMIT } from '../src/run.js';
+import { buildFiles } from '../src/build.js';
+import { serve } from '../src/serve.js';
 
 // The engine is imported WHERE IT IS USED, never at the top. src/node.js pulls in
 // 5.9 MB of WebAssembly at module scope, so a static import here would mean that
@@ -36,12 +40,18 @@ const require = createRequire(import.meta.url);
 
 const USAGE = `prolog-notebook — Jupyter-style notebooks for Prolog
 
+  prolog-notebook view <file.prolog.md>    read it in a browser, cells and all
+  prolog-notebook build <file.prolog.md>   write a page you can host or send
   prolog-notebook run <file.prolog.md>...   run every cell, write the answers back
+  prolog-notebook upgrade                  fetch the latest version
 
 Options
   --limit <n>     solutions to take from one query before stopping (default ${DEFAULT_LIMIT})
   --stdout        print the result instead of writing the file
   --quiet         report only failures
+  --out <dir>     where build writes (default: <file>-site)
+  --port <n>      what view listens on (default 8777)
+  --no-open       view prints the URL instead of opening a browser
   --version       version, engine and copyright
   --check-update  ask npm whether a newer one exists, and say so either way
   -h, --help      this
@@ -91,6 +101,63 @@ async function version() {
   return `${lines.join('\n')}\n\n`;
 }
 
+/**
+ * Fetch the latest, if this copy is one we know how to replace.
+ *
+ * @param {string} version what to install
+ * @returns {Promise<number>} an exit code
+ */
+async function upgrade(version) {
+  const packageRoot = new URL('..', import.meta.url).pathname;
+  const kind = describeInstall({ packageRoot, globalRoot: await globalRoot() });
+  const plan = upgradePlan(kind, version);
+  if (plan.say) {
+    process.stderr.write(`${plan.say}\n`);
+    return 1;
+  }
+  process.stderr.write(`Updating with ${NPM_LINE} ${plan.argv.join(' ')}\n`);
+  if (!(await install(plan.argv))) {
+    process.stderr.write('npm could not complete the update.\n');
+    return 1;
+  }
+  process.stderr.write(`You now have Prolog Notebook ${version}.\n`);
+  return 0;
+}
+
+/**
+ * Offer it, but only where a question is a question.
+ *
+ * A pipe, a script and CI are all places where waiting for an answer is a hang,
+ * so the notice is simply printed there. Both streams are checked because the
+ * question goes to stderr and the answer comes from stdin.
+ */
+/**
+ * Is there somebody at the other end?
+ *
+ * Both streams, because the question goes to stderr and the answer comes back on
+ * stdin. A pipe, a script and CI are all places where a question is a hang.
+ */
+function canAsk() {
+  return Boolean(process.stdin.isTTY && process.stderr.isTTY);
+}
+
+async function offerUpgrade(newer) {
+  if (!canAsk()) {
+    // Nobody to ask, so say what to type instead. `prolog-notebook upgrade`
+    // rather than the npm line: it knows how this copy was installed, and the
+    // npm line is wrong for a project dependency.
+    process.stderr.write('Update with: prolog-notebook upgrade\n');
+    return null;
+  }
+  if (!(await confirm('Update now?'))) {
+    process.stderr.write('  (run `prolog-notebook upgrade` whenever you like)\n');
+    return null;
+  }
+  return upgrade(newer);
+}
+
+const NPM_LINE = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+
 async function main(argv) {
   const args = argv.slice(2);
   if (!args.length || args.includes('-h') || args.includes('--help')) {
@@ -108,18 +175,26 @@ async function main(argv) {
   // forces the check that would otherwise wait for the day to turn over.
   const asked = args.includes('--check-update');
   if (asked && args.filter((a) => !a.startsWith('-')).length === 0) {
-    const notice = await updateNotice({ version: VERSION, force: true });
-    process.stderr.write(`${notice}\n`);
-    return 0;
+    const { message, newer } = await updateNotice({ version: VERSION, force: true });
+    if (message) process.stderr.write(`${message}\n`);
+    return newer ? (await offerUpgrade(newer)) ?? 0 : 0;
   }
 
   const command = args.shift();
+  if (command === 'view' || command === 'build') return page(command, args);
+  if (command === 'upgrade') {
+    const { message, newer } = await updateNotice({ version: VERSION, force: true });
+    if (message) process.stderr.write(`${message}\n`);
+    return newer ? upgrade(newer) : 0;
+  }
   if (command !== 'run') {
     process.stderr.write(`unknown command "${command}"\n\n${USAGE}`);
     return 2;
   }
 
   const options = { limit: DEFAULT_LIMIT, stdout: false, quiet: false };
+  // Whether the offer has already been made, before the work started.
+  let checked = false;
   const files = [];
   while (args.length) {
     const arg = args.shift();
@@ -145,6 +220,31 @@ async function main(argv) {
   }
   if (!options.quiet) process.stderr.write(`${RUNAWAY_WARNING}\n`);
 
+  // BEFORE THE WORK, when there is somebody to ask — because the point of asking
+  // is to run the NEW version, and that is only possible while there is still
+  // something to run. Afterwards the files are written and the answer comes too
+  // late to change them.
+  //
+  // It costs a network round trip once a day, not once a run: the rest of the day
+  // is a file read. Measured at 25-120 ms against npm, against a run that spends
+  // seconds in Prolog.
+  if (canAsk() && !options.quiet) {
+    const ahead = await updateNotice({ version: VERSION, force: asked })
+      .catch(() => ({ message: null, newer: null }));
+    if (ahead.message) process.stderr.write(`${ahead.message}\n`);
+    if (ahead.newer && await confirm('Update and continue on the new version?')) {
+      if ((await upgrade(ahead.newer)) === 0) {
+        process.stderr.write('Continuing on the new version.\n');
+        // The path has not changed — npm replaced what is behind it — so this is
+        // the same command, running the bytes that have just arrived.
+        return relaunch(process.argv);
+      }
+      process.stderr.write('Carrying on with the version you have.\n');
+    }
+    // Asked and answered: the check below has nothing left to say.
+    checked = true;
+  }
+
   // STARTED NOW, READ AT THE END. The registry is somebody else's machine on
   // somebody else's network, and none of that should stand between the reader
   // and their answers — so the question is asked while the work happens and the
@@ -153,9 +253,11 @@ async function main(argv) {
   // Not asked at all under --quiet, unless it was asked for outright: --quiet
   // means "report only failures", and news about a newer version is not one. Not
   // starting the request is better than starting it and discarding the answer.
-  const update = options.quiet && !asked
-    ? Promise.resolve(null)
-    : updateNotice({ version: VERSION, force: asked }).catch(() => null);
+  // The other half: nobody to ask, so the question is asked ALONGSIDE the work
+  // and reported at the end. A terminal has had its offer already.
+  const update = checked || (options.quiet && !asked)
+    ? Promise.resolve({ message: null, newer: null })
+    : updateNotice({ version: VERSION, force: asked }).catch(() => ({ message: null, newer: null }));
 
   // One engine for the whole invocation, restarted between files. A notebook is
   // a world of its own — one cell is one virtual file, and two chapters may
@@ -172,11 +274,88 @@ async function main(argv) {
 
   // stderr, always: `run --stdout` is a notebook going down a pipe, and a version
   // notice in the middle of it would corrupt the file it is printing.
-  const notice = await update;
-  if (notice) process.stderr.write(`${notice}\n`);
+  const { message, newer } = await update;
+  if (message) process.stderr.write(`${message}\n`);
+  // Offered AFTER the work, and never re-running it: the files are written, and
+  // a command that repeated itself on a newer version would write them twice.
+  if (newer) await offerUpgrade(newer);
   return status;
 }
 
+/**
+ * `build` and `view`, which are the same page put in two different places.
+ *
+ * Neither runs a cell: a chapter's answers are already in the file, which is the
+ * whole reason a built page is readable before any engine arrives. Use `run` to
+ * put them there.
+ */
+async function page(command, args) {
+  const options = { out: null, port: 8777, open: true };
+  const files = [];
+  while (args.length) {
+    const arg = args.shift();
+    if (arg === '--out') options.out = args.shift();
+    else if (arg === '--port') {
+      options.port = Number(args.shift());
+      if (!Number.isInteger(options.port) || options.port < 0 || options.port > 65535) {
+        process.stderr.write('--port takes a port number\n');
+        return 2;
+      }
+    } else if (arg === '--no-open') options.open = false;
+    else if (arg.startsWith('-')) {
+      process.stderr.write(`unknown option "${arg}"\n`);
+      return 2;
+    } else files.push(arg);
+  }
+  if (files.length !== 1) {
+    process.stderr.write(`${command} takes exactly one notebook\n`);
+    return 2;
+  }
+
+  const file = files[0];
+  let built;
+  try {
+    const source = readFileSync(file, 'utf8');
+    built = buildFiles(parse(source), source, { filename: basename(file) });
+  } catch (e) {
+    process.stderr.write(`${file}: ${e.message}\n`);
+    return 1;
+  }
+
+  if (command === 'build') {
+    const out = options.out ?? `${file.replace(/\.prolog\.md$/, '')}-site`;
+    for (const [name, entry] of built) {
+      const target = join(out, name);
+      mkdirSync(dirname(target), { recursive: true });
+      if (entry.text !== undefined) writeFileSync(target, entry.text);
+      else copyFileSync(entry.copy, target);
+    }
+    process.stderr.write(`${out}: ${built.size} files\n`);
+    process.stderr.write(`Open ${join(out, 'index.html')} over HTTP, or host the directory.\n`);
+    return 0;
+  }
+
+  const server = await serve(built, { port: options.port });
+  process.stderr.write(`${basename(file)} at ${server.url}\n`);
+  if (server.port !== options.port) {
+    process.stderr.write(`(${options.port} was taken)\n`);
+  }
+  process.stderr.write('Ctrl-C to stop.\n');
+  if (options.open) openInBrowser(server.url);
+  // Deliberately never resolves: the server is the command.
+  return new Promise(() => {});
+}
+
+/** Hand the URL to whatever the desktop uses. Failure is not worth reporting. */
+function openInBrowser(url) {
+  const opener = { darwin: 'open', win32: 'start' }[process.platform] ?? 'xdg-open';
+  try {
+    spawn(opener, [url], { stdio: 'ignore', detached: true }).unref();
+  } catch {
+    // No desktop, or no opener: the URL is on screen either way.
+  }
+}
+
 async function runFile(file, session, options) {
   const name = basename(file);
   let notebook;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prolog-notebook",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "Jupyter-style notebooks for Prolog. Runs in the browser, installs nothing.",
   "type": "module",
   "main": "./src/node.js",

package/src/build-info.json

@@ -1,4 +1,4 @@
 {
-  "commit": "a4ae8f0",
-  "built": "2026-08-30 15:34:45 UTC"
+  "commit": "084182f",
+  "built": "2026-08-30 16:32:07 UTC"
 }

package/src/build.js

@@ -0,0 +1,140 @@
+// A chapter to a page that stands on its own (869ermwfv).
+//
+// The output is a plain static directory: open it, host it, zip it and send it.
+// Nothing here is a bundler — the runtime is already plain ES modules with
+// relative imports, so the "build" is a prerender plus a copy.
+//
+// WHAT THE PAGE DOES NOT CONTAIN is the interesting half. No markdown library:
+// the prose is HTML by the time this writes it, which is exactly why page.js and
+// notebook.js were split — a prerendered chapter needs the wiring, not the
+// parser. And no engine on the critical path: 6.2 MB of WebAssembly sits in the
+// directory and is fetched the first time somebody presses Run, so the chapter is
+// readable with none of it, which is the property this whole project exists for.
+//
+// NOTHING IS WRITTEN HERE. This returns a MAP of what the directory should
+// contain — generated text, or a path to copy — so that `build` can write it,
+// `view` can serve it, and a test can read it, without any of the three
+// disagreeing about what a page is.
+import { renderNotebook } from './render.js';
+
+/** The runtime a page needs. Copied side by side, so their relative imports hold. */
+export const RUNTIME = [
+  'notebook.js', 'browser.js', 'session.js', 'engine.js', 'worker.js',
+  'clauses.js', 'export.js', 'format.js', 'version.js',
+];
+
+/** The one engine file: the bundle carries its own data. */
+export const ENGINE = 'swipl-bundle.js';
+
+/**
+ * The page, as a map of file name to what belongs there.
+ *
+ * @param {{frontMatter: Map<string,string>, cells: object[]}} notebook parsed
+ * @param {string} source the notebook's own bytes, for the download
+ * @param {{filename?: string, src?: URL, engine?: URL}} [options]
+ *   `src` is the directory holding the runtime modules and `engine` the
+ *   directory holding swipl-wasm's bundle — arguments rather than constants so a
+ *   test can point them anywhere and an installed package can find its own.
+ * @returns {Map<string, {text: string}|{copy: URL}>}
+ */
+export function buildFiles(notebook, source, options = {}) {
+  const {
+    filename = 'notebook.prolog.md',
+    src = new URL('./', import.meta.url),
+    engine = new URL('../node_modules/swipl-wasm/dist/swipl/', import.meta.url),
+  } = options;
+
+  const files = new Map();
+  files.set('index.html', { text: page(notebook) });
+  files.set('app.js', { text: app(source, filename) });
+  files.set('notebook.css', { copy: new URL('notebook.css', src) });
+  for (const module of RUNTIME) files.set(`lib/${module}`, { copy: new URL(module, src) });
+  files.set(`swipl/${ENGINE}`, { copy: new URL(ENGINE, engine) });
+  return files;
+}
+
+/**
+ * The chapter's own title, from its first H1 (format §2).
+ *
+ * Written into the HTML at build time rather than set by script on load: it is
+ * the browser tab, the bookmark and the thing a link preview shows, and none of
+ * those wait for JavaScript.
+ */
+function titleOf(notebook) {
+  for (const cell of notebook.cells) {
+    if (cell.kind !== 'markdown') continue;
+    const heading = /^#\s+(.+)$/m.exec(cell.source);
+    if (heading) return heading[1].trim();
+  }
+  return 'A Prolog notebook';
+}
+
+function escapeHtml(text) {
+  return String(text).replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }[c]));
+}
+
+function page(notebook) {
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(titleOf(notebook))}</title>
+<link rel="stylesheet" href="notebook.css">
+</head>
+<body>
+<main>
+${renderNotebook(notebook)}
+<!--
+  THE CHAPTER ABOVE IS ALREADY READABLE. Everything below is the runtime that
+  makes it runnable, and none of it is needed to read a word.
+-->
+<div id="boot-warning">
+  <strong>This notebook is not running.</strong>
+  The page loaded but its JavaScript did not. The usual cause is opening
+  <code>index.html</code> straight from disk — browsers block ES modules over
+  <code>file://</code>. Serve it over HTTP instead, or run
+  <code>prolog-notebook view</code> on the notebook itself.
+  The chapter is readable either way; only the buttons need this.
+</div>
+</main>
+<script type="module" src="app.js"></script>
+</body>
+</html>
+`;
+}
+
+/**
+ * The wiring, and the source it hands back when a reader asks for a copy.
+ *
+ * The notebook's own bytes are embedded because "the chapter as published" has to
+ * mean the bytes the author wrote, not a re-serialisation of the model — a
+ * hand-written chapter would otherwise come back reformatted.
+ */
+function app(source, filename) {
+  return `// Generated by prolog-notebook build. The chapter is already in index.html;
+// this only wires it up.
+import { editsOf, mount, offerDownload } from './lib/notebook.js';
+import { parse } from './lib/format.js';
+import { exportSource } from './lib/export.js';
+
+const SOURCE = ${JSON.stringify(source)};
+const FILENAME = ${JSON.stringify(filename)};
+
+const root = document.querySelector('main');
+// The engine lives beside this file rather than in a node_modules the browser
+// cannot see, so its location is passed rather than guessed.
+const cells = mount(root, {
+  swiplUrl: new URL('./swipl/${ENGINE}', import.meta.url).href,
+});
+
+const notebook = parse(SOURCE);
+offerDownload(root, {
+  produce: () => ({ filename: FILENAME, text: exportSource(notebook, editsOf(cells)) }),
+  published: () => ({ filename: FILENAME, text: SOURCE }),
+  isEdited: () => cells.programs.some((p) => p.isEdited())
+    || cells.queries.some((q) => q.isEdited()),
+  on: cells.on,
+});
+`;
+}

package/src/notebook.js

@@ -1338,6 +1338,31 @@ function mountQuery(cell, options, bus, { above = [], below = [], prediction = n
   };
 }
 
+/**
+ * What the cells now say, keyed by id, for src/export.js to fold into the model.
+ *
+ * HERE RATHER THAN IN page.js, because a built page has its HTML already and must
+ * not import the renderer to get this — page.js pulls in markdown-it, and 137 KB
+ * of markdown parser to answer "what does this textarea say" is the opposite of
+ * why these two files are separate.
+ *
+ * @param {{programs: object[], queries: object[]}} cells what mount() returned
+ * @returns {Map<string, object>}
+ */
+export function editsOf(cells) {
+  const map = new Map();
+  for (const program of cells.programs) {
+    map.set(program.name, { source: program.text() });
+  }
+  for (const query of cells.queries) {
+    const output = query.output();
+    map.set(query.id, output === undefined
+      ? { goal: query.goal() }
+      : { goal: query.goal(), output });
+  }
+  return map;
+}
+
 function autosizeNow(ta) {
   ta.style.height = 'auto';
   ta.style.height = `${ta.scrollHeight}px`;

package/src/page.js

@@ -6,7 +6,7 @@
 // a prerendered chapter from downloading 137 KB of markdown-it to render nothing.
 import { parse } from './format.js';
 import { renderNotebook } from './render.js';
-import { mount, offerDownload } from './notebook.js';
+import { editsOf, mount, offerDownload } from './notebook.js';
 import { exportSource, filenameFor } from './export.js';
 
 /**
@@ -33,7 +33,7 @@ export function renderInto(text, root, options = {}) {
   // but a markdown cell has been rendered to HTML and cannot be read back out of
   // it — a chapter exported from the DOM alone would lose its writing.
   offerDownload(root, {
-    produce: () => ({ filename, text: exportSource(notebook, edits(cells)) }),
+    produce: () => ({ filename, text: exportSource(notebook, editsOf(cells)) }),
     // THE BYTES THE PAGE WAS GIVEN, not the model written out again. A
     // re-serialisation would be canonical form, which is not necessarily the
     // author's file: a hand-written chapter with no ids, or attributes in
@@ -49,21 +49,6 @@ export function renderInto(text, root, options = {}) {
   return notebook;
 }
 
-/** What the cells now say, keyed by id, for src/export.js to fold into the model. */
-function edits(cells) {
-  const map = new Map();
-  for (const program of cells.programs) {
-    map.set(program.name, { source: program.text() });
-  }
-  for (const query of cells.queries) {
-    const output = query.output();
-    map.set(query.id, output === undefined
-      ? { goal: query.goal() }
-      : { goal: query.goal(), output });
-  }
-  return map;
-}
-
 /**
  * Fetch a `.prolog.md` and render it.
  *

package/src/serve.js

@@ -0,0 +1,80 @@
+// Showing the chapter you are writing (869ermwjv).
+//
+// It serves exactly what `build` writes — the same map — so the page somebody
+// looks at and the page they would publish cannot drift apart. Generated files
+// come from memory and copied ones are streamed from wherever they live, so
+// nothing is written to disk and there is nothing to clean up.
+//
+// A server of about forty lines rather than a dependency: it answers GET for a
+// fixed set of paths that this process generated, and 404s everything else. It
+// is not a static file server and must not become one.
+import { createReadStream } from 'node:fs';
+import { createServer } from 'node:http';
+
+const TYPES = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.wasm': 'application/wasm',
+  '.data': 'application/octet-stream',
+  '.md': 'text/markdown; charset=utf-8',
+};
+
+export function contentType(name) {
+  const dot = name.lastIndexOf('.');
+  return TYPES[name.slice(dot)] ?? 'application/octet-stream';
+}
+
+/**
+ * Serve a built page.
+ *
+ * @param {Map<string, {text: string}|{copy: URL}>} files what build produced
+ * @param {{port?: number, host?: string}} [options]
+ * @returns {Promise<{url: string, port: number, close: () => Promise<void>}>}
+ */
+export async function serve(files, { port = 8777, host = '127.0.0.1' } = {}) {
+  const server = createServer((request, response) => {
+    // Only GET, and only the names this process generated: the path never
+    // reaches the filesystem, so there is nothing for a `..` to escape into.
+    const name = decodeURIComponent(new URL(request.url, 'http://x').pathname).replace(/^\//, '');
+    const entry = files.get(name === '' ? 'index.html' : name);
+    if (request.method !== 'GET' || !entry) {
+      response.writeHead(404, { 'content-type': 'text/plain' }).end('not found\n');
+      return;
+    }
+    response.writeHead(200, {
+      'content-type': contentType(name || 'index.html'),
+      // A page being written is a page that changes under the reader.
+      'cache-control': 'no-store',
+    });
+    if (entry.text !== undefined) {
+      response.end(entry.text);
+      return;
+    }
+    createReadStream(entry.copy).on('error', () => response.end()).pipe(response);
+  });
+
+  const listening = await listen(server, port, host);
+  return {
+    url: `http://${host}:${listening}/`,
+    port: listening,
+    close: () => new Promise((resolve) => server.close(resolve)),
+  };
+}
+
+/**
+ * Take the port asked for, or any port at all.
+ *
+ * A tool that dies because something else is on 8777 is a tool that makes the
+ * reader find out what. It says which port it took instead.
+ */
+function listen(server, port, host) {
+  return new Promise((resolve, reject) => {
+    server.once('error', (error) => {
+      if (error.code !== 'EADDRINUSE') return reject(error);
+      server.listen(0, host, () => resolve(server.address().port));
+    });
+    server.listen(port, host, () => resolve(server.address().port));
+  });
+}

package/src/update.js

@@ -124,7 +124,11 @@ export function isNewer(latest, current) {
 }
 
 /**
- * The line to print, or null for silence.
+ * What to say, and what was found.
+ *
+ * An object rather than a string because a caller may want to ACT on it — offer
+ * to upgrade — and parsing our own sentence back into a version number would be
+ * a worse way to learn what we already knew.
  *
  * @param {object} options
  * @param {string} options.version what this copy is
@@ -134,7 +138,7 @@ export function isNewer(latest, current) {
  * @param {{read: Function, write: Function}} [options.store]
  * @param {() => Promise<string|null>} [options.latest]
  * @param {object} [options.env]
- * @returns {Promise<string|null>}
+ * @returns {Promise<{message: string|null, newer: string|null}>}
  */
 export async function updateNotice({
   version,
@@ -145,7 +149,12 @@ export async function updateNotice({
   latest = latestFromRegistry,
   env = process.env,
 } = {}) {
-  if (!force && (env.CI || env.NO_UPDATE_NOTIFIER)) return null;
+  const quiet = { message: null, newer: null };
+  // UPGRADED is the loop guard: the process that replaced itself re-runs this
+  // command on the new version, and that one must not go round again. A failed
+  // or partial upgrade would otherwise re-exec for ever.
+  if (!force && (env.CI || env.NO_UPDATE_NOTIFIER || env.PROLOG_NOTEBOOK_UPGRADED)) return quiet;
+  if (env.PROLOG_NOTEBOOK_UPGRADED) return quiet;
 
   const remembered = store.read();
   const fresh = !force && remembered && now - remembered.checked < ttl;
@@ -155,14 +164,20 @@ export async function updateNotice({
   if (!fresh) store.write({ checked: now, latest: newest ?? null });
 
   if (!newest) {
-    return fresh && !force ? null : 'Could not reach the npm registry to check for updates.';
+    return fresh && !force
+      ? quiet
+      : { message: 'Could not reach the npm registry to check for updates.', newer: null };
   }
   // BOTH LINES START WITH WHAT YOU HAVE, because that is the question being
   // asked. "Prolog Notebook 0.4.0 is the latest" states a fact about the world
   // and leaves the reader to work out that it is also a fact about them.
   if (isNewer(newest, version)) {
-    return `You have Prolog Notebook ${version}. The latest is ${newest}.\n`
-      + 'Update with: npm i -g prolog-notebook';
+    return {
+      message: `You have Prolog Notebook ${version}. The latest is ${newest}.`,
+      newer: newest,
+    };
   }
-  return force ? `You have the latest version of Prolog Notebook, ${version}.` : null;
+  return force
+    ? { message: `You have the latest version of Prolog Notebook, ${version}.`, newer: null }
+    : quiet;
 }

package/src/upgrade.js

@@ -0,0 +1,128 @@
+// Updating itself, which is mostly a question of knowing how it was installed.
+//
+// A global `npm i -g`, a project dependency, an npx run, a pnpm or bun global,
+// a git checkout — each needs a different answer, and running `npm i -g` from
+// the wrong one either fails or upgrades something the reader did not mean. So
+// this proves the global case and REFUSES THE REST WITH THE RIGHT COMMAND
+// rather than guessing: a tool that breaks somebody's project while trying to
+// help is worse than one that tells them what to type.
+//
+// Nothing here happens without being asked. See bin/prolog-notebook.mjs for the
+// prompt, which only appears at a terminal — a pipe, a script and CI are all
+// places where a question is a hang.
+import { spawn } from 'node:child_process';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const run = promisify(execFile);
+
+/** npm is a batch file on Windows, and spawn will not find it otherwise. */
+export const NPM = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+
+/**
+ * Which kind of copy is this?
+ *
+ * @param {{packageRoot: string, globalRoot: string|null}} where
+ * @returns {'global'|'local'|'source'}
+ */
+export function describeInstall({ packageRoot, globalRoot }) {
+  if (globalRoot && packageRoot.startsWith(globalRoot)) return 'global';
+  // `node_modules` in the path and not the global root: somebody's project
+  // depends on this, and upgrading it globally would leave that project on the
+  // version it pinned while changing a tool they did not ask about.
+  if (packageRoot.includes(`${'node_modules'}`)) return 'local';
+  return 'source';
+}
+
+/**
+ * What to do about it — a command to run, or words to print.
+ *
+ * @param {'global'|'local'|'source'} kind
+ * @param {string} version
+ * @returns {{argv: string[]}|{say: string}}
+ */
+export function upgradePlan(kind, version) {
+  if (kind === 'global') return { argv: ['i', '-g', `prolog-notebook@${version}`] };
+  if (kind === 'local') {
+    return {
+      say: 'This copy is a dependency of a project rather than a global install.\n'
+        + `Upgrade it there: npm i prolog-notebook@${version}`,
+    };
+  }
+  return {
+    say: 'This copy is a source checkout, not an install. Upgrade it with git.',
+  };
+}
+
+/** Where npm keeps global packages, or null if it will not say. */
+export async function globalRoot(exec = run) {
+  try {
+    const { stdout } = await exec(NPM, ['root', '-g'], { timeout: 5000 });
+    return stdout.trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Ask a yes/no question, defaulting to yes.
+ *
+ * ON STDERR, always: `run --stdout` is a notebook going down a pipe, and a
+ * question in the middle of it would corrupt the file it is writing.
+ *
+ * @returns {Promise<boolean>}
+ */
+export async function confirm(question, { input = process.stdin, output = process.stderr } = {}) {
+  const { createInterface } = await import('node:readline/promises');
+  const rl = createInterface({ input, output });
+  try {
+    const answer = await rl.question(`${question} [Y/n] `);
+    return !/^n/i.test(answer.trim());
+  } catch {
+    // Ctrl-C, a closed stream: not an answer, so not a yes.
+    return false;
+  } finally {
+    rl.close();
+  }
+}
+
+/**
+ * Do it, showing npm's own output rather than a spinner of our own.
+ *
+ * @returns {Promise<boolean>} whether npm was happy
+ */
+export function install(argv, spawnImpl = spawn) {
+  return new Promise((resolve) => {
+    const child = spawnImpl(NPM, argv, { stdio: ['ignore', 'inherit', 'inherit'] });
+    child.on('error', () => resolve(false));
+    child.on('close', (code) => resolve(code === 0));
+  });
+}
+
+/**
+ * Run this same command again, on the version that has just replaced us.
+ *
+ * THE PATH DOES NOT CHANGE, which is what makes this work: npm replaces the
+ * contents of the package directory, and the bin the reader typed still points
+ * at the same file. So the script to run is the one we are already running — its
+ * bytes are simply new.
+ *
+ * A child rather than a true exec, because Node has no execve: stdio is
+ * inherited so it looks like one process, and the child's exit code becomes
+ * ours. The marker in the environment stops the new process checking for updates
+ * again, which is what would otherwise turn a failed upgrade into a loop.
+ *
+ * @param {string[]} argv the original process.argv
+ * @param {Function} [spawnImpl]
+ * @returns {Promise<number>} the exit code to leave with
+ */
+export function relaunch(argv, spawnImpl = spawn) {
+  return new Promise((resolve) => {
+    const child = spawnImpl(argv[0], argv.slice(1), {
+      stdio: 'inherit',
+      env: { ...process.env, PROLOG_NOTEBOOK_UPGRADED: '1' },
+    });
+    child.on('error', () => resolve(1));
+    child.on('close', (code) => resolve(code ?? 0));
+  });
+}

package/src/version.js

@@ -10,7 +10,7 @@
 export const NAME = 'Prolog Notebook';
 
 /** Must equal package.json's `version` — test/run.test.mjs enforces it. */
-export const VERSION = '0.4.2';
+export const VERSION = '0.5.0';
 
 /** The two facts a licence notice is actually made of. */
 export const YEAR = '2026';