@polycode-projects/the-mechanical-code-talker 2.9.0 → 2.9.4

package/src/services/fold.mjs

@@ -7,11 +7,14 @@
 // The cleaning rules themselves are pure and live in domain/memory/fold.mjs;
 // everything that touches the filesystem or the store lives here.
 
-import { mkdir, readdir, readFile, rename, writeFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
 import { SESSIONS_DIR_REL, parseSessionJsonl, parseSessionLog } from "./sessions.mjs";
 import { removeBlock, saveBlock } from "../adapters/memory/blocks.mjs";
-import { CANONICALISED_FROM_PROP, FACT_CLASS, appendFacts, loadMemory, readFactRows, resolveMemoryGraphFile } from "../adapters/memory/core.mjs";
+import {
+  FACT_CLASS, appendCanonicalisedFromEdges, appendFacts, loadMemory,
+  openConfiguredMemoryBackend, readFactRows,
+} from "../adapters/memory/core.mjs";
 import { cleanSessionText } from "../domain/memory/fold.mjs";
 import { syllogise } from "../domain/syllogise.mjs";
 
@@ -24,38 +27,15 @@ const LOG_DIR_REL = ".tmct";
 // talking; we know exactly what the session touched). They are offline, $0,
 // best-effort side effects: a failure NEVER fails the fold.
 
-/** Atomic JSON write of the memory graph (temp-in-dir + rename), used here
- *  only to add mgx:canonicalisedFrom edges. */
-async function writeMemoryGraph(repoDir, payload) {
-  const file = resolveMemoryGraphFile(repoDir);
-  await mkdir(dirname(file), { recursive: true });
-  const tmp = `${file}.tmp-${process.pid}-${Math.random().toString(36).slice(2, 10)}`;
-  await writeFile(tmp, JSON.stringify(payload));
-  await rename(tmp, file);
-}
-
-/** Add mgx:canonicalisedFrom edges (Fact → Utterance) into the payload, deduped
- *  by (subject,object) so a re-fold is idempotent — never duplicates a link. */
-function addCanonicalisedFromEdges(payload, links) {
-  let group = payload.objectProperties.find((g) => g?.prop === CANONICALISED_FROM_PROP);
-  if (!group) {
-    group = { predicate: "canonicalisedFrom", prop: CANONICALISED_FROM_PROP, count: 0, examples: [] };
-    payload.objectProperties.push(group);
-  }
-  for (const l of links) {
-    group.examples = group.examples.filter((e) => !(e?.subject === l.factId && e?.object === l.uttId));
-    group.examples.push({ subject: l.factId, object: l.uttId, subjectLabel: l.factLabel, objectLabel: l.uttLabel });
-  }
-  group.count = group.examples.length;
-}
-
 /** CANONISE + LINK, never replace: for each Fact whose provenance names a
  *  `ace:chat:<sessionId>@<ts>` utterance, add an mgx:canonicalisedFrom edge
- *  Fact -> Utterance (the utterance itself is left verbatim). Returns
- *  { linked, focus } — `focus` seeds the speculative pass below. */
-async function canoniseLinkSession(repoDir, sessionId) {
+ *  Fact -> Utterance (the utterance itself is left verbatim). `memoryDir` is
+ *  the already-opened store handle — the write goes through the store seam,
+ *  never a direct graph-file write. Returns { linked, focus } — `focus` seeds
+ *  the speculative pass below. */
+async function canoniseLinkSession(memoryDir, sessionId) {
   const focus = new Set();
-  const memory = await loadMemory(repoDir);
+  const memory = await loadMemory(memoryDir);
   const individuals = memory.individuals || [];
   if (!individuals.length) return { linked: [], focus };
   const uttById = new Map(individuals.filter((i) => i?.class === "Utterance").map((i) => [i.id, i]));
@@ -80,24 +60,28 @@ async function canoniseLinkSession(repoDir, sessionId) {
       links.push({ factId: r.id, factLabel: factById.get(r.id)?.label || r.id, uttId, uttLabel: utt.label || uttId });
     }
   }
-  if (links.length) {
-    addCanonicalisedFromEdges(memory, links);
-    await writeMemoryGraph(repoDir, memory);
-  }
+  if (links.length) await appendCanonicalisedFromEdges(memoryDir, links);
   return { linked: links, focus };
 }
 
-/** The fold-time idle pass (best-effort): canonise-link each folded session,
- *  then run one bounded speculative pass scoped to the union footprint (empty
- *  footprint -> skipped). Never throws — must never fail a fold. */
+/** The fold-time idle pass (best-effort): open the repo's configured memory
+ *  backend once (the fold only ever has the repo path in hand — its callers
+ *  are file-level), canonise-link each folded session through it, then run one
+ *  bounded speculative pass scoped to the union footprint (empty footprint ->
+ *  skipped). Never throws — must never fail a fold. */
 async function speculateOverSessions(repoDir, sessionIds) {
   try {
-    const focus = new Set();
-    for (const sid of sessionIds) {
-      const { focus: f } = await canoniseLinkSession(repoDir, sid);
-      for (const t of f) focus.add(t);
+    const { dir: memoryDir, close } = await openConfiguredMemoryBackend(repoDir);
+    try {
+      const focus = new Set();
+      for (const sid of sessionIds) {
+        const { focus: f } = await canoniseLinkSession(memoryDir, sid);
+        for (const t of f) focus.add(t);
+      }
+      if (focus.size) await syllogise(memoryDir, { focus, store: { loadMemory, readFactRows, appendFacts } });
+    } finally {
+      await close();
     }
-    if (focus.size) await syllogise(repoDir, { focus, store: { loadMemory, readFactRows, appendFacts } });
   } catch { /* offline best-effort: a fold never fails on the speculative pass */ }
 }
 

package/src/services/import-file.mjs

@@ -13,7 +13,7 @@ import { readFile } from "node:fs/promises";
 import { basename, resolve } from "node:path";
 
 import { runTurn, uuidv7 } from "./chat.mjs";
-import { loadMemory, readFactRows, appendFact, openMemoryBackend } from "../adapters/memory/core.mjs";
+import { loadMemory, readFactRows, appendFact, openConfiguredMemoryBackend } from "../adapters/memory/core.mjs";
 import { loadConfig } from "../adapters/config.mjs";
 import { splitSentencesPreservingPaths } from "./sentences.mjs";
 
@@ -25,7 +25,7 @@ import { splitSentencesPreservingPaths } from "./sentences.mjs";
  *   comments: number, report: string
  * }>}
  */
-export async function importDefinitionFile(repoRoot, filePath, { env = process.env } = {}) {
+export async function importDefinitionFile(repoRoot, filePath, { env = process.env, memoryDir: injectedMemoryDir = null } = {}) {
   const root = resolve(repoRoot);
   const abs = resolve(root, filePath);
   const sourceTag = `import:${basename(abs)}`;
@@ -36,10 +36,11 @@ export async function importDefinitionFile(repoRoot, filePath, { env = process.e
   const body = lines.filter((l) => !l.trim().startsWith("#")).join("\n");
   const sentences = splitSentencesPreservingPaths(body);
 
-  const { loadTomlConfig } = await import("../adapters/toml-config.mjs");
-  const raw = await loadTomlConfig(root).catch(() => null);
-  const backend = String(raw?.memory?.backend || "default").trim().toLowerCase();
-  const { dir: memoryDir, close } = await openMemoryBackend(root, backend);
+  // An injected handle (a caller mid-session, or a build script pinned to the
+  // in-memory backend) is used as-is and left open — the caller owns it.
+  const opened = injectedMemoryDir ? null : await openConfiguredMemoryBackend(root, env);
+  const memoryDir = injectedMemoryDir ?? opened.dir;
+  const close = opened ? opened.close : async () => {};
   const config = loadConfig(env, root);
 
   const taught = [];

package/src/services/init.mjs

@@ -122,10 +122,10 @@ ${seed.limit != null ? `limit = ${Number(seed.limit)}` : "# limit = 500"}
 [memory]
 # Storage backend for taught facts + the memory graph.
 # Precedence: --memory-backend flag > TMCT_MEMORY_BACKEND env > this file >
-# "default" (the built-in fallback).
-#   "default" — the flat OWL-labelled JSON file under .tmct/memory/. The default.
+# sqlite (the built-in default).
+#   "sqlite"  — a local SQLite file at .tmct/memory/graph.sqlite. The default.
 #   "memory"  — in-process only; nothing written to disk (a library caller's option).
-#   "sqlite"  — a local SQLite file at .tmct/memory/graph.sqlite.
+#   "default" — same as leaving this unset: the sqlite default applies.
 backend = ${JSON.stringify(config.memory.backend)}
 `;
   }
@@ -277,9 +277,14 @@ export async function initRepo(dir, { force = false, seed, env = process.env, pe
     if (backendChoice === "memory") {
       seedNote = "seed skipped (memory backend is in-process only — nothing would persist past this command)";
     } else {
-      const { openMemoryBackend } = await import("../adapters/memory/core.mjs");
-      const { dir: memoryDir, close: closeMemoryStore } = await openMemoryBackend(root, backendChoice);
+      // The open itself sits inside the failure-tolerant try: an unopenable
+      // store (e.g. a directory squatting on graph.sqlite's path) degrades to
+      // an initialised-but-unseeded repo exactly like a broken corpus does.
+      let closeMemoryStore = async () => {};
       try {
+        const { openMemoryBackend } = await import("../adapters/memory/core.mjs");
+        const { dir: memoryDir, close } = await openMemoryBackend(root, backendChoice);
+        closeMemoryStore = close;
         const { resolveExtensions, seedActiveCorpusEntries } = await import("./extensions.mjs");
         const { entries } = await resolveExtensions(root);
         // `[seed] limit` caps the tier-1 ConceptNet band specifically (SEON is small

package/src/services/ledger-viz.mjs

@@ -536,28 +536,17 @@ export function renderLedgerHtml({ rows, terms, edges, focus, contradictions, wo
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>${escapeHtml(title)}</title>
 <!--
-  Import map: resolves the "wink-nlp"/"wink-eng-lite-web-model" bare specifiers the
-  live ask-and-teach dock's own dynamic import() needs (pinned to the exact versions
-  package.json depends on) to esm.sh CDN builds — the same seam chat.html and
-  plan.html each wire up for their own live sessions, mirrored here because this page
-  can be opened standalone (no import map inherited from a host document; this
-  includes the self-contained file tmct viz writes to disk — a plain cross-origin
-  dynamic import() of a remote https:// URL, not a file:// read, so it works the
-  same way offline this page's own try/catch already handles for the deployed site:
-  the fetch fails and the wink tier degrades gracefully). Nothing in this file
-  touches wink-nlp directly — wink-model.mjs's own header explains why a static
-  import would drag the ~1 MB model into every bundle; only the page's own inline
-  script performs this CDN import, the same bounded-race tryLoadWink() pattern
-  public/tmct-browser.mjs uses.
+  The wink lemma/POS tier loads from ./vendor/wink.js — the site's own shared
+  first-party bundle of wink-nlp + wink-eng-lite-web-model (built by
+  scripts/build-wink-vendor.mjs), one cached copy shared with chat.html and
+  plan.html, no CDN. A copy of this page opened somewhere without the sibling
+  asset (the self-contained file tmct viz writes to disk, say) just fails that
+  one import and this page's own try/catch degrades the wink tier gracefully.
+  Nothing in this file touches wink directly — wink-model.mjs's own header
+  explains why a static import would drag the ~1 MB model into every bundle;
+  only the page's own inline script performs the import, the same bounded-race
+  tryLoadWink() pattern public/tmct-browser.mjs uses.
 -->
-<script type="importmap">
-{
-  "imports": {
-    "wink-nlp": "https://esm.sh/wink-nlp@2.4.0",
-    "wink-eng-lite-web-model": "https://esm.sh/wink-eng-lite-web-model@1.8.1"
-  }
-}
-</script>
 <style>
 ${THEME_TOKENS_CSS}
   html { background: var(--bg); }
@@ -723,6 +712,10 @@ ${ledgerBundleAvailable ? `<script src="./ledger-browser.bundle.js"></script>` :
 <script>
 (function () {
   "use strict";
+  // Best-effort: a copy of this page opened without the sibling worker file
+  // (the CLI's own tmct viz output, a file:// open) just swallows the
+  // registration failure and works exactly as before.
+  if ("serviceWorker" in navigator) navigator.serviceWorker.register("./tmct-sw.js").catch(() => {});
   const DAY = 86400000;
   const facetCounts = ${facetCounts.toString()};
   const el = (id) => document.getElementById(id);
@@ -996,12 +989,12 @@ ${ledgerBundleAvailable ? `<script src="./ledger-browser.bundle.js"></script>` :
     let lock = Promise.resolve();
     const withLock = (fn) => { const run = lock.then(fn, fn); lock = run.catch(() => {}); return run; };
 
-    // The SAME bounded-race wink-nlp CDN load plan-viz.mjs's own chat-assert
-    // dock uses: a cross-origin dynamic import() can neither resolve nor
-    // reject on some failures, so an unbounded await would leave a session
-    // stuck forever. Best-effort — a teach sentence that needs the lemma tier
-    // just declines honestly without it, same as a checkout missing the
-    // optional deps.
+    // The SAME bounded-race wink load plan-viz.mjs's own chat-assert dock
+    // uses, now against the site's shared first-party ./vendor/wink.js: a
+    // dynamic import() can neither resolve nor reject on some failures, so an
+    // unbounded await would leave a session stuck forever. Best-effort — a
+    // teach sentence that needs the lemma tier just declines honestly without
+    // it, same as a checkout missing the optional deps.
     const WINK_LOAD_TIMEOUT_MS = 8000;
     const winkTimeout = (ms, reason) => new Promise((_, reject) => setTimeout(() => reject(new Error(reason)), ms));
     let winkReady = null;
@@ -1009,16 +1002,14 @@ ${ledgerBundleAvailable ? `<script src="./ledger-browser.bundle.js"></script>` :
       if (winkReady) return winkReady;
       winkReady = (async () => {
         try {
-          const mods = await Promise.race([
-            Promise.all([import("wink-nlp"), import("wink-eng-lite-web-model")]),
-            winkTimeout(WINK_LOAD_TIMEOUT_MS, "wink-nlp CDN load timed out"),
+          const mod = await Promise.race([
+            import("./vendor/wink.js"),
+            winkTimeout(WINK_LOAD_TIMEOUT_MS, "wink vendor asset load timed out"),
           ]);
-          const winkNLP = mods[0].default;
-          const model = mods[1].default;
-          tmctLedger.registerWinkModel(() => ({ winkNLP: winkNLP, model: model }));
+          tmctLedger.registerWinkModel(() => ({ winkNLP: mod.winkNLP, model: mod.model }));
         } catch (err) {
           // eslint-disable-next-line no-console
-          console.warn("tmct ledger: wink-nlp CDN load failed, continuing without the lemma/POS tier", err);
+          console.warn("tmct ledger: the wink vendor asset failed to load, continuing without the lemma/POS tier", err);
         }
       })();
       return winkReady;

package/src/services/plan-viz.mjs

@@ -294,24 +294,16 @@ export function renderPlanHtml({ plan, rendersAs = {}, sizeOrder = [], title } =
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>${escapeHtml(pageTitle)}</title>
 <!--
-  Import map: resolves the "wink-nlp"/"wink-eng-lite-web-model" bare specifiers the
-  live re-solve session's own dynamic import() needs (pinned to the exact versions
-  package.json depends on) to esm.sh CDN builds — the same seam chat.html and
-  ledger.html each wire up for their own live sessions, mirrored here because this
-  page can be opened standalone (no import map inherited from a host document). The
-  bundle itself (./plan-browser.bundle.js) never touches wink-nlp directly —
-  wink-model.mjs's own header explains why a static import would drag the ~1 MB
-  model into every bundle; only the page's own inline script performs this CDN
-  import, the same bounded-race tryLoadWink() pattern public/tmct-browser.mjs uses.
+  The wink lemma/POS tier loads from ./vendor/wink.js — the site's own shared
+  first-party bundle of wink-nlp + wink-eng-lite-web-model (built by
+  scripts/build-wink-vendor.mjs), one cached copy shared with chat.html and
+  ledger.html, no CDN. The bundle itself (./plan-browser.bundle.js) never
+  touches wink directly — wink-model.mjs's own header explains why a static
+  import would drag the ~1 MB model into every bundle; only the page's own
+  inline script performs the import, the same bounded-race tryLoadWink()
+  pattern public/tmct-browser.mjs uses, and a failed load degrades to the
+  curated + fuzzy tiers, never an error.
 -->
-<script type="importmap">
-{
-  "imports": {
-    "wink-nlp": "https://esm.sh/wink-nlp@2.4.0",
-    "wink-eng-lite-web-model": "https://esm.sh/wink-eng-lite-web-model@1.8.1"
-  }
-}
-</script>
 <style>
 ${THEME_TOKENS_CSS}
 html { background: var(--bg); }
@@ -321,6 +313,10 @@ main { max-width: 880px; margin: 0 auto; padding: 1.4rem 1rem 3rem; }
 h1 { font-size: 1.15rem; margin: 0 0 .8rem; }
 .chip { font-family: ${MONO_STACK}; font-size: .68rem; color: var(--muted); border: 1px solid var(--line); border-radius: 99px; padding: .12rem .55rem; }
 .stage { display: grid; grid-template-columns: minmax(0, 1fr) 230px; gap: 1rem; }
+/* grid items refuse to shrink below their content's min-width by default, so
+   the 640px board would stretch the track and the whole page with it on a
+   phone — let the items shrink and the boardwrap scroll instead. */
+.stage > * { min-width: 0; }
 @media (max-width: 660px) { .stage { grid-template-columns: 1fr; } }
 .boardwrap { overflow-x: auto; }
 .board { position: relative; width: ${BOARD_W}px; height: ${BOARD_H}px; background: var(--card); border: 1px solid var(--line); border-radius: 8px; }
@@ -432,6 +428,10 @@ const PLAN = ${embedded};
 <script>
 (function () {
   "use strict";
+  // Best-effort: a copy of this page opened without the sibling worker file
+  // (a tmct --render plan --output file, a file:// open) just swallows the
+  // registration failure and works exactly as before.
+  if ("serviceWorker" in navigator) navigator.serviceWorker.register("./tmct-sw.js").catch(() => {});
   const pageTitleEl = document.getElementById("pageTitle");
   const board = document.getElementById("board");
   const stepLabel = document.getElementById("stepLabel");
@@ -635,10 +635,10 @@ const PLAN = ${embedded};
     // rest on the target" sentence needs a real lemmatiser to reduce
     // "moving" to "move" — without it that one teach sentence honestly
     // declines and every position fact taught after it fails in turn. Load
-    // wink from the CDN and register it, the SAME bounded-race pattern
-    // public/tmct-browser.mjs uses: a cross-origin dynamic import() can
-    // neither resolve nor reject on some failures, so an unbounded await
-    // would leave a resolve stuck forever.
+    // wink from the site's shared first-party ./vendor/wink.js and register
+    // it, the SAME bounded-race pattern public/tmct-browser.mjs uses: a
+    // dynamic import() can neither resolve nor reject on some failures, so
+    // an unbounded await would leave a resolve stuck forever.
     // Awaited before EVERY session creation below (idempotent — a second
     // await after the first attempt already settled resolves immediately).
     const WINK_LOAD_TIMEOUT_MS = 8000;
@@ -648,14 +648,14 @@ const PLAN = ${embedded};
       if (winkReady) return winkReady;
       winkReady = (async () => {
         try {
-          const [{ default: winkNLP }, { default: model }] = await Promise.race([
-            Promise.all([import("wink-nlp"), import("wink-eng-lite-web-model")]),
-            winkTimeout(WINK_LOAD_TIMEOUT_MS, "wink-nlp CDN load timed out"),
+          const mod = await Promise.race([
+            import("./vendor/wink.js"),
+            winkTimeout(WINK_LOAD_TIMEOUT_MS, "wink vendor asset load timed out"),
           ]);
-          tmctPlan.registerWinkModel(() => ({ winkNLP, model }));
+          tmctPlan.registerWinkModel(() => ({ winkNLP: mod.winkNLP, model: mod.model }));
         } catch (err) {
           // eslint-disable-next-line no-console
-          console.warn("tmct plan: wink-nlp CDN load failed, continuing without the lemma/POS tier", err);
+          console.warn("tmct plan: the wink vendor asset failed to load, continuing without the lemma/POS tier", err);
         }
       })();
       return winkReady;

package/src/services/sessions.mjs

@@ -18,7 +18,7 @@
 
 import { mkdir, readFile, readdir, rename, writeFile } from "node:fs/promises";
 import { basename, dirname, join } from "node:path";
-import { appendUtterances, CREATED_AT_PROP, UPDATED_AT_PROP } from "../adapters/memory/core.mjs";
+import { appendUtterances, openConfiguredMemoryBackend, CREATED_AT_PROP, UPDATED_AT_PROP } from "../adapters/memory/core.mjs";
 import { turnKey } from "../domain/memory/session-turns.mjs";
 
 export const SESSIONS_DIR_REL = join(".tmct", "sessions");
@@ -193,7 +193,12 @@ function repoDirFromGraphFile(graphFile) {
  *  change — it already calls appendSessionToGraph every turn. Each recorded turn becomes
  *  an a-visitor-said Utterance; the response prose is recovered from the human transcript
  *  (the sidecar only records ids) and recorded alongside as a tmct Utterance replying to
- *  it. Deterministic utterance ids make the per-turn replay idempotent. Once the sidecar
+ *  it. The write goes through the repo's CONFIGURED memory backend (the same store the
+ *  session's taught facts land in), opened fresh per append — never a raw Backend-A
+ *  graph.json off the repo path, so the fold's canonise-link finds these utterances.
+ *  Deterministic utterance ids make the per-turn replay idempotent, and each append
+ *  replays the WHOLE record so far, so the completed-append state is always the full
+ *  session even if a concurrent writer dropped an earlier turn's rows. Once the sidecar
  *  carries its end marker, the session is folded into the text-block corpus
  *  (memory/fold.mjs). */
 async function recordSessionMemory(graphFile, record, repoDirOverride = null) {
@@ -232,7 +237,14 @@ async function recordSessionMemory(graphFile, record, repoDirOverride = null) {
       });
     }
   }
-  await appendUtterances(repoDir, utterances);
+  if (utterances.length) {
+    const { dir: memoryDir, close } = await openConfiguredMemoryBackend(repoDir);
+    try {
+      await appendUtterances(memoryDir, utterances);
+    } finally {
+      await close();
+    }
+  }
 
   // Session over? The sidecar's end marker is authoritative (chat.mjs writes it
   // before the final upsert). Fold THIS session's transcript into the corpus.

package/src/services/spider-fly-viz.mjs

@@ -32,15 +32,15 @@
 // bundle's own real ES exports instead, since (unlike ledger-viz, which
 // reuses a FIXED shared bundle it can't extend for one page's own needs) this
 // page ships its own dedicated bundle and can just export what it needs.
-import { THEME_TOKENS_CSS, SERIF_STACK, MONO_STACK, escapeHtml, embedJson } from "./viz-theme.mjs";
+import { THEME_TOKENS_CSS, SERIF_STACK, MONO_STACK, escapeHtml, embedJson, embedScriptText } from "./viz-theme.mjs";
 import { createTicker } from "./viz-ticker.mjs";
 import { GRID_SIZE, WEB_HOME, WEB_RADIUS, isInWebBlock, cellId } from "../domain/spider-fly-world.mjs";
 import { FLY_INITIAL_MASS, EGG_LAY_MASS_THRESHOLD } from "./spider-fly.mjs";
 import { DEFAULT_GAME_CONFIG } from "../domain/game-config.mjs";
 
-// A larger cell than this page's first cut (44px) — the board now fills
-// noticeably more of the stage's own width, closing most of the dead gap a
-// fixed-260px side column used to leave next to a small fixed-440px board.
+// A larger cell than this page's first cut (44px) — the board sits in its
+// own full-width block, so a bigger cell keeps it reading as the page's
+// main scene rather than a small inset square.
 const CELL_PX = 54;
 const BOARD_PX = CELL_PX * GRID_SIZE;
 const DEFAULT_TITLE = "tmct — the spider and the fly";
@@ -220,8 +220,13 @@ export function nextCorpses(prevCorpses, prevAgents, agents, turn, lingerTurns =
  *  `?preview=1` on the page's own URL switches it into the small, auto-
  *  playing, non-interactive mode the home page's hero iframe embeds (§11) —
  *  one file serves both the hero and the "open full-screen" link, matching
- *  how ledger.html/plan.html are each one file embedded two ways. */
-export function renderSpiderFlyHtml({ title = DEFAULT_TITLE, spriteTemplates = [] } = {}) {
+ *  how ledger.html/plan.html are each one file embedded two ways.
+ *  `engineBundleJs` (the built spider-fly-browser bundle's own text) inlines
+ *  the engine into the page instead of the sibling `<script src>`, for the
+ *  CLI's standalone export — one downloadable file that runs from file://
+ *  with no sibling assets. Default empty keeps the site build's sibling-file
+ *  arrangement byte-identical. */
+export function renderSpiderFlyHtml({ title = DEFAULT_TITLE, spriteTemplates = [], engineBundleJs = "" } = {}) {
   const gridData = embedJson({
     gridSize: GRID_SIZE,
     webCells: webCellIds(),
@@ -294,7 +299,11 @@ ${THEME_TOKENS_CSS}
   h1 { font-size: 1.4rem; margin: .3rem 0 .9rem; text-wrap: balance; }
   button { font: inherit; color: inherit; background: none; cursor: pointer; }
   button:focus-visible, input:focus-visible, .sprite:focus-visible { outline: 2px solid var(--ink); outline-offset: 2px; }
-  .stage { display: grid; grid-template-columns: minmax(0, 1fr) minmax(280px, 360px); gap: 1.2rem; }
+  /* The top row: the tuning console at roughly two-thirds width on the left,
+     the chat/agents column at roughly a quarter on the right — the 8fr/3fr
+     split plus the gap approximates that pair of fractions without them
+     needing to sum to a full width. */
+  .stage { display: grid; grid-template-columns: minmax(0, 8fr) minmax(280px, 3fr); gap: 1.2rem; align-items: start; }
   @media (max-width: 760px) { .stage { grid-template-columns: 1fr; } }
   /* A dusty window corner: a soft light glow near the top-left (WEB_HOME
      already sits near that corner — spider-fly-world.mjs's own header
@@ -302,14 +311,7 @@ ${THEME_TOKENS_CSS}
      in the light. Decoration only — the 10x10 game grid itself is drawn by
      drawBoard() on the canvas beneath, unchanged. */
   .board-frame {
-    /* The side column's own height grows with the live agent count
-       (.hud-list caps out at 420px, then scrolls) — align-self keeps this
-       fixed-square board centered in whatever row height that produces,
-       instead of top-aligning it and leaving a dead gap below once the
-       side column outgrows the board. The grid's default align-items:
-       stretch would otherwise force this box tall, breaking its own
-       aspect-ratio square. */
-    align-self: center;
+    margin: 0 auto;
     position: relative; width: ${BOARD_PX}px; max-width: 100%; aspect-ratio: 1 / 1;
     background:
       radial-gradient(140% 140% at 6% 6%, rgba(255, 241, 199, .55), transparent 52%),
@@ -336,6 +338,7 @@ ${THEME_TOKENS_CSS}
   .sprite.corpse { filter: grayscale(1); opacity: .38; pointer-events: none; }
   .sprite.corpse .sprite-face { transform: none !important; }
   .thread-tip { position: absolute; transform: translate(-50%, -130%); font-family: ${MONO_STACK}; font-size: .68rem; background: var(--ink); color: var(--bg); padding: .1rem .4rem; border-radius: 3px; pointer-events: none; white-space: nowrap; display: none; }
+  .stage-left { display: flex; flex-direction: column; gap: 1.2rem; min-width: 0; }
   .side { display: flex; flex-direction: column; gap: .8rem; min-width: 0; }
   /* The console panel shell: a raised beveled plastic face (chrome-shadow-
      raised), never the flat card/hairline the rest of the site uses — the
@@ -446,7 +449,8 @@ ${THEME_TOKENS_CSS}
   .status { font-family: ${MONO_STACK}; font-size: .74rem; color: var(--muted); margin-top: .5rem; padding-left: .5rem; border-left: 2px solid var(--chrome-brass); }
   body.preview .side, body.preview .controls-row, body.preview .status, body.preview .tuning { display: none; }
   body.preview main { padding: 0; max-width: none; }
-  body.preview .stage { display: block; }
+  body.preview .stage, body.preview .stage-left { display: block; }
+  body.preview .board-frame { margin: 0; }
   body.preview .eyebrow, body.preview h1 { display: none; }
 </style>
 </head>
@@ -455,17 +459,38 @@ ${THEME_TOKENS_CSS}
   <div class="eyebrow">tmct &middot; spider and fly</div>
   <h1>A spider in its web, a fly on the board — each planning against the other</h1>
   <div class="stage">
+    <div class="stage-left">
+    <div class="tuning" id="tuning">
+      <h2>live tuning &mdash; mass loss, spawn rate, vision, per class</h2>
+      <div class="tuning-grid">
+        <div class="tuning-col spider">
+          <h3>spider</h3>
+          <label>mass lost/turn <span class="tuning-val" id="tvSpiderMass"></span>
+            <input type="range" id="ctlSpiderMass" min="0.1" max="3" step="0.1" disabled></label>
+          <label>hatchlings per egg <span class="tuning-val" id="tvSpiderSpawn"></span>
+            <input type="range" id="ctlSpiderSpawn" min="1" max="5" step="1" disabled></label>
+          <label>vision radius <span class="tuning-val" id="tvSpiderVision"></span>
+            <input type="range" id="ctlSpiderVision" min="1" max="8" step="1" disabled></label>
+        </div>
+        <div class="tuning-col fly">
+          <h3>fly</h3>
+          <label>mass lost/turn <span class="tuning-val" id="tvFlyMass"></span>
+            <input type="range" id="ctlFlyMass" min="0.1" max="3" step="0.1" disabled></label>
+          <label>spawns every N turns <span class="tuning-val" id="tvFlySpawn"></span>
+            <input type="range" id="ctlFlySpawn" min="1" max="10" step="1" disabled></label>
+          <label>vision radius <span class="tuning-val" id="tvFlyVision"></span>
+            <input type="range" id="ctlFlyVision" min="1" max="8" step="1" disabled></label>
+        </div>
+      </div>
+    </div>
     <div class="board-frame" id="boardFrame">
       <canvas id="board" width="${BOARD_PX}" height="${BOARD_PX}" aria-label="the 10x10 board"></canvas>
       <canvas id="pov" width="${BOARD_PX}" height="${BOARD_PX}" aria-hidden="true"></canvas>
       <div class="sprite-layer" id="spriteLayer"></div>
       <div class="thread-tip" id="threadTip"></div>
     </div>
-    <aside class="side" aria-label="Agents and chat">
-      <div class="hud">
-        <h2>agents</h2>
-        <div class="hud-list" id="hud"></div>
-      </div>
+    </div>
+    <aside class="side" aria-label="Chat and agents">
       <div class="chat">
         <h2>tell the spider or the fly something</h2>
         <div class="chatlog" id="chatlog" aria-live="polite"></div>
@@ -483,30 +508,11 @@ ${THEME_TOKENS_CSS}
         </div>
         <div class="dynpills" id="dynamicPills" role="group" aria-label="address one individual and feed it a true or false position claim"></div>
       </div>
-    </aside>
-  </div>
-  <div class="tuning" id="tuning">
-    <h2>live tuning &mdash; mass loss, spawn rate, vision, per class</h2>
-    <div class="tuning-grid">
-      <div class="tuning-col spider">
-        <h3>spider</h3>
-        <label>mass lost/turn <span class="tuning-val" id="tvSpiderMass"></span>
-          <input type="range" id="ctlSpiderMass" min="0.1" max="3" step="0.1" disabled></label>
-        <label>hatchlings per egg <span class="tuning-val" id="tvSpiderSpawn"></span>
-          <input type="range" id="ctlSpiderSpawn" min="1" max="5" step="1" disabled></label>
-        <label>vision radius <span class="tuning-val" id="tvSpiderVision"></span>
-          <input type="range" id="ctlSpiderVision" min="1" max="8" step="1" disabled></label>
-      </div>
-      <div class="tuning-col fly">
-        <h3>fly</h3>
-        <label>mass lost/turn <span class="tuning-val" id="tvFlyMass"></span>
-          <input type="range" id="ctlFlyMass" min="0.1" max="3" step="0.1" disabled></label>
-        <label>spawns every N turns <span class="tuning-val" id="tvFlySpawn"></span>
-          <input type="range" id="ctlFlySpawn" min="1" max="10" step="1" disabled></label>
-        <label>vision radius <span class="tuning-val" id="tvFlyVision"></span>
-          <input type="range" id="ctlFlyVision" min="1" max="8" step="1" disabled></label>
+      <div class="hud">
+        <h2>agents</h2>
+        <div class="hud-list" id="hud"></div>
       </div>
-    </div>
+    </aside>
   </div>
   <div class="controls-row">
     <button id="resetBtn" type="button" disabled>reset</button>
@@ -519,7 +525,7 @@ ${THEME_TOKENS_CSS}
 <script>
 const SPIDERFLY = ${gridData};
 </script>
-<script src="./spider-fly-browser.bundle.js"></script>
+${engineBundleJs ? `<script>\n${embedScriptText(engineBundleJs)}\n</script>` : `<script src="./spider-fly-browser.bundle.js"></script>`}
 <script>
 (function () {
   "use strict";