@vsirotin/ts-stop 1.13.1 → 2.4.1

package/scripts/json-to-drawio.js

@@ -0,0 +1,309 @@
+#!/usr/bin/env node
+/**
+ * Convert SFSM compact-format FA JSON to draw.io UML state diagram
+ * Each FA is a separate container, sub-FAs are nested containers with light grey background
+ * Usage: node json-to-drawio.js <input-json> <output-drawio>
+ */
+
+const fs = require('fs');
+const path = require('path');
+const ELK = require('elkjs').default;
+
+const elk = new ELK();
+
+// ============ MAIN ============
+async function main() {
+  const [inputJsonPath, outputDrawioPath] = process.argv.slice(2);
+  
+  if (!inputJsonPath || !outputDrawioPath) {
+    console.error('Usage: node json-to-drawio.js <input-json> <output-drawio>');
+    process.exit(1);
+  }
+
+  try {
+    const faData = JSON.parse(fs.readFileSync(inputJsonPath, 'utf-8'));
+    const drawio = await generateDrawio(faData);
+    
+    // Ensure output directory exists
+    const outputDir = path.dirname(outputDrawioPath);
+    if (!fs.existsSync(outputDir)) {
+      fs.mkdirSync(outputDir, { recursive: true });
+    }
+    
+    fs.writeFileSync(outputDrawioPath, drawio);
+    console.log(`Generated: ${outputDrawioPath}`);
+  } catch (err) {
+    console.error('Error:', err.message);
+    process.exit(1);
+  }
+}
+
+// ============ CONVERSION LOGIC ============
+
+async function generateDrawio(faData) {
+  const allFaNames = Object.keys(faData);
+  const cellsMap = new Map();
+  const edgeList = [];
+  const stateNodeMap = new Map(); // `${faKey}:${state}` -> nodeId
+  
+  let containerYOffset = 20; // Track vertical position of containers
+  
+  // Process each FA and create its container with nested states
+  for (const faName of allFaNames) {
+    containerYOffset = await processFAWithContainer(faName, faData, allFaNames, cellsMap, edgeList, stateNodeMap, containerYOffset);
+  }
+  
+  // Convert to drawio
+  return buildDrawioXml(cellsMap, edgeList);
+}
+
+async function processFAWithContainer(faKey, faData, allFaNames, cellsMap, edgeList, stateNodeMap, containerYPos) {
+  const transitions = faData[faKey];
+  const states = new Set();
+  const exitStates = new Set();
+  const subFaStates = new Set();
+  
+  // Collect state information
+  for (const tr of transitions) {
+    const [from, signal, to] = tr;
+    states.add(from);
+    states.add(to);
+    
+    if (to.startsWith('E_')) {
+      exitStates.add(to);
+    }
+    if (allFaNames.includes(to)) {
+      subFaStates.add(to);
+    }
+  }
+  
+  // Build ELK graph structure for this FA's layout
+  const elkChildren = [];
+  const nodePositions = new Map(); // nodeId -> {x, y}
+  
+  // Initial state
+  const initId = `init-${faKey}`;
+  elkChildren.push({
+    id: initId,
+    width: 20,
+    height: 20
+  });
+  
+  // Other states
+  for (const state of states) {
+    if (state === 'I') continue;
+    
+    const nodeId = `state-${faKey}-${state}`;
+    let width = 120;
+    let height = 50;
+    
+    if (exitStates.has(state)) {
+      width = 70;
+      height = 70;
+    } else if (subFaStates.has(state)) {
+      // Sub-FA: much smaller size
+      width = 100;
+      height = 60;
+    }
+    
+    elkChildren.push({
+      id: nodeId,
+      width: width,
+      height: height,
+      labels: [{ text: state }]
+    });
+  }
+  
+  // Build ELK edges for this FA
+  const elkEdges = [];
+  for (const tr of transitions) {
+    const [from, signal, to] = tr;
+    const fromId = from === 'I' ? `init-${faKey}` : `state-${faKey}-${from}`;
+    const toId = `state-${faKey}-${to}`;
+    
+    elkEdges.push({
+      id: `tr-${faKey}-${from}-${to}`,
+      sources: [fromId],
+      targets: [toId],
+      labels: [{ text: signal }]
+    });
+  }
+  
+  // Layout this FA using ELK
+  const graph = {
+    id: `graph-${faKey}`,
+    layoutOptions: {
+      'elk.algorithm': 'layered',
+      'elk.direction': 'DOWN',
+      'elk.spacing.nodeNode': '30',
+      'elk.spacing.edgeNode': '15',
+      'elk.layered.spacing.edgeNodeBetweenLayers': '20'
+    },
+    children: elkChildren,
+    edges: elkEdges
+  };
+  
+  try {
+    const layout = await elk.layout(graph);
+    
+    // Extract positions from layout
+    if (layout.children) {
+      for (const node of layout.children) {
+        nodePositions.set(node.id, { x: Math.round(node.x || 0), y: Math.round(node.y || 0) });
+      }
+    }
+  } catch (err) {
+    console.warn(`Warning: ELK layout failed for ${faKey}, using default positions`);
+  }
+  
+  // Create cells for this FA's states
+  // Initial state
+  const initPos = nodePositions.get(initId) || { x: 20, y: 20 };
+  cellsMap.set(initId, {
+    id: initId,
+    value: '',
+    style: `ellipse;whiteSpace=wrap;html=1;fillColor=#000000;strokeColor=#000000;sfsmRole=initial;sfsmFa=${faKey};`,
+    x: initPos.x,
+    y: initPos.y,
+    width: 20,
+    height: 20,
+    parent: `container-${faKey}`
+  });
+  stateNodeMap.set(`${faKey}:I`, initId);
+  
+  // Other states
+  for (const state of states) {
+    if (state === 'I') continue;
+    
+    const nodeId = `state-${faKey}-${state}`;
+    const pos = nodePositions.get(nodeId) || { x: 20, y: 80 };
+    let style = '';
+    let width = 120;
+    let height = 50;
+    
+    if (exitStates.has(state)) {
+      style = `ellipse;whiteSpace=wrap;html=1;strokeWidth=3;fillColor=#FFFFFF;sfsmRole=exit;sfsmFa=${faKey};sfsmKey=${state};`;
+      width = 70;
+      height = 70;
+    } else if (subFaStates.has(state)) {
+      // Sub-FA: light grey container, smaller size
+      style = `rounded=0;whiteSpace=wrap;html=1;fillColor=#E8E8E8;strokeColor=#999999;strokeWidth=2;sfsmRole=subfa;sfsmFa=${faKey};sfsmKey=${state};`;
+      width = 100;
+      height = 60;
+    } else {
+      style = `rounded=1;whiteSpace=wrap;html=1;arcSize=20;sfsmRole=state;sfsmFa=${faKey};sfsmKey=${state};`;
+    }
+    
+    cellsMap.set(nodeId, {
+      id: nodeId,
+      value: state,
+      style: style,
+      x: pos.x,
+      y: pos.y,
+      width: width,
+      height: height,
+      parent: `container-${faKey}`
+    });
+    stateNodeMap.set(`${faKey}:${state}`, nodeId);
+  }
+  
+  // Calculate container size based on layout
+  let maxX = 40;
+  let maxY = 40;
+  for (const [, pos] of nodePositions) {
+    maxX = Math.max(maxX, pos.x + 150);
+    maxY = Math.max(maxY, pos.y + 100);
+  }
+  
+  const containerWidth = Math.max(280, maxX + 40);
+  const containerHeight = Math.max(140, maxY + 40);
+  
+  // Create container for FA at specified Y position
+  const containerId = `container-${faKey}`;
+  cellsMap.set(containerId, {
+    id: containerId,
+    value: faKey,
+    style: `swimlane;whiteSpace=wrap;html=1;startSize=35;fontStyle=1;rounded=1;sfsmRole=facontainer;sfsmFa=${faKey};`,
+    x: 20,
+    y: containerYPos,
+    width: containerWidth,
+    height: containerHeight,
+    parent: '1'
+  });
+  
+  // Create transitions
+  let transitionCounter = 0;
+  for (const tr of transitions) {
+    const [from, signal, to, command] = tr;
+    const fromState = from === 'I' ? 'I' : from;
+    const sourceId = stateNodeMap.get(`${faKey}:${fromState}`);
+    const targetId = stateNodeMap.get(`${faKey}:${to}`);
+    
+    if (!sourceId || !targetId) continue;
+    
+    const edgeLabel = command ? `${signal} / ${to}:${command}` : signal;
+    const edgeId = `tr-${faKey}-${transitionCounter++}`;
+    const isLoop = from === to;
+    
+    let style = `edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;sfsmRole=transition;sfsmFa=${faKey};sfsmSignal=${signal};sfsmCommand=${command || ''};`;
+    if (isLoop) {
+      style += `exitX=0.25;exitY=0;exitDx=0;exitDy=0;entryX=0.75;entryY=0;entryDx=0;entryDy=0;`;
+    }
+    
+    edgeList.push({
+      id: edgeId,
+      value: edgeLabel,
+      style: style,
+      source: sourceId,
+      target: targetId,
+      parent: '1'
+    });
+  }
+  
+  // Return next Y position for next container (with some spacing)
+  return containerYPos + containerHeight + 30;
+}
+
+function buildDrawioXml(cellsMap, edgeList) {
+  let xml = `<?xml version="1.0" encoding="UTF-8"?>
+<mxfile host="Electron">
+  <diagram id="sfsm-diagram" name="Page-1">
+    <mxGraphModel dx="800" dy="600" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="1169" pageHeight="827" math="0" shadow="0">
+      <root>
+        <mxCell id="0"/>
+        <mxCell id="1" parent="0"/>
+`;
+  
+  for (const [cellId, cell] of cellsMap) {
+    xml += `        <mxCell id="${cell.id}" value="${escapeXml(cell.value)}" style="${cell.style}" vertex="1" parent="${cell.parent}">
+          <mxGeometry x="${cell.x}" y="${cell.y}" width="${cell.width}" height="${cell.height}" as="geometry"/>
+        </mxCell>
+`;
+  }
+  
+  for (const edge of edgeList) {
+    xml += `        <mxCell id="${edge.id}" value="${escapeXml(edge.value)}" style="${edge.style}" edge="1" parent="${edge.parent}" source="${edge.source}" target="${edge.target}">
+          <mxGeometry relative="1" as="geometry"/>
+        </mxCell>
+`;
+  }
+  
+  xml += `      </root>
+    </mxGraphModel>
+  </diagram>
+</mxfile>`;
+  
+  return xml;
+}
+
+function escapeXml(str) {
+  if (!str) return '';
+  return String(str)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}
+
+main();

package/tutorial/01-finite-state-machine.md

@@ -0,0 +1,223 @@
+# StOP Tutorial. Part 1; Finite State Machines
+
+## 1. What is a Finite Automaton?
+
+Mountains of scientific and educational books and articles have been written about finite automata (FA), which manage in an amazing way to not only confuse the reader, but also to frighten practitioners away from using them.
+
+However, the basic idea of a finite automaton is as simple as it is fundamental. 
+
+Namely. We have:
+- **A finite set of states** in which some object can exist, one of which is the initial state
+- **A finite number of signals** that can be sent to this object and possibly lead to a change in its state, i.e., a transition from the current state to another
+
+All the magic of finite automata is based on this simple idea.
+
+To define a specific finite automaton, you need to specify a list of its states (States S), signals (Signals G), and transitions (Transitions T) in the form of a list of triples:
+
+`<s0, g, s1>`, where:
+- `s0` - the state in which the automaton is currently located (initially - the starting state)
+- `g` - the signal
+- `s1` - the state to which our object will transition after receiving the signal
+
+Of course, we don't need states in S and signals in G that are not represented in T in any way. For practical use, some other constraints are also important, but we won't delve into the depths of theory for now, and will move on to a concrete programming example.
+
+Let's examine the use of a finite automaton (FA) using the example of a very simple automaton - a primitive turnstile that lets someone into the metro or a paid restroom after they drop a coin or special token into its slot.
+
+Like this:
+
+![Turnstile](./images/Turnstile-img.png)
+
+This automaton has two states: **locked** and **unlocked**, and two signals: **coin received** (coin) and **person passed through** (push).
+
+## 2. Defining the turnstile with the StOP library
+
+The [TypeScript StOP library](https://github.com/vsirotin/StOP) processes finite automata with the `Sfsm` engine (available from the `@vsirotin/ts-stop` package). 
+
+SFSM stands for "Stacked Finite State Machine" — a finite automaton that can contain other finite automata as sub-machines, and can be stacked into hierarchies of arbitrary depth. The turnstile is a simple FA with no children, so it is a good starting point for our tutorial. Because of its simple behaviour we talk about finite automata (FA) and not about finite machines.
+
+Some FA is described as a list of transitions, each one a triple (or, when a command must be sent, a quadruple — covered in a later chapter):
+
+```
+[s0, g, s1]
+```
+
+which is a direct, literal translation of the `<s0, g, s1>` triples introduced above. This representation is convenient when a FA is small — for large, dense automata you may prefer other representations, but that is out of scope here.
+
+One detail of the `Sfsm` engine is important to know from the very first example: every FA always starts in a reserved entry state named `"I"` or, by complex machines with `"*.I"`, e.g. `"BCC.I"`, that means `initial state`. This is not part of the pure theory above — it is a small, deliberate engine convention that becomes very useful once FAs are combined into hierarchies (a topic of a later chapter). For now, it simply means our turnstile needs one extra transition out of `"I"` into its real initial state, triggered by an explicit "start" signal.
+
+Here is the complete turnstile FA, written as compact JSON:
+
+```json
+{
+  "Turnstile": [
+    ["I",       "Start", "Locked"],
+    ["Locked",  "Coin",  "Unlocked"],
+    ["Unlocked","Push",  "Locked"]
+  ]
+}
+```
+
+This FA can be visually presented as a simple state diagram:
+![Turnstile](./images/TurnstileBaseFA.png)
+
+And here is how it is loaded and driven with the `Sfsm` class:
+
+```typescript
+import { Sfsm, FaDefinition } from '@vsirotin/ts-stop/sfsm';
+import turnstileFa from './turnstile-fa.json';
+
+const sfsm = new Sfsm();
+sfsm.loadFA(turnstileFa as FaDefinition);
+
+sfsm.getHeadState();          // 'I'  — the reserved entry state
+
+sfsm.receiveSignal('start');
+sfsm.getHeadState();          // 'locked'
+
+sfsm.receiveSignal('coin');
+sfsm.getHeadState();          // 'unlocked'
+
+sfsm.receiveSignal('push');
+sfsm.getHeadState();          // 'locked'
+```
+
+A runnable version of this exact example is available as a unit test: [01-what-is-a-finite-automaton.test.ts](../../ts-stop/test/sfsm/tutorial/01-what-is-a-finite-automaton.test.ts).
+
+### 2.1 A type-safe alternative
+
+The plain-string form above is convenient, but nothing stops a typo like `"lokced"` from silently compiling — the `Transition` type accepts any string in each slot. If you would rather have the TypeScript compiler catch such typos, declare your states and signals as string-literal union types first, and write the transition list against them with a small generic helper:
+
+```typescript
+import { Sfsm, FaDefinition, Transition } from '@vsirotin/ts-stop/sfsm';
+
+type TurnstileState = 'I' | 'locked' | 'unlocked';
+type TurnstileSignal = 'start' | 'coin' | 'push';
+
+// A transition restricted to a specific pair of state/signal literal types.
+type TypedTransition<S extends string, G extends string> = [S, G, S];
+
+// Accepts only transitions built from S/G, returns the plain runtime Transition[]
+// that Sfsm actually consumes — no change to the library's runtime format.
+function typedTransitions<S extends string, G extends string>(
+    transitions: Array<TypedTransition<S, G>>
+): Transition[] {
+    return transitions;
+}
+
+const turnstileTransitions = typedTransitions<TurnstileState, TurnstileSignal>([
+    ['I',        'start', 'locked'],
+    ['locked',   'coin',  'unlocked'],
+    ['unlocked', 'push',  'locked'],
+    // ['locked', 'coin', 'lokced'],   // ✗ compile error: 'lokced' is not TurnstileState
+]);
+
+const turnstileFa: FaDefinition = { Turnstile: turnstileTransitions };
+
+const sfsm = new Sfsm();
+sfsm.loadFA(turnstileFa);
+```
+
+This costs nothing at runtime — `typedTransitions()` just returns its argument — but any misspelled state or signal name is now a compile-time error instead of a silent bug. A runnable version of this example is available as a unit test: [02-type-safe-fa-definition.test.ts](../../ts-stop/test/sfsm/tutorial/02-type-safe-fa-definition.test.ts).
+
+
+## 3. Jokers: wildcard signals and states
+
+Writing out every single `<s0, g, s1>` transition by hand works well for a tidy, well-behaved automaton like our turnstile. Real devices, however, are messier: they can receive signals nobody planned for, and they can be told to do the same thing no matter what they happen to be doing at the time. Enumerating every combination by hand would make the transition list explode and, worse, would be all too easy to forget a case.
+
+For this, the `Sfsm` engine supports **jokers** — a reserved value (`"*"` by default) that can stand in for "any signal" or "any state" in a transition:
+
+- A **joker-signal** transition `[s0, "*", s1]` matches *any* signal while the automaton is in state `s0` — but only as a fallback: if a transition for the exact, literal signal already exists for `s0`, that one wins.
+- A **joker-state** transition `["*", g, s1]` matches signal `g` from *any* current state — again only as a fallback, behind any transition that names the exact, literal state.
+
+Because jokers are only a fallback, you can freely mix them with ordinary transitions without worrying about ordering: an exact match always takes priority, so the recommendation is simply to place joker transitions last in the list, purely for readability.
+
+Jokers are configured through `SfsmOptions` when constructing the engine:
+
+```typescript
+const sfsm = new Sfsm({
+  jokerSignal: '*', // default — the value that means "any signal"
+  jokerState:  '*'  // default — the value that means "any state"
+});
+```
+
+You will rarely need to change these from the default `"*"`; the option exists mainly so you can pick a different symbol if `"*"` ever needs to be a real state or signal name in your own FA.
+
+### 3.1 Joker signal: reacting to the unexpected (e.g. a power failure)
+
+Imagine our turnstile's electronics can, at any moment, receive all sorts of diagnostic signals from its sensors — most of which are irrelevant, except that *any* signal that isn't part of its normal vocabulary (`coin`, `push`) should be treated as a sign that something is wrong (power dropping out, a sensor glitching, a cable disconnected...) and the safest reaction is to shut the turnstile down into a safe `off` state.
+
+Instead of trying to list every possible malfunction signal, one joker-signal transition per operational state covers all of them at once:
+
+```json
+{
+  "Turnstile": [
+    ["I",        "start", "locked"],
+    ["locked",   "coin",  "unlocked"],
+    ["unlocked", "push",  "locked"],
+    ["locked",   "*",     "off"],
+    ["unlocked", "*",     "off"]
+  ]
+}
+```
+
+```typescript
+import { Sfsm, FaDefinition } from '@vsirotin/ts-stop/sfsm';
+
+const sfsm = new Sfsm();
+sfsm.loadFA(turnstileWithJokerSignalFa as FaDefinition);
+
+sfsm.receiveSignal('start');
+sfsm.getHeadState();             // 'locked'
+
+sfsm.receiveSignal('coin');
+sfsm.getHeadState();             // 'unlocked'  (exact transition still wins)
+
+sfsm.receiveSignal('powerFailure');
+sfsm.getHeadState();             // 'off'       (joker-signal fallback)
+```
+
+The turnstile keeps behaving exactly as before for `coin` and `push`; only signals it has no explicit rule for fall through to `*` and trigger the safety shutdown.
+
+A runnable version of this example is available as a unit test: [03-joker-signal.test.ts](../../ts-stop/test/sfsm/tutorial/03-joker-signal.test.ts).
+
+### 3.2 Joker state: a universal signal for technical personnel
+
+Now imagine the opposite situation: a maintenance technician needs to send a `service` signal that must always work, no matter what the turnstile happens to be doing — locked, unlocked, mid-transaction, or even already `off`. The technician should not need to know (or care) about the turnstile's current state; they just need "put this thing into maintenance mode, now."
+
+A single joker-state transition expresses exactly that, regardless of how many operational states the FA has:
+
+```json
+{
+  "Turnstile": [
+    ["I",        "start",   "locked"],
+    ["locked",   "coin",    "unlocked"],
+    ["unlocked", "push",    "locked"],
+    ["*",        "service", "maintenance"]
+  ]
+}
+```
+
+```typescript
+import { Sfsm, FaDefinition } from '@vsirotin/ts-stop/sfsm';
+
+const sfsm = new Sfsm();
+sfsm.loadFA(turnstileWithJokerStateFa as FaDefinition);
+
+sfsm.receiveSignal('start');
+sfsm.receiveSignal('service');
+sfsm.getHeadState();             // 'maintenance' — reached straight from 'locked'
+
+// ...and it works the same from any other state:
+sfsm.loadFA(turnstileWithJokerStateFa as FaDefinition);
+sfsm.receiveSignal('start');
+sfsm.receiveSignal('coin');      // now 'unlocked'
+sfsm.receiveSignal('service');
+sfsm.getHeadState();             // 'maintenance' — reached just as easily from 'unlocked'
+```
+
+One transition now covers "enter maintenance mode" from every current and future state — including states added to the FA later, with no changes needed to the `service` rule itself.
+
+A runnable version of this example is available as a unit test: [03-joker-state.test.ts](../../ts-stop/test/sfsm/tutorial/03-joker-state.test.ts).
+
+In the [next chapter](./02-stacked-finite-state-machine.md) we will see how to combine multiple FAs into a hierarchy, and how the `Sfsm` engine processes signals through that hierarchy.
+

package/tutorial/02-stacked-finite-state-machine.md

@@ -0,0 +1,32 @@
+# StOP Tutorial. Part 2: Stacked Finite State Machines
+
+## 4. What is a Stacked Finite State Machine (SFSM)?
+
+The turnstile so far is a single, flat automaton — a nice fit for the pure theory from chapter 1. Real systems, however, are rarely that simple: a "check the coin" step is itself a small process with its own states, and a "process a payment" step might contain both "check a coin" and "check a banknote" as alternatives inside it. Modelling all of that as one giant flat FA would quickly become unreadable.
+
+The **Stacked Finite State Machine (SFSM)** solves this by allowing a state to be, itself, another whole FA. This turns the picture from a single flat automaton into a **tree of FAs**: a root FA at the top, and any number of nested child FAs underneath it (each of which can itself have children, and so on). The SFSM engine (the `Sfsm` class) keeps an internal **stack** of currently-active FAs to process this tree: the bottom of the stack is always the root FA, and the top (the "head") is whichever FA is currently handling incoming signals. The stack grows (push) when a state turns out to be a sub-FA, and shrinks (pop) when a sub-FA finishes and control returns to its parent.
+
+Two small naming conventions make this hierarchy work uniformly for every FA, at any depth:
+- every FA has exactly one **entry state**, always named `"I"` or `"*.I"` (as already seen in chapters 1–3);
+- every FA has one or more **exit states**, each named starting with `"E_"` or `"*-E_"` — reaching one means "this FA is done, hand control back to whoever activated it."
+
+Here is a small, self-contained FA that only makes sense as a *child* of something bigger: it models checking a banknote offered as payment, without yet worrying about who offers it or what happens afterwards. It has one entry state, one "business" state per step, and three possible outcomes:
+
+```json
+{
+  "BPP": [
+    ["I",        "BR.bc",           "checking",  "BC.check"],
+    ["checking", "BC.pass",         "accepting", "BA.accept"],
+    ["checking", "BC.reject",       "E_rejected"],
+    ["accepting","BA.changeNeeded", "E_changeNeeded"],
+    ["accepting","BA.noChangeNeeded","E_noChangeNeeded"]
+  ]
+}
+```
+
+ Its real purpose, though, is to later become a *state* inside a bigger turnstile finite state machine (FSM), at which point reaching an exit state pops it and hands the triggering signal back to its parent instead of resetting. 
+
+A runnable version of this example is available as a unit test: [04-stacked-finite-state-machine.test.ts](../../ts-stop/test/sfsm/tutorial/04-stacked-finite-state-machine.test.ts).
+
+
+

package/tutorial/03-advanced-themes.md

@@ -0,0 +1,110 @@
+# StOP Tutorial. Part 3: Advanced Themes
+
+## 5. How stacked states are processed
+
+Once an FA can contain other FAs, "processing a signal" needs a precise algorithm — not just "look up the transition," but also "where do I look, and what happens once I find (or fail to find) one." Here are the rules the `Sfsm` engine actually implements (verified directly against its source, `Sfsm.ts`):
+
+1. After `loadFA()`, the root FA is the only element on the stack and its active state is `"I"`. The engine now waits for a signal.
+2. When a signal `s` arrives, the engine searches for a matching transition, starting at the **head** of the stack (the innermost, currently active FA) and, if needed, continuing down through each ancestor FA towards the root:
+   - **2.1** — If the head FA has a transition matching its own active state and `s` (including joker fallbacks, see chapter 3), that transition is applied directly: the head's active state becomes the transition's target. This step is logged with rule `"2.1"`.
+   - **2.2** — If the head FA has *no* matching transition, the search continues in its parent FA, then that FA's parent, and so on down to the root.
+     - **2.2.1** — If a matching transition is found in some ancestor FA, every FA above it on the stack is popped (they are abandoned mid-flight), that ancestor becomes the new head, and the transition is applied there. 
+     - **2.2.2** — If **no** FA anywhere in the stack — from the head all the way down to the root — has a matching transition, **no log entry is created**, and the engine instead applies the `byMissingTransition` policy (`'error'` throws, `'log_warning'` warns and does nothing, `'ignore'` silently does nothing).
+3. If the transition found in step 2 carries a command (its 4th element), the command is sent to the registered command receiver. 
+4. If the transition's target state is itself the name of a sub-FA, that sub-FA is pushed onto the stack with active state `"I"`, and the very same signal `s` is immediately forwarded into it, restarting this whole process (step 2) one level deeper.
+5. If the transition's target state is an exit state (starts with `"E_"`):
+   - **5.1** — if the current FA is the only one left on the stack (the root), it simply resets its own active state back to `"I"`;
+   - **5.2** — otherwise, the current FA is popped off the stack, and the very same signal `s` is forwarded to the FA that is now the head, restarting this whole process (step 2) one level up.
+
+
+The example of using the SFSM engine can be found in [Sfsm.log.test.ts](../../ts-stop/test/sfsm/Sfsm.log.test.ts).
+
+## 6. Signal Senders, Command Receivers, Controllers, and the Controller Hub
+
+Everything so far has driven the `Sfsm` engine directly, by calling `receiveSignal()` from test code. In a real application, signals come from real devices — a coin slot, a push sensor, a button — and commands need to reach real devices too — a lock, a light, a dispenser. The library gives you three small building blocks to wire this up cleanly:
+
+- **`SignalSender`** — an abstract base class you extend on any component that needs to emit signals into the SFSM. You implement `getSignalNames()` (the list of signal names it may ever send) and call the protected `sendSignal(name, data?)` method whenever something happens in the real world.
+- **`CommandReceiver`** — an abstract base class (or, if a class already extends something else, the `ICommandReceiver` interface it mirrors) for any component that needs to react to commands coming *from* the SFSM. You implement `getCommandNames()` (the commands it can handle) and `receiveCommand(command, data?)`.
+- **Controller** — not a class, but a *role*: any component that plays the `SignalSender` role, the `CommandReceiver` role, or (as most real devices do) both at once, is called a Controller.
+- **`ControllerHub`** — the wiring hub that connects every Controller to one `Sfsm` instance. You register each Controller once with `registerSignalSender()` and/or `registerCommandReceiver()`, then call `connectTo(sfsm)`. From then on, the hub automatically routes every command the SFSM sends to the right Controller (by the exact command name), and forwards every signal a Controller sends into the SFSM.
+
+Here is a minimal physical turnstile "gate" Controller — it plays both roles at once, exactly like the real simulators used elsewhere in this library's own test suite:
+
+```typescript
+import { Sfsm, FaDefinition, SignalSender, ICommandReceiver, ControllerHub } from '@vsirotin/ts-stop/sfsm';
+
+class TurnstileGate extends SignalSender implements ICommandReceiver {
+    private locked = true;
+
+    getSignalNames(): readonly string[] { return ['start', 'coin', 'push']; }
+    getCommandNames(): readonly string[] { return ['GATE.lock', 'GATE.unlock']; }
+
+    receiveCommand(command: string): void {
+        this.locked = command === 'GATE.lock';
+    }
+
+    isLocked(): boolean { return this.locked; }
+
+    start(): void       { this.sendSignal('start'); }
+    insertCoin(): void  { this.sendSignal('coin'); }
+    walkThrough(): void { this.sendSignal('push'); }
+}
+
+const turnstileFa: FaDefinition = {
+    Turnstile: [
+        ['I',        'start', 'locked'],
+        ['locked',   'coin',  'unlocked', 'GATE.unlock'],
+        ['unlocked', 'push',  'locked',   'GATE.lock']
+    ]
+};
+
+const sfsm = new Sfsm();
+const gate = new TurnstileGate();
+
+new ControllerHub()
+    .registerSignalSender(gate)
+    .registerCommandReceiver(gate)
+    .connectTo(sfsm);
+
+sfsm.loadFA(turnstileFa);
+
+gate.start();
+gate.insertCoin();
+gate.isLocked();      // false — the SFSM sent 'GATE.unlock' in response to 'coin'
+
+gate.walkThrough();
+gate.isLocked();      // true  — the SFSM sent 'GATE.lock' in response to 'push'
+```
+
+Notice that `TurnstileGate` never touches the `Sfsm` instance directly: it only knows how to emit its own signals and react to its own commands. All the wiring — "which Controller sends which signal," "which Controller handles which command" — lives in one place, the `ControllerHub`, which also gives you `getRegisteredSignals()` / `getRegisteredCommands()` for diagnostics (e.g. to validate that every signal and command mentioned in an FA definition actually has a Controller behind it).
+
+A runnable version of this example is available as a unit test: [06-controllers-and-controller-hub.test.ts](../../ts-stop/test/sfsm/tutorial/06-controllers-and-controller-hub.test.ts).
+
+### 7. Name conventions
+
+Every example so far has named the entry state simply `"I"` and exit states `"E_something"` — perfectly fine for a small, self-contained FA. Once a stacked SFSM grows to dozens of FAs, plain abbreviations like `"L"`, `"U"`, `"I"`, `"E_R"` start colliding in your head across FAs, and it becomes hard to tell, just by looking at a state name, *which* FA it belongs to.
+
+For larger SFSMs, it is recommended to namespace state names with their own FA's name, using a dot: `<FaName>.I` for the entry state, and `<FaName>.<state>` for ordinary states — e.g. `TS.I`, `TS.L`, `TS.U` instead of bare `I`, `L`, `U`. Exit states keep their familiar `E_` marker but move it after the FA-name dot: `<FaName>.E_<name>` — e.g. `TS.E_ok` instead of bare `E_ok`.
+
+```json
+{
+  "TS": [
+    ["TS.I", "TS.s",   "TS.L"],
+    ["TS.L", "TS.coin", "TS.U"],
+    ["TS.U", "TS.push", "TS.L"]
+  ]
+}
+```
+
+The `Sfsm` engine recognises **both** forms everywhere, automatically:
+- an entry state is whatever from-state a FA's own transitions use that is exactly `"I"` **or** ends with `".I"`;
+- an exit state is any target state that starts with `"E_"` **or** contains `".E_"`.
+
+This means:
+- every FA fixture used earlier in this tutorial (bare `"I"` / `"E_..."`) keeps working exactly as written — no migration is required;
+- you can freely mix both styles across FAs in the same SFSM (e.g. namespace only the FAs that are large enough to benefit from it);
+- nothing else changes — this is purely a naming convention for readability, not a new engine feature: no new `SfsmOptions`, no change to how transitions, pushes, pops, or jokers are matched.
+
+A runnable version of this example, built entirely with namespaced names, is available as a unit test: [08-namespaced-state-names.test.ts](../../ts-stop/test/sfsm/tutorial/08-namespaced-state-names.test.ts).
+
+In future this part of tutorial will be expanded with more advanced topics, including description of best practices for building large SFSMs, and a few more examples of real-world applications.