Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/website.yml
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ jobs:
- run: npm run test:installer
- run: npm run check:audit
- run: npm run build
- name: Dry-run the Cloudflare Worker deploy
- name: Dry-run the Cloudflare deploy
env:
WRANGLER_SEND_METRICS: 'false'
run: npm run deploy -- --dry-run
Expand Down
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,7 @@ next-env.d.ts
/.wrangler/
/outputs/
/work/
/public/sitemap.xml

# Source assets and TypeScript cache
!/public/assets/*.png
Expand Down
21 changes: 12 additions & 9 deletions DEPLOYMENT.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,11 @@

The source and production build are prepared for `https://fxcss.com`. They include the interactive shell installer at `/install.sh`, canonical page URLs, `/sitemap.xml`, and `/robots.txt`. The installer is a public static asset with a plain-text content type, revalidation on every request, and no sign-in requirement in the application.

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 site is a set of static files served by Cloudflare under the Worker name `fxcss-website`. No site code runs per request: `npm run build` writes every page to `dist/client/` as HTML, and each page's data for in-browser navigation as a matching `.txt` file. `wrangler.static.jsonc` holds the configuration, with no `main` script on purpose, and the `deploy` script in `package.json` attaches the `fxcss.com` and `www.fxcss.com` custom domains. Keep the config's name: vinext reads a file called `wrangler.jsonc` as a Worker build and refuses to run without Cloudflare's build plugin. Only the custom 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). Never list `.well-known/` there: `security.txt` stays public. The site has no database, storage or secrets.

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.
The redirects for old addresses are in `public/_redirects`, and every security header is in `public/_headers`. A page can't read the request, so a feature that needs per-request data doesn't fit this setup: `/docs?path=` is read in the browser for that reason.

The application configuration is the source of truth for the site 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

Expand All @@ -28,7 +30,12 @@ The site deploys from this `website` branch. From a fresh clone (`git clone --br
just dry-run
```

3. Sign in to the Cloudflare account that holds the `fxcss.com` zone, then publish:
3. Verify both Cloudflare redirect settings before publishing.

- In **SSL/TLS → Edge Certificates**, enable **Always Use HTTPS** to redirect HTTP requests to HTTPS.
- In **Rules → Redirect Rules**, use the **Redirect from WWW to root** template to send HTTPS requests for `www.fxcss.com` to `https://fxcss.com` with the same path. Enable **Preserve query string**.

4. Sign in to the Cloudflare account that holds the `fxcss.com` zone, then publish:

```sh
just login
Expand All @@ -43,10 +50,6 @@ The site deploys from this `website` branch. From a fresh clone (`git clone --br
- build command `npm ci && npm run build`;
- deploy command `npm run deploy`.

4. Turn on two zone settings. The Worker's `proxy.ts` sends plain HTTP and `www` page requests to `https://fxcss.com`, but static files such as `/install.sh` are served before the Worker runs, so the zone has to cover them:
- **SSL/TLS → Edge Certificates → Always Use HTTPS.**
- A redirect rule from `www.fxcss.com/*` to `https://fxcss.com/${1}`, keeping the query string. In the dashboard: Rules → Redirect Rules, with the "Redirect from WWW to root" template.

5. Validate the public domain without authentication:

```sh
Expand All @@ -73,6 +76,6 @@ On macOS, missing pipx is installed through an existing Homebrew installation. O

## 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.
HTML uses Cloudflare's default for static files, `public, max-age=0, must-revalidate`, so a deploy reaches readers on their next page load. Pages are the same bytes for everyone, so they can't carry a per-request script nonce. The Content Security Policy in `public/_headers` allows inline scripts, which the framework's page data needs, and limits where scripts can load from.

`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.
`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, as do `robots.txt` and `sitemap.xml`. The installer still revalidates on every request. `scripts/check-site.mjs` checks these headers against the built site; verify them again at the live edge after deployment because zone rules can override them.
19 changes: 9 additions & 10 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# fxcss website

The Showcase homepage and Field guide documentation for https://fxcss.com. The application is built with vinext (the Next.js App Router on Vite) and runs as a Cloudflare Worker.
The Showcase homepage and Field guide documentation for https://fxcss.com. The application is built with vinext (the Next.js App Router on Vite) and exported as static files that Cloudflare serves.

This is the `website` branch of [AdamXweb/fxcss](https://github.com/AdamXweb/fxcss). fxcss itself, and the README the documentation is generated from, live on `main`. The two share no files: website changes go to pull requests against `website`, toolkit changes against `main`.

Expand All @@ -13,14 +13,13 @@ This is the `website` branch of [AdamXweb/fxcss](https://github.com/AdamXweb/fxc
| `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/`. |
| `just preview` | Serve the built Worker on http://127.0.0.1:4318, under the production runtime. |
| `just build` | Build every page into `dist/client/`. |
| `just preview` | Serve the built site on http://127.0.0.1:4318, under the production runtime. |
| `just verify [url]` | Check every page, asset, redirect and security header of a running site; `just verify https://fxcss.com` checks the live one. |
| `just dry-run` | Check the deploy without uploading anything or signing in. |
| `just login` | Sign in to Cloudflare with wrangler. |
| `just deploy` | Upload the Worker and attach `fxcss.com` and `www.fxcss.com`. |
| `just first-deploy` | `check`, `build`, `dry-run` and `deploy` in order, then the two zone settings to turn on. |
| `just tail` | Stream the deployed Worker's logs. |
| `just deploy` | Upload the built site and attach `fxcss.com` and `www.fxcss.com`. |
| `just first-deploy` | Run `check`, `build`, `dry-run` and `deploy` in order. Verify the Cloudflare redirect settings before running it. |
| `just content ../fxcss` | Refresh the documentation from a checkout of `main`. |
| `just refresh` | Run the Refresh docs workflow on GitHub: regenerate from `main`, check, push here. |
| `just evidence ../fxcss` | Recapture the comparison screenshots with fxcss (opens Firefox windows). |
Expand Down Expand Up @@ -55,7 +54,7 @@ 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 `@ts-morph/common` override moves `minimatch` to 11.0.3 for its globparts denial-of-service advisory; it is reached only through the `shadcn` CLI (via `ts-morph`), whose newest release still asks for `minimatch` 10, which has no patched version. Remove it once `@ts-morph/common` depends on `minimatch` 11. 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. Pull requests stacked on `fix/website-*` branches also run these checks. 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 raw-head metadata and share cards, checks 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 and Firefox suite (`npm run test:browser`) against the built Worker. It covers journey selection, game completion, search loading and recovery, route announcements, code copying, keyboard-operated comparison controls, catalogue toggles, mobile Escape handling, logo picking and its report card, sidebar search sizing and scrolling, narrow layouts, and the reported catalogue and retro contrast regressions. The main checks also run on the declared minimum Node 22.18.0. For local browser checks, run `npx playwright install chromium firefox`, `npm run build`, then `npm run test:browser`; Playwright starts and stops its own local Worker and blocks outside requests. These checks do not replace testing with screen readers or native browser zoom.
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. Pull requests stacked on `fix/website-*` branches also run these checks. 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 raw-head metadata and share cards, checks 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 and Firefox suite (`npm run test:browser`) against the built site. It covers journey selection, game completion, search loading and recovery, route announcements, code copying, keyboard-operated comparison controls, catalogue toggles, mobile Escape handling, logo picking and its report card, sidebar search sizing and scrolling, narrow layouts, and the reported catalogue and retro contrast regressions. The main checks also run on the declared minimum Node 22.18.0. For local browser checks, run `npx playwright install chromium firefox`, `npm run build`, then `npm run test:browser`; Playwright starts and stops a local Wrangler server and blocks outside requests. These checks do not replace testing with screen readers or native browser zoom.

To run only Firefox, use `npm run test:browser -- --project=firefox`. If the bundled Firefox fails to start on macOS 27 with “Could not find profile folder”, give the test browser separate application data directories ([upstream issue](https://github.com/microsoft/playwright/issues/42768)):

Expand All @@ -66,7 +65,7 @@ MOZ_APP_DATA="$PWD/work/firefox-app-data" MOZ_LOCAL_APP_DATA="$PWD/work/firefox-

## 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. 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 and the normal page navigation if it fails. Retrying returns keyboard focus to the search field. Exact phrases rank first, followed by pages containing all query words in any order. Descriptions select useful prose or list content, with explicit summaries for reference pages, and end at a word boundary. Metadata resolves before HTML streams so all clients receive it in the document head.
`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 and the normal page navigation if it fails. Retrying returns keyboard focus to the search field. Exact phrases rank first, followed by pages containing all query words in any order. Descriptions select useful prose or list content, with explicit summaries for reference pages, and end at a word boundary. Each exported page includes its metadata in the HTML head.

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;
Expand All @@ -82,7 +81,7 @@ just content ../fxcss

That sets `FXCSS_SOURCE` for `scripts/build-content.mjs`, which also copies `docs/icon.png`. Website CI compares the recorded copy with `main` on every run and warns when it is behind. The website's getting-started overview remains deliberately short and links to the full generated guides.

`app/components/` contains the shared navigation, documentation controls, comparison, and copy controls. `app/docs/[slug]/page.tsx` renders the generated pages. `proxy.ts` supplies a fresh Content Security Policy nonce and security headers for each production application response. `public/_headers` gives static files the same headers, and the static catalogue its own policy. `lib/share-card.ts` gives every page the share image, `public/assets/og-card.png`. There are no accounts, forms, remote fonts, or site databases.
`app/components/` contains the shared navigation, documentation controls, comparison, and copy controls. `app/docs/[slug]/page.tsx` renders the generated pages. `public/_headers` gives every page and file its security headers, and the static catalogue its own policy. `public/_redirects` keeps old addresses working. `lib/share-card.ts` gives every page the share image, `public/assets/og-card.png`. There are no accounts, forms, remote fonts, or site databases.

The transparent vector logo is `public/assets/fxcss-logo.svg`. `app/components/brand-mark.tsx` reuses its named `fxcss-flames` and `fxcss-braces` groups, so the downloadable artwork and the website share one source. `app/components/brand-link.tsx` starts one flame spin on pointer entry or keyboard focus and lets it finish even when the pointer or focus leaves. Re-entry during a spin does not restart it. CSS in `app/globals.css` keeps the cyan braces glowing through the spin, then fades the glow if the link is no longer hovered or focused; the braces and wordmark stay upright. The spin is disabled when reduced motion is requested. Serve the SVG from the same origin when reusing the interactive component; a regular `<img>` displays the static artwork.

Expand Down Expand Up @@ -121,6 +120,6 @@ The film is rendered from an HTML source outside this repository. Its on-screen

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.

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 is served as static files under the Worker name `fxcss-website`, configured in `wrangler.static.jsonc`; the `deploy` script attaches the `fxcss.com` and `www.fxcss.com` custom domains. `npm run build` writes every page to `dist/client/`, and `npm run deploy` publishes that folder. No site code runs per request. 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. After each catalogue recapture, `scripts/prepare_catalogue.py` applies the website's document structure, language, landmarks, toggle semantics and contrast fixes without changing captured images. It fails if the toolkit's generated structure has changed unexpectedly. The captured directory is an auxiliary reference marked `noindex,follow`; `/docs/catalogue` remains its indexable documentation page.
7 changes: 0 additions & 7 deletions app/[sample]/page.tsx

This file was deleted.

Loading
Loading