# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Build/Test Commands

```bash
npm run dev          # Start dev server
npm run build        # Production build (static site via adapter-static)
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
```

## Code Style

- Tabs for indentation, single quotes, no trailing commas, 100 char print width (Prettier)
- Spanish comments in code are acceptable
- Svelte 5 runes mode enforced globally (`svelte.config.js` `dynamicCompileOptions`)
- DOM event handlers: lowercase (`onclick`, `onfocus`). User callbacks: camelCase (`onComplete`, `onInteractOutside`)
- State fields: `$state()` without `#`. Derived: `readonly x = $derived.by(...)`
- Boolean attrs: always use helpers (`boolToTrueOrUndef`, `boolToEmptyStrOrUndef`, `boolToStr`) — never ternaries

## Path Aliases

Aliases must be synced in BOTH `svelte.config.js` AND `vite.config.ts`:

| Alias                   | Target                                                 |
| ----------------------- | ------------------------------------------------------ |
| `@/`                    | `src/`                                                 |
| `@/ling`                | `src/lib/ling` (i18n)                                  |
| `@/logr`                | `src/lib/logr` (logging)                               |
| `@/glob`                | `src/lib/glob` (legacy; do not use for new code)       |
| `@/actx`                | `src/lib/actx` (app context)                           |
| `@/uiux`                | `src/lib/uiux`                                         |
| `$uix`                  | `src/uix` (UI layers)                                  |
| `$terra`                | `src/uix/terra` (headless primitives)                  |
| `$terra/utils`          | `src/uix/terra/utils/sound.svelte.ts`                  |
| `$terra/system`         | `src/uix/terra/system/exports.ts`                      |
| `$terra/external/dates` | `src/uix/terra/external/dates/sound.svelte.ts`         |
| `$lib`                  | `src/lib`                                              |
| `$lib/util/dias`        | `src/lib/util/dias` (date/time library — canonical)    |

## Vitest Two-Project Structure

`vite.config.ts` defines two test projects:

- **client**: Browser tests via Playwright for `*.svelte.{test,spec}.{js,ts}`
- **server**: Node environment for `*.{test,spec}.{js,ts}` (excludes svelte tests)

## Architecture: Three-Layer UI System

```
terra  → headless primitives: behavior, accessibility, data-* contracts, context
air    → visual layer on top of terra: tokens, themes, recipes, styled components
glob   → domain logic: dates, numbers, currency, units, locale
```

The dependency flows one way: `air` → `terra`. Terra never imports from air.

### terra (`src/uix/terra/`)

Headless primitive library. Each component follows `Element.SubElement` pattern (`Dialog.Root`, `Dialog.Trigger`, `Dialog.Content`).

**Key patterns:**

- Thin `.svelte` wrappers + logic in `*.svelte.ts` State classes
- State classes use `static create()` for context registration, `createComposed()` for internal composition without context
- Reactive system: `Active<T>`, `State<T>`, `readableActive()`, `writableActive()` — values travel as boxes with `.current`
- Context via `createTerraContext()` (wraps runed's `Context`)
- Props merging: `mergeProps(restProps, state.props)` in every wrapper
- `data-*` attrs are formal public API, validated via `assertDataContract()` against `utils/contracts.ts`
- `child` snippet replaces the rendered node; `children` fills the interior

**Structure:**

- `[component]/components/` — Svelte wrappers
- `[component]/types.ts` — public props
- `[component]/*.svelte.ts` — State classes
- `[component]/exports.ts` + `sound.svelte.ts` — barrel exports
- `layers/` — shared infra (portal, floating, presence, focus-scope, dismissible, escape, scroll)
- `dom/` — browser-dependent utils (focus, roving focus, arrow navigation)
- `utils/` — pure helpers (state system, attrs, merge-props, events, keyboard, css, datetime)
- `system/` — `TerraConfig` for cross-cutting services (translator, formatters, logger, dir, portalTo)
- `external/dates/` — adapter boundary for date library

**Import rules within terra:** use `$terra/utils` or relative paths internally, never `$uix/terra`.

### air (`src/uix/air/`)

Visual layer built on terra. Consumes terra's public anatomy and `data-*` attrs — never internal classes or incidental DOM structure.

**Three-level token system:**

1. **Primitive tokens** (`tokens/primitive.css`) — absolute scale values, never used directly by components
2. **Semantic tokens** (`tokens/semantic.css`) — theme-aware, switch via `[data-theme]`
3. **Component tokens** (`tokens/components/*.css`) — scoped per component (`--air-button-*`), the only level component CSS writes

**Token naming:**

- Public: `--air-{component}-*` (stable, overridable)
- Private: `--_air-{component}-*` (implementation detail, may change)

**Contracts** (`contracts/`):

- `contract.css` — minimum semantic tokens any theme must implement
- `contract-categorical.css` — optional categorical color families
- `contract-primitives.css` — optional advanced 12-step scales
- `contracts/components/*.css` — per-component public token API

**CSS rules:**

- Tokens and `data-*` selectors must be global CSS (imported `.css` files), not `<style scoped>`
- Svelte scoped styles only for properties that don't depend on `data-*` or terra internals
- Components respond to terra states purely via `data-*` selectors: `[data-disabled]`, `[data-state='open']`, etc.
- Theme activation via `data-theme` attribute on any DOM container (supports nesting)
- Variant dimensions are orthogonal: `size` → dimensions, `variant` → appearance, `state` → transversal overrides

**Structure:**

- `components/` — styled wrappers over terra primitives
- `tokens/` — token implementation (primitive, semantic, per-component)
- `contracts/` — public token interfaces for theme authors
- `themes/` — theme implementations (base light/dark)
- `icons/` — icon system (`Icon` + per-icon components in `icons/lib/`)

### Internal Libraries (`src/lib/`)

- `ling` — i18n system (factory: `createLing`)
- `logr` — logging (factory: `createLogr`, depends on `ling`)
- `ext/` — App-layer reactive services: `app`, `dates`, `lang`, `money`, `nums`, `presentation`, `units`
- `util/dias` — canonical date/time library. Single public door at `$lib/util/dias`. `_vendor/` holds the internal implementation (Adobe Apache 2.0 vendored code) and MUST NOT be imported by consumers
- `glob` — legacy (pre-App-layer); do not use for new code
- `actx` — app context
- `vice` — app-level utilities

**Dates — canonical layout:**

- Value types (`CalendarDate`, `CalendarDateTime`, `Time`, `ZonedDateTime`), 9 calendars, queries, operations, parsing: all re-exported from `$lib/util/dias`
- All date-related `Intl` (`DateFormatter`, cache, `resolveDateOrder`, `resolveHourCycle`, placeholders, defaults) lives in `$lib/util/dias/format.ts`
- `ext/dates` is a thin reactive wrapper for App-level preferences (dateOrder, hourCycle) that delegates formatting to `dias`
- `HourCycle` is canonically numeric — `12 | 24` — matching `Intl.DateTimeFormat`'s `hour12` resolved option. Never `'12h' | '24h'`
- Soma consumes via `$soma/external/dates`; terra via `$terra/external/dates`. Both re-export from `dias`. Components never import `dias` directly

**Number formatting:** use `createNumr` from the App layer, NEVER raw `Intl.NumberFormat`.

### soma (`src/uix/soma/`)

Headless component library. Follows terra's architecture exactly — same patterns, same conventions. Uses `$soma` alias.

**Key patterns (must match terra):**

- Child providers reference parent as `provider`, NEVER `root`
- **The root export is always `Provider`, never `Root`**. Consumer writes `<Dialog.Provider>`, `<Calendar.Provider>`. `createAttrs` still uses the part name `'root'` internally — that is the DOM attribute part, not the export
- **Data-attr naming is canonical**: `data-{component}` (root) and `data-{component}-{part}` (sub-parts), emitted by `createAttrs`. **Never** `data-soma-*`. QuerySelectors, CSS selectors, README tables, and inline strings must all match exactly what `createAttrs` writes on the DOM — the contract validator does NOT check this (only enum values)
- `onChange` callbacks go in `writableActive` setter in the `.svelte` wrapper, NOT in provider Opts
- Translations: idlangref constants (`#?components.xxx.yyy|Fallback`) defined in the component's `langs.ts`. Root-level entries live in `src/uix/soma/core/langs.ts` under `components.{kebab-name}`. Providers call `soma?.langs.ts(IDLANGREF)` — no `resolveSomaTranslationPath` wrapper
- Props defined ONCE in `types.ts` (consumer API). Provider Opts only has reactive wrappers + internal fields
- `Soma.get()` returns the Soma config from context. `Soma.require()` throws when missing
- Test pages use shared layout at `src/routes/test/soma/+layout.svelte` with real `createLangs()` + `createPresentation()` + `App.create()`

**Structure:** mirrors terra exactly:

- `[component]/components/` — Svelte wrappers
- `[component]/types.ts` — public props with JSDoc
- `[component]/*-provider.svelte.ts` — Provider classes
- `[component]/exports.ts` + `index.ts` — barrel exports
- `core/` — Soma class, translator adapter, prop-resolvers, formatters
- `provider/` — base Provider class, context utility
- `layers/` — shared infra (floating, presence, focus-scope, dismissal, scroll-lock)

**Import rules within soma:** use `$soma/` alias paths, never relative paths across component boundaries.

### Test Pages

Component demos live in `src/routes/test/`. Each terra/air/soma component should have a test page demonstrating its states and variants.

Soma test pages share a layout at `src/routes/test/soma/+layout.svelte` that provides:

- Real ling instance with soma translations via `extendSomaTranslationModule`
- `createSomaTranslator` adapter connecting to ling
- Locale/dir switcher in a sticky bar
- `<Soma>` wrapper for all children

Test pages should NOT create their own `<Soma>` or translator — use the layout's.

## TerraConfig / Soma Integration

```svelte
<!-- Terra -->
<TerraConfig {translator} {dateTimeFormatter}>
	<Dialog.Root />
</TerraConfig>

<!-- Soma -->
<Soma {translator} {presentation}>
	<Dialog.Provider />
</Soma>
```

Priority chain for resolved props: explicit component prop → config context value → internal fallback. Both support nesting (child overrides parent partially).

## Key Conventions

- When creating terra components: follow the checklist in `src/uix/terra/README.md` §21
- When creating soma components: follow the full checklist in `src/uix/soma/COMPONENT_GUIDE.md` (rules A1–A37, 40 checklist items). Walk every item explicitly before reporting done — this is mandatory, not optional. Compare features against ark-ui, bits-ui, radix-ui, react-aria and document the gap table in the component's README. Run `npm run perm:check` (permutation runner) before shipping; instrument the demo with `data-perm-step="N"` annotations for every distinct state transition.
- When reading existing modules: start with `exports.ts` → `types.ts` → root `.svelte` → `*-provider.svelte.ts` → child wrappers → test page → README
- `$bindable()` without fallback when parent might pass `undefined`; apply defaults via coalescing (see `src/uix/terra/README.md` §13.1)
- Components that use Portal: consumer must manage `z-index` explicitly (layers don't impose z-indices)
- Every soma component ships with its own `README.md` following the format of `dialog/README.md` — anatomy, parts, props, ARIA, data-attrs, keyboard, comparison table, example

## Critical Rules

- **NEVER modify terra source code.** Terra is the reference architecture. Soma copies its patterns.
- **NEVER delete files without explicit instruction** ("delete", "remove", "borra", "elimina"). If ambiguous, ASK first. Reading costs nothing, deleting can be irreversible.
- **NEVER create fake translators** in test pages. Use real ling instances with `createSomaTranslator` + `extendSomaTranslationModule`.
- **READ before acting.** When told to read a file, read it. Don't interpret "léete" as "eléte".
- **Verify before reporting done.** Run `npm run check`, test the UI in the browser. `npm run smoke` and `npx tsx scripts/morfo-check.ts` must both be green — smoke proves 200 OK, morfo-check proves the DOM matches the morfo contract and catches `effect_update_depth_exceeded` (it shows up as "Execution context was destroyed" on the affected route — see COMPONENT_GUIDE A35).
- Soma audits: the two most recent are `src/uix/soma/soma-audit-2026-04-20.md` and `soma-audit-2026-04-21.md`. All their findings are resolved. Older audits (`AUDIT_1.md`, `codex_audit.md`) are historical. Read the latest audit before making architectural changes.
- Morfo layer: part naming is `kebab: 'provider'` for the root part (never `'root'`). `createAttrs` still emits `data-{component}` for it. See `src/uix/morfo/README.md`.




Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.

**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.

## 1. Think Before Coding

**Don't assume. Don't hide confusion. Surface tradeoffs.**

Before implementing:
- State your assumptions explicitly. If uncertain, ask.
- If multiple interpretations exist, present them - don't pick silently.
- If a simpler approach exists, say so. Push back when warranted.
- If something is unclear, stop. Name what's confusing. Ask.

## 2. Simplicity First

**Minimum code that solves the problem. Nothing speculative.**

- No features beyond what was asked.
- No abstractions for single-use code.
- No "flexibility" or "configurability" that wasn't requested.
- No error handling for impossible scenarios.
- If you write 200 lines and it could be 50, rewrite it.

Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.

## 3. Surgical Changes

**Touch only what you must. Clean up only your own mess.**

When editing existing code:
- Don't "improve" adjacent code, comments, or formatting.
- Don't refactor things that aren't broken.
- Match existing style, even if you'd do it differently.
- If you notice unrelated dead code, mention it - don't delete it.

When your changes create orphans:
- Remove imports/variables/functions that YOUR changes made unused.
- Don't remove pre-existing dead code unless asked.

The test: Every changed line should trace directly to the user's request.

## 4. Goal-Driven Execution

**Define success criteria. Loop until verified.**

Transform tasks into verifiable goals:
- "Add validation" → "Write tests for invalid inputs, then make them pass"
- "Fix the bug" → "Write a test that reproduces it, then make it pass"
- "Refactor X" → "Ensure tests pass before and after"

For multi-step tasks, state a brief plan:
```
1. [Step] → verify: [check]
2. [Step] → verify: [check]
3. [Step] → verify: [check]
```

Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.

---

**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.