prolog-notebook 0.6.0 → 0.6.2

package/CHANGELOG.md

@@ -1,5 +1,63 @@
 # Changelog
 
+## [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
+
+- **`view` served the notebook as it was when the server started.** It built the page once and
+  handed the map to the server, which held it for the life of the process — so an author who
+  edited their chapter and reloaded was shown the version the server had started with. A reload
+  is the gesture for *show me what I just did*, and answering it with the old page teaches an
+  author to doubt their own edit rather than the tool.
+
+  The request is now what reads the file, so there is no window in which the page and the file
+  can disagree, and nothing that can have missed a change. Compared by bytes rather than mtime:
+  an editor writing through a rename, a `git checkout` and two saves inside one millisecond are
+  all changes an mtime reports unreliably, and reparsing a chapter is milliseconds on a file the
+  author has open anyway. An unchanged file is read and not rebuilt.
+
+  A chapter that stops parsing keeps the last version that did, with the parser's own message
+  across the top of the page and once on stderr — not once per asset. Silently serving the
+  previous version would be the same bug wearing the fix's clothes, and blanking the page would
+  throw a chapter away over a half-typed fence. Fixing the file restores it with no restart.
+
+  `build` is unchanged: it takes the first answer and writes it.
+
 ## [0.6.0] — 2026-08-30
 
 Taking the answers back out — at the terminal, and on the page. Plus the first documentation

package/bin/prolog-notebook.mjs

@@ -14,7 +14,7 @@ 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 { buildFiles } from '../src/build.js';
+import { livePages } from '../src/build.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
@@ -391,10 +391,17 @@ async function page(command, args) {
   if (jump !== null) return jump;
 
   const file = files[0];
+  // ASKED AGAIN ON EVERY REQUEST, and built again only when the bytes have moved
+  // (869erpuhk). `build` takes the first answer and writes it; `view` keeps the
+  // producer, so a reload shows the chapter as it is now rather than as it was
+  // when the server started.
+  const pages = livePages(() => readFileSync(file, 'utf8'), {
+    filename: basename(file),
+    onError: (e) => process.stderr.write(`${file}: ${e.message}\n`),
+  });
   let built;
   try {
-    const source = readFileSync(file, 'utf8');
-    built = buildFiles(parse(source), source, { filename: basename(file) });
+    built = pages();
   } catch (e) {
     process.stderr.write(`${file}: ${e.message}\n`);
     return 1;
@@ -409,11 +416,17 @@ 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;
   }
 
-  const server = await serve(built, { port: options.port });
+  const server = await serve(pages, { port: options.port });
   // 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prolog-notebook",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "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": "4e10d19",
-  "built": "2026-08-30 18:33:44 UTC"
+  "commit": "bdbce1b",
+  "built": "2026-08-30 22:41:37 UTC"
 }

package/src/build.js

@@ -15,6 +15,7 @@
 // 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 { parse } from './format.js';
 import { renderNotebook } from './render.js';
 
 /** The runtime a page needs. Copied side by side, so their relative imports hold. */
@@ -67,6 +68,82 @@ export function buildFiles(notebook, source, options = {}) {
   return files;
 }
 
+/**
+ * The page, rebuilt whenever the notebook has changed underneath it (869erpuhk).
+ *
+ * `view` used to build once and serve that forever, so an author who edited their
+ * chapter and reloaded was shown the version the server had started with. A
+ * reload is the gesture for "show me what I just did"; answering it with the old
+ * page teaches an author to doubt their own edit.
+ *
+ * COMPARED BY BYTES, not by mtime. The point of a rebuild here is to be right
+ * rather than quick — an editor that writes through a rename, a `git checkout`, a
+ * clock that went backwards, two saves inside one millisecond, all of them are
+ * changes and none of them reliably move an mtime the way one would hope. Reading
+ * a chapter is microseconds and reparsing one is milliseconds, on a file the
+ * author has open anyway.
+ *
+ * A BROKEN FILE KEEPS THE LAST GOOD PAGE AND SAYS SO. Silently serving the
+ * previous version would be the same bug this exists to fix, so the page carries
+ * the parser's own message. Blanking it instead would throw away a chapter over a
+ * half-typed fence — an author saves mid-thought, and the useful thing on screen
+ * is the last version that worked, labelled.
+ *
+ * @param {() => string} read the notebook's bytes, now
+ * @param {{onError?: (e: Error) => void}} [options] and everything buildFiles takes
+ * @returns {() => Map<string, {text: string}|{copy: URL}>}
+ */
+export function livePages(read, { onError = () => {}, ...options } = {}) {
+  let last = null;
+  let failing = null;
+  return () => {
+    let source = null;
+    try {
+      source = read();
+      if (last && last.source === source) return last.files;
+      const files = buildFiles(parse(source), source, options);
+      last = { source, files };
+      failing = null;
+      return files;
+    } catch (e) {
+      // Nothing good to fall back to: this is the first build, and the caller —
+      // the command — is the one that should report it and stop.
+      if (!last) throw e;
+      // Once per broken version, not once per request. A page fetches a dozen
+      // files, and a terminal repeating the same syntax error a dozen times is
+      // worse at communicating it than saying it once.
+      if (failing !== source) onError(e);
+      failing = source;
+      return withNotice(last.files, e.message);
+    }
+  };
+}
+
+/**
+ * The last good page, wearing the reason it is not the current one.
+ *
+ * A copy, so the good build is never mutated and recovering is simply serving it
+ * again.
+ */
+function withNotice(files, message) {
+  const index = files.get('index.html');
+  if (index?.text === undefined) return files;
+  const copy = new Map(files);
+  copy.set('index.html', { text: index.text.replace('<body>', `<body>\n${notice(message)}`) });
+  return copy;
+}
+
+/**
+ * Inline styles, deliberately: this belongs to no chapter and must never depend
+ * on a stylesheet the broken file might itself have been changing.
+ */
+function notice(message) {
+  return '<div role="alert" style="position:sticky;top:0;z-index:99;padding:.7rem 1rem;'
+    + 'background:#7a2618;color:#fff;font:500 .8rem/1.5 ui-monospace,Menlo,monospace">'
+    + '<strong>This notebook does not currently parse.</strong> Showing the last version that'
+    + ` did.<br>${escapeHtml(message)}</div>`;
+}
+
 /**
  * The chapter's own title, from its first H1 (format §2).
  *
@@ -99,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/serve.js

@@ -31,11 +31,24 @@ export function contentType(name) {
 /**
  * Serve a built page.
  *
- * @param {Map<string, {text: string}|{copy: URL}>} files what build produced
+ * THE REQUEST IS WHAT READS THE FILE, when a producer is given rather than a map
+ * (869erpuhk). The first version of this held the map it was handed for the life
+ * of the process, so `view` served the notebook as it had been at start-up and a
+ * reload — the universal gesture for "show me what I just did" — confirmed the
+ * old version. An author doubts their edit before they doubt the tool.
+ *
+ * Asked per request rather than pushed by a watcher, because that is what makes
+ * the guarantee unconditional: there is no window in which the page and the file
+ * disagree, and nothing to have missed a change. A watcher (869edp5c8) can only
+ * ever save the reader a keystroke on top of this.
+ *
+ * @param {Map<string, {text: string}|{copy: URL}>|(() => Map)} pages what build
+ *   produced, or something that produces it — called once per request
  * @param {{port?: number, host?: string}} [options]
  * @returns {Promise<{url: string, port: number, close: () => Promise<void>}>}
  */
-export async function serve(files, { port = 8777, host = '127.0.0.1' } = {}) {
+export async function serve(pages, { port = 8777, host = '127.0.0.1' } = {}) {
+  const files = typeof pages === 'function' ? pages : () => pages;
   // 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
@@ -49,7 +62,7 @@ export async function serve(files, { port = 8777, host = '127.0.0.1' } = {}) {
     // Only GET, and only the names this process generated: the path never
     // reaches the filesystem, so there is nothing for a `..` to escape into.
     const name = decodeURIComponent(new URL(request.url, 'http://x').pathname).replace(/^\//, '');
-    const entry = files.get(name === '' ? 'index.html' : name);
+    const entry = files().get(name === '' ? 'index.html' : name);
     if (request.method !== 'GET' || !entry) {
       response.writeHead(404, { 'content-type': 'text/plain' }).end('not found\n');
       return;

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