Files
luxe/web/README.md
Evan Whittaker 09a7de2520 Initial public release
Luxe 0.1.0: a coding agent harness for the terminal. See README.md to get started and CHANGELOG.md for releases.
2026-10-17 12:08:30 -05:00

147 lines
8.0 KiB
Markdown

# 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`.