# luxe.dev The website. Astro for the pages, Svelte for the three things that need behavior, no server. ```bash npm install npm run dev # http://localhost:4321 npm run build # → dist/ npm run check # astro + typescript npm run smoke # builds, then drives the pages in headless Chrome npm run cross # every engine on the machine, against `astro dev` ``` **One engine is not coverage.** `npm run smoke` drives Chrome, and the two worst bugs this site has had were invisible in it: a demo player whose dynamic `import()` Firefox refused outright, and a row pitch only Chrome's metrics agreed with. `npm run cross` opens the pages in Chromium, Firefox and WebKit — WebKit standing in for Safari — and asserts that every demo island actually *boots*, which is the thing that broke. It also checks each demo's terminal fills its frame at 1600px and twice the density: Chromium rounds a glyph's advance to a whole pixel unless the player asks for `geometricPrecision`, and at that size a 120-column demo ran 7% off its frame. It runs against `astro dev` by default and `--built` for the real bundle. An engine the host cannot launch is reported and skipped: Playwright's WebKit wants Ubuntu's ICU and libxml2 sonames, which a rolling distro does not have. CI installs all three and passes `--require webkit`, so the coverage is real there even when a laptop skips it. One trap worth knowing, because it is invisible three different ways. The player is behind a dynamic `import()` inside an island, so Vite does not see it while crawling entry points and optimizes it *mid-session*, invalidating the graph it had already served. Chrome re-requests and carries on; Firefox calls the interrupted response corrupted and every demo stays blank for the rest of the session. It never touched a production bundle. `optimizeDeps.include` in `astro.config.mjs` is the mitigation — and note that it is a *race*, so a cold `.vite` cache does not reproduce it. What `cross` guards is the outcome: blank demos, in any engine, for any reason. ## Nothing here is drawn by hand Two kinds of asset, and they answer to different rules. **`src/assets/generated/`** comes out of the Rust source and is regenerated by `scripts/site-assets.sh` at the repo root: | asset | from | | --- | --- | | `wordmark.svg`, `mark.svg`, `tile.svg` | the art constants the TUI draws (`wordmark_svg`) | | `tokens.css` | `crates/luxe-core/src/themes/luxe*.json` (`theme_css`) | | `*.luxe.svg`, `*.luxe-light.svg` | the production view path (`fixture_svg`) | | `theme-preview.svg`, `.json` | the dashboard once for every theme, colored by CSS variables (`fixture_svg --palette`) | | `*.cast` | a scripted session through the real reducer (`fixture_cast`) | CI runs `scripts/site-assets.sh --check` and fails if they are stale. Do not edit them; change the source and regenerate. **`src/assets/captures/`** is the other kind: recordings of real sessions against a real provider. ```bash scripts/site-record.sh web/demo-scripts/flagship.rec # 150x36, for a laptop scripts/site-record.sh --name flagship.mobile --cols 72 --rows 24 web/demo-scripts/flagship.rec scripts/site-record.sh --raw web/demo-scripts/stills.rec # a take cut into screenshots scripts/cast-still.py src/assets/captures/stills.cast --at 7.8 --out .../palette.svg ``` Each demo declares its own size, speed, model and starting state in `#:` directives at the top of its `.rec` script, so re-shooting the set is one command per demo. The window runs hidden on a Hyprland special workspace and keystrokes go into the pty, so a recording cannot be disturbed by — or disturb — whatever you are doing. Two recordings play on the page, `flagship` and `mention`, and everything else is a still: a screenshot holds still long enough to be read, and a page of moving terminals is a page nobody can follow. The recorded stills come from `stills.rec` and `stills-tools.rec`, whose headers list the exact `cast-still.py` cuts; the review, peek and theme pictures are fixtures `site-assets.sh` generates. They play at 1x: agents are fast enough without help, so a take is trimmed of dead air and never sped up. The demo project is fictional and so is its GitHub. `demo-scripts/gh/gh` stands in for the GitHub CLI, answering for an `acme/todo` that doesn't exist, so the `@` picker's GitHub tab has issues to list without putting strangers' names on the site. A script opts in with `#: bin gh`; the stand-in is read-only and refuses anything it wasn't written to answer. The trade is stated plainly: **no two runs produce the same bytes, so nothing checks that a capture still matches the build.** `manifest.json` records the commit, size and theme each take was shot against. When luxe's appearance changes, re-record. The webfonts in `public/fonts/` come from `scripts/site-fonts.sh`, which subsets them to exactly the characters **both** directories use — a capture that catches an icon no fixture ever drew would otherwise ship as tofu to every reader without JetBrains Mono installed. JetBrains Mono is the face, because it's the one most people already run; a sliver of Adwaita Mono covers the six marks it lacks. ## The manual is not here either `/docs` renders `docs/guide/*.md` from the repo root through a content collection — the same files someone reads on GitHub, and the same ones the agent reads when you ask it how to do something. A copy under `web/` would be a third version that drifts from both. A new page is a new file with `title`, `summary` and `order` front matter. Nothing registers it; the sidebar, the pager and the search index all come from the collection. Search is [Pagefind](https://pagefind.app), which indexes the **built** site (`npm run build` runs it) — so what it searches is exactly what a reader sees. There is no index under `astro dev`, and the search box is inert there rather than throwing. ## Deploying Cloudflare Pages, from this subdirectory: - **Build command** — `npm run build` - **Output directory** — `dist` - **Root directory** — `web` - **Node** — 24 or newer (`web/.node-version` pins it for the build image) `public/_headers` sets caching and a content security policy that forbids third-party origins outright, which is the only way to keep the same promise the product makes. A merge to `main` of the public repository that touches `web/` or `docs/guide/` deploys itself: `.github/workflows/site.yml` builds, runs the render check, and uploads. It reads `CLOUDFLARE_API_TOKEN` (an API token with **Account → Cloudflare Pages → Edit**) and `CLOUDFLARE_ACCOUNT_ID` from the repository's `production` environment. By hand: ```bash npm run deploy # → production: luxe-dev.pages.dev and luxe.dev npm run deploy:preview # → a throwaway preview URL, production untouched ``` `deploy` pins `--branch main` **on purpose**. Cloudflare decides production-vs-preview by comparing the deploy's branch against the project's production branch, and with no flag Wrangler reports the local git branch — so from any other branch (this repo is on `master`) the upload silently lands as a preview, production stays empty, and the custom domain serves nothing. The only symptom is that the one URL you get handed has a hash in it. **A hash URL is always a preview.** Production is `luxe-dev.pages.dev`. ## Layout ``` src/ assets/generated/ derived from the Rust source — checked by CI assets/captures/ recorded sessions — checked by nobody, see above components/ Wordmark, Shot, Still, Demo, Refine, InstallTabs, ThemeToggle, DocsSearch content.config.ts the docs collection, loaded from ../docs/guide layouts/Base.astro head, theme boot, masthead, footer pages/ index, themes, brand, social-card, docs/[...slug] styles/ base.css (type, chamfer, layout), prose.css, grain.css ``` The design system is `styles/base.css`. Color is not in it — that is `tokens.css`, generated — so the site and the terminal cannot drift. The one primitive worth knowing is the **chamfer**: a 45° cut corner, taken from the logotype, applied with one custom property and a `clip-path`.