Claude Sonnet 5.5
Site and docs for 0.9.0; drop template leftovers; scripts without hard-coded paths
794b22f | # AGENTS.md: for AI agents (and humans) working on this repo | |
| DSSL is a style language. The engine lives in `public/dssl/`, the site in `src/`, the styles that | |
| drive the site in `public/styles/`, the tests in `scripts/`, the editor extension in `dssl-vscode/`. | |
| The Hugging Face repo (`EHS-Studio/dssl`) is this repo; its README is the full docs. | |
| ## Commands | |
| ```sh | |
| npm install # three runtime packages and a few dev ones; nothing else | |
| npm run dev # Next dev server for the site | |
| npm run typecheck # tsc, must be clean (builds fail on type errors) | |
| npm test # EVERY suite in one report (needs Chrome or Chromium) | |
| npm run test:fast # the same without the browser suites | |
| node scripts/sync-extension-engine.mjs # REQUIRED after touching public/dssl/*.js | |
| bash scripts/build-engine-package.sh # rebuild public/dssl-engine.zip and .tar.gz | |
| cd dssl-vscode && npx @vscode/vsce package --no-dependencies # rebuild the .vsix | |
| ``` | |
| Browser tests use `playwright-core` with a Chrome already on the machine. Set `DSSL_CHROME` if | |
| yours is somewhere unusual. `scripts/lib/browser-harness.mjs` is the one place that launches it. | |
| ## Rules of the house | |
| 1. The engine stays the engine. Inline styles applied live are the architecture, and pseudo-elements | |
| compile to one shadow stylesheet. `dssl build` is a second lane for the static subset, not a | |
| replacement: anything that needs the runtime (`@signal`, `animate`, aura, texture, deform, overlap) | |
| stays in the engine, and the build report must say so. If you add an engine-native feature, the | |
| report has to count it (it prefixes its declaration with `@`, which is how `static.js` knows). | |
| 2. New language surface needs tests in a `scripts/test-vNNN.mjs` and, if it draws, a real-browser | |
| test. A string comparison of generated CSS is not a test of rendering: look at pixels | |
| (`scripts/lib/pixels.mjs`). Add a changelog entry in `src/components/dssl/views/ChangelogView.tsx`. | |
| 3. Every error is loud, with a did-you-mean, and a leftover or unknown word is an error, never noise. | |
| Warnings compile fine; `ok` stays `true`. A lint or checker must never be able to break a compile. | |
| 4. The site dogfoods the engine: its styling lives in `public/styles/*.dssl`, and `dssl check --strict` | |
| over those files must print nothing. A new page needs a route under `src/app/`, an entry in `NAV` | |
| and `VIEW_PATH` in `SiteRoot.tsx`, its own `.dssl` listed in `DSSL_SHEETS` in `src/app/layout.tsx`, | |
| and a line in `src/app/sitemap.ts`. | |
| 5. After ANY change to `public/dssl/*.js`, run `scripts/sync-extension-engine.mjs`, then the extension | |
| tests. The package script and the sync script copy the WHOLE engine folder (the resolver imports | |
| `color`, `texture`, `aura`, `slider` and `lint`); never go back to a hardcoded file list. A test | |
| (`test-v081.mjs`, `test-designer-host.mjs`) fails if you do. | |
| 6. Cascade order is one global sequence in load order (`assignGlobalOrder` in `engine.js`). Do not | |
| compare a rule's own `order` across stylesheets. | |
| 7. Never commit tokens or credentials, not here, not in `public/`, not in a commit message. | |
| 8. Deploys. Site: `vercel deploy --prod --yes --token "$VERCEL_TOKEN"` from the repo root (the project | |
| is `dssl`; run `vercel link --project dssl` once, and delete the `.env.local` it writes). Hugging | |
| Face: push `main` with the token in a request header, not in the URL, so nothing lands in | |
| `.git/config`: | |
| `git -c http.extraHeader="Authorization: Basic $(printf 'EHS-Studio:%s' "$HF_TOKEN" | base64 -w0)" push origin main`. | |
| 9. Verify a ship with raw `curl` and a cache-busting query string, not only a fetcher: CDNs have | |
| served stale content minutes after a good deploy. | |
| 10. Docs are written for people. Plain sentences, no em dashes, say what it is and what it costs. | |
| Tables of settings are generated from the vocabulary modules, so they cannot drift. | |
| ## Conventions | |
| - Numbers are bare and mean pixels. No semicolons are required (except inside `raw { }`, which is real | |
| CSS). Comments are `//` and `/* */`. | |
| - The token registry folds across files in load order; `tokens*.dssl` sorts first. | |
| - Aura has no presets, on purpose. If you want fire, write a `behavior`. Textures have presets because | |
| they are stored combinations of generators and settings; every preset must be reproducible by hand. | |
| - The site is the test suite: when the site needs something the language cannot express, the language | |
| grows. That loop found the cascade bug in 0.8.2 and the contrast failures in 0.9.0. | |