You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
54 lines
2.5 KiB
54 lines
2.5 KiB
# AGENTS.md
|
|
|
|
This file provides guidance to agents when working with code in this repository.
|
|
|
|
## ⚠ INVIOLABLE — component work pre-flight
|
|
|
|
Before creating, porting, or modifying ANY UIX component, you MUST read:
|
|
|
|
1. **[`web/routes/uix/lib/COMPONENT_AUDIT_GUIDE.md`](web/routes/uix/lib/COMPONENT_AUDIT_GUIDE.md)** — pre-flight audit + reference library matrix + architectural rules + anti-patterns
|
|
2. **[`web/routes/uix/lib/DEMO_AUTHORING_GUIDE.md`](web/routes/uix/lib/DEMO_AUTHORING_GUIDE.md)** — locked demo template (6 tabs, stage, observer, snippets)
|
|
3. **[`src/uix/eidos/components/README.md`](src/uix/eidos/components/README.md)** — eidos contract
|
|
|
|
Skipping these produced the broken Layout Batch 1 (commit `9ec2a57a`) that was reverted + redone. Don't repeat the mistake.
|
|
|
|
## Build/Test Commands
|
|
|
|
```bash
|
|
npm run dev # Start dev server
|
|
npm run build # Production build (static site)
|
|
npm run test # Run all tests once
|
|
npm run test:unit # Run tests in watch mode
|
|
npx vitest run src/lib/ling/test/ling.test.ts # Run single test file
|
|
npx vitest run -t "describe name" # Run tests matching pattern
|
|
npm run check # Type check with svelte-check
|
|
npm run lint # Check formatting with Prettier
|
|
npm run format # Auto-format with Prettier
|
|
```
|
|
|
|
## Critical Architecture
|
|
|
|
### One Alias Table
|
|
|
|
Path aliases live in ONE module, [`uix.aliases.js`](uix.aliases.js), imported by `vite.config.ts`, `svelte.config.js`, the scripts and any app in the workspace. Never copy it into a config; `src/uix/aliases.test.ts` fails if a second copy appears. How an app consumes it: [`docs/consuming.md`](docs/consuming.md).
|
|
|
|
### Svelte 5 Runes Mode Enforced
|
|
|
|
[`svelte.config.js`](svelte.config.js:31) forces `runes: true` for all project files via `dynamicCompileOptions`. All components must use Svelte 5 runes (`$state`, `$derived`, `$effect`, etc.).
|
|
|
|
### Vitest Two-Project Structure
|
|
|
|
[`vite.config.ts`](vite.config.ts:35) defines separate test projects:
|
|
|
|
- **client**: Browser tests via Playwright for `*.svelte.{test,spec}.{js,ts}` files
|
|
- **server**: Node environment for `*.{test,spec}.{js,ts}` files (excludes svelte tests)
|
|
|
|
### Internal Library Pattern
|
|
|
|
Each library (`ling`, `logr`, `glob`, `actx`) uses factory functions (`createLing`, `createLogr`, etc.) that return instances with internal state. The `logr` library depends on `ling` for localized messages.
|
|
|
|
## Code Style
|
|
|
|
- Tabs for indentation, single quotes, no trailing commas, 100 char print width
|
|
- Spanish comments in code are acceptable
|