Run the project site

Develop the documentation and examples, validate content, and pack local archives.

Use this guide to run the project website or work on its source. To create a diagram workspace, start with Your first session. Both use zfb, but the website presents documentation and fixtures while your session contains the diagrams you are reviewing.

Open the documentation and examples locally

Use Node.js 22–24 and pnpm 10. From the repository root:

pnpm install
pnpm dev

Open the address printed by zfb. Visit the tone catalog, the six example sessions, and these guides. The root development command prepares showcase data before starting zfb and watches examples, tone resources, and viewer assets for changes.

The Architecture reference describes the package and website boundaries. Session content belongs in metadata and candidate directories; the installed engine supplies the review interface.

Check changes and preview the build

Run these from the repository root:

pnpm check
pnpm test
pnpm check:examples
pnpm build
pnpm preview

Command	What it checks or produces
`pnpm check`	Prepared showcase data and TypeScript checking for the project sources.
`pnpm test`	Engine, renderer, browser-state logic, and initializer tests.
`pnpm check:examples`	Validation of the six example sessions and tone catalog.
`pnpm build`	The documentation and showcase site, built with zfb.
`pnpm preview`	A local server for the built site.

In a generated session, pnpm check instead validates that session's metadata, SVG assets, and lineage. Validation and builds do not establish that a diagram explains the feature correctly or that every browser interaction works. Inspect the relevant pages and review actions when changing them.

Pack an engine for a separate session

pnpm pack:local

This writes engine and initializer archives under artifacts/ and prints their absolute paths. Follow Your first session to initialize and install a consumer outside this repository.

Use that separate consumer when changing package exports, packaged resources, initializer templates, or runtime paths. Confirm that its engine resolves from its own installed dependency, validate an empty session and a populated one, and check the relevant dev, export, or build behavior. A source import within this workspace does not exercise the installed package boundary.

Set a session's host and port

In a generated session, the installed engine accepts explicit network settings:

pnpm exec zudo-diagram-gen dev . --host 0.0.0.0 --port 4799

Use a free port. Binding to 0.0.0.0 allows access through the machine's network interfaces; the default local address is sufficient for review on the same machine. Stop the server when finished. See the CLI reference for the complete command interface.