@turing-machine-js/visuals 7.0.0-alpha.6

package/dist/types.d.ts

@@ -0,0 +1,92 @@
+import type { Graph } from '@turing-machine-js/machine';
+/**
+ * State-graph highlight descriptor (machines-demo#10). MachineView derives it
+ * from `executionMode` + the latest pause-response data; MachineGraph reads
+ * it to light up the `from → edge → to` triple in the rendered SVG.
+ *
+ * - `fromId: 'idle'` represents the synthetic `idle([idle])` sentinel that
+ *   `toMermaid` emits at the entry point. Used in IDLE mode to mark "where
+ *   execution would start".
+ * - `fromId: number` is an engine `GraphNode.id` — the source state.
+ * - `toId: number | null` is the destination state's id (or `null` at halt).
+ * - `strong` selects which end of the triple gets the bolder/stronger
+ *   accent. Per the (B) rule: `from` strong at `before` pause; `to` strong
+ *   at `after` / iter-end pause / IDLE (destination feels current).
+ */
+export type GraphHighlight = {
+    fromId: number | 'idle';
+    toId: number | null;
+    strong: 'from' | 'to';
+    /**
+     * True when this highlight reflects a paused-event apply (RUNNING_PAUSED),
+     * false for per-iter idle applies (RUNNING_AUTO). MachineGraph uses this
+     * to detect cross-pause same-state revisits — pulsing the strong node when
+     * the current paused apply lands on the same state as the previous paused
+     * apply, even when intermediate idle applies pointed elsewhere
+     * (e.g., stateA breakpoint → continue → run through stateB/C → stateA
+     * breakpoint fires again). The simpler "previous apply's strong matches"
+     * check already covers AUTO self-loops; this flag drives the second pulse
+     * trigger.
+     */
+    paused: boolean;
+};
+/**
+ * Per-tape snapshot: the cells visible/usable plus the head's index into them.
+ * Same shape as machines-demo's TapeSnapshot. Pure data — no library handles.
+ */
+export type TapeSnapshot = {
+    symbols: string[];
+    position: number;
+};
+/**
+ * One frame of a recorded snippet — the state of the machine at iter `step`.
+ * Frame 0 = initial state (before any transition); frame N = state after iter N's transition.
+ *
+ * `tape` is per-tape (single-tape machines: length 1). `highlight` describes
+ * what to render on the state graph at this moment (null when no highlight).
+ * `log` is optional pre-formatted text — a caption / status line consumers can render.
+ */
+export type Frame = {
+    step: number;
+    tape: TapeSnapshot[];
+    /**
+     * Per-tape engine command for the iter that produced this frame. Carries
+     * both sides of the cell so players can step bi-directionally without
+     * recomputing from neighbouring frames:
+     *
+     * - `movement` — `'L' | 'R' | 'S'`. Forward step slides the tape this way;
+     *   backward step slides the opposite.
+     * - `read` — symbol on the head's cell BEFORE this iter (what the engine
+     *   matched). Backward step writes this back.
+     * - `write` — symbol on the cell AFTER this iter (=== `read` if no write
+     *   happened). Forward step writes this; UI triggers the per-cell flash
+     *   iff `write !== read`.
+     *
+     * Undefined on frame 0 (initial state — no transition has fired yet).
+     */
+    commands?: {
+        movement: 'L' | 'R' | 'S';
+        read: string;
+        write: string;
+    }[];
+    highlight: GraphHighlight | null;
+    log?: string;
+};
+/**
+ * Recorded run of a machine — playback artifact for embeds, articles,
+ * landing-page panels. Engine-agnostic (no `engine` field; identity lives
+ * at the caller bucket level).
+ *
+ * - `version: 1` — schema integer. Additive fields don't bump it;
+ *   shape-breaking changes do.
+ * - `graph` — engine `State.toGraph` output captured at recording time.
+ * - `alphabets` — per-tape alphabet list (single-tape: length 1).
+ * - `frames` — length === `stepsApplied + 1`; frame 0 is the initial state.
+ */
+export type Snippet = {
+    version: 1;
+    name?: string;
+    graph: Graph;
+    alphabets: string[][];
+    frames: Frame[];
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/docs/graph-highlight-and-breakpoints.md

@@ -0,0 +1,272 @@
+# Graph highlight and breakpoint rules
+
+> Canonical reference for every CSS class the demo applies to the rendered state-graph SVG, when each class fires, and how the breakpoint engine-side / UI-side state stays consistent. Companion to [`execution-model.md`](./execution-model.md) (modes + transitions) and [`machine-graph-palette.md`](./machine-graph-palette.md) (color tokens). Source files: `src/components/MachineGraph.svelte` (the apply-highlight + cache-build + indicator effects), `src/components/MachineView.svelte` (derives `graphHighlight`, owns the `breakpoints` set), `src/lib/machineWorker.ts` (`onPauseFn` + `toggleBreakpoint`), `src/lib/graphUtils.ts` (canonicalization helpers).
+
+## 1. Node-id conventions
+
+The engine's `Graph.nodes` keys are positive integer ids assigned at graph-build time. The demo also recognizes three synthetic ids:
+
+| Id range | Kind | Where it comes from | Click target? |
+|---|---|---|---|
+| `> 0` | Regular state, wrapper, or bare | `State.toGraph` walks reachable States | yes |
+| `0` | Halt singleton (`haltState`) | Engine sentinel, process-wide | no — global, not per-machine |
+| `< 0` | Halt marker (`isHaltMarker: true`, id = `-frameId`) | `toGraph` rewrites in-frame halts so they land inside the subgraph cluster instead of the global singleton | no — collapses to `haltState` at runtime |
+| `'idle'` | Synthetic entry sentinel | `toGraph` always emits a stadium-shape `idle` node with `idle -. enter .-> sN` | no |
+
+Click handlers are attached only to nodes whose key is `typeof === 'number' && > 0` — see `MachineGraph.svelte`'s cache-build `$effect`.
+
+## 2. Wrapper / bare equivalence
+
+A `State.withOverriddenHaltState(continuation)` produces a *wrapper* State that shares its `#debugRef` cell with the bare engine-side (`State.ts:391`: `state.#debugRef = bare.#debugRef`). Setting `wrapper.debug.before = true` and `bare.debug.before = true` mutate the SAME cell.
+
+The demo collapses this into a single breakpoint *equivalence class*:
+
+- The **canonical id** for a class is the bare's id. `bareIdOf(id, graph)` returns the bare id for a wrapper, self otherwise.
+- The `breakpoints: SvelteMap<number, { before: boolean; after: boolean }>` (in `MachineView`) holds canonical bare ids → per-kind state. Entries with both kinds off are pruned. `breakpointIndicatorSet` is the `$derived` set of "any kind set" canonical ids, passed to the indicator effect.
+- The **indicator effect** (in `MachineGraph`) renders the `mg-breakpoint` mark on every class member (bare + every wrapper sharing that bare via `bareStateId`): for each cached node, it normalizes the node's id via `bareIdOf` and checks the indicator set. The set is kind-agnostic — the future per-kind dots (Layer N) will use the Map directly.
+- The **highlight effect** uses an **asymmetric** expansion via `highlightExpand`:
+
+  | Source side | Returns | Why |
+  |---|---|---|
+  | Wrapper | `[wrapper, bare]` | wrapper-entry pause is the visually joined pair — light up both |
+  | Bare | `[bare]` only | when the engine is genuinely on the bare (loop iter), the wrapper isn't active |
+  | Regular state | `[self]` | no class membership |
+
+This means right-clicking a wrapper or a bare opens the menu over the same engine breakpoint class, both nodes show the indicator, but the strong-highlight only "leaks" wrapper → bare, never bare → wrappers.
+
+**Halt class.** The halt singleton (`id 0`) and every halt marker (`id < 0`, one per frame; see §1) form an additional equivalence class — they all collapse to the engine-wide `haltState` at runtime. `bareIdOf` maps any negative id to `0`; `equivalentIds(0, g)` returns `[0, ...all halt markers]`. The breakpoint Map stores canonical `0`; the indicator therefore lights up the singleton AND every halt marker simultaneously. `MachineView`'s `onToggleBreakpoint` also normalizes negative ids to `0` before forwarding to the worker, so the worker (which only has `id 0` in `collectStates`) sees a single canonical toggle regardless of which halt-class node the user right-clicked.
+
+**Class membership in the menu.** The context menu (§12) shows a "Shared with: …" info line listing other class members' names — so the user can see at a glance that flipping the BP also flips the sibling. For the halt class it instead shows "Global — affects all halts in the runtime", since `haltState` is a process-wide singleton rather than a per-graph state. Singleton classes (regular states, no wrappers / no sharing) omit the info line.
+
+## 3. CSS classes applied to SVG elements
+
+All classes are added imperatively by the apply-highlight or indicator `$effect`s in `MachineGraph.svelte`. Styling lives in the same component's `<style>` block; tokens in `app.css`.
+
+| Class | Target | When | Cleared by |
+|---|---|---|---|
+| `mg-breakpoint` | `g.node` | Set on every member of an equivalence class whose canonical id is in `breakpoints` | Indicator effect re-runs on `breakpoints` change |
+| `mg-highlight-from` | `g.node` (+ `'idle'` sentinel) | Source side of the just-fired or about-to-fire transition | Cleared at the top of every apply-highlight run |
+| `mg-highlight-to` | `g.node` | Destination side of same | Same |
+| `mg-highlight-strong` | `g.node` | The "focal" node of the highlight triple (set on the side matching `h.strong`, plus any class member via `highlightExpand` if source is wrapper) | Same |
+| `mg-highlight-edge` | `path` + `g.label` of edge | The edge connecting from→to in graph data-id space (`L_${from}_${to}_*`); also wrapper→bare "call" edge when `toEqIds` expanded the pair | Same |
+| `mg-frame-active` | `g.cluster` of a callable-subtree subgraph | The strong node (via canonical id) lives inside the frame — or the destination return chain detected a post-pop arrival from that frame | Same |
+| `mg-hl-arrow-shape` | inside cloned `<marker>` | Materialized once per render at cache-build time; switched in via `marker-end` swap on highlighted paths (browsers without `context-stroke`) | Marker swap reverts via `data-mg-orig-marker-end` on clear |
+
+## 4. `graphHighlight` shape (the input to the effect)
+
+Derived in `MachineView.svelte` from `(executionMode, currentStateId, nextStateId, prevStateId, pauseBefore, graph)`:
+
+```ts
+type GraphHighlight = {
+  fromId: number | 'idle';   // source-side node
+  toId: number | null;       // destination-side node; null = no destination
+  strong: 'from' | 'to' | null;
+  paused: boolean;           // true → eligible for pulse + revisit logic
+};
+```
+
+| Mode | `fromId` | `toId` | `strong` | `paused` |
+|---|---|---|---|---|
+| `RUNNING_AUTO` | `currentStateId` | `nextStateId` | `'from'` | `false` |
+| `RUNNING_PAUSED`, `pauseBefore = true` (debug.before fired) | `prevStateId ?? 'idle'` | `currentStateId` | `'to'` | `true` |
+| `RUNNING_PAUSED`, `pauseBefore = false` (Step / pause-after / click-pause) | `currentStateId` | `nextStateId` | `'from'` | `true` |
+| Anything else | `null` (no highlight) |
+
+`currentStateId` / `nextStateId` come from the worker's `paused` / `idle` / `stepped` responses (worker uses `m.state.id` for current, `nextStateIdFromYield` for next).
+
+## 5. Halt-target retargeting
+
+`toGraph` rewrites halt-bound transitions of in-frame states so they land on the **frame's halt marker** (id `= -frameId`), not the real `haltState` (id `0`). The engine's runtime, however, reports `nextState.id === 0` for any halt. The apply-highlight effect bridges:
+
+```
+if toId === 0 AND fromId is in some frame F → toId := -F
+```
+
+This makes the visible edge (`L_sX_cF_*`) the one that lights up. If `fromId` isn't in any frame (e.g. `writeMarker → halt` in the callable-subtree example), `toId` stays `0` and falls into the halt-singleton branch (§7).
+
+## 6. Source return chain (engine just halted into a frame)
+
+Fires when `toId < 0` (an in-frame halt marker). The engine will pop the stack and resume at the wrapper's override. To visualize the post-pop trajectory **before** the next iter relocates the strong node:
+
+- Highlight the return arrow `L_w_${F}_s${wrapperId}` (dotted).
+- Mark each wrapper of frame F with `mg-highlight-to`.
+- Highlight each wrapper's call-target-replacement edge `L_s${wrapperId}_s${overrideId}` and the override node.
+
+When multiple wrappers share the bare, the demo highlights all of them — the engine's runtime choice depends on stack state, which the demo doesn't track.
+
+## 7. Destination return chain (engine just resumed at an override-target)
+
+Mirror of §6, fires when `toId > 0` AND `fromId` is in some frame F AND any wrapper of F has `overriddenHaltStateId === toId`. The engine *just popped* and is paused/running at the override. The straight `bare → override` edge doesn't exist in the graph — light up the actual visible path:
+
+- bare (`fromId`, gets `mg-highlight-from` from the standard pass)
+- bare → halt-marker edge `L_s${fromId}_c${F}`
+- halt-marker `c${F}` with `mg-highlight-to`
+- return arrow `L_w_${F}_s${wrapperId}` (dotted)
+- wrapper with `mg-highlight-to`
+- wrapper → override edge `L_s${wrapperId}_s${toId}`
+- override (= `toId`, gets `mg-highlight-to` + strong from standard pass)
+- frame F's cluster gets `mg-frame-active` (strong node lives outside the frame, so the frame-highlight pass otherwise wouldn't fire)
+
+## 8. Halt singleton (`toId === 0` with no retarget)
+
+If §5's retarget didn't fire (because `fromId` isn't in a frame), `toId` stays `0`. The halt-singleton node is then highlighted via a direct lookup `nodeCache.get(0)` instead of the normal `highlightExpand` path (which skips `id <= 0`). Without this branch the leading edge would light up while the singleton stays grey — visually orphaned.
+
+## 9. Frame-active rule
+
+`mg-frame-active` lights the cluster border of a callable-subtree subgraph. Fires when **either**:
+
+- the strong node's canonical id (`bareIdOf(strongId)`) lives inside the frame (`nodeFrameMap.get`), OR
+- the destination return chain (§7) detected a post-pop arrival from that frame.
+
+The first case handles "we're executing inside the subroutine"; the second handles "we just left the subroutine but the return-chain is still visualized."
+
+## 10. Wrapper-entry call-edge highlight
+
+When the to-side expansion via `highlightExpand` produced `[wrapper, bare]` (length 2), the connector between them is the wrapper→bare **call edge** `L_s${wrapperId}_s${bareId}`. The standard `highlightEdgeByDataId(fromKey, toKey)` call uses `toKey = s${wrapper}` so it wouldn't pick up this edge. An explicit follow-up call highlights it so the joined visual pair has a visible connector.
+
+## 11. Pause-revisit pulse
+
+A short opacity pulse fires on the strong element when the current paused event lands on the same state as the **immediately previous** paused event. Implementation:
+
+- `lastPausedStrongId: number | 'idle' | null` stored at module scope.
+- After applying highlight, if `h.paused && strongId === lastPausedStrongId`, call `strongEl.animate(...)`.
+- If `h.paused`, write `strongId` to `lastPausedStrongId`.
+
+**Important: use the raw `strongId`, NOT the canonical bare-id.** Wrapper-pause and bare-pause are visually distinct events even though they share `#debugRef`; pausing at the wrapper then continuing into the bare must NOT pulse (the engine moved between two different nodes). The frame-highlight pass uses the canonical for its lookup, but the pulse comparison uses the raw id.
+
+Idle events (`h.paused === false`) never update `lastPausedStrongId`, so an `idle` that happens to report the same state doesn't poison the next paused-event comparison.
+
+## 12. Right-click handling + listener lifecycle
+
+The cache-build `$effect` walks the rendered SVG and attaches a `contextmenu` listener to every `g.node` whose key is a number (positive state, halt singleton `0`, or negative halt marker — only the synthetic `'idle'` string sentinel is skipped). Left-click stays native (text selection, focus, scroll-tap) — only right-click opens the BP menu, matching IDE convention. Halt nodes participate so the user can set / clear the global haltState breakpoint from any halt-class node (see §2's halt-class paragraph); the per-kind menu items dispatch through `MachineView.onToggleBreakpoint`, which canonicalizes negative ids → `0` before the runner sees them. Because mermaid's `lastSource` cache can skip a re-render when the source is byte-identical (so the SAME DOM persists across builds), the effect must NOT just re-attach — that stacks listeners and a single right-click would trigger N menu opens.
+
+Pattern:
+
+1. Module-scope `clickListenersController: AbortController | null = null`.
+2. At the top of each cache-build pass: `clickListenersController?.abort()` (removes ALL listeners attached with that signal), then `new AbortController()`.
+3. Pass `{ signal }` to every `addEventListener`.
+4. Component unmount aborts in `onMount`'s cleanup.
+
+The right-click handler `preventDefault`s the native context menu, then sets `menuStateId`, `menuX`, `menuY` to render a custom menu at the cursor.
+
+### Menu state + lifecycle
+
+The menu is two `<button role="menuitem">` items inside a `<div role="menu">`, positioned `fixed` at clamped viewport coordinates. Items show `☑`/`☐` based on the current `before` / `after` bits in `breakpointKinds.get(bareIdOf(stateId))`. Picking an item calls `runner.toggleBreakpoint(stateId, kind)` and closes the menu. The worker echoes `breakpointToggled` with the same `kind`, which updates the `breakpoints` Map via `runner.onBreakpointToggled`.
+
+Closing happens via:
+- Picking a menu item (fires `onclick`, then `closeMenu`).
+- ESC keydown (global handler installed while menu open).
+- Outside `mousedown` (global handler; `mousedown` not `click` so item picks land first).
+
+A separate `AbortController` (`menuOutsideController`) gates the global handlers so they detach cleanly when the menu closes or the component unmounts.
+
+### Edge-clamped positioning
+
+After the menu mounts, a `$effect` measures `menuEl.getBoundingClientRect()` and shifts the position so the menu fits in the viewport (8px margin from each edge). The raw `menuX/menuY` are the right-click coordinates; the clamped `menuClampedX/menuClampedY` are what feed the inline `left`/`top` style. Re-runs when the raw coords change (subsequent right-click on a different node).
+
+## 13. Breakpoint replay across builds
+
+Building a new worker creates fresh State instances — any `debug.before`/`debug.after` set on the previous instances is gone. The `breakpoints` Map in `MachineView` is **user intent**, not run state, and survives:
+
+```ts
+async function reloadWorker(source = code) {
+  // ... await runner.build(source) ...
+  // Prune ids that don't exist in the new graph (user edited code).
+  for (const id of [...breakpoints.keys()]) {
+    if (!res.graph.nodes[id]) breakpoints.delete(id);
+  }
+  // Replay surviving kinds via toggleBreakpoint. Fresh States have no
+  // debug set, so each toggle flips off→on. One call per stored kind per
+  // class — the canonical-id keying prevents double-flips of the shared
+  // #debugRef.
+  for (const [id, kinds] of breakpoints) {
+    if (kinds.before) runner.toggleBreakpoint(id, 'before');
+    if (kinds.after) runner.toggleBreakpoint(id, 'after');
+  }
+}
+```
+
+On build **failure** the Map IS cleared — there's no graph to prune against.
+
+The runner's echo `onBreakpointToggled` normalizes the echoed `stateId` via `bareIdOf(graph)` and updates only the matching `kind` bit, so the Map always holds canonical ids regardless of which class member the user actually right-clicked.
+
+## 13a. After-fire + Step: synthetic-pause suppression
+
+The engine's `onIter` fires at end-of-iter — functionally the same execution point as an `onPause(after, K)` fire (both happen after the iter's transition has executed and `onStep` has run). When a user clicks Step from inside an after-fire BP pause, the worker's `onIterFn` would otherwise dispatch a SECOND synthetic pause at the same effective point, producing a duplicate log entry.
+
+Suppression: `onPauseFn` sets `dispatchedAfterThisIter = true` whenever the engine pause is after-side (`m.pause?.side === 'after'`). `onIterFn` reads the flag (and resets it) at iter boundary; when set AND `stepRequested` is true, it skips the synthetic dispatch **but keeps `stepRequested`** so the NEXT iter's `onIter` pauses naturally. Net effect: Step from an after-fire BP advances one iter (the right semantic for "next pause point"), instead of bouncing twice at the same point.
+
+`before`-fires don't set the flag — they fire mid-iter, distinct from end-of-iter, so the synthetic at end-of-iter is a genuinely different pause point and isn't suppressed.
+
+## 14. Worker-side wrapper handling (`onPauseFn`)
+
+The engine fires `onPause` on BOTH the wrapper entry (iter K) and the immediately following bare entry (iter K+1) when the shared `#debugRef.before === true`. The worker pauses at the wrapper (the user-facing call site) and suppresses ONE following bare entry via `pendingJoinedBareId: number | null`:
+
+```
+1. onPause(wrapper):  if node.isWrapper && node.bareStateId !== null:
+                        pendingJoinedBareId := bareStateId; dispatchPause
+2. onPause(bare):     if state.id === pendingJoinedBareId:
+                        clear flag; skip dispatch
+3. onPause(bare K+2): pendingJoinedBareId === null; dispatch normally
+```
+
+Subsequent bare→bare loop iters pause normally — that's a real iteration, not a joined entry.
+
+Also: when pausing at a wrapper, the worker swaps the dispatched `state` field to the bare's `name` (looked up via `currentGraph.nodes[bareStateId].name`). The log reads `paused at state walkToBlank ...` instead of `paused at state walkToBlank(writeMarker) ...` — the composite is engine implementation.
+
+`currentGraph` is the engine-v7 `Graph` snapshot captured at build time and retained worker-side specifically so `onPauseFn` can ask `isWrapper?` and look up names. Cleared in `reset()`.
+
+## 15. Post-machine differences
+
+`@post-machine-js/machine` installs an `Object.defineProperty` lockdown on every non-halt PostMachine-constructed State's `debug` property that funnels DIRECT writes through Post's registry (`pm.setBreakpoint` for un-shared, throw for shared). `haltState` is NOT locked — direct `turing.haltState.debug = boolean` writes go straight to the engine setter (post dropped the module-load halt lockdown alongside engine #207). Post wraps `run`'s `onPause` to filter via that registry — pauses fire only when the registered breakpoint matches.
+
+**Direct mutation of the engine's `DebugConfig` (e.g. `state.debug.before = true`) bypasses Post's lockdown** because the getter passes through; Post's wrapper then filters the engine's onPause out entirely. The worker's `toggleBreakpoint` therefore uses the SETTER form, reading both kinds and writing the merged shape so toggling one doesn't lose the other:
+
+```ts
+const debug = entry.state.debug;
+const currentBefore = debug.before === true;
+const currentAfter = debug.after === true;
+const newBefore = req.kind === 'before' ? !currentBefore : currentBefore;
+const newAfter = req.kind === 'after' ? !currentAfter : currentAfter;
+entry.state.debug = null;  // clear first — see below
+if (newBefore || newAfter) {
+  entry.state.debug = {
+    ...(newBefore ? { before: true } : {}),
+    ...(newAfter ? { after: true } : {}),
+  };
+}
+```
+
+The intermediate `state.debug = null` is **required for Post**: Post's lockdown's setter PUSHES onto the `#breakpoints` array rather than replacing, so without the clear, repeated toggles accumulate stale entries. Turing's setter just creates a fresh DebugConfig either way — the null assignment is a no-op for Turing but essential for Post.
+
+- Turing: setter creates/clears the engine's `DebugConfig` normally.
+- Post: setter is intercepted, routed to `pm.setBreakpoint(path, filter)` or `pm.clearBreakpoint(path)` — registry updated, lockdown's internal write via `withLockdownEscape` then updates the engine ref.
+
+Branchless form works for both engines.
+
+## 16. Quick rules summary
+
+A condensed cheat-sheet for the apply-highlight effect's decisions:
+
+```
+expand from-side via highlightExpand(fromId)            # asymmetric: wrapper → [wrapper, bare]
+expand to-side via highlightExpand(toId) if toId > 0    # bare stays alone
+
+mark fromEqIds as highlight-from (+ strong if h.strong === 'from')
+mark toEqIds as highlight-to    (+ strong if h.strong === 'to')
+
+mark halt-marker  (toId < 0) directly with highlight-to (+ strong if matching)
+mark halt-singleton (toId === 0) directly with highlight-to (+ strong if matching)
+
+highlight edge L_{fromKey}_{toKey}
+if toEqIds had wrapper+bare: also highlight L_s{wrapper}_s{bare}  (call edge)
+
+if toId < 0:    source return chain    (halt-marker entry → wrappers → overrides)
+if toId > 0 AND fromFrame matches some wrapper.overrideId:
+                destination return chain  (bare → halt-marker → wrapper → override; frame active)
+
+mark frame active for canonical(strongId)
+
+if h.paused AND strongId === lastPausedStrongId: pulse strongEl
+if h.paused: lastPausedStrongId := strongId           # raw, not canonical
+```

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@turing-machine-js/visuals",
+  "version": "7.0.0-alpha.6",
+  "description": "Pure highlight + graph-indexing logic for @turing-machine-js/machine — no DOM, no renderer.",
+  "engines": {
+    "npm": ">=7.0.0"
+  },
+  "author": "Ruslan Gilmullin <mellonis@yandex.ru>",
+  "homepage": "https://github.com/mellonis/turing-machine-js#readme",
+  "license": "GPL-3.0-or-later",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mellonis/turing-machine-js.git",
+    "directory": "packages/visuals"
+  },
+  "bugs": {
+    "url": "https://github.com/mellonis/turing-machine-js/issues?utf8=✓&q=is%3Aissue+is%3Aopen+label%3A%22pkg%3A+visuals%22+label%3Abug"
+  },
+  "keywords": [
+    "turing",
+    "machine",
+    "visualization"
+  ],
+  "peerDependencies": {
+    "@turing-machine-js/machine": "^7.0.0-alpha.6"
+  },
+  "scripts": {
+    "build": "tsc --build --verbose tsconfig.build.json && node ../../scripts/build-node-entries.mjs --package=@turing-machine-js/visuals",
+    "prepublishOnly": "npm run build"
+  },
+  "main": "dist/index.cjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "gitHead": "7801a33fef2f6c30cf6e1c2780b1fbf58685f064"
+}