15 State Machines, Zero Frameworks📋

Architecture of a Terminal-Themed CV Site📋

This site started as three JavaScript files and a question at 3 AM: "Can you turn my PDF resume into a website?" What came back was 5,620 lines of vanilla JS that worked -- until it didn't. Every new feature tangled with every other feature. Navigation raced with scroll spy. The TOC fought with the headings panel. Copy feedback timers leaked. And there was no way to test any of it without opening a browser.

The fix was not a framework. It was 15 state machines -- pure TypeScript functions with zero DOM dependencies, zero side effects, and zero coupling between them. Each one small enough to read in five minutes. Each one testable in milliseconds. Together, they run every interactive behavior on this site.

This series walks through the extraction, from the simplest toggle to the most complex scroll orchestration, then covers the TypeScript migration that made the interfaces explicit and the testing strategy that keeps them honest.

Before and After📋

Table of Contents📋

Part I: Three Files and Five Thousand Lines📋

The original architecture and why it broke. State encoded as booleans, race conditions on rapid clicks, DOM coupling that made unit testing impossible. The "before" picture that motivated everything that follows.

Part II: The Pattern -- Factory, Closures, Callbacks📋

The architecture applied to the four simplest machines: FontSizeManager, AccentPaletteMachine, CopyFeedbackMachine, and SidebarResizeMachine. Factory functions, closure state, callback injection, guard clauses, and pure helpers. The template that every machine follows.

Part III: Navigation and Interaction Machines📋

SpaNavMachine and PageLoadMachine -- the two machines that orchestrate every page transition. Plus TourStateMachine, ScrollSpyMachine, ZoomPanState, and KeyboardNavState. Navigation classification, the generation counter pattern, composition at the wiring layer, and three pattern variations.

Part IV: The TOC Machine Cluster -- When Simple Isn't Enough📋

Five machines that power the table of contents. From the 30-line TocTooltipMachine to the 8-state TocScrollMachine -- the most complex machine in the project. Geometry injection, timer injection, user scroll locking, and the wiring diagram that connects them all.

Part V: From Vanilla JS to TypeScript📋

The migration that made it all explicit. tsconfig choices, esbuild for browser bundles, tsx for scripts, the IIFE output format, and concrete bugs that strict mode caught. Two build pipelines: browser (esbuild) and Node.js (tsx).

Part VI: Testing Pure State Machines📋

98% statement coverage with zero DOM dependencies. Unit tests with Vitest, property-based tests with fast-check, E2E tests with Playwright, coverage thresholds as quality gates, and the @FeatureTest / @Implements decorator system that links tests to requirements.

How to Read This Series📋

If you want the architecture: Start with Part I for motivation, then Part II for the pattern. Parts III and IV apply it at increasing complexity.

If you want the migration story: Jump to Part V (TypeScript) and Part VI (testing). They reference earlier parts but stand alone.

If you're here for the TOC complexity: Part IV is the climax. But read Part II first -- it introduces the vocabulary (factory function, callback injection, guard clause, geometry injection) that Part IV uses heavily.

The Machine Catalog📋

All 15 state machines, sorted by complexity:

Key Concepts by Part📋

This table maps each concept to the part where it's introduced:

Related📋

• This Website: From PDF to Terminal-Styled SPA in 72 Hours -- the origin story
• This Website: Going Static -- static generation and SEO
• FiniteStateMachine: Three Tiers, One Engine, Zero Exceptions -- the .NET FSM framework (different project, same philosophy)