@iyulab/canopy-page 0.9.0 → 0.11.0

package/CHANGELOG.md

@@ -7,6 +7,42 @@ Notable changes to canopy-page. The format follows
 The `settings.json` contract is what consuming projects plan their upgrades around, so changes
 to it — its fields, its validation, and what the checks reject — are what this file is about.
 
+## [0.11.0] — 2026-08-17
+
+### Added
+
+- **`strings.breadcrumb`**, overriding the accessible label of the topbar's new ancestor-trail
+  nav (canopy 0.11.0). Rides the same validated `strings` object every other reader-chrome
+  override already does.
+
+### Changed
+
+- **Upgraded to canopy 0.11.0** — collapsible sidebar groups and the breadcrumb trail (above),
+  a stronger sidebar current-page tint, a placeholder and icon on the search input, styled
+  topbar links, and the on-page outline now following the article instead of preceding it. See
+  [canopy's own changelog](https://github.com/iyulab/canopy/blob/main/CHANGELOG.md#0110--2026-08-17)
+  for the full list.
+
+### Fixed
+
+- **The mobile nav no longer opens on every page load.** canopy's shell ships the site
+  navigation as `<details open>` unconditionally — the one default that works with no script at
+  all — but on a narrow viewport, that meant a reader landed on a full navigation (rendered as a
+  full-screen overlay by canopy's own mobile styling) in front of the article they followed a
+  link to read, every single page. canopy-page's script now closes it by default on a narrow
+  viewport and remembers a reader's own choice to leave it open for the rest of that browser
+  session. A wide viewport, and a build with no script attached, are unaffected.
+
+## [0.10.0] — 2026-08-11
+
+### Added
+
+- **New `watch` command.** `canopy-page watch [site-dir] [-o out] [--port n]` builds once, then
+  rebuilds on every source change and serves the result on `http://localhost:<port>/` (default
+  `8080`, refused if already taken rather than silently moved). A failed rebuild is reported on
+  the console and leaves the last successful build being served — the process itself never exits
+  on a broken save.
+
 ## [0.9.0] — 2026-08-11
 
 ### Added

package/README.md

@@ -40,7 +40,12 @@ go away.
   system setting
 - **Prev/next cards** linking to a page's neighbors in the sidebar's own order, and **backlinks**
   listing every page that points to it
-- **A full-screen menu on narrow screens**, rather than one that pushes the page's content down
+- **Sidebar groups collapse**, open exactly along the path to the page you're on and closed
+  everywhere else
+- **A breadcrumb trail** in the topbar, when there's a title, a logo, `home`, or search for it to
+  sit beside
+- **A full-screen menu on narrow screens** that starts closed instead of opening on every page,
+  remembering a reader's own choice to leave it open for the rest of that visit
 - **Sitemap and `robots.txt`**, once `siteUrl` is set
 
 See it live at <https://iyulab.github.io/canopy-page>, or read
@@ -60,6 +65,7 @@ Node 22 or newer.
 npx canopy-page init docs/site     # write a settings file (and a home page, if needed)
 npx canopy-page check docs/site    # report anything broken, without building
 npx canopy-page build docs/site -o dist/help
+npx canopy-page watch docs/site       # rebuild on change, serve it locally
 ```
 
 `init` never replaces a settings file that is already there, and writes no page into a folder
@@ -75,6 +81,7 @@ fail. Both leave with a non-zero exit code when they do, which is all a pipeline
 | `canopy-page init [site-dir]` | Write a settings file naming the site after its folder |
 | `canopy-page check [site-dir]` | Check settings and references; build nothing |
 | `canopy-page build [site-dir] [-o out]` | Check, then publish to `out` (default `./site`) |
+| `canopy-page watch [site-dir] [-o out] [--port n]` | Build, then rebuild on change and serve it locally (default port `8080`) |
 
 `[site-dir]` is the folder holding `settings.json`, and defaults to the current one.
 
@@ -110,7 +117,7 @@ unpublished.
 | `title` | Site name. Defaults to the folder's name |
 | `description` | Fills `<meta name="description">`, which is what link previews show |
 | `lang` | BCP 47 tag for `<html lang>`. Worth setting for any non-English site: assistive technology reads pronunciation from it |
-| `strings` | Overrides for the reader chrome's own text — `search`, `toggleTheme`, `siteNav`, `pageNav`, `onThisPage`, `indexTitle` (the auto-generated contents page's title/heading), `backlinks` (a page's "linked references" heading), `searchFailed` (the client search's failure message). `lang` only changes what `<html lang>` declares; this text is canopy's own UI or canopy-page's own search script, not vault content, so it stays English otherwise. No built-in translation table — the same reasoning `home.label` already follows: link text has to be written in the site's own language. Keys left out keep their English default |
+| `strings` | Overrides for the reader chrome's own text — `search`, `toggleTheme`, `siteNav`, `pageNav`, `onThisPage`, `indexTitle` (the auto-generated contents page's title/heading), `backlinks` (a page's "linked references" heading), `breadcrumb` (the topbar's ancestor-trail nav's label), `searchFailed` (the client search's failure message). `lang` only changes what `<html lang>` declares; this text is canopy's own UI or canopy-page's own search script, not vault content, so it stays English otherwise. No built-in translation table — the same reasoning `home.label` already follows: link text has to be written in the site's own language. Keys left out keep their English default |
 | `icon` | Favicon, relative to the settings file. Must be a published file |
 | `tokens` | CSS of design-token overrides, relative to the settings file. Appended *after* canopy's own tokens, so a file naming one value keeps the rest. It is configuration rather than content, so — unlike `icon` and `logo` — it is excluded from the published site automatically. Absent: canopy's default palette |
 | `logo` | Image shown beside the site title, relative to the settings file. Must be a published file — the opposite direction from `tokens`, because this one is content. Rendered with an empty `alt`, deliberately: the site title beside it already names the site, so there is no separate text to give it. Absent: the sidebar header shows the title text alone |
@@ -143,6 +150,13 @@ specificity over a bare selector — so a bare `:root` appended after that block
 schemes. A one-block file naming only a light-mode colour would ship that colour onto a dark
 sidebar too.
 
+Unlike `settings.json` (below), `tokens` gets no such validation — it's a plain CSS file appended
+to canopy's own, and CSS silently ignores a custom property nothing reads. A file carried over
+from a previous documentation tool's own token names (or a `.dark`/`.light` class toggle instead
+of canopy's `[data-theme]` attribute) parses fine, builds fine, and changes nothing: the site
+keeps canopy's default colours with no error anywhere. If a `tokens` override doesn't show up on
+the built site, that silent mismatch — not a build failure — is the first thing to check.
+
 The settings file itself is never published, and neither is anything `exclude` names. A file
 named `settings.json` deeper in the site is content, and ships.
 

package/dist/assets/mobile-nav.js

@@ -0,0 +1,81 @@
+/**
+ * canopy-page's mobile nav default — vanilla JS, no dependencies. Wires the
+ * `<details class="canopy-nav" open>` disclosure canopy's shell always ships
+ * open: canopy itself writes no JavaScript (see canopy's docs/SCOPE.md), so
+ * a static page has no way to default that state per breakpoint on its own,
+ * and `open` has to pick one default for every viewport. It picks the safe
+ * one — a script-free reader on any screen still gets a working, fully
+ * visible navigation — but on a narrow viewport that leaves every fresh page
+ * load showing the full site navigation (canopy's shell renders an open
+ * `.canopy-nav` there as a full-screen overlay) in front of the article a
+ * reader actually followed a link to see.
+ *
+ * This script narrows that default, never widens it: a wide viewport is left
+ * exactly as canopy's shell already renders it (open, no toggle needed). On
+ * a narrow one it starts closed, unless the reader already chose to leave it
+ * open earlier in the same session — sessionStorage rather than
+ * localStorage, since a stale "open" choice from a different visit days ago
+ * would be more surprising than useful.
+ *
+ * `shouldOpenOnLoad` is exposed for tests: it is the one piece of this file
+ * with real logic, and it needs no DOM to run.
+ */
+var CanopyMobileNav = (function () {
+  "use strict";
+
+  var STORAGE_KEY = "canopy-nav-open";
+  var NARROW_QUERY = "(max-width: 40rem)";
+
+  /**
+   * Whether the nav should start open, given the viewport it's rendering at
+   * and the reader's last explicit choice this session (undefined if they
+   * never toggled it). A wide viewport always opens — matching the shell's
+   * own always-there design there, which this script only ever narrows for
+   * a narrow viewport, never overrides for a wide one. A narrow viewport
+   * starts closed unless the reader explicitly left it open last time.
+   */
+  function shouldOpenOnLoad(isNarrowViewport, storedChoice) {
+    if (!isNarrowViewport) return true;
+    return storedChoice === "open";
+  }
+
+  function readStoredChoice() {
+    try {
+      return sessionStorage.getItem(STORAGE_KEY) || undefined;
+    } catch (e) {
+      // Storage access can throw (private browsing with storage disabled) —
+      // a reader who hits that just gets the narrow-viewport default every
+      // load, not a broken page.
+      return undefined;
+    }
+  }
+
+  function storeChoice(open) {
+    try {
+      sessionStorage.setItem(STORAGE_KEY, open ? "open" : "closed");
+    } catch (e) {
+      // Same as above: a reader who can't write storage just loses the
+      // memory across pages, not the toggle itself.
+    }
+  }
+
+  function main() {
+    var nav = document.querySelector(".canopy-nav");
+    if (!nav || typeof matchMedia !== "function") return;
+
+    var isNarrow = matchMedia(NARROW_QUERY).matches;
+    nav.open = shouldOpenOnLoad(isNarrow, readStoredChoice());
+
+    // A reader's own click (native <details> toggling, no JS involved in the
+    // click itself) still fires this — the same event a script-driven
+    // assignment above fires too, so the very first automatic close is
+    // recorded as "closed" for free rather than needing a separate write.
+    nav.addEventListener("toggle", function () {
+      storeChoice(nav.open);
+    });
+  }
+
+  if (typeof document !== "undefined") main();
+
+  return { shouldOpenOnLoad: shouldOpenOnLoad };
+})();

package/dist/assets-bundle.js

@@ -34,10 +34,11 @@ const SEARCH_FAILED_DEFAULT = "Search failed to load.";
  * asset stays valid, readable JavaScript on its own.
  */
 export async function assembleScript(searchFailed) {
-    const [search, scrollspy, themeToggle] = await Promise.all([
+    const [search, scrollspy, themeToggle, mobileNav] = await Promise.all([
         readAsset("search.js"),
         readAsset("scrollspy.js"),
         readAsset("theme-toggle.js"),
+        readAsset("mobile-nav.js"),
     ]);
     // A function replacer, not a replacement string: String.replace treats
     // "$&"/"$'"/"$$" etc. in a replacement string as patterns, and a site
@@ -45,7 +46,7 @@ export async function assembleScript(searchFailed) {
     const searchWithStrings = searchFailed === undefined
         ? search
         : search.replace(JSON.stringify(SEARCH_FAILED_DEFAULT), () => JSON.stringify(searchFailed));
-    return `${searchWithStrings}\n${scrollspy}\n${themeToggle}`;
+    return `${searchWithStrings}\n${scrollspy}\n${themeToggle}\n${mobileNav}`;
 }
 /**
  * CSS canopy-page contributes on top of a site's own tokens, carried via

package/dist/cli-args.d.ts

@@ -12,6 +12,12 @@ export type ParsedArgs = {
     command: "build";
     dir: string;
     out: string;
+} | {
+    ok: true;
+    command: "watch";
+    dir: string;
+    out: string;
+    port: number;
 } | {
     ok: true;
     command: "check" | "init";

package/dist/cli-args.js

@@ -12,16 +12,19 @@ export const USAGE = [
     "  init  [site-dir]           Start a site: write a settings file",
     "  check [site-dir]           Check the site without publishing it",
     "  build [site-dir]           Check the site, then publish it",
+    "  watch [site-dir]           Build, then rebuild on change and serve it",
     "",
     "  [site-dir]                 Folder holding settings.json (defaults to .)",
-    "  -o, --out <dir>            Where build writes the site (defaults to ./site)",
+    "  -o, --out <dir>            Where build/watch writes the site (defaults to ./site)",
+    "  --port <n>                 Port watch serves on (defaults to 8080)",
 ].join("\n");
 const OUT_FLAGS = new Set(["-o", "--out"]);
+const PORT_FLAGS = new Set(["--port"]);
 export function parseArgs(argv) {
     const [command, ...rest] = argv;
     if (command === undefined)
         return { ok: false, error: USAGE };
-    if (command === "build" || command === "check" || command === "init") {
+    if (command === "build" || command === "check" || command === "init" || command === "watch") {
         return parseCommand(command, rest);
     }
     if (command.startsWith("-")) {
@@ -31,18 +34,30 @@ export function parseArgs(argv) {
     }
     return { ok: false, error: `${USAGE}\n\nUnknown command "${command}".` };
 }
+function parsePort(value, flag) {
+    if (value === undefined || value.startsWith("-")) {
+        return { ok: false, error: `${flag} needs a port number.` };
+    }
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 1 || parsed > 65535) {
+        return { ok: false, error: `${flag} needs a port number between 1 and 65535, got "${value}".` };
+    }
+    return parsed;
+}
 function parseCommand(command, argv) {
     const positional = [];
     let out;
+    let port;
     for (let i = 0; i < argv.length; i += 1) {
         const arg = argv[i];
         if (OUT_FLAGS.has(arg)) {
-            if (command !== "build") {
-                // Only build writes a site, so an output directory elsewhere is not a
-                // harmless extra: whoever passed it expects a site to appear somewhere.
+            if (command !== "build" && command !== "watch") {
+                // Only build and watch write a site, so an output directory elsewhere
+                // is not a harmless extra: whoever passed it expects a site to appear
+                // somewhere.
                 return {
                     ok: false,
-                    error: `${arg} is for build, which writes a site; ${command} does not.`,
+                    error: `${arg} is for build/watch, which write a site; ${command} does not.`,
                 };
             }
             const value = argv[i + 1];
@@ -53,6 +68,20 @@ function parseCommand(command, argv) {
             i += 1;
             continue;
         }
+        if (PORT_FLAGS.has(arg)) {
+            if (command !== "watch") {
+                return {
+                    ok: false,
+                    error: `${arg} is for watch, which serves the site; ${command} does not.`,
+                };
+            }
+            const parsed = parsePort(argv[i + 1], arg);
+            if (typeof parsed !== "number")
+                return parsed;
+            port = parsed;
+            i += 1;
+            continue;
+        }
         if (arg.startsWith("-")) {
             return { ok: false, error: `${USAGE}\n\nUnknown option "${arg}".` };
         }
@@ -66,5 +95,7 @@ function parseCommand(command, argv) {
     const dir = positional[0] ?? ".";
     if (command === "build")
         return { ok: true, command, dir, out: out ?? "site" };
+    if (command === "watch")
+        return { ok: true, command, dir, out: out ?? "site", port: port ?? 8080 };
     return { ok: true, command, dir };
 }

package/dist/cli.js

@@ -4,6 +4,7 @@ import { checkSite } from "./check.js";
 import { initSite, InitError } from "./init.js";
 import { parseArgs } from "./cli-args.js";
 import { SiteError } from "./site.js";
+import { WatchError, watchSite } from "./watch.js";
 async function main() {
     const args = parseArgs(process.argv.slice(2));
     if (!args.ok) {
@@ -19,6 +20,32 @@ async function main() {
         console.log("canopy-page: run `canopy-page build` to publish it");
         return;
     }
+    if (args.command === "watch") {
+        const handle = await watchSite({ dir: args.dir, out: args.out, port: args.port });
+        if (handle === undefined) {
+            // The initial build already printed why — buildSite/reportFindings own
+            // that message, watch has nothing to add.
+            process.exitCode = 1;
+            return;
+        }
+        let closing = false;
+        const shutdown = () => {
+            if (closing)
+                return;
+            closing = true;
+            void handle
+                .close()
+                .then(() => process.exit(0))
+                .catch((error) => {
+                const message = error instanceof Error ? error.message : String(error);
+                console.error(`canopy-page: error while shutting down — ${message}`);
+                process.exit(1);
+            });
+        };
+        process.on("SIGINT", shutdown);
+        process.on("SIGTERM", shutdown);
+        return;
+    }
     process.exitCode =
         args.command === "build"
             ? await buildSite({ dir: args.dir, out: args.out })
@@ -27,7 +54,7 @@ async function main() {
 main().catch((error) => {
     // A site error is about the site, not about canopy-page: the message is the
     // whole of what a reader needs, and a stack trace on top of it only buries it.
-    if (error instanceof SiteError || error instanceof InitError) {
+    if (error instanceof SiteError || error instanceof InitError || error instanceof WatchError) {
         console.error(`error: ${error.message}`);
     }
     else

package/dist/settings.d.ts

@@ -131,6 +131,8 @@ export interface Settings {
         indexTitle?: string;
         /** Heading over a page's list of pages that link to it. */
         backlinks?: string;
+        /** Accessible label for the topbar's ancestor-trail nav. */
+        breadcrumb?: string;
         /**
          * Message shown in place of results when the client search index fails to
          * load. This key rides the same JSON `--strings` flag as every other one

package/dist/settings.js

@@ -67,6 +67,7 @@ export const STRINGS_KEYS = new Set([
     "onThisPage",
     "indexTitle",
     "backlinks",
+    "breadcrumb",
     "searchFailed",
 ]);
 export const NAV_ITEM_KEYS = new Set(["label", "path", "items"]);

package/dist/watch.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Something about running `watch` itself, as opposed to `check.ts`'s findings
+ * (about the site) or `InitError` (about `init`) — a port already in use is
+ * the case this exists for. The message is the whole of what a reader needs,
+ * same reasoning as `SiteError` in `site.ts`.
+ */
+export declare class WatchError extends Error {
+}
+/** A running preview server, and how to stop it. */
+export interface StaticServer {
+    /** The port actually bound — the same value passed in, unless it was 0. */
+    readonly port: number;
+    close(): Promise<void>;
+}
+/** Serve the files in `root` over HTTP on `port` (0 for an OS-assigned port). */
+export declare function serveStatic(root: string, port: number): Promise<StaticServer>;
+/** What a watch run needs to know. */
+export interface WatchOptions {
+    /** Directory holding the settings file. */
+    dir: string;
+    /** Directory to write the site into, and to serve. */
+    out: string;
+    /** Port to serve on. */
+    port: number;
+    /** Called after every rebuild attempt (not the initial build) with its exit code. */
+    onRebuild?: (code: number) => void;
+}
+/** A running watch session, and how to stop it. */
+export interface WatchHandle {
+    /** The port actually bound. */
+    readonly port: number;
+    close(): Promise<void>;
+}
+/**
+ * Build once, then rebuild on every source change and serve the result.
+ *
+ * The server binds before the first build runs: a port already in use is an
+ * environment problem that has nothing to do with the site, and failing on
+ * it immediately — via `WatchError`, which propagates uncaught to `cli.ts` —
+ * costs nothing. Binding after a multi-second build would waste that build
+ * on a run that was always going to fail.
+ *
+ * A failed *rebuild* (as opposed to this first build) is reported and
+ * nothing else: `buildSite`'s existing contract (an error means nothing is
+ * written) means the previous, working output just keeps being served. The
+ * process only ever stops on the initial build failing — there is nothing to
+ * serve yet, so the server is closed again — or on the caller closing it.
+ *
+ * `buildSite` is not guaranteed to only resolve with an exit code: a
+ * malformed `settings.json` (edited mid-session) or a transient fs error
+ * (e.g. a lock held by an editor's save, more likely here since the watcher
+ * below has no `awaitWriteFinish`) surfaces as a thrown `SiteError` instead.
+ * Both the initial build and every rebuild treat a throw exactly like a
+ * nonzero exit code — the alternative, letting a rebuild's rejection go
+ * uncaught, would take down the whole watch process over one bad save.
+ */
+export declare function watchSite(options: WatchOptions): Promise<WatchHandle | undefined>;

package/dist/watch.js

@@ -0,0 +1,294 @@
+import { readFile, stat } from "node:fs/promises";
+import http from "node:http";
+import { basename, extname, resolve, sep } from "node:path";
+import { watch as watchFiles } from "chokidar";
+import { buildSite } from "./build.js";
+/**
+ * Serving a build's output locally during authoring.
+ *
+ * This is a preview server for one author on one machine, not a production
+ * origin: no range requests, no caching headers, no compression. The only
+ * thing it has to get right is not serving a path outside the directory it
+ * was told to serve.
+ */
+const MIME_TYPES = {
+    ".html": "text/html; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8",
+    ".json": "application/json; charset=utf-8",
+    ".svg": "image/svg+xml",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".ico": "image/x-icon",
+    ".txt": "text/plain; charset=utf-8",
+    ".xml": "application/xml; charset=utf-8",
+    ".woff": "font/woff",
+    ".woff2": "font/woff2",
+};
+function contentType(filePath) {
+    return MIME_TYPES[extname(filePath).toLowerCase()] ?? "application/octet-stream";
+}
+/**
+ * Check if a resolved file path contains any dot-prefixed segments (hidden files
+ * or directories). A request for `/.git/config` has `basename(...) === "config"`,
+ * which doesn't start with `.`, but the path contains the hidden segment `.git`.
+ * We reject any such path to avoid serving hidden version control, metadata, or
+ * temporary files that happen to exist under the served root.
+ */
+function hasHiddenSegment(root, filePath) {
+    const relative = filePath.slice(root.length);
+    const segments = relative.split(sep).filter((s) => s.length > 0);
+    return segments.some((s) => s.startsWith("."));
+}
+/**
+ * Something about running `watch` itself, as opposed to `check.ts`'s findings
+ * (about the site) or `InitError` (about `init`) — a port already in use is
+ * the case this exists for. The message is the whole of what a reader needs,
+ * same reasoning as `SiteError` in `site.ts`.
+ */
+export class WatchError extends Error {
+}
+/**
+ * Resolve a request URL to a path inside `root`, refusing anything that
+ * would land outside it.
+ *
+ * A percent-encoded "..%2F" is exactly as much a traversal attempt as a
+ * literal one, so decoding happens before the containment check runs — a
+ * check against the raw string would let the encoded form through.
+ *
+ * Malformed percent-encoding (e.g. %zz, lone %) throws URIError in
+ * decodeURIComponent — catching it here prevents an unhandled rejection
+ * that would hang the connection.
+ */
+function resolveRequestPath(root, url) {
+    let decoded;
+    try {
+        decoded = decodeURIComponent(url.split("?")[0] ?? "/");
+    }
+    catch {
+        // Malformed percent-encoding results in 404
+        return undefined;
+    }
+    const target = resolve(root, decoded.replace(/^\/+/, ""));
+    const rootWithSep = root.endsWith(sep) ? root : root + sep;
+    if (target !== root && !target.startsWith(rootWithSep))
+        return undefined;
+    return target;
+}
+/** Resolve a request URL to the file that answers it, following one directory→index.html hop. */
+async function resolveFile(root, url, triedIndex = false) {
+    const target = resolveRequestPath(root, url);
+    if (target === undefined)
+        return undefined;
+    try {
+        const stats = await stat(target);
+        if (stats.isDirectory()) {
+            if (triedIndex)
+                return undefined;
+            return resolveFile(root, `${url.replace(/\/?$/, "/")}index.html`, true);
+        }
+        return target;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Serve the files in `root` over HTTP on `port` (0 for an OS-assigned port). */
+export function serveStatic(root, port) {
+    const absoluteRoot = resolve(root);
+    // Path segments this server never has a reason to answer for — the same
+    // reasoning `isSkippedDir` in vault.ts applies to what a build publishes.
+    const server = http.createServer((req, res) => {
+        void (async () => {
+            const file = await resolveFile(absoluteRoot, req.url ?? "/");
+            if (file === undefined || hasHiddenSegment(absoluteRoot, file)) {
+                res.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
+                res.end("Not Found");
+                return;
+            }
+            try {
+                const body = await readFile(file);
+                res.writeHead(200, { "content-type": contentType(file) });
+                res.end(body);
+            }
+            catch {
+                res.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
+                res.end("Not Found");
+            }
+        })();
+    });
+    return new Promise((resolvePromise, reject) => {
+        server.once("error", (error) => {
+            reject(error.code === "EADDRINUSE"
+                ? new WatchError(`Port ${port} is already in use — pick another with --port.`)
+                : error);
+        });
+        server.listen(port, () => {
+            const address = server.address();
+            const actualPort = typeof address === "object" && address !== null ? address.port : port;
+            resolvePromise({
+                port: actualPort,
+                close: () => new Promise((res, rej) => {
+                    server.close((err) => (err ? rej(err) : res()));
+                }),
+            });
+        });
+    });
+}
+const DEBOUNCE_MS = 300;
+/** `Error#message` if it's one, else a `String()` fallback for whatever else a rejection carries. */
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * Build once, then rebuild on every source change and serve the result.
+ *
+ * The server binds before the first build runs: a port already in use is an
+ * environment problem that has nothing to do with the site, and failing on
+ * it immediately — via `WatchError`, which propagates uncaught to `cli.ts` —
+ * costs nothing. Binding after a multi-second build would waste that build
+ * on a run that was always going to fail.
+ *
+ * A failed *rebuild* (as opposed to this first build) is reported and
+ * nothing else: `buildSite`'s existing contract (an error means nothing is
+ * written) means the previous, working output just keeps being served. The
+ * process only ever stops on the initial build failing — there is nothing to
+ * serve yet, so the server is closed again — or on the caller closing it.
+ *
+ * `buildSite` is not guaranteed to only resolve with an exit code: a
+ * malformed `settings.json` (edited mid-session) or a transient fs error
+ * (e.g. a lock held by an editor's save, more likely here since the watcher
+ * below has no `awaitWriteFinish`) surfaces as a thrown `SiteError` instead.
+ * Both the initial build and every rebuild treat a throw exactly like a
+ * nonzero exit code — the alternative, letting a rebuild's rejection go
+ * uncaught, would take down the whole watch process over one bad save.
+ */
+export async function watchSite(options) {
+    const { dir, out, port, onRebuild } = options;
+    const server = await serveStatic(out, port);
+    let initialCode;
+    try {
+        initialCode = await buildSite({ dir, out });
+    }
+    catch (error) {
+        console.error(`canopy-page: build failed — ${errorMessage(error)}`);
+        await server.close();
+        return undefined;
+    }
+    if (initialCode !== 0) {
+        await server.close();
+        return undefined;
+    }
+    const absoluteDir = resolve(dir);
+    const resolvedOut = resolve(out);
+    const outWithSep = resolvedOut.endsWith(sep) ? resolvedOut : resolvedOut + sep;
+    let rebuildTimer;
+    let rebuilding = false;
+    let rebuildQueued = false;
+    // Tracks the rebuild currently running (if any) so close() can drain it
+    // instead of resolving while it's still writing to `out` in the
+    // background — see close() below.
+    let currentRebuild;
+    function runRebuild() {
+        if (rebuilding) {
+            rebuildQueued = true;
+            return;
+        }
+        rebuilding = true;
+        currentRebuild = buildSite({ dir, out })
+            .then((code) => {
+            console.log(code === 0
+                ? "canopy-page: rebuilt"
+                : "canopy-page: rebuild failed — serving the last successful build");
+            onRebuild?.(code);
+        }, (error) => {
+            // Same outcome as a nonzero exit code — the last successful build
+            // keeps being served — reported distinctly since it's a different
+            // failure shape. onRebuild still fires so a caller waiting on it
+            // (a test, or a future CLI status line) doesn't hang forever.
+            console.error(`canopy-page: rebuild failed — serving the last successful build (${errorMessage(error)})`);
+            onRebuild?.(1);
+        })
+            .finally(() => {
+            rebuilding = false;
+            currentRebuild = undefined;
+            if (rebuildQueued) {
+                rebuildQueued = false;
+                runRebuild();
+            }
+        });
+    }
+    function scheduleRebuild() {
+        if (rebuildTimer !== undefined)
+            clearTimeout(rebuildTimer);
+        rebuildTimer = setTimeout(runRebuild, DEBOUNCE_MS);
+    }
+    // Ignoring is structural only — dot-directories, node_modules, and the
+    // resolved output directory itself (unignored, a build watching its own
+    // output would rebuild forever). Content-level exclusions (settings.exclude)
+    // are deliberately not repeated here: vault.ts already restates canopy's
+    // exclusion rules once as a tracked debt, and a watch trigger that fires on
+    // an excluded file costs one redundant rebuild, not a wrong answer.
+    const watcher = watchFiles(absoluteDir, {
+        ignoreInitial: true,
+        ignored: (watchedPath) => {
+            const resolved = resolve(watchedPath);
+            if (resolved === absoluteDir)
+                return false;
+            if (resolved === resolvedOut || resolved.startsWith(outWithSep))
+                return true;
+            const name = basename(resolved);
+            return name === "node_modules" || name.startsWith(".");
+        },
+    });
+    // chokidar.watch() returns before its initial directory scan finishes
+    // arming the underlying OS watches — a file saved in that window can go
+    // unnoticed. Waiting for "ready" here means the promise this function
+    // returns is only kept once a change is guaranteed to be caught, which is
+    // what lets a caller (a test, or a human saving a file right after start)
+    // trust that watch mode is actually watching.
+    await new Promise((res) => watcher.once("ready", res));
+    watcher.on("all", scheduleRebuild);
+    // chokidar emits "error" for real, plausible triggers — a watched folder
+    // renamed or deleted mid-session, EPERM on Windows, ENOSPC from an inotify
+    // watch limit on Linux, EACCES on an unreadable subdirectory. An
+    // EventEmitter's "error" event with no listener throws uncaught, which
+    // would take down the whole watch process — exactly what this file's other
+    // error handling (buildSite failures never killing the process) exists to
+    // avoid. Reporting and continuing is the same "keep running" contract.
+    watcher.on("error", (error) => {
+        console.error(`canopy-page: watch error — ${errorMessage(error)}`);
+    });
+    console.log(`canopy-page: watching ${dir}, serving http://localhost:${server.port}/`);
+    return {
+        port: server.port,
+        close: async () => {
+            if (rebuildTimer !== undefined)
+                clearTimeout(rebuildTimer);
+            // A rebuild queued behind one already in flight (see runRebuild) hasn't
+            // started yet — cancelling it here means close() doesn't leave a fresh,
+            // unsignaled canopy build spawning after it returns, same as clearing
+            // rebuildTimer above does for one that was merely scheduled.
+            rebuildQueued = false;
+            // Closing the watcher first means no further change can schedule a new
+            // rebuild while we drain below — only what's already running is left
+            // to wait out, since rebuildQueued was just cleared above.
+            await watcher.close();
+            // A rebuild already in flight keeps writing to `out` and calling
+            // onRebuild after this close() would otherwise have returned, which
+            // breaks the "everything this started has stopped" contract close()
+            // is supposed to have. The loop (rather than a single await) guards
+            // against runRebuild reassigning currentRebuild synchronously from
+            // inside the previous one's `finally` — which can no longer chain into
+            // an actual rebuild now that rebuildQueued is cleared, but leaves the
+            // loop here as the correct shape regardless.
+            while (currentRebuild !== undefined) {
+                await currentRebuild;
+            }
+            await server.close();
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iyulab/canopy-page",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Authoring pipeline for documentation sites: one settings file, integrity checks, and a build.",
   "type": "module",
   "license": "MIT",
@@ -53,6 +53,7 @@
     "vitest": "^4.1.9"
   },
   "dependencies": {
-    "@iyulab/canopy": "^0.10.0"
+    "@iyulab/canopy": "^0.11.0",
+    "chokidar": "^5.0.0"
   }
 }