Merge pull request #215 from bcomnes/progressive-rebuilds

Initial implementation of progressive reloading

Author: bcomnes

.claude/settings.local.json

@@ -2,6 +2,10 @@
   "permissions": {
     "allow": [
       "Bash(node --test:*)"
+      "WebFetch(domain:github.com)",
+      "WebFetch(domain:raw.githubusercontent.com)",
+      "Bash(gh repo view:*)",
+      "Bash(gh api:*)"
     ]
   }
 }

README.md

@@ -1444,10 +1444,41 @@ Variable Resolution Layers:
   - **JS pages**: exported vars → page.vars.js → postVars
 - **postVars** - Post-processing function that can modify variables based on all resolved data
 
+### Watch Mode Flow
+
+Watch mode (`domstack watch` / `DomStack.watch()`) performs an initial build using watch-mode esbuild (stable, non-hashed output filenames) and then keeps the site up to date as files change.
+
+#### File change decision tree
+
+When a file changes under `src`, the chokidar watcher applies this decision tree (first match wins):
+
+| File pattern | Action |
+|---|---|
+| `global.vars.*` | Full page rebuild (all pages) |
+| `esbuild.settings.*` | Restart esbuild context + full page rebuild |
+| `markdown-it.settings.*` | Rebuild `.md` pages only |
+| Layout file | Rebuild pages using that layout |
+| Dep of a layout | Rebuild pages using any affected layout |
+| Page file or `page.vars.*` | Rebuild that page + all `postVars` pages |
+| `*.template.*` | Rebuild that template only |
+| Layout CSS/client JS | esbuild watches these itself; its `onEnd` triggers a full page rebuild |
+| (no match) | Skip |
+
+File additions and deletions always trigger a **full structural rebuild**: re-run `identifyPages`, restart the esbuild context, rebuild all pages, and rebuild the watch maps.
+
+#### Watched file extensions
+
+chokidar watches: `.js`, `.mjs`, `.cjs`, `.ts`, `.mts`, `.cts`, `.css`, `.html`, `.md`
+
+cpx watchers handle static asset copying independently and do not trigger page rebuilds.
+
+#### `postVars` contagion
+
+Pages that export a `postVars` function depend on other pages' resolved data. After each full (unfiltered) page build, domstack records which pages used `postVars`. When any page file or vars file subsequently changes, those `postVars` pages are re-rendered alongside the changed page so their cross-page data stays current.
+
 ## Roadmap
 
-`domstack` works and has a rudimentary watch command, but hasn't been battle tested yet.
-If you end up trying it out, please open any issues or ideas that you have, and feel free to share what you build.
+`domstack` is working and actively developed. If you end up trying it out, please open any issues or ideas that you have, and feel free to share what you build.
 
 Some notable features are included below, see the [roadmap](https://github.com/users/bcomnes/projects/3/) for a more in depth view of whats planned.
 
@@ -1488,6 +1519,7 @@ Some notable features are included below, see the [roadmap](https://github.com/u
 - [x] markdown-it.settings.ts support
 - [x] page-worker.worker.ts page worker support
 - [x] `page.md` page support
+- [x] Progressive watch rebuilds (only rebuild affected pages on change)
 - ...[See roadmap](https://github.com/users/bcomnes/projects/3/)
 
 ## History

examples/basic/src/js-page/client.js

@@ -1 +1,3 @@
 console.log('This client script runs on the js page')
+
+console.log('hello world!')

examples/basic/src/js-page/loose-assets/page.ts

@@ -1,7 +1,7 @@
 import { html } from 'htm/preact'
 import type { PageFunction } from '@domstack/static'
 
-import sharedData from './shared-lib.js'
+import sharedData from './shared-lib.ts'
 import type { PageVars } from '../../layouts/root.layout.ts'
 
 const JSPage: PageFunction<PageVars> = async () => {

examples/basic/src/layouts/child.layout.ts

@@ -2,8 +2,8 @@ import type { LayoutFunction } from '@domstack/static'
 import { html } from 'htm/preact'
 import { render } from 'preact-render-to-string'
 
-import defaultRootLayout from './root.layout.js'
-import type { PageVars } from './root.layout.js'
+import defaultRootLayout from './root.layout.ts'
+import type { PageVars } from './root.layout.ts'
 
 const articleLayout: LayoutFunction<PageVars> = (args) => {
   const { children, ...rest } = args