prolog-notebook 0.6.0 → 0.6.1

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## [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;
@@ -413,7 +420,7 @@ async function page(command, args) {
     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.1",
   "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": "3abbaef",
+  "built": "2026-08-30 19:27:20 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).
  *

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