zebra-spaces: lay down FSM framework + publishSpec + unit tests

First step of the state-machine refactor. Same self-contained pattern
as the rest of the page — FSMs live inline in web/zebra-spaces.html so
the page-integrity stamp keeps working, and the tests extract them with
the same regex/brace-match technique web-protocol.test.js already uses
(page = source of truth, tests track the page).

Added:
- createFSM(spec): minimal state machine. spec.states[name] has optional
  entry/exit hooks and an .on table mapping events → target (string) or
  { target, action }. Observers fire after each transition with
  { state, prev, ev, ctx }. No async in transitions; effects belong in
  observers (which can call send() to advance the machine).
- publishSpec: pure transition table for the publish flow.
    off ──START──▶ acquiring ──ACQUIRED──▶ negotiating ──NEGOTIATED──▶ live
                       │ FAILED                │ FAILED                │ STOP/LOST
                       ▼                       ▼                       ▼
                      off                    stopping ◀──── stopping ──┘
                                                 │ DONE
                                                 ▼
                                                off
  One instance per kind (mic / screen / camera). FAILED in negotiating
  goes to stopping (not off) so any acquired stream/pc gets torn down.
- test/zebra-fsm.test.js: 23 unit tests covering framework semantics +
  publishSpec happy path + error/cancel paths + illegal-transition
  no-ops. Function-constructor scope handles const-leak; bare eval()
  doesn't expose const declarations to the harness.
- Makefile: test-fsm target + included in test-all.

Next: SubscribeFSM, CallFSM, RemoteTileFSM. Then wire each into the
imperative call sites progressively, replacing the firefighting code.
This commit is contained in:
Russell Ballestrini 2026-06-02 11:01:33 -04:00
parent f71e9e74c4
commit ebda460574
No known key found for this signature in database
3 changed files with 409 additions and 3 deletions

View file

@ -19,6 +19,12 @@ test: test/unit
test-web:
@node test/web-protocol.test.js
# zebra-spaces state-machine tests — pure unit tests for the FSM framework
# + each machine spec (publish / subscribe / call / remote-tile). Extracts
# the live code from web/zebra-spaces.html so the tests track the page.
test-fsm:
@node test/zebra-fsm.test.js
# zebra-spaces JS↔Go protocol parity + vault + ed25519 + (optionally) a live
# server flow. The live-server tier auto-runs when proxy.unturf.com sits
# alongside this checkout AND has a Go toolchain — we build the relay binary
@ -36,7 +42,7 @@ test-zebra-spaces:
ZEBRA_SPACES_BINARY=$$bin node test/zebra-spaces.test.js; \
rc=$$?; rm -f /tmp/zspc-signal-test; exit $$rc
test-all: test/unit test/integration test/functional test-web test-zebra-spaces
test-all: test/unit test/integration test/functional test-web test-fsm test-zebra-spaces
@echo "--- unit ---"
@./test/unit
@echo "--- integration ---"
@ -45,6 +51,8 @@ test-all: test/unit test/integration test/functional test-web test-zebra-spaces
@./test/functional
@echo "--- web protocol ---"
@node test/web-protocol.test.js
@echo "--- zebra-fsm ---"
@node test/zebra-fsm.test.js
@echo "--- zebra-spaces ---"
@$(MAKE) -s test-zebra-spaces