Skip to content

Improve DOMStack outputs, authoring, and incremental builds - #3

Draft
bcomnes wants to merge 2 commits into
refactor/typescript-toolingfrom
refactor/domstack-improvements
Draft

bcomnes wants to merge 2 commits into
refactor/typescript-toolingfrom
refactor/domstack-improvements

Conversation

@bcomnes

@bcomnes bcomnes commented Sep 16, 2026

Copy link
Copy Markdown

Stack: 2 of 2 — depends on #2

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.7.
  • 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/migration 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 add the start script.

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 final tree is exactly identical to the preserved combined checkpoint 515761e (both tree IDs: 3f6e1ea523fca7c4a917a5dd16b4d2d112cc2076). No work was dropped during extraction.

Validation

Full npm run check passed on this stacked branch:

  • Typecheck and 57 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

Source initialization, state copying, projection, and fingerprint traversal still have whole-site costs. Beta.7 tracking does not follow all import aliases/static re-exports; 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).

@bcomnes

bcomnes commented Sep 16, 2026

Copy link
Copy Markdown
Author

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant