Refactor build and watch internals into cohesive subsystems

.gitignore

@@ -23,4 +23,3 @@ test-results
 *.d.ts.map
 !types/**/*.d.ts
 !types/**/*.d.ts.map
-test-cases/generated-pages/.streaming

CONTRIBUTING.md

@@ -45,4 +45,3 @@ If for some reason that isn't working or a local release is preferred, follow th
 
 Generation belongs in `version`, not `preversion` (which runs before the version update) or `postversion` (which runs after the commit and tag).
 The release workflow's pre-version reset/clean is safe because the initial generated JavaScript is tracked and the version hook rebuilds it before staging.
-Run `npm run test:version-build` to verify generation, staging, tagging, and cleanup in a disposable repository without versioning this checkout.

agents.md

@@ -11,5 +11,11 @@
 - After running a type build, clean up the generated build files and do not leave them sitting around.
 - Use the cleanup scripts in `package.json` for generated type build files.
 - The generated `lib/defaults/default.root.layout.js` is versioned runtime code, not temporary declaration output; regenerate it with `npm run build:defaults` after editing its TypeScript source and never remove it during cleanup.
+- Keep `test-cases/` focused on checked-in example sites paired with acceptance tests that build through the public API and assert on outputs or expected build errors.
+- Example sites should be understandable by browsing their source files, not reconstructed from JavaScript strings embedded in tests.
+- Put detailed behavioral and regression tests beside the subsystem they exercise under `lib/`, even when they build temporary sites or run real watchers.
+- Keep public facade tests at the repository root and public TypeScript contract tests in `type-tests/`.
+- Behavioral tests may copy example sites into temporary directories, but must not mutate checked-in fixtures or depend on another test's output directory.
+- Keep test-only files out of published packages and declaration builds; see `test-cases/README.md` for the test organization guidelines.
 - For formatting-only ESLint failures, use `npx eslint <path> --fix` for a quick targeted fix before rerunning lint.
 - When handling PR review comments, validate that each comment is correct before making changes; maintainer comments are almost always valid, but review bot comments may be wrong, and after addressing a comment, always reply with what was done.

declaration.tsconfig.json

@@ -8,6 +8,13 @@
   },
   "exclude": [
     "**/*.test.js",
+    "**/*.test.ts",
+    "**/*test-helpers.js",
+    "**/fixtures/**/*",
+    "lib/cli/tests/**/*",
+    "lib/watch/*-tests/**/*",
+    "type-tests/**/*",
+    "test-fixtures/**/*",
     "test-cases/**/*",
     "site/**/*",
   ]

docs/api/README.md

@@ -73,6 +73,6 @@ Options are passed through to `DomStack`, including `copy` paths.
 
 See these repository tests for complete usage:
 
-- [`test-build-helper/index.test.js`](https://github.com/bcomnes/domstack/blob/master/test-cases/test-build-helper/index.test.js) tests temporary output, `readOutput()`, copied directories, and cleanup.
+- [`test-build.test.js`](https://github.com/bcomnes/domstack/blob/master/test-build.test.js) tests temporary output, `readOutput()`, copied directories, and cleanup.
 - [`default-layout/index.test.js`](https://github.com/bcomnes/domstack/blob/master/test-cases/default-layout/index.test.js) uses `testBuild()` for a focused output assertion.
 - [`generated-pages/index.test.js`](https://github.com/bcomnes/domstack/blob/master/test-cases/generated-pages/index.test.js) uses it with generated pages, global data, and templates.

docs/implementation/README.md

@@ -167,6 +167,7 @@ Layout subscriptions contribute to page invalidation, but each layout still rece
 Page initialization uses a concurrency limit of `min(CPUs, 24)`.
 The final page and template rendering queues run in parallel, splitting that concurrency budget between them.
 
+
 Variable Resolution Layers, from lowest to highest precedence:
 - **Domstack defaults** - Internal defaults such as the default `layout: 'root'`.
 - **Global vars** - Site-wide variables from `global.vars.js` (resolved once).
@@ -193,7 +194,7 @@ Watch mode coordinates three independent watchers:
 
 Chokidar events pass through a pure planner before any rebuild executes.
 The planner reads an explicit snapshot of discovery, dependency maps, and the previous page-build outcome; it does not perform I/O or mutate that state.
-`DomStack` owns the watch session, serializes events, executes plans, and releases its watchers, esbuild context, and server on shutdown.
+DOMStack manages the watch session, queues changes, rebuilds affected outputs, and shuts down the watchers and server when stopped.
 
 <pre class="mermaid" tabindex="0" role="region" aria-label="Watch planning diagram">
 flowchart TD

docs/pages/README.md

@@ -30,6 +30,11 @@ Variables are available in all pages.
 `ts` pages receive variables as part of the argument passed to them.
 See the [Variables](../../docs/pages/#variables) section for more info.
 
+DOMStack prepares each page's renderer once per build.
+HTML and Markdown source content is captured when the page initializes; repeated renders reuse that content but still receive the current render inputs.
+Watch rebuilds prepare fresh renderers, so an edit observed during a build is picked up by a subsequent build.
+The `readMarkdownContent()` helper remains a fresh read of the source file rather than a read of the prepared content.
+
 Pages can define a special variable called [`layout`](../layouts/#selecting-a-layout) that determines which layout the page is rendered into.
 
 Because pages are just directories, they nest and structure naturally as a filesystem router.

examples/tailwind/src/layouts/root.layout.js

@@ -1,7 +1,7 @@
 /**
  * @import { LayoutFunction } from '@domstack/static'
  */
-// @ts-ignore
+
 import { html } from 'htm/preact'
 import { render } from 'preact-render-to-string'