2.6 KiB

Raw Permalink Blame History

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:

web/routes/uix/lib/COMPONENT_AUDIT_GUIDE.md — pre-flight audit + reference library matrix + architectural rules + anti-patterns
web/routes/uix/lib/DEMO_AUTHORING_GUIDE.md — locked demo template (6 tabs, stage, observer, snippets)
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

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 AND vite.config.ts 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 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 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

2.6 KiB Raw Permalink Blame History