Pinega Web: Development Watch Loop v1

[likern]

Summary

Adds the first deliberately simple Pinega Web development loop: one authoritative full build pipeline, automatic source watching, local serving, and browser live reload.

What changed

• adds npm run dev backed by web/scripts/dev.mjs;
• watches web/src, web/content, web/pages, web/static, canonical Strata tokens, semantic diagrams, and the token generator;
• debounces file-system events and serializes rebuilds so overlapping edits cannot run concurrent full builds;
• invokes the existing web/scripts/build.mjs in a fresh Node child process for every rebuild instead of creating a second development build implementation;
• keeps watching after a failed rebuild and reloads browsers only after a successful rebuild;
• refactors the existing static server into an importable startPinegaServer() API while preserving npm run serve behaviour;
• adds dev-only Server-Sent Events live reload by injecting the client into HTTP responses only — generated web/dist HTML is unchanged;
• documents the development path in the Gate 2 build how-to and Web environment reference;
• adds unit coverage for live-reload response injection, SSE notifications, and unchanged ordinary serve output.

Design boundary

This is intentionally v1, not an incremental compiler. The accepted invariant is:

source change -> existing build.mjs -> successful dist -> reload

There is no Vite/Webpack layer and no parallel dev-only content/diagram/token generation path. Incremental rebuilds can be evaluated later if full rebuild latency becomes material.

External API basis

• Node.js 26 fs.watch() supports recursive directory watching on Linux and AbortSignal-based shutdown.
• esbuild documents that its built-in live reload only observes outputs known to its build graph and recommends custom live-reload infrastructure for unrelated HTML/other inputs; Pinega has exactly those extra build-time inputs.

Validation

Isolated development-loop fixtures:

• node --check for dev.mjs, serve.mjs, and the unit test;
• server unit tests: 2/2 pass;
• integration fixture: initial build -> source edit -> automatic rebuild -> updated served response;
• failure recovery fixture: intentional build failure remains alive, next edit rebuilds successfully;
• production serve mode does not inject the live-reload client;
• package-lock.json requires no update because no dependencies changed.

Repository CI on e3441338fae15de6c24ec70d7e6aaff2cec8234c:

• generated Strata token adapters: pass;
• TypeScript typecheck: pass;
• unit and architecture tests: pass;
• production multi-page build: pass;
• build/performance budgets: pass;
• browser and accessibility tests: pass;
• committed visual baselines: pass;
• validated website artifact upload: pass;
• Scientific diagram review artifacts workflow: pass.