Add incremental global-data state and docs navigation indexing

[bcomnes]

Summary

Add session-owned incremental global-data state and use it to update the documentation navigation index without rendering every document on ordinary Markdown edits.

Closes #325. Related: #289, #322/#323. Precise watch dependency tracking is split into follow-up #329; this PR keeps conservative invalidation and the existing dependency maps.

Feature

• Global-data callbacks receive pages, previousState, changes, and setState. The application chooses its own index structure.
• Changes are either a reset or a delta containing initialized source-page upserts and removed source IDs. page.sourceId is the source-root-relative path with POSIX separators.
• State is isolated across fresh workers, snapshotted by setState, and committed only after rendering and output cleanup succeed. Failed builds retain the previous successful baseline and recover with a reset.
• Private state stays out of public data and fingerprints. Existing returned-data fingerprints and dataDeps subscriptions still control downstream data invalidation.
• Buffer startup and in-flight events and reconcile source membership after rediscovery.
• Cache documentation records by sourceId, update affected entries with bounded p-map concurrency, and regenerate navigation and TOCs from those records.
• Keep the simplified tests, direct optional plan fields, and usage-focused documentation.

Base versus follow-up

This base reuses existing watch dependency maps without adding global-vars, Markdown-settings, or browser-helper analysis. When state is retained, Markdown/HTML source edits can use deltas; watched module and configuration edits conservatively reset the index and trigger a full rebuild. Sites without retained state keep their existing output-routing behavior.

Follow-up #329 adds targeted routing for ordinary module edits, browser-only skips, dependency-analysis recovery, and observation of known imported inputs such as JSON. Settings roots and their tracked imports share one detection set and always trigger a full rebuild and index reset; there is no fine-grained settings routing. JSON support connects dependencies discovered by the existing import tracker to file-watcher events, rather than adding a JSON analyzer. The producer API and documentation index are unchanged.

Static re-export analysis remains limited upstream: #328. Two test TODOs cite that issue, and the documentation describes an explicit-import/local-export workaround. Imported JSON changes require restarting watch mode until #329 is applied.

Validation

• Full Node suite: 349 passed, 0 failed, 2 TODOs linked to Watch dependency tracking misses static re-exports #328.
• ESLint, TypeScript, and diff whitespace checks passed.
• Documentation-site build passed.
• Coverage includes source membership, worker state isolation, explicit commit semantics, shared configuration helpers, startup/in-flight buffering, failure and cleanup recovery, and independent watch sessions.

The browser suite was not rerun for this split. An earlier run passed 14 of 16 tests; two documentation-navigation interaction tests timed out and remain unresolved.

Part of the stack with #329, created using gh stack.

[coveralls]

Coverage Report for CI Build 35044786822

Coverage increased (+0.6%) to 95.352%

Details

• Coverage increased (+0.6%) from the base build.
• Patch coverage: 9 uncovered changes across 4 files (806 of 815 lines covered, 98.9%).
• No coverage regressions found.

Uncovered Changes

File	Changed	Covered	%
index.js	109	104	95.41%
test-cases/watch/helpers.js	54	52	96.3%
site/globals/global.data.ts	34	33	97.06%
test-cases/incremental-global-data/helpers.js	157	156	99.36%
Total (10 files)	815	806	98.9%

Coverage Regressions

No coverage regressions found.

---

Coverage Stats

Relevant Lines:	10250
Covered Lines:	9890
Line Coverage:	96.49%
Relevant Branches:	3154
Covered Branches:	2891
Branch Coverage:	91.66%
Branches in Coverage %:	Yes
Coverage Strength:	440.41 hits per line

---

💛 - Coveralls

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[Copilot]

🟡 Changes recommended

Abort handling can start a full build after watcher cancellation, and the source identity documentation needs correction.

Get a fresh assessment by requesting another Copilot review.

Review details

Suppressed comments (1)

index.js:258

• When stopWatching() aborts the watcher before it emits ready, the ready promise resolves through the AbortError handler in #createSourceWatcher, so this await returns and #prepareWatch immediately starts discovery, esbuild, and the initial page build despite the cancelled signal. stopWatching() then waits for that full startup and resources are acquired after cancellation; short-circuit the preparation after an aborted readiness wait (while preserving the startup return contract).

    await ready

• Files reviewed: 32/32 changed files
• Comments generated: 1
• Review effort level: Lite