prolog-notebook 0.1.2 → 0.3.1

package/package.json

@@ -1,16 +1,27 @@
 {
   "name": "prolog-notebook",
-  "version": "0.1.2",
+  "version": "0.3.1",
   "description": "Jupyter-style notebooks for Prolog. Runs in the browser, installs nothing.",
   "type": "module",
   "main": "./src/node.js",
+  "bin": {
+    "prolog-notebook": "./bin/prolog-notebook.mjs"
+  },
   "exports": {
     ".": "./src/node.js",
     "./browser": "./src/browser.js",
     "./engine": "./src/engine.js",
-    "./notebook.css": "./src/notebook.css"
+    "./format": "./src/format.js",
+    "./notebook.css": "./src/notebook.css",
+    "./page": "./src/page.js",
+    "./render": "./src/render.js",
+    "./session": "./src/session.js",
+    "./worker": "./src/worker.js",
+    "./run": "./src/run.js",
+    "./export": "./src/export.js"
   },
   "files": [
+    "bin",
     "src",
     "README.md",
     "LICENSE",
@@ -18,7 +29,7 @@
   ],
   "scripts": {
     "test": "node --test test/*.test.mjs",
-    "example": "python3 -m http.server 8777",
+    "dev": "python3 -m http.server 8777",
     "prepublishOnly": "npm test"
   },
   "keywords": [
@@ -45,9 +56,13 @@
     "node": ">=18"
   },
   "dependencies": {
-    "swipl-wasm": "^8.0.4"
+    "markdown-it": "^15.0.0",
+    "swipl-wasm": "8.0.7"
   },
   "publishConfig": {
     "access": "public"
+  },
+  "devDependencies": {
+    "jsdom": "^29.1.1"
   }
 }

package/src/browser.js

@@ -1,25 +1,261 @@
-// Browser entry point. The swipl-wasm bundle is loaded by a <script> tag and
-// exposes a global SWIPL factory; keeping the load out of this module means the
-// 5.9 MB bundle is fetched by the page, not by a bundler.
-import { PrologSession } from './engine.js';
+// Browser entry point. The engine runs in a Web Worker, so a query that never
+// terminates costs the reader a click on Stop rather than the whole tab.
+//
+// The 5.9 MB swipl bundle is still fetched by the page's own URL rather than by a
+// bundler — the worker is told where to find it.
+import { ConsultLog, defaultCellName, unconsult } from './session.js';
 
 export * from './engine.js';
+export { ConsultLog } from './session.js';
 
-let session = null;
+const DEFAULT_SWIPL_URL = new URL(
+  '../node_modules/swipl-wasm/dist/swipl/swipl-bundle.js',
+  import.meta.url
+).href;
 
 /**
- * Boot (once) and return the shared session for this page.
- * @returns {Promise<PrologSession>}
+ * A session whose engine lives in a worker.
+ *
+ * Every method returns a promise. `abort()` terminates the worker outright and
+ * replays the consult log into a new one, which is the only thing that works: a
+ * thread blocked inside WASM cannot be asked politely to stop.
  */
-export function createSession(options = {}) {
-  if (!session) {
-    if (typeof globalThis.SWIPL !== 'function') {
-      throw new Error(
-        'swipl-wasm not found. Load it first, e.g.\n' +
-          '<script src="node_modules/swipl-wasm/dist/swipl/swipl-bundle.js"></script>'
-      );
+export class WorkerSession {
+  #worker = null;
+  #pending = new Map();
+  #nextId = 1;
+  #booting = null;
+  /** The one query allowed to hold a frame. See supersede(). */
+  #open = null;
+
+  constructor({ workerUrl, swiplUrl = DEFAULT_SWIPL_URL, engineUrl, options = {} } = {}) {
+    this.workerUrl = workerUrl ?? new URL('./worker.js', import.meta.url).href;
+    this.swiplUrl = swiplUrl;
+    // The worker imports the engine itself, so it needs an absolute URL: a
+    // relative specifier would resolve against the worker script, which may have
+    // been served from anywhere.
+    this.engineUrl = engineUrl ?? new URL('./engine.js', import.meta.url).href;
+    this.options = options;
+    this.log = new ConsultLog();
+  }
+
+  /** Boot the worker and the engine inside it. Idempotent. */
+  async start() {
+    if (this.#worker) return this;
+    if (this.#booting) return this.#booting;
+    this.#booting = (async () => {
+      this.#spawn();
+      await this.#send('boot', {
+        swiplUrl: this.swiplUrl,
+        engineUrl: this.engineUrl,
+        options: this.options,
+      });
+      this.#booting = null;
+      return this;
+    })();
+    return this.#booting;
+  }
+
+  async consult(text, name = defaultCellName()) {
+    await this.start();
+    const result = await this.#send('consult', { text, name });
+    if (result.ok) this.log.record(name, text);
+    return result;
+  }
+
+  /**
+   * Open a query. Nothing runs until the first `next()` or `all()`, so opening
+   * one is always safe even if the goal is a disaster.
+   */
+  query(goal) {
+    return new WorkerQuery(this, goal);
+  }
+
+  /**
+   * ONE OPEN SEQUENCE PER SESSION, and the reason is not tidiness.
+   *
+   * SWI keeps open queries on a stack and swipl-wasm enforces it: stepping or
+   * closing anything but the innermost throws "Attempt to access not innermost
+   * query". A page cannot promise the order — the order is whatever the reader
+   * clicks — so the constraint is met by construction instead: there is never
+   * more than one open query, which means the one being closed is always the
+   * innermost, which means the close is always legal (869epzqpc).
+   *
+   * Called at the moment a frame is about to be opened, never when the query
+   * OBJECT is made: a cell whose Run fails before it ever steps must not end
+   * someone else's sequence for nothing.
+   *
+   * @internal
+   */
+  async supersede() {
+    const previous = this.#open;
+    this.#open = null;
+    if (!previous) return;
+    await previous.close({ superseded: true });
+    // Said only after the frame is actually gone, so a listener that starts a new
+    // query cannot race the close it was told about.
+    previous.onSuperseded?.();
+  }
+
+  /** @internal a query's frame is gone — exhausted, closed, or died with the engine. */
+  release(query) {
+    if (this.#open === query) this.#open = null;
+  }
+
+  /** @internal a query has just taken the session's one frame. */
+  hold(query) {
+    this.#open = query;
+  }
+
+  /** Take one cell's clauses back out. See unconsult() in session.js. */
+  async unconsult(name) {
+    return unconsult(this, name);
+  }
+
+  /**
+   * Throw the engine away and rebuild it from the consult log.
+   *
+   * Terminating is not a last resort here, it is the mechanism: it reclaims the
+   * whole WASM heap as well as the stuck goal, so a memory blow-up and an
+   * infinite loop have the same cure.
+   *
+   * A `:- dynamic` cell's assert/retract state does not survive this, which is
+   * already the documented behaviour of "restart engine and run all"
+   * (format §8) rather than a new surprise.
+   */
+  async restart() {
+    this.#teardown(new Error('aborted'));
+    // Every frame died with the worker, so nothing is holding the session's.
+    this.#open = null;
+    await this.start();
+    for (const { name, text } of this.log) {
+      await this.#send('consult', { text, name });
+    }
+  }
+
+  /**
+   * Stop whatever is running. Identical to restart() here, and named separately
+   * because the two are different intentions: one rescues a page, the other
+   * throws away assert/retract state deliberately.
+   */
+  async abort() {
+    return this.restart();
+  }
+
+  async close() {
+    this.#teardown(new Error('session closed'));
+  }
+
+  #spawn() {
+    // Classic, not module: swipl-wasm has no ESM entry, and importScripts is the
+    // only way to get its global. See the comment at the top of worker.js.
+    this.#worker = new Worker(this.workerUrl);
+    this.#worker.onmessage = ({ data }) => {
+      const entry = this.#pending.get(data.id);
+      if (!entry) return;
+      this.#pending.delete(data.id);
+      if (data.ok) entry.resolve(data.value);
+      else entry.reject(new Error(data.error));
+    };
+    this.#worker.onerror = (event) => {
+      this.#teardown(new Error(event.message ?? 'worker failed'));
+    };
+  }
+
+  #teardown(reason) {
+    this.#open = null;
+    this.#worker?.terminate();
+    this.#worker = null;
+    this.#booting = null;
+    // Anything still waiting will never hear back, so say so rather than leaving
+    // a promise dangling forever — a silent hang is what this whole change exists
+    // to remove.
+    for (const { reject } of this.#pending.values()) reject(reason);
+    this.#pending.clear();
+  }
+
+  #send(op, args = {}) {
+    if (!this.#worker) return Promise.reject(new Error('worker is not running'));
+    const id = this.#nextId++;
+    return new Promise((resolve, reject) => {
+      this.#pending.set(id, { resolve, reject });
+      this.#worker.postMessage({ id, op, ...args });
+    });
+  }
+
+  /** @internal */
+  send(op, args) {
+    return this.#send(op, args);
+  }
+}
+
+class WorkerQuery {
+  #qid = null;
+
+  constructor(session, goal) {
+    this.session = session;
+    this.goal = goal;
+    this.done = false;
+    // Ended by another query taking the session's one frame, rather than by its
+    // own search finishing. Kept apart from `done` because only one of the two
+    // may ever be written down as an exhausted search (format §6).
+    this.superseded = false;
+    /** Set by the caller to hear that its sequence was closed for another one. */
+    this.onSuperseded = null;
+  }
+
+  async #open() {
+    if (this.#qid === null) {
+      await this.session.start();
+      // Before the frame exists, never after: once a second query is open the
+      // first is no longer innermost and can never be closed at all.
+      await this.session.supersede();
+      this.#qid = await this.session.send('open', { goal: this.goal });
+      this.session.hold(this);
     }
-    session = PrologSession.create(globalThis.SWIPL, options);
+    return this.#qid;
   }
-  return session;
+
+  async next() {
+    if (this.done) return this.superseded ? { done: true, superseded: true } : { done: true };
+    const qid = await this.#open();
+    const result = await this.session.send('next', { qid });
+    // The worker forgets a query that reports done — swipl-wasm has closed it —
+    // so the frame is already back and nothing here needs to ask for it.
+    if (result.done) this.#finish();
+    return result;
+  }
+
+  async all(limit) {
+    if (this.done) return { solutions: [], truncated: false };
+    const qid = await this.#open();
+    this.#finish();
+    return this.session.send('all', { qid, limit });
+  }
+
+  async close({ superseded = false } = {}) {
+    if (superseded) this.superseded = true;
+    if (this.#qid === null || this.done) {
+      this.#finish();
+      return;
+    }
+    this.#finish();
+    await this.session.send('close', { qid: this.#qid });
+  }
+
+  #finish() {
+    this.done = true;
+    this.session.release(this);
+  }
+}
+
+let shared = null;
+
+/**
+ * Boot (once) and return the shared session for this page.
+ * @returns {Promise<WorkerSession>}
+ */
+export function createSession(options = {}) {
+  if (!shared) shared = new WorkerSession(options).start();
+  return shared;
 }

package/src/build-info.js

@@ -0,0 +1,103 @@
+// Which copy of this you are actually running.
+//
+// A version number answers "which release"; it does not answer "which of the
+// four things on this machine claiming to be 0.2.0". A published install, a
+// checkout with the branch still on it, and an npm-linked working copy with
+// uncommitted edits are three different programs, and a bug report against the
+// wrong one costs an afternoon.
+//
+// TWO STATES, NAMED, because they are not the same claim:
+//
+//   Built from commit ccf8e5b on 2026-08-30 14:32:51 UTC
+//   Working copy ccf8e5b (modified)
+//
+// The first is baked in by the release workflow just before publish — git exists
+// there and does not exist inside an installed package. The second is read from
+// git at run time, and says `(modified)` when the tree has edits, because a bare
+// SHA over a dirty tree names a program that nobody has.
+//
+// ONE DATE, AND IT IS THE BUILD'S. The commit's own date is not printed because
+// the hash already identifies it — anyone who wants it can ask git — and two
+// dates where one was asked for is noise dressed as rigour. A working copy has no
+// build time at all, which is why that state carries no date: there is nothing to
+// date yet.
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+
+/** Where prepack leaves the facts. Inside `src`, so `files` already ships it. */
+const BAKED = new URL('./build-info.json', import.meta.url);
+
+/**
+ * The provenance line, or null when nothing is known.
+ *
+ * Pure, so both states can be tested without a filesystem or a git repository.
+ *
+ * @param {{commit: string, built?: string, modified?: boolean}|null} info
+ * @returns {string|null}
+ */
+export function buildLine(info) {
+  if (!info?.commit) return null;
+  if (info.built) return `Built from commit ${info.commit} on ${info.built}`;
+  return `Working copy ${info.commit}${info.modified ? ' (modified)' : ''}`;
+}
+
+/**
+ * What this copy is, from whichever of the two sources exists.
+ *
+ * Null rather than a guess when neither does — a tarball built before any of
+ * this existed, or a source tree with no history. A line that says "unknown"
+ * three times is worse than no line.
+ *
+ * @returns {{commit: string, built?: string, modified?: boolean}|null}
+ */
+export function currentBuild() {
+  try {
+    const baked = JSON.parse(readFileSync(BAKED, 'utf8'));
+    if (baked?.commit) return baked;
+  } catch {
+    // No file, or a damaged one. Either way git is the better authority here.
+  }
+  return fromGit();
+}
+
+/**
+ * Ask git, which is only there in a working copy.
+ *
+ * `execFileSync` with fixed arguments and no shell. It costs about ten
+ * milliseconds and only ever runs in development, where the alternative is a
+ * command that cannot tell you which of your own commits it is.
+ */
+function fromGit() {
+  const root = new URL('..', import.meta.url);
+  const git = (...args) => execFileSync('git', ['-C', root.pathname, ...args], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+  }).trim();
+  try {
+    return {
+      commit: git('log', '-1', '--format=%h'),
+      modified: git('status', '--porcelain') !== '',
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The facts, as the release writes them. Exported so the script that runs at
+ * publish time and the code that reads the result agree on the shape.
+ *
+ * UTC, spelled out. A build stamp is read by whoever is holding the package,
+ * wherever they are, and a bare local time from someone else's machine says less
+ * than nothing.
+ *
+ * @param {{commit: string}} head
+ * @param {Date} [now]
+ * @returns {{commit: string, built: string}}
+ */
+export function bakedFrom(head, now = new Date()) {
+  return {
+    commit: head.commit,
+    built: `${now.toISOString().slice(0, 19).replace('T', ' ')} UTC`,
+  };
+}

package/src/build-info.json

@@ -0,0 +1,4 @@
+{
+  "commit": "82ab5c7",
+  "built": "2026-08-30 14:50:00 UTC"
+}

package/src/clauses.js

@@ -0,0 +1,236 @@
+// What does this program cell define?
+//
+// A deliberately shallow reading of Prolog source — clause heads only, no terms,
+// no operators, no module qualification. That is not laziness, it is the design:
+// the answer is only ever used to IMPROVE AN ERROR MESSAGE that the engine has
+// already produced. A head this misses costs a hint; a head it invents costs a
+// hint that is wrong about a predicate nobody asked about. Neither can change
+// what a query does, which is why a regex is an honest tool here and would not
+// be anywhere near the execution path.
+//
+// DOM-free and engine-free, like format.js: the same reading serves the browser,
+// the CLI runner and eventually the `:- dynamic` detection that 869eddzfp needs.
+
+/** `name` and `'quoted name'`, the two spellings of a functor. */
+const FUNCTOR = /^(?:'((?:[^'\\]|\\.)*)'|([a-z][a-zA-Z0-9_]*))/;
+
+/**
+ * The predicate indicators a cell defines, as `name/arity`.
+ *
+ * @param {string} source Prolog text
+ * @returns {Set<string>}
+ */
+export function definedPredicates(source) {
+  const found = new Set();
+  for (const line of clauseStarts(source)) {
+    const indicator = headOf(line);
+    if (indicator) found.add(indicator);
+  }
+  return found;
+}
+
+/**
+ * Lines that can begin a clause.
+ *
+ * A clause head starts at column 0 — the same rule the notebook format relies on
+ * for cells (format §1), and the reason both can be line scanners. Continuation
+ * lines of a clause body are indented by every convention in use, including
+ * SWI's own portray_clause.
+ */
+function clauseStarts(source) {
+  const lines = [];
+  let inBlockComment = false;
+  for (const raw of source.split('\n')) {
+    let line = raw;
+    if (inBlockComment) {
+      const end = line.indexOf('*/');
+      if (end === -1) continue;
+      line = line.slice(end + 2);
+      inBlockComment = false;
+    }
+    // A block comment opening on this line takes the rest of it with it.
+    const open = line.indexOf('/*');
+    if (open !== -1 && line.indexOf('*/', open) === -1) {
+      inBlockComment = true;
+      line = line.slice(0, open);
+    }
+    if (/^\s/.test(line) || line.trim() === '') continue;
+    if (line.startsWith('%')) continue;
+    // A directive is an instruction to the loader, not a definition. `:- dynamic
+    // counter/1.` declares one, but the clauses are still what define it.
+    if (line.startsWith(':-') || line.startsWith('?-')) continue;
+    lines.push(line);
+  }
+  return lines;
+}
+
+/**
+ * `foo(a, b) :- …` → `foo/2`. Null if the line does not start with a functor.
+ */
+function headOf(line) {
+  const m = FUNCTOR.exec(line);
+  if (!m) return null;
+  const name = m[1] !== undefined ? m[1].replace(/\\(.)/g, '$1') : m[2];
+  const rest = line.slice(m[0].length);
+
+  let arity = 0;
+  let after = rest;
+  if (rest.startsWith('(')) {
+    const args = countArguments(rest);
+    if (args === null) return null;
+    arity = args.count;
+    after = rest.slice(args.end + 1);
+  }
+
+  // A DCG rule defines a predicate with two extra arguments — the difference list
+  // SWI threads through it. `greeting --> [hello]` is greeting/2, and a reader
+  // told otherwise would go looking for greeting/0.
+  if (/^\s*-->/.test(after)) arity += 2;
+
+  return `${name}/${arity}`;
+}
+
+/**
+ * Count top-level arguments in `(…)`, respecting nesting and quotes.
+ *
+ * @returns {{count: number, end: number}|null} null if the parenthesis never closes
+ */
+function countArguments(text) {
+  let depth = 0;
+  let count = 1;
+  let quote = null;
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i];
+    if (quote) {
+      if (c === '\\') i++;
+      else if (c === quote) quote = null;
+      continue;
+    }
+    if (c === "'" || c === '"' || c === '`') { quote = c; continue; }
+    if (c === '(' || c === '[' || c === '{') { depth++; continue; }
+    if (c === ')' || c === ']' || c === '}') {
+      depth--;
+      if (depth === 0) return { count, end: i };
+      continue;
+    }
+    // `foo(a, b)` has two arguments; `foo()` is not valid Prolog, so a comma at
+    // depth 1 is always an argument separator.
+    if (c === ',' && depth === 1) count++;
+  }
+  return null;
+}
+
+/**
+ * The predicates a cell declares `:- dynamic`, as `name/arity`.
+ *
+ * WHY THIS IS WORTH KNOWING WITHOUT RUNNING ANYTHING (format §8): a cell that
+ * declares one is **stateful**. Its assert/retract state lives in no file, so
+ * re-consulting the cell does not undo it and neither does resetting the cell —
+ * only throwing the engine away does. That is the one place where the otherwise
+ * reliable promise "the clause store self-heals" stops being true, and a reader
+ * who does not know it will conclude something false about Prolog rather than
+ * about us.
+ *
+ * Read statically so the page can say so BEFORE the reader has asserted anything,
+ * rather than after they are already confused. Shallow like the rest of this file
+ * and for the same reason: at worst it fails to warn, and it can never change
+ * what a goal does.
+ *
+ * @param {string} source Prolog text
+ * @returns {Set<string>} predicate indicators
+ */
+export function declaredDynamic(source) {
+  const found = new Set();
+  for (const body of directives(source)) {
+    // `:- dynamic foo/1.` and `:- dynamic(foo/1).` are the same declaration.
+    const m = /^dynamic\b\s*(.*)$/s.exec(body);
+    if (!m) continue;
+    let list = m[1].trim();
+    if (list.startsWith('(') && list.endsWith(')')) list = list.slice(1, -1);
+    for (const item of splitTopLevel(list)) {
+      const indicator = /^\s*(?:'((?:[^'\\]|\\.)*)'|([a-z][a-zA-Z0-9_]*))\s*\/\s*(\d+)\s*$/.exec(item);
+      if (indicator) {
+        const name = indicator[1] !== undefined ? indicator[1].replace(/\\(.)/g, '$1') : indicator[2];
+        found.add(`${name}/${indicator[3]}`);
+      }
+    }
+  }
+  return found;
+}
+
+/**
+ * The body of every `:- …` directive, with comments stripped.
+ *
+ * Directives wrap across lines far more often than clauses do — a chapter that
+ * declares six dynamic predicates will list them one per line — so this cannot be
+ * the line scanner the rest of the file uses. It reads to the terminating full
+ * stop instead.
+ */
+function directives(source) {
+  const bodies = [];
+  const text = stripComments(source);
+  const pattern = /(^|\n)\s*:-\s*/g;
+  let m;
+  while ((m = pattern.exec(text)) !== null) {
+    const start = m.index + m[0].length;
+    const end = endOfTerm(text, start);
+    if (end === -1) break;
+    bodies.push(text.slice(start, end).trim());
+    pattern.lastIndex = end;
+  }
+  return bodies;
+}
+
+/** Index of the `.` that ends a term, skipping quotes. -1 if it never ends. */
+function endOfTerm(text, from) {
+  let quote = null;
+  for (let i = from; i < text.length; i++) {
+    const c = text[i];
+    if (quote) {
+      if (c === '\\') i++;
+      else if (c === quote) quote = null;
+      continue;
+    }
+    if (c === "'" || c === '"' || c === '`') { quote = c; continue; }
+    // A full stop ends a term only when whitespace or the end of input follows,
+    // which is exactly SWI's own rule — otherwise `1.5` would end one.
+    if (c === '.' && (i + 1 === text.length || /\s/.test(text[i + 1]))) return i;
+  }
+  return -1;
+}
+
+function stripComments(source) {
+  return source
+    .replace(/\/\*[\s\S]*?\*\//g, ' ')
+    .split('\n')
+    .map((line) => line.replace(/(^|\s)%.*$/, '$1'))
+    .join('\n');
+}
+
+/** Split on commas that are not inside brackets or quotes. */
+function splitTopLevel(text) {
+  const parts = [];
+  let depth = 0;
+  let quote = null;
+  let start = 0;
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i];
+    if (quote) {
+      if (c === '\\') i++;
+      else if (c === quote) quote = null;
+      continue;
+    }
+    if (c === "'" || c === '"' || c === '`') { quote = c; continue; }
+    if (c === '(' || c === '[' || c === '{') depth++;
+    else if (c === ')' || c === ']' || c === '}') depth--;
+    else if (c === ',' && depth === 0) { parts.push(text.slice(start, i)); start = i + 1; }
+  }
+  parts.push(text.slice(start));
+  return parts;
+}
+
+/** The predicate indicator an "Unknown procedure" error is complaining about. */
+export function unknownProcedure(message) {
+  const m = /Unknown procedure:\s*(?:[a-z][a-zA-Z0-9_]*:)?((?:'[^']*'|[^\s/]+)\/\d+)/.exec(message ?? '');
+  return m ? m[1] : null;
+}