@polycode-projects/the-mechanical-code-talker 5.0.4 → 5.0.6

package/src/surfaces/web/mudiii-browser-entry.mjs

@@ -6,14 +6,6 @@
 // on `{ as: character }` — the addressee is in the sentence, "@fox-1 look"),
 // and the simulation itself advances as ONE whole-world tick
 // (`runTownSquareTick`) rather than mud's per-character `autoplayTick`.
-//
-// `src/services/predator-prey.mjs` — the engine this file drives — does not
-// exist in every worktree yet; a concurrent track owns it. The import below
-// is guarded (dynamic, try/catch) so this module still loads, and every
-// test that imports mudiii-viz.mjs (which never imports this file) is
-// unaffected either way. `createMudiiiSession` throws a clear "the engine
-// isn't built yet" error if actually called before that track lands, rather
-// than a bare ERR_MODULE_NOT_FOUND with no context.
 import {
   createInMemoryStore, appendFacts, appendRule, loadMemory, readFactRows, removeFacts,
 } from "../../adapters/memory/core.mjs";
@@ -21,25 +13,22 @@ import { parseEntities } from "../../domain/codegraph.mjs";
 import { memoryFactGraphPayload } from "../../domain/memory-facts.mjs";
 import { loadLexicon } from "../../domain/grammar/lexicon.mjs";
 import { worldProvenanceTag } from "../../domain/worlds-pack.mjs";
-import { layoutNamed } from "../../domain/town-square-world.mjs";
+import {
+  COMPASS_POINTS, DEFAULT_FACING, cellId, layoutNamed, parseCellId, reverseFacing, stepCellFrom, turnedFacing,
+} from "../../domain/town-square-world.mjs";
+import { findActionPath } from "../../domain/planning.mjs";
+import { DEFAULT_GAME_CONFIG } from "../../domain/game-config.mjs";
 import { parseMudEditorText, planMudEditorSync, gridWorldEditorState } from "../../services/mud-editor.mjs";
+import { pillsForMudiii } from "../../services/mudiii-turn.mjs";
+import { relatedForTerm } from "../../domain/skos-view.mjs";
+import { classAncestorChain } from "../../domain/sprite-map.mjs";
 import { createTurnSession } from "./turn-session.mjs";
 import { publishTmctSurface } from "./tmct-surface.mjs";
 import { graphAsk, enginePlan } from "./engine-surface.mjs";
-
-let engine = null;
-async function loadEngine() {
-  if (engine) return engine;
-  try {
-    engine = await import("../../services/predator-prey.mjs");
-  } catch (err) {
-    throw new Error(
-      "mudiii's engine (src/services/predator-prey.mjs) is not built in this worktree yet "
-      + `(${err && err.message ? err.message : err})`,
-    );
-  }
-  return engine;
-}
+import {
+  foldTownSquareState, gridApplyActions, pathStateKey, placeFood as engPlaceFood, recastTownSquare,
+  roleOfId, runTownSquareTick, startTownSquareGame, townSquareBoard,
+} from "../../services/predator-prey.mjs";
 
 /** `count` entries drawn at random from `roster`, in random order, without
  *  repeats — mirrors mud-browser-entry.mjs's own `pickMudRoster`. `random` is
@@ -78,6 +67,76 @@ export function townSquareRosterArgs(agents, roleOf) {
   return { predatorCount, preyCount };
 }
 
+// Where each press on the page's ring of controls sits relative to the agent's
+// own facing. Up and down are steps — straight ahead and straight back — and
+// the other six turn on the spot to the angle they sit at, which is what makes
+// the ring one rule rather than eight cases.
+const RING_ANGLES = Object.freeze({
+  up: 0, forward: 0,
+  "up-right": 45, right: 90, "down-right": 135,
+  down: 180, back: 180,
+  "down-left": -135, left: -90, "up-left": -45,
+});
+const RING_STEPS = new Set(["up", "forward", "down", "back"]);
+
+/** The `manualMoves` entry one press asks of an agent standing at `cell` and
+ *  facing `facing`: `{ cell, facing }` for a step, `{ facing }` alone for a
+ *  turn on the spot. Null when `direction` names neither a ring press nor a
+ *  compass point.
+ *
+ *  `direction` is either a ring press — "up"/"forward" and "down"/"back" step
+ *  straight ahead and straight back with the facing left alone, "left" and
+ *  "right" turn ninety degrees, and the four diagonals turn to the angle they
+ *  sit at (forty-five for the top pair, a hundred and thirty-five for the
+ *  bottom) — or an absolute compass point, where a cardinal steps that way and
+ *  faces that way and an intercardinal turns on the spot to face it.
+ *
+ *  Whether the cell it names can be entered is the engine's answer rather than
+ *  this function's: there is one legality table, and it is the world's own
+ *  exit facts. Pure. */
+export function driveRequest(direction, { cell, facing = DEFAULT_FACING } = {}) {
+  const press = String(direction ?? "").trim().toLowerCase();
+  if (!press) return null;
+  if (press in RING_ANGLES) {
+    const angle = RING_ANGLES[press];
+    if (!RING_STEPS.has(press)) {
+      const turned = turnedFacing(facing, angle);
+      return turned ? { facing: turned } : null;
+    }
+    const along = angle === 0 ? facing : reverseFacing(facing);
+    // An agent facing an intercardinal has no cell straight ahead of it — the
+    // grid carries no diagonal exit — so the press holds it where it stands.
+    const target = stepCellFrom(cell, along);
+    return target ? { cell: target, facing } : { facing };
+  }
+  const target = stepCellFrom(cell, press);
+  if (target) return { cell: target, facing: press };
+  return COMPASS_POINTS.includes(press) ? { facing: press } : null;
+}
+
+/** The shortest route from `fromCell` to `toCell` over `factRows`' own exit
+ *  facts, as `{ cells, directions }` — `cells` runs from one end to the other
+ *  inclusive, `directions` names one hop each. Null when nothing connects
+ *  them, so a caller declines visibly rather than drawing a line through a
+ *  building the board would never let anyone walk through.
+ *
+ *  The exit table is the one legality answer, the same rows the engine's own
+ *  chase and forage searches read, so a route drawn here is a route the world
+ *  agrees with. */
+export function routeBetweenCells(factRows, fromCell, toCell) {
+  const from = parseCellId(fromCell);
+  const to = parseCellId(toCell);
+  if (!from || !to) return null;
+  const found = findActionPath(
+    from,
+    (searchState) => searchState.x === to.x && searchState.y === to.y,
+    gridApplyActions(factRows),
+    { stateKey: pathStateKey },
+  );
+  if (!found) return null;
+  return { cells: found.states.map((s) => cellId(s.x, s.y)), directions: found.actions };
+}
+
 /** A live, shared town-square world one visitor watches and talks over.
  *  `worldPayload` is `{ name, facts, rules, opening }`, read once at build
  *  time the same way every other viz page's world payload is. `agents` is
@@ -88,15 +147,14 @@ export function townSquareRosterArgs(agents, roleOf) {
  *  (`runTownSquareTick`) and its conversation is a single shared dock.
  *
  *  Returns `{ memoryDir, codeGraph, graph, refreshGraph, turn, tick, board,
- *  snapshot, applyEdit, placeFood }`. A reset is not a method here: the
- *  page re-opens a whole session for it, which is what a reset means when the
- *  store is in memory and belongs to one visitor. */
-export async function createMudiiiSession(worldPayload, { agents = [], epoch = 0 } = {}) {
-  const {
-    startTownSquareGame, runTownSquareTick, townSquareBoard, foldTownSquareState,
-    placeFood: engPlaceFood, roleOfId,
-  } = await loadEngine();
-
+ *  snapshot, applyEdit, placeFood, driveAgent, recast }`.
+ *
+ *  `getTeachEnabled` is read fresh on every turn, so a visitor can tick the
+ *  page's teach box mid-session and have the very next line read as a fact to
+ *  store rather than a command to run. */
+export async function createMudiiiSession(
+  worldPayload, { agents = [], epoch = 0, getTeachEnabled = () => false } = {},
+) {
   // Every engine call is layout-scoped: the world pack ships the BOARD, and
   // the layout carries the geometry plus the cast counts the engine mints the
   // animals from. Resolved once here so no call site has to remember it.
@@ -135,8 +193,11 @@ export async function createMudiiiSession(worldPayload, { agents = [], epoch = 0
 
   const turnSession = createTurnSession({
     memoryDir, graph: codeGraph, lexicon, sessionId: "town-square",
-    vocabHint: 'Try "@fox-1 look", or "what does fox-1 believe".',
-    buildExtraOptions: () => ({ planState: planHolder.state }),
+    vocabHint: 'Try "@fox the goblin is east", or "what does the fox see".',
+    buildExtraOptions: () => ({
+      planState: planHolder.state,
+      gameConfig: { ...DEFAULT_GAME_CONFIG, mudiii: { ...DEFAULT_GAME_CONFIG.mudiii, teach: getTeachEnabled() } },
+    }),
     captureExtraState: async (result, state) => {
       if ("planState" in result) planHolder.state = state.planState;
     },
@@ -150,6 +211,56 @@ export async function createMudiiiSession(worldPayload, { agents = [], epoch = 0
     return runTownSquareTick(memoryDir, { layout });
   }
 
+  /** Drive one agent by hand for a turn — `driveAgent("fox-1", "up")`, where
+   *  `direction` is a ring press or a compass point and `driveRequest` above
+   *  says what each one means.
+   *
+   *  A press goes through the SAME whole-world tick every other turn goes
+   *  through: it spends a turn, the ecology pass runs, and every other agent
+   *  decides and moves. So the return IS a tick payload, with one field added:
+   *  `driven` says whether the world took the press and where the agent ended
+   *  up. A press the board refuses — a wall, a prop, an agent that is not on
+   *  the board — still advances the world, and that agent decides for itself
+   *  this turn rather than freezing. */
+  async function driveAgent(agentId, direction) {
+    const state = foldTownSquareState(readFactRows(await loadMemory(memoryDir)));
+    const standing = state.removed.has(agentId) ? null : state.placements.get(agentId);
+    const facing = state.facing.get(agentId)?.value ?? DEFAULT_FACING;
+    const request = standing ? driveRequest(direction, { cell: standing.cell, facing }) : null;
+    const result = await runTownSquareTick(memoryDir, {
+      layout, manualMoves: request ? { [agentId]: request } : {},
+    });
+    const accepted = result.rungs[agentId] === "driven";
+    const after = result.agents[agentId] ?? null;
+    return {
+      ...result,
+      driven: {
+        agent: agentId,
+        direction: String(direction ?? ""),
+        accepted,
+        from: standing?.cell ?? null,
+        cell: accepted && after ? after.cell : null,
+        facing: accepted && after ? after.facing : null,
+      },
+    };
+  }
+
+  /** Re-cast this same store onto a fresh epoch and hand back the opening
+   *  board. This is what a Reset means once a store is live: the world's own
+   *  facts, everything taught into it and everything the editor changed all
+   *  stand, and only the animals are minted again. Re-opening a whole session
+   *  instead would throw away the taught facts along with the cast, which is
+   *  not what "reset the board" says.
+   *
+   *  `agents` sizes the new cast the same way `createMudiiiSession`'s own
+   *  roster does; `epoch` defaults to one past whatever the store is on. */
+  async function recast({ agents: nextAgents = [], epoch: nextEpoch = null } = {}) {
+    await recastTownSquare(memoryDir, {
+      layout, epoch: nextEpoch, ...townSquareRosterArgs(nextAgents, (id) => roleOfId(id)),
+    });
+    return townSquareBoard(memoryDir, { layout });
+  }
+
   /** The board as it stands, in the same payload shape `tick` returns, with no
    *  turn spent. A page opens a session and then draws THIS — otherwise its
    *  first sight of where anything stands is the first tick, and every mesh
@@ -201,6 +312,8 @@ export async function createMudiiiSession(worldPayload, { agents = [], epoch = 0
     refreshGraph,
     turn: turnSession.turn,
     tick,
+    driveAgent,
+    recast,
     board,
     snapshot,
     applyEdit,
@@ -220,5 +333,12 @@ publishTmctSurface({
   plan: enginePlan,
   page: {
     pickMudiiiRoster,
+    // pillsForMudiii closes over two other modules' bindings, so the page
+    // reaches it through this bag rather than a `.toString()` splice.
+    pillsForMudiii,
+    // What the editor's own suggestion rail reads for the word under the
+    // cursor: the lateral SKOS neighbourhood and the vertical is-a chain.
+    relatedForTerm, classAncestorChain,
+    routeBetweenCells,
   },
 });