prolog-notebook 0.6.1 → 0.6.3

package/CHANGELOG.md

@@ -1,5 +1,71 @@
 # Changelog
 
+## [0.6.3] — 2026-08-30
+
+`prolog-notebook build lists.prolog.md --check-update` answered *unknown option* — on a flag the
+help listed under no command, exactly as though it were global.
+
+### Fixed
+
+- **`--check-update` works with every command**, and forces the check past the daily TTL, which
+  is the whole point of asking. It was accepted by `execute` alone.
+
+- **…and it answers down a pipe.** The check was skipped entirely without a terminal, so an
+  explicit check in a script reported nothing — indistinguishable from *you are up to date*,
+  which is the one thing an update notice must never look like. A terminal is needed to **offer**
+  an upgrade, never to **report** one.
+
+- **`build --port 90` was accepted and ignored.** `view` and `build` share a parser, so each
+  quietly took the other's flags. A flag that is read and thrown away is worse than one refused:
+  it looks like it worked.
+
+- **`clear` never looked for an update.** 0.5.1 established that every command doing real work
+  goes through one door, before the work; `clear` shipped afterwards and missed it, while
+  rewriting the author's notebook.
+
+### Changed
+
+- **The help lists each option under the command that takes it.** Only `--check-update`,
+  `--version` and `-h` are listed as working anywhere, because only those three do.
+
+- **A misplaced option says where it lives** — `--limit belongs to execute, not to view` —
+  rather than `unknown option` about a flag that is real and two lines further up.
+
+## [0.6.2] — 2026-08-30
+
+From a field report: a built chapter opened in Chrome and Safari showed no controls and a Run
+button that did nothing, while the same directory worked in VS Code's browser.
+
+### Fixed
+
+- **A page that could not run looked exactly like one that could.** Opening `index.html` from
+  disk means `file://`, where browsers refuse ES modules, so none of the runtime loads. That
+  part is the browser doing its job; the page then lied about it twice.
+
+  The warning that exists for this sat **after the whole chapter** — line 540 of 551 — several
+  screens below the fold, which is the one place it could not do its job. It is now first in
+  the document and a fixed banner, revealed by a CSS `animation-delay` rather than a timer,
+  because script is precisely what is broken when it matters. `mount()` removes it long before
+  the delay elapses, so a page that boots never shows it and nothing jolts.
+
+  And **Run and Consult shipped enabled**, so the two controls a reader reaches for first were
+  full colour and inert — a screenshot of the failure was indistinguishable from success. They
+  now ship disabled and `mount()` enables them, which makes "this button works" and "something
+  is here to work it" one fact rather than two that can disagree. It also closes a real race on
+  a slow page.
+
+- **Every prediction box had the same id.** The ordinal is counted correctly and was dropped on
+  the last hop into `renderPredict`, which took its default every time. The test asserted the
+  shape of the id, which three identical ones satisfy; it now asserts uniqueness.
+
+- **The version picker had neither an id nor a name.** It only exists on a page that boots,
+  which is why the earlier console sweep never saw it. A served chapter's console is now empty.
+
+### Changed
+
+- `build` says that opening the directory from disk will not run, rather than mentioning HTTP
+  in passing. It is the point at which somebody is about to double-click the thing.
+
 ## [0.6.1] — 2026-08-30
 
 ### Fixed

package/README.md

@@ -132,16 +132,24 @@ 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.
 
+Each option belongs to a command, and typing one under the wrong command tells you which:
+
+| flag | on | |
+|---|---|---|
+| `--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` |
+| `--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 |
+
+Three work anywhere, because they are about the tool rather than about a notebook:
+
 | 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 |
+| `--check-update` | ask npm whether a newer one exists, and say so either way — forced, whatever the daily check thinks, and answered even down a pipe |
+| `-h`, `--help` | the same list, from the command itself |
 
 ```sh
 prolog-notebook upgrade      # fetch the latest

package/bin/prolog-notebook.mjs

@@ -37,29 +37,66 @@ for (const stream of [process.stdout, process.stderr]) {
 // src/version.js, where a page can import it too.
 const require = createRequire(import.meta.url);
 
+/**
+ * EACH OPTION UNDER THE COMMAND THAT TAKES IT (869erqra0).
+ *
+ * They were listed in one flat `Options` block with no owner, which reads as a
+ * promise that every one of them works everywhere — so `build --check-update`
+ * was a reasonable thing to type and `unknown option` was a strange thing to be
+ * told. Only three of them are actually the tool's rather than a command's, and
+ * now only those three are listed as such.
+ */
 const USAGE = `prolog-notebook — Jupyter-style notebooks for Prolog
 
   prolog-notebook view <file.prolog.md>       read it in a browser, cells and all
+    --port <n>      what it listens on (default 8777)
+    --no-open       print the URL instead of opening a browser
+
   prolog-notebook build <file.prolog.md>      write a page you can host or send
+    --out <dir>     where it writes (default: <file>-site)
+
   prolog-notebook execute <file.prolog.md>... run every query, write the answers in
+    --limit <n>     solutions to take from one query before stopping (default ${DEFAULT_LIMIT})
+    --stdout        print the result instead of writing the file
+    --quiet         report only failures
+
   prolog-notebook clear <file.prolog.md>...   take the answers back out
+    --stdout        print the result instead of writing the file
+    --quiet         report only failures
+
   prolog-notebook upgrade                     fetch the latest version
 
-Options
-  --limit <n>     solutions to take from one query before stopping (default ${DEFAULT_LIMIT})
-  --stdout        print the result instead of writing the file
-  --quiet         report only failures
-  --out <dir>     where build writes (default: <file>-site)
-  --port <n>      what view listens on (default 8777)
-  --no-open       view prints the URL instead of opening a browser
-  --version       version, engine and copyright
+Anywhere
   --check-update  ask npm whether a newer one exists, and say so either way
+  --version       version, engine and copyright
   -h, --help      this
 
 A query that stops at the limit is written without a terminator, which is the
 format's way of saying the search was never exhausted. Nothing is invented.
 `;
 
+/**
+ * Which command each option belongs to, so a misplaced one can say where it lives.
+ *
+ * `unknown option "--limit"` is true and unhelpful when the flag is real and two
+ * lines further up the same help. This costs a lookup table and saves a re-read.
+ */
+const BELONGS_TO = {
+  '--limit': 'execute',
+  '--stdout': 'execute and clear',
+  '--quiet': 'execute and clear',
+  '--out': 'build',
+  '--port': 'view',
+  '--no-open': 'view',
+};
+
+function unknownOption(arg, command) {
+  const home = BELONGS_TO[arg];
+  return home && home !== command
+    ? `${arg} belongs to ${home}, not to ${command}\n`
+    : `unknown option "${arg}"\n`;
+}
+
 /**
  * A runaway goal hangs this process — the engine is in-process here, so there is
  * no thread left to notice (869ejgyax). Stated rather than implied, because the
@@ -158,11 +195,18 @@ function canAsk() {
  *   to a newer version, null to carry on here.
  */
 async function upgradeFirst({ quiet = false, asked = false } = {}) {
-  if (!canAsk() || (quiet && !asked)) return null;
+  // ASKED OUTRIGHT ALWAYS ANSWERS (869erqra0). A terminal is needed to OFFER the
+  // upgrade, never to report one: `--check-update` down a pipe used to check
+  // nothing and say nothing, which is indistinguishable from "you are up to
+  // date" — the one thing this must never look like.
+  if (!asked && (!canAsk() || quiet)) 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;
+  // The notice is printed above whatever happens next; only the question needs
+  // somebody at the other end to answer it.
+  if (!ahead.newer || !canAsk()) return null;
+  if (!(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;
@@ -213,8 +257,8 @@ 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 === 'view' || command === 'build') return page(command, args, asked);
+  if (command === 'clear') return clear(args, asked);
   if (command === 'upgrade') {
     const { message, newer } = await updateNotice({ version: VERSION, force: true });
     if (message) process.stderr.write(`${message}\n`);
@@ -246,7 +290,7 @@ async function main(argv) {
     else if (arg === '--quiet') options.quiet = true;
     else if (arg === '--check-update') { /* handled above, and not a file */ }
     else if (arg.startsWith('-')) {
-      process.stderr.write(`unknown option "${arg}"\n\n${USAGE}`);
+      process.stderr.write(unknownOption(arg, 'execute'));
       return 2;
     } else files.push(arg);
   }
@@ -259,7 +303,9 @@ async function main(argv) {
 
   const jump = await upgradeFirst({ quiet: options.quiet, asked });
   if (jump !== null) return jump;
-  checked = canAsk() && (!options.quiet || asked);
+  // Whatever upgradeFirst has just reported must not be reported again below.
+  // Asked outright, it always reports now, terminal or not.
+  checked = asked || (canAsk() && !options.quiet);
 
   // 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
@@ -309,14 +355,16 @@ async function main(argv) {
  * No engine, no network and no update check: this is a text operation on a file
  * the reader already has.
  */
-async function clear(args) {
+async function clear(args, asked = false) {
   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;
+    // Handled by the caller, and not a file.
+    else if (arg === '--check-update') { /* global */ }
     else if (arg.startsWith('-')) {
-      process.stderr.write(`unknown option "${arg}"\n`);
+      process.stderr.write(unknownOption(arg, 'clear'));
       return 2;
     } else files.push(arg);
   }
@@ -325,6 +373,13 @@ async function clear(args) {
     return 2;
   }
 
+  // THE SAME DOOR AS EVERY OTHER COMMAND THAT DOES REAL WORK (869erqra0). 0.5.1
+  // put `view` and `build` through it and this command shipped afterwards, so it
+  // never looked. Emptying somebody's notebook is as real as work gets here, and
+  // before the work is the only point at which a newer version changes anything.
+  const jump = await upgradeFirst({ quiet: options.quiet, asked });
+  if (jump !== null) return jump;
+
   let status = 0;
   for (const file of files) {
     let source;
@@ -361,11 +416,20 @@ async function clear(args) {
  * whole reason a built page is readable before any engine arrives. Use `run` to
  * put them there.
  */
-async function page(command, args) {
+async function page(command, args, asked = false) {
   const options = { out: null, port: 8777, open: true };
   const files = [];
   while (args.length) {
     const arg = args.shift();
+    // ONE PARSER, TWO COMMANDS, AND THEY DO NOT TAKE THE SAME FLAGS. `view` and
+    // `build` share this function, so `build --port 90` was quietly accepted and
+    // ignored while the help said --port was view's (869erqra0). A flag that is
+    // read and thrown away is worse than one that is refused: it looks like it
+    // worked.
+    if (BELONGS_TO[arg] && BELONGS_TO[arg] !== command) {
+      process.stderr.write(unknownOption(arg, command));
+      return 2;
+    }
     if (arg === '--out') options.out = args.shift();
     else if (arg === '--port') {
       options.port = Number(args.shift());
@@ -374,8 +438,10 @@ async function page(command, args) {
         return 2;
       }
     } else if (arg === '--no-open') options.open = false;
+    // Handled by the caller, and not a file.
+    else if (arg === '--check-update') { /* global */ }
     else if (arg.startsWith('-')) {
-      process.stderr.write(`unknown option "${arg}"\n`);
+      process.stderr.write(unknownOption(arg, command));
       return 2;
     } else files.push(arg);
   }
@@ -387,7 +453,7 @@ async function page(command, args) {
   // 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();
+  const jump = await upgradeFirst({ asked });
   if (jump !== null) return jump;
 
   const file = files[0];
@@ -416,7 +482,13 @@ async function page(command, args) {
       else copyFileSync(entry.copy, target);
     }
     process.stderr.write(`${out}: ${built.size} files\n`);
-    process.stderr.write(`Open ${join(out, 'index.html')} over HTTP, or host the directory.\n`);
+    // 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`
+      + ' will not run.\n');
     return 0;
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prolog-notebook",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "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": "3abbaef",
-  "built": "2026-08-30 19:27:20 UTC"
+  "commit": "2d089b9",
+  "built": "2026-08-30 22:55:39 UTC"
 }

package/src/build.js

@@ -176,19 +176,26 @@ function page(notebook) {
 </head>
 <body>
 <main>
-${renderNotebook(notebook)}
 <!--
-  THE CHAPTER ABOVE IS ALREADY READABLE. Everything below is the runtime that
-  makes it runnable, and none of it is needed to read a word.
+  FIRST IN THE DOCUMENT, AND IT COSTS A READER NOTHING (869erqq1u). mount()
+  removes this element, and the stylesheet holds it invisible for a second and a
+  half before revealing it — so a page that boots never shows it, and a page that
+  cannot boot says so where somebody staring at a dead button will see it. It
+  used to sit AFTER the chapter, several screens below the fold, which is the one
+  place it could not do its job.
+
+  The delay is CSS rather than a timer, for the obvious reason: script is exactly
+  what is broken when this matters.
 -->
 <div id="boot-warning">
   <strong>This notebook is not running.</strong>
   The page loaded but its JavaScript did not. The usual cause is opening
-  <code>index.html</code> straight from disk — browsers block ES modules over
-  <code>file://</code>. Serve it over HTTP instead, or run
-  <code>prolog-notebook view</code> on the notebook itself.
-  The chapter is readable either way; only the buttons need this.
+  <code>index.html</code> straight from disk — browsers refuse ES modules over
+  <code>file://</code>, and the engine cannot be fetched there either. Serve this
+  directory over HTTP, or run <code>prolog-notebook view</code> on the notebook
+  itself. The chapter is readable either way; only the buttons need this.
 </div>
+${renderNotebook(notebook)}
 </main>
 <script type="module" src="app.js"></script>
 </body>

package/src/notebook.css

@@ -502,13 +502,47 @@ button.primary:hover { background: #98380f; }
 }
 
 /* Shown until mount() runs; see notebook.js. Its presence means the page is inert. */
+/* THE PAGE THAT CANNOT RUN HAS TO SAY SO, WHERE IT WILL BE READ (869erqq1u).
+
+   Two properties, and both are the point:
+
+   FIXED, so it takes no layout. A working page carries this element for the
+   fraction of a second before mount() removes it, and a banner in the flow would
+   push the whole chapter down and then let it snap back — a visible jolt on every
+   single load, to warn about something that is not happening.
+
+   REVEALED ON A DELAY, in CSS. mount() removes it long before the animation
+   fires, so a page that boots never shows it at all; a page that cannot boot
+   shows it a second and a half in. It cannot be a timer, because script is the
+   thing that is broken. `forwards` holds the final frame rather than snapping
+   back to invisible. */
 #boot-warning {
-  margin: 0 0 2rem;
+  position: fixed;
+  top: 0;
+  left: 0;
+  right: 0;
+  z-index: 100;
+  margin: 0;
   padding: 1rem 1.2rem;
-  border: 2px solid var(--err);
-  border-radius: 6px;
+  border-bottom: 2px solid var(--err);
   background: #fff5f3;
   font-size: .95rem;
+  opacity: 0;
+  animation: boot-warning .25s ease 1.5s forwards;
+}
+@keyframes boot-warning { to { opacity: 1; } }
+/* ROOM FOR IT, made on the same delay and only while it is there. A fixed banner
+   would otherwise sit over the chapter's title — the page is broken, but it
+   should not also look broken. `:has` is what keeps this honest: the moment
+   mount() removes the element the selector stops matching, so a page that boots
+   never reserves the space, and a browser too old for `:has` merely goes back to
+   the banner overlapping. */
+body:has(#boot-warning) { animation: boot-warning-room .25s ease 1.5s forwards; }
+@keyframes boot-warning-room { to { padding-top: 7rem; } }
+/* Somebody who has asked not to be moved still gets the message — only the fade
+   goes. Without this the whole rule is skipped and the warning never appears. */
+@media (prefers-reduced-motion: reduce) {
+  #boot-warning { animation-duration: 0s; }
 }
 #boot-warning strong { color: var(--err); }
 #boot-warning pre {

package/src/notebook.js

@@ -595,7 +595,12 @@ export function offerDownload(root, options = {}) {
   // their version IS the chapter, and a menu with one item is a control
   // pretending to offer something.
   unit.innerHTML = '<span class="state notebook-state"><span class="only"></span>'
-    + '<span class="picker" hidden><select aria-label="which version to download">'
+    // `name` rather than `id`, because a page may hold more than one notebook
+    // (v0.4) and two ids would collide where two names cannot — this select is in
+    // no form. Without either, the issues panel flags it, which is the same red
+    // console 869ernmxe was about; it only shows up on a page that BOOTS, so the
+    // earlier sweep never saw it.
+    + '<span class="picker" hidden><select name="notebook-version" aria-label="which version to download">'
     + '<option value="mine">Your version</option>'
     + '<option value="published">As published</option>'
     + `</select>${icon('chevron')}</span></span>`
@@ -677,6 +682,10 @@ function mountProgram(cell, options, bus) {
   const button = cell.querySelector('[data-act="consult"]') ?? cell.querySelector('button');
   const resetBtn = cell.querySelector('[data-act="reset"]');
   const status = cell.querySelector('.status');
+  // THE BUTTON IS LIVE BECAUSE THIS RAN, and not a moment before (869erqq1u).
+  // It ships disabled so that a page whose runtime never arrived looks like what
+  // it is, rather than offering a control nothing is listening to.
+  button.disabled = false;
 
   /**
    * The one cell whose state a re-consult does not undo (format §8).
@@ -1482,6 +1491,10 @@ function mountQuery(cell, options, bus, { above = [], below = [], prediction = n
   }
 
   decorateSaved();
+  // Same as a program cell's Consult: enabled here, by the thing that makes it
+  // do something, so the page cannot show a live-looking Run with no runtime
+  // behind it (869erqq1u).
+  runBtn.disabled = false;
   refresh();
 
   return {

package/src/render.js

@@ -100,7 +100,7 @@ export function renderContainer(cell, ordinal = 1) {
       return `<div class="aside">\n${renderProse(joinHeadAndBody(cell))}\n</div>`;
 
     case 'predict':
-      return renderPredict(cell);
+      return renderPredict(cell, ordinal);
 
     case 'bullets':
       return `<div class="bullets">\n${cell.title ? `<h2>${renderInline(cell.title)}</h2>\n` : ''}${renderProse(cell.body)}\n</div>`;
@@ -164,6 +164,24 @@ function splitReveal(body) {
   };
 }
 
+/**
+ * EVERY BUTTON SHIPS DISABLED, AND THE RUNTIME TURNS IT ON (869erqq1u).
+ *
+ * A page whose JavaScript never arrives is a page where none of these can work —
+ * opened from disk, where browsers refuse ES modules; behind a CSP that blocks
+ * the script; on a connection that dropped it. What that page must not do is look
+ * exactly like a working one. Consult and Run used to ship enabled, so the two
+ * controls a reader reaches for first were full colour and did nothing, and a
+ * screenshot of the failure was indistinguishable from success.
+ *
+ * mount() enables them, which makes "this button works" and "something is here to
+ * work it" the same fact rather than two that can disagree. It also closes a real
+ * race on a slow page: they were clickable before anything was wired to them.
+ *
+ * `; next`, `all` and `stop` were already disabled for the ordinary reason — there
+ * is no query open yet — and now the whole bar tells one story.
+ */
+
 /**
  * A program cell: the Prolog, and a button that loads it.
  *
@@ -180,7 +198,7 @@ export function renderProgram(cell) {
   return `<div class="cell program" data-cell="${escapeHtml(cell.id)}">
   <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>
+    <button class="primary" data-act="consult" disabled>Consult</button></div>
   <textarea id="src-${escapeHtml(cell.id)}" spellcheck="false">${escapeHtml(cell.source)}</textarea>
 </div>`;
 }
@@ -217,7 +235,7 @@ export function renderQuery(cell, options = {}) {
   return `<div class="cell query" data-cell="${escapeHtml(cell.id)}"${hold}${auto}${wasStale}>
   <div class="bar">query<span class="spacer"></span><span class="status"></span>
     <button data-act="reset" disabled>reset</button>
-    <button class="primary" data-act="run">Run</button>
+    <button class="primary" data-act="run" disabled>Run</button>
     <button data-act="next" disabled>; next</button>
     <button data-act="all" disabled>all</button>
     <button data-act="stop" disabled>stop</button></div>

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