@vsirotin/ts-stop 1.13.1 → 2.4.1

package/ai/skills/sfsm-compare-json-uml-diagram/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: sfsm-compare-json-uml-diagram
+description: Compare an SFSM FA definition JSON file against a draw.io UML state diagram and report every discrepancy. Use when validating that a diagram matches its source JSON, or vice versa. Combines drawio-to-json and compare-compact-jsons for round-trip verification.
+metadata:
+  author: vsirotin
+  version: "2.0"
+---
+
+# Compare SFSM Compact JSON ↔ UML State Diagram (draw.io)
+
+This skill validates the correspondence between an SFSM FA definition in compact JSON format and a draw.io UML state diagram. It combines two scripts to produce a detailed diff report without modifying either file:
+1. **`drawio-to-json.js`** extracts JSON from the diagram (via SFSM metadata in cell styles or shape-based heuristics)
+2. **`compare-compact-jsons.js`** performs an intelligent comparison of the original and extracted JSON
+
+## Usage
+
+Use this skill when you need to:
+- **Validate** that a draw.io diagram matches its source JSON (e.g., after generating it with `sfsm-json-to-uml-diagram`)
+- **Verify** a round-trip workflow: JSON → Diagram → JSON → Compare
+- **Audit** a manually edited diagram to detect any data loss or drift
+- **Catch discrepancies** early (missing transitions, target mismatches, incorrect commands, etc.)
+
+## Workflow
+
+The skill requests two file paths from you (unless you provide them upfront):
+- **JSON file**: A compact-format SFSM definition
+- **Diagram file**: A `.drawio` file (ideally generated by `json-to-drawio.js`)
+
+It then runs:
+1. `drawio-to-json.js <diagram.drawio> <extracted.json>` — extract JSON from the diagram
+2. `compare-compact-jsons.js <original.json> <extracted.json>` — compare and report differences
+
+## Output
+
+The comparison report shows, per FA:
+- ✅ Number of matching transitions
+- ❌ Missing transitions (in diagram, not in JSON)
+- ❌ Extra transitions (in diagram, not in JSON)
+- ❌ Mismatches (same `from/signal` pair, different `to` or `command`)
+
+If both sides match exactly, the report confirms alignment with no discrepancies.
+
+## Input/Output
+
+- **Input**: Compact JSON file path (requested if not provided) and diagram `.drawio` file path (requested if not provided)
+- **Output**: A report printed to console (no files are modified)
+
+## Commands
+
+```bash
+cd ts/ts-stop
+node scripts/drawio-to-json.js <input.drawio> <extracted.json>
+node scripts/compare-compact-jsons.js <original.json> <extracted.json>
+```
+
+## Important note
+
+**No files are modified by this skill.** If the comparison reveals discrepancies and you decide which side is authoritative, use:
+- `sfsm-json-to-uml-diagram` to regenerate the diagram from the JSON if the JSON is authoritative
+- `sfsm-uml-diagram-to-json` to extract the diagram's corrected JSON if the diagram is authoritative
+
+See [04-tools.md § 7.5.5](../../tutorial/04-tools.md#755-compare-compact-jsons--validate-diagram-vs-json-correspondence) for detailed documentation.

package/ai/skills/sfsm-json-to-uml-diagram/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: sfsm-json-to-uml-diagram
+description: Convert an SFSM FA definition JSON file (compact or extended format) to a professional draw.io UML state diagram with hierarchical ELK.js layout. Use when asked to visualize or diagram an SFSM JSON definition. The generated diagram may require small manual repositioning for visual perfection.
+metadata:
+  author: vsirotin
+  version: "2.0"
+---
+
+# SFSM JSON → UML State Diagram (draw.io)
+
+This skill wraps the `ts/ts-stop/scripts/json-to-drawio.js` script to convert an SFSM FA definition into a professional, hierarchical draw.io UML state diagram.
+
+## Usage
+
+Invoke the script directly or use this skill when you need to:
+- **Visualize** an SFSM JSON definition as a UML state diagram
+- **Generate** a draw.io file for inspection, sharing, or further manual editing
+- **Export** an FA definition to a visual format
+
+## What the script produces
+
+- **Hierarchical layout**: Each FA rendered as a swimlane container; sub-FAs as nested light-grey boxes (100×60 px).
+- **ELK.js automatic layout**: Professional hierarchical positioning of states within each FA using the Eclipse Layout Kernel.
+- **Vertical stacking**: Multiple FAs stacked without overlap with 30px spacing.
+- **Complete metadata**: All SFSM state roles, FA names, signals, and commands embedded in cell styles for round-trip conversion back to JSON.
+- **UML state types**: Initial states (black dot), plain states (rounded rectangles), sub-FA containers (swimlanes), and exit/final states (thick-bordered circles).
+
+## Important note
+
+**Generated diagrams may require small manual adjustments** for visual perfection. Common improvements:
+- Reposition state or container nodes for better spacing or clarity
+- Adjust swimlane heights or container sizes
+- Tweak edge routing or labels
+
+These manual edits preserve the underlying SFSM metadata (stored in cell styles), so the diagram remains convertible back to JSON with zero data loss.
+
+## Input/Output
+
+- **Input**: Path to a compact or extended-format SFSM JSON file
+- **Output**: A `.drawio` file ready for inspection in draw.io or manual editing
+
+## Command
+
+```bash
+cd ts/ts-stop
+npm run build  # if not already built
+node scripts/json-to-drawio.js <input.json> <output.drawio>
+```
+
+See [04-tools.md § 7.5.3](../../tutorial/04-tools.md#753-json-to-drawio--convert-compact-fa-json-to-uml-state-diagram) for detailed documentation.

package/ai/skills/sfsm-uml-diagram-to-json/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: sfsm-uml-diagram-to-json
+description: Extract an SFSM FA definition JSON file in compact format from a draw.io UML state diagram. Use when asked to convert, export, or reverse-engineer a diagram back into SFSM/StOP JSON.
+metadata:
+  author: vsirotin
+  version: "2.0"
+---
+
+# UML State Diagram (draw.io) → SFSM Compact JSON
+
+This skill wraps the `ts/ts-stop/scripts/drawio-to-json.js` script to extract or reverse-convert a draw.io diagram into a compact-format SFSM FA definition ready for `Sfsm.loadFA()`.
+
+## Usage
+
+Invoke the script directly or use this skill when you need to:
+- **Convert** a draw.io diagram back to SFSM JSON format
+- **Reverse-engineer** a manually drawn state diagram into a machine-readable FA definition
+- **Extract** SFSM data from a diagram produced by the `sfsm-json-to-uml-diagram` skill (lossless round-trip)
+- **Export** a collaborator's visual diagram as a JSON file for programmatic use
+
+## How it works
+
+The script reads a `.drawio` file and extracts every state, transition, and SFSM-specific metadata:
+- **Preferred**: Diagrams generated by `json-to-drawio.js` include custom metadata (sfsmRole, sfsmFa, sfsmKey, sfsmSignal, sfsmCommand) embedded in cell styles — these are read directly and trusted as ground truth.
+- **Fallback**: Hand-drawn diagrams without metadata are parsed using shape-based heuristics (ellipses → states, swimlanes → sub-FAs, thick-bordered circles → exit states, etc.).
+
+Output is a compact-format JSON object: `{ "<FaName>": [[from, signal, to], [from, signal, to, command], ...], ... }`
+
+## Input/Output
+
+- **Input**: A `.drawio` file (ideally generated by `json-to-drawio.js`)
+- **Output**: A `.json` file in compact SFSM format
+
+## Command
+
+```bash
+cd ts/ts-stop
+node scripts/drawio-to-json.js <input.drawio> <output.json>
+```
+
+## Validation tip
+
+After converting a diagram to JSON, compare the result against the original JSON using the `compare-compact-jsons.js` script or the `sfsm-compare-json-uml-diagram` skill to verify the round-trip was lossless:
+
+```bash
+node scripts/compare-compact-jsons.js <original.json> <output.json>
+```
+
+See [04-tools.md § 7.5.4](../../tutorial/04-tools.md#754-drawio-to-json--extract-compact-fa-json-from-uml-diagram) for detailed documentation.

package/lib/esm/sfsm/CommandReceiver.js

@@ -0,0 +1,17 @@
+/**
+ * Abstract base class for the command-receiving role of an external-world component
+ * (a "Controller" in ControllerHub terminology).
+ *
+ * Concrete subclasses declare the command names they handle via getCommandNames()
+ * (read by ControllerHub for routing and diagnostics — no need to repeat the list
+ * again at the registration call site) and implement receiveCommand() to react to
+ * commands dispatched by the SFSM.
+ *
+ * A component that both sends signals and receives commands should extend
+ * SignalSender and additionally implement this class's contract directly
+ * (getCommandNames / receiveCommand) — TypeScript does not allow extending two
+ * classes, but structurally implementing this abstract class's shape is sufficient
+ * for ControllerHub.registerCommandReceiver().
+ */
+export class CommandReceiver {
+}

package/lib/esm/sfsm/ControllerHub.js

@@ -0,0 +1,82 @@
+/**
+ * Wiring hub between the SFSM and a collection of Controllers — components that
+ * play the SignalSender and/or CommandReceiver role for the "external world".
+ *
+ * - registerSignalSender(sender) — wires a SignalSender; its signal names are
+ *   read from sender.getSignalNames(), so they never need to be repeated here.
+ * - registerCommandReceiver(receiver) — wires a CommandReceiver; its command names
+ *   are read from receiver.getCommandNames(). Throws if a command name is already
+ *   registered by another receiver.
+ * - connectTo(sfsm) — wires everything: sets itself as the SFSM's command receiver
+ *   and calls connectSignalTarget(sfsm) on every registered signal sender.
+ *
+ * A single component that plays both roles (most real devices do) extends
+ * SignalSender and additionally implements the CommandReceiver contract on the
+ * same class, then is registered once with each method:
+ *
+ *   new ControllerHub()
+ *     .registerSignalSender(turnstileService)
+ *     .registerSignalSender(turnstileDevice)
+ *     .registerCommandReceiver(turnstileDevice)
+ *     .connectTo(sfsm);
+ */
+export class ControllerHub {
+    constructor() {
+        this.commandRoutes = new Map();
+        this.signalSenders = [];
+    }
+    /**
+     * Register a signal sender. Its signal names (getSignalNames()) are used for
+     * diagnostics via getRegisteredSignals().
+     * Fluent — returns this.
+     */
+    registerSignalSender(sender) {
+        this.signalSenders.push(sender);
+        return this;
+    }
+    /**
+     * Register a command receiver for all command names it declares via getCommandNames().
+     * Throws if any of those command names is already registered.
+     * Fluent — returns this.
+     */
+    registerCommandReceiver(receiver) {
+        for (const cmd of receiver.getCommandNames()) {
+            if (this.commandRoutes.has(cmd)) {
+                throw new Error(`ControllerHub: command "${cmd}" is already registered`);
+            }
+            this.commandRoutes.set(cmd, receiver);
+        }
+        return this;
+    }
+    /**
+     * Wire this hub to the given SFSM instance:
+     * 1. Sets this hub as the SFSM's command receiver.
+     * 2. Calls connectSignalTarget(sfsm) on every registered signal sender.
+     * Fluent — returns this.
+     */
+    connectTo(sfsm) {
+        sfsm.setCommandReceiver(this);
+        for (const sender of this.signalSenders) {
+            sender.connectSignalTarget(sfsm);
+        }
+        return this;
+    }
+    /** ICommandReceiver implementation — dispatches command to the registered receiver. */
+    receiveCommand(command, data) {
+        const receiver = this.commandRoutes.get(command);
+        if (!receiver) {
+            const registered = [...this.commandRoutes.keys()].join(', ');
+            throw new Error(`ControllerHub: no receiver registered for command "${command}". ` +
+                `Registered commands: [${registered}]`);
+        }
+        receiver.receiveCommand(command, data);
+    }
+    /** Returns all command names that have a registered receiver (for diagnostics / validation). */
+    getRegisteredCommands() {
+        return [...this.commandRoutes.keys()];
+    }
+    /** Returns all signal names that have a registered sender (for diagnostics / validation). */
+    getRegisteredSignals() {
+        return this.signalSenders.flatMap(s => s.getSignalNames());
+    }
+}

package/lib/esm/sfsm/FaResolver.js

@@ -67,7 +67,8 @@ export class FaResolver {
                     name: rootName,
                     transitions: rootValue,
                     subFaNames: new Set(),
-                    node
+                    node,
+                    entryState: this.resolveEntryState(rootValue)
                 });
             }
             else {
@@ -85,7 +86,13 @@ export class FaResolver {
                 .map(t => t[2])
                 .filter(target => definedFaNames.has(target)));
             const node = { ts: transitions };
-            this.index.set(name, { name, transitions, subFaNames, node });
+            this.index.set(name, {
+                name,
+                transitions,
+                subFaNames,
+                node,
+                entryState: this.resolveEntryState(transitions)
+            });
         }
     }
     indexNode(name, node) {
@@ -102,7 +109,8 @@ export class FaResolver {
             name,
             transitions: node.ts,
             subFaNames,
-            node
+            node,
+            entryState: this.resolveEntryState(node.ts)
         });
     }
     /** A state value is a sub-FA if it has a "ts" array property. */
@@ -112,4 +120,17 @@ export class FaResolver {
             'ts' in value &&
             Array.isArray(value.ts));
     }
+    /**
+     * Auto-detects the literal entry-state name used by a FA's own transitions:
+     * the bare `"I"`, or a namespaced `"<FaName>.I"` (e.g. `"TS.I"`). Falls back
+     * to `"I"` if the FA has no transition whose from-state matches either form.
+     */
+    resolveEntryState(transitions) {
+        for (const t of transitions) {
+            if (t[0] === 'I' || t[0].endsWith('.I')) {
+                return t[0];
+            }
+        }
+        return 'I';
+    }
 }

package/lib/esm/sfsm/Sfsm.js

@@ -12,10 +12,24 @@ import { FaResolver } from './FaResolver';
  * processing a signal (e.g. from within a command receiver callback), the
  * incoming signal is queued and processed after the current step completes.
  * This prevents stack corruption and ensures deterministic ordering.
+ *
+ * Jokers: a transition may use a reserved "joker" string (default '*',
+ * configurable via SfsmOptions.jokerSignal / jokerState) in its signal or
+ * from-state slot to act as a fallback. A joker-signal transition matches
+ * any signal for its from-state; a joker-state transition matches any
+ * from-state for its signal. Exact, literal transitions always take
+ * priority over joker matches. See docs/Tutorial/Tutorial.md for examples.
+ *
+ * Entry/exit naming convention: every FA's entry state is either the bare
+ * "I", or a namespaced "<FaName>.I" (e.g. "TS.I") — auto-detected per FA from
+ * its own transitions. Every exit state either starts with "E_", or contains
+ * ".E_" (e.g. "TS.E_ok"). Both forms are recognised everywhere and may be
+ * freely mixed across FAs; see Tutorial.md §8.1 for when to use the
+ * namespaced form.
  */
 export class Sfsm {
     constructor(options = {}) {
-        var _a, _b;
+        var _a, _b, _c, _d;
         this.resolver = null;
         this.stack = [];
         this.commandReceiver = null;
@@ -24,7 +38,9 @@ export class Sfsm {
         this.signalQueue = [];
         this.options = {
             byMissingData: (_a = options.byMissingData) !== null && _a !== void 0 ? _a : 'error',
-            byMissingTransition: (_b = options.byMissingTransition) !== null && _b !== void 0 ? _b : 'error'
+            byMissingTransition: (_b = options.byMissingTransition) !== null && _b !== void 0 ? _b : 'error',
+            jokerSignal: (_c = options.jokerSignal) !== null && _c !== void 0 ? _c : '*',
+            jokerState: (_d = options.jokerState) !== null && _d !== void 0 ? _d : '*'
         };
     }
     /** Register the single command receiver for this SFSM instance. */
@@ -40,7 +56,7 @@ export class Sfsm {
     loadFA(definition) {
         this.resolver = new FaResolver(definition);
         const rootName = this.resolver.getRootName();
-        this.stack = [{ faName: rootName, currentState: 'I' }];
+        this.stack = [{ faName: rootName, currentState: this.resolver.get(rootName).entryState }];
         this.log = [];
         this.processing = false;
         this.signalQueue = [];
@@ -92,12 +108,30 @@ export class Sfsm {
     /**
      * Rule 2: find a matching transition, searching from head down the stack.
      * Returns { frameIndex, transition } or null if not found anywhere.
+     *
+     * Within each frame, matches are tried in priority order so that exact,
+     * literal transitions always win over joker (wildcard) ones:
+     *   1. exact from-state + exact signal
+     *   2. exact from-state + joker signal
+     *   3. joker from-state + exact signal
+     *   4. joker from-state + joker signal
      */
     findTransition(signal) {
+        const jokerSignal = this.options.jokerSignal;
+        const jokerState = this.options.jokerState;
         for (let i = this.stack.length - 1; i >= 0; i--) {
             const frame = this.stack[i];
             const fa = this.resolver.get(frame.faName);
-            const match = fa.transitions.find(t => t[0] === frame.currentState && t[1] === signal);
+            let match = fa.transitions.find(t => t[0] === frame.currentState && t[1] === signal);
+            if (!match && jokerSignal !== undefined) {
+                match = fa.transitions.find(t => t[0] === frame.currentState && t[1] === jokerSignal);
+            }
+            if (!match && jokerState !== undefined) {
+                match = fa.transitions.find(t => t[0] === jokerState && t[1] === signal);
+            }
+            if (!match && jokerState !== undefined && jokerSignal !== undefined) {
+                match = fa.transitions.find(t => t[0] === jokerState && t[1] === jokerSignal);
+            }
             if (match) {
                 return { frameIndex: i, toState: match[2], command: match[3] };
             }
@@ -160,15 +194,15 @@ export class Sfsm {
         // Rule 3: new state is itself a sub-FA — push it
         const headFa = this.resolver.get(this.stack[frameIndex].faName);
         if (headFa.subFaNames.has(toState)) {
-            this.stack.push({ faName: toState, currentState: 'I' });
+            this.stack.push({ faName: toState, currentState: this.resolver.get(toState).entryState });
             this.applySignal(signal, data); // forward signal to sub-FA
             return;
         }
         // Rule 4: new state is an exit state
-        if (toState.startsWith('E_')) {
+        if (this.isExitState(toState)) {
             if (this.stack.length === 1) {
                 // Rule 4.1 — root FA resets to I
-                this.stack[0].currentState = 'I';
+                this.stack[0].currentState = this.resolver.get(this.stack[0].faName).entryState;
             }
             else {
                 // Rule 4.2 — pop current FA, forward signal to new head
@@ -178,6 +212,13 @@ export class Sfsm {
         }
     }
     // ── Meta resolution helpers ──────────────────────────────────────────────
+    /**
+     * A state is an exit/final state if it starts with "E_" (default
+     * convention) or contains ".E_" (namespaced convention, e.g. "TS.E_ok").
+     */
+    isExitState(state) {
+        return state.startsWith('E_') || state.includes('.E_');
+    }
     resolveStateMeta(frameIndex, state) {
         var _a;
         const fa = this.resolver.get(this.stack[frameIndex].faName);

package/lib/esm/sfsm/SignalSender.js

@@ -0,0 +1,27 @@
+/**
+ * Abstract base class for the signal-sending role of an external-world component
+ * (a "Controller" in ControllerHub terminology).
+ *
+ * Concrete subclasses:
+ *   - declare the signal names they may emit via getSignalNames()
+ *     (read by ControllerHub for wiring and diagnostics — no need to repeat the
+ *     list again at the registration call site);
+ *   - call the protected sendSignal() to push a signal to the connected target
+ *     (normally the SFSM).
+ *
+ * ControllerHub calls connectSignalTarget() automatically during connectTo().
+ */
+export class SignalSender {
+    constructor() {
+        this.signalTarget = null;
+    }
+    /** Called by ControllerHub to connect the SFSM (or any receiver) as the signal target. */
+    connectSignalTarget(target) {
+        this.signalTarget = target;
+    }
+    /** Sends a signal to the connected target (normally the SFSM). */
+    sendSignal(name, data) {
+        var _a;
+        (_a = this.signalTarget) === null || _a === void 0 ? void 0 : _a.receiveSignal(name, data);
+    }
+}

package/lib/esm/sfsm/index.js

@@ -1,4 +1,6 @@
-export { ExternalWorldHub } from './ExternalWorldHub';
+export { ControllerHub } from './ControllerHub';
+export { SignalSender } from './SignalSender';
+export { CommandReceiver } from './CommandReceiver';
 export { FaResolver } from './FaResolver';
 export { Sfsm } from './Sfsm';
 export { reduceFA } from './FaReducer';

package/lib/sfsm/CommandReceiver.d.ts

@@ -0,0 +1,23 @@
+import { ICommandReceiver } from './interfaces';
+/**
+ * Abstract base class for the command-receiving role of an external-world component
+ * (a "Controller" in ControllerHub terminology).
+ *
+ * Concrete subclasses declare the command names they handle via getCommandNames()
+ * (read by ControllerHub for routing and diagnostics — no need to repeat the list
+ * again at the registration call site) and implement receiveCommand() to react to
+ * commands dispatched by the SFSM.
+ *
+ * A component that both sends signals and receives commands should extend
+ * SignalSender and additionally implement this class's contract directly
+ * (getCommandNames / receiveCommand) — TypeScript does not allow extending two
+ * classes, but structurally implementing this abstract class's shape is sufficient
+ * for ControllerHub.registerCommandReceiver().
+ */
+export declare abstract class CommandReceiver implements ICommandReceiver {
+    /** Returns all command names this receiver handles. */
+    abstract getCommandNames(): readonly string[];
+    /** Called by ControllerHub when the SFSM dispatches a matching command. */
+    abstract receiveCommand(command: string, data?: unknown): void;
+}
+//# sourceMappingURL=CommandReceiver.d.ts.map

package/lib/sfsm/CommandReceiver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CommandReceiver.d.ts","sourceRoot":"","sources":["../../src/sfsm/CommandReceiver.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEhD;;;;;;;;;;;;;;GAcG;AACH,8BAAsB,eAAgB,YAAW,gBAAgB;IAE7D,uDAAuD;IACvD,QAAQ,CAAC,eAAe,IAAI,SAAS,MAAM,EAAE;IAE7C,2EAA2E;IAC3E,QAAQ,CAAC,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI;CACjE"}

package/lib/sfsm/CommandReceiver.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommandReceiver = void 0;
+/**
+ * Abstract base class for the command-receiving role of an external-world component
+ * (a "Controller" in ControllerHub terminology).
+ *
+ * Concrete subclasses declare the command names they handle via getCommandNames()
+ * (read by ControllerHub for routing and diagnostics — no need to repeat the list
+ * again at the registration call site) and implement receiveCommand() to react to
+ * commands dispatched by the SFSM.
+ *
+ * A component that both sends signals and receives commands should extend
+ * SignalSender and additionally implement this class's contract directly
+ * (getCommandNames / receiveCommand) — TypeScript does not allow extending two
+ * classes, but structurally implementing this abstract class's shape is sufficient
+ * for ControllerHub.registerCommandReceiver().
+ */
+class CommandReceiver {
+}
+exports.CommandReceiver = CommandReceiver;
+//# sourceMappingURL=CommandReceiver.js.map

package/lib/sfsm/CommandReceiver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CommandReceiver.js","sourceRoot":"","sources":["../../src/sfsm/CommandReceiver.ts"],"names":[],"mappings":";;;AAEA;;;;;;;;;;;;;;GAcG;AACH,MAAsB,eAAe;CAOpC;AAPD,0CAOC"}

package/lib/sfsm/ControllerHub.d.ts

@@ -0,0 +1,56 @@
+import { ICommandReceiver } from './interfaces';
+import { Sfsm } from './Sfsm';
+import { SignalSender } from './SignalSender';
+import { CommandReceiver } from './CommandReceiver';
+/**
+ * Wiring hub between the SFSM and a collection of Controllers — components that
+ * play the SignalSender and/or CommandReceiver role for the "external world".
+ *
+ * - registerSignalSender(sender) — wires a SignalSender; its signal names are
+ *   read from sender.getSignalNames(), so they never need to be repeated here.
+ * - registerCommandReceiver(receiver) — wires a CommandReceiver; its command names
+ *   are read from receiver.getCommandNames(). Throws if a command name is already
+ *   registered by another receiver.
+ * - connectTo(sfsm) — wires everything: sets itself as the SFSM's command receiver
+ *   and calls connectSignalTarget(sfsm) on every registered signal sender.
+ *
+ * A single component that plays both roles (most real devices do) extends
+ * SignalSender and additionally implements the CommandReceiver contract on the
+ * same class, then is registered once with each method:
+ *
+ *   new ControllerHub()
+ *     .registerSignalSender(turnstileService)
+ *     .registerSignalSender(turnstileDevice)
+ *     .registerCommandReceiver(turnstileDevice)
+ *     .connectTo(sfsm);
+ */
+export declare class ControllerHub implements ICommandReceiver {
+    private commandRoutes;
+    private signalSenders;
+    /**
+     * Register a signal sender. Its signal names (getSignalNames()) are used for
+     * diagnostics via getRegisteredSignals().
+     * Fluent — returns this.
+     */
+    registerSignalSender(sender: SignalSender): this;
+    /**
+     * Register a command receiver for all command names it declares via getCommandNames().
+     * Throws if any of those command names is already registered.
+     * Fluent — returns this.
+     */
+    registerCommandReceiver(receiver: CommandReceiver): this;
+    /**
+     * Wire this hub to the given SFSM instance:
+     * 1. Sets this hub as the SFSM's command receiver.
+     * 2. Calls connectSignalTarget(sfsm) on every registered signal sender.
+     * Fluent — returns this.
+     */
+    connectTo(sfsm: Sfsm): this;
+    /** ICommandReceiver implementation — dispatches command to the registered receiver. */
+    receiveCommand(command: string, data?: unknown): void;
+    /** Returns all command names that have a registered receiver (for diagnostics / validation). */
+    getRegisteredCommands(): string[];
+    /** Returns all signal names that have a registered sender (for diagnostics / validation). */
+    getRegisteredSignals(): string[];
+}
+//# sourceMappingURL=ControllerHub.d.ts.map

package/lib/sfsm/ControllerHub.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ControllerHub.d.ts","sourceRoot":"","sources":["../../src/sfsm/ControllerHub.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAC9B,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,aAAc,YAAW,gBAAgB;IAElD,OAAO,CAAC,aAAa,CAAsC;IAC3D,OAAO,CAAC,aAAa,CAAsB;IAE3C;;;;OAIG;IACH,oBAAoB,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI;IAKhD;;;;OAIG;IACH,uBAAuB,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI;IAUxD;;;;;OAKG;IACH,SAAS,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI;IAQ3B,uFAAuF;IACvF,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI;IAYrD,gGAAgG;IAChG,qBAAqB,IAAI,MAAM,EAAE;IAIjC,6FAA6F;IAC7F,oBAAoB,IAAI,MAAM,EAAE;CAGnC"}

package/lib/sfsm/ControllerHub.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ControllerHub = void 0;
+/**
+ * Wiring hub between the SFSM and a collection of Controllers — components that
+ * play the SignalSender and/or CommandReceiver role for the "external world".
+ *
+ * - registerSignalSender(sender) — wires a SignalSender; its signal names are
+ *   read from sender.getSignalNames(), so they never need to be repeated here.
+ * - registerCommandReceiver(receiver) — wires a CommandReceiver; its command names
+ *   are read from receiver.getCommandNames(). Throws if a command name is already
+ *   registered by another receiver.
+ * - connectTo(sfsm) — wires everything: sets itself as the SFSM's command receiver
+ *   and calls connectSignalTarget(sfsm) on every registered signal sender.
+ *
+ * A single component that plays both roles (most real devices do) extends
+ * SignalSender and additionally implements the CommandReceiver contract on the
+ * same class, then is registered once with each method:
+ *
+ *   new ControllerHub()
+ *     .registerSignalSender(turnstileService)
+ *     .registerSignalSender(turnstileDevice)
+ *     .registerCommandReceiver(turnstileDevice)
+ *     .connectTo(sfsm);
+ */
+class ControllerHub {
+    constructor() {
+        this.commandRoutes = new Map();
+        this.signalSenders = [];
+    }
+    /**
+     * Register a signal sender. Its signal names (getSignalNames()) are used for
+     * diagnostics via getRegisteredSignals().
+     * Fluent — returns this.
+     */
+    registerSignalSender(sender) {
+        this.signalSenders.push(sender);
+        return this;
+    }
+    /**
+     * Register a command receiver for all command names it declares via getCommandNames().
+     * Throws if any of those command names is already registered.
+     * Fluent — returns this.
+     */
+    registerCommandReceiver(receiver) {
+        for (const cmd of receiver.getCommandNames()) {
+            if (this.commandRoutes.has(cmd)) {
+                throw new Error(`ControllerHub: command "${cmd}" is already registered`);
+            }
+            this.commandRoutes.set(cmd, receiver);
+        }
+        return this;
+    }
+    /**
+     * Wire this hub to the given SFSM instance:
+     * 1. Sets this hub as the SFSM's command receiver.
+     * 2. Calls connectSignalTarget(sfsm) on every registered signal sender.
+     * Fluent — returns this.
+     */
+    connectTo(sfsm) {
+        sfsm.setCommandReceiver(this);
+        for (const sender of this.signalSenders) {
+            sender.connectSignalTarget(sfsm);
+        }
+        return this;
+    }
+    /** ICommandReceiver implementation — dispatches command to the registered receiver. */
+    receiveCommand(command, data) {
+        const receiver = this.commandRoutes.get(command);
+        if (!receiver) {
+            const registered = [...this.commandRoutes.keys()].join(', ');
+            throw new Error(`ControllerHub: no receiver registered for command "${command}". ` +
+                `Registered commands: [${registered}]`);
+        }
+        receiver.receiveCommand(command, data);
+    }
+    /** Returns all command names that have a registered receiver (for diagnostics / validation). */
+    getRegisteredCommands() {
+        return [...this.commandRoutes.keys()];
+    }
+    /** Returns all signal names that have a registered sender (for diagnostics / validation). */
+    getRegisteredSignals() {
+        return this.signalSenders.flatMap(s => s.getSignalNames());
+    }
+}
+exports.ControllerHub = ControllerHub;
+//# sourceMappingURL=ControllerHub.js.map