[bcomnes]

Stack: 2 of 3 — depends on #2

Full stack: #2 → #3 → #5, managed with gh stack. #5 adds the blog, GitHub author registry/cache, feeds, source edit links, and related visual refinements. Those additions are intentionally excluded from this layer.

Review this diff against refactor/typescript-tooling, not master. Merge #2 first, then retarget/rebase this PR onto master as needed (especially if #2 is squash-merged).

This is the website-improvements slice extracted from #1. The TypeScript tooling replacement is isolated in #2.

Summary

Native DOMStack data and outputs

• Pin DOMStack to 12.0.0-beta.9. Its source-preparation cache avoids reparsing unchanged Markdown; measured median doc edits improved from 564 ms on beta.8 to 315 ms on beta.9.
• Prepare JSON-safe navigation and collection search/LLM data outside layouts; retain one shared docs layout plus spec.
• Move global vars/data under src/globals/, co-locate search/LLM templates with outputs, and use shared import aliases.
• Replace six collection-wide raw exporters with page-owned pageOutputs hooks. Preserve raw URLs/bytes, skip unchanged raw writes, and clean up deleted/renamed outputs.
• Remove unused public navigation JSON; retain active browser search JSON.
• Register seven layouts with the type-only registry and validate 20 HTML vars companions.

Authoring and redirects

• Derive docs titles from H1, normalize inline Markdown for metadata consumers, and remove 585 redundant frontmatter titles. Preserve formatted article headings, anchors, and raw Markdown bodies; explicit title overrides remain supported.
• Adjust the existing importer code for that authoring change without repeating the tooling port.
• Generate the two existing path aliases from destination-owned redirectFrom metadata. Retain full root-layout chrome, canonical/no-JavaScript fallback, and query/fragment behavior. Legacy ?p= handling remains separate.

Incremental global data

• Cache cloneable document projections in private state keyed by page.sourceId.
• Reset builds process all docs; deltas replace upserts and remove deleted entries.
• Rebuild inexpensive views from cached document references. Existing fingerprints and dataDeps remain the only downstream invalidation system—no app hashes or changed-key declarations.
• Use framework successful-build state commit/reset behavior; no patch-package or framework patch.

Clients and assets

• Convert remaining browser helpers/grammars to checked TypeScript.
• Scope homepage/learn styles and route-specific clients.
• Fix failed search caching, Ask AI positioning/focus/dismissal, and most-specific subnavigation selection.
• Keep article transforms page-local, preserve the Markdown plugin policy, improve edit/canonical artifact URLs, and use npm start for domstack --watch; no separate dev/preview commands.

Review guidance

Most changed-file count is the mechanical removal of one frontmatter title from each of 585 docs. Article bodies and raw exports are unchanged. Review runtime code separately from that mechanical migration.

Suggested order: global data/index and shared layouts; artifacts/page outputs; title and redirect helpers; registry/vars checks; clients/styles; tests and docs.

The initial split matched the preserved combined checkpoint exactly. Subsequent commits add the sidebar breakpoint fix, beta.8/beta.9 upgrades, and migration cleanup; the current tree intentionally differs from that checkpoint.

Validation

Full npm run check passed on this stacked branch:

• Typecheck and unit/integration tests.
• Clean build, output/link/anchor audits, content audits, and static-output tests.
• 18 desktop/mobile browser tests using local Brave.
• Tooling tests and actual full-site watcher instrumentation.
• Identical repeated build output with no source changes.

Actual global-data work measured by the watcher:

Change	Markdown reads	Search renders
Initial reset	585	585
Body edit	1	1
Title override	1	1
Raw-path change	1	1
Delete	0	0

All 1,238 output files were also verified byte-identical before/after the beta.7 index implementation. Raw output checks prove one body edit rewrites only its raw file and a title-only edit rewrites none.

Limits

State copying, projection, fingerprint traversal, and some page setup still have whole-site costs; beta.9 reuses unchanged Markdown source preparation. Dependency tracking has known import-alias/static-re-export limitations; restart watch mode after edits to such helpers. Navigation metadata changes still invalidate the shared navigation consumers by design. Ingestion remains manual and separate from builds.

Local browser tests used ORO_BROWSER_EXECUTABLE with Brave; CI installs Playwright Chromium. Newly triggered CI status is separate from local validation.

Related framework work: bcomnes/domstack#325. Original application plan: #1 (comment).

Migration cleanup

• Remove the one-time converter, unused link inventory, and historical migration report.
• Move active normalization/reference helpers to tools/ingestion/ without changing their contents.
• Retain the historical compatibility baseline at tests/fixtures/legacy-routes.json.
• Derive current-document counts instead of freezing them at 585; compare complete roundtrip file membership and bytes.
• Replace the baseline-fed lookup loop with focused normalization/missing/prototype-safety assertions.
• Update operational guidance in README.

Full npm run check passed after cleanup, including browser tests, actual watch checks, audits, and reproducibility. Historical conversion tooling remains in Git history.

[bcomnes]

Added the responsive sidebar fix: collapse the documentation index at 820px, matching the point where the docs grid moves the sidebar above the article. Previously it collapsed at 980px, leaving an empty sidebar column between 821px and 980px. Validated the build, 32 temporary Playwright assertions covering docs/spec layouts, resizing, mobile controls and no-JavaScript navigation, plus all 18 existing browser tests. No permanent tests added.