prolog-notebook 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,91 @@
 # Changelog
 
+## [0.6.0] — 2026-08-30
+
+Taking the answers back out — at the terminal, and on the page. Plus the first documentation
+written for somebody who is not us.
+
+### Added
+
+- **`prolog-notebook clear <file>`** empties every output block and leaves everything else
+  alone: prose, program cells, goals and attributes are the author's. A chapter with no answers
+  is a valid chapter — one that has not been executed yet — so `clear` then `execute` returns
+  the original bytes exactly. For a workbook edition, for a diff you can read, or for starting
+  again deliberately rather than trusting an overwrite.
+
+- **The page can clear its own answers, and put them back.** A new row in the panel:
+
+      4 outputs in this chapter          [Clear all outputs]
+      4 outputs cleared                  [Restore outputs]
+
+  It sits next to the hide row on purpose, because the two blank the same box for opposite
+  reasons. Hiding acts on the **screen** — the answers are still the chapter's and still go
+  into a download. Clearing acts on the **notebook**: a download taken after it carries no
+  output block at all, through the same erasure the CLI uses, so a chapter emptied on the page
+  and one emptied at the terminal are the same bytes.
+
+  That makes clearing a third way away from the published chapter, beside running and editing,
+  which is why nothing new was needed to get back. **One origin, one way back**: reset already
+  meant *as published* and now has one more thing it can undo — per cell, or all at once with
+  restore. An auto cell does not refill itself once cleared, and restore is the exact inverse
+  of clear, leaving an edited goal alone.
+
+- **`docs/authoring.md` — the author's handbook.** The loop, a whole chapter from scratch,
+  what `hold` and `rerun` do to a reader, why you never hand-write an output block, staleness,
+  what a reader can do to your chapter, publishing, and nine things that otherwise cost an
+  afternoon. Every command line in it was run.
+
+### Changed
+
+- **`run` is now `execute`.** It executes a chapter and writes its answers into the file, which
+  `run` did not say — and *run* was already the name of the button a reader presses on one
+  cell. `run` and `exec` still work; nothing has been taken away.
+
+- **The README had not met the CLI.** Its banner still said the renderer was unwritten, Status
+  still counted 186 tests, and *Try it* pointed a fresh global install at a chapter that ships
+  in the repo and not in the package — so the first command in the front door failed for
+  everybody who had just installed it. It now writes a three-line chapter, executes it and
+  views it.
+
+- `docs/modes.md` §3 gains *Hiding is not clearing*.
+
+## [0.5.1] — 2026-08-30
+
+Everything here came from one field report: a chapter written with the tool rather than a test
+written against it.
+
+### Fixed
+
+- **`view` bound quietly behind a squatter on the same port.** A stale
+  `python3 -m http.server --bind ::` holds `*:8777` on IPv6; binding `127.0.0.1:8777` on IPv4
+  does not collide with it, so `EADDRINUSE` never fired and the auto-bump never ran. `localhost`
+  then resolves to `::1` first and the reader gets somebody else's directory listing where a
+  chapter should be. The port is now connect-tested on **both stacks** before binding, because
+  *can I bind* and *will the reader reach me* are different questions.
+
+- **`view` printed its URL on stderr**, where a wrapper never saw it — which is how somebody
+  came to type `localhost` by hand. It is the command's output and is on stdout now; `view`
+  writes no notebook and no data there, so nothing can be corrupted by it.
+
+- **`view` and `build` never looked for an update.** The offer went into the `run` path first
+  and stayed there. Every command that does real work now goes through one door, always before
+  the work — the only point at which the answer can change the outcome.
+
+- **A prediction released the hold on blur, not on typing.** A reader who typed their prediction
+  and looked up saw nothing happen, and the link between *I wrote something* and *the answers
+  appeared* was broken by a pause with no cause. Debounced `input` at 1.2 s now, with `change`
+  kept so leaving the box is still immediate.
+
+- **The console was not clean, and this audience opens the console.** A `favicon.ico` 404 on
+  every load — now a `data:` URI carrying the notebook's own `?-` prompt — and an issues-panel
+  warning for every form field on the page, all of which were anonymous. Every field has an id:
+  `src-<cell>`, `goal-<cell>`, `predict-<n>`.
+
+- **A missing browser opener took the whole command down.** `spawn` reports that
+  asynchronously, so the `try/catch` around it caught nothing and an unhandled `'error'` event
+  killed `view` after the server had started. `start` on Windows is a shell builtin and was
+  never going to work spawned by name; it goes through `cmd` now.
+
 ## [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

package/README.md

@@ -2,9 +2,9 @@
 
 **Jupyter-style notebooks for Prolog. Runs in the browser, installs nothing.**
 
-> ⚠️ **v0.1.0 — early.** The execution core works and is tested. The renderer that turns a
-> notebook *file* into a page is not written yet; today you mark cells up in HTML by hand.
-> See [Status](#status).
+> **v0.5 — usable, and moving.** A chapter is a markdown file; the CLI runs it, serves it and
+> publishes it. Writing one is [the author's handbook](docs/authoring.md). See
+> [Status](#status) for what is not built yet.
 
 ## The idea
 
@@ -40,19 +40,35 @@ So a query cell gives you the first solution, and then you step.
 
 ## Try it
 
-```sh
+A whole chapter, from nothing, in four commands:
+
+````sh
 npm i -g prolog-notebook
-prolog-notebook view notebooks/ch04-cut.prolog.md
+
+cat > splitting.prolog.md <<'EOF'
+# Splitting a list
+
+`append/3` is usually introduced as the predicate that joins two lists. That is the
+least interesting thing it does — run it backwards and it takes a list apart, every
+way it can be split, one solution at a time.
+
+```prolog query
+append(Front, Back, [hello, there, world])
 ```
+EOF
+
+prolog-notebook execute splitting.prolog.md   # SWI fills the answers in
+prolog-notebook view splitting.prolog.md      # read it, cells live
+````
 
-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.
+`execute` runs the chapter and writes the solutions back into the markdown — you never
+hand-write an answer. `view` opens it in your browser: press Run, then `; next`, and watch the
+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 ch04-cut.prolog.md --out site/
+prolog-notebook build splitting.prolog.md --out site/
 ```
 
 A plain directory: prerendered HTML with the saved answers in it, the runtime beside it, and
@@ -98,7 +114,7 @@ author's *guess* at what SWI prints, published as though it ran. So write the fi
 output blocks and let the engine fill them in:
 
 ```sh
-npx prolog-notebook run notebooks/ch04-cut.prolog.md
+prolog-notebook execute chapter.prolog.md
 ```
 
 It consults every program cell, runs every query below it, and writes the solution sequences
@@ -106,11 +122,24 @@ back into the file along with an `input-hash` for each — which is what makes t
 complete, and render as *current*, before the engine arrives. Running it again on an unchanged
 chapter changes nothing.
 
+And back out again, for a workbook edition or a diff you can read:
+
+```sh
+prolog-notebook clear chapter.prolog.md
+chapter.prolog.md: 4 answers removed
+```
+
+`clear` empties every output block and touches nothing else; `execute` fills them in again from
+the engine. A chapter with no answers is a valid chapter — one that has not been executed yet.
+
 | flag | |
 |---|---|
 | `--limit <n>` | solutions to take from one query before stopping. Default 100. |
 | `--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, and it takes another if that one is busy |
+| `--no-open` | `view` prints the URL instead of opening a browser |
 | `--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 |
 
@@ -135,7 +164,7 @@ doing the work — and if you say yes it upgrades, then runs your command on the
 One command, no re-run:
 
 ```
-$ prolog-notebook run ch04.prolog.md
+$ prolog-notebook execute 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
@@ -158,6 +187,20 @@ It has no defence against a non-terminating goal yet — the engine runs in this
 not a solution count. Fixing it properly means a worker thread, and it is the prerequisite for
 putting this in CI.
 
+## Write one
+
+**[The author's handbook](docs/authoring.md)** — the loop, a chapter from scratch, what `hold`
+and `rerun` do to a reader, why you never hand-write an answer, publishing, and the things that
+will otherwise cost you an afternoon.
+
+| | |
+|---|---|
+| [docs/authoring.md](docs/authoring.md) | writing and publishing a chapter |
+| [docs/format.md](docs/format.md) | the `.prolog.md` format, normatively |
+| [docs/modes.md](docs/modes.md) | Read, Explore, Own — what a reader may change, and what may never be confused with what |
+| [docs/binding.md](docs/binding.md) | chapters into books; why a notebook never states its own position |
+| [docs/platform-seams.md](docs/platform-seams.md) | what is environment-specific, and where |
+
 ## Use it
 
 Headless, in Node — this is how you test that every example in a document still works:
@@ -268,14 +311,16 @@ 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**: `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
+- **the CLI**: `execute` runs a chapter headlessly and writes its answers back, `clear` takes
+  them out again, `view` opens it in a browser, `build` writes a page you can host or send,
+  and it updates itself
+- **page controls**: hide the saved answers to work a chapter cold, clear them out and restore
+  them, and download your own copy — yours or the chapter as published
+- 253 passing tests
 
 Not built yet:
 
-- `--check` — run a chapter in CI and fail the build when its answers have drifted. Needs a
+- `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.
 - 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

package/bin/prolog-notebook.mjs

@@ -4,7 +4,6 @@
 // Code "run all" and a future --check get the same behaviour without going
 // through a shell (869ectt38, 869ectt3e).
 import { createRequire } from 'node:module';
-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';
@@ -13,10 +12,10 @@ 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 { clearedSource, 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';
+import { openInBrowser, 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
@@ -24,7 +23,7 @@ import { serve } from '../src/serve.js';
 // commands most likely to be typed at a broken install are --help and --version.
 const engine = () => import('../src/node.js');
 
-// `prolog-notebook run --stdout file | head` closes the pipe while we are still
+// `prolog-notebook execute --stdout file | head` closes the pipe while we are still
 // writing to it. That is the reader using the shell correctly, not an error, and
 // a command that answers it with an unhandled EPIPE and a stack trace is
 // complaining about being used properly.
@@ -40,10 +39,11 @@ 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
+  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 execute <file.prolog.md>... run every query, write the answers in
+  prolog-notebook clear <file.prolog.md>...   take the answers back out
+  prolog-notebook upgrade                     fetch the latest version
 
 Options
   --limit <n>     solutions to take from one query before stopping (default ${DEFAULT_LIMIT})
@@ -141,6 +141,38 @@ function canAsk() {
   return Boolean(process.stdin.isTTY && process.stderr.isTTY);
 }
 
+/**
+ * The offer, BEFORE the command does anything — which is the only place it can
+ * change the outcome. Afterwards the files are written, the server is up, and a
+ * newer version has nothing left to do.
+ *
+ * Every command that does real work goes through here: `run`, `view` and
+ * `build`. It went in the execute path first and stayed there, so `view` — the
+ * command somebody is most likely to leave running — was the one that never
+ * looked.
+ *
+ * It costs a network round trip once a day, not once a run: the rest of the day
+ * is a file read.
+ *
+ * @returns {Promise<number|null>} an exit code when the command has been handed
+ *   to a newer version, null to carry on here.
+ */
+async function upgradeFirst({ quiet = false, asked = false } = {}) {
+  if (!canAsk() || (quiet && !asked)) return null;
+  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?'))) return null;
+  if ((await upgrade(ahead.newer)) !== 0) {
+    process.stderr.write('Carrying on with the version you have.\n');
+    return null;
+  }
+  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);
+}
+
 async function offerUpgrade(newer) {
   if (!canAsk()) {
     // Nobody to ask, so say what to type instead. `prolog-notebook upgrade`
@@ -182,12 +214,17 @@ async function main(argv) {
 
   const command = args.shift();
   if (command === 'view' || command === 'build') return page(command, args);
+  if (command === 'clear') return clear(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') {
+  // `execute` and `exec` are aliases and stay undocumented: one name is the name.
+  // `run` because it is published in every release since 0.3.0 and breaking it
+  // silently would be rude; `exec` because seven characters is a lot to type in
+  // a loop (869erp0jd).
+  if (!['execute', 'exec', 'run'].includes(command)) {
     process.stderr.write(`unknown command "${command}"\n\n${USAGE}`);
     return 2;
   }
@@ -215,35 +252,14 @@ async function main(argv) {
   }
 
   if (!files.length) {
-    process.stderr.write('run needs at least one file\n');
+    process.stderr.write('execute needs at least one file\n');
     return 2;
   }
   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;
-  }
+  const jump = await upgradeFirst({ quiet: options.quiet, asked });
+  if (jump !== null) return jump;
+  checked = canAsk() && (!options.quiet || asked);
 
   // 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
@@ -272,7 +288,7 @@ async function main(argv) {
     status = Math.max(status, await runFile(file, session, options));
   }
 
-  // stderr, always: `run --stdout` is a notebook going down a pipe, and a version
+  // stderr, always: `execute --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 { message, newer } = await update;
   if (message) process.stderr.write(`${message}\n`);
@@ -282,6 +298,62 @@ async function main(argv) {
   return status;
 }
 
+/**
+ * Take the answers back out.
+ *
+ * The counterpart to `execute`, and it exists because the alternative was editing
+ * the file by hand: a workbook edition with the answers withheld, a diff without
+ * nineteen solution sequences in the way, or starting again deliberately rather
+ * than trusting an overwrite.
+ *
+ * No engine, no network and no update check: this is a text operation on a file
+ * the reader already has.
+ */
+async function clear(args) {
+  const options = { stdout: false, quiet: false };
+  const files = [];
+  for (const arg of args) {
+    if (arg === '--stdout') options.stdout = true;
+    else if (arg === '--quiet') options.quiet = true;
+    else if (arg.startsWith('-')) {
+      process.stderr.write(`unknown option "${arg}"\n`);
+      return 2;
+    } else files.push(arg);
+  }
+  if (!files.length) {
+    process.stderr.write('clear needs at least one file\n');
+    return 2;
+  }
+
+  let status = 0;
+  for (const file of files) {
+    let source;
+    let emptied;
+    try {
+      source = readFileSync(file, 'utf8');
+      emptied = clearedSource(parse(source));
+    } catch (e) {
+      process.stderr.write(`${file}: ${e.message}\n`);
+      status = 1;
+      continue;
+    }
+    if (options.stdout) {
+      process.stdout.write(emptied.text);
+      continue;
+    }
+    if (emptied.text === source) {
+      if (!options.quiet) process.stderr.write(`${basename(file)}: nothing to remove\n`);
+      continue;
+    }
+    writeFileSync(file, emptied.text);
+    if (!options.quiet) {
+      const n = emptied.cleared;
+      process.stderr.write(`${basename(file)}: ${n} answer${n === 1 ? '' : 's'} removed\n`);
+    }
+  }
+  return status;
+}
+
 /**
  * `build` and `view`, which are the same page put in two different places.
  *
@@ -312,6 +384,12 @@ async function page(command, args) {
     return 2;
   }
 
+  // The same offer the execute path makes, and for the same reason: a server about to
+  // start, or a directory about to be written, is work that a newer version
+  // should be doing.
+  const jump = await upgradeFirst();
+  if (jump !== null) return jump;
+
   const file = files[0];
   let built;
   try {
@@ -336,26 +414,20 @@ async function page(command, args) {
   }
 
   const server = await serve(built, { port: options.port });
-  process.stderr.write(`${basename(file)} at ${server.url}\n`);
+  // THE URL IS THIS COMMAND'S OUTPUT. `view` writes no notebook and no data to
+  // stdout, so there is nothing for it to corrupt — and a URL on stderr is a URL
+  // a wrapper does not see, which is how somebody came to type localhost by hand
+  // and land on another server entirely (869ernmvh).
+  process.stdout.write(`${server.url}\n`);
   if (server.port !== options.port) {
-    process.stderr.write(`(${options.port} was taken)\n`);
+    process.stderr.write(`${options.port} was already answering — using ${server.port} instead.\n`);
   }
-  process.stderr.write('Ctrl-C to stop.\n');
+  process.stderr.write(`${basename(file)} is at ${server.url} — 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.5.0",
+  "version": "0.6.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": "084182f",
-  "built": "2026-08-30 16:32:07 UTC"
+  "commit": "4e10d19",
+  "built": "2026-08-30 18:33:44 UTC"
 }

package/src/build.js

@@ -23,6 +23,20 @@ export const RUNTIME = [
   'clauses.js', 'export.js', 'format.js', 'version.js',
 ];
 
+/**
+ * The notebook's own prompt, `?-`, as a tab icon.
+ *
+ * A data: URI rather than a file, because the alternative is a favicon.ico 404 on
+ * every single load and this audience opens the console (869ernmxe). An SVG so it
+ * scales to whatever size the tab wants.
+ */
+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"'
+  + ' font-weight="600" fill="#8a3b1e" text-anchor="middle">?-</text></svg>',
+);
+
 /** The one engine file: the bundle carries its own data. */
 export const ENGINE = 'swipl-bundle.js';
 
@@ -80,6 +94,7 @@ function page(notebook) {
 <meta charset="utf-8">
 <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">
 </head>
 <body>

package/src/export.js

@@ -94,6 +94,29 @@ export function exportSource(notebook, edits) {
   return serialise(withEdits(notebook, edits));
 }
 
+/**
+ * The chapter with its answers taken back out.
+ *
+ * A query cell with no output block is valid — the result is a chapter that
+ * simply has not been executed yet, and `execute` will fill it in again. Nothing
+ * else moves: prose, program cells, goals and attributes are the author's, and
+ * this is not an excuse to reformat them.
+ *
+ * It goes through the SAME ERASURE PATH the reader's download already uses:
+ * `output: null` has always meant "there are no answers to write down here"
+ * (869ejgbxf), so nothing new decides what an emptied cell means.
+ *
+ * @param {{frontMatter: Map<string, string>, cells: object[]}} notebook
+ * @returns {{text: string, cleared: number}} the bytes, and how many were emptied
+ */
+export function clearedSource(notebook) {
+  const edits = new Map();
+  for (const cell of notebook.cells) {
+    if (cell.kind === 'query' && cell.output) edits.set(cell.id, { output: null });
+  }
+  return { text: exportSource(notebook, edits), cleared: edits.size };
+}
+
 /**
  * A filename for the reader's copy.
  *

package/src/notebook.js

@@ -25,6 +25,14 @@ let serial = 0;
 let panels = 0;
 
 /** Absolute, never relative: "3 minutes ago" is wrong the moment it is written. */
+/**
+ * How long a reader may stop typing before a prediction counts as written.
+ *
+ * Long enough that a first keystroke does not reveal the answers, short enough
+ * that somebody who has finished sees the consequence of finishing.
+ */
+const PREDICTION_PAUSE = 1200;
+
 function clock(date = new Date()) {
   return date.toLocaleTimeString(undefined, { hour12: false });
 }
@@ -190,6 +198,14 @@ const ICONS = {
   download: '<path d="M12 3.6v10.6"/><path d="m7.6 10.2 4.4 4.4 4.4-4.4"/><path d="M4.6 19.4h14.8"/>',
   hide: '<path d="M2.5 12S6 6 12 6s9.5 6 9.5 6-3.5 6-9.5 6-9.5-6-9.5-6Z"/><circle cx="12" cy="12" r="2.7"/><path d="M4 4l16 16"/>',
   show: '<path d="M2.5 12S6 6 12 6s9.5 6 9.5 6-3.5 6-9.5 6-9.5-6-9.5-6Z"/><circle cx="12" cy="12" r="2.7"/>',
+  // An eraser rubbing something out, NOT a bin. What clear does is undone by the
+  // button beside it, and a lid-and-body icon promises a finality this control
+  // does not have.
+  erase: '<path d="m7 21-4.3-4.3a2.4 2.4 0 0 1 0-3.4l9.6-9.6a2.4 2.4 0 0 1 3.4 0l5.6 5.6a2.4 2.4 0 0 1 0 3.4L13 21"/><path d="M21.4 21H7"/><path d="m5 11 9 9"/>',
+  // The undo hook, deliberately not the engine's circular arrow two rows below:
+  // two glyphs that near-match in one small card is how a reader presses the
+  // wrong one.
+  restore: '<path d="M3.2 7.4v6.2h6.2"/><path d="M20.8 17.2a9 9 0 0 0-9-9 9 9 0 0 0-6.4 2.6L3.2 13.6"/>',
 };
 
 function icon(name) {
@@ -218,6 +234,13 @@ function mountPageBar(root, options, bus, programs, queries) {
     + `<span class="dot"></span><span class="count"></span><span class="chev">${icon('chevron')}</span></button>`
     + `<div class="panel" id="${panelId}">`
     + '<div class="unit answers"><span class="state answers-state"></span></div>'
+    // THE SAME ANSWERS, THE OTHER QUESTION. The row above is about the screen —
+    // put them out of sight, work the chapter cold, they are still the chapter's.
+    // This one is about the FILE: an output cleared here is gone from the page
+    // and from a download of it, which is why its verb is undone by restore and
+    // not by show. Two rows because they are two questions, adjacent because a
+    // reader comparing them is exactly what tells them apart.
+    + '<div class="unit outputs"><span class="state outputs-state"></span></div>'
     + '<div class="unit"><span class="state engine-state"></span>'
     + `<button data-act="restart"><span class="icon">${icon('power')}</span>`
     + '<span class="label">Start engine</span></button></div>'
@@ -338,8 +361,14 @@ function mountPageBar(root, options, bus, programs, queries) {
   let age = null;
 
   bus.on((event) => {
-    // A cell's own hide control moved something this panel is reporting on.
-    if (event.kind === 'answers') return refreshAnswers();
+    // A cell's own hide or reset control moved something this panel is reporting
+    // on — both rows, since a cell restored on its own leaves one fewer cleared
+    // and one more showing.
+    if (event.kind === 'answers') {
+      refreshAnswers();
+      refreshOutputs();
+      return;
+    }
     if (event.kind === 'booting') {
       // Lit from wherever the engine was asked for — a Run halfway up the chapter
       // starts it just as this button does, and the light should not care which.
@@ -432,6 +461,73 @@ function mountPageBar(root, options, bus, programs, queries) {
     refreshAnswers();
   }
 
+  /**
+   * Take the answers out of the chapter, and put them back (869erp9ap).
+   *
+   * The page's half of `prolog-notebook clear`. An author emptying a chapter has
+   * the command; a reader who wants the file without the answers — to work
+   * through it later, to hand it to somebody, to keep a copy that gives nothing
+   * away — had to edit markdown by hand, which is the same "that's tedious" that
+   * put the command in the CLI.
+   *
+   * WHAT MAKES IT SAFE TO OFFER is that it is reversible in the page's existing
+   * vocabulary. Clear is a third way AWAY from the chapter, beside running and
+   * editing, and reset is still the one way back: per cell for one of them, and
+   * restore here for all at once.
+   */
+  const outputsUnit = bar.querySelector('.unit.outputs');
+  const outputsState = bar.querySelector('.outputs-state');
+  let refreshOutputs = () => {};
+  // Nothing published to clear, and nothing a restore could give back. The row
+  // goes, exactly as the one above it does — an unrun chapter is the CLI's
+  // business, and a control whose only possible effect is on the reader's own
+  // run is a control offering to undo the thing they just asked for.
+  if (!spoilers.length) {
+    outputsUnit.remove();
+  } else {
+    const wipe = document.createElement('button');
+    wipe.dataset.act = 'clear-all';
+    wipe.innerHTML = '<span class="icon"></span><span class="label"></span>';
+    outputsUnit.appendChild(wipe);
+
+    const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
+
+    refreshOutputs = () => {
+      const gone = queries.filter((q) => q.isCleared());
+      const left = queries.filter((q) => q.hasOutput());
+      // Restore only once there is nothing left to clear, which is the rule the
+      // hide/show button already follows: in a half-cleared page the useful move
+      // is to finish, and one vocabulary is cheaper to learn than two.
+      const back = left.length === 0 && gone.length > 0;
+      // A cleared cell that never had saved answers has nothing of the chapter's
+      // to give back, so a page of only those leaves restore with no work.
+      const restorable = gone.filter((q) => q.hasSaved).length;
+      wipe.disabled = back ? restorable === 0 : left.length === 0;
+      // COUNTED FROM THE FILE while nothing is cleared, because that is the fact
+      // the reader does not have: how much of this chapter is answers. After
+      // that it counts what they did, which is the fact they want confirmed.
+      outputsState.textContent = gone.length === 0
+        ? `${plural(spoilers.length, 'output')} in this chapter`
+        : `${plural(gone.length, 'output')} cleared`;
+      label(wipe, back ? 'restore' : 'erase',
+        back ? 'Restore outputs' : 'Clear all outputs');
+      wipe.title = back
+        ? 'put the chapter’s own answers back into every cell you cleared'
+        : 'empty every output on this page, your own runs included — a download'
+          + ' taken then carries none of them, and restore puts the chapter’s back';
+      render();
+    };
+
+    wipe.addEventListener('click', () => {
+      const left = queries.filter((q) => q.hasOutput());
+      if (left.length) for (const q of left) q.clear();
+      else for (const q of queries) if (q.isCleared()) q.restore();
+      refreshOutputs();
+      refreshAnswers();
+    });
+    refreshOutputs();
+  }
+
   restart.title = 'download SWI-Prolog and have it ready, so your first Run is not the slow one';
 
   restart.addEventListener('click', async () => {
@@ -815,6 +911,14 @@ function mountQuery(cell, options, bus, { above = [], below = [], prediction = n
   // to the chapter.
   let mine = false;
   let hidden = false;
+  // Emptied on purpose, by the page's own control (869erp9ap). A THIRD state
+  // rather than a kind of hiding: hidden answers are still the chapter's and
+  // still go into a download, and cleared ones are gone from both. What the two
+  // have in common is only that the box looks empty.
+  //
+  // It is a way AWAY from the chapter, like a run and like an edit, so the way
+  // back is the one that has always existed — reset.
+  let cleared = false;
   // The author's own spoiler mark (format §5). It is a starting state rather than
   // a lock: the reader can always press show, because withholding the answer from
   // someone who has decided they want it is theatre, not teaching.
@@ -870,7 +974,11 @@ function mountQuery(cell, options, bus, { above = [], below = [], prediction = n
 
   const refresh = () => {
     if (resetBtn) {
-      const changed = mine || input.value !== published.goal;
+      // Cleared counts, and it is the reason this cell can be brought back one at
+      // a time out of a page-wide clear. A reset button left grey over an emptied
+      // cell would say the answers are gone for good, which is the opposite of
+      // what this control is for.
+      const changed = mine || cleared || input.value !== published.goal;
       cell.dataset.edited = String(changed);
       resetBtn.disabled = !changed;
       resetBtn.title = changed
@@ -1080,9 +1188,13 @@ function mountQuery(cell, options, bus, { above = [], below = [], prediction = n
     // with the reader's own is fine; replacing them SILENTLY is not, so the run is
     // labelled and the way back is stated (docs/modes.md §3) — and the way back is
     // now a button on this cell rather than a page reload.
-    const hadSaved = !mine && out.querySelector('.line.from') !== null;
+    // ASKED OF THE CHAPTER, not of the screen. A cleared cell has nothing on
+    // screen to have come from the chapter, but the chapter's answers are still
+    // one press of reset away — so the note that says so is still owed.
+    const hadSaved = !mine && published.out !== '';
     out.innerHTML = '';
     mine = true;
+    cleared = false;
     // This cell has just stopped showing the chapter's answers, which changes what
     // the page's control is counting. setHidden only speaks up when the hidden
     // flag itself moves, so a cell that was already visible would leave the count
@@ -1197,6 +1309,12 @@ function mountQuery(cell, options, bus, { above = [], below = [], prediction = n
       // that quizzes the reader and then answers itself is worse than one that
       // never asked.
       if (held) return;
+      // AND A CLEARED CELL STAYS CLEARED. Auto exists so that answers do not go
+      // stale under a reader who changed the program; a cell with no answers has
+      // none that can. Refilling it would be the page overruling the reader who
+      // emptied it, and doing so behind their back — they pressed Consult
+      // somewhere else entirely.
+      if (cleared) return;
       if (running || query) return;
       if (!outOfDate()) return;
       bus.queue(() => {
@@ -1269,18 +1387,59 @@ function mountQuery(cell, options, bus, { above = [], below = [], prediction = n
    * disagreed in fact — the same argument that makes a program cell's reset
    * un-consult.
    */
-  resetBtn?.addEventListener('click', () => {
+  const restore = ({ goal = true } = {}) => {
     query?.close();
-    input.value = published.goal;
+    if (goal) input.value = published.goal;
     out.innerHTML = published.out;
     mine = false;
+    cleared = false;
     ran = null;
     engineChanged = false;
     decorateSaved();
     // Back in the set the page's control acts on, for the same reason.
     bus.emit({ kind: 'answers' });
     finish();
-  });
+  };
+
+  resetBtn?.addEventListener('click', () => restore());
+
+  /**
+   * Take the answers out — the chapter's included.
+   *
+   * The reader's half of `prolog-notebook clear`, and the same claim: there are
+   * no answers here. Not a stronger kind of hiding — a download taken now
+   * carries no output block for this cell, which is the whole difference and the
+   * reason it is undone by reset rather than by show.
+   *
+   * The reader's own run goes with it, because "clear all output" that leaves
+   * some output on the page has not done what it says. That is no worse than
+   * what reset has always done to a run, and Run reproduces it.
+   */
+  const clear = () => {
+    if (!mine && published.out === '') return false;
+    // An open sequence in a cell showing nothing is a frame held in the reader's
+    // name against a cell they have emptied — the same argument that makes reset
+    // close one.
+    query?.close();
+    out.innerHTML = '';
+    mine = false;
+    cleared = true;
+    ran = null;
+    engineChanged = false;
+    produced = [];
+    failed = null;
+    exhausted = false;
+    count = 0;
+    // Nothing to hide, and nothing to be held back from: the box is empty, and a
+    // cell that still said "held until you run it" would be describing a wait
+    // that no longer has anything to wait for.
+    hidden = false;
+    held = false;
+    out.classList.remove('answers-hidden');
+    bus.emit({ kind: 'answers' });
+    finish();
+    return true;
+  };
 
   input.addEventListener('input', refresh);
 
@@ -1294,11 +1453,31 @@ function mountQuery(cell, options, bus, { above = [], below = [], prediction = n
 
   if (held) {
     hidden = true;
-    // `change` rather than `input`: it fires when they leave the box, so the
-    // answers do not appear under a reader who is still mid-sentence. An empty
-    // box is not a prediction, so it does not end the wait.
-    prediction?.addEventListener('change', () => {
+    /**
+     * AS THEY WRITE, not when they leave the box.
+     *
+     * This listened on `change` alone, which fires on blur — so a reader who
+     * typed their prediction and looked up saw nothing happen, and the link
+     * between "I wrote something" and "the answers appeared" was broken by a
+     * pause with no cause (869ernmzh). The original reasoning was about the
+     * FIRST KEYSTROKE and it over-corrected: they have committed as soon as they
+     * have written something.
+     *
+     * Debounced, so one character does not reveal the chapter and a reader who is
+     * still typing is not interrupted. `change` stays as well, so leaving the box
+     * is immediate. An empty box is still not a prediction.
+     */
+    const release = () => {
       if (held && prediction.value.trim() !== '') setHidden(false);
+    };
+    let pause = null;
+    prediction?.addEventListener('input', () => {
+      clearTimeout(pause);
+      pause = setTimeout(release, PREDICTION_PAUSE);
+    });
+    prediction?.addEventListener('change', () => {
+      clearTimeout(pause);
+      release();
     });
   }
 
@@ -1315,11 +1494,23 @@ function mountQuery(cell, options, bus, { above = [], below = [], prediction = n
      * control acts on what is on screen, and after a run the chapter's answers
      * are behind reset rather than in front of the reader.
      */
-    showsChapter: () => !mine && published.out !== '',
+    showsChapter: () => !mine && !cleared && published.out !== '',
     setHidden,
     isHidden: () => hidden,
-    isEdited: () => mine || input.value !== published.goal,
+    isEdited: () => mine || cleared || input.value !== published.goal,
     goal: () => input.value,
+    /** Is there an output on screen at all — the chapter's or the reader's? */
+    hasOutput: () => !cleared && (mine || published.out !== ''),
+    isCleared: () => cleared,
+    clear,
+    /**
+     * Put the chapter's answers back, and nothing else.
+     *
+     * The exact inverse of clear, which is what lets the page offer the pair as
+     * one control: an edited goal is not an answer and was not what clear took
+     * away, so restoring one must not quietly discard the other.
+     */
+    restore: () => restore({ goal: false }),
     /**
      * This cell's answers for an export, in the format's own spelling (§6).
      *
@@ -1330,6 +1521,10 @@ function mountQuery(cell, options, bus, { above = [], below = [], prediction = n
      * has actually produced.
      */
     output: () => {
+      // `null` is the one that ERASES, and it is the same null the CLI's clear
+      // writes (src/export.js): a chapter emptied on the page and one emptied at
+      // the terminal produce the same bytes, because they take the same path.
+      if (cleared) return null;
       if (!mine) return undefined;
       // Stopping and finishing look the same from outside — both leave no open
       // query — so `exhausted` is the only thing that distinguishes them.

package/src/render.js

@@ -85,7 +85,7 @@ export function escapeHtml(text) {
  * @param {{variant: string, title: string, body: string}} cell
  * @returns {string}
  */
-export function renderContainer(cell) {
+export function renderContainer(cell, ordinal = 1) {
   switch (cell.variant) {
     case 'margin':
       // The whole note lives in the head line — `> [!margin] text with no body` —
@@ -122,7 +122,7 @@ function joinHeadAndBody(cell) {
  * markup for a place to answer it. The reveal is a <details> so that it still
  * works, unclicked, on the GitHub page.
  */
-function renderPredict(cell) {
+function renderPredict(cell, ordinal = 1) {
   const { before, summary, reveal } = splitReveal(cell.body);
   const parts = [];
   if (cell.title) parts.push(`<h3>${renderInline(cell.title)}</h3>`);
@@ -131,7 +131,11 @@ function renderPredict(cell) {
   // the format has no spelling for a per-prediction one, and inventing an
   // attribute for it would be a format change to save one line of prose — the
   // author's own question is directly above it and says what to write.
-  parts.push('<textarea placeholder="your prediction…" spellcheck="false"></textarea>');
+  // An id, because a form field without one is a warning in every browser's
+  // issues panel and this audience opens the issues panel (869ernmxe). Minted
+  // from position, since a container carries no id in the model — and stable for
+  // a given chapter, which is what a saved prediction will need (869ectt5d).
+  parts.push(`<textarea id="predict-${ordinal}" placeholder="your prediction…" spellcheck="false"></textarea>`);
   if (reveal !== null) {
     parts.push(`<details>\n<summary>${escapeHtml(summary)}</summary>\n${renderProse(reveal)}\n</details>`);
   }
@@ -177,7 +181,7 @@ export function renderProgram(cell) {
   <div class="bar">program<span class="spacer"></span><span class="status"></span>
     <button data-act="reset" disabled>reset</button>
     <button class="primary" data-act="consult">Consult</button></div>
-  <textarea spellcheck="false">${escapeHtml(cell.source)}</textarea>
+  <textarea id="src-${escapeHtml(cell.id)}" spellcheck="false">${escapeHtml(cell.source)}</textarea>
 </div>`;
 }
 
@@ -217,7 +221,8 @@ export function renderQuery(cell, options = {}) {
     <button data-act="next" disabled>; next</button>
     <button data-act="all" disabled>all</button>
     <button data-act="stop" disabled>stop</button></div>
-  <div class="prompt"><span>?-</span><input value="${escapeHtml(cell.goal)}" spellcheck="false"></div>
+  <div class="prompt"><span>?-</span>`
+    + `<input id="goal-${escapeHtml(cell.id)}" value="${escapeHtml(cell.goal)}" spellcheck="false"></div>
   <div class="out">${renderSavedOutput(cell, { stale })}</div>
 </div>`;
 }
@@ -305,7 +310,7 @@ export function renderCell(cell, options = {}) {
     case 'markdown':
       return renderProse(cell.source);
     case 'container':
-      return renderContainer(cell);
+      return renderContainer(cell, options.ordinal);
     case 'program':
       return renderProgram(cell);
     case 'query':
@@ -333,7 +338,9 @@ export function renderNotebook(notebook) {
   const parts = [];
   const kicker = renderKicker(notebook.frontMatter);
   if (kicker) parts.push(kicker);
+  let predictions = 0;
   for (const cell of notebook.cells) {
+    if (cell.kind === 'container' && cell.variant === 'predict') predictions += 1;
     // Staleness is decided here rather than in renderQuery, because it is a fact
     // about the cell's PLACE in the notebook — the program cells above it — and a
     // query cell on its own cannot know it. Computed before first paint: a 64-bit
@@ -348,7 +355,7 @@ export function renderNotebook(notebook) {
     const rerun = cell.kind === 'query'
       ? cell.rerun ?? notebook.frontMatter.get('rerun') ?? 'manual'
       : null;
-    parts.push(renderCell(cell, { stale, rerun }));
+    parts.push(renderCell(cell, { stale, rerun, ordinal: predictions }));
   }
   return `${parts.join('\n\n')}\n`;
 }

package/src/serve.js

@@ -8,8 +8,10 @@
 // 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 { spawn } from 'node:child_process';
 import { createReadStream } from 'node:fs';
 import { createServer } from 'node:http';
+import { connect } from 'node:net';
 
 const TYPES = {
   '.html': 'text/html; charset=utf-8',
@@ -34,6 +36,15 @@ export function contentType(name) {
  * @returns {Promise<{url: string, port: number, close: () => Promise<void>}>}
  */
 export async function serve(files, { port = 8777, host = '127.0.0.1' } = {}) {
+  // ASK WHETHER ANYBODY IS THERE, on both stacks, before binding to one of them.
+  //
+  // An IPv6 wildcard listener — `python3 -m http.server --bind ::` — does not
+  // collide with an IPv4 loopback bind, so EADDRINUSE never fires and the bind
+  // succeeds. `localhost` then resolves to ::1 first, and the reader gets the
+  // other server's directory listing while this one sits unreachable on
+  // 127.0.0.1 with nothing anywhere saying why (869ernmvh). Found by somebody
+  // authoring their first chapter, which is exactly where it would be found.
+  if (port !== 0 && await occupied(port)) port = 0;
   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.
@@ -78,3 +89,53 @@ function listen(server, port, host) {
     server.listen(port, host, () => resolve(server.address().port));
   });
 }
+
+/**
+ * Hand the URL to whatever the desktop uses.
+ *
+ * TWO WAYS THIS GOES WRONG, both found by reading it rather than running it:
+ *
+ * - `start` on Windows is a SHELL BUILTIN, not a program, so spawning it by name
+ *   fails every time. It has to be run through cmd, and the empty string is
+ *   cmd's title argument — without it, a quoted URL becomes the window title and
+ *   nothing opens.
+ * - spawn reports a missing program ASYNCHRONOUSLY. A try/catch around it catches
+ *   nothing, and an 'error' event with no listener is an uncaught exception —
+ *   which took the whole command down, AFTER the server had started, on any
+ *   machine without an opener. A listener that does nothing is the fix: the URL
+ *   is on screen either way, and a browser that will not open is not a reason to
+ *   stop serving.
+ */
+export function openInBrowser(url, { spawnImpl = spawn, platform = process.platform } = {}) {
+  const argv = platform === 'win32'
+    ? ['cmd', ['/c', 'start', '', url]]
+    : [platform === 'darwin' ? 'open' : 'xdg-open', [url]];
+  const child = spawnImpl(argv[0], argv[1], { stdio: 'ignore', detached: true });
+  child.on('error', () => {});
+  child.unref?.();
+  return child;
+}
+
+/**
+ * Is something already answering on this port, on either stack?
+ *
+ * A connect, not a bind: the question is "will the reader reach somebody else
+ * here", and a bind can succeed while the answer is yes.
+ */
+export async function occupied(port, { hosts = ['127.0.0.1', '::1'], timeout = 300 } = {}) {
+  const answers = await Promise.all(hosts.map((host) => reachable(host, port, timeout)));
+  return answers.some(Boolean);
+}
+
+function reachable(host, port, timeout) {
+  return new Promise((resolve) => {
+    const socket = connect({ host, port, timeout });
+    const done = (answer) => {
+      socket.destroy();
+      resolve(answer);
+    };
+    socket.once('connect', () => done(true));
+    socket.once('error', () => done(false));
+    socket.once('timeout', () => done(false));
+  });
+}

package/src/upgrade.js

@@ -67,7 +67,7 @@ export async function globalRoot(exec = run) {
 /**
  * Ask a yes/no question, defaulting to yes.
  *
- * ON STDERR, always: `run --stdout` is a notebook going down a pipe, and a
+ * ON STDERR, always: `execute --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>}

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