Add API reference generation and website

[SandroMaglione]

Summary

• add an Effect-aligned TypeDoc extraction pipeline that emits one JSON document per configured public module
• add a lightweight static API-reference website with module navigation, source links, responsive layout, search, and TypeScript highlighting
• deploy the generated website to GitHub Pages after releases, with a manual workflow trigger for pre-release testing
• document the public API with 0.4.0 introduction metadata and focused examples for the primary Machine, testing, reactivity, and Cluster workflows
• fail documentation checks when a public declaration lacks a summary, category, version, or a configured major API lacks an example

Changeset

• Added or updated for a library or package-metadata change
• Not required because this PR does not change src/ or package.json

Validation

• pnpm check
• pnpm docs:site
• Generated JSON and website metadata audit across all four public modules
• Syntax validation for all 26 extracted TypeScript examples
• Relevant example checks, when examples changed (not applicable; no example package changed)
• Reviewed the automated type-performance report, when the public TypeScript API or inference changed (not applicable; documentation and tooling only)
• Reviewed the automated runtime-performance report, when runtime behavior changed (not applicable; documentation and tooling only)

The website deployment can be tested before the next package release through the manual Website workflow trigger.

[github-actions]

Type performance

Measured with TypeScript 6.0.3 and skipLibCheck=true.

Scenario	Base	PR	Difference
Effect only	55	55	0 (0.0%)
Import effect-machine	55	55	0 (0.0%)
Machine.defineStates (3 states)	2,965	2,965	0 (0.0%)
Machine.make (3 states, 2 events)	8,715	8,715	0 (0.0%)
machine.handle (3 states, 2 transitions)	23,492	23,492	0 (0.0%)
machine.handle (depth 8)	117,075	117,075	0 (0.0%)
machine.handle (depth 12)	129,713	129,713	0 (0.0%)
machine.handle (depth 16)	145,055	145,055	0 (0.0%)
machine.handle (depth 24)	183,851	183,851	0 (0.0%)
machine.handle (wide depth 16)	214,189	214,189	0 (0.0%)
machine.handle (parallel/history/choice)	132,667	132,667	0 (0.0%)
machine.handle (4 successive calls)	128,674	128,674	0 (0.0%)
machine exact input/output/error/services	110,584	110,584	0 (0.0%)
execution adapter readiness	127,854	127,854	0 (0.0%)

Marginal instantiations are measured against the matching setup without that API call:

Scenario	Base	PR	Difference
Import effect-machine	0	0	0
Machine.defineStates (3 states)	2,910	2,910	0 (0.0%)
Machine.make (3 states, 2 events)	5,742	5,742	0 (0.0%)
machine.handle (3 states, 2 transitions)	14,777	14,777	0 (0.0%)
machine.handle (depth 8)	109,601	109,601	0 (0.0%)
machine.handle (depth 12)	121,039	121,039	0 (0.0%)
machine.handle (depth 16)	135,181	135,181	0 (0.0%)
machine.handle (depth 24)	171,577	171,577	0 (0.0%)
machine.handle (wide depth 16)	202,224	202,224	0 (0.0%)
machine.handle (parallel/history/choice)	114,331	114,331	0 (0.0%)
machine.handle (4 successive calls)	113,703	113,703	0 (0.0%)
machine exact input/output/error/services	100,670	100,670	0 (0.0%)
execution adapter readiness	102,092	102,092	0 (0.0%)

Check times (informational)

Scenario	Base	PR
Effect only	0.03s	0.03s
Import effect-machine	0.03s	0.03s
Machine.defineStates (3 states)	0.09s	0.09s
Machine.make (3 states, 2 events)	0.14s	0.15s
machine.handle (3 states, 2 transitions)	0.23s	0.21s
machine.handle (depth 8)	0.48s	0.49s
machine.handle (depth 12)	0.57s	0.53s
machine.handle (depth 16)	0.65s	0.57s
machine.handle (depth 24)	0.71s	0.64s
machine.handle (wide depth 16)	0.71s	0.70s
machine.handle (parallel/history/choice)	0.59s	0.56s
machine.handle (4 successive calls)	0.53s	0.54s
machine exact input/output/error/services	0.48s	0.49s
execution adapter readiness	0.54s	0.54s

Type instantiations are the comparison metric. Check time varies with runner load and is informational only.

[github-actions]

Runtime performance

Median of 5 independent benchmark processes on AMD EPYC 7763 64-Core Processor with Node v24.18.0.

Pull request baseline

Scenario	Effect Machine	XState 5	XState 6 alpha
Plan counter transitions	123,581 transitions/s	133,028 transitions/s	12,857 transitions/s
Drain burst with terminal fence	485,891 increments/s	388,054 increments/s	191,693 increments/s
Drain burst with a change observer	446,442 increments/s	384,354 increments/s	190,986 increments/s
Lookup and send to one child	381,726 increments/s	381,390 increments/s	183,545 increments/s
Start and stop a machine	167,168 machines/s	183,486 machines/s	143,000 machines/s
Start and stop a parent with one child	32,523 families/s	68,273 families/s	40,858 families/s
Plan transitions through a compound state	117,031 transitions/s	—	—
Plan transitions through parallel regions	91,143 transitions/s	—	—
Drain burst through a compound state	497,566 events/s	341,758 events/s	189,007 events/s
Drain burst through two parallel regions	456,922 events/s	257,861 events/s	143,655 events/s
Drain a compound-state burst with a change observer	452,925 events/s	—	—

Effect runtime reference points

Scenario	Effect Machine	Effect runtime primitives
Start and stop a raw generic process	16,341 processes/s	—
Start and stop a raw compiled process	66,854 processes/s	—
Start and interrupt a suspended fiber	—	164,447 fibers/s
Start and stop a queue worker	—	116,063 workers/s
Start and stop an actor shell	—	106,758 actors/s
Start and stop two actor shells	—	64,562 families/s
Update an owner-only mutable snapshot	—	316,856,781 updates/s
Update a synchronized snapshot	—	1,544,411 updates/s
Create, resolve, and await a terminal latch	—	1,423,003 latches/s

Memory profile	Effect Machine	XState 5	XState 6 alpha	Effect runtime primitives
Idle machine	1.5 KiB	3.8 KiB	2.2 KiB	—
Raw generic managed process	12.7 KiB	—	—	—
Raw compiled process	2.8 KiB	—	—	—
Two independent idle machines	3.0 KiB	7.3 KiB	3.9 KiB	—
Idle parent with one child	4.8 KiB	5.5 KiB	4.0 KiB	—
Parent with observed child registry	9.0 KiB	—	—	—
Parent with observed invoked child snapshots	5.0 KiB	—	—	—
Suspended Effect fiber	—	—	—	0.6 KiB
Effect queue with waiting fiber	—	—	—	2.8 KiB
Effect mailbox actor shell	—	—	—	3.2 KiB
Two Effect actor shells	—	—	—	6.8 KiB

Effect Machine change from base

Metric	Base	Base variability	PR	PR variability	Difference
Plan counter transitions	125,292 transitions/s	1.1% MAD	123,581 transitions/s	0.9% MAD	-1.4%
Drain burst with terminal fence	483,519 increments/s	1.0% MAD	485,891 increments/s	1.5% MAD	+0.5%
Drain burst with a change observer	463,087 increments/s	0.7% MAD	446,442 increments/s	2.5% MAD	-3.6%
Lookup and send to one child	414,905 increments/s	1.6% MAD	381,726 increments/s	1.5% MAD	-8.0%
Start and stop a machine	179,211 machines/s	1.4% MAD	167,168 machines/s	1.4% MAD	-6.7%
Start and stop a parent with one child	38,808 families/s	2.4% MAD	32,523 families/s	1.3% MAD	-16.2%
Plan transitions through a compound state	119,494 transitions/s	0.7% MAD	117,031 transitions/s	1.0% MAD	-2.1%
Plan transitions through parallel regions	91,630 transitions/s	1.0% MAD	91,143 transitions/s	0.9% MAD	-0.5%
Drain burst through a compound state	508,620 events/s	0.8% MAD	497,566 events/s	1.9% MAD	-2.2%
Drain burst through two parallel regions	467,958 events/s	0.4% MAD	456,922 events/s	0.7% MAD	-2.4%
Drain a compound-state burst with a change observer	462,580 events/s	1.4% MAD	452,925 events/s	1.7% MAD	-2.1%
Idle machine heap per unit	1.5 KiB	0.1% MAD	1.5 KiB	0.2% MAD	+0.3%
Raw generic managed process heap per unit	12.7 KiB	0.0% MAD	12.7 KiB	0.0% MAD	+0.0%
Raw compiled process heap per unit	2.8 KiB	0.0% MAD	2.8 KiB	0.5% MAD	+0.9%
Two independent idle machines heap per unit	3.0 KiB	0.0% MAD	3.0 KiB	0.0% MAD	0.0%
Idle parent with one child heap per unit	4.8 KiB	0.0% MAD	4.8 KiB	0.0% MAD	-0.0%
Parent with observed child registry heap per unit	9.0 KiB	0.1% MAD	9.0 KiB	0.0% MAD	-0.1%
Parent with observed invoked child snapshots heap per unit	5.0 KiB	0.0% MAD	5.0 KiB	0.0% MAD	-0.0%

Effect runtime reference change from base

Metric	Base	Base variability	PR	PR variability	Difference
Start and stop a raw generic process	17,186 processes/s	1.5% MAD	16,341 processes/s	0.5% MAD	-4.9%
Start and stop a raw compiled process	67,581 processes/s	1.2% MAD	66,854 processes/s	0.7% MAD	-1.1%
Start and interrupt a suspended fiber	166,334 fibers/s	0.3% MAD	164,447 fibers/s	1.1% MAD	-1.1%
Start and stop a queue worker	117,302 workers/s	0.8% MAD	116,063 workers/s	0.9% MAD	-1.1%
Start and stop an actor shell	106,293 actors/s	2.9% MAD	106,758 actors/s	0.9% MAD	+0.4%
Start and stop two actor shells	62,150 families/s	6.0% MAD	64,562 families/s	2.0% MAD	+3.9%
Update an owner-only mutable snapshot	316,856,781 updates/s	0.0% MAD	316,856,781 updates/s	0.0% MAD	0.0%
Update a synchronized snapshot	1,550,118 updates/s	1.9% MAD	1,544,411 updates/s	2.0% MAD	-0.4%
Create, resolve, and await a terminal latch	1,420,491 latches/s	1.0% MAD	1,423,003 latches/s	2.2% MAD	+0.2%

Versions and interpretation

• Effect Machine: 0.4.0
• XState 5: 5.32.5
• XState 6 alpha: 6.0.0-alpha.31
• Effect runtime primitives: 4.0.0-beta.107

Higher throughput is better; lower heap is better. Variability is the median absolute deviation across independent processes, relative to their median. Runtime measurements on shared GitHub-hosted hardware remain informational, so small differences should be confirmed across multiple workflow runs.