@turing-machine-js/machine 7.0.0-alpha.2 → 7.0.0-alpha.3

package/CHANGELOG.md

@@ -4,6 +4,46 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [7.0.0-alpha.3] - 2026-05-21
+
+Third v7 pre-release. Adds first-class out-of-band tags on `State` ([#186](https://github.com/mellonis/turing-machine-js/issues/186)) — a metadata channel for visualization grouping and debugger labels that survives `toGraph` / `fromGraph` / `toMermaid` / `fromMermaid` round-trips. Driven by downstream [post-machine-js#86](https://github.com/mellonis/post-machine-js/issues/86), which will build a path-based registry and inline pseudo-command on top once this ships. Published under the `next` dist-tag: `npm install @turing-machine-js/machine@next`.
+
+**Pre-release — the API surface may still shift before stable v7.0.0.** Pin to a specific alpha for reproducibility: `@turing-machine-js/machine@7.0.0-alpha.3`.
+
+### Added
+
+- **`State.tag(...) / .untag(...) / .tags` API** ([#186](https://github.com/mellonis/turing-machine-js/issues/186)). Fluent post-construct API for attaching string tags to a State. Tags are out-of-band metadata — they don't affect runtime transition lookup, `equivalentOn` comparisons, or any structural identity. Storage lives on the State INSTANCE (not on the shared `#symbolToDataMap`), so engine [#175](https://github.com/mellonis/turing-machine-js/issues/175) memoization doesn't leak tags across wrappers that share a bare: `A.wohs(t1).tag('hot')` does NOT propagate to `A.wohs(t2)`.
+
+  ```ts
+  const s = new State({...}, 'foo')
+    .tag('hot', 'sampled')
+    .untag('sampled');
+  s.tags; // ['hot']  ← frozen snapshot, in insertion order
+  ```
+
+- **`GraphNode.tags: string[]`** ([#186](https://github.com/mellonis/turing-machine-js/issues/186)). New field on the serialized graph node. Survives `State.toGraph` / `State.fromGraph` round-trip; empty array for untagged states.
+
+- **`toMermaid` tag rendering** ([#186](https://github.com/mellonis/turing-machine-js/issues/186)). Two surfaces:
+  - **Visible labels via `<br>`**: tagged node labels include the tag names inline (`s5["A<br>hot, sampled"]`). Uses Mermaid's universal `<br>` line break — works across mermaid.js, the live editor, machines-demo, and any other renderer; no CSS-pseudo-element tricks.
+  - **Color grouping via `classDef` + `class`**: each unique tag gets a `classDef tag_<sanitized> fill:#...,stroke:#...` line (palette of 6 colors selected by tag-name hash) and a `class s5,s6 tag_<sanitized>` line listing every node carrying the tag.
+
+- **`fromMermaid` tag parse** ([#186](https://github.com/mellonis/turing-machine-js/issues/186)). Splits the node label on `<br>` to extract tags as the source of truth; `class` lines are decorative and discarded on parse (they regenerate on the next `toMermaid` emit from the tag set).
+
+### Compatibility
+
+- Peer dep `@turing-machine-js/machine` widened `^7.0.0-alpha.2` → `^7.0.0-alpha.3` on `@turing-machine-js/builder`, `@turing-machine-js/library-binary-numbers`, `@turing-machine-js/library-binary-numbers-bare`.
+
+### Migration from alpha.2
+
+Purely additive — no breaking changes. Existing code that doesn't call `state.tag(...)` or read `state.tags` / `GraphNode.tags` continues to work identically. Mermaid emit for untagged states is bytewise unchanged.
+
+If you serialize `GraphNode` JSON, note that the new `tags: string[]` field is now required by the type (always emitted; empty array if no tags).
+
+### Out of v7-alpha.3 (still pending for stable v7.0.0)
+
+- **[#102](https://github.com/mellonis/turing-machine-js/issues/102)** — debugger step-in / step-out / step-over primitives.
+- **[#180](https://github.com/mellonis/turing-machine-js/issues/180)** — extract `State.toGraph`/`fromGraph` to its own module.
+
 ## [7.0.0-alpha.2] - 2026-05-21
 
 Second v7 pre-release. Refines alpha.1's `toMermaid` wrapped-state emit into the function-call model ([#174](https://github.com/mellonis/turing-machine-js/issues/174)) and adds two construction-time improvements to `withOverriddenHaltState` ([#175](https://github.com/mellonis/turing-machine-js/issues/175), [#176](https://github.com/mellonis/turing-machine-js/issues/176)). Published to npm under the `next` dist-tag: `npm install @turing-machine-js/machine@next`.

package/README.md

@@ -13,6 +13,7 @@ A composable Turing-machine engine for JavaScript: multi-tape, subroutine compos
 - [Building from a state table](#building-from-a-state-table)
 - [Classes](#classes) — [`Alphabet`](#alphabet) · [`Tape`](#tape) · [`TapeBlock`](#tapeblock) · [`TapeCommand`](#tapecommand) · [`Command`](#command) · [`State`](#state) · [`Reference`](#reference) · [`TuringMachine`](#turingmachine)
 - [Subroutine composition with `withOverriddenHaltState`](#subroutine-composition-with-withoverriddenhaltstate)
+- [State tags](#state-tags)
 - [Debugging breakpoints](#debugging-breakpoints)
 - [Special objects](#special-objects) — [`haltState`](#haltstate) · [`ifOtherSymbol`](#ifothersymbol) · [`movements`](#movements) · [`symbolCommands`](#symbolcommands)
 - [Introspection and testing](#introspection-and-testing)
@@ -427,6 +428,25 @@ flowchart TD
 
 Wrappers nest: `inner.withOverriddenHaltState(middle).withOverriddenHaltState(outer)` chains halt-redirects through `middle → outer → halt`. `library-binary-numbers/src/index.ts`'s `minusOne` (the `~(~x + 1)` composition) uses a 4-deep nest of wrappers.
 
+## State tags
+
+A State carries an optional set of string tags — out-of-band metadata for visualization grouping and debugger labels. Tags don't affect runtime transition lookup, `equivalentOn` comparisons, or any structural identity; they ride alongside the State.
+
+```ts
+const s = new State({...}, 'walkToBlank::1')
+  .tag('hot', 'subroutine-entry');
+
+s.tags; // readonly ['hot', 'subroutine-entry'] — frozen snapshot
+s.untag('hot');
+s.tags; // readonly ['subroutine-entry']
+```
+
+**Scoped to the wrapper instance.** Under [`withOverriddenHaltState` memoization (#175)](https://github.com/mellonis/turing-machine-js/issues/175), `A.wohs(t1)` and `A.wohs(t2)` are distinct wrapper instances even though they share `A`'s `#symbolToDataMap`. Tags live on the instance, so tagging one wrapper doesn't propagate to siblings sharing the same bare. Wrappers from `withOverriddenHaltState` start with an empty tag set (do not inherit from bare); the caller tags explicitly as needed.
+
+**Round-trip preserved.** `state.toGraph` writes the tag set to `GraphNode.tags`; `state.fromGraph` reads it back and reapplies. `toMermaid` renders tags two ways: inline in the node label (`sN["name<br>tag1, tag2"]`, universal Mermaid line break) and as `classDef tag_<sanitized>` + `class sN tag_<sanitized>` lines for color grouping. `fromMermaid` splits the label on `<br>` as source of truth; the `class` lines are decorative and discarded on parse.
+
+See [§Diagram conventions § Tags](#tags) for the full emit shape.
+
 ## Debugging breakpoints
 
 Any `State` can carry a runtime-mutable `debug` config that pauses execution at chosen points.
@@ -599,6 +619,15 @@ The `&` ribbon syntax (`s_W1 & s_W2 == "call" ==> s_A`) collapses multiple wrapp
 
 `subgraph w_N["callable subtree of NAME"] … end` wraps a bare + its body + a halt marker — the callable scope of code that runs when a wrapper "calls" the bare. Multi-bare frames (union-find merged from shared body states) use the label `"callable scope: A ∪ B"`.
 
+### Tags
+
+Tagged states (via `state.tag('hot', 'sampled')` — see [§State tags](#state-tags)) render two ways simultaneously:
+
+- **Inline in the node label**: `sN["name<br>tag1, tag2"]` — the `<br>` is Mermaid's universal line break, so the tags display as a second line under the state name in any renderer.
+- **As a color class**: `classDef tag_<sanitized> fill:#...,stroke:#...` per unique tag (6-color palette selected by tag-name hash), plus `class sN,sM tag_<sanitized>` listing all nodes carrying the tag. Lets the eye group related states by color even when their names are scattered across the diagram.
+
+The `<br>`-embedded label is the source of truth for `fromMermaid` round-trip; the `classDef`/`class` lines are decorative and regenerate on the next `toMermaid` emit. Tag-name sanitization in `classDef` identifiers: any char outside `[A-Za-z0-9_-]` is replaced with `_`. Labels preserve the raw tag names.
+
 ### Edge label format
 
 `[reads] → [writes]/[moves]`. Each bracketed list is a tape-block reading — one entry per tape; brackets always present, even single-tape.
@@ -654,7 +683,13 @@ API surface changes since v3, in past tense so the timing of each piece is expli
 - **v6.2** *(superseded by v6.3.0)* — widened `onStep`'s signature to `(m) => void | Promise<void>` and added an inline `await onStep(...)` in the run loop, enabling throttle-in-`onStep` patterns. This overturned the docstring-stated contract that `onStep` is sync (microtask-free); the right place for per-iter throttling is `onPause` with self-rearm (see [Throttle pattern](#throttle-pattern)). Restored in v6.3.0.
 - **v6.3** — `onStep` reverted to its v6.0–v6.1 sync contract — `(m) => void`, called synchronously inside the run loop. The Throttle pattern section documents the engine-native shape for per-iter throttle / "wait between iters" UIs. No other API changes.
 - **v6.4** — New **`onIter`** hook on `run()`: awaited, fires once at the end of every iter (after both `onPause` dispatches on the same yield), unaffected by the `debug` master switch. Use for per-iter throttle / animation / coordination needing a suspend point; complements the existing sync `onStep` (tracing) and conditional `onPause` (user breakpoints). Three-hook contract is now `onStep` (sync, mid-iter) / `onPause` (awaited, on `state.debug` match) / `onIter` (awaited, end-of-iter). Additive — peer-deps unchanged. The v6.3.0 README's `onPause`-rearm throttle workaround is superseded.
-- **v7** *(alpha 1, 2026-05-21)* — Composition-representation overhaul. **First pre-release on the `next` dist-tag:** `npm install @turing-machine-js/machine@next` (or pin `@7.0.0-alpha.1`). Stable v7.0.0 still pending [#102](https://github.com/mellonis/turing-machine-js/issues/102) (debugger step-in/over/out primitives). Landed in alpha.1:
+- **v7** *(latest alpha: alpha.3, 2026-05-21)* — Composition-representation overhaul + first-class state tags. **Pre-release on the `next` dist-tag:** `npm install @turing-machine-js/machine@next` (or pin `@7.0.0-alpha.3`). Stable v7.0.0 still pending [#102](https://github.com/mellonis/turing-machine-js/issues/102) (debugger step-in/over/out primitives). Highlights across alphas:
+
+  **alpha.3** — first-class **State tags** ([#186](https://github.com/mellonis/turing-machine-js/issues/186)). `state.tag(...) / .untag(...) / .tags` API; `GraphNode.tags: string[]` round-trips through `toGraph`/`fromGraph`; `toMermaid` emits tags two ways simultaneously — inline via `<br>` in node labels (`sN["name<br>tag1, tag2"]`) and as `classDef`/`class` for color grouping. Tags live on the State instance (not on the shared `#symbolToDataMap`), so engine [#175](https://github.com/mellonis/turing-machine-js/issues/175) memoization doesn't leak tags across wrappers sharing a bare. See [§State tags](#state-tags).
+
+  **alpha.2** — callable-subtree `toMermaid` emit refinement ([#174](https://github.com/mellonis/turing-machine-js/issues/174)). The wrapper is a separate `[[composite-name]]` node OUTSIDE the subgraph; the bare's reachable subtree becomes a `subgraph w_${frameId}["callable subtree of NAME"]` block. Frames computed via union-find — shared bares dedupe with `&` ribbons on call arrows. Bold `==> "call"` reserved for wrapper-to-bare; dotted `-.->` for frame dispatch (`return` / `halt` / `enter`). Plus engine memoization ([#175](https://github.com/mellonis/turing-machine-js/issues/175)) and nested-chain collapse ([#176](https://github.com/mellonis/turing-machine-js/issues/176)) for `.wohs()`.
+
+  **alpha.1** — initial v7 composition-representation overhaul:
   - **`withOverrodeHaltState` → `withOverriddenHaltState`** ([#149](https://github.com/mellonis/turing-machine-js/issues/149)). Grammar fix on a name introduced in 2019: the past-participle `overridden` fits the "with a halt-state that has been ___" naming idiom; `overrode` (simple past) didn't. Hard cutover — no deprecated alias. The getter (`state.overrodeHaltState` → `state.overriddenHaltState`) and the serialized `Graph` data field (`node.overrodeHaltStateId` → `node.overriddenHaltStateId`) rename in lockstep. Consumer migration: global find/replace `OverrodeHaltState` → `OverriddenHaltState` and `overrodeHaltState` → `overriddenHaltState`. Persisted `State.toGraph` JSON dumps would need the same field-rename treatment, but persistence isn't a known consumer pattern.
   - **Paren-based wrapped-state naming** ([#148](https://github.com/mellonis/turing-machine-js/issues/148)). `withOverriddenHaltState`'s composite name format changed from flat `bare>override` to nested `bare(override)`. Same nesting depth reads as `A(B(A))` (bare = `A`, override = `B(A)`) versus `A(B)(A)` (bare = `A(B)`, override = `A`) — two structurally-different wrap-trees that the old `>`-flat notation collided into the single string `A>B>A`. As a consequence, **user-provided state names must not contain `(` or `)`** — `State` now throws at construction time if a user passes such a name. The `>` character stays valid in user names (no longer reserved). The `inspect()` / `toGraph` / `toMermaid` outputs carry the new format. `states.md` files in `library-binary-numbers` regenerate accordingly.
   - **`toMermaid` callable-subtree emit** ([#174](https://github.com/mellonis/turing-machine-js/issues/174), supersedes the alpha.1 collapsed-bare shape from #138/#139). `withOverriddenHaltState` is modeled as a function call: the wrapper is a `[[composite-name]]` call site OUTSIDE any subgraph, the bare's reachable subtree becomes a `subgraph w_${frameId}["callable subtree of NAME"] … end` block containing the bare + body states + a per-frame halt marker `c${frameId}(((halt)))`. Frames are computed via union-find on bare-reachability — overlapping reach sets merge into a single union frame, so shared bares (`library-binary-numbers/minusOne`'s `invertNumber`) appear ONCE with `& `-joined call arrows from each wrapper. Bold `==> "call"` arrows are reserved for the wrapper-to-bare call; dotted `-.->` is reserved for frame-level dispatch (`return` / `halt` / `enter`). The retired `-. onHalt .->` keyword is replaced by a solid `--> override` arrow (just an ordinary transition under the call/return mental model). `GraphNode` gains `isWrapper`, `bareStateId`, `frameId` fields (and drops `isWrapped`). Bytewise round-trip stability now holds for all wrapped states including shared-bare cases (no per-context duplication).

package/dist/classes/State.d.ts

@@ -32,6 +32,24 @@ export default class State {
         before?: symbol[] | readonly symbol[] | true;
         after?: symbol[] | readonly symbol[] | true;
     } | null);
+    /**
+     * Add one or more tags to this State (#186). Tags are out-of-band metadata
+     * used by visualization (`toMermaid` emits `classDef`/`class` lines) and
+     * debugger tooling — they don't affect runtime transition lookup,
+     * `equivalentOn` comparisons, or any structural identity. Chainable.
+     */
+    tag(...tags: string[]): this;
+    /**
+     * Remove one or more tags from this State (#186). Untagging a tag the
+     * State doesn't carry is a no-op. Chainable.
+     */
+    untag(...tags: string[]): this;
+    /**
+     * Frozen snapshot of this State's current tags (#186). The returned array
+     * is `Object.freeze`d — mutating it throws in strict mode (which TS-emitted
+     * code uses). Order matches insertion order of the underlying Set.
+     */
+    get tags(): readonly string[];
     /** @internal — invoked by DebugConfig setters via module-private symbol. */
     [validateDebugFilter](fieldName: 'before' | 'after', filter: readonly symbol[] | true | undefined): void;
     getSymbol(tapeBlock: TapeBlock): symbol;

package/dist/index.cjs

@@ -689,7 +689,7 @@ var __classPrivateFieldGet$1 = (undefined && undefined.__classPrivateFieldGet) |
     if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
     return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
 };
-var _DebugConfig_ownerState, _DebugConfig_before, _DebugConfig_after, _a, _State_wrapperCache, _State_id, _State_name, _State_overriddenHaltState, _State_bareState, _State_symbolToDataMap, _State_debugRef;
+var _DebugConfig_ownerState, _DebugConfig_before, _DebugConfig_after, _a, _State_wrapperCache, _State_id, _State_name, _State_overriddenHaltState, _State_bareState, _State_symbolToDataMap, _State_debugRef, _State_tags;
 const ifOtherSymbol = Symbol('other symbol');
 // Module-private symbol used by DebugConfig setters to call State's validator
 // without exposing the validator on the public surface.
@@ -750,6 +750,14 @@ class State {
         // Note: toGraph / fromGraph deliberately do not serialize debug — debug is
         // a runtime concern, not part of the structural graph.
         _State_debugRef.set(this, { current: null });
+        // Out-of-band tags applied to this State (#186). Tags are visualization
+        // and debugger-tooling metadata — they don't affect runtime transition
+        // lookup or `equivalentOn` comparisons. Stored as a Set for de-duplication;
+        // exposed via the `tags` getter as a frozen array snapshot. Lives on the
+        // State INSTANCE so wrappers (from `withOverriddenHaltState`) carry tags
+        // independently of their bare's tag set — see the #175 sharing test in
+        // State.spec.ts.
+        _State_tags.set(this, new Set());
         if (stateDefinition) {
             const keys = Object.getOwnPropertyNames(stateDefinition);
             if (keys.length) {
@@ -833,8 +841,38 @@ class State {
         }
         __classPrivateFieldGet$1(this, _State_debugRef, "f").current = new DebugConfig(this, value);
     }
+    /**
+     * Add one or more tags to this State (#186). Tags are out-of-band metadata
+     * used by visualization (`toMermaid` emits `classDef`/`class` lines) and
+     * debugger tooling — they don't affect runtime transition lookup,
+     * `equivalentOn` comparisons, or any structural identity. Chainable.
+     */
+    tag(...tags) {
+        for (const t of tags) {
+            __classPrivateFieldGet$1(this, _State_tags, "f").add(t);
+        }
+        return this;
+    }
+    /**
+     * Remove one or more tags from this State (#186). Untagging a tag the
+     * State doesn't carry is a no-op. Chainable.
+     */
+    untag(...tags) {
+        for (const t of tags) {
+            __classPrivateFieldGet$1(this, _State_tags, "f").delete(t);
+        }
+        return this;
+    }
+    /**
+     * Frozen snapshot of this State's current tags (#186). The returned array
+     * is `Object.freeze`d — mutating it throws in strict mode (which TS-emitted
+     * code uses). Order matches insertion order of the underlying Set.
+     */
+    get tags() {
+        return Object.freeze([...__classPrivateFieldGet$1(this, _State_tags, "f")]);
+    }
     /** @internal — invoked by DebugConfig setters via module-private symbol. */
-    [(_State_id = new WeakMap(), _State_name = new WeakMap(), _State_overriddenHaltState = new WeakMap(), _State_bareState = new WeakMap(), _State_symbolToDataMap = new WeakMap(), _State_debugRef = new WeakMap(), validateDebugFilter)](fieldName, filter) {
+    [(_State_id = new WeakMap(), _State_name = new WeakMap(), _State_overriddenHaltState = new WeakMap(), _State_bareState = new WeakMap(), _State_symbolToDataMap = new WeakMap(), _State_debugRef = new WeakMap(), _State_tags = new WeakMap(), validateDebugFilter)](fieldName, filter) {
         if (filter === undefined)
             return;
         // #108 part 2: `.after` on haltState has no semantic anchor — halt is
@@ -999,6 +1037,7 @@ class State {
                         frameId: null,
                         transitions: [],
                         overriddenHaltStateId: null,
+                        tags: [...__classPrivateFieldGet$1(state, _State_tags, "f")],
                     };
                 }
                 continue;
@@ -1017,6 +1056,7 @@ class State {
                     frameId: null,
                     transitions: [],
                     overriddenHaltStateId: __classPrivateFieldGet$1(overrideTarget, _State_id, "f"),
+                    tags: [...__classPrivateFieldGet$1(state, _State_tags, "f")],
                 };
                 bareIds.add(__classPrivateFieldGet$1(bareState, _State_id, "f"));
                 queue.push(bareState);
@@ -1034,6 +1074,7 @@ class State {
                 frameId: null,
                 transitions: [],
                 overriddenHaltStateId: null,
+                tags: [...__classPrivateFieldGet$1(state, _State_tags, "f")],
             };
             nodes[__classPrivateFieldGet$1(state, _State_id, "f")] = node;
             let patternIx = 0;
@@ -1073,6 +1114,7 @@ class State {
                 frameId: null,
                 transitions: [],
                 overriddenHaltStateId: null,
+                tags: [...__classPrivateFieldGet$1(haltState, _State_tags, "f")],
             };
         }
         // Pass 2: For each bare, compute its forward-reachable set (following
@@ -1087,7 +1129,10 @@ class State {
                     continue;
                 }
                 const node = nodes[id];
-                if (!node || node.isHalt || node.isWrapper) {
+                // `nodes[id]` is always populated for `id` that the BFS reached, so
+                // a defensive `!node` check would be dead. `isHalt` / `isWrapper`
+                // are real boundaries — both stop reach-set expansion.
+                if (node.isHalt || node.isWrapper) {
                     continue;
                 }
                 reach.add(id);
@@ -1109,6 +1154,10 @@ class State {
         // sets share any state. Canonical representative = smallest bare-id in
         // the component.
         const ufParent = new Map();
+        // Note: no path compression. The union policy below ("smaller id always
+        // becomes root") keeps the tree flat — every union targets bares[0] as
+        // the root, so any node's parent IS the root. Walking up never exceeds
+        // one step. Path compression would be dead code under this invariant.
         const ufFind = (id) => {
             if (!ufParent.has(id)) {
                 ufParent.set(id, id);
@@ -1117,13 +1166,6 @@ class State {
             while (ufParent.get(root) !== root) {
                 root = ufParent.get(root);
             }
-            // Path compression
-            let cur = id;
-            while (ufParent.get(cur) !== root) {
-                const next = ufParent.get(cur);
-                ufParent.set(cur, root);
-                cur = next;
-            }
             return root;
         };
         const ufUnion = (a, b) => {
@@ -1194,6 +1236,7 @@ class State {
                 frameId,
                 transitions: [],
                 overriddenHaltStateId: null,
+                tags: [],
             };
         }
         return { initialId: __classPrivateFieldGet$1(initialState, _State_id, "f"), alphabets, nodes };
@@ -1265,6 +1308,9 @@ class State {
             // and assign `#name` directly to skip user-facing name validation.
             const bare = new _a(stateDefinition);
             __classPrivateFieldSet$1(bare, _State_name, node.name, "f");
+            if (node.tags.length > 0) {
+                bare.tag(...node.tags);
+            }
             bareStates[nodeId] = bare;
         }
         // Pass 3: resolve every node to its final State (memoized + cycle-safe).
@@ -1290,6 +1336,13 @@ class State {
                 const bare = getFinal(node.bareStateId);
                 const override = getFinal(node.overriddenHaltStateId);
                 state = bare.withOverriddenHaltState(override);
+                // Apply wrapper-scoped tags (#186). Tags don't leak across wrappers
+                // sharing a bare — the wrapper instance owns its own tag set, and
+                // engine #175 memoization returns the same instance for the same
+                // (bare, override) pair, so this is idempotent across rebuilds.
+                if (node.tags.length > 0) {
+                    state.tag(...node.tags);
+                }
             }
             else {
                 state = bareStates[nodeId];
@@ -1532,6 +1585,16 @@ function toMermaid(graph) {
             bucket.push(node);
         }
     }
+    // Build the visible-label string for a node — name plus, if tagged, a
+    // `<br>tag1, tag2, ...` suffix so the rendered Mermaid shows both. Tags
+    // are the source of truth on the GraphNode; `<br>` is the universal
+    // Mermaid line-break that works across renderers without `classDef`-
+    // pseudo-element hacks (#186).
+    const labelOf = (node) => {
+        if (node.tags.length === 0)
+            return node.name;
+        return `${node.name}<br>${node.tags.join(', ')}`;
+    };
     // 1. Emit top-level nodes (real halt, non-wrapper regulars outside any frame).
     for (const node of topLevelNodes) {
         const mid = mermaidIdFor(node.id);
@@ -1539,12 +1602,12 @@ function toMermaid(graph) {
             lines.push(`  ${mid}(((halt)))`);
         }
         else {
-            lines.push(`  ${mid}["${node.name}"]`);
+            lines.push(`  ${mid}["${labelOf(node)}"]`);
         }
     }
     // 2. Emit wrappers at top level.
     for (const wrapper of wrapperNodes) {
-        lines.push(`  ${mermaidIdFor(wrapper.id)}[["${wrapper.name}"]]`);
+        lines.push(`  ${mermaidIdFor(wrapper.id)}[["${labelOf(wrapper)}"]]`);
     }
     // 3. `idle` sentinel.
     lines.push('  idle([idle])');
@@ -1562,12 +1625,13 @@ function toMermaid(graph) {
         lines.push(`  subgraph ${frameSubgraphId(frameId)}["${label}"]`);
         // Inner nodes — sort by id for determinism.
         for (const node of (nodesByFrame.get(frameId) ?? []).slice().sort((a, b) => a.id - b.id)) {
-            lines.push(`    ${mermaidIdFor(node.id)}["${node.name}"]`);
+            lines.push(`    ${mermaidIdFor(node.id)}["${labelOf(node)}"]`);
         }
+        // Every frame has a halt marker — `State.toGraph`'s frame-emit pass
+        // creates one for each frame. Non-null assertion is safe; a defensive
+        // null check would be dead.
         const haltMarker = haltMarkerByFrame.get(frameId);
-        if (haltMarker) {
-            lines.push(`    ${mermaidIdFor(haltMarker.id)}(((halt)))`);
-        }
+        lines.push(`    ${mermaidIdFor(haltMarker.id)}(((halt)))`);
         lines.push('  end');
     }
     // 5. Enter arrow.
@@ -1620,29 +1684,31 @@ function toMermaid(graph) {
     for (const frameId of frameIds) {
         if (!haltMarkerHasIncoming.get(frameId))
             continue;
-        // Return arrow — collapsed `&` ribbon over all wrappers calling this frame.
+        // Return arrow — collapsed `&` ribbon over all wrappers calling this
+        // frame. Frames only exist because at least one wrapper's bareStateId
+        // points to a bare in the frame, so `callingWrappers` is always
+        // non-empty for any frame that reached this code path.
         const callingWrappers = wrapperNodes.filter((w) => {
-            if (w.bareStateId === null)
-                return false;
             const bare = graph.nodes[w.bareStateId];
-            return !!bare && bare.frameId === frameId;
+            return bare.frameId === frameId;
         });
-        if (callingWrappers.length > 0) {
-            const targets = callingWrappers
-                .slice()
-                .sort((a, b) => a.id - b.id)
-                .map((w) => mermaidIdFor(w.id))
-                .join(' & ');
-            lines.push(`  ${frameSubgraphId(frameId)} -. "return" .-> ${targets}`);
-        }
+        const targets = callingWrappers
+            .slice()
+            .sort((a, b) => a.id - b.id)
+            .map((w) => mermaidIdFor(w.id))
+            .join(' & ');
+        lines.push(`  ${frameSubgraphId(frameId)} -. "return" .-> ${targets}`);
         if (hasNonWrapperEntry.get(frameId)) {
             lines.push(`  ${frameSubgraphId(frameId)} -. "halt" .-> s0`);
         }
     }
     // 8. Wrapper-to-override arrows (regular solid).
+    //
+    // `wrapper.overriddenHaltStateId` is always non-null on wrapper nodes
+    // (set by `State.toGraph` for every `isWrapper: true` node — it's the
+    // wrapper's override target, which a wrapper by definition has). The
+    // non-null assertion is safe; a defensive null check would be dead.
     for (const wrapper of wrapperNodes) {
-        if (wrapper.overriddenHaltStateId === null)
-            continue;
         lines.push(`  ${mermaidIdFor(wrapper.id)} --> ${mermaidIdFor(wrapper.overriddenHaltStateId)}`);
     }
     // 9. Regular transitions for non-wrapper non-halt-marker non-halt nodes.
@@ -1658,14 +1724,75 @@ function toMermaid(graph) {
             lines.push(`  ${mermaidIdFor(node.id)} -- "${label}" --> ${mermaidIdFor(t.nextStateId)}`);
         }
     }
+    // 10. Tags (#186) — emit one `classDef tag_<name> fill:#...` per unique
+    //     tag across all nodes, then one `class <ids> tag_<name>` line per
+    //     tag listing every node that carries it (comma-joined for compact
+    //     emit). Tag-name → CSS-class identifier sanitization replaces any
+    //     char outside `[A-Za-z0-9_-]` with `_`; tag-name uniqueness in the
+    //     emit assumes user tags are already distinct after sanitization
+    //     (collisions are user error).
+    emitTagAnnotations(lines, nodes);
     return lines.join('\n');
 }
+// Default Mermaid `classDef` palette — 6 visually distinct fill+stroke pairs,
+// selected by tag-name hash so multi-tag diagrams look readable out of the
+// box without user configuration. Users who want different colors can edit
+// the emitted Mermaid before rendering or override post-emit.
+const TAG_PALETTE = [
+    ['#fef3c7', '#92400e'], // amber
+    ['#dbeafe', '#1e40af'], // blue
+    ['#dcfce7', '#166534'], // green
+    ['#fce7f3', '#9d174d'], // pink
+    ['#ede9fe', '#5b21b6'], // violet
+    ['#fee2e2', '#991b1b'], // red
+];
+function sanitizeTagName(tag) {
+    return tag.replace(/[^A-Za-z0-9_-]/g, '_');
+}
+function tagColor(tag) {
+    // Cheap deterministic hash — sum of char codes mod palette length. Stable
+    // across runs; same tag name always picks the same color.
+    let h = 0;
+    for (let i = 0; i < tag.length; i += 1) {
+        h = (h + tag.charCodeAt(i)) % TAG_PALETTE.length;
+    }
+    return TAG_PALETTE[h];
+}
+function emitTagAnnotations(lines, nodes) {
+    // Collect nodes per tag in node-id order so output is deterministic.
+    const nodesByTag = new Map();
+    for (const node of nodes) {
+        for (const tag of node.tags) {
+            let list = nodesByTag.get(tag);
+            if (!list) {
+                list = [];
+                nodesByTag.set(tag, list);
+            }
+            list.push(node.id);
+        }
+    }
+    if (nodesByTag.size === 0)
+        return;
+    const sortedTags = [...nodesByTag.keys()].sort();
+    for (const tag of sortedTags) {
+        const sanitized = sanitizeTagName(tag);
+        const [fill, stroke] = tagColor(tag);
+        lines.push(`  classDef tag_${sanitized} fill:${fill},stroke:${stroke}`);
+    }
+    for (const tag of sortedTags) {
+        const sanitized = sanitizeTagName(tag);
+        const ids = nodesByTag.get(tag).map((id) => mermaidIdFor(id)).join(',');
+        lines.push(`  class ${ids} tag_${sanitized}`);
+    }
+}
 // Helper: identify "the bare states" that anchor a frame's name. A bare is a
 // node referenced as some wrapper's `bareStateId`. Body states (also in-frame
 // but not bare) are excluded from the frame label.
+//
+// The caller in `toMermaid` only passes non-wrapper, non-halt-marker nodes
+// (wrappers go to a separate bucket; halt markers go to `haltMarkerByFrame`).
+// No defensive `isHalt` / `isWrapper` guards needed here.
 function isFrameBare(node, graph) {
-    if (node.isWrapper || node.isHalt)
-        return false;
     for (const other of Object.values(graph.nodes)) {
         if (other.isWrapper && other.bareStateId === node.id) {
             return true;
@@ -1707,6 +1834,33 @@ const haltArrowRegex = /^w_(\d+)\s+-\.\s+"halt"\s+\.->\s+s0$/;
 // First capture char anchored as \S to avoid polynomial backtracking between
 // the preceding \s* and a permissive (.+); see CodeQL js/polynomial-redos.
 const alphabetsRegex = /^%%\s*alphabets:\s*(\S.*)$/;
+// Tag annotation lines (#186). Matches both `classDef tag_<sanitized>` and
+// `class <id-list> tag_<sanitized>`. ClassDef declarations are decorative
+// (palette) and discarded on parse — toMermaid will regenerate them from
+// the tag set on re-emit. `class` lines carry the actual graph-node
+// assignments; we strip the `tag_` prefix and assign each tag to each
+// listed node's `tags` array.
+//
+// Inter-token gaps are fixed at single literal spaces (matching toMermaid's
+// canonical emit) rather than `\s+`. This avoids the polynomial-ReDoS
+// pattern CodeQL flags when `\s+` surrounds a content group (see also
+// `callArrowRegex` / `returnArrowRegex` tightening in PR #182).
+const classDefTagRegex = /^classDef tag_([A-Za-z0-9_-]+) .+$/;
+const classAssignTagRegex = /^class ([sc]\d+(?:,[sc]\d+)*) tag_([A-Za-z0-9_-]+)$/;
+// Splits a node label like `"A<br>hot, sampled"` into its name and tags (#186).
+// Labels without `<br>` have no tags. Tags are comma-joined; trimmed of
+// whitespace. The `<br>` is the single source of truth for tag-name parsing —
+// `class` lines are decorative-only and not consulted here.
+function splitLabelTags(label) {
+    const brIx = label.indexOf('<br>');
+    if (brIx < 0) {
+        return { name: label, tags: [] };
+    }
+    const name = label.slice(0, brIx);
+    const tagsStr = label.slice(brIx + '<br>'.length);
+    const tags = tagsStr.split(',').map((t) => t.trim()).filter((t) => t.length > 0);
+    return { name, tags };
+}
 function fromMermaid(text) {
     const lines = text.split('\n').map((l) => l.trim()).filter(Boolean);
     let alphabets = [];
@@ -1725,6 +1879,7 @@ function fromMermaid(text) {
                 frameId: opts.frameId ?? null,
                 transitions: [],
                 overriddenHaltStateId: null,
+                tags: opts.tags ? [...opts.tags] : [],
             };
         }
         else {
@@ -1740,6 +1895,12 @@ function fromMermaid(text) {
                 nodes[id].bareStateId = opts.bareStateId;
             if (opts.frameId !== undefined)
                 nodes[id].frameId = opts.frameId;
+            if (opts.tags !== undefined) {
+                for (const t of opts.tags) {
+                    if (!nodes[id].tags.includes(t))
+                        nodes[id].tags.push(t);
+                }
+            }
         }
         return nodes[id];
     };
@@ -1752,6 +1913,11 @@ function fromMermaid(text) {
             alphabets = JSON.parse(am[1]);
             continue;
         }
+        // Tag annotations (#186) — classDef lines are decorative and skipped;
+        // `class` lines are parsed in the edge pass since they reference nodes
+        // by id and need those nodes already created in the first pass.
+        if (classDefTagRegex.test(line))
+            continue;
         const sgStart = line.match(subgraphStartRegex);
         if (sgStart) {
             currentFrameId = Number(sgStart[1]);
@@ -1777,17 +1943,21 @@ function fromMermaid(text) {
         }
         const wm = line.match(wrappedNodeRegex);
         if (wm) {
+            const { name, tags } = splitLabelTags(wm[2]);
             ensureNode(parseMermaidId(wm[1]), {
-                name: wm[2],
+                name,
                 isWrapper: true,
+                tags,
             });
             continue;
         }
         const rm = line.match(regularNodeRegex);
         if (rm) {
+            const { name, tags } = splitLabelTags(rm[2]);
             ensureNode(parseMermaidId(rm[1]), {
-                name: rm[2],
+                name,
                 frameId: currentFrameId,
+                tags,
             });
             continue;
         }
@@ -1804,6 +1974,19 @@ function fromMermaid(text) {
         if (returnArrowRegex.test(line) || haltArrowRegex.test(line)) {
             continue;
         }
+        // Tag class-assignment line (#186): `class s1,s5 tag_hot` — adds
+        // the tag to each listed node. Tag-name preserved as written
+        // (sanitization on emit is lossy in principle; on parse we don't
+        // un-sanitize, since the original could have any characters).
+        const tagMatch = line.match(classAssignTagRegex);
+        if (tagMatch) {
+            const ids = tagMatch[1].split(',');
+            const tagName = tagMatch[2];
+            for (const idStr of ids) {
+                ensureNode(parseMermaidId(idStr), { tags: [tagName] });
+            }
+            continue;
+        }
         // `call` arrow — sets bareStateId on each source wrapper.
         const cm = line.match(callArrowRegex);
         if (cm) {
@@ -1820,7 +2003,12 @@ function fromMermaid(text) {
         if (wo) {
             const fromId = parseMermaidId(wo[1]);
             const toId = parseMermaidId(wo[2]);
-            if (nodes[fromId] && nodes[fromId].isWrapper) {
+            // The wrapper-override regex only matches `sN --> sM` (unlabeled);
+            // since `toMermaid` only emits this shape from wrappers, the source
+            // is guaranteed to be a wrapper if `fromMermaid`'s input came from
+            // `toMermaid`. `nodes[fromId]` is always populated (first pass emits
+            // node declarations before any edge parsing).
+            if (nodes[fromId].isWrapper) {
                 nodes[fromId].overriddenHaltStateId = toId;
                 continue;
             }

package/dist/index.mjs

@@ -687,7 +687,7 @@ var __classPrivateFieldGet$1 = (undefined && undefined.__classPrivateFieldGet) |
     if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
     return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
 };
-var _DebugConfig_ownerState, _DebugConfig_before, _DebugConfig_after, _a, _State_wrapperCache, _State_id, _State_name, _State_overriddenHaltState, _State_bareState, _State_symbolToDataMap, _State_debugRef;
+var _DebugConfig_ownerState, _DebugConfig_before, _DebugConfig_after, _a, _State_wrapperCache, _State_id, _State_name, _State_overriddenHaltState, _State_bareState, _State_symbolToDataMap, _State_debugRef, _State_tags;
 const ifOtherSymbol = Symbol('other symbol');
 // Module-private symbol used by DebugConfig setters to call State's validator
 // without exposing the validator on the public surface.
@@ -748,6 +748,14 @@ class State {
         // Note: toGraph / fromGraph deliberately do not serialize debug — debug is
         // a runtime concern, not part of the structural graph.
         _State_debugRef.set(this, { current: null });
+        // Out-of-band tags applied to this State (#186). Tags are visualization
+        // and debugger-tooling metadata — they don't affect runtime transition
+        // lookup or `equivalentOn` comparisons. Stored as a Set for de-duplication;
+        // exposed via the `tags` getter as a frozen array snapshot. Lives on the
+        // State INSTANCE so wrappers (from `withOverriddenHaltState`) carry tags
+        // independently of their bare's tag set — see the #175 sharing test in
+        // State.spec.ts.
+        _State_tags.set(this, new Set());
         if (stateDefinition) {
             const keys = Object.getOwnPropertyNames(stateDefinition);
             if (keys.length) {
@@ -831,8 +839,38 @@ class State {
         }
         __classPrivateFieldGet$1(this, _State_debugRef, "f").current = new DebugConfig(this, value);
     }
+    /**
+     * Add one or more tags to this State (#186). Tags are out-of-band metadata
+     * used by visualization (`toMermaid` emits `classDef`/`class` lines) and
+     * debugger tooling — they don't affect runtime transition lookup,
+     * `equivalentOn` comparisons, or any structural identity. Chainable.
+     */
+    tag(...tags) {
+        for (const t of tags) {
+            __classPrivateFieldGet$1(this, _State_tags, "f").add(t);
+        }
+        return this;
+    }
+    /**
+     * Remove one or more tags from this State (#186). Untagging a tag the
+     * State doesn't carry is a no-op. Chainable.
+     */
+    untag(...tags) {
+        for (const t of tags) {
+            __classPrivateFieldGet$1(this, _State_tags, "f").delete(t);
+        }
+        return this;
+    }
+    /**
+     * Frozen snapshot of this State's current tags (#186). The returned array
+     * is `Object.freeze`d — mutating it throws in strict mode (which TS-emitted
+     * code uses). Order matches insertion order of the underlying Set.
+     */
+    get tags() {
+        return Object.freeze([...__classPrivateFieldGet$1(this, _State_tags, "f")]);
+    }
     /** @internal — invoked by DebugConfig setters via module-private symbol. */
-    [(_State_id = new WeakMap(), _State_name = new WeakMap(), _State_overriddenHaltState = new WeakMap(), _State_bareState = new WeakMap(), _State_symbolToDataMap = new WeakMap(), _State_debugRef = new WeakMap(), validateDebugFilter)](fieldName, filter) {
+    [(_State_id = new WeakMap(), _State_name = new WeakMap(), _State_overriddenHaltState = new WeakMap(), _State_bareState = new WeakMap(), _State_symbolToDataMap = new WeakMap(), _State_debugRef = new WeakMap(), _State_tags = new WeakMap(), validateDebugFilter)](fieldName, filter) {
         if (filter === undefined)
             return;
         // #108 part 2: `.after` on haltState has no semantic anchor — halt is
@@ -997,6 +1035,7 @@ class State {
                         frameId: null,
                         transitions: [],
                         overriddenHaltStateId: null,
+                        tags: [...__classPrivateFieldGet$1(state, _State_tags, "f")],
                     };
                 }
                 continue;
@@ -1015,6 +1054,7 @@ class State {
                     frameId: null,
                     transitions: [],
                     overriddenHaltStateId: __classPrivateFieldGet$1(overrideTarget, _State_id, "f"),
+                    tags: [...__classPrivateFieldGet$1(state, _State_tags, "f")],
                 };
                 bareIds.add(__classPrivateFieldGet$1(bareState, _State_id, "f"));
                 queue.push(bareState);
@@ -1032,6 +1072,7 @@ class State {
                 frameId: null,
                 transitions: [],
                 overriddenHaltStateId: null,
+                tags: [...__classPrivateFieldGet$1(state, _State_tags, "f")],
             };
             nodes[__classPrivateFieldGet$1(state, _State_id, "f")] = node;
             let patternIx = 0;
@@ -1071,6 +1112,7 @@ class State {
                 frameId: null,
                 transitions: [],
                 overriddenHaltStateId: null,
+                tags: [...__classPrivateFieldGet$1(haltState, _State_tags, "f")],
             };
         }
         // Pass 2: For each bare, compute its forward-reachable set (following
@@ -1085,7 +1127,10 @@ class State {
                     continue;
                 }
                 const node = nodes[id];
-                if (!node || node.isHalt || node.isWrapper) {
+                // `nodes[id]` is always populated for `id` that the BFS reached, so
+                // a defensive `!node` check would be dead. `isHalt` / `isWrapper`
+                // are real boundaries — both stop reach-set expansion.
+                if (node.isHalt || node.isWrapper) {
                     continue;
                 }
                 reach.add(id);
@@ -1107,6 +1152,10 @@ class State {
         // sets share any state. Canonical representative = smallest bare-id in
         // the component.
         const ufParent = new Map();
+        // Note: no path compression. The union policy below ("smaller id always
+        // becomes root") keeps the tree flat — every union targets bares[0] as
+        // the root, so any node's parent IS the root. Walking up never exceeds
+        // one step. Path compression would be dead code under this invariant.
         const ufFind = (id) => {
             if (!ufParent.has(id)) {
                 ufParent.set(id, id);
@@ -1115,13 +1164,6 @@ class State {
             while (ufParent.get(root) !== root) {
                 root = ufParent.get(root);
             }
-            // Path compression
-            let cur = id;
-            while (ufParent.get(cur) !== root) {
-                const next = ufParent.get(cur);
-                ufParent.set(cur, root);
-                cur = next;
-            }
             return root;
         };
         const ufUnion = (a, b) => {
@@ -1192,6 +1234,7 @@ class State {
                 frameId,
                 transitions: [],
                 overriddenHaltStateId: null,
+                tags: [],
             };
         }
         return { initialId: __classPrivateFieldGet$1(initialState, _State_id, "f"), alphabets, nodes };
@@ -1263,6 +1306,9 @@ class State {
             // and assign `#name` directly to skip user-facing name validation.
             const bare = new _a(stateDefinition);
             __classPrivateFieldSet$1(bare, _State_name, node.name, "f");
+            if (node.tags.length > 0) {
+                bare.tag(...node.tags);
+            }
             bareStates[nodeId] = bare;
         }
         // Pass 3: resolve every node to its final State (memoized + cycle-safe).
@@ -1288,6 +1334,13 @@ class State {
                 const bare = getFinal(node.bareStateId);
                 const override = getFinal(node.overriddenHaltStateId);
                 state = bare.withOverriddenHaltState(override);
+                // Apply wrapper-scoped tags (#186). Tags don't leak across wrappers
+                // sharing a bare — the wrapper instance owns its own tag set, and
+                // engine #175 memoization returns the same instance for the same
+                // (bare, override) pair, so this is idempotent across rebuilds.
+                if (node.tags.length > 0) {
+                    state.tag(...node.tags);
+                }
             }
             else {
                 state = bareStates[nodeId];
@@ -1530,6 +1583,16 @@ function toMermaid(graph) {
             bucket.push(node);
         }
     }
+    // Build the visible-label string for a node — name plus, if tagged, a
+    // `<br>tag1, tag2, ...` suffix so the rendered Mermaid shows both. Tags
+    // are the source of truth on the GraphNode; `<br>` is the universal
+    // Mermaid line-break that works across renderers without `classDef`-
+    // pseudo-element hacks (#186).
+    const labelOf = (node) => {
+        if (node.tags.length === 0)
+            return node.name;
+        return `${node.name}<br>${node.tags.join(', ')}`;
+    };
     // 1. Emit top-level nodes (real halt, non-wrapper regulars outside any frame).
     for (const node of topLevelNodes) {
         const mid = mermaidIdFor(node.id);
@@ -1537,12 +1600,12 @@ function toMermaid(graph) {
             lines.push(`  ${mid}(((halt)))`);
         }
         else {
-            lines.push(`  ${mid}["${node.name}"]`);
+            lines.push(`  ${mid}["${labelOf(node)}"]`);
         }
     }
     // 2. Emit wrappers at top level.
     for (const wrapper of wrapperNodes) {
-        lines.push(`  ${mermaidIdFor(wrapper.id)}[["${wrapper.name}"]]`);
+        lines.push(`  ${mermaidIdFor(wrapper.id)}[["${labelOf(wrapper)}"]]`);
     }
     // 3. `idle` sentinel.
     lines.push('  idle([idle])');
@@ -1560,12 +1623,13 @@ function toMermaid(graph) {
         lines.push(`  subgraph ${frameSubgraphId(frameId)}["${label}"]`);
         // Inner nodes — sort by id for determinism.
         for (const node of (nodesByFrame.get(frameId) ?? []).slice().sort((a, b) => a.id - b.id)) {
-            lines.push(`    ${mermaidIdFor(node.id)}["${node.name}"]`);
+            lines.push(`    ${mermaidIdFor(node.id)}["${labelOf(node)}"]`);
         }
+        // Every frame has a halt marker — `State.toGraph`'s frame-emit pass
+        // creates one for each frame. Non-null assertion is safe; a defensive
+        // null check would be dead.
         const haltMarker = haltMarkerByFrame.get(frameId);
-        if (haltMarker) {
-            lines.push(`    ${mermaidIdFor(haltMarker.id)}(((halt)))`);
-        }
+        lines.push(`    ${mermaidIdFor(haltMarker.id)}(((halt)))`);
         lines.push('  end');
     }
     // 5. Enter arrow.
@@ -1618,29 +1682,31 @@ function toMermaid(graph) {
     for (const frameId of frameIds) {
         if (!haltMarkerHasIncoming.get(frameId))
             continue;
-        // Return arrow — collapsed `&` ribbon over all wrappers calling this frame.
+        // Return arrow — collapsed `&` ribbon over all wrappers calling this
+        // frame. Frames only exist because at least one wrapper's bareStateId
+        // points to a bare in the frame, so `callingWrappers` is always
+        // non-empty for any frame that reached this code path.
         const callingWrappers = wrapperNodes.filter((w) => {
-            if (w.bareStateId === null)
-                return false;
             const bare = graph.nodes[w.bareStateId];
-            return !!bare && bare.frameId === frameId;
+            return bare.frameId === frameId;
         });
-        if (callingWrappers.length > 0) {
-            const targets = callingWrappers
-                .slice()
-                .sort((a, b) => a.id - b.id)
-                .map((w) => mermaidIdFor(w.id))
-                .join(' & ');
-            lines.push(`  ${frameSubgraphId(frameId)} -. "return" .-> ${targets}`);
-        }
+        const targets = callingWrappers
+            .slice()
+            .sort((a, b) => a.id - b.id)
+            .map((w) => mermaidIdFor(w.id))
+            .join(' & ');
+        lines.push(`  ${frameSubgraphId(frameId)} -. "return" .-> ${targets}`);
         if (hasNonWrapperEntry.get(frameId)) {
             lines.push(`  ${frameSubgraphId(frameId)} -. "halt" .-> s0`);
         }
     }
     // 8. Wrapper-to-override arrows (regular solid).
+    //
+    // `wrapper.overriddenHaltStateId` is always non-null on wrapper nodes
+    // (set by `State.toGraph` for every `isWrapper: true` node — it's the
+    // wrapper's override target, which a wrapper by definition has). The
+    // non-null assertion is safe; a defensive null check would be dead.
     for (const wrapper of wrapperNodes) {
-        if (wrapper.overriddenHaltStateId === null)
-            continue;
         lines.push(`  ${mermaidIdFor(wrapper.id)} --> ${mermaidIdFor(wrapper.overriddenHaltStateId)}`);
     }
     // 9. Regular transitions for non-wrapper non-halt-marker non-halt nodes.
@@ -1656,14 +1722,75 @@ function toMermaid(graph) {
             lines.push(`  ${mermaidIdFor(node.id)} -- "${label}" --> ${mermaidIdFor(t.nextStateId)}`);
         }
     }
+    // 10. Tags (#186) — emit one `classDef tag_<name> fill:#...` per unique
+    //     tag across all nodes, then one `class <ids> tag_<name>` line per
+    //     tag listing every node that carries it (comma-joined for compact
+    //     emit). Tag-name → CSS-class identifier sanitization replaces any
+    //     char outside `[A-Za-z0-9_-]` with `_`; tag-name uniqueness in the
+    //     emit assumes user tags are already distinct after sanitization
+    //     (collisions are user error).
+    emitTagAnnotations(lines, nodes);
     return lines.join('\n');
 }
+// Default Mermaid `classDef` palette — 6 visually distinct fill+stroke pairs,
+// selected by tag-name hash so multi-tag diagrams look readable out of the
+// box without user configuration. Users who want different colors can edit
+// the emitted Mermaid before rendering or override post-emit.
+const TAG_PALETTE = [
+    ['#fef3c7', '#92400e'], // amber
+    ['#dbeafe', '#1e40af'], // blue
+    ['#dcfce7', '#166534'], // green
+    ['#fce7f3', '#9d174d'], // pink
+    ['#ede9fe', '#5b21b6'], // violet
+    ['#fee2e2', '#991b1b'], // red
+];
+function sanitizeTagName(tag) {
+    return tag.replace(/[^A-Za-z0-9_-]/g, '_');
+}
+function tagColor(tag) {
+    // Cheap deterministic hash — sum of char codes mod palette length. Stable
+    // across runs; same tag name always picks the same color.
+    let h = 0;
+    for (let i = 0; i < tag.length; i += 1) {
+        h = (h + tag.charCodeAt(i)) % TAG_PALETTE.length;
+    }
+    return TAG_PALETTE[h];
+}
+function emitTagAnnotations(lines, nodes) {
+    // Collect nodes per tag in node-id order so output is deterministic.
+    const nodesByTag = new Map();
+    for (const node of nodes) {
+        for (const tag of node.tags) {
+            let list = nodesByTag.get(tag);
+            if (!list) {
+                list = [];
+                nodesByTag.set(tag, list);
+            }
+            list.push(node.id);
+        }
+    }
+    if (nodesByTag.size === 0)
+        return;
+    const sortedTags = [...nodesByTag.keys()].sort();
+    for (const tag of sortedTags) {
+        const sanitized = sanitizeTagName(tag);
+        const [fill, stroke] = tagColor(tag);
+        lines.push(`  classDef tag_${sanitized} fill:${fill},stroke:${stroke}`);
+    }
+    for (const tag of sortedTags) {
+        const sanitized = sanitizeTagName(tag);
+        const ids = nodesByTag.get(tag).map((id) => mermaidIdFor(id)).join(',');
+        lines.push(`  class ${ids} tag_${sanitized}`);
+    }
+}
 // Helper: identify "the bare states" that anchor a frame's name. A bare is a
 // node referenced as some wrapper's `bareStateId`. Body states (also in-frame
 // but not bare) are excluded from the frame label.
+//
+// The caller in `toMermaid` only passes non-wrapper, non-halt-marker nodes
+// (wrappers go to a separate bucket; halt markers go to `haltMarkerByFrame`).
+// No defensive `isHalt` / `isWrapper` guards needed here.
 function isFrameBare(node, graph) {
-    if (node.isWrapper || node.isHalt)
-        return false;
     for (const other of Object.values(graph.nodes)) {
         if (other.isWrapper && other.bareStateId === node.id) {
             return true;
@@ -1705,6 +1832,33 @@ const haltArrowRegex = /^w_(\d+)\s+-\.\s+"halt"\s+\.->\s+s0$/;
 // First capture char anchored as \S to avoid polynomial backtracking between
 // the preceding \s* and a permissive (.+); see CodeQL js/polynomial-redos.
 const alphabetsRegex = /^%%\s*alphabets:\s*(\S.*)$/;
+// Tag annotation lines (#186). Matches both `classDef tag_<sanitized>` and
+// `class <id-list> tag_<sanitized>`. ClassDef declarations are decorative
+// (palette) and discarded on parse — toMermaid will regenerate them from
+// the tag set on re-emit. `class` lines carry the actual graph-node
+// assignments; we strip the `tag_` prefix and assign each tag to each
+// listed node's `tags` array.
+//
+// Inter-token gaps are fixed at single literal spaces (matching toMermaid's
+// canonical emit) rather than `\s+`. This avoids the polynomial-ReDoS
+// pattern CodeQL flags when `\s+` surrounds a content group (see also
+// `callArrowRegex` / `returnArrowRegex` tightening in PR #182).
+const classDefTagRegex = /^classDef tag_([A-Za-z0-9_-]+) .+$/;
+const classAssignTagRegex = /^class ([sc]\d+(?:,[sc]\d+)*) tag_([A-Za-z0-9_-]+)$/;
+// Splits a node label like `"A<br>hot, sampled"` into its name and tags (#186).
+// Labels without `<br>` have no tags. Tags are comma-joined; trimmed of
+// whitespace. The `<br>` is the single source of truth for tag-name parsing —
+// `class` lines are decorative-only and not consulted here.
+function splitLabelTags(label) {
+    const brIx = label.indexOf('<br>');
+    if (brIx < 0) {
+        return { name: label, tags: [] };
+    }
+    const name = label.slice(0, brIx);
+    const tagsStr = label.slice(brIx + '<br>'.length);
+    const tags = tagsStr.split(',').map((t) => t.trim()).filter((t) => t.length > 0);
+    return { name, tags };
+}
 function fromMermaid(text) {
     const lines = text.split('\n').map((l) => l.trim()).filter(Boolean);
     let alphabets = [];
@@ -1723,6 +1877,7 @@ function fromMermaid(text) {
                 frameId: opts.frameId ?? null,
                 transitions: [],
                 overriddenHaltStateId: null,
+                tags: opts.tags ? [...opts.tags] : [],
             };
         }
         else {
@@ -1738,6 +1893,12 @@ function fromMermaid(text) {
                 nodes[id].bareStateId = opts.bareStateId;
             if (opts.frameId !== undefined)
                 nodes[id].frameId = opts.frameId;
+            if (opts.tags !== undefined) {
+                for (const t of opts.tags) {
+                    if (!nodes[id].tags.includes(t))
+                        nodes[id].tags.push(t);
+                }
+            }
         }
         return nodes[id];
     };
@@ -1750,6 +1911,11 @@ function fromMermaid(text) {
             alphabets = JSON.parse(am[1]);
             continue;
         }
+        // Tag annotations (#186) — classDef lines are decorative and skipped;
+        // `class` lines are parsed in the edge pass since they reference nodes
+        // by id and need those nodes already created in the first pass.
+        if (classDefTagRegex.test(line))
+            continue;
         const sgStart = line.match(subgraphStartRegex);
         if (sgStart) {
             currentFrameId = Number(sgStart[1]);
@@ -1775,17 +1941,21 @@ function fromMermaid(text) {
         }
         const wm = line.match(wrappedNodeRegex);
         if (wm) {
+            const { name, tags } = splitLabelTags(wm[2]);
             ensureNode(parseMermaidId(wm[1]), {
-                name: wm[2],
+                name,
                 isWrapper: true,
+                tags,
             });
             continue;
         }
         const rm = line.match(regularNodeRegex);
         if (rm) {
+            const { name, tags } = splitLabelTags(rm[2]);
             ensureNode(parseMermaidId(rm[1]), {
-                name: rm[2],
+                name,
                 frameId: currentFrameId,
+                tags,
             });
             continue;
         }
@@ -1802,6 +1972,19 @@ function fromMermaid(text) {
         if (returnArrowRegex.test(line) || haltArrowRegex.test(line)) {
             continue;
         }
+        // Tag class-assignment line (#186): `class s1,s5 tag_hot` — adds
+        // the tag to each listed node. Tag-name preserved as written
+        // (sanitization on emit is lossy in principle; on parse we don't
+        // un-sanitize, since the original could have any characters).
+        const tagMatch = line.match(classAssignTagRegex);
+        if (tagMatch) {
+            const ids = tagMatch[1].split(',');
+            const tagName = tagMatch[2];
+            for (const idStr of ids) {
+                ensureNode(parseMermaidId(idStr), { tags: [tagName] });
+            }
+            continue;
+        }
         // `call` arrow — sets bareStateId on each source wrapper.
         const cm = line.match(callArrowRegex);
         if (cm) {
@@ -1818,7 +2001,12 @@ function fromMermaid(text) {
         if (wo) {
             const fromId = parseMermaidId(wo[1]);
             const toId = parseMermaidId(wo[2]);
-            if (nodes[fromId] && nodes[fromId].isWrapper) {
+            // The wrapper-override regex only matches `sN --> sM` (unlabeled);
+            // since `toMermaid` only emits this shape from wrappers, the source
+            // is guaranteed to be a wrapper if `fromMermaid`'s input came from
+            // `toMermaid`. `nodes[fromId]` is always populated (first pass emits
+            // node declarations before any edge parsing).
+            if (nodes[fromId].isWrapper) {
                 nodes[fromId].overriddenHaltStateId = toId;
                 continue;
             }

package/dist/utilities/graph.d.ts

@@ -18,6 +18,7 @@ export type GraphNode = {
     bareStateId: number | null;
     frameId: number | null;
     isHaltMarker: boolean;
+    tags: string[];
 };
 export type Graph = {
     initialId: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@turing-machine-js/machine",
-  "version": "7.0.0-alpha.2",
+  "version": "7.0.0-alpha.3",
   "description": "A convenient Turing machine",
   "engines": {
     "npm": ">=7.0.0"
@@ -38,5 +38,5 @@
       "default": "./dist/index.mjs"
     }
   },
-  "gitHead": "163c0f818365241bac2c2de5e489124056703d8b"
+  "gitHead": "d0c25d94e1f3caca1c68dd08072a3e21685e2428"
 }