refactor(): migrate to domstack

Author: jwerle

.github/workflows/docs-audit.yml

@@ -3,83 +3,33 @@ name: Docs Audit
 on:
   pull_request:
   push:
-    branches:
-      - main
-      - master
+    branches: [main, master]
   workflow_dispatch:
 
+permissions:
+  contents: read
+
 jobs:
   docs-audit:
     runs-on: ubuntu-latest
-
     steps:
-      - name: Check out repository
-        uses: actions/checkout@v4
-
-      - name: Set up Python
-        uses: actions/setup-python@v5
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
         with:
-          python-version: "3.12"
-
-      - name: Set up Node.js
-        uses: actions/setup-node@v4
+          node-version: '24'
+          cache: npm
+      - uses: actions/setup-python@v5
         with:
-          node-version: "20"
-
-      - name: Rebuild generated docs artifacts
-        run: |
-          python3 runtime/tools/build-indexes.py
-          python3 runtime/tools/build-llms-txt.py
-
-          python3 sage/tools/build-indexes.py
-          python3 sage/tools/build-llms-txt.py
-
-          python3 slg/tools/build-indexes.py
-          python3 slg/tools/build-llms-txt.py
-
-          python3 virtnosis/tools/build-indexes.py
-          python3 virtnosis/tools/build-llms-txt.py
-
-          python3 silk/tools/build-indexes.py
-          python3 silk/tools/build-llms-txt.py
-
-      - name: Run docs audits
-        run: |
-          python3 runtime/tools/audit-site.py
-          python3 sage/tools/audit-site.py
-          python3 slg/tools/audit-site.py
-          python3 virtnosis/tools/audit-site.py
-          python3 silk/tools/audit-site.py
-          python3 silk/tools/audit-stdlib-docs.py
-
-      - name: Run static checks
+          python-version: '3.12'
+      - run: npm ci
+      - run: npx playwright install --with-deps chromium
+      - run: npm run check
+      - name: Verify source files remain unchanged
         run: |
-          python3 -m py_compile runtime/tools/*.py
-          python3 -m py_compile sage/tools/*.py
-          python3 -m py_compile slg/tools/*.py
-          python3 -m py_compile virtnosis/tools/*.py
-          python3 -m py_compile silk/tools/*.py
-
-          node --check assets/docs-viewer.js
-          node --check assets/spec-viewer.js
-          node --check assets/site.js
-
           git diff --check
-          git diff --exit-code -- \
-            runtime/docs/index.json \
-            runtime/docs/search.json \
-            runtime/llms.txt \
-            sage/docs/index.json \
-            sage/docs/search.json \
-            sage/llms.txt \
-            slg/docs/index.json \
-            slg/docs/search.json \
-            slg/llms.txt \
-            virtnosis/docs/index.json \
-            virtnosis/docs/search.json \
-            virtnosis/llms.txt \
-            silk/docs/index.json \
-            silk/docs/search.json \
-            silk/wiki/index.json \
-            silk/wiki/search.json \
-            silk/llms.txt
+          git diff --exit-code
+      - uses: actions/upload-artifact@v4
+        if: failure()
+        with:
+          name: browser-test-results
+          path: test-results/

.github/workflows/pages.yml

@@ -0,0 +1,46 @@
+name: Deploy GitHub Pages
+
+on:
+  push:
+    branches: [main, master]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+          cache: npm
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: npm ci
+      # Upstream ingestion is manual. Validate only the committed public sources.
+      - run: npx playwright install --with-deps chromium
+      - run: npm run check
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: public
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -2,3 +2,11 @@
 _site
 .code
 .codex
+
+node_modules/
+public/
+public-next/
+test-results/
+playwright-report/
+__pycache__/
+*.pyc

.nvmrc

@@ -0,0 +1 @@
+24

README.md

@@ -1,87 +1,129 @@
 # Oro Website
 
-This directory contains the static website for Oro Computer, including landing pages and documentation for:
+Oro Computer's static website uses DOMStack to build marketing pages, learning
+chapters, and documentation for Runtime, Silk, Virtnosis, Sage, and slg.
 
-- **Oro Runtime** (`website/runtime/`)
-- **Silk** (`website/silk/`)
-- **Virtnosis** (`website/virtnosis/`)
+## Local development
 
-The public top-level navigation is intentionally small:
+Use Node 24 and Python 3.12. No sibling checkout is needed to build the site.
 
-- **Technology** (`website/index.html`) presents Oro Runtime, Silk, and Virtnosis.
-- **Blog** (`website/blog/`) is a static placeholder for future engineering notes.
-- **Docs** (`website/docs/`) routes readers into Runtime and Silk documentation.
-
-Legacy Sage and slg pages remain in the repository for continuity, but they are
-not promoted from the top-level navigation or docs hub.
-
-## Runtime docs
-
-Runtime docs use the same docs viewer UX as Silk docs (sidebar, search, prev/next, deep links).
-
-- Viewer: `website/runtime/docs/index.html`
-- Markdown sources: `website/runtime/docs/source/`
-- Generated indexes:
-  - `website/runtime/docs/index.json`
-  - `website/runtime/docs/search.json`
-- LLM pack: `website/runtime/llms.txt`
-
-Rebuild generated files after changing sources:
-
-```bash
-python3 website/runtime/tools/build-indexes.py
-python3 website/runtime/tools/build-llms-txt.py
-```
-
-## Silk docs
-
-- Docs viewer: `website/silk/docs/index.html`
-- Wiki viewer: `website/silk/wiki/index.html`
-- Generators live in `website/silk/tools/`.
-
-Rebuild generated files:
-
-```bash
-python3 website/silk/tools/build-indexes.py
-python3 website/silk/tools/build-llms-txt.py
+```sh
+npm ci
+npm run dev
 ```
 
-To refresh the website copy from the sibling Silk compiler checkout:
-
-```bash
-python3 website/silk/tools/sync-from-silk-docs.py
-python3 website/silk/tools/build-indexes.py
-python3 website/silk/tools/build-llms-txt.py
-python3 website/silk/tools/audit-site.py
-python3 website/silk/tools/audit-stdlib-docs.py
+`npm run build` creates `public/` from scratch. `npm run preview` builds and serves
+that same artifact. Generated HTML, search indexes, raw Markdown, and LLM packs
+are output files; do not commit `public/`.
+
+## Editing content
+
+- `src/**/page.html`: authored page fragments, with metadata in `page.vars.ts`.
+- `src/**/page.md`: public documentation, including YAML frontmatter.
+- `src/layouts/`: shared page chrome, navigation, and progressive browser clients.
+- `src/globals/global.css`: Oro styles, based on `docs/branding/`.
+- `src/lib/`: rendering, URL, collection, and navigation helpers.
+- `src/global.data.ts`: collection data derived from source pages.
+- `src/artifacts.template.ts`: navigation/search JSON, raw Markdown, LLM packs,
+  and sitemap output.
+
+Consult `docs/branding/` before changing visual design or copy tone. The approved
+logo originals remain in `docs/branding/assets/`; their checked mirrors in `src/docs/branding/assets/` retain
+the same public URLs. Update both when replacing an asset. Handlebars is disabled globally so literal `{{ ... }}` code
+examples remain intact.
+
+Each documentation page declares `title`, `description`, `docsCollection`,
+`section`, `order`, `sourcePath`, `githubRepo`, and `githubRef`. Preserve
+`sourcePath`: it defines the stable raw Markdown endpoint and import identity.
+The `start` document lives at its collection root; the specification lives at
+`src/silk/spec/2026/page.md`. Order is explicit and does not depend on filenames.
+New imported pages are appended; review their section and order after syncing.
+
+Use canonical directory links such as `/runtime/docs/guides/hello-world/`.
+Collection roots redirect legacy `?p=` links while preserving fragments. Static
+redirect pages retain Silk's old logger-guide and specification aliases. The
+articles, sidebar, previous/next navigation, and ToC work without JavaScript;
+search, tabs, copy controls, and Ask AI progressively enhance them.
+
+## Refreshing upstream content
+
+Ingestion is separate from building and CI. These commands read explicit upstream
+checkouts, preserve the established curated/website-owned content, and write
+committed DOMStack Markdown pages. Review and commit their changes before deploying.
+
+```sh
+python3 silk/tools/sync-from-silk-docs.py --silk-repo /path/to/silk
+python3 runtime/tools/generate-js-api-reference.py --runtime-repo /path/to/runtime
+npm run build
+npm run audit
+npm run audit:content
 ```
 
-## Virtnosis docs
-
-- Docs viewer: `website/virtnosis/docs/index.html`
-- Markdown sources: `website/virtnosis/docs/source/`
-
-Rebuild generated files:
-
-```bash
-python3 website/virtnosis/tools/build-indexes.py
-python3 website/virtnosis/tools/build-llms-txt.py
+The defaults use adjacent `silk` and `runtime` directories, independent of the
+website checkout's name. Silk's legacy `--repo-root` workspace option is retained.
+The tools stage flat Markdown temporarily, apply the existing ownership and
+pruning rules, then import it through `tools/import-public.ts`. Public-copy
+normalization runs during ingestion, never during rendering; fenced examples
+are preserved. Unchanged staged pages keep their exact Markdown and metadata;
+linked API headings become plain-text titles when a page changes. The reference
+catalog includes new pages in the same import batch. Runtime's generated
+reference markers retain surrounding prose.
+
+The Python index and LLM exporters have been replaced by DOMStack templates.
+Content audits inspect `public/` by default; set `ORO_SITE_OUTPUT` to inspect
+another output directory. Set `ORO_RUNTIME_REPO` explicitly to additionally audit
+against a particular upstream Runtime checkout; ordinary checks are independent
+of whatever happens to be checked out next door.
+
+## Validation
+
+Install the browser once, then run the same complete gate used by both CI and
+Pages deployment:
+
+```sh
+npx playwright install chromium
+npm run check
 ```
 
-## slg docs
-
-- Docs viewer: `website/slg/docs/index.html`
-- Markdown sources: `website/slg/docs/source/`
-
-Rebuild generated files:
-
-```bash
-python3 website/slg/tools/build-indexes.py
-python3 website/slg/tools/build-llms-txt.py
+Individual checks are also available:
+
+```sh
+npm run typecheck
+npm test
+npm run build
+npm run audit
+npm run audit:content
+npm run test:site
+npx playwright install chromium
+npm run test:browser
+npm run test:tooling
+npm run test:reproducibility
 ```
 
-## Shared docs viewer
-
-Runtime, Silk, Virtnosis, Sage, and slg use the shared docs viewer:
-
-- `website/assets/docs-viewer.js`
+The crawler checks every generated internal link and fragment. Site tests cover
+all original 27 HTML routes and 585 documentation routes, raw-source parity,
+search text, and LLM packs. Browser tests cover desktop/mobile layouts,
+no-JavaScript rendering, compatibility redirects, search, tabs, copy controls,
+Ask AI, specification heading search, and fragments inside tabs. Tooling tests
+verify all 585 pages survive unchanged imports and that a renamed standalone
+checkout rebuilds articles and exports during development. To use an existing Chromium install,
+set `ORO_BROWSER_EXECUTABLE` to its executable path.
+
+`tools/migration/migrate.ts /path/to/legacy-checkout` records the original route
+inventory and performs the deterministic initial conversion. It is a migration
+utility, not a routine content refresh command. Keep `tools/migration/baseline.json`
+as the compatibility fixture. See [migration status and cutover](docs/migration.md). When intentionally retiring or adding routes,
+update the relevant assertions and redirects together.
+
+## Deployment and dependency updates
+
+GitHub Actions builds and uploads `public/` and deploys with the Pages environment.
+The repository's **Settings → Pages → Source** must be **GitHub Actions**. Merging
+these changes does not itself change that repository setting. The output contains
+`CNAME`, `.nojekyll`, branding assets, raw Markdown, and `llms.txt` packs.
+
+DOMStack uses the **beta** distribution tag in `package.json`. The committed
+lockfile records the resolved version, and CI uses `npm ci` for reproducible
+installs. To refresh to the current beta, run `npm update @domstack/static`,
+commit the updated lockfile, run the complete validation sequence, and compare
+representative desktop and mobile screenshots.