From a9e08cac6c86308e567f54a6f7863d1851703499 Mon Sep 17 00:00:00 2001 From: adamXbot <111877622+adamXbot@users.noreply.github.com> Date: Fri, 30 Oct 2026 16:24:25 +1100 Subject: [PATCH] Fix website navigation, search, loading and interaction coverage --- .github/workflows/refresh-docs.yml | 15 +- .github/workflows/website.yml | 12 +- .gitignore | 4 + DEPLOYMENT.md | 8 +- README.md | 14 +- app/components/comparison.tsx | 30 +- app/components/doc-article.tsx | 7 +- app/components/docs-navigation.tsx | 57 +- app/components/specificity-battle.tsx | 2 +- app/docs/layout.tsx | 7 +- app/globals.css | 12 + app/layout.tsx | 3 +- app/page.tsx | 12 + content/docs.json | 94 +- content/search-index.json | 3 + hooks/use-mobile.ts | 27 +- justfile | 7 +- lib/docs-search.ts | 33 +- package-lock.json | 1297 +++++---------------- package.json | 22 +- playwright.config.ts | 20 + public/_headers | 18 + public/catalogue/index.html | 4 +- public/install.sh | 2 +- public/search/index-df4810122229002a.json | 1 + scripts/build-content.mjs | 38 +- scripts/capture-evidence.py | 4 + scripts/check-site.mjs | 26 + scripts/doc-text.mjs | 33 + tests/browser/site.spec.ts | 184 +++ tests/packaged-source.test.mjs | 4 +- tests/site.test.mjs | 39 +- 32 files changed, 911 insertions(+), 1128 deletions(-) create mode 100644 content/search-index.json create mode 100644 playwright.config.ts create mode 100644 public/search/index-df4810122229002a.json create mode 100644 scripts/doc-text.mjs create mode 100644 tests/browser/site.spec.ts diff --git a/.github/workflows/refresh-docs.yml b/.github/workflows/refresh-docs.yml index 35feff5..6f2e771 100644 --- a/.github/workflows/refresh-docs.yml +++ b/.github/workflows/refresh-docs.yml @@ -61,7 +61,8 @@ jobs: - run: npm ci # npm run content writes content/ and copies main's icon to - # public/assets/icon.png; anything else changing is a bug, not a refresh. + # public/assets/icon.png and the hashed search index; anything else + # changing is a bug, not a refresh. - name: Regenerate the documentation id: content env: @@ -72,12 +73,12 @@ jobs: version=$(cat content/source/version.txt) echo "version=$version" >> "$GITHUB_OUTPUT" echo "main=$(git -C main-checkout rev-parse --short HEAD)" >> "$GITHUB_OUTPUT" - outside=$(git diff --name-only -- . ':!content' ':!public/assets/icon.png') + outside=$(git diff --name-only -- . ':!content' ':!public/assets/icon.png' ':!public/search') if [ -n "$outside" ]; then echo "::error::npm run content changed files it should not: $outside" exit 1 fi - if git diff --quiet -- content public/assets/icon.png; then + if git diff --quiet -- content public/assets/icon.png public/search; then echo "::notice title=Documentation already current::It matches main's README and fxcss $version." echo "publish=no" >> "$GITHUB_OUTPUT" exit 0 @@ -106,6 +107,12 @@ jobs: env: WRANGLER_SEND_METRICS: 'false' run: scripts/check-built-site.sh + - name: Install the browser test runtime + if: steps.content.outputs.publish == 'yes' + run: npx playwright install --with-deps chromium + - name: Check browser interactions + if: steps.content.outputs.publish == 'yes' + run: npm run test:browser - name: Push to website if: steps.content.outputs.publish == 'yes' @@ -116,7 +123,7 @@ jobs: set -euo pipefail git config user.name 'github-actions[bot]' git config user.email '41898282+github-actions[bot]@users.noreply.github.com' - git add -- content public/assets/icon.png + git add -- content public/assets/icon.png public/search git commit -q -m "$MESSAGE" -m "Generated by the Refresh docs workflow from main at $MAIN." git push origin HEAD:website echo "::notice title=Documentation published::$MESSAGE ($(git rev-parse --short HEAD))." diff --git a/.github/workflows/website.yml b/.github/workflows/website.yml index 3a02930..ca46673 100644 --- a/.github/workflows/website.yml +++ b/.github/workflows/website.yml @@ -23,11 +23,15 @@ jobs: check: runs-on: ubuntu-latest timeout-minutes: 15 + strategy: + fail-fast: false + matrix: + node: ['22.18.0', '24'] steps: - uses: actions/checkout@v7 - uses: actions/setup-node@v7 with: - node-version: '24' + node-version: ${{ matrix.node }} cache: npm - uses: actions/setup-python@v7 with: @@ -55,6 +59,12 @@ jobs: env: WRANGLER_SEND_METRICS: 'false' run: scripts/check-built-site.sh + - name: Install the browser test runtime + if: matrix.node == '24' + run: npx playwright install --with-deps chromium + - name: Check browser interactions + if: matrix.node == '24' + run: npm run test:browser # The documentation is a recorded copy of main's README (content/source). # Refresh docs normally keeps it current, but a refresh can fail or wait for diff --git a/.gitignore b/.gitignore index c2355d6..4ae4c22 100644 --- a/.gitignore +++ b/.gitignore @@ -42,3 +42,7 @@ next-env.d.ts !/public/evidence/*.png !/public/catalogue/**/*.png *.tsbuildinfo + +# Browser checks +/playwright-report/ +/test-results/ diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md index f611dea..cf2a43a 100644 --- a/DEPLOYMENT.md +++ b/DEPLOYMENT.md @@ -6,7 +6,7 @@ The source and production build are prepared for `https://fxcss.com`. They inclu The site runs as a Cloudflare Worker named `fxcss-website`. `vite.config.ts` holds its configuration (the name, the compatibility date and Workers Logs), and the `deploy` script in `package.json` attaches the `fxcss.com` and `www.fxcss.com` custom domains. Only those domains answer: the config sets `workers_dev` and `preview_urls` to false, so there is no `workers.dev` or preview URL outside the zone's WAF, HSTS and Access, and a dashboard-only switch would be undone by the next deploy. `public/.assetsignore` lists what wrangler must never upload as a static file (Finder's `.DS_Store`, `.env*` files, the wrangler config, repository metadata); the build prepends it to `dist/client/.assetsignore`, which wrangler reads. Never list `.well-known/` there: `security.txt` stays public. It has no database, storage or secrets. `npm run build` writes the Worker (`dist/server/index.js`), its static files (`dist/client/`) and the generated `dist/server/wrangler.json`, and `npm run deploy` publishes them. Don't edit the generated file; change `vite.config.ts` and rebuild. -The domain's public nameservers were `dorthy.ns.cloudflare.com` and `scott.ns.cloudflare.com` when checked on 2026-09-05, so the zone is on Cloudflare. No apex A record was returned. Nothing has been deployed yet. +The application configuration is the source of truth for the Worker and its custom domains. Verify the current deployment and DNS with the checks below; a repository checkout does not establish their live state. ## Launch sequence @@ -70,3 +70,9 @@ The installer asks for a starting point, confirms its installation plan, bootstr On macOS, missing pipx is installed through an existing Homebrew installation. Otherwise setup uses Python 3.10+ and venv to bootstrap a persistent pipx-managed pipx installation. It cleans up only its own temporary bootstrap directory. Missing Python or venv produces recovery instructions; the installer does not install an operating-system package manager, run as root, or bypass Python's system-package protections. `npm run test:installer` tests those paths with isolated command stubs, including a real terminal-backed `cat install.sh | bash` flow. No tests install packages or modify the host's shell configuration. Windows users receive the documented PowerShell/pipx instructions. + +## Caching policy + +HTML deliberately sends `private, no-store`: every render has a fresh CSP script nonce, which must agree with the response policy. Keep that policy when changing page delivery. A hash-based policy would require separate validation of framework-generated inline scripts; it is not needed to cache static files. + +`public/_headers` gives content-hashed `/_next/static/*` chunks and `/search/*` indexes one year of immutable caching. Unversioned images, media, evidence and catalogue files get a one-hour browser cache. The installer still revalidates on every request. `scripts/check-site.mjs` checks these headers against the built Worker; verify them again at the live edge after deployment because zone rules can override them. diff --git a/README.md b/README.md index b55c444..9820bf4 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ This is the `website` branch of [AdamXweb/fxcss](https://github.com/AdamXweb/fxc | Command | What it does | | --- | --- | -| `just setup` | Install the locked dependencies (Node.js 22.13 or newer). | +| `just setup` | Install the locked dependencies (Node.js 22.18 or newer). | | `just dev` | Development server on http://127.0.0.1:4317. | | `just check` | What Website CI checks before building: docs, types, lint, tests, the installer, and the dependency audit. | | `just build` | Build the Worker into `dist/`. | @@ -55,11 +55,11 @@ just verify vinext 1.0.1 includes `@vercel/og` 1.0.3 with the Satori SVG-escaping fix and the framework's HarfBuzz runtime support. The `satori` override pins `fflate` 0.7.5 to fix its ZIP64 parsing advisory while Satori pins 0.7.3; remove that override once Satori uses a patched release. The lockfile also keeps `@hono/node-server` and `systeminformation` on patched versions within their existing dependency ranges. -The Website GitHub Actions workflow (`.github/workflows/website.yml`) runs the same checks, plus a deploy dry run, on every pull request and push to `website`, without deploying. A second job warns when the recorded documentation is behind `main`. The production check visits every documentation page, validates asset responses and the security headers on pages, redirects and static files, checks that every page carries the share card and that each labelled control's name contains its visible text, and verifies not-found responses and redirects. Browser checks cover navigation, search, code copying, keyboard-operated comparison controls, and narrow layouts. +The Website GitHub Actions workflow (`.github/workflows/website.yml`) runs the same checks, plus a deploy dry run, on every pull request and push to `website`, without deploying. A second job warns when the recorded documentation is behind `main`. The production check visits every documentation page, validates asset responses and the security headers on pages, redirects and static files, checks that every page carries the share card and that each labelled control's name contains its visible text, and verifies not-found responses and redirects. On Node 24, CI also runs the Playwright Chromium suite (`npm run test:browser`) against the built Worker. It covers journey selection, game completion, search loading and recovery, code copying, keyboard-operated comparison controls, catalogue toggles, and mobile Escape handling. The main checks also run on the declared minimum Node 22.18.0. For local browser checks, run `npx playwright install chromium`, `npm run build`, then `npm run test:browser`; Playwright starts and stops its own local Worker and blocks outside requests. ## Documentation source -`README.md` on `main` is the reference source. This branch keeps a recorded copy of it, and of the fxcss version, in `content/source/`. `npm run content` generates and sanitises `content/docs.json` from that copy; it runs automatically before development and production builds. Source hashes and tests detect stale generated content and missing command pages. +`README.md` on `main` is the reference source. This branch keeps a recorded copy of it, and of the fxcss version, in `content/source/`. `npm run content` generates and sanitises `content/docs.json` from that copy; it runs automatically before development and production builds. Source hashes and tests detect stale generated content and missing command pages. The build also writes a content-hashed search index under `public/search/` and records its URL in `content/search-index.json`. Documentation navigation receives only page labels; search downloads the index on first focus or input, with a retry control if it fails. Exact phrases rank first, followed by pages containing all query words in any order. Descriptions use the first prose paragraph and end at a word boundary. The copy refreshes itself. The Refresh docs workflow (`.github/workflows/refresh-docs.yml`) regenerates it from `main` and pushes it to this branch, and Workers Builds deploys the result. `main`'s Website docs workflow starts it after each release reaches PyPI and after each README change. Before pushing, it: - skips a version PyPI doesn't serve yet, so the site never advertises an install that fails; @@ -105,12 +105,14 @@ This launches disposable Firefox sessions, captures 20 states for the unchanged ## Homepage film -The homepage plays a 57-second silent film between the introduction and the three starting points. `public/media/fxcss-film.mp4` is H.264 at 1920x1080 (CRF 27, BT.709, `+faststart`, about 5 MB); `public/media/fxcss-film-poster.jpg` is its frame at 2.5 seconds with a "Get started on your first theme today." play card added on the right; that card appears only on the poster, not in the film. The video uses `preload="none"`, so visitors download only the poster until they press play. The film ends on the logo, without a URL or install command, because the page carries both. +The homepage plays a 57-second silent film between the introduction and the three starting points. `public/media/fxcss-film.mp4` is H.264 at 1920x1080 (CRF 27, BT.709, `+faststart`, about 5 MB); `public/media/fxcss-film-poster.jpg` is its frame at 2.5 seconds with a "Get started on your first theme today." play card added on the right; that card appears only on the poster, not in the film. An expandable text description below the film provides its steps without requiring video playback. The video uses `preload="none"`, so visitors download only the poster until they press play. The film ends on the logo, without a URL or install command, because the page carries both. -The film is rendered from an HTML source outside this repository. Its on-screen commands and output match fxcss's real CLI, and the theme colours come from WhiteSur's `custom/theme-*.css`. Replace both files together when the film changes. +The film is rendered from an HTML source outside this repository. Its on-screen commands and output match fxcss's real CLI, and the theme colours come from WhiteSur's `custom/theme-*.css`. Replace both files and update the adjacent text description in `app/page.tsx` when the film changes. ## Publishing The site is prepared for **https://fxcss.com**. `/install.sh` serves the interactive installer directly as plain text. Canonical URLs, the sitemap, and setup examples use that domain. Publish the matching package metadata when the domain is live. See [DEPLOYMENT.md](DEPLOYMENT.md) for the launch, the Cloudflare zone settings and deploying on every push. -Nothing has been published yet. The site runs as the Cloudflare Worker `fxcss-website`, configured in `vite.config.ts`; the `deploy` script attaches the `fxcss.com` and `www.fxcss.com` custom domains. `npm run build` writes `dist/server/index.js`, `dist/client/` and the generated `dist/server/wrangler.json`, and `npm run deploy` publishes them. Production scripts require the generated Worker configuration. The public installer must work without a browser session or a sign-in redirect. Do not serve the development server publicly. +The site runs as the Cloudflare Worker `fxcss-website`, configured in `vite.config.ts`; the `deploy` script attaches the `fxcss.com` and `www.fxcss.com` custom domains. `npm run build` writes `dist/server/index.js`, `dist/client/` and the generated `dist/server/wrangler.json`, and `npm run deploy` publishes them. Production scripts require the generated Worker configuration. The public installer must work without a browser session or a sign-in redirect. Do not serve the development server publicly. + +The tab favicon uses the existing lightweight SVG, independently of the recorded source icon. The catalogue capture script normalises older toolkit output to `aria-pressed` toggle buttons after each recapture. diff --git a/app/components/comparison.tsx b/app/components/comparison.tsx index 7d664f6..c5cd3c7 100644 --- a/app/components/comparison.tsx +++ b/app/components/comparison.tsx @@ -54,14 +54,13 @@ export function ComparisonDemo({ eyebrow?: string; }) { const [example, setExample] = useState('accent'); - // Fetch the other example's captures shortly after load, so switching is instant. - useEffect(() => { - const id = window.setTimeout(() => { - for (const shown of Object.values(EXAMPLES)) - for (const src of [shown.after, shown.difference]) - new window.Image().src = src; - }, 1000); - return () => window.clearTimeout(id); + const prefetched = useRef(false); + const prefetchExamples = useCallback(() => { + if (prefetched.current) return; + prefetched.current = true; + for (const shown of Object.values(EXAMPLES)) + for (const src of [shown.after, shown.difference]) + new window.Image().src = src; }, []); return ( <> @@ -83,7 +82,7 @@ export function ComparisonDemo({ {/* One comparison for both examples: switching swaps the captures and keeps the chosen view, zoom and slider position. */} - +

{EXAMPLES[example].caption}

@@ -95,8 +94,10 @@ export function ComparisonDemo({ } export function Comparison({ example = 'accent', + onVisible, }: { example?: ComparisonExample; + onVisible?: () => void; }) { const shown = EXAMPLES[example]; const percentage = shown.comparison.percent.toFixed(2); @@ -128,7 +129,10 @@ export function Comparison({ preference.addEventListener('change', updatePreference); document.addEventListener('visibilitychange', updateVisibility); const observer = new IntersectionObserver( - ([entry]) => setVisible(entry.isIntersecting), + ([entry]) => { + setVisible(entry.isIntersecting); + if (entry.isIntersecting) onVisible?.(); + }, { threshold: 0.15, }, @@ -139,7 +143,7 @@ export function Comparison({ preference.removeEventListener('change', updatePreference); document.removeEventListener('visibilitychange', updateVisibility); }; - }, []); + }, [onVisible]); useEffect(() => { if ( @@ -276,7 +280,7 @@ export function Comparison({ height={evidence.dimensions.height} alt={shown.afterAlt} draggable={false} - preload + loading="lazy" />
@@ -288,7 +292,7 @@ export function Comparison({ height={evidence.dimensions.height} alt={shown.beforeAlt} draggable={false} - preload + loading="lazy" />
diff --git a/app/components/doc-article.tsx b/app/components/doc-article.tsx index 6893e9a..6ab0a60 100644 --- a/app/components/doc-article.tsx +++ b/app/components/doc-article.tsx @@ -1,8 +1,11 @@ "use client"; -import { useEffect, useRef, useState } from "react"; +import { useEffect, useMemo, useRef, useState } from "react"; export function DocArticle({ html, codes }: { html: string; codes: string[] }) { const ref = useRef(null); const [status, setStatus] = useState(""); + // Status announcements must not replace the article DOM and erase the + // copied button's label (or keyboard focus and scrollable-code attributes). + const markup = useMemo(() => ({ __html: html }), [html]); useEffect(() => { const element = ref.current; let timer: ReturnType | undefined; @@ -54,7 +57,7 @@ export function DocArticle({ html, codes }: { html: string; codes: string[] }) { }, [codes]); return ( <> -
+
{status} ); diff --git a/app/components/docs-navigation.tsx b/app/components/docs-navigation.tsx index a21d115..bf53c32 100644 --- a/app/components/docs-navigation.tsx +++ b/app/components/docs-navigation.tsx @@ -1,9 +1,8 @@ 'use client'; -import { useEffect, useId, useRef, useState } from 'react'; +import { useCallback, useEffect, useId, useRef, useState } from 'react'; import Link from 'next/link'; import { usePathname } from 'next/navigation'; import { Search, X, ChevronDown } from 'lucide-react'; -import { Sidebar, SidebarProvider } from '@/components/ui/sidebar'; import { Input } from '@/components/ui/input'; import { Button } from '@/components/ui/button'; import { @@ -14,7 +13,8 @@ import { import { searchDocs, type SearchableDoc } from '@/lib/docs-search'; import { revealSecret, searchSecret } from '@/lib/easter-eggs'; import { retroDestinationForQuery, retroDestinations } from '@/lib/time-machine'; -export type NavPage = SearchableDoc; +export type NavPage = Pick; +type SearchStatus = 'idle' | 'loading' | 'ready' | 'error'; function Highlight({ text, query }: { text: string; query: string }) { const terms = [ @@ -48,12 +48,18 @@ function DocsNavigation({ query, setQuery, onNavigate, + searchPages, + searchStatus, + loadSearch, }: { pages: NavPage[]; version: string; query: string; setQuery: (query: string) => void; onNavigate: () => void; + searchPages: SearchableDoc[]; + searchStatus: SearchStatus; + loadSearch: () => void; }) { const pathname = usePathname(); const searchId = useId(); @@ -61,7 +67,7 @@ function DocsNavigation({ const secret = searchSecret(query); const retroDestination = retroDestinationForQuery(query); const searching = Boolean(query.trim()); - const matches = searchDocs(pages, query); + const matches = searchDocs(searchPages, query); const groups = [...new Set(pages.map((p) => p.chapter))]; return (