dogfooding fixes: astryx theme build --watch

[josephfarina]

What this adds

astryx theme build --watch — rebuild a theme automatically whenever its source file changes, until interrupted with Ctrl-C. Closes #3375 (item 1, the highest-impact request in that DX report).

Why

Today every tweak to a defineTheme file requires manually re-running astryx theme build theme.ts --out theme.css. Forget it once and you're debugging stale CSS that has nothing to do with your change. --watch turns theme authoring into a real tight loop: edit → save → rebuilt.

How it works

• Runs an initial build, then watches the theme file and rebuilds on change (debounced, since editors emit several events per save).
• Watches the containing directory and filters to the theme file, so atomic-save/rename (used by many editors) doesn't drop the watch.
• Each rebuild runs in a child process that reuses the exact single-build code path. This has two benefits: the existing single-build behavior is untouched (zero regression risk), and a build error — which the single-build path reports via a hard exit — is contained in the child so the watcher keeps running instead of dying.
• Coalesces changes that land mid-build into a single follow-up rebuild.
• Stops cleanly on SIGINT/SIGTERM (closes the watcher, no orphaned process).
• --watch is a human-interactive mode and is rejected with --json (which expects a single machine-readable envelope).

Per-rebuild latency is ~235ms (Node startup + core import), which is imperceptible next to the browser refresh that follows a theme edit.

Verification

New build-theme.watch.test.mjs (3 tests):

1. --watch is advertised in theme build --help.
2. --watch with --json is rejected.
3. End-to-end: an initial build produces the CSS, editing the theme triggers a rebuild whose CSS reflects the new token value, and SIGINT stops the watcher cleanly (asserts the "Stopped watching" output and process exit).

Existing build-theme tests (prose, import-path, path-safety, variants) are unaffected — the single-build path is unchanged. ESLint clean.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
astryx	Ready	Preview, Comment	Jul 2, 2026 11:22pm

[github-actions]

PR Analysis Report

📚 Storybook Preview

View Storybook for this PR
GitHub Pages may take up to a minute to hydrate after deploy.

🧪 Sandbox Preview

View Sandbox for this PR
GitHub Pages may take up to a minute to hydrate after deploy.

No new or modified components detected.

Bundle Size Summary

Package	Size (ESM)	Size (CJS)	Gzipped
@astryxdesign/core	N/A	4.6KB	0B

Accessibility Audit

Status: No accessibility violations detected.

---

_{Generated by PR Enrichment workflow | Storybook | Sandbox | View full report}