@zvndev/darkmown 2.4.1-next.7.ge25dbba → 2.5.0

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to Darkmown are documented here. Versions follow [semver](https://semver.org); pre-1.0 minor versions may contain breaking changes.
 
+## 2.5.0 (2026-08-16)
+
+Everything Darkmown has shipped for AI authoring so far has been *description*: a directive catalog, a cheatsheet, a corpus, a GBNF grammar. All of it teaches a model to write a `.wd` file from scratch. None of it helps a model edit one it did not write, which is the operation an AI editor actually performs. This release adds the other half: a tool surface the model calls instead of rewriting whole files. No runtime change (7654 B gzipped, unchanged) and no breaking changes.
+
+- **`@zvndev/darkmown/tools`, a six-tool surface for editing agents.** `outline` lists what a page declares with line numbers and block spans; `refs` finds every declare, write, and read of one symbol; `deps` reports what a page pulls in and what pulls it in; `grammar` returns only the cheatsheet rows this edit needs; `apply` makes a targeted edit addressed by line, symbol, or anchor; `validate` compiles the result for real. `Session` stages edits in memory so `apply` and `outline` cannot disagree about what the file currently is, and `parseToolCall` reads a call back out of a model's reply (brace-counting and string-aware, because the one thing a Darkmown edit reliably contains is `{ count }`). Everything runs over a plain `{ path: contents }` object with no filesystem, so a full compile is milliseconds and checking after every edit is affordable rather than aspirational.
+- **Every tool answers one shape, and a refusal is an answer.** All six return `{ ok, text, data }` and none of them throw. A model only ever reads `text`, so a tool that fails in its own shape is invisible to the thing driving it and ends the run. Every rejection names what was wrong *and* what would have worked: an unknown grammar category lists the real ones, a symbol that is not there lists what the page does have, a bad edit op lists the four valid ones. Addressing an edit three ways is deliberate. Anchored-only editing is the obvious design and it fails as files grow, not because small models cannot count lines but because they cannot quote back a string they read once.
+- **The compiler records a symbol table.** It already knew everything a tool would want to ask (what a page declares, on what line, whether a loop stayed reactive, which state key an action writes) and threw all of it away. Each directive handler now records its symbol as it parses, and a compile returns them alongside the HTML. The point is that there is exactly one parser: anything answering "what is in this page?" from a second parse of the `.wd` will eventually disagree with the compiler, and the day it does is the day a tool reports something true about a file that will not compile. No change to any page's output and no runtime cost.
+- **BUGFIX: TypeScript consumers were getting stale declarations.** The committed `types/` had drifted 344 lines across eight files, and the root entrypoint had never declared `directiveCatalog` or `llmsText` at all, so `import { directiveCatalog } from "@zvndev/darkmown"` type-checked as a missing export. This class of bug is invisible to every gate the project had: tests, typecheck, and `npm pack` all pass while the shipped `.d.ts` says something else. Two guards now close it, one regenerating the declarations and diffing the whole tree, one asserting the hand-authored entrypoints name every export that exists at runtime.
+- **BUGFIX: three dev-server tests were measuring the wrong rebuild.** On macOS `fs.watch` is backed by FSEvents, which replays a short history of events from *before* the watcher was created, so the files `darkmown init` scaffolds land in the dev server's first debounce window. The full rebuild two of those tests observed was correct behavior, just not the rebuild under test, and they had been passing for that reason. They now drain the watcher first.
+
 ## 2.4.0 (2026-08-09)
 
 A discoverability release, in both senses. Search engines can now index the site correctly, and coding agents working in a Darkmown project finally get the directive reference where they will actually read it. No runtime change (7654 B gzipped, unchanged) and no breaking changes.

package/README.md

@@ -1118,6 +1118,39 @@ darkmown build                               # also emits dist/llms.txt + dist/l
 
 Because the catalog, cheatsheet, grammar, and error `example`s are all generated from the compiler's own tables, they cannot drift from what actually compiles (enforced by tests).
 
+### Agent tools
+
+`@zvndev/darkmown/tools` is the same language description turned into a **tool surface**: six functions a model calls instead of rewriting a whole file. Everything runs in memory against a plain `{ path: contents }` object, so a full compile is milliseconds and "check after every edit" is affordable rather than aspirational.
+
+| Tool | Answers |
+| --- | --- |
+| `outline(files, entry)` | What is declared in this page, with line numbers and block spans. |
+| `refs(files, entry, name)` | Every place a symbol is declared, written, or read. |
+| `deps(files, entry)` | What this page pulls in, and which pages pull it in. |
+| `grammar(categories)` | Only the cheatsheet rows this edit needs. |
+| `apply(files, entry, edits)` | A targeted edit, addressed by `line`, `symbol`, or `anchor`. |
+| `validate(files, entry)` | Compiles it for real, or says exactly what broke. |
+
+Every tool answers the same shape, `{ ok, text, data }`, and a refusal always carries a sentence the model can act on rather than throwing. `Session` holds the files so `apply` and `outline` are guaranteed to be looking at one snapshot, and records a `history` of calls:
+
+```js
+import { Session, parseToolCall } from "@zvndev/darkmown/tools";
+
+const session = new Session({ "site/pages/index.wd": source }, "site/pages/index.wd");
+
+session.call("outline", {});
+//   :7       state     count = 0
+//   :12-14   loop      @loop /products.json into p
+
+session.call("apply", {
+  edits: [{ op: "replace", symbol: "state:count", text: ":state count = 5" }]
+});
+session.call("validate", {});
+//   compiles. reactive (ships the runtime), 0 skins.
+```
+
+`toolPrompt()` renders the tool list for a system prompt, and `parseToolCall(reply)` reads a call back out of a model's answer (brace-counting and string-aware, because the one thing a Darkmown edit reliably contains is `{ count }`).
+
 ## Editor support
 
 A VS Code extension in [`editors/vscode`](editors/vscode) gives `.wd` and `.skin` files syntax highlighting, snippets, and folding — so a `.wd` file reads as Markdown-plus-directives, never as broken Markdown.

package/docs/spec-alignment.md

@@ -2,6 +2,17 @@
 
 This audit compares the current Darkmown implementation with the original MARROW/WhateverDown vision and the follow-up decisions made on 2026-06-11.
 
+## Agent tool surface: `@zvndev/darkmown/tools` (2026-08-16)
+
+The AI-authoring work so far shipped *description*: a catalog, a cheatsheet, a corpus, a GBNF grammar. All of it teaches a model to write a `.wd` file from scratch. None of it helps a model **edit one it did not write**, which is the operation an AI editor actually performs, and the one that fails: measurement showed the failure is not counting lines, it is recalling a string read once, and it gets worse as a file grows.
+
+- **Six tools, all derived from the compiler.** `outline` (what is declared, with line numbers and block spans), `refs` (every declare/write/read of a symbol), `deps` (what the page pulls in and what pulls it in), `grammar` (only the cheatsheet rows this edit needs), `apply` (a targeted edit), `validate` (compile it for real). They are built on the symbol table `compileFromMemory` returns, recorded by the directive handlers as they parse, so there is no second parser to drift: the day a parser beside the compiler disagrees is the day a model is told something true about a file that will not compile.
+- **One answer shape, and refusals are answers.** Every tool returns `{ ok, text, data }` and nothing throws. A model only ever reads `text`, so a tool that fails in its own shape is invisible to the thing driving it and ends the run. Every rejection names what was wrong *and* what would have worked: an unknown grammar category lists the real ones, a missing symbol lists what the page does have, a bad op lists the four valid ops.
+- **Three ways to say where, because the plan's objection was the wrong one.** The original design ruled out line numbers on the grounds that small models cannot count. They can; what they cannot do is quote a line back verbatim, which is where anchored editing dies (42% of tasks at 16 lines, 67% at 244). `apply` accepts `line` (as printed by `outline`), `symbol` (as named by `outline`/`refs`), or `anchor`, and the staleness worry is designed out rather than ignored: every target resolves against the snapshot passed to *this* call, all edits apply against that one snapshot in descending line order, and an optional `expect` catches a file that moved underneath.
+- **`Session` is what keeps the snapshot single.** It stages edits in memory rather than on disk, so `apply` and `outline` cannot disagree about what the file currently is, and records a `history` a run can be scored on later. Everything runs against a plain `{ path: contents }` object with no filesystem, which is what makes "validate after every edit" affordable rather than aspirational.
+- **BUGFIX: `validate` leaked the virtual project root into its own error text.** It shortened the location it prints but not the compiler's message, which names the file mid-sentence (`Malformed @loop in /site/pages/index.wd:3`). A model shown `/site/pages/` uses it, and the path it then writes resolves to nothing.
+- **BUGFIX: a flaky dev-server test, found by running the suite rather than the file.** On macOS `fs.watch` is backed by FSEvents, which replays a short history of events from *before* the watcher existed, so the files `darkmown init` scaffolded landed in the dev server's first debounce window. The rebuild the test measured was a correct full rebuild (one replayed path is the watched directory itself, the "no attributable file" signal) rather than the incremental one under test. Two sibling tests were passing for the same wrong reason. All three now drain the watcher before acting.
+
 ## Technical SEO: canonical URLs, structured data, AI crawlers, llms-full.txt (2026-08-09)
 
 The 1.3.0 cycle shipped the crawler *files* (sitemap, rss, robots). This closes the gaps a real deployment exposed: the files existed but nothing on the page said which URL was canonical, and the host disagreed with the framework about the URL form.
@@ -235,7 +246,7 @@ The 1.3.0 cycle closes table-stakes gaps a new user expects out of the box. Trac
 - **`llms.txt` cheatsheet** — `llmsText()` renders a compact (~90-line) markdown cheatsheet from the same catalog; `darkmown catalog` prints the JSON and `darkmown catalog --llms` the cheatsheet, and every build writes `dist/llms.txt`. This is the artifact an app pastes into a small model's system prompt.
 - **Generated GBNF grammar** — `src/grammar.js` (`generateGrammar()`, wrapped by `scripts/gen-grammar.mjs`) emits `grammar/wd-directives.gbnf`, a llama.cpp grammar for `.wd` **directive lines** (plus the `{ path | pipe }` interpolation token). It constrains a line's *shape* — the leading keyword must be a real directive, `@loop` must be `@loop <src> into <item> …clauses`, a condition must be `operand <op> operand`, a `:button` must be `"…" -> <action-chain>` — which deletes the on-device failure class (JS/HTML muscle-memory openers become unrepresentable) while staying small; free-form values remain `text`. Well-formedness + catalog coverage are tested in `tests/grammar.test.js`, and the committed file is kept in sync by the same test.
 - **Structured compile errors** — errors carry a machine-readable mirror on `err.wd = { file, line?, hint?, example? }` (helper `wdError` in context.js) alongside the unchanged string message. Applied across loops, includes, predicates, forms, state, actions, media, fetch, and structure. `example` is always a compilable line.
-- **Concrete examples in error hints** — every corrective `Use:` hint that contained bracket-placeholders now ends with ` — e.g. <concrete valid line>`, drawn from the same `*_EXAMPLE` constants. `tests/error-examples.test.js` extracts each `e.g.` example from the *real* thrown error string and compiles it (enforcement, not convention). Motivation: the on-device model bench (`bench/on-device/RESULTS.md`) found small models echo bracket-placeholders into source verbatim.
+- **Concrete examples in error hints** — every corrective `Use:` hint that contained bracket-placeholders now ends with ` — e.g. <concrete valid line>`, drawn from the same `*_EXAMPLE` constants. `tests/error-examples.test.js` extracts each `e.g.` example from the *real* thrown error string and compiles it (enforcement, not convention). Motivation: benchmarking small local models found they echo bracket-placeholders into source verbatim.
 
 ## Demo-only directives (not part of the public surface)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zvndev/darkmown",
-  "version": "2.4.1-next.7.ge25dbba",
+  "version": "2.5.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -20,6 +20,10 @@
       "types": "./types/catalog.d.ts",
       "default": "./src/catalog.js"
     },
+    "./tools": {
+      "types": "./types/tools/index.d.ts",
+      "default": "./src/tools/index.js"
+    },
     "./package.json": "./package.json"
   },
   "types": "./types/index.d.ts",

package/site/pages/docs/index.wd

@@ -677,6 +677,28 @@ darkmown catalog --llms-full            # the complete reference + every error c
 
 Compile errors help here too: every corrective `Use:` hint ends with a concrete `— e.g. <valid line>`, and each thrown error carries a structured `err.wd = { file, line, hint, example }` mirror alongside its message — so an edit-and-retry loop gets the fix without parsing prose.
 
+### Agent tools
+
+`@zvndev/darkmown/tools` turns that same description into six functions a model calls instead of rewriting a whole file. Everything runs in memory over a plain `{ path: contents }` object, so a full compile is milliseconds:
+
+- **`outline(files, entry)`** lists what the page declares, with line numbers and block spans.
+- **`refs(files, entry, name)`** finds every declare, write, and read of one symbol.
+- **`deps(files, entry)`** reports what the page pulls in, and what pulls it in.
+- **`grammar(categories)`** returns only the cheatsheet rows this edit needs.
+- **`apply(files, entry, edits)`** makes a targeted edit, addressed by `line`, `symbol`, or `anchor`.
+- **`validate(files, entry)`** compiles it for real, or says exactly what broke.
+
+Every tool answers `{ ok, text, data }`, and a refusal carries a sentence the model can act on rather than throwing. `Session` holds the files so `apply` and `outline` always see one snapshot:
+
+```js
+import { Session } from "@zvndev/darkmown/tools";
+
+const session = new Session({ "site/pages/index.wd": source }, "site/pages/index.wd");
+session.call("outline", {});
+session.call("apply", { edits: [{ op: "replace", symbol: "state:count", text: ":state count = 5" }] });
+session.call("validate", {});
+```
+
 ## Compile error codes
 
 Every author-facing compile error opens with a stable `WDxxx` code, so it is searchable and matchable by tooling without parsing prose:

package/src/compiler/actions.js

@@ -9,7 +9,7 @@
 // while keeping the message text and `Use:` hints intact.
 // ---------------------------------------------------------------------------
 
-import { at, lineOf, wdError } from "./context.js";
+import { at, lineOf, recordSymbol, wdError } from "./context.js";
 import {
   escapeHtml,
   resolveStateKey,
@@ -45,6 +45,14 @@ export function handleButton(line, ctx, index) {
     });
   ctx.comp.assets.runtime = true;
   const action = parseAction(match[2], ctx);
+  for (const a of Array.isArray(action) ? action : [action])
+    recordSymbol(ctx, index, {
+      kind: "action",
+      name: a.target,
+      target: a.target,
+      op: a.op,
+      detail: `:button "${match[1]}" -> ${match[2].trim()}`
+    });
   if (Array.isArray(action)) {
     return `<button type="button" data-wd-actions="${escapeHtml(JSON.stringify(action))}">${escapeHtml(match[1])}</button>`;
   }
@@ -92,6 +100,14 @@ export function handleEffect(line, ctx, index) {
   const watch = [key, ...segs.slice(1)].join(".");
   const action = parseAction(match[2], ctx);
   const actions = Array.isArray(action) ? action : [action];
+  for (const a of actions)
+    recordSymbol(ctx, index, {
+      kind: "action",
+      name: a.target,
+      target: a.target,
+      op: a.op,
+      detail: `:effect ${watch} -> ${match[2].trim()}`
+    });
   return `<script type="application/json" data-wd-effect>${safeScriptJson({ watch, actions })}</script>`;
 }
 
@@ -142,6 +158,14 @@ export function handleEvery(line, ctx, index) {
   ctx.comp.assets.runtime = true;
   const action = parseAction(match[2], ctx);
   const actions = Array.isArray(action) ? action : [action];
+  for (const a of actions)
+    recordSymbol(ctx, index, {
+      kind: "action",
+      name: a.target,
+      target: a.target,
+      op: a.op,
+      detail: `:every ${match[1]} -> ${match[2].trim()}`
+    });
   return `<script type="application/json" data-wd-every>${safeScriptJson({ ms, actions })}</script>`;
 }
 

package/src/compiler/body.js

@@ -7,7 +7,7 @@
 // multi-line directive bodies with nesting + fence awareness.
 // ---------------------------------------------------------------------------
 
-import { at, lineOf, wdError } from "./context.js";
+import { at, lineOf, stampBlockEnd, wdError } from "./context.js";
 import {
   handleBind,
   handleButton,
@@ -84,7 +84,9 @@ export function compileBody(lines, ctx) {
       flush();
       const block = scanBlock(lines, i, /^@loop\s/, "@endloop", ctx);
       const split = splitEmptyBranch(block.body);
+      const loopAt = ctx.comp.symbols.length;
       out.push(handleLoop(line, split.body, split.empty, ctx, i, split.emptyStart));
+      stampBlockEnd(ctx, loopAt, block.end);
       i = block.end;
       continue;
     }
@@ -227,7 +229,9 @@ export function compileBody(lines, ctx) {
     if (/^:if\s/.test(line)) {
       flush();
       const block = scanConditional(lines, i, ctx);
+      const ifAt = ctx.comp.symbols.length;
       out.push(handleIf(line, block.truthy, block.falsy, ctx, i, block.falsyStart));
+      stampBlockEnd(ctx, ifAt, block.end);
       i = block.end;
       continue;
     }

package/src/compiler/context.js

@@ -81,6 +81,33 @@
  *   read threads through — the real filesystem by default, or an in-memory map
  *   for `compileFromMemory`. Set once by `createCompilation` and reached via
  *   `ctx.comp.reader` in the directive handlers (includes, loop data).
+ * @property {Symbol[]} symbols Every declared thing this compile saw, in source
+ *   order, recorded by {@link recordSymbol} from the handler that parsed it.
+ *   Surfaced on {@link CompiledPage} so a tool layer can answer "what is in this
+ *   page?" without parsing `.wd` a second time.
+ */
+
+/**
+ * One declared thing in a page, as the compiler saw it.
+ *
+ * `kind` is the directive family; `name` is what an author would call the thing
+ * and is what `refs` matches on. `detail` is a short human string in the same
+ * vocabulary the model writes, never a serialized AST: the tool layer's job is
+ * to hand back text a model can nearly paste, and translation is where small
+ * models lose.
+ *
+ * @typedef {object} Symbol
+ * @property {"state" | "store" | "computed" | "theme" | "fetch" | "action" | "loop" | "form" | "field" | "if" | "include" | "read"} kind
+ * @property {string} name The symbol's own name, or the thing it targets.
+ * @property {string} [detail] Short source-shaped description, e.g. `cart append p`.
+ * @property {boolean} [reactive] For loops: whether it stays reactive at runtime.
+ * @property {string} [target] For actions: the state key written.
+ * @property {string} [op] For actions: the validated action token.
+ * @property {string} file Absolute path of the file the symbol was declared in.
+ * @property {number} [endLine] For a block directive (`@loop`, `:if`), the
+ *   1-based line its closer sits on, so a tool can address the whole block.
+ * @property {number | null} line 1-based line in that file, or null for a read
+ *   recorded by {@link recordRead} (see there for why prose reads carry no line).
  */
 
 /**
@@ -137,6 +164,8 @@
  *   `@loop` recorded, or null. The builder reads it to multiply routes.
  * @property {Set<string>} deps Absolute source-file dependencies of this compile.
  * @property {Set<string>} collectionsUsed Collection names this compile looped.
+ * @property {Symbol[]} symbols Every declared thing the compile saw, in
+ *   source order. See {@link recordSymbol}.
  */
 
 /**
@@ -150,6 +179,8 @@
  *   `@loop` recorded, or null. The builder reads it to multiply routes.
  * @property {Set<string>} deps Absolute source-file dependencies of this compile.
  * @property {Set<string>} collectionsUsed Collection names this compile looped.
+ * @property {Symbol[]} symbols Every declared thing the compile saw, in
+ *   source order. See {@link recordSymbol}.
  */
 
 /**
@@ -270,10 +301,85 @@ export function createCompilation(reader) {
     collections: new Map(),
     pagination: null,
     deps: new Set(),
-    collectionsUsed: new Set()
+    collectionsUsed: new Set(),
+    symbols: []
   };
 }
 
+/**
+ * Record one declared thing as the handler that owns it parses it.
+ *
+ * This is the compiler telling a tool layer what is in a page, rather than a
+ * tool layer parsing `.wd` a second time. A shadow parser drifts, and the day it
+ * disagrees with `compilePage` it tells a model something true about a file that
+ * will not compile.
+ *
+ * Called from the `handle*` functions, where the 0-based `index` is live, so
+ * every symbol carries a real `file:line`. Include bodies share the parent's
+ * `Compilation` but compile under their own `ctx.file`, so attribution stays
+ * correct with no extra plumbing.
+ *
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index into the current body slice.
+ * @param {Omit<Symbol, "file" | "line">} sym
+ * @returns {Symbol} The pushed record, so a caller whose reactive/static decision
+ *   happens in a later branch can stamp it rather than duplicate that logic.
+ */
+export function recordSymbol(ctx, index, sym) {
+  const record = { ...sym, file: ctx.file, line: lineOf(ctx, index) };
+  ctx.comp.symbols.push(record);
+  return record;
+}
+
+/**
+ * Record where a block directive CLOSES, so a tool layer can address the whole
+ * construct rather than only its opening line.
+ *
+ * Measured need, not speculation: with only the opener line recorded, the 1.5B
+ * targeted a `@loop` for replacement and swapped out its header, leaving the
+ * `@endloop` behind. That produced `[WD010] Stray "@endloop"` as the single
+ * most common compile failure of the round-4 tool run. A `@loop` is three or
+ * more lines and a tool has to be able to say so.
+ *
+ * The dispatcher owns this because only it has the block's extent, from
+ * `scanBlock`/`scanConditional`. `at` is the index the block handler's own
+ * symbol was pushed to; nested symbols recorded while compiling the body land
+ * after it and are left alone.
+ *
+ * @param {Ctx} ctx
+ * @param {number} at Index into `ctx.comp.symbols` the block handler wrote to.
+ * @param {number} endIndex 0-based body index of the closing line.
+ * @returns {void}
+ */
+export function stampBlockEnd(ctx, at, endIndex) {
+  const sym = ctx.comp.symbols[at];
+  if (sym) sym.endLine = lineOf(ctx, endIndex);
+}
+
+/**
+ * Record that a page READS a state key through an interpolation.
+ *
+ * Deliberately line-less. Prose is rendered a chunk at a time by markdown-it, so
+ * no 0-based body `index` is in scope at the point a `{ name }` binding resolves,
+ * and threading one through the markdown layer would mean tracking source
+ * positions inside a renderer that does not care about them.
+ *
+ * Instead the compiler records the two things only it can know: that the
+ * expression resolved to this state key, and the exact expression text. The tool
+ * layer locates the line by searching the file for that compiler-supplied
+ * string, which is a substring search for a known needle rather than a second
+ * parser. Duplicates (a static loop re-renders its body once per row) are the
+ * caller's to fold.
+ *
+ * @param {Ctx} ctx
+ * @param {string} key Resolved state key.
+ * @param {string} expr The binding expression as authored, e.g. `cart | count`.
+ * @returns {void}
+ */
+export function recordRead(ctx, key, expr) {
+  ctx.comp.symbols.push({ kind: "read", name: key, detail: expr, file: ctx.file, line: null });
+}
+
 /**
  * @param {Scope | null} parent
  * @param {Record<string, unknown>} [vars]

package/src/compiler/fetch.js

@@ -7,7 +7,7 @@
 // while keeping the message text and `Use:` hints intact.
 // ---------------------------------------------------------------------------
 
-import { at, lineOf, wdError } from "./context.js";
+import { at, lineOf, recordSymbol, wdError } from "./context.js";
 import {
   escapeHtml,
   resolveStateKey,
@@ -123,6 +123,7 @@ export function handleFetch(line, ctx, index) {
   // (collision-checked); the derived keys are seeded directly.
   const key = declareState(name, null, ctx);
   ctx.comp.fetchKeys.add(key);
+  recordSymbol(ctx, index, { kind: "fetch", name: key, detail: `${key} from "${url}"` });
   /** @type {Record<string, unknown>} */
   const seeds = { [key]: null };
   for (const [suffix, seed] of [

package/src/compiler/forms.js

@@ -9,7 +9,7 @@
 // while keeping the message text and `Use:` hints intact.
 // ---------------------------------------------------------------------------
 
-import { at, lineOf, nestedCtx, wdError } from "./context.js";
+import { at, lineOf, nestedCtx, recordSymbol, wdError } from "./context.js";
 import { validateFetchUrl } from "./fetch.js";
 import {
   escapeHtml,
@@ -73,6 +73,12 @@ export function handleForm(line, bodyLines, ctx, index) {
   }
   const key = declareState(into, null, ctx);
   declareErrorState(key, ctx);
+  recordSymbol(ctx, index, {
+    kind: "form",
+    name: key,
+    target: key,
+    detail: `:form action="${rawAction}" into ${into}`
+  });
   const actionAttrs = action
     ? ` action="${escapeHtml(action)}" method="${escapeHtml(method)}"`
     : "";
@@ -96,6 +102,7 @@ export function handleInput(line, ctx, index) {
       example: INPUT_EXAMPLE
     });
   const attrs = [`name="${escapeHtml(match[1])}"`];
+  recordSymbol(ctx, index, { kind: "field", name: match[1], detail: `:input ${match[1]}` });
   let type = "text";
   let placeholder;
   let hasAria = false;
@@ -175,6 +182,12 @@ export function handleBind(line, ctx, index) {
       { code: "WD406", file: ctx.file }
     );
   }
+  recordSymbol(ctx, index, {
+    kind: "field",
+    name: match[1],
+    target: key,
+    detail: `:bind ${match[1]}`
+  });
   ctx.comp.assets.runtime = true;
   let type = "text";
   let placeholder;
@@ -326,6 +339,7 @@ export function handleSlider(line, ctx, index) {
   const valueAttr =
     initial === undefined || initial === null ? "" : ` value="${escapeHtml(String(initial))}"`;
   const ariaAttr = ` aria-label="${escapeHtml(ariaLabel || humanizeName(name))}"`;
+  recordSymbol(ctx, index, { kind: "field", name, target: key, detail: `:slider ${name}` });
   return `${seed}<input type="range" data-wd-bind-input="${key}" min="${escapeHtml(min)}" max="${escapeHtml(max)}" step="${escapeHtml(step)}"${valueAttr}${ariaAttr}>`;
 }
 
@@ -348,6 +362,7 @@ export function handleSubmit(line, ctx, index) {
         example: SUBMIT_EXAMPLE
       }
     );
+  recordSymbol(ctx, index, { kind: "field", name: "submit", detail: line.trim() });
   return `<button type="submit">${escapeHtml(match[1])}</button>`;
 }
 
@@ -374,6 +389,7 @@ export function handleTextarea(line, ctx, index) {
     });
   }
   const attrs = [`name="${escapeHtml(match[1])}"`];
+  recordSymbol(ctx, index, { kind: "field", name: match[1], detail: `:textarea ${match[1]}` });
   let placeholder;
   let hasAria = false;
   const re = /([A-Za-z-]+)=("[^"]*"|\S+)|([A-Za-z-]+)/g;
@@ -441,6 +457,7 @@ export function handleSelect(line, optionLines, ctx, index) {
     });
   }
   const attrs = [`name="${escapeHtml(match[1])}"`];
+  recordSymbol(ctx, index, { kind: "field", name: match[1], detail: `:select ${match[1]}` });
   let hasAria = false;
   const re = /([A-Za-z-]+)=("[^"]*"|\S+)|([A-Za-z-]+)/g;
   for (const token of (match[2] || "").matchAll(re)) {
@@ -518,6 +535,7 @@ export function handleChoiceGroup(line, optionLines, ctx, kind, index) {
     });
   }
   const name = match[1];
+  recordSymbol(ctx, index, { kind: "field", name, detail: `:${kind} ${name}` });
   const flags = [];
   let ariaLabel = null;
   let ariaDescribedby = null;

package/src/compiler/loops.js

@@ -6,7 +6,7 @@
 // string fill used for the initial paint (text binds, per-row `:if`, meta).
 // ---------------------------------------------------------------------------
 
-import { at, createScope, lineOf, nestedCtx, wdError } from "./context.js";
+import { at, createScope, lineOf, nestedCtx, recordSymbol, wdError } from "./context.js";
 import { serializeExpr } from "./expr-ast.js";
 import { applyPipeline, stagesFromAttr } from "./format.js";
 import { resolveInclude } from "./includes.js";
@@ -296,6 +296,15 @@ export function handleLoop(line, bodyLines, emptyLines, ctx, index, emptyStart =
     sortable: clauses.sortable,
     paginate: clauses.paginate
   };
+  // Stamped by whichever branch below resolves the source. `reactive` is the one
+  // fact a tool layer cannot recover from the source text alone, and it is the
+  // fact that decides whether the page ships the runtime.
+  const loopSymbol = recordSymbol(ctx, index, {
+    kind: "loop",
+    name: itemName,
+    detail: line.replace(/^@loop\s+/, "@loop "),
+    reactive: Boolean((where && where.refsState) || clauses.refsState)
+  });
   // The loop body starts on the line after the opener; nested errors in it (and
   // in the empty branch, via `opts.emptyStart`) report the true file line. The
   // opener's location rides on the body ctx so a reactive loop nested inside this
@@ -362,6 +371,9 @@ export function handleLoop(line, bodyLines, emptyLines, ctx, index, emptyStart =
     if (key) {
       if (opts.paginate) throw paginateOnlyCollections(ctx);
       const fullKey = segs.length > 1 ? `${key}.${segs.slice(1).join(".")}` : key;
+      loopSymbol.reactive = true;
+      loopSymbol.name = itemName;
+      loopSymbol.target = fullKey;
       return reactiveLoop(fullKey, itemName, bodyLines, bodyCtx, opts);
     }
     // A bare name matching a collection (any `site/pages/<name>/` subdir) resolves
@@ -382,6 +394,7 @@ export function handleLoop(line, bodyLines, emptyLines, ctx, index, emptyStart =
         );
       }
       if (opts.paginate) throw paginateOnlyCollections(ctx);
+      loopSymbol.reactive = true;
       return itemRelativeLoop(segs.slice(1).join("."), itemName, bodyLines, bodyCtx, opts);
     }
   }

package/src/compiler/markdown.js

@@ -7,7 +7,7 @@
 
 import MarkdownIt from "markdown-it";
 import { highlightCode } from "../highlight.js";
-import { LOOP_META, wdError } from "./context.js";
+import { LOOP_META, recordRead, wdError } from "./context.js";
 import { applyPipeline, fmtAttr, validatePipes } from "./format.js";
 import {
   escapeHtml,
@@ -288,6 +288,7 @@ function resolveBindingHtml(expr, ctx) {
   const key = resolveStateKey(head, ctx);
   if (key) {
     ctx.comp.assets.runtime = true;
+    recordRead(ctx, key, expr);
     const initial = getPath(ctx.comp.state.get(key), segs.slice(1));
     const rest = segs.slice(1).join(".");
     const pathAttr = rest ? ` data-wd-path="${escapeHtml(rest)}"` : "";

package/src/compiler/page.js

@@ -206,6 +206,7 @@ export function compilePage(file, context, options = {}) {
     meta: compiled.meta,
     deps: compiled.deps,
     collectionsUsed: compiled.collectionsUsed,
+    symbols: compiled.symbols,
     html: `<!doctype html>
 <html lang="${escapeHtml(lang)}">
 <head>
@@ -391,7 +392,8 @@ export function compileDocument(
     warnings: comp.warnings,
     pagination: comp.pagination,
     deps: comp.deps,
-    collectionsUsed: comp.collectionsUsed
+    collectionsUsed: comp.collectionsUsed,
+    symbols: comp.symbols
   };
 }
 

package/src/compiler/state.js

@@ -8,7 +8,7 @@
 // while keeping the message text and `Use:` hints intact.
 // ---------------------------------------------------------------------------
 
-import { at, lineOf, wdError } from "./context.js";
+import { at, lineOf, recordSymbol, wdError } from "./context.js";
 import { astOf, evalAst } from "./expr-ast.js";
 import { escapeHtml, parseStateValue, safeScriptJson } from "./interpolation.js";
 import { compileComputedExpr } from "./predicates.js";
@@ -42,6 +42,7 @@ export function handleState(line, ctx, index) {
     });
   const value = parseStateValue(match[2], at(ctx, index));
   const key = declareState(match[1], value, ctx);
+  recordSymbol(ctx, index, { kind: "state", name: key, detail: `${key} = ${match[2].trim()}` });
   const persistAttr = match[3] ? ` data-wd-persist="${key}"` : "";
   return `<script type="application/json" data-wd-state${persistAttr}>${safeScriptJson({ [key]: value })}</script>`;
 }
@@ -101,6 +102,7 @@ export function handleStore(line, ctx, index) {
     );
   const value = parseStateValue(match[2], at(ctx, index));
   const name = declareStore(match[1], value, ctx);
+  recordSymbol(ctx, index, { kind: "store", name, detail: `${name} = ${match[2].trim()}` });
   const ephemeral = match[3] ? " data-wd-store-ephemeral" : "";
   return `<script type="application/json" data-wd-store="${name}"${ephemeral}>${safeScriptJson(value)}</script>`;
 }
@@ -195,6 +197,7 @@ export function handleComputed(line, ctx, index) {
   // folds to null, never throws — so parse-failure above is the only error path.
   const initial = evalAst(ast, undefined, ctx.comp);
   const key = declareState(match[1], initial ?? null, ctx);
+  recordSymbol(ctx, index, { kind: "computed", name: key, detail: `${key} = ${match[2].trim()}` });
   return `<span data-wd-computed data-wd-computed-key="${key}" data-wd-computed-expr="${escapeHtml(JSON.stringify(ast))}"></span><script type="application/json" data-wd-state>${safeScriptJson({ [key]: initial ?? null })}</script>`;
 }
 
@@ -227,5 +230,10 @@ export function handleTheme(line, ctx, index) {
   const name = match[1] || "theme";
   const seed = match[2] != null ? parseStateValue(match[2], at(ctx, index)) : "auto";
   const storeName = declareStore(name, seed, ctx);
+  recordSymbol(ctx, index, {
+    kind: "theme",
+    name: storeName,
+    detail: `${storeName} = ${JSON.stringify(seed)}`
+  });
   return `<script type="application/json" data-wd-store="${storeName}">${safeScriptJson(seed)}</script><span data-wd-theme="${storeName}" hidden></span>`;
 }

package/src/compiler/structure.js

@@ -11,7 +11,7 @@
 // while keeping the message text and `Use:` hints intact.
 // ---------------------------------------------------------------------------
 
-import { at, createScope, LOOP_META, lineOf, nestedCtx, wdError } from "./context.js";
+import { at, createScope, LOOP_META, lineOf, nestedCtx, recordSymbol, wdError } from "./context.js";
 import { astOf, serializeExpr } from "./expr-ast.js";
 import { resolveInclude, scopedSkinFor, stampScope } from "./includes.js";
 import {
@@ -68,6 +68,7 @@ export function handleInclude(line, ctx, index) {
     ctx.comp.reader
   );
   const args = parseIncludeArgs(match[2] || "", ctx);
+  recordSymbol(ctx, index, { kind: "include", name: match[1], detail: `@include ${match[1]}` });
   const childScope = createScope(ctx.scope, args);
   // Thread the reactive-nesting depth (and the enclosing loop opener, so a depth
   // error names the right opener) into the include, exactly as `loopItem` is —
@@ -288,6 +289,7 @@ export function handleIf(line, truthyLines, falsyLines, ctx, index, falsyStart =
   const truthyCtx = nestedCtx(ctx, index + 1);
   const falsyCtx = nestedCtx(ctx, falsyStart);
   const condition = line.replace(/^:if\s+/, "").trim();
+  recordSymbol(ctx, index, { kind: "if", name: condition, detail: `:if ${condition}` });
   // Fast path: a bare truthy dotted path (`:if open`, `:if item.done`). Keeps the
   // existing markup/behavior identical. Anything with operators (`>`, `==`, `and`,
   // `not`, …) falls through to the predicate path below.