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.
This commit is contained in:
146
web/README.md
Normal file
146
web/README.md
Normal file
@@ -0,0 +1,146 @@
|
||||
# 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`.
|
||||
Reference in New Issue
Block a user