beatrina 0.8.6

package/engines/js/persist.mjs

@@ -0,0 +1,214 @@
+// persist.mjs — make a chunk's top-level declarations outlive the chunk.
+//
+// A notebook runs chunk after chunk in ONE scope, and a chunk is re-run many
+// times. JavaScript's scripts fight both halves:
+//
+//   · top-level `let`/`const`/`class` in a classic script DO persist in the
+//     context — and re-running the chunk then throws "Identifier 'x' has already
+//     been declared". So the second Run of any chunk would fail.
+//   · a chunk that uses top-level `await` cannot be a classic script at all; it
+//     has to run inside an async function, where every declaration is LOCAL and
+//     vanishes when the chunk ends.
+//
+// The Node REPL solves both with an internal acorn pass that is not exported.
+// This is the smallest honest equivalent: a tokenizer that knows strings,
+// template literals (with nesting), comments and regular-expression literals,
+// and rewrites ONLY declarations at brace depth 0 —
+//
+//   let / const  →  var          (re-declarable; `var` persists in the context)
+//   class X {…}  →  var X = class X {…};
+//
+// and, in async mode, reports the names declared at depth 0 so the worker can
+// copy them to the context's global object when the chunk ends (finally). The
+// names of a destructuring declaration are collected too. What this does NOT
+// do, stated rather than discovered: `const` loses its immutability (as it
+// does in the REPL's own editor mode), and a name declared by destructuring
+// with a computed key is not collected.
+
+const ID_START = /[A-Za-z_$ -￿]/;
+const ID_PART = /[A-Za-z0-9_$ -￿]/;
+// After these tokens a `/` starts a regular expression, not a division.
+const REGEX_AFTER_WORDS = new Set(["return", "typeof", "instanceof", "in", "of", "new", "delete", "void", "throw", "case", "do", "else", "yield", "await"]);
+
+/**
+ * Tokenize enough of JavaScript to find declarations safely.
+ * @returns {Array<{type: "word"|"punct"|"string"|"template"|"regex"|"comment"|"space"|"number", text: string, start: number, depth: number}>}
+ */
+export function tokenize(src) {
+  const toks = [];
+  let i = 0;
+  let depth = 0;               // { } depth; parens and brackets do not change it
+  const templateStack = [];    // brace depth at which each `${` opened
+  let lastSignificant = null;
+  const push = (type, start, end) => {
+    const t = { type, text: src.slice(start, end), start, depth };
+    toks.push(t);
+    if (type !== "space" && type !== "comment") lastSignificant = t;
+  };
+  const regexAllowed = () => {
+    const t = lastSignificant;
+    if (!t) return true;
+    if (t.type === "word") return REGEX_AFTER_WORDS.has(t.text);
+    if (t.type === "number" || t.type === "string" || t.type === "template" || t.type === "regex") return false;
+    return !/^[)\]}]$/.test(t.text);
+  };
+  const readTemplate = (start) => {
+    // from just after ` or after the } that closes a ${ … }
+    let j = start;
+    while (j < src.length) {
+      if (src[j] === "\\") { j += 2; continue; }
+      if (src[j] === "`") return { end: j + 1, open: false };
+      if (src[j] === "$" && src[j + 1] === "{") return { end: j + 2, open: true };
+      j += 1;
+    }
+    return { end: src.length, open: false };
+  };
+  while (i < src.length) {
+    const c = src[i];
+    const start = i;
+    if (/\s/.test(c)) { while (i < src.length && /\s/.test(src[i])) i += 1; push("space", start, i); continue; }
+    if (c === "/" && src[i + 1] === "/") { while (i < src.length && src[i] !== "\n") i += 1; push("comment", start, i); continue; }
+    if (c === "/" && src[i + 1] === "*") { const e = src.indexOf("*/", i + 2); i = e < 0 ? src.length : e + 2; push("comment", start, i); continue; }
+    if (c === "'" || c === "\"") {
+      i += 1;
+      while (i < src.length && src[i] !== c && src[i] !== "\n") i += src[i] === "\\" ? 2 : 1;
+      i += 1; push("string", start, Math.min(i, src.length)); continue;
+    }
+    if (c === "`") {
+      const r = readTemplate(i + 1);
+      i = r.end;
+      push("template", start, i);
+      if (r.open) { templateStack.push(depth); depth += 1; }
+      continue;
+    }
+    if (c === "}" && templateStack.length && templateStack[templateStack.length - 1] === depth - 1) {
+      depth -= 1;
+      templateStack.pop();
+      const r = readTemplate(i + 1);
+      i = r.end;
+      push("template", start, i);
+      if (r.open) { templateStack.push(depth); depth += 1; }
+      continue;
+    }
+    if (c === "/" && regexAllowed()) {
+      i += 1;
+      let inClass = false;
+      while (i < src.length && src[i] !== "\n") {
+        if (src[i] === "\\") { i += 2; continue; }
+        if (src[i] === "[") inClass = true;
+        else if (src[i] === "]") inClass = false;
+        else if (src[i] === "/" && !inClass) break;
+        i += 1;
+      }
+      i += 1;
+      while (i < src.length && ID_PART.test(src[i])) i += 1;
+      push("regex", start, i); continue;
+    }
+    if (/[0-9]/.test(c) || (c === "." && /[0-9]/.test(src[i + 1] || ""))) {
+      while (i < src.length && /[0-9A-Za-z_.]/.test(src[i])) i += 1;
+      push("number", start, i); continue;
+    }
+    if (ID_START.test(c)) { while (i < src.length && ID_PART.test(src[i])) i += 1; push("word", start, i); continue; }
+    if (c === "{") { push("punct", start, i + 1); depth += 1; i += 1; continue; }
+    if (c === "}") { depth = Math.max(0, depth - 1); i += 1; push("punct", start, i); continue; }
+    const three = src.slice(i, i + 3);
+    const two = src.slice(i, i + 2);
+    const len = ["...", "===", "!==", "**=", "<<=", ">>=", "&&=", "||=", "??="].includes(three) ? 3
+      : ["=>", "==", "!=", "<=", ">=", "&&", "||", "??", "?.", "++", "--", "+=", "-=", "*=", "/=", "%=", "**"].includes(two) ? 2 : 1;
+    i += len;
+    push("punct", start, i);
+  }
+  return toks;
+}
+
+/** Identifiers bound by a destructuring pattern between `open` and its closer. */
+function patternNames(toks, open) {
+  const names = [];
+  let level = 0;
+  let k = open;
+  for (; k < toks.length; k += 1) {
+    const t = toks[k];
+    if (t.type === "space" || t.type === "comment") continue;
+    if (t.text === "{" || t.text === "[") level += 1;
+    else if (t.text === "}" || t.text === "]") { level -= 1; if (level === 0) break; }
+    else if (t.type === "word") {
+      const next = toks.slice(k + 1).find((x) => x.type !== "space" && x.type !== "comment");
+      const prev = [...toks.slice(0, k)].reverse().find((x) => x.type !== "space" && x.type !== "comment");
+      if (next && next.text === ":") continue;                    // a property key
+      if (prev && prev.text === "=") continue;                     // a default value's first word (approximation)
+      names.push(t.text);
+    }
+  }
+  return { names, end: k };
+}
+
+/**
+ * Rewrite a chunk so its top-level declarations persist and re-run cleanly.
+ * @returns {{code: string, names: string[]}} names declared at depth 0
+ */
+export function persistDeclarations(src) {
+  const toks = tokenize(src);
+  const edits = [];             // {at, remove, insert}
+  const names = new Set();
+  const significant = (from) => { for (let k = from; k < toks.length; k += 1) if (toks[k].type !== "space" && toks[k].type !== "comment") return k; return -1; };
+  const prevSignificant = (from) => { for (let k = from; k >= 0; k -= 1) if (toks[k].type !== "space" && toks[k].type !== "comment") return toks[k]; return null; };
+  for (let k = 0; k < toks.length; k += 1) {
+    const t = toks[k];
+    if (t.type !== "word" || t.depth !== 0) continue;
+    const prev = prevSignificant(k - 1);
+    // A declaration starts a statement: after `;`, `{`, `}`, at the start, or
+    // after a line break that ends a statement without a semicolon. Never
+    // `x.let`, never `for (let …` (its `(` is the previous token).
+    const newlineBefore = toks[k - 1] && toks[k - 1].type === "space" && toks[k - 1].text.includes("\n");
+    const atStatement = !prev || (prev.type === "punct" ? [";", "{", "}"].includes(prev.text) : newlineBefore);
+    if (!atStatement) continue;
+    if (t.text === "let" || t.text === "const" || t.text === "var") {
+      const n = significant(k + 1);
+      if (n < 0) continue;
+      const nt = toks[n];
+      // `let` followed by something that cannot start a binding is an identifier named let.
+      if (!(nt.type === "word" || nt.text === "{" || nt.text === "[")) continue;
+      if (t.text !== "var") edits.push({ at: t.start, remove: t.text.length, insert: "var" });
+      // Collect every binding of the declaration list at this level.
+      let m = n;
+      let paren = 0;
+      let expectBinding = true;
+      for (; m < toks.length; m += 1) {
+        const x = toks[m];
+        if (x.type === "space" || x.type === "comment") { if (paren === 0 && x.depth === 0 && /\n/.test(x.text) && !expectBinding) { const nx = significant(m + 1); if (nx < 0 || ![",", "=", "."].includes(toks[nx].text) && toks[nx].type === "word") break; } continue; }
+        if (x.depth > 0 && !(x.text === "{" && expectBinding)) continue;
+        if (expectBinding && paren === 0) {
+          if (x.type === "word") { names.add(x.text); expectBinding = false; continue; }
+          if (x.text === "{" || x.text === "[") { const p = patternNames(toks, m); p.names.forEach((nm) => names.add(nm)); m = p.end; expectBinding = false; continue; }
+        }
+        if (x.text === "(" || x.text === "[") paren += 1;
+        else if (x.text === ")" || x.text === "]") paren -= 1;
+        else if (paren === 0 && x.text === ",") expectBinding = true;
+        else if (paren === 0 && x.text === ";") break;
+      }
+      k = Math.max(k, n);
+    } else if (t.text === "class") {
+      const n = significant(k + 1);
+      if (n < 0 || toks[n].type !== "word" || toks[n].text === "extends") continue;
+      const name = toks[n].text;
+      // Find the class body's closing brace: the first `{` at depth 0 opens it.
+      let open = -1;
+      for (let m = n + 1; m < toks.length; m += 1) if (toks[m].text === "{" && toks[m].depth === 0) { open = m; break; }
+      if (open < 0) continue;
+      let close = -1;
+      for (let m = open + 1; m < toks.length; m += 1) if (toks[m].text === "}" && toks[m].depth === 0) { close = m; break; }
+      if (close < 0) continue;
+      edits.push({ at: t.start, remove: 0, insert: `var ${name} = ` });
+      edits.push({ at: toks[close].start + 1, remove: 0, insert: ";" });
+      names.add(name);
+    } else if (t.text === "function" || (t.text === "async" && toks[significant(k + 1)]?.text === "function")) {
+      let n = significant(k + 1);
+      if (t.text === "async") n = significant(n + 1);
+      if (n >= 0 && toks[n].text === "*") n = significant(n + 1);
+      if (n >= 0 && toks[n].type === "word") names.add(toks[n].text);
+    }
+  }
+  let code = src;
+  for (const e of edits.sort((a, b) => b.at - a.at)) code = code.slice(0, e.at) + e.insert + code.slice(e.at + e.remove);
+  return { code, names: [...names] };
+}

package/engines/js/worker.mjs

@@ -0,0 +1,424 @@
+// worker.mjs — the JavaScript engine: one Node process, one persistent scope.
+//
+// It speaks the wire spike/worker.R and engines/python/worker.py speak
+// (docs/worker-protocol.md): control frames on stdout behind the session's
+// sentinel, commands on stdin behind the command tag, Stop as SIGINT. The
+// host adapter is host/engine-js.mjs.
+//
+// Decisions, each with its reason:
+//
+//   · ONE vm CONTEXT for the session, not the worker's own globals, so a chunk
+//     that assigns `console` or `process.stdout.write` cannot take the wire down.
+//     The context still gets the real `process`, `require` (resolved from the
+//     working directory) and dynamic `import()` through Node's own loader —
+//     a notebook that cannot load a package is not a notebook.
+//   · DECLARATIONS PERSIST AND RE-RUN (engines/js/persist.mjs): top-level
+//     let/const/class become var-bound, and a chunk using top-level await runs
+//     in an async function whose declared names are copied out when it ends.
+//   · STOP KEEPS THE SESSION. `breakOnSigint` interrupts synchronous code
+//     (a tight loop) with the context intact — the host's group SIGINT reaches
+//     it exactly as it reaches R. An await in progress is abandoned: the chunk
+//     ends `interrupted` and a timer the user started keeps running in the
+//     background, as a promise cannot be cancelled. Code a timer runs LATER is
+//     outside any Stop; Force Stop ends the process.
+//   · WHAT A CHUNK SHOWS is its last expression, as R and IPython do: an array
+//     of plain objects is a table (the `dataframe` frame R's worker sends),
+//     `display.html/svg/table/text` are explicit, anything else is
+//     util.inspect. A Promise as the last value is awaited first.
+//   · SHARE/USE is the ONLY bridge between languages, and it is explicit:
+//     `share("name", rows)` writes a column table to the host's hand-off
+//     directory and R's `use("name")` reads it as a data.frame (and the other
+//     way). Numbers travel as JSON doubles with full precision.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import readline from "node:readline";
+import util from "node:util";
+import vm from "node:vm";
+import { createRequire } from "node:module";
+import { persistDeclarations } from "./persist.mjs";
+import { DocumentExecError, DocumentSetups, FEATURE } from "./document-exec.mjs";
+
+const SENTINEL = process.env.CARMAR_SENTINEL || "";
+const CMD_TAG = process.env.CARMAR_CMD_TAG || "";
+const HANDOFF_DIR = process.env.CARMAR_HANDOFF_DIR || "";
+const COMMANDS = ["exec", "wd", "doctor", "env", "rm", "parse", "complete"];
+const PREVIEW_ROWS = 200;
+const PREVIEW_COLS = 20;
+const CELL_CHARS = 160;
+const NAME_RE = /^[A-Za-z_][A-Za-z0-9_.]*$/;
+
+// ── the wire ─────────────────────────────────────────────────────────────────
+const realStdoutWrite = process.stdout.write.bind(process.stdout);
+// A setup chunk's output is hidden (knitr include = FALSE); the gate is how.
+const emitGate = { filter: null };
+function emit(frame) {
+  if (emitGate.filter && !emitGate.filter(frame)) return;
+  let body;
+  try {
+    body = JSON.stringify(frame, (_k, v) => (typeof v === "bigint" ? Number(v) : v));
+  } catch (e) {
+    body = JSON.stringify({ type: frame.type || "error", id: frame.id ?? null, error: `this engine produced a frame that is not JSON: ${e.message}` });
+  }
+  realStdoutWrite(`${SENTINEL}${body}\n`);
+}
+
+// ── the session ──────────────────────────────────────────────────────────────
+let current = null;               // { wire, interrupted, onInterrupt }
+const docs = new DocumentSetups();
+
+function text(kind, args) {
+  const line = util.formatWithOptions({ colors: false, depth: 4 }, ...args);
+  if (current) emit({ type: kind, id: current.wire, text: line });
+  else (kind === "stderr" ? process.stderr : process.stdout).write(`${line}\n`);
+}
+
+const sessionConsole = {
+  log: (...a) => text("stdout", a), info: (...a) => text("stdout", a), debug: (...a) => text("stdout", a),
+  warn: (...a) => text("stderr", a), error: (...a) => text("stderr", a),
+  dir: (v) => text("stdout", [util.inspect(v, { depth: 4 })]),
+  table: (v) => display.table(v),
+  time() {}, timeEnd() {}, group() {}, groupEnd() {},
+};
+
+/** A cell value → a short printable description, as R's safe_column does. */
+function cell(v) {
+  if (v === null || v === undefined) return null;
+  if (typeof v === "number") return Number.isFinite(v) ? v : null;
+  if (typeof v === "boolean") return v;
+  if (typeof v === "bigint") return Number(v);
+  if (typeof v === "string") return v.length > CELL_CHARS ? `${v.slice(0, CELL_CHARS - 1)}…` : v;
+  if (v instanceof Date) return v.toISOString();
+  return `<${Array.isArray(v) ? `Array(${v.length})` : (v.constructor && v.constructor.name) || "Object"}>`;
+}
+
+const isPlainRow = (r) => r !== null && typeof r === "object" && !Array.isArray(r) && !(r instanceof Date);
+function isTable(v) {
+  if (!Array.isArray(v) || v.length === 0) return false;
+  return v.slice(0, PREVIEW_ROWS).every(isPlainRow);
+}
+/** A columns object {a: [...], b: [...]} with equal lengths → rows. */
+function columnsToRows(obj) {
+  const keys = Object.keys(obj);
+  if (!keys.length || !keys.every((k) => Array.isArray(obj[k]))) return null;
+  const n = obj[keys[0]].length;
+  if (!keys.every((k) => obj[k].length === n)) return null;
+  return Array.from({ length: n }, (_x, i) => Object.fromEntries(keys.map((k) => [k, obj[k][i]])));
+}
+
+function tableFrame(rows, source) {
+  const names = [];
+  for (const r of rows.slice(0, PREVIEW_ROWS)) for (const k of Object.keys(r)) if (!names.includes(k)) names.push(k);
+  const shownNames = names.slice(0, PREVIEW_COLS);
+  const shown = rows.slice(0, PREVIEW_ROWS);
+  const types = shownNames.map((k) => {
+    const vals = shown.map((r) => r[k]).filter((x) => x !== null && x !== undefined);
+    if (vals.length && vals.every((x) => typeof x === "number" || typeof x === "bigint")) return "numeric";
+    if (vals.length && vals.every((x) => typeof x === "boolean")) return "logical";
+    return "character";
+  });
+  return {
+    type: "dataframe", id: current ? current.wire : null,
+    columns: shownNames, types, nrow: rows.length, ncol: names.length,
+    shown: shown.length, shownCols: shownNames.length,
+    truncated: rows.length > shown.length || names.length > shownNames.length,
+    ...(source ? { source } : {}),
+    rows: shown.map((r) => Object.fromEntries(shownNames.map((k) => [k, cell(r[k])]))),
+  };
+}
+
+function show(value, source = null) {
+  if (value === undefined) return;
+  if (isTable(value)) return emit(tableFrame(value, source));
+  text("stdout", [util.inspect(value, { depth: 4, colors: false, maxArrayLength: 100, breakLength: 100 })]);
+}
+
+const display = Object.assign((v) => show(v), {
+  table(v) {
+    const rows = Array.isArray(v) ? v : (v && typeof v === "object" ? columnsToRows(v) : null);
+    if (!rows || !isTable(rows)) throw new TypeError("display.table() takes an array of row objects or an object of equal-length columns.");
+    emit(tableFrame(rows, null));
+  },
+  html(html) {
+    emit({ type: "widget", id: current ? current.wire : null, kind: "html", class: "html", html: String(html) });
+  },
+  svg(svg, { width = 672, height = 480 } = {}) {
+    emit({ type: "plot", id: current ? current.wire : null, mime: "image/svg+xml", width, height, res: 96, data: String(svg) });
+  },
+  text(v) { text("stdout", [String(v)]); },
+});
+
+// ── share / use ──────────────────────────────────────────────────────────────
+function handoffPath(name) {
+  if (!HANDOFF_DIR) throw new Error("share()/use() need the Beatrina host's hand-off directory; this worker was started without one.");
+  if (typeof name !== "string" || !NAME_RE.test(name)) throw new TypeError("A shared name is letters, digits, dots and underscores, starting with a letter or underscore.");
+  return path.join(HANDOFF_DIR, `${name}.json`);
+}
+function share(a, b) {
+  // share(name, value) or share(value, name): whichever order the author reaches for.
+  const [name, value] = typeof a === "string" ? [a, b] : [b, a];
+  const rows = Array.isArray(value) ? value : (value && typeof value === "object" ? columnsToRows(value) : null);
+  if (!rows || !(rows.length === 0 || isTable(rows))) throw new TypeError("share(name, value) takes an array of row objects or an object of equal-length columns.");
+  const columns = [];
+  for (const r of rows) for (const k of Object.keys(r)) if (!columns.includes(k)) columns.push(k);
+  const data = Object.fromEntries(columns.map((k) => [k, rows.map((r) => {
+    const v = r[k];
+    if (v === undefined || v === null) return null;
+    if (typeof v === "number") return Number.isFinite(v) ? v : null;
+    if (v instanceof Date) return v.toISOString();
+    return typeof v === "object" ? JSON.stringify(v) : v;
+  })]));
+  const file = handoffPath(name);
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify({ format: "beatrix-columns-v1", name, from: "js", columns, data }), { mode: 0o600 });
+  fs.renameSync(tmp, file);
+  return undefined;
+}
+function use(name) {
+  const file = handoffPath(name);
+  if (!fs.existsSync(file)) throw new Error(`Nothing has been shared as "${name}" in this session. Share it first with share("${name}", …) in JavaScript or share(${name}) in R.`);
+  const rec = JSON.parse(fs.readFileSync(file, "utf8"));
+  if (rec.format !== "beatrix-columns-v1") throw new Error(`"${name}" is not a Beatrina hand-off table.`);
+  const n = rec.columns.length ? rec.data[rec.columns[0]].length : 0;
+  return Array.from({ length: n }, (_x, i) => Object.fromEntries(rec.columns.map((k) => [k, rec.data[k][i]])));
+}
+
+// ── the context ──────────────────────────────────────────────────────────────
+const sandbox = {
+  console: sessionConsole, display, share, use, process,
+  setTimeout, clearTimeout, setInterval, clearInterval, setImmediate, clearImmediate, queueMicrotask, structuredClone,
+  fetch, URL, URLSearchParams, TextEncoder, TextDecoder, Buffer, AbortController, AbortSignal, performance,
+  crypto: globalThis.crypto, Blob, atob, btoa,
+};
+Object.defineProperty(sandbox, "require", {
+  get: () => createRequire(path.join(process.cwd(), "__beatrina_chunk__.js")), enumerable: false, configurable: true,
+});
+const context = vm.createContext(sandbox, { name: "Beatrina JavaScript session" });
+const BUILTINS = new Set([...Object.getOwnPropertyNames(vm.runInContext("globalThis", context)), "require"]);
+const userNames = () => Object.getOwnPropertyNames(vm.runInContext("globalThis", context)).filter((k) => !BUILTINS.has(k));
+
+const INTERRUPTED = Symbol("interrupted");
+process.on("SIGINT", () => {
+  // Idle: nothing to stop (the host's ladder may send one after a run ended).
+  if (current && !current.interrupted) { current.interrupted = true; if (current.onInterrupt) current.onInterrupt(); }
+});
+
+/** Evaluate one chunk in the session. @returns {"ok"|"error"|"interrupted"} */
+async function evaluate(source, wire, srcname) {
+  current = { wire, interrupted: false, onInterrupt: null, failure: null };
+  const run = current;
+  const filename = path.join(process.cwd(), `${srcname && NAME_RE.test(srcname) ? srcname : "chunk"}.js`);
+  const opts = { filename, importModuleDynamically: vm.constants.USE_MAIN_CONTEXT_DEFAULT_LOADER };
+  const { code, names } = persistDeclarations(source);
+  let script;
+  let asyncMode = false;
+  try {
+    script = new vm.Script(code, opts);
+  } catch (e) {
+    if (e instanceof SyntaxError && /await is only valid/.test(e.message)) {
+      asyncMode = true;
+      const copy = names.map((n) => `try { globalThis[${JSON.stringify(n)}] = ${n}; } catch {}`).join(" ");
+      try { script = new vm.Script(`(async () => { try {\n${code}\n} finally { ${copy} } })()`, { ...opts, lineOffset: -1 }); } catch (e2) { return fail(run, e2); }
+    } else return fail(run, e);
+  }
+  try {
+    let value = script.runInContext(context, { breakOnSigint: true, displayErrors: false });
+    if (value && typeof value.then === "function") {
+      value = await new Promise((resolve, reject) => {
+        run.onInterrupt = () => resolve(INTERRUPTED);
+        if (run.interrupted) resolve(INTERRUPTED);
+        value.then(resolve, reject);
+      });
+      if (value === INTERRUPTED) return "interrupted";
+    }
+    if (run.interrupted) return "interrupted";
+    if (!asyncMode) {
+      const last = source.trim().split("\n").pop().trim().replace(/;$/, "");
+      show(value, /^[A-Za-z_$][\w$]*$/.test(last) ? last : null);
+    }
+    return "ok";
+  } catch (e) {
+    if (e && e.code === "ERR_SCRIPT_EXECUTION_INTERRUPTED") return "interrupted";
+    return fail(run, e);
+  }
+}
+
+function fail(run, e) {
+  const headline = e && e.name ? `${e.name}: ${e.message}` : String(e);
+  run.failure = headline;
+  const stack = e && typeof e.stack === "string" ? e.stack.split("\n").filter((l) => !/node:internal|engines[\\/]js[\\/]worker\.mjs/.test(l)).join("\n") : headline;
+  const m = e && typeof e.stack === "string" ? e.stack.match(/\.js:(\d+)(?::\d+)?\)?\s*$/m) : null;
+  emit({ type: "stderr", id: run.wire, text: stack });
+  emit({ type: "traceback", id: run.wire, message: headline, line: m ? Number(m[1]) : null, call: e && e.name ? e.name : "Error", frames: [] });
+  return "error";
+}
+
+// ── commands ─────────────────────────────────────────────────────────────────
+async function exec(cmd) {
+  const wire = cmd.id;
+  const source = typeof cmd.source === "string" ? cmd.source : (typeof cmd.code === "string" ? cmd.code : null);
+  const doneFrame = (fields) => { current = null; emit({ type: "done", id: wire, cwd: process.cwd(), ...fields }); };
+  if (source === null) return doneFrame({ status: "error", message: "no source" });
+  const engine = cmd.engine == null ? "js" : String(cmd.engine).toLowerCase();
+  if (!["js", "javascript", "node"].includes(engine)) {
+    return doneFrame({ status: "error", message: `This engine runs JavaScript; it was asked to run a ${cmd.engine} chunk.` });
+  }
+  const lines = source.split("\n").length;
+  if (cmd.document == null) {
+    emit({ type: "progress", id: wire, index: 1, total: 1, line: 1, end: lines });
+    const status = await evaluate(source, wire, cmd.srcname);
+    return doneFrame({ status, message: status === "interrupted" ? "Execution interrupted" : (current && current.failure) || null });
+  }
+  const done = { status: "ok", message: null, setup: null, cacheHit: false, effectiveOptions: null };
+  let plan;
+  try { plan = docs.plan(source, cmd.document); } catch (e) {
+    if (e instanceof DocumentExecError) return doneFrame({ ...done, status: "error", message: e.message });
+    throw e;
+  }
+  done.execution = plan.execution;
+  if (plan.runSetup) {
+    docs.setupStarted(plan.docId);
+    const report = { source: plan.setupSource, srcname: plan.setupSrcname, status: "running" };
+    emit({ type: "setup", id: wire, ...report });
+    emit({ type: "progress", id: wire, index: 1, total: 1, line: 1, end: plan.setupSource.split("\n").length, phase: "setup" });
+    // knitr include = FALSE: the setup's output is hidden, its failure is not.
+    const status = await withHiddenOutput(() => evaluate(plan.setupSource, wire, plan.setupSrcname));
+    const why = current && current.failure;
+    if (status !== "ok") {
+      docs.setupFailed(plan.docId, plan.setupSource);
+      report.status = status;
+      return doneFrame({ ...done, status, setup: report, message: `Setup chunk failed; dependent chunk was not run. ${why || `Chunk ${status}`}` });
+    }
+    docs.setupOk(plan.docId, plan.setupSource);
+    report.status = "ok";
+    done.setup = report;
+  } else if (plan.setupSource === null) {
+    docs.noSetup(plan.docId);
+  }
+  if (plan.runChunk) {
+    emit({ type: "progress", id: wire, index: 1, total: 1, line: 1, end: lines });
+    done.status = await evaluate(source, wire, cmd.srcname);
+    done.message = done.status === "interrupted" ? "Execution interrupted" : (current && current.failure) || null;
+  }
+  return doneFrame(done);
+}
+
+/** Run with stdout/table/html frames suppressed; stderr and tracebacks pass. */
+async function withHiddenOutput(fn) {
+  const hidden = new Set(["stdout", "dataframe", "widget", "plot"]);
+  const original = emitGate.filter;
+  emitGate.filter = (f) => !hidden.has(f.type);
+  try { return await fn(); } finally { emitGate.filter = original; }
+}
+
+function describe(name) {
+  const v = context[name];
+  const kind = typeof v === "function" ? "function" : isTable(v) ? "data" : "value";
+  const cls = v === null ? "null" : Array.isArray(v) ? "Array" : typeof v === "object" ? (v.constructor && v.constructor.name) || "Object" : typeof v;
+  const summary = kind === "data" ? `${v.length} rows of ${Object.keys(v[0]).length} fields`
+    : kind === "function" ? `function(${(String(v).match(/^[^(]*\(([^)]*)\)/) || [0, ""])[1]})`
+      : util.inspect(v, { depth: 0, breakLength: Infinity, maxArrayLength: 5, maxStringLength: 60 }).slice(0, 120);
+  const base = { name, class: cls, dims: Array.isArray(v) ? String(v.length) : "1", bytes: null, summary, kind };
+  return kind === "data" ? { ...base, nrow: v.length, ncol: Object.keys(v[0]).length } : base;
+}
+
+function complete(line, cursor) {
+  const upto = line.slice(0, cursor);
+  const m = upto.match(/([A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*)\.?([A-Za-z_$][\w$]*)?$/);
+  if (!m) return { start: cursor, end: cursor, token: "", items: [], truncated: false };
+  const dotted = upto.endsWith(".") ? `${m[1]}.` : m[0];
+  const parts = dotted.split(".");
+  const prefix = parts.pop();
+  let target = vm.runInContext("globalThis", context);
+  for (const p of parts) {
+    // Property reads only — never a call. A getter can still run, as in the REPL.
+    try { target = target == null ? undefined : target[p]; } catch { target = undefined; }
+  }
+  const keys = new Set();
+  for (let o = target; o != null && keys.size < 2000; o = Object.getPrototypeOf(o)) {
+    for (const k of Object.getOwnPropertyNames(o)) if (k.startsWith(prefix) && !/^__/.test(k)) keys.add(k);
+    if (o === Object.prototype) break;
+  }
+  const all = [...keys].sort();
+  const items = all.slice(0, 200).map((k) => {
+    let v;
+    try { v = target[k]; } catch { v = undefined; }
+    return { value: k, kind: typeof v === "function" ? "function" : "variable", detail: "" };
+  });
+  return { start: cursor - prefix.length, end: cursor, token: prefix, items, truncated: all.length > 200 };
+}
+
+async function dispatch(cmd) {
+  const wire = cmd.id;
+  switch (cmd.type) {
+    case "exec": return exec(cmd);
+    case "wd":
+      if (typeof cmd.path === "string" && cmd.path) { try { process.chdir(cmd.path); } catch (e) { return emit({ type: "wd", id: wire, path: process.cwd(), error: e.message }); } }
+      return emit({ type: "wd", id: wire, path: process.cwd() });
+    case "doctor":
+      return emit({ type: "doctor", id: wire, language: "javascript", version: process.version, executable: process.execPath, platform: `${os.type()} ${os.release()} ${process.arch}`, cwd: process.cwd(), handoff: HANDOFF_DIR || null });
+    case "env":
+      return emit({ type: "env", id: wire, objects: userNames().map(describe) });
+    case "rm": {
+      const names = Array.isArray(cmd.names) ? cmd.names : (typeof cmd.name === "string" ? [cmd.name] : []);
+      for (const n of names) if (typeof n === "string" && !BUILTINS.has(n)) delete context[n];
+      return emit({ type: "rm", id: wire, removed: names });
+    }
+    case "parse": {
+      let complete_ = true;
+      let error = null;
+      try { new vm.Script(persistDeclarations(String(cmd.source || "")).code); } catch (e) {
+        if (/Unexpected end of input|Unterminated/.test(e.message)) complete_ = false; else if (!/await is only valid/.test(e.message)) error = e.message;
+      }
+      return emit({ type: "parse", id: wire, complete: complete_, error });
+    }
+    case "complete":
+      return emit({ type: "complete", id: wire, ...complete(String(cmd.line || ""), Number.isInteger(cmd.cursor) ? cmd.cursor : String(cmd.line || "").length) });
+    default:
+      return undefined;              // unknown: silent, as worker.R's dispatch chain is
+  }
+}
+
+// ── the reader and the queue ─────────────────────────────────────────────────
+const queue = [];
+let pumping = false;
+async function pump() {
+  if (pumping) return;
+  pumping = true;
+  while (queue.length) {
+    const cmd = queue.shift();
+    try { await dispatch(cmd); } catch (e) {
+      if (cmd.type === "exec") { current = null; emit({ type: "done", id: cmd.id, status: "error", message: `${e.name}: ${e.message}`, cwd: process.cwd() }); }
+      else if (cmd.id != null) emit({ type: cmd.type, id: cmd.id, error: `${e.name}: ${e.message}` });
+    }
+  }
+  pumping = false;
+}
+
+function accept(line) {
+  let body = line.trim();
+  if (!body) return;
+  const tag = CMD_TAG ? `#${CMD_TAG} ` : "";
+  if (tag && body.startsWith(tag)) body = body.slice(tag.length);
+  else if (tag && body.startsWith("#")) return;
+  let cmd;
+  try { cmd = JSON.parse(body); } catch { return; }
+  if (!cmd || typeof cmd !== "object" || Array.isArray(cmd) || typeof cmd.type !== "string") return;
+  if (cmd.type === "cmdfile") {
+    try { cmd = JSON.parse(fs.readFileSync(cmd.path, "utf8")); } catch { return; } finally { try { fs.unlinkSync(cmd.path); } catch { /* taken */ } }
+    if (!cmd || typeof cmd.type !== "string") return;
+  }
+  if (cmd.type === "shutdown") { process.exit(0); }
+  if (cmd.type === "interrupt") { process.emit("SIGINT"); return; }
+  queue.push(cmd);
+  pump();
+}
+
+readline.createInterface({ input: process.stdin, crlfDelay: Infinity }).on("line", accept).on("close", () => process.exit(0));
+
+emit({
+  type: "ready", pid: process.pid, language: "js", language_version: process.versions.node,
+  engines: ["js"], executable: process.execPath, cwd: process.cwd(), home: os.homedir(), libs: [],
+  mode: "batch", features: [FEATURE], commands: COMMANDS, handoff: Boolean(HANDOFF_DIR),
+});