v7 release: composition-representation overhaul

README.md

@@ -12,6 +12,7 @@ This repository contains the following packages:
 * [@turing-machine-js/library-binary-numbers](https://github.com/mellonis/turing-machine-js/tree/master/packages/library-binary-numbers) — binary arithmetic on a 5-symbol alphabet (` ^$01`) supporting multiple numbers per tape, with `plusOne`, `minusOne`, `minusOneFast`, `invertNumber`, `normalizeNumber`, and inter-number navigation.
 * [@turing-machine-js/library-binary-numbers-bare](https://github.com/mellonis/turing-machine-js/tree/master/packages/library-binary-numbers-bare) — the same arithmetic on a 3-symbol alphabet (` 01`), single-number-per-tape. Side-by-side with the marker-based library to make the alphabet-size vs state-graph-size trade-off visible.
 * [@turing-machine-js/builder](https://github.com/mellonis/turing-machine-js/tree/master/packages/builder) — declarative state-table construction. Not actively developed; the same pattern is shown inline in `@turing-machine-js/machine`'s README.
+* [@turing-machine-js/visuals](https://github.com/mellonis/turing-machine-js/tree/master/packages/visuals) (v7+) — pure highlight + graph-indexing logic for the engine `Graph`: `applyHighlight` / `applyIndicator` against a renderer-agnostic `HighlightOps` interface, `bareIdOf` / `highlightExpand` for wrapper/bare canonicalization, `formatStepNotation` / `tokenizeStep` / `formatTape` for engine-edge-label rendering (byte-identical to `toMermaid`), `recordSnippet` for prerecorded-playback artifacts. No DOM, no Svelte, no Mermaid — consumers bring their own renderer.
 
 # An example
 
@@ -74,35 +75,29 @@ console.log(tape.symbols.join('').trim()); // a*c*a
 
 ## How it runs
 
-Just one state — call it **S** — that loops on every cell, writing `*` whenever the head reads `b` and stopping at the trailing blank:
-
-```mermaid
-flowchart LR
-    S(("**S**"))
-    H((("**halt**")))
-    S -- "b → *, R" --> S
-    S -- "_ → keep, L" --> H
-    S -- "any other → keep, R" --> S
-```
-
-*Reading the labels: `read → write, move`. `_` is the blank symbol.*
-
-<details>
-<summary>📊 Same diagram, generated by <code>toMermaid()</code> (the engine's actual output)</summary>
+Just one state — call it `replaceB` — that loops on every cell, writing `*` whenever the head reads `b` and stopping at the trailing blank. The engine emits its state graph via `toMermaid(toGraph(replaceB, tapeBlock))`:
 
 ```mermaid
 flowchart TD
 %% alphabets: [[" ","a","b","c","*"]]
   s0(((halt)))
-  s1(("replaceB"))
-  s1 -- "b → */R" --> s1
-  s1 -- "- → ·/L" --> s0
-  s1 -- "* → ·/R" --> s1
+  s1["replaceB"]
+  idle([idle])
+  idle -. enter .-> s1
+  s1 -- "['b'] → ['*']/[R]" --> s1
+  s1 -- "[B] → [K]/[L]" --> s0
+  s1 -- "[*] → [K]/[R]" --> s1
 ```
 
-Engine notation: `read → write/move`; `·` = keep, `*` = `ifOtherSymbol` catch-all, `-` = the blank symbol.
+Quick legend for the diagram above — full table at [packages/machine/README.md § Diagram conventions](packages/machine/README.md#diagram-conventions):
 
-</details>
+- **Edge format**: `[reads] → [writes]/[moves]` (each `[…]` is a tape-block reading; brackets always, even single-tape).
+- **Read cells**: `'X'` (literal, single-quoted), `*` (`ifOtherSymbol` catch-all), `B` (the tape's blank).
+- **Write cells**: `'X'` (literal), `K` (keep), `E` (erase = write blank).
+- **Movement cells**: `L` / `R` / `S` (left / right / stay).
+- **Node shapes**: `(((halt)))` = halt, `["square"]` = regular state or callable-subtree bare, `[[double-walled]]` = `withOverriddenHaltState` wrapper (call site), `idle([idle])` = pre-execution sentinel.
+- **Edges**: `-->` regular transition (and wrapper → override target), `==> "call"` = bold call arrow from wrapper to bare (`&` ribbons collapse multi-wrapper-shares-bare), `-. "return" .->` / `-. "halt" .->` from subgraph = frame-level dispatch, `-. enter .->` from `idle` = where execution starts.
+- **Subgraph `w_N["callable subtree of NAME"]`** wraps a bare + its body + a halt marker — see [§Subroutine composition](packages/machine/README.md#subroutine-composition-with-withoverriddenhaltstate) in the engine README.
 
 Trace on the input tape `abcba`: