svelte-kit-vice/AGENTS.md

# 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

### Dual Alias Configuration Required

Path aliases must be synced in BOTH [`svelte.config.js`](svelte.config.js:11) AND [`vite.config.ts`](vite.config.ts:14) for TypeScript, Svelte compiler, and Vitest to resolve consistently:

- `@/` → `src/`
- `@/ling` → `src/lib/ling` (i18n)
- `@/logr` → `src/lib/logr` (logging)
- `@/glob` → `src/lib/glob` (globalization)
- `@/actx` → `src/lib/actx` (audio context)
- `$uix` → `src/uix` (UI components)

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