feat: complete the Astro migration, remove all framework islands

.ai/templates/generate-reveal-zip.mjs

@@ -4,9 +4,14 @@
  *
  * Run: node .ai/templates/generate-reveal-zip.mjs
  *
+ * Requires jszip (devDependency). The reveal assets are read from the committed
+ * public/reveal/, not from node_modules, so reveal.js itself is not needed to run this.
+ *
  * Re-vendor note: public/reveal/ is a hand-vendored four-file subset of reveal.js@6.0.1.
+ * reveal.js is deliberately NOT a dependency; install it ad hoc when updating
+ * (npm install reveal.js@6, same pattern as pptxgenjs for the PPTX generator).
  * The full dist/ tree is NOT copied. When updating Reveal, copy only these four files from
- * node_modules/reveal.js/dist/ to public/reveal/ — do not copy the whole directory, as
+ * node_modules/reveal.js/dist/ to public/reveal/ - do not copy the whole directory, as
  * that would restore deleted themes and plugins along with their OFL and BSD attribution
  * obligations. The four required files are: reset.css, reveal.css, reveal.js,
  * plugin/notes.js.

.claude/commands/add-solution.md

@@ -188,13 +188,13 @@ If lint or build fail, fix the issues before reporting done.
 Check the built HTML contains the solution title:
 
 ```bash
-grep -c "<solution-title-fragment>" dist/client/adventures/<adventure-id>/levels/<level-id>/solution/index.html
+grep -c "<solution-title-fragment>" dist/adventures/<adventure-id>/levels/<level-id>/solution/index.html
 ```
 
 Use a unique word from the solution title as the fragment. If a contributor was provided, also confirm their name appears:
 
 ```bash
-grep -c "<contributor-name>" dist/client/adventures/<adventure-id>/levels/<level-id>/solution/index.html
+grep -c "<contributor-name>" dist/adventures/<adventure-id>/levels/<level-id>/solution/index.html
 ```
 
 Report success with the path if both pass.

.claude/commands/create-presentation.md

@@ -16,7 +16,7 @@ Generate a presentation that matches the OffOn design system, in the format of y
 2. Reads the appropriate template file.
 3. Generates slide content and fills in the placeholders.
 4. Writes the output file to `public/`.
-5. Does not touch `public/sitemap.xml`, `react-router.config.ts`, or `src/routes.ts`.
+5. Does not touch `src/pages/sitemap.xml.ts`, `astro.config.mjs` redirects, or test route lists — presentations go in `public/` and are not Astro pages.
 
 ---
 
@@ -517,7 +517,7 @@ When creating a deck for a challenge walkthrough:
 - Slides 3–N: One slide per major step. Use `.sh` header with step number as overline label.
 - Final slide: What the learner accomplished + link to the challenge on offon.dev.
 
-For scenario and architecture text, pull from the adventure's generated TypeScript in `src/data/adventures/<id>/<id>.generated.ts`. The `scenario`, `architecture`, `backstory`, and `objective` fields are pre-rendered HTML; strip tags or paraphrase for slide copy; do not paste raw HTML into the deck.
+For scenario and architecture text, pull from the adventure YAML at `src/data/adventures/<id>/adventure.yaml`. The `scenario`, `architecture`, `backstory`, and `objective` fields contain markdown; paraphrase for slide copy. Do not use or look for `*.generated.ts` files — they no longer exist.
 
 ---
 
@@ -529,7 +529,7 @@ For scenario and architecture text, pull from the adventure's generated TypeScri
 4. Update the title in `<title>` (Reveal.js).
 5. Write to:
    - Reveal.js: `public/<event-slug>/index.html` (create the subfolder if it does not exist)
-6. Do not add any of these files to `src/routes.ts`, `public/sitemap.xml`, or `react-router.config.ts`.
+6. Do not add any of these files to `src/pages/sitemap.xml.ts` or the test route lists in `e2e/` — presentations live under `public/` and are not Astro pages.
 7. Confirm: `ls -lh <output-path>`
 
 **For PowerPoint (`pptx`):** edit `.ai/templates/generate-pptx.mjs` with the presentation content, then run:

.claude/commands/navigation.md

@@ -103,12 +103,12 @@ Dragon NaturallySpeaking and iOS Voice Control navigate by speaking visible link
 If `aria-label` differs from visible text, the user cannot activate the link by speaking
 what they see. **The accessible name must contain the visible text.**
 
-## SPA/React Router Note
+## SPA Navigation Note
 
-After route changes, screen reader users hear nothing unless focus is managed. When React
-Router navigates, move focus to the new page's `<h1>` or the skip link target, and ensure
-the page title updates. This is already handled by React Router v7's framework mode —
-verify it is not broken when adding new routes.
+After route changes, screen reader users hear nothing unless focus is managed. Astro's
+`<ClientRouter />` emits a route announcer and moves focus to `#main-content` after each
+client-side navigation — this is wired in `Layout.astro`. Verify it is not broken when
+adding new routes.
 
 ## Definition of Done Checklist
 

.claude/commands/progressive-enhancement.md

@@ -64,10 +64,10 @@ if ('fetch' in window && 'querySelector' in document) {
 
 ## Critical: Core Content Must Not Require JavaScript
 
-This site uses React Router v7 with `ssr: false` (static prerendering). Pages are
-prerendered at build time so content is in the HTML. Verify that:
+This site uses Astro with `output: 'static'`. Pages are prerendered at build time
+so content is in the HTML. Verify that:
 
-- Every page's core content is in the prerendered HTML output in `dist/client/`
+- Every page's core content is in the prerendered HTML output in `dist/`
 - No critical information is rendered exclusively client-side after hydration
 - Filter/search UI degrades gracefully (content visible even when JS filtering is unavailable)
 

.claude/commands/user-personalization.md

@@ -49,7 +49,7 @@ in `src/index.css`. Check every new animation or color change against these quer
   }
 }
 
-@media (prefers-color-scheme: dark) { /* handled by useTheme hook */ }
+@media (prefers-color-scheme: dark) { /* handled by the inline pre-paint script in Layout.astro */ }
 
 @media (prefers-contrast: more) {
   :root {
@@ -70,14 +70,14 @@ in `src/index.css`. Check every new animation or color change against these quer
 
 This site manages two user preferences:
 
-**Theme (light/dark):** Handled by `useTheme` hook in `src/hooks/useTheme.tsx`.
-- Stored in `localStorage` under the `theme` key (see `THEME_STORAGE_KEY` in `src/data/constants.ts`)
-- Initialized to `dark` on first render, updated in `useEffect` from stored value
-- Never read `localStorage` during render — hydration safety rule applies
+**Theme (light/dark):** Handled by `ThemeToggle.astro` and an inline pre-paint script in `Layout.astro`.
+- Stored in `localStorage` under the `theme` key
+- The pre-paint script reads it before first paint to avoid FOUC; `ThemeToggle.astro` toggles it via a delegated `click` listener on `document`
+- Never read `localStorage` during server-side render — only in the inline pre-paint script or in an `astro:page-load` handler
 
-**Analytics consent:** Handled by `useConsent` hook in `src/hooks/useConsent.tsx`.
+**Analytics consent:** State lives in the `$consent` nanostore (`src/stores/consent.ts`).
 - Stored in `localStorage` under `analytics_consent` key
-- The consent banner is the personalization UI for this preference
+- `ConsentBanner.astro` is the personalization UI; its script re-subscribes to `$consent` on every `astro:page-load`
 - All `localStorage` access must be in `try/catch` blocks
 
 ## Moderate: Safe localStorage Pattern

.github/pull_request_template.md

@@ -10,7 +10,7 @@
 ## Manual checks
 
 - [ ] Screen reader tested _(UI changes only)_
-- [ ] New routes added to sitemap.xml, prerender array, README _(routes only)_
+- [ ] New routes added to e2e/a11y.spec.ts, e2e/smoke.spec.ts, sitemap.xml.ts, and README _(routes only; sitemap is auto-generated from getStaticPaths, so only static pages need manual entries)_
 - [ ] UI verified at 375px, 768px, and 1280px against the production build (`npm run build && npm run preview`) _(UI changes only)_
 - [ ] Re-read every changed file; checked all call sites of any modified exports _(all changes)_
 - [ ] Per-level discussion JSON exists with correct `discussionUrl` _(adventure/level changes only)_

.github/workflows/a11y-scan.yml

@@ -25,6 +25,8 @@ jobs:
 
       - run: npm ci
 
+      - run: npm run sync
+
       - run: npm run build
 
       - uses: actions/cache@v6

.github/workflows/add-discussion-url.yml

@@ -35,7 +35,7 @@ jobs:
       pull-requests: write
 
     steps:
-      - uses: actions/create-github-app-token@v3
+      - uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3
         id: app-token
         with:
           client-id: ${{ vars.APP_ID }}
@@ -102,8 +102,8 @@ jobs:
           DISCUSSION_URL: ${{ inputs.discussion_url }}
         run: node scripts/set-discussion-url.mjs
 
-      - name: Regenerate TypeScript
-        run: node scripts/generate-adventures.mjs
+      - name: Validate adventure YAML (Zod content schema)
+        run: npm run sync
 
       - name: Create pull request
         env:
@@ -125,9 +125,6 @@ jobs:
           git add \
             "src/data/adventures/${ADVENTURE_ID}/adventure.yaml" \
             "src/data/adventures/${ADVENTURE_ID}/${LEVEL_ID}-posts.json" \
-            "src/data/adventures/${ADVENTURE_ID}.generated.ts" \
-            "src/data/adventures/index.ts" \
-            "src/data/adventures/summaries.ts" \
             "scripts/refresh-leaderboard.mjs"
 
           HAS_CHANGES=false
@@ -154,14 +151,14 @@ jobs:
 
           - \`adventure.yaml\` — \`community_url\` set on the \`${LEVEL_ID}\` level; \`community_category_id\` set at adventure root if it was missing
           - \`${LEVEL_ID}-posts.json\` — \`discussionUrl\` set and initial posts fetched from Discourse
-          - Generated TypeScript updated (\`${ADVENTURE_ID}.generated.ts\`, \`index.ts\`, \`summaries.ts\`)
           - \`scripts/refresh-leaderboard.mjs\` — \`ADVENTURE_CATEGORIES\` patched with the resolved category ID
+          - (Astro reads the YAML directly — no generated TypeScript to update)
 
           ### Before merging
 
           - [ ] Verify the discussion URL is correct and the thread is publicly visible
           - [ ] Check that the posts JSON contains the expected content (or is an empty array if the thread is new)
-          - [ ] Run \`npm run lint && npm test && npm run build && npm run test:e2e\` locally
+          - [ ] Run \`npm run lint && npm run test:unit && npm run build && npm run test:e2e\` locally
 
           ### After merging
 

.github/workflows/deploy.yml

@@ -9,7 +9,7 @@ on:
     - cron: "0 2 * * *"
 
 permissions:
-  contents: write
+  contents: read   # All jobs read-only by default; deploy job overrides to write
 
 concurrency:
   group: pages
@@ -21,6 +21,8 @@ env:
 jobs:
   deploy:
     runs-on: ubuntu-latest
+    permissions:
+      contents: write  # Required by JamesIves/github-pages-deploy-action to push gh-pages
     steps:
       - uses: actions/checkout@v7
 
@@ -29,17 +31,29 @@ jobs:
           node-version-file: .nvmrc
           cache: npm
 
-      - run: npm ci
+      - uses: actions/cache@v6
+        id: npm-cache
+        with:
+          path: node_modules
+          key: node-modules-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
 
-      - run: npm run build
+      - if: steps.npm-cache.outputs.cache-hit != 'true'
+        run: npm ci
 
-      - run: cp dist/client/404/index.html dist/client/404.html
+      - run: npm run sync
+      - run: npm run lint
+      - run: npm run check
+      - run: npm run test:unit:coverage
+
+      # Astro static build → dist/ (not dist/client/). Astro emits dist/404.html
+      # natively, so the old `cp .../404/index.html 404.html` step is gone.
+      - run: npm run build
 
       - name: Deploy to gh-pages
-        uses: JamesIves/github-pages-deploy-action@v4
+        uses: JamesIves/github-pages-deploy-action@fa24774553152dd7873cd16ebd8d959b010c5445 # v4
         with:
           branch: gh-pages
-          folder: dist/client
+          folder: dist
           force: false
           clean: true
           clean-exclude: |

.github/workflows/preview.yml

@@ -12,7 +12,7 @@ env:
   FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
 
 jobs:
-  lint:
+  check:
     if: github.event.action != 'closed'
     runs-on: ubuntu-latest
     steps:
@@ -32,7 +32,12 @@ jobs:
       - if: steps.node-cache.outputs.cache-hit != 'true'
         run: npm ci
 
+      # Content validation gate: astro sync runs the Zod collection schema and
+      # fails on invalid adventure YAML.
+      - run: npm run sync
       - run: npm run lint
+      - run: npm run check
+      - run: npm run test:unit:coverage
 
   build:
     if: github.event.action != 'closed'
@@ -54,14 +59,13 @@ jobs:
       - if: steps.node-cache.outputs.cache-hit != 'true'
         run: npm ci
 
+      - run: npm run sync
       - run: npm run build
 
-      - run: npm test
-
       - uses: actions/upload-artifact@v7
         with:
-          name: dist-client
-          path: dist/client/
+          name: dist
+          path: dist/
           retention-days: 1
 
   e2e:
@@ -91,8 +95,8 @@ jobs:
 
       - uses: actions/download-artifact@v7
         with:
-          name: dist-client
-          path: dist/client/
+          name: dist
+          path: dist/
 
       - uses: actions/cache@v6
         id: playwright-cache
@@ -106,13 +110,12 @@ jobs:
       - if: steps.playwright-cache.outputs.cache-hit == 'true'
         run: npx playwright install-deps chromium
 
+      # playwright.config webServer runs `astro preview` (serves dist/) itself.
       - run: npm run test:e2e -- --shard=${{ matrix.shard }}/3
 
   preview:
-    needs: [lint, e2e]
-    # Run when both passed (normal PR update), or when build was skipped (PR closed, cleanup).
-    # Never run when tests failed.
-    if: always() && ((needs.lint.result == 'success' && needs.e2e.result == 'success') || needs.lint.result == 'skipped')
+    needs: [check, e2e]
+    if: always() && ((needs.check.result == 'success' && needs.e2e.result == 'success') || needs.check.result == 'skipped')
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
@@ -132,27 +135,18 @@ jobs:
       - if: github.event.action != 'closed' && steps.node-cache.outputs.cache-hit != 'true'
         run: npm ci
 
+      # Astro's `base` (from VITE_BASE_PATH) prefixes every asset/link, and public/
+      # assets are copied into dist/ automatically — so the whole dist/ deploys as
+      # the preview with no per-directory asset-copy step. Layout.astro marks
+      # /pr-preview/ builds noindex.
       - if: github.event.action != 'closed'
-        run: VITE_BASE_PATH=/pr-preview/pr-${{ github.event.number }}/ npm run build
+        run: npm run sync
 
       - if: github.event.action != 'closed'
-        run: |
-          PREVIEW_DIR="dist/client/pr-preview/pr-${{ github.event.number }}"
-          cp -r dist/client/assets "${PREVIEW_DIR}/"
-          cp -r dist/client/fonts "${PREVIEW_DIR}/"
-          cp -r dist/client/reveal "${PREVIEW_DIR}/"
-          cp -r dist/client/team "${PREVIEW_DIR}/"
-          cp -r dist/client/speakers "${PREVIEW_DIR}/"
-          cp -r dist/client/brand "${PREVIEW_DIR}/"
-          cp -r dist/client/solutions "${PREVIEW_DIR}/"
-          cp -r dist/client/qr "${PREVIEW_DIR}/"
-          cp -r dist/client/downloads "${PREVIEW_DIR}/"
-          cp -r dist/client/screenshots "${PREVIEW_DIR}/"
-          cp -r dist/client/deck "${PREVIEW_DIR}/"
-          cp -r dist/client/deck-template "${PREVIEW_DIR}/"
-          find dist/client -maxdepth 1 -type f \( -name "*.svg" -o -name "*.png" -o -name "*.ico" -o -name "*.webmanifest" -o -name "*.webp" \) -exec cp {} "${PREVIEW_DIR}/" \;
-          cp "${PREVIEW_DIR}/index.html" "${PREVIEW_DIR}/404.html"
-
-      - uses: rossjrw/pr-preview-action@v1
+        env:
+          PR_NUMBER: ${{ github.event.number }}
+        run: VITE_BASE_PATH=/pr-preview/pr-${PR_NUMBER}/ npm run build
+
+      - uses: rossjrw/pr-preview-action@ffa7509e91a3ec8dfc2e5536c4d5c1acdf7a6de9 # v1
         with:
-          source-dir: dist/client/pr-preview/pr-${{ github.event.number }}/
+          source-dir: dist/

.github/workflows/refresh-community-data.yml

@@ -21,7 +21,7 @@ jobs:
   refresh:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/create-github-app-token@v3
+      - uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3
         id: app-token
         with:
           client-id: ${{ vars.APP_ID }}
@@ -96,14 +96,22 @@ jobs:
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
-          gh issue create \
-            --title "Refresh community data: JSON validation failed" \
-            --label "bug" \
-            --body "The scheduled \`refresh-community-data\` workflow failed JSON structure validation and did not commit new data to \`main\`.
+          TITLE="Refresh community data: JSON validation failed"
+          OPEN=$(gh issue list \
+            --state open \
+            --search "\"${TITLE}\" in:title" \
+            --json number \
+            --jq 'length' 2>/dev/null || echo "0")
+          if [ "$OPEN" -eq 0 ]; then
+            gh issue create \
+              --title "${TITLE}" \
+              --label "bug" \
+              --body "The scheduled \`refresh-community-data\` workflow failed JSON structure validation and did not commit new data to \`main\`.
 
           **Run:** ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
 
           Check the run log for which file failed and which field was missing or malformed. Fix the upstream script that writes that file, then re-run the workflow manually via workflow_dispatch."
+          fi
 
       - name: Commit if changed
         id: commit

.github/workflows/refresh-community-sitemap.yml

@@ -21,7 +21,7 @@ jobs:
   generate:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/create-github-app-token@v3
+      - uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3
         id: app-token
         with:
           client-id: ${{ vars.APP_ID }}

.github/workflows/reuse.yml

@@ -14,4 +14,4 @@ jobs:
     steps:
       - uses: actions/checkout@v7
       - name: REUSE lint
-        uses: fsfe/reuse-action@v6
+        uses: fsfe/reuse-action@676e2d560c9a403aa252096d99fcab3e1132b0f5 # v6