prolog-notebook 0.6.5 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,104 @@
 # Changelog
 
+## [0.7.0] — 2026-08-31
+
+A site of notebooks, rather than a folder of unrelated pages.
+
+### Added
+
+- **A site has exactly one runtime, and `build` keeps it that way.** A page's `app.js` and the
+  shared `lib/` are not a stable contract — `offerDownload` gained arguments in #28, `editsOf`
+  moved modules in #40 — so a site holding two generations of page has no safe resting state:
+  overwrite `lib/` and the older page imports a symbol that has moved; leave it and the page just
+  built is the broken one. So a build reconciles rather than warns.
+
+  | the site was written by | what happens |
+  |---|---|
+  | the same versions | the page is written and **nothing else is touched** — the 6.2 MB engine is not copied again |
+  | an older version | the shared files are replaced and **every page is regenerated**, said out loud: `runtime 0.6.0 → 0.7.0 · 2 pages regenerated` |
+  | an older engine | the same, plus what regeneration cannot fix: `engine 8.0.1 → 8.0.7 · re-run \`execute\` on your chapters` |
+  | a newer version | **refused.** A silent downgrade of pages you did not name is the case you almost certainly did not mean |
+
+  Outputs are never cleared on an engine bump. We would know the answers came from a different
+  engine, not that they are wrong, and erasing asserts more than we know — the complication of
+  version management belongs in what is recorded and reported, not in what is destroyed.
+
+- **A page carries the chapter it was built from.** `prolog-notebook-site/lists/lists.prolog.md`
+  sits beside the page it produced, so a site can rebuild itself with no source tree, no
+  repository and no manifest — and a reader can have the markdown.
+
+- **A site, with an index.** `build` writes every chapter into one `prolog-notebook-site`, and
+  regenerates `index.html` from the directory each time — each entry titled by that chapter's own
+  H1, alphabetical, because a notebook never states its own position and an index is the site's
+  opinion rather than the notebook's.
+
+- **`--here`**, for writing `prolog-notebook-site` beside the notebook instead of at the project
+  root.
+
+### Changed
+
+- **`build` writes to one site at the project root, not a folder beside each notebook.** It used
+  to default to `<file>-site`, so `notebooks/lists.prolog.md` became `notebooks/lists-site/`:
+  twenty chapters gave you twenty orphan sites, each with its own copy of the engine, and nowhere
+  for a table of contents to live because there was no "the site" for one to be a table of
+  contents of.
+
+  The destination is now found by walking up from the notebook and taking the first hit — an
+  existing `prolog-notebook-site`, then a `.git`, then the working directory. The first clue is
+  the one that matters: a second chapter, built from a different folder, joins the first's site
+  without being told to.
+
+  **The runtime, the engine and the stylesheet are the site's, not the page's.** They are written
+  once at the root and every page reaches them with `../`. Two chapters used to cost 12.6 MB; they
+  now cost 6.3.
+
+  And every build says where it went — `3 files → ../prolog-notebook-site/lists/ (12 shared with
+  the site)` — plus, on the build that creates it, one line noting you may want the directory in
+  `.gitignore`. Writing outside the directory you named is not something a tool should do quietly.
+
+
+- **The bare help screen names the commands and leaves everything else to them.** It printed
+  every option of every command, which made the first screen a new reader meets the longest one in
+  the tool and left the per-command help earning nothing. What remains is the name, what it does,
+  the three flags that really do work anywhere, and where to ask for more:
+
+  ```
+    view       read it in a browser, cells and all
+    build      write a page you can host or send
+    execute    run every query, write the answers in
+    clear      take the answers back out
+    upgrade    fetch the latest version
+  ```
+
+  Not even the operand: every command takes a file, so naming it here said nothing about the
+  choice this screen exists to help with. The summary answers *which command*; the command's own
+  help answers *how to call it*.
+
+- **Every command's help is laid out the same way**, because the usage line is now derived rather
+  than written out five times:
+
+  ```
+    prolog-notebook clear [<options>] <file(s)>     take the answers back out
+      <file(s)>       space separated list of Prolog Notebook files (.md)
+      --stdout        print the result instead of writing the file
+      --quiet         report only failures
+  ```
+
+  What the command takes is named on a line beside the switches — they are the same kind of fact,
+  and a reader who has to learn two shapes to read one screen is paying for our tidiness.
+  Options come before operands, as POSIX has it and as every tool a reader has already met prints
+  it, and they are bracketed because they may be left out where the file may not. `[<options>]`
+  appears only on a command that has any. A command taking several files says `<file(s)>` rather
+  than the conventional `<file>...` — the ellipsis is punctuation you have to already know, and
+  nobody types either form, so the cost of being legible here is nothing.
+
+  The `--limit` footnote goes with them, to `execute --help` where the flag it explains lives.
+
+- **`-h, --help` now says which help it gave you.** The line read `this` — written when there
+  was only one screen it could have meant, and never revisited when commands learned to answer
+  about themselves. The summary now offers `prolog-notebook build --help`; a command's own help
+  still says `this`, where it is once again true.
+
 ## [0.6.5] — 2026-08-31
 
 Both from one field report on a real chapter.

package/README.md

@@ -68,12 +68,25 @@ four splits arrive one at a time. Nothing is installed but the command.
 To send it to somebody, or host it:
 
 ```sh
-prolog-notebook build splitting.prolog.md --out site/
+prolog-notebook build splitting.prolog.md
+# 2 files → prolog-notebook-site/splitting/ (11 shared with the site)
+# prolog-notebook-site/index.html lists 1 notebook
 ```
 
-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.
+A plain directory: prerendered HTML with the saved answers in it, the runtime and the 6.2 MB
+engine shared at the root, and an index listing every chapter you have built. The engine is
+fetched only when a reader presses Run. No bundler, no build step of your own, nothing to
+configure.
+
+Build a second chapter from anywhere in the project and it joins the same site — `build` walks
+up for an existing `prolog-notebook-site`, then for a `.git`, so chapters that live in
+different folders still publish as one thing. `--here` puts the site beside the notebook
+instead; `--out <dir>` puts it wherever you say.
+
+A site has exactly one runtime and one engine, so the second post costs its own page rather than
+another 6.2 MB. When you upgrade the tool, the next build brings the whole site with it and says
+so — `runtime 0.6.0 → 0.7.0 · 2 pages regenerated` — because each page keeps the chapter it was
+built from.
 
 ### Or from a checkout
 
@@ -139,7 +152,8 @@ Each option belongs to a command, and typing one under the wrong command tells y
 | `--limit <n>` | `execute` | solutions to take from one query before stopping. Default 100. |
 | `--stdout` | `execute`, `clear` | print the result instead of writing the file |
 | `--quiet` | `execute`, `clear` | report only failures |
-| `--out <dir>` | `build` | where it writes. Default `<file>-site` |
+| `--out <dir>` | `build` | where the site is. Default: the nearest `prolog-notebook-site`, else one at the project root |
+| `--here` | `build` | write `prolog-notebook-site` beside the notebook instead |
 | `--port <n>` | `view` | what it listens on. Default 8777, and it takes another if that one is busy |
 | `--no-open` | `view` | print the URL instead of opening a browser |
 

package/bin/prolog-notebook.mjs

@@ -4,7 +4,7 @@
 // Code "run all" and a future --check get the same behaviour without going
 // through a shell (869ectt38, 869ectt3e).
 import { createRequire } from 'node:module';
-import { copyFileSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { copyFileSync, existsSync, 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';
@@ -14,7 +14,10 @@ import { updateNotice } from '../src/update.js';
 import { confirm, describeInstall, globalRoot, install, relaunch, upgradePlan } from '../src/upgrade.js';
 import { clearedSource, exportSource } from '../src/export.js';
 import { runNotebook, DEFAULT_LIMIT } from '../src/run.js';
-import { livePages } from '../src/build.js';
+import { buildFiles, livePages } from '../src/build.js';
+import {
+  SITE, findSite, indexHtml, isShared, pageName, pagesIn, reconcile, shownAs, sourceOf,
+} from '../src/site.js';
 import { openInBrowser, serve } from '../src/serve.js';
 
 // The engine is imported WHERE IT IS USED, never at the top. src/node.js pulls in
@@ -37,6 +40,23 @@ for (const stream of [process.stdout, process.stderr]) {
 // src/version.js, where a page can import it too.
 const require = createRequire(import.meta.url);
 
+/**
+ * WHAT A COMMAND TAKES BESIDE ITS OPTIONS, named and explained once.
+ *
+ * `.prolog.md` is a convention and nothing enforces it — any markdown file runs —
+ * so the operand is `<file>` everywhere and the line below the usage says what
+ * kind of file to hand it.
+ *
+ * SEVERAL FILES ARE `<file(s)>`, NOT THE POSIX `<file>...`, and the departure is
+ * deliberate. The ellipsis is the convention — Base Specifications 12.1, and what
+ * cc, cp, grep and git print — but it is punctuation you have to already know, and
+ * the Captain read it as saying less than it does. `(s)` is legible to someone who
+ * has never read a man page, and the row below spells it out in words anyway.
+ * Nobody types either form, so the cost of being unconventional here is zero.
+ */
+const FILE = ['<file>', 'Prolog Notebook file (.md)'];
+const FILES = ['<file(s)>', 'space separated list of Prolog Notebook files (.md)'];
+
 /**
  * THE COMMANDS, AND WHAT EACH ONE TAKES — one table, three readers (869erqra0).
  *
@@ -49,7 +69,7 @@ const require = createRequire(import.meta.url);
  */
 const COMMANDS = {
   view: {
-    usage: 'prolog-notebook view <file.prolog.md>',
+    takes: [FILE],
     blurb: 'read it in a browser, cells and all',
     options: [
       ['--port <n>', 'what it listens on (default 8777)'],
@@ -57,12 +77,15 @@ const COMMANDS = {
     ],
   },
   build: {
-    usage: 'prolog-notebook build <file.prolog.md>',
+    takes: [FILE],
     blurb: 'write a page you can host or send',
-    options: [['--out <dir>', 'where it writes (default: <file>-site)']],
+    options: [
+      ['--out <dir>', `where the site is (default: the nearest ${SITE})`],
+      ['--here', `write ${SITE} beside the notebook instead`],
+    ],
   },
   execute: {
-    usage: 'prolog-notebook execute <file.prolog.md>...',
+    takes: [FILES],
     blurb: 'run every query, write the answers in',
     options: [
       ['--limit <n>', `solutions to take from one query before stopping (default ${DEFAULT_LIMIT})`],
@@ -74,7 +97,7 @@ const COMMANDS = {
       + "format's way of saying the search was never exhausted. Nothing is invented.\n",
   },
   clear: {
-    usage: 'prolog-notebook clear <file.prolog.md>...',
+    takes: [FILES],
     blurb: 'take the answers back out',
     options: [
       ['--stdout', 'print the result instead of writing the file'],
@@ -82,7 +105,7 @@ const COMMANDS = {
     ],
   },
   upgrade: {
-    usage: 'prolog-notebook upgrade',
+    takes: [],
     blurb: 'fetch the latest version',
     options: [],
   },
@@ -94,26 +117,85 @@ const ALIASES = { exec: 'execute', run: 'execute' };
 /** The command this argument names, aliases resolved, or null. */
 const commandNamed = (arg) => (COMMANDS[arg] ? arg : ALIASES[arg] ?? null);
 
-const ANYWHERE = `Anywhere
+/**
+ * What works anywhere, and one line saying what --help has just done.
+ *
+ * The flag is contextual and that line was not: `-h, --help  this` was written
+ * before a command could be asked about itself and nobody revisited it, so the
+ * summary sat there promising the summary (869ery5hj). Each screen says which
+ * of the two it is.
+ */
+const anywhere = (help) => `Anywhere
   --check-update  ask npm whether a newer one exists, and say so either way
   --version       version, engine and copyright
-  -h, --help      this
+  -h, --help      ${help}
 `;
 
-/** One command, laid out exactly as it is laid out in the full help. */
+/**
+ * One command, one line — the summary's unit.
+ *
+ * Everything but the name and the blurb belongs to the command's own help, where
+ * the line is the one you would actually type rather than an entry in a list.
+ * This screen answers WHICH COMMAND; that one answers HOW TO CALL IT.
+ */
+/**
+ * How the command is called: options before operands, as POSIX has it and as
+ * every tool a reader has already met prints it.
+ *
+ * `[<options>]` IS BRACKETED AND `<file(s)>` IS NOT, which is the same convention
+ * saying the two are not alike: brackets mean you may leave it out, and every
+ * command here works with no options and none works with no file.
+ *
+ * The rows below the line stay operand-first, because that row explains the
+ * placeholder in the line above and is no use to anyone underneath five switches.
+ */
+const called = (name) => {
+  const { takes, options } = COMMANDS[name];
+  return [name, options.length ? '[<options>]' : '', ...takes.map(([operand]) => operand)]
+    .filter(Boolean)
+    .join(' ');
+};
+
+function commandLine(name) {
+  // THE NAME AND WHAT IT DOES, AND NOTHING ELSE. A reader on this screen is
+  // choosing a command, and every one of them takes a file — so the operand told
+  // them nothing about the choice while making five lines wider than the answer
+  // they came for.
+  return `  ${name.padEnd(11)}${COMMANDS[name].blurb}`;
+}
+
+/**
+ * One command, everything it takes, and nothing another command takes.
+ *
+ * Operands and options are laid out the same way because they are the same kind
+ * of fact — what may follow the command — and a reader who has to learn two
+ * shapes to read one screen is being charged for our tidiness.
+ */
 function commandHelp(name) {
-  const { usage, blurb, options } = COMMANDS[name];
-  return [`  ${usage.padEnd(44)}${blurb}`]
-    .concat(options.map(([flag, what]) => `    ${flag.padEnd(16)}${what}`))
+  const { takes, blurb, options } = COMMANDS[name];
+  return [`  prolog-notebook ${called(name).padEnd(32)}${blurb}`]
+    .concat([...takes, ...options].map(([what, why]) => `    ${what.padEnd(16)}${why}`))
     .join('\n');
 }
 
+/**
+ * THE SUMMARY NAMES THE COMMANDS AND NOTHING ELSE (869ery5hj).
+ *
+ * The Captain, on running the tool bare: "this is not great, why do we have
+ * command level help then." It printed every option of every command, so the tier
+ * below it earned nothing and the first screen a new reader met was the longest
+ * one in the tool. What is left is the list, the three flags that do work
+ * anywhere, and where to ask for more.
+ *
+ * The execute note goes with them. It explains --limit, and the comment on it in
+ * COMMANDS says it travels wherever --limit goes and nowhere else — a rule this
+ * screen was breaking.
+ */
 const USAGE = `prolog-notebook — Jupyter-style notebooks for Prolog
 
-${Object.keys(COMMANDS).map(commandHelp).join('\n\n')}
+${Object.keys(COMMANDS).map(commandLine).join('\n')}
 
-${ANYWHERE}
-${COMMANDS.execute.note}`;
+${anywhere("this, or one command's: prolog-notebook build --help")}`;
 
 /**
  * JUST THE COMMAND ASKED ABOUT (869erqra0).
@@ -127,7 +209,7 @@ ${COMMANDS.execute.note}`;
  */
 function helpFor(name) {
   const { note } = COMMANDS[name];
-  return `${commandHelp(name)}\n\n${ANYWHERE}${note ? `\n${note}` : ''}`;
+  return `${commandHelp(name)}\n\n${anywhere('this')}${note ? `\n${note}` : ''}`;
 }
 
 /**
@@ -490,6 +572,7 @@ async function page(command, args, asked = false) {
       return 2;
     }
     if (arg === '--out') options.out = args.shift();
+    else if (arg === '--here') options.here = true;
     else if (arg === '--port') {
       options.port = Number(args.shift());
       if (!Number.isInteger(options.port) || options.port < 0 || options.port > 65535) {
@@ -522,6 +605,9 @@ async function page(command, args, asked = false) {
   // when the server started.
   const pages = livePages(() => readFileSync(file, 'utf8'), {
     filename: basename(file),
+    // A built page is one page of a site and reaches the shared runtime with
+    // `../`; `view` serves a single page at the root, where it is `./`.
+    prefix: command === 'build' ? '../' : './',
     onError: (e) => process.stderr.write(`${file}: ${e.message}\n`),
   });
   let built;
@@ -533,20 +619,112 @@ async function page(command, args, asked = false) {
   }
 
   if (command === 'build') {
-    const out = options.out ?? `${file.replace(/\.prolog\.md$/, '')}-site`;
+    // THREE WAYS TO SAY WHERE, and only the first is a decision the author has to
+    // make twice: --out is the explicit one, --here is beside the notebook, and
+    // the default is the site this project already has (869ery5e8).
+    const site = options.out ? resolve(options.out)
+      : options.here ? join(dirname(resolve(file)), SITE)
+        : findSite(file);
+    const existed = existsSync(site);
+    const page = pageName(file);
+
+    // WHAT WROTE THIS SITE, AND WHAT IS WRITING NOW (869erqwkp). A site has
+    // exactly one runtime, so this decides whether the shared files are already
+    // the right ones, need replacing, or are newer than us.
+    const state = reconcile(site);
+    if (state.verdict === 'older') {
+      process.stderr.write(`${shownAs(site)} was built by prolog-notebook `
+        + `${state.have.runtime ?? '?'} with engine ${state.have.engine ?? '?'};`
+        + ` you are running ${state.ours.runtime} with ${state.ours.engine}.\n`
+        // Overwriting would downgrade every page in the site, none of which the
+        // author named. Refusing is the only move that breaks nothing.
+        + 'Run `prolog-notebook upgrade`, or build somewhere else with --out.\n');
+      return 1;
+    }
+    // The ordinary loop writes 52 KB: the page, and nothing else.
+    const writeShared = state.verdict !== 'same';
+
+    let own = 0;
+    let shared = 0;
     for (const [name, entry] of built) {
-      const target = join(out, name);
+      // The runtime, the engine and the stylesheet are the site's; the page is
+      // the page's. One copy each, however many chapters.
+      if (isShared(name) && !writeShared) continue;
+      const target = isShared(name) ? join(site, name) : join(site, page, name);
+      if (isShared(name)) shared += 1; else own += 1;
       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`);
+
+    // EVERY OTHER PAGE COMES WITH US. A page generated by an older tool imports
+    // symbols from a lib/ that has just moved under it, so leaving it alone is
+    // not the cautious option — it is the one that breaks it. Each page holds the
+    // chapter it was built from, so the site can rebuild itself.
+    const regenerated = [];
+    const stranded = [];
+    if (state.verdict === 'newer') {
+      for (const other of pagesIn(site)) {
+        if (other.name === page) continue;
+        const chapter = sourceOf(site, other.name);
+        if (!chapter) { stranded.push(other.name); continue; }
+        const files = buildFiles(parse(chapter.source), chapter.source, {
+          filename: chapter.filename, prefix: '../',
+        });
+        for (const [name, entry] of files) {
+          if (isShared(name)) continue;
+          const target = join(site, other.name, name);
+          mkdirSync(dirname(target), { recursive: true });
+          if (entry.text !== undefined) writeFileSync(target, entry.text);
+          else copyFileSync(entry.copy, target);
+        }
+        regenerated.push(other.name);
+      }
+    }
+
+    // REGENERATED FROM THE DIRECTORY, EVERY TIME. The site is the only thing that
+    // knows what the site contains — builds happen one chapter at a time, from
+    // different folders, days apart (869erptbr).
+    const listed = pagesIn(site);
+    writeFileSync(join(site, 'index.html'), indexHtml(listed));
+
+    // SAY WHERE IT WENT. This is the one command that writes outside the
+    // directory it was pointed at, and doing that in silence is spooky.
+    if (!existed) {
+      process.stderr.write(`created ${shownAs(site)}/ — you may want it in .gitignore\n`);
+    }
+    // COUNTED APART, because they answer different questions: how big is this
+    // chapter, and what does the site cost. "13 files" of a two-file page was
+    // true of the write and false about the page.
+    process.stderr.write(`${own} files → ${shownAs(join(site, page))}/`
+      + (writeShared ? ` (${shared} shared with the site)\n` : ' (runtime and engine already'
+        + ' there)\n'));
+
+    // SAID OUT LOUD, because a build aimed at one file has just rewritten others.
+    // One line naming what moved and how many pages came with it, the way a
+    // lockfile update reads.
+    if (state.verdict === 'newer' && state.runtimeMoved) {
+      process.stderr.write(`runtime ${state.have.runtime ?? 'unknown'} → ${state.ours.runtime}`
+        + ` · ${regenerated.length} page${regenerated.length === 1 ? '' : 's'} regenerated\n`);
+    }
+    if (state.verdict === 'newer' && state.engineMoved) {
+      // What regeneration cannot fix: the pages' code is current, their saved
+      // answers came out of the old engine and still live in the author's file.
+      process.stderr.write(`engine ${state.have.engine ?? 'unknown'} → ${state.ours.engine}`
+        + ' · re-run `execute` on your chapters\n');
+    }
+    if (stranded.length) {
+      process.stderr.write(`could not regenerate ${stranded.join(', ')} — no chapter beside `
+        + `${stranded.length === 1 ? 'it' : 'them'}. Build from the notebook again.\n`);
+    }
+    process.stderr.write(`${shownAs(join(site, 'index.html'))} lists `
+      + `${listed.length} notebook${listed.length === 1 ? '' : 's'}\n`);
     // SAID HERE BECAUSE THIS IS WHERE IT IS ACTED ON. The obvious next move is to
     // double-click index.html, and that is the one thing that cannot work:
     // browsers refuse ES modules over file:// and the engine cannot be fetched
     // there either (869erqq1u). The page says so too, but by then somebody is
     // already looking at a chapter whose buttons do nothing.
-    process.stderr.write(`Host ${out} over HTTP — opening ${join(out, 'index.html')} from disk`
+    process.stderr.write(`Host ${shownAs(site)} over HTTP — opening it from disk`
       + ' will not run.\n');
     return 0;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prolog-notebook",
-  "version": "0.6.5",
+  "version": "0.7.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": "60e27bc",
-  "built": "2026-08-30 23:44:28 UTC"
+  "commit": "7e40763",
+  "built": "2026-08-31 10:59:41 UTC"
 }

package/src/build.js

@@ -15,9 +15,22 @@
 // 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 { createRequire } from 'node:module';
 import { parse } from './format.js';
 import { renderNotebook } from './render.js';
 
+/**
+ * Which swipl-wasm the bundle beside us came from.
+ *
+ * READ FROM THE DEPENDENCY, never written down twice: a constant we maintain by
+ * hand is a constant that is wrong the first time somebody bumps the dependency
+ * and forgets. This is the only thing in this file that touches the disk to
+ * answer a question, and it is a question about the package rather than about a
+ * notebook.
+ */
+const require = createRequire(import.meta.url);
+export const ENGINE_VERSION = require('swipl-wasm/package.json').version;
+
 /** 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',
@@ -31,7 +44,7 @@ export const RUNTIME = [
  * every single load and this audience opens the console (869ernmxe). An SVG so it
  * scales to whatever size the tab wants.
  */
-const FAVICON = encodeURIComponent(
+export const FAVICON = encodeURIComponent(
   '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32">'
   + '<rect width="32" height="32" rx="7" fill="#faf7f0"/>'
   + '<text x="16" y="23" font-family="ui-monospace,Menlo,monospace" font-size="19"'
@@ -41,15 +54,32 @@ const FAVICON = encodeURIComponent(
 /** The one engine file: the bundle carries its own data. */
 export const ENGINE = 'swipl-bundle.js';
 
+/**
+ * WHICH ENGINE IS IN THIS DIRECTORY, written beside it (869erqwkp).
+ *
+ * The design for this said to read the versions back out of the site rather than
+ * write a manifest, and for the runtime that works — lib/version.js is already
+ * there and carries ours. THE BUNDLE CANNOT ANSWER FOR ITSELF: it is a megabyte
+ * of minified glue around base64 data with no version string in it, and comparing
+ * bytes can only say DIFFERENT, never NEWER. So the one fact we cannot recover is
+ * recorded, in the smallest place that makes sense: a module beside the artefact
+ * it describes, not a manifest at the root describing everything.
+ */
+export const ENGINE_VERSION_FILE = 'swipl/version.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]
+ * @param {{filename?: string, src?: URL, engine?: URL, prefix?: string}} [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.
+ *   `prefix` is how the page reaches the shared files: `./` when it is alone in a
+ *   directory, `../` when it is one page of a site whose runtime and engine live
+ *   at the root (869ery5e8). It is the ONLY thing that differs between the two,
+ *   which is why the map's keys do not change.
  * @returns {Map<string, {text: string}|{copy: URL}>}
  */
 export function buildFiles(notebook, source, options = {}) {
@@ -57,14 +87,29 @@ export function buildFiles(notebook, source, options = {}) {
     filename = 'notebook.prolog.md',
     src = new URL('./', import.meta.url),
     engine = new URL('../node_modules/swipl-wasm/dist/swipl/', import.meta.url),
+    prefix = './',
+    engineVersion = ENGINE_VERSION,
   } = options;
 
   const files = new Map();
-  files.set('index.html', { text: page(notebook) });
-  files.set('app.js', { text: app(source, filename) });
+  files.set('index.html', { text: page(notebook, prefix) });
+  files.set('app.js', { text: app(source, filename, prefix) });
   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) });
+  files.set(ENGINE_VERSION_FILE, {
+    text: '// Generated by prolog-notebook build. Which engine is in this directory.\n'
+      + `export const SWIPL_WASM = ${JSON.stringify(engineVersion)};\n`,
+  });
+  // THE CHAPTER ITSELF, beside the page it produced.
+  //
+  // It is already inside app.js, because the "as published" download hands back
+  // the author's own bytes. As a real file it is also what a rebuild reads to
+  // regenerate this page against a newer runtime (869erqwkp) — regexing a source
+  // back out of generated JavaScript would work and would be a thing nobody
+  // should have to look at. And the markdown sitting on the site next to the page
+  // is the whole argument for the format.
+  files.set(filename, { text: source });
   return files;
 }
 
@@ -164,7 +209,7 @@ function escapeHtml(text) {
   return String(text).replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }[c]));
 }
 
-function page(notebook) {
+function page(notebook, prefix) {
   return `<!doctype html>
 <html lang="en">
 <head>
@@ -172,7 +217,7 @@ function page(notebook) {
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>${escapeHtml(titleOf(notebook))}</title>
 <link rel="icon" href="data:image/svg+xml,${FAVICON}">
-<link rel="stylesheet" href="notebook.css">
+<link rel="stylesheet" href="${prefix}notebook.css">
 </head>
 <body>
 <main>
@@ -210,12 +255,12 @@ ${renderNotebook(notebook)}
  * 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) {
+function app(source, filename, prefix) {
   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';
+import { editsOf, mount, offerDownload } from '${prefix}lib/notebook.js';
+import { parse } from '${prefix}lib/format.js';
+import { exportSource } from '${prefix}lib/export.js';
 
 const SOURCE = ${JSON.stringify(source)};
 const FILENAME = ${JSON.stringify(filename)};
@@ -224,7 +269,7 @@ 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,
+  swiplUrl: new URL('${prefix}swipl/${ENGINE}', import.meta.url).href,
 });
 
 const notebook = parse(SOURCE);

package/src/site.js

@@ -0,0 +1,259 @@
+// One site, however many notebooks, and it finds itself (869ery5e8).
+//
+// `build` used to write beside the notebook it was given: lists.prolog.md became
+// notebooks/lists-site/. Twenty chapters gave you twenty orphan sites, each with
+// its own copy of the runtime, and nowhere for a table of contents to live —
+// there was no "the site" for one to be a table of contents OF.
+//
+// So the destination is a property of the PROJECT rather than of the file, and
+// the second chapter lands beside the first without being told to.
+//
+// NOTHING HERE WRITES ANYTHING, for the same reason build.js does not: this
+// decides names and produces text, and the command does the I/O.
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { basename, dirname, join, relative, resolve } from 'node:path';
+import { ENGINE_VERSION, ENGINE_VERSION_FILE, FAVICON } from './build.js';
+import { VERSION } from './version.js';
+
+/** The one name, wherever it lands. */
+export const SITE = 'prolog-notebook-site';
+
+/**
+ * WHERE THE SITE IS, from the notebook being built.
+ *
+ * Walk up and take the first hit, in this order:
+ *
+ *   1. an existing prolog-notebook-site/ — somebody has already decided
+ *   2. a .git/ — the project's own idea of where it begins
+ *   3. the working directory — nothing to go on, so do not go looking
+ *
+ * CLUE 1 IS THE ONE THAT MATTERS and it is deliberately first: it means chapter
+ * two, built from a different subfolder, joins chapter one's site rather than
+ * starting a second one next to it. That is what makes an index possible at all,
+ * and it is the precondition for a shared engine (869erqwkp).
+ *
+ * Clue 2 answers the first build, when clue 1 cannot exist yet. Both are looked
+ * for on every step of the walk rather than one pass each, so a notebook inside a
+ * submodule finds its own project rather than the one containing it.
+ *
+ * @param {string} from a notebook's path
+ * @param {string} [stop] where to give up — the working directory
+ * @returns {string} the site directory, which may not exist yet
+ */
+export function findSite(from, stop = process.cwd()) {
+  let dir = resolve(dirname(from));
+  const root = resolve(dir).split(/[\\/]/)[0] || '/';
+  for (;;) {
+    if (existsSync(join(dir, SITE))) return join(dir, SITE);
+    if (existsSync(join(dir, '.git'))) return join(dir, SITE);
+    const up = dirname(dir);
+    if (up === dir || dir === root) return join(resolve(stop), SITE);
+    dir = up;
+  }
+}
+
+/**
+ * The notebook's own directory inside the site.
+ *
+ * The name a reader sees in the URL, so it comes from the file rather than from
+ * the chapter's title: an author who renames their H1 has not asked for every
+ * link to their page to break.
+ */
+export function pageName(file) {
+  return basename(file).replace(/\.prolog\.md$/, '').replace(/\.md$/, '') || 'notebook';
+}
+
+/**
+ * Files that belong to the SITE rather than to one page.
+ *
+ * The runtime, the engine and the stylesheet are identical for every chapter, so
+ * they are written once at the site root and every page reaches them with `../`.
+ * A six-chapter site was six copies of a 6.2 MB engine.
+ */
+export function isShared(name) {
+  return name.startsWith('lib/') || name.startsWith('swipl/') || name === 'notebook.css';
+}
+
+/**
+ * WHAT WROTE THIS SITE — the two keys a rebuild has to compare (869erqwkp).
+ *
+ *   prolog-notebook   decides lib/*.js, notebook.css and how a page is generated
+ *   swipl-wasm        decides swipl-bundle.js, the bytes we copy
+ *
+ * SWI-Prolog's own version is a property of swipl-wasm rather than a third axis,
+ * and it is not recorded: getting it means booting the engine, which is a second
+ * of every build spent on a label. It belongs on the output block that the answers
+ * came from, which is a different ticket and the place a reader would look.
+ *
+ * Both are read back out of the site rather than kept in a manifest at the root.
+ * A directory that has been half-deleted then reports what it actually has.
+ *
+ * @returns {{runtime: string|null, engine: string|null}} null where the site is silent
+ */
+export function siteVersions(dir) {
+  return {
+    runtime: constIn(join(dir, 'lib/version.js'), /VERSION = '([^']+)'/),
+    engine: constIn(join(dir, ENGINE_VERSION_FILE), /SWIPL_WASM = "([^"]+)"/),
+  };
+}
+
+function constIn(file, pattern) {
+  if (!existsSync(file)) return null;
+  const found = pattern.exec(readFileSync(file, 'utf8'));
+  return found ? found[1] : null;
+}
+
+/** -1, 0 or 1. Numeric where both sides are numeric, which ours and swipl-wasm's are. */
+export function compareVersions(a, b) {
+  const parts = (v) => String(v).split('.').map((n) => Number.parseInt(n, 10) || 0);
+  const [x, y] = [parts(a), parts(b)];
+  for (let i = 0; i < Math.max(x.length, y.length); i += 1) {
+    if ((x[i] ?? 0) !== (y[i] ?? 0)) return (x[i] ?? 0) < (y[i] ?? 0) ? -1 : 1;
+  }
+  return 0;
+}
+
+/**
+ * A SITE HAS EXACTLY ONE RUNTIME: whichever tool last touched it (869erqwkp).
+ *
+ * The contract between a page's app.js and lib/ is NOT stable — `offerDownload`
+ * gained arguments in #28 and `editsOf` moved modules in #40 — so a site holding
+ * two generations of page has no safe resting state. Overwrite lib/ and the older
+ * page imports a symbol that has moved; leave it and the page just built is the
+ * broken one. There is no third option in which everything works, which is why
+ * this reconciles rather than warns.
+ *
+ * BUILD IS SCOPED IN THE PAGES IT ADDS, NOT IN THE CONSISTENCY IT GUARANTEES.
+ * Ordinarily that is one page and nothing else moves. The moment a key differs the
+ * scope widens to the whole site, because that is the only state in which nothing
+ * is broken.
+ *
+ * @returns {{verdict: 'fresh'|'same'|'newer'|'older', have: object, ours: object}}
+ *   fresh  nothing there yet — write everything
+ *   same   write the page; the runtime and engine are already the right ones
+ *   newer  overwrite the shared files and regenerate every page
+ *   older  refuse: a silent downgrade of pages the author did not name
+ */
+export function reconcile(dir, ours = { runtime: VERSION, engine: ENGINE_VERSION }) {
+  const have = siteVersions(dir);
+  if (!have.runtime && !have.engine) return { verdict: 'fresh', have, ours };
+  const runtime = compareVersions(ours.runtime, have.runtime ?? '0');
+  const engine = compareVersions(ours.engine, have.engine ?? '0');
+  if (runtime < 0 || engine < 0) return { verdict: 'older', have, ours };
+  if (runtime === 0 && engine === 0) return { verdict: 'same', have, ours };
+  return {
+    verdict: 'newer', have, ours, runtimeMoved: runtime > 0, engineMoved: engine > 0,
+  };
+}
+
+/**
+ * A built page's own chapter, for regenerating it against a newer runtime.
+ *
+ * The page directory holds the .prolog.md it was built from, so a site can be
+ * rebuilt with no source tree, no repository and no manifest — it describes
+ * itself. A page with no source file was not written by a version that emitted
+ * one, and says so by returning null rather than by being silently skipped.
+ *
+ * @returns {{filename: string, source: string}|null}
+ */
+export function sourceOf(dir, page) {
+  const where = join(dir, page);
+  if (!existsSync(where)) return null;
+  const found = readdirSync(where).find((f) => f.endsWith('.md'));
+  return found ? { filename: found, source: readFileSync(join(where, found), 'utf8') } : null;
+}
+
+/**
+ * What the site already contains, newest build included.
+ *
+ * READ BACK OFF DISK, NOT REMEMBERED. `build` is called once per chapter, often
+ * from different directories and days apart, so the only thing that knows the
+ * whole site is the site. Each page's own <title> is the answer — it is written
+ * from the chapter's H1 at build time, so there is no manifest to keep in step
+ * and no second place for a title to be wrong.
+ *
+ * A directory with no index.html is not a page and is left alone: the site is
+ * somebody's directory and may hold things we did not put there.
+ *
+ * @returns {{name: string, title: string}[]} alphabetical by directory name
+ */
+export function pagesIn(dir) {
+  if (!existsSync(dir)) return [];
+  const pages = [];
+  for (const name of readdirSync(dir).sort()) {
+    const index = join(dir, name, 'index.html');
+    if (name === 'lib' || name === 'swipl') continue;
+    if (!existsSync(index) || !statSync(join(dir, name)).isDirectory()) continue;
+    const html = readFileSync(index, 'utf8');
+    const title = /<title>([^<]*)<\/title>/.exec(html);
+    pages.push({ name, title: title ? unescapeHtml(title[1]) : name });
+  }
+  return pages;
+}
+
+/**
+ * The site's front page, rewritten on every build (869erptbr).
+ *
+ * ORDER IS THE SITE'S BUSINESS, NOT THE NOTEBOOK'S. A chapter never states its
+ * own position — that is the rule the whole format is built on (binding.md) — so
+ * an index is an opinion held by the directory, and alphabetical is the honest
+ * placeholder until there is somewhere for a real order to live.
+ *
+ * It borrows the chapter stylesheet rather than carrying its own, so it inherits
+ * the palette, the dark mode and the typography, and cannot drift from the pages
+ * it lists.
+ */
+export function indexHtml(pages, { title = 'Prolog notebooks' } = {}) {
+  const items = pages.length
+    ? pages.map((p) => `<li><a href="${encodeURIComponent(p.name)}/">${escapeHtml(p.title)}</a></li>`)
+      .join('\n')
+    : '<li class="empty">No notebooks here yet.</li>';
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(title)}</title>
+<link rel="icon" href="data:image/svg+xml,${FAVICON}">
+<link rel="stylesheet" href="notebook.css">
+<style>
+  .contents { list-style: none; padding: 0; margin: 2.5rem 0 0; }
+  .contents li { border-top: 1px solid var(--rule); }
+  .contents li:last-child { border-bottom: 1px solid var(--rule); }
+  .contents a { display: block; padding: 1rem .2rem; text-decoration: none; color: inherit; }
+  .contents a:hover { color: var(--accent); }
+  .contents .empty { padding: 1rem .2rem; opacity: .6; font-style: italic; }
+</style>
+</head>
+<body>
+<main>
+<h1>${escapeHtml(title)}</h1>
+<ul class="contents">
+${items}
+</ul>
+</main>
+</body>
+</html>
+`;
+}
+
+/**
+ * Where the build went, as the reader would type it.
+ *
+ * The relative form wins whenever it is shorter, INCLUDING when it climbs — the
+ * whole point of the default destination is that the site is above the notebook,
+ * so `../prolog-notebook-site/lists/` is the normal case and the absolute path is
+ * the unreadable one.
+ */
+export function shownAs(target) {
+  const here = relative(process.cwd(), target);
+  return here && here.length < target.length ? here : target;
+}
+
+function escapeHtml(text) {
+  return String(text).replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }[c]));
+}
+
+function unescapeHtml(text) {
+  return String(text).replace(/&(amp|lt|gt|quot);/g, (_, name) => ({ amp: '&', lt: '<', gt: '>', quot: '"' }[name]));
+}

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.6.5';
+export const VERSION = '0.7.0';
 
 /** The two facts a licence notice is actually made of. */
 export const YEAR = '2026';