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. docs/guides/component-audit.md — pre-flight audit + reference library matrix + architectural rules + anti-patterns
2. docs/guides/demo-authoring.md — the demo template (the copies under web/routes/uix/lib/ belong to the frozen tree; these are the canonical ones)
3. src/uix/eidos/components/README.md — eidos contract
4. docs/building-a-component.md — the one door: the phases and the guard for each

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/uix/morfo/compile.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 check:gate   # ...with the policy: src/ and scripts/ owe ZERO
npm run lint         # Check formatting with Prettier
npm run format       # Auto-format with Prettier
npm run gate         # Everything the pre-push hook runs (lint first, suite last)

The zones this runs over — and the frozen web/routes/ tree — are in docs/repository.md; the gate, the format policy and the doctrine for guards that read source text are in docs/testing-and-tooling.md.

Critical Architecture

One Alias Table

Path aliases live in ONE module, 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.

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)

The Layers and the Artifacts

src/uix/{morfo,soma,sema,eidos} are the layers; src/arts/* the runtime artifacts (Engine* / Active*, one per concern: prefs, motion, langs, dom, …), src/libs/* the zero-dependency helpers, src/svrs/* the server-authoritative engines. A service is created by a composition root only (createActiveUix / attachActiveUix, Soma.create, ActiveEidos.create). The layer map with the hard rules is CLAUDE.md → Architecture. The legacy ling / logr / glob / actx libraries under src/lib/ were removed in the UIX refactor and must not reappear.

Code Style

• Tabs for indentation, single quotes, no trailing commas, 100 char print width (.prettierrc; npm run lint is the first member of the gate)
• Comments in code are English. Some legacy Spanish comments remain — don't add new ones (CLAUDE.md → Code Style)