feat: enhance sorter simulation demo

docs/ARCHITECTURE.md

@@ -0,0 +1,71 @@
+# Architecture
+
+## Module Map
+
+```text
+src/data/items.ts
+src/data/scenarios.ts
+        |
+        v
+src/domain/classifier.ts  ->  src/domain/simulation.ts  ->  React UI components
+        |                         |
+        |                         +-> metrics, PID, sensors, event log
+        v
+classification result
+```
+
+## Data Flow
+
+1. Scenario selects a sequence of mock items.
+2. Simulation feeds one item at a time into zone A.
+3. Pseudo-CV and sensors derive measurements from item data.
+4. `classifyItem` applies deterministic rules.
+5. State machine commands gate and pushers.
+6. UI renders SVG scene, panels, metrics, timeline and event log.
+
+## Pseudo-CV
+
+The MVP does not run real ML. Camera output is generated from item dimensions:
+
+- bbox width/depth;
+- confidence;
+- CV latency;
+- detected dimensions.
+
+Low confidence is not ignored: the event log and classification panel show a warning and explain rule-based fallback.
+
+## Sensor Simulation
+
+- Camera is active in `DETECTING`.
+- Laser is active during `DETECTING` and `MOVING_TO_GATE`.
+- Ultrasonic sensor is active at `WAITING_AT_GATE` and `CLASSIFYING`.
+
+Each sensor keeps active state, last value, latency and last event timestamp.
+
+## Actuator Control
+
+- Stop-gate closes at `WAITING_AT_GATE`.
+- B route opens the gate and sends item straight.
+- C route keeps the gate closed and extends pusher C.
+- D route keeps the gate closed and extends pusher D.
+- `RETURN_HOME` retracts mechanisms.
+
+## State Machine
+
+Main cycle:
+
+```text
+IDLE -> MOVING_TO_CAMERA -> DETECTING -> MOVING_TO_GATE -> WAITING_AT_GATE
+-> CLASSIFYING -> ROUTE_TO_B/C/D -> RETURN_HOME -> next item or IDLE
+```
+
+Fault states:
+
+- `FAULT` for jam at gate;
+- `EMERGENCY_STOP` for emergency stop scenario.
+
+Both stop conveyor motion and require Reset.
+
+## Metrics
+
+The dashboard tracks processed count, success/error count, avg cycle time, throughput, CV latency, actuator latency, queue length, queue delay and conveyor speed.

docs/DEMO_SCRIPT.md

@@ -0,0 +1,69 @@
+# Demo Script
+
+Target duration: 3-5 minutes.
+
+## 1. Open The Dashboard
+
+Open https://arhipovdan.ru/.
+
+Explain that this is a 2D engineering simulation, not a decorative animation: the SVG scene shows a scaled work zone, conveyor dimensions, sensors, stop-gate, pushers and roll-cages.
+
+## 2. Normal Flow
+
+Select `Normal flow`, press `Start`.
+
+Explain:
+
+- item enters zone A;
+- camera captures bbox;
+- laser measures height;
+- ultrasonic confirms gate position;
+- gate holds item;
+- classifier selects B/C/D;
+- route command is shown on the scene;
+- event log records the full cycle.
+
+Question closed: can the system show a full sorting cycle end-to-end?
+
+## 3. Step-By-Step Decision
+
+Press `Reset`, then use `Step state`.
+
+Explain each state in the timeline. Show that Step advances by logical state, not by arbitrary animation time.
+
+Question closed: can the jury inspect synchronization and state transitions?
+
+## 4. Oversized And Round Rules
+
+Select `Oversized item`, step to classification.
+
+Show decision tree:
+
+- dimensions check fails;
+- category C selected;
+- roundness is lower priority because dimensions are checked first.
+
+Then select `Round object` and show D when dimensions pass and roundness >= 0.8.
+
+Question closed: how is classification proved?
+
+## 5. Robustness Scenarios
+
+Show `close_items`, `low_confidence`, `jam`, `emergency_stop`.
+
+Explain:
+
+- close items generate spacing warning and queue length;
+- low confidence uses rule-based fallback;
+- jam enters FAULT and stops conveyor;
+- emergency stop enters EMERGENCY_STOP and requires Reset.
+
+Question closed: what happens outside the happy path?
+
+## 6. PID And Metrics
+
+Point to PID panel and metrics cards.
+
+Explain that PID is simplified: actual speed approaches target in normal flow and decays toward zero in fault/emergency.
+
+Question closed: how is conveyor control represented without overbuilding physics?

docs/JURY_QA.md

@@ -0,0 +1,41 @@
+# Jury Q&A
+
+## 1. Why 2D, Not 3D?
+
+2D is enough for MVP validation: it shows geometry, timing, sensor positions, routes and state transitions without spending effort on heavy rendering.
+
+## 2. Where Is Computer Vision?
+
+The MVP uses pseudo-CV: bbox, dimensions, confidence and latency are derived from mock items. The architecture keeps CV output separate from classification, so a real CV service can replace it later.
+
+## 3. How Is Classification Correctness Proven?
+
+The decision tree shows PASS/FAIL for dimensions and roundness, actual values, thresholds and final category. Tests cover key boundary cases.
+
+## 4. How Are Dimensions And Circular Section Handled?
+
+Dimensions are checked first against min/max width, depth and height. If they pass, roundness is checked against threshold 0.8.
+
+## 5. Why Does C Have Priority Over D?
+
+Oversized or undersized items are operationally unsafe for the main line and must be diverted first. Therefore dimensions check precedes roundness.
+
+## 6. How Is Synchronization Shown?
+
+Cycle timeline shows state order, simulated timestamps, durations and status: done, active, pending or skipped.
+
+## 7. How Does The Actuator Part Work?
+
+The stop-gate fixes the item. B opens the gate, C extends pusher C, D extends pusher D, then mechanisms return home.
+
+## 8. What Happens On Jam?
+
+The system enters FAULT, conveyor target speed becomes 0, actual speed decays toward 0, and Reset is required.
+
+## 9. What Happens On Low CV Confidence?
+
+A warning is logged, but the system still classifies by deterministic dimensions and roundness rules.
+
+## 10. How To Scale This To A Real Hardware-Software System?
+
+Replace pseudo-CV with a CV service, connect PLC/robot telemetry via backend/WebSocket, persist event logs, calibrate sensor latencies and add recovery policies.

docs/SCENARIOS.md

@@ -0,0 +1,49 @@
+# Scenarios
+
+## normal_flow
+
+Goal: demonstrate the full cycle across B/C/D routes.
+
+Expected result: mixed B, C and D items are processed successfully.
+
+## oversized_item
+
+Goal: prove dimensions have first priority.
+
+Expected result: every item routes to C.
+
+## round_object
+
+Goal: prove roundness check after dimensions.
+
+Expected result: every item routes to D.
+
+## boundary_dimensions
+
+Goal: test min/max boundaries.
+
+Expected result: `Boundary box 450x320x320` routes to B, `Pen 9x13x148` routes to C.
+
+## close_items
+
+Goal: demonstrate queue/spacing resilience.
+
+Expected result: warning appears, queue length is shown, items are processed sequentially.
+
+## low_confidence
+
+Goal: demonstrate fallback when pseudo-CV confidence is below 0.65.
+
+Expected result: warning appears, rule-based classification still selects B or D.
+
+## jam
+
+Goal: demonstrate fail-safe behavior at stop-gate.
+
+Expected result: state becomes FAULT, conveyor speed target is 0, Reset is required.
+
+## emergency_stop
+
+Goal: demonstrate emergency stop.
+
+Expected result: state becomes EMERGENCY_STOP, conveyor speed target is 0, Reset is required.