decantr 0.9.0

package/CHANGELOG.md

@@ -0,0 +1,255 @@
+# Changelog
+
+## 0.9.1 — Production Cleanup
+
+### Style System
+- **Addon architecture**: Only `auradecantism` ships as core builtin. 10 styles moved to `src/css/styles/addons/` — import individually via `decantr/styles/clean` + `registerStyle()`
+- **Plugin style wiring**: `mergePluginStyles()` added to theme-registry for plugin-contributed styles
+
+### New Atom Features
+- **Pseudo-class prefixes**: `_h:` (hover), `_f:` (focus), `_fv:` (focus-visible), `_a:` (active), `_fw:` (focus-within) — compose with ANY existing atom
+- **Responsive + pseudo**: `_sm:h:bgmuted` — breakpoint-wrapped pseudo-class atoms
+- **Ring utilities**: `_ring1`, `_ring2`, `_ring4`, `_ring0`, `_ringPrimary`, `_ringAccent`, `_ringBorder`
+- **Transition shortcuts**: `_transColors`, `_transOpacity`, `_transTransform`, `_transShadow`
+- **Prose atom**: `_prose` maps to `d-prose` class for nested rich-text typography (h1-h4, p, code, blockquote, etc.)
+- **Divide utilities**: `_divideY`, `_divideX` — child separator borders
+- **Text wrapping**: `_textBalance`, `_textPretty`
+- **Scroll behavior**: `_scrollSmooth`
+
+### Behaviors
+- **createScrollReveal()**: IntersectionObserver wrapper that adds `d-visible` class on viewport entry. Returns cleanup function for `onDestroy`.
+
+### Documentation Fixes
+- CLAUDE.md: Updated style list to 11 (1 core + 10 addons), documented opacity modifiers and arbitrary transitions
+- Docs essence synced to match actual 14 routes (was claiming 5-pattern homepage with only 1 implemented)
+- Workbench essence: added version field, verified sidebar data-driven from registry
+- Fixed markdown path resolution (relative → absolute) in tutorial and cookbook pages
+- Added explorer module exports to package.json
+- Reference docs: atoms.md documents all new atoms, llm-primer.md updated
+
+### Consolidation
+- Workbench integrated into docs site as `/workbench` route section
+- `de-card-grid`/`de-card-item` custom CSS replaced with framework atoms
+- docs/src/style.js: hardcoded pixel values replaced with design tokens
+
+## 0.9.0 — Release Candidate
+
+### Docs Site
+- Full documentation site at decantr.ai with nested routing (17 routes)
+- Markdown renderer (260 LOC) for tutorial and cookbook content
+- ShadCN-style component gallery with search, category filters, and detail views
+- Live component showcase carousel on landing page
+- Framework comparison table (decantr vs React vs Angular)
+- Sidebar layout with mobile hamburger, active link tracking
+- JSON-LD structured data, enhanced OpenGraph/Twitter meta tags
+- Explorer modules (icons, charts, tokens, atoms, patterns, archetypes, recipes, shells, tools) integrated into docs
+
+### Registry Enrichment
+- Icon groups (24) moved from workbench JS → `icons.json` registry
+- Chart groups (5) + type metadata (25) in new `chart-showcase.json`
+- Data subsection added to `foundations.json`
+- Component group categorization in `components.json` (form, layout, data, feedback, navigation, overlay, typography, chart)
+
+### CLI
+- `decantr doctor` — 8 health checks with colored pass/warn/fail output
+- Doctor accepts both `decantr` and `decantr` package names
+
+### Infrastructure
+- CI/CD: `ci.yml` (Node 20.x/22.x matrix), `docs-deploy.yml` (GitHub Pages), `release.yml` (tag → npm publish)
+- `tools/verify-pack.js` — npm package verification (expected files, sensitive leak detection, size reporting)
+- MIT LICENSE file
+- README: CI/npm/license badges, expanded CLI commands list
+
+### Playground
+- Ellafi Lending Dashboard validated end-to-end (validate, doctor, lint, a11y, build)
+- Playground README documenting validation checklist
+
+## Unreleased
+
+### Added
+- **SSR + Hydration** (`decantr/ssr`) — server-side rendering for SEO-dependent apps. Zero DOM dependencies at module level.
+  - `renderToString(component)` — renders component tree to HTML string in pure Node.js
+  - `renderToStream(component)` — streaming render via Web Streams API (Node 18+)
+  - `hydrate(root, component)` — walks existing SSR DOM, attaches signal bindings + event listeners without re-creating elements
+  - SSR context: `h()`, `text()`, `cond()`, `list()`, `css()` all work transparently in server environment
+- **Accessibility testing** (`decantr a11y`) — static analysis for 8 WCAG rules: button-label, input-label, img-alt, focus-visible, keyboard-handler, role-valid, heading-order, contrast-ratio. Zero dependencies. Also available via `decantr audit --a11y`.
+- **`decantr migrate` command** — automated migration for `decantr.essence.json` between versions. Supports `--dry-run` for preview, `--target` for specific version. Migrations: 0.5.0 (organs→tannins, anatomy→structure) and 0.6.0 (pattern consolidation to preset format).
+- **Starter templates** — `decantr init --template=<name>` with 5 templates: `saas-dashboard`, `ecommerce`, `portfolio`, `content-site`, `landing-page`. Each provides pre-filled essence, router setup, and page stubs.
+- **Archetype inheritance** — Archetypes now support `extends` field for inheriting pages, tannins, and skeletons from parent archetypes. Circular dependency detection and max depth (5) enforced. `financial-dashboard` updated to extend `saas-dashboard` as a reference example.
+- **Component-level HMR** — Dev server now sends targeted `hmr` messages for `src/pages/` and `src/components/` file changes instead of full-page reloads. Module-level state (signals, stores) is preserved across updates. Infrastructure files (`state/`, `css/`, `router/`, `app.js`, essence) still trigger full reload. HMR remount hook in `src/core/index.js` is gated behind `globalThis.__DECANTR_DEV__` for zero production cost.
+- **Auth reference tannin** (`decantr/tannins/auth`) — token-based authentication with reactive signals, persistent cross-tab token storage, auto-refresh on 401, and route guard helper.
+  - `createAuth(config)` — creates an auth instance with `user()`, `token()`, `isAuthenticated()`, `login()`, `logout()`, `refresh()`, `destroy()`
+  - `requireAuth(router, options)` — installs route guard that redirects unauthenticated users to login page
+  - Fetch middleware: auto-injects Bearer token, intercepts 401 → refresh → retry
+  - Token persistence via `createPersisted()` with cross-tab sync
+
+## v0.7.0 — Internationalization (2026-03-16)
+
+### Added
+- **i18n module** (`decantr/i18n`) — reactive internationalization built on Decantr signals and `Intl.PluralRules`. Zero external dependencies.
+  - `createI18n({ locale, messages, fallbackLocale })` — creates a reactive i18n instance
+  - `t(key, params?)` — translate with dot notation, `{param}` interpolation, and automatic pluralization via `_one`/`_other` suffixes
+  - `locale()` — signal getter for the current locale
+  - `setLocale(loc)` — reactively switch locales (all `t()` consumers auto-update)
+  - `setDirection('rtl' | 'ltr')` — set `dir` attribute on `<html>` for RTL languages
+  - `addMessages(locale, messages)` — deep-merge translations at runtime for lazy loading
+  - Fallback chain: current locale -> fallback locale -> raw key
+- **TypeScript declarations** for i18n (`types/i18n.d.ts`)
+- **Reference docs** (`reference/i18n.md`) — API, interpolation, pluralization rules, RTL setup, lazy loading patterns
+- **Test suite** (`test/i18n.test.js`) — comprehensive tests covering translation, dot notation, interpolation, pluralization, locale switching, fallback chain, direction setting, addMessages, edge cases, and reactivity
+
+### Changed
+- `package.json` — added `./i18n` export
+- `tools/dev-server.js` — added `decantr/i18n` import map entry
+- `tools/dts-gen.js` — added i18n declaration generator
+- `src/registry/index.json` — added `decantr/i18n` module entry
+- `CLAUDE.md` — added i18n import to Framework Imports section
+- `AGENTS.md` — added react-intl/vue-i18n/svelte-i18n equivalence row for `createI18n`
+
+## v0.6.0 — Architectural Audit & Pattern v2 (2026-03-16)
+
+### Breaking Changes
+- **Pattern v2 schema** — Patterns now support `presets` (named variants within a single file) and `default_preset`. Archetypes reference patterns as `{ "pattern": "hero", "preset": "image-overlay", "as": "recipe-hero" }` instead of separate files.
+- **13 domain-specific patterns removed** and consolidated into presets on generic patterns:
+  - `recipe-hero`, `cookbook-hero` → `hero` (presets: `image-overlay`, `image-overlay-compact`)
+  - `product-grid`, `recipe-card-grid`, `cookbook-grid`, `feature-grid` → `card-grid` (presets: `product`, `content`, `collection`, `icon`)
+  - `recipe-stats-bar` → `stats-bar`
+  - `recipe-ingredients` → `checklist-card`
+  - `recipe-instructions` → `steps-card`
+  - `nutrition-card` → `stat-card`
+  - `recipe-form-simple`, `recipe-form-chef` → `form-sections` (presets: `creation`, `structured`)
+  - `profile-header` → `detail-header` (preset: `profile`)
+- Pattern count: 49 → 41 (4 new generics + presets replace 13 domain-specific files)
+
+### Added
+- **Three-tier pattern architecture** — Tier 1 (structural patterns), Tier 2 (presets within patterns), Tier 3 (domain compositions in archetypes)
+- **Pattern Design Review Gate** — mandatory checkpoint between CLARIFY and DECANT stages to prevent pattern proliferation
+- **Plugin system** (`src/plugins/index.js`) — extend Decantr without forking via `plugins` config in `decantr.config.json`. Hooks: `onBuild`, `onDev`, `onGenerate`, `registerStyle`, `registerPattern`, `registerRecipe`
+- **`decantr lint` command** — code quality gates: atom validation, essence drift detection, inline style detection
+- **Error telemetry hooks** — `setErrorHandler(fn)` for ErrorBoundary integration with external error services
+- **Request middleware** — `queryClient.use(middleware)` chain for auth headers, logging, retry logic
+- **Cache invalidation API** — `queryClient.invalidateQueries('user.*')` glob-based query invalidation
+- **Route metadata** — `meta` field on route definitions, merged parent→child, accessible via `useRoute().meta`
+- **Bundle size budgets** — `build.sizeBudget` config with warnings for JS, CSS, total, and chunk size limits
+- **Essence versioning** — `version` field (semver) for tracking essence evolution
+- **Blend validation depth** — validates `at` breakpoints, `span` values, and span/cols consistency
+- **Package distribution** — `files` field and `publishConfig` in package.json for clean npm publishing
+
+### Changed
+- Archetype schemas updated to v2 (`ecommerce.json`, `recipe-community.json`) with preset references
+- Pattern index updated to v2 format with `presets` arrays per pattern
+- `tools/generate.js` — `resolvePatternRef()` handles both v1 strings and v2 `{pattern, preset, as}` objects
+- `test/decantation/engine.js` — `resolveBlend()` and `validateBlend()` handle v2 format
+- `cli/commands/validate.js` — validates preset existence against pattern index
+- `tools/figma-patterns.js` — preset-aware `patternToFigmaFrame()` and archetype composition
+- `workbench/src/explorer/patterns.js` — displays presets as expandable sub-items within pattern detail
+- All reference docs updated for v2 pattern architecture
+
+## v0.5.1 — Recipe Community Archetype (2026-03-16)
+
+### Added
+- **New archetype: `recipe-community`** — AI-powered recipe sharing platform with 12 pages (home, feed, recipe detail, create/edit, AI generate, chef chat, cookbooks, profile, auth), 8 tannins, and 3 skeletons
+- **14 new patterns** (now consolidated into presets in v0.6.0)
+- **New pattern category: Social** — groups community and social cooking patterns in the workbench explorer
+- Registry: 35 → 49 patterns, 6 → 7 archetypes
+
+## v0.5.0 — Greenfield Component Rebuild (2026-03-13)
+
+### Breaking Changes
+- **`createFormField()` wrapper class** renamed from `d-field` → `d-form-field`. CSS classes `.d-field-label`, `.d-field-help`, `.d-field-error`, `.d-field-required` → `.d-form-field-*`. The `.d-field` class is now reserved for field visual styling (border/bg/focus).
+- **`createFormField()` return value** changed from `HTMLElement` to `{ wrapper, setError, setSuccess, destroy }`.
+- **ColorPicker** now uses OKLCH color space instead of HSV. Saturation panel is now a Lightness/Chroma plane. API unchanged (hex in/out).
+- All 14 field components now apply `.d-field` class on their bordered container. Consumers querying DOM structure may need updates.
+
+### Added
+- **New file: `_primitives.js`** — shared rendering primitives: `renderCalendar()`, `renderTimeColumns()`, `renderMenuItems()`, `applyFieldState()`, `createFieldOverlay()`, `hexToOklch()`, `oklchToHex()`.
+- **Unified field API** on all 14 field components: `variant` (outlined/filled/ghost), `success`, `loading`, `label`, `help`, `required`, `aria-label`.
+- **`applyFieldState()`** — single source of truth for reactive `data-error`, `data-success`, `data-disabled`, variant class, size class on `.d-field` elements.
+- **`createFieldOverlay()`** — thin wrapper around `createOverlay()` with field-standard defaults (portal, matchWidth, closeOnEscape/Outside).
+- **Error/aria-label** support added to Checkbox, Switch, InputOTP, RadioGroup.
+- **Keyboard navigation** added to Accordion (ArrowUp/Down/Home/End between triggers).
+- **`disabled` prop** added to Segmented.
+- **`aria-checked`** wired on Switch.
+- 58 new component rebuild tests (425 total).
+
+### Changed
+- All 23 interactive components migrated from `h()` to `tags` proxy API (~25% fewer markup tokens).
+- All overlay components (Select, Combobox, DatePicker, TimePicker, Cascader, TreeSelect, Mentions, ColorPicker) now use `createFieldOverlay()` + portal positioning.
+- Combobox: manual click-outside replaced with `createOverlay()`.
+- Mentions: blur timeout replaced with `createOverlay()`.
+- RadioGroup: manual arrow-key nav replaced with `createRovingTabindex()`.
+- Slider: manual pointer handlers replaced with `createDrag()` from `_behaviors.js`.
+- DatePicker/DateRangePicker: calendar rendering deduplicated via `renderCalendar()`.
+- TimePicker/TimeRangePicker: column rendering deduplicated via `renderTimeColumns()`.
+- ContextMenu: item rendering deduplicated via `renderMenuItems()`.
+- All overlay components now wire `onDestroy()` for cleanup.
+- Segmented now wires `onDestroy()` for roving tabindex cleanup.
+- Net: ~555 fewer LOC across 23 components.
+
+## v0.4.1 — Full Design Token Sweep (2026-03-12)
+
+### Added
+- **Field tokens** (15 tokens): `--d-field-bg`, `--d-field-border`, `--d-field-border-focus`, `--d-field-border-error`, `--d-field-ring`, `--d-field-radius`, `--d-field-placeholder`, and 8 more state variants
+- **Interactive state tokens** (9 tokens): `--d-item-hover-bg`, `--d-selected-bg/fg/border`, `--d-disabled-opacity`, `--d-disabled-opacity-soft`, `--d-icon-muted`, `--d-icon-subtle`
+- **Overlay tokens**: `--d-overlay-light`, `--d-overlay-heavy` — three intensity levels
+- **Table tokens**: `--d-table-stripe-bg`, `--d-table-header-bg`, `--d-table-hover-bg`, `--d-table-selected-bg`
+- **Semantic motion tokens**: `--d-motion-enter`, `--d-motion-exit`, `--d-motion-state`
+- **Layout tokens**: `--d-prose-width`, `--d-sidebar-width`, `--d-drawer-width`, `--d-sheet-max-h`, `--d-content-width-*`
+- **Typography semantic roles**: `--d-text-helper`, `--d-text-error`, `--d-ls-tight`, `--d-ls-wide`
+- **Chart UI tokens**: `--d-chart-tooltip-shadow`, `--d-chart-axis-opacity`, `--d-chart-grid-opacity`, `--d-chart-legend-gap`
+- **Glass blur tokens**: `--d-glass-blur-sm`, `--d-glass-blur`, `--d-glass-blur-lg`
+- **Scrollbar tokens**: `--d-scrollbar-w`, `--d-scrollbar-track`, `--d-scrollbar-thumb`, `--d-scrollbar-thumb-hover`
+- **Skeleton tokens**: `--d-skeleton-bg`, `--d-skeleton-shine`
+- **Focus ring inset**: `--d-focus-ring-offset-inset` — replaces inline `calc()` in every `outline-offset`
+- `.d-field` base CSS class with hover, focus, error, success, disabled, readonly states
+- `.d-field-outlined`, `.d-field-filled`, `.d-field-ghost` variant modifiers
+- New atoms: `_field`, `_fieldFilled`, `_fieldGhost`, `_hoverBg`, `_activeBg`, `_selectedBg`, `_selectedFg`, `_proseWidth`, `_disabled`
+- Per-style field token overrides for all 5 styles
+- 28 new tests for token existence + cross-style verification (367 total)
+
+### Changed
+- ~44 hardcoded `opacity` values in `_base.js` replaced with semantic tokens (`--d-disabled-opacity`, `--d-icon-muted`, etc.)
+- ~13 hardcoded `background:var(--d-surface-1)` on hover rules replaced with `var(--d-item-hover-bg)`
+- ~11 `outline-offset:calc(...)` replaced with `var(--d-focus-ring-offset-inset)`
+- Selected row/range backgrounds now use `var(--d-selected-bg)` instead of `var(--d-primary-subtle)`
+- Default scrollbar CSS now uses tokens (overridable per style)
+- Token count: ~280 → ~340 CSS custom properties
+- Contrast validation: added field-placeholder and selected-fg pairs
+
+### Documentation
+- `reference/tokens.md`: 11 new sections (field, interactive state, overlay, table, scrollbar, skeleton, layout, chart UI, glass blur, semantic motion)
+- `reference/atoms.md`: 4 new sections (field, interactive state, semantic opacity, layout atoms)
+- `src/registry/css.json`: 7 new token family entries
+- `CLAUDE.md`: new FIELD checklist item, 2 new anti-patterns, code standard #13
+
+## v0.4.0 — Enterprise Upgrade
+
+### Breaking Changes
+
+- **Blocks removed.** `src/blocks/` (21 files) deleted. Use patterns (`registry/patterns/`) instead.
+- **Kits removed.** `src/kit/` (16 files) deleted. Use patterns and archetypes instead.
+- **Terminology renames.** "Anatomy" → "Structure", "Organs" → "Tannins".
+- **Legacy color atoms removed.** `_fg0`–`_fg9`, `_bg0`–`_bg9`, `_bc0`–`_bc9`, `legacyColorMap()`, `--c0`–`--c9` variables all removed.
+
+### Added
+
+- **Core:** ErrorBoundary, Portal, Suspense, Transition, forwardRef; `mount()` returns unmount function
+- **State:** createContext/provide/inject, createSelector, createDeferred, createHistory, useLocalStorage
+- **Router:** Nested routes, route guards (beforeEach/afterEach), lazy loading, query params, active links, scroll restoration, named routes, URL validation
+- **Form system:** `decantr/form` module — createForm, validators, fieldArray, useFormField
+- **DataTable:** Sort, paginate, select, pin, resize, virtual scroll, edit, expand, filter, export
+- **New components:** DateRangePicker, TimeRangePicker, RangeSlider, TreeSelect, AvatarGroup, NavigationMenu, Splitter, BackTop, VisuallyHidden
+- **New style:** Command Center (`command-center`) — HUD/radar visual language with recipe system
+- **Accessibility:** WCAG AA contrast validation in derive(), RTL logical property atoms
+- **Security:** Router URL validation (rejects javascript:, data:, absolute URLs), `sanitize()` utility
+- **Build tooling:** Tree shaking, code splitting, source maps, incremental builds, CSS purging, Brotli reporting, bundle analyzer
+- **TypeScript declarations:** `tools/dts-gen.js` generates `.d.ts` for all 15 modules
+- **Registry:** 49 patterns, 7 archetypes, recipe system, architect domain files
+- **Workbench:** Complete rewrite as "Decantation Explorer" — 7-layer navigation, token inspector, global search
+- **Decantation Process:** Full POUR→SETTLE→CLARIFY→DECANT→SERVE→AGE methodology with essence files
+- **Reference docs:** 14 deep-dive reference documents for all subsystems
+
+### Fixed
+
+- Component lifecycle cleanup: Modal, Select, Dropdown, Combobox, ContextMenu, Tooltip, Slider, Image, DataTable now properly clean up via `onDestroy`
+- CSS runtime performance: `inject()`/`injectResponsive()` buffer rules and flush via microtask

package/CLAUDE.md

@@ -0,0 +1,178 @@
+# /tmp/decantr-baseline-test
+
+Built with [decantr](https://decantr.ai) v0.4.2 — AI-first web framework.
+
+## Project Structure
+
+- `src/app.js` — Entry point, mounts the app to `#app`
+- `src/pages/` — Route page components
+- `src/components/` — Project-specific reusable components
+- `public/index.html` — HTML shell with theme CSS variables
+- `decantr.config.json` — Project configuration
+- `decantr.essence.json` — Project DNA (generated during Decantation Process)
+- `AGENTS.md` — Framework translation layer (read this for API equivalences)
+- `reference/llm-primer.md` — Imports, atoms, components, pattern snippets
+- `reference/spatial-guidelines.md` — Spacing rules, density zones, Clarity profiles
+- `reference/atoms.md` — Valid atom class names (always check before using `_` atoms)
+- `reference/shells.md` — Shell layout presets, config schema, nav states, grid area diagrams
+
+## The Decantation Process
+
+Follow this process for ALL new projects and major feature additions:
+
+### Stage 1: POUR — User expresses intent in natural language
+### Stage 2: SETTLE — Decompose into five layers:
+- **Terroir**: Domain archetype → read `node_modules/decantr/src/registry/archetypes/`
+- **Vintage**: Style + mode + recipe → read `node_modules/decantr/src/registry/recipe-*.json`
+- **Character**: Brand personality traits (e.g. "tactical", "minimal", "playful")
+- **Structure**: Page/view map with skeleton assignments
+- **Tannins**: Functional systems (auth, search, payments, etc.)
+### Stage 3: CLARIFY — Write `decantr.essence.json` and confirm with user
+### Stage 4: DECANT — Resolve each page's Blend (spatial arrangement)
+Read the archetype's `default_blend` for each page. Copy into the Essence's `blend` array, then customize.
+Derive Clarity profile from Character traits → `reference/spatial-guidelines.md` §17. Apply density-appropriate gaps to each page's `surface` atoms.
+
+**Blend format**: Each `blend` is an ordered array of rows:
+- `"pattern-id"` — full-width pattern row (default preset)
+- `{ "pattern": "hero", "preset": "image-overlay", "as": "recipe-hero" }` — pattern with preset + local alias
+- `{ "cols": ["a", "b"], "at": "lg" }` — equal-width side-by-side, collapse below `lg`
+- `{ "cols": ["a", "b"], "span": { "a": 3 }, "at": "md" }` — weighted columns (a=3fr, b=1fr)
+
+**Pattern Presets (v2)**: Patterns support named presets — structural variants within a single file.
+- `hero` has presets: `landing`, `image-overlay`, `image-overlay-compact`
+- `card-grid` has presets: `product`, `content`, `collection`, `icon`
+- `form-sections` has presets: `settings`, `creation`, `structured`
+- `detail-header` has presets: `standard`, `profile`
+Before creating a new pattern file, check if it can be a preset on an existing pattern.
+
+Optional `surface` on each structure entry sets page container atoms (default: `_flex _col _gap4 _p4 _overflow[auto] _flex1`).
+
+### Stage 5: SERVE — Generate code from Blend specs
+For each page, read its `blend` array and apply:
+1. Create page container with `surface` atoms
+2. String rows → full-width pattern (use pattern's `default_blend.atoms`)
+3. `{ cols }` rows → `_grid _gc{N} _gap4` wrapper, collapse below `at` breakpoint
+4. `{ cols, span }` rows → `_gc{total}` grid, each pattern gets `_span{weight}`
+5. Apply recipe wrappers per `recipe_overrides`
+
+### Ongoing: AGE — Read Essence before every change. Guard against drift.
+
+### Cork Rules (Anti-Drift)
+Before writing ANY code, read `decantr.essence.json`. Verify:
+1. Style matches the Vintage. Do not switch styles.
+2. Page exists in the Structure. If new, add it to the Essence first.
+3. Layout follows the page's Blend. Do not freestyle spatial arrangement.
+4. Composition follows the active Recipe. Do not freestyle decoration.
+5. Spacing follows the Clarity profile derived from Character → `reference/spatial-guidelines.md` §17. Do not default to `_gap4`/`_p4` everywhere.
+If a request conflicts with the Essence, flag the conflict and ask for confirmation.
+
+## Essence Schema
+
+You MUST create `decantr.essence.json` during CLARIFY. Do NOT proceed to DECANT without it.
+
+**Simple (single domain):**
+```json
+{
+  "version": "1.0.0",
+  "terroir": "saas-dashboard",
+  "vintage": { "style": "command-center", "mode": "dark", "recipe": "command-center", "shape": "sharp" },
+  "character": ["tactical", "data-dense"],
+  "vessel": { "type": "spa", "routing": "hash" },
+  "structure": [
+    { "id": "overview", "skeleton": "sidebar-main", "blend": ["kpi-grid", "data-table"] },
+    { "id": "catalog", "skeleton": "top-nav-main", "blend": [
+      { "pattern": "card-grid", "preset": "product", "as": "product-grid" }
+    ]}
+  ],
+  "tannins": ["auth", "realtime-data"],
+  "cork": { "enforce_style": true, "enforce_recipe": true }
+}
+```
+
+**Sectioned (multi-domain):**
+```json
+{
+  "vessel": { "type": "spa", "routing": "hash" },
+  "character": ["professional", "technical"],
+  "sections": [
+    {
+      "id": "brand",
+      "path": "/",
+      "terroir": "portfolio",
+      "vintage": { "style": "glassmorphism", "mode": "dark" },
+      "structure": [{ "id": "home", "skeleton": "full-bleed", "blend": ["hero", "cta-section"] }],
+      "tannins": ["analytics"]
+    }
+  ],
+  "shared_tannins": ["auth"],
+  "cork": { "enforce_style": true, "enforce_sections": true }
+}
+```
+
+## Framework Imports
+
+```js
+import { tags } from 'decantr/tags';
+import { h, text, cond, list, mount, onMount, onDestroy } from 'decantr/core';
+import { createSignal, createEffect, createMemo, createStore, batch, createRoot, on } from 'decantr/state';
+import { createQuery, createMutation, queryClient, createEntityStore, createURLSignal, createPersisted } from 'decantr/data';
+import { createRouter, link, navigate, useRoute } from 'decantr/router';
+import { css, setStyle, setMode } from 'decantr/css';
+import { Button, Input, Card, Modal, Tabs, ... } from 'decantr/components';
+import { createI18n } from 'decantr/i18n';
+import { createAuth, requireAuth } from 'decantr/tannins/auth';
+import { renderToString, renderToStream, hydrate } from 'decantr/ssr';
+```
+
+## Styles
+
+**Core** (ships with framework, no extra import): `auradecantism` (default)
+
+**Add-on styles** (import individually via `import { clean } from 'decantr/styles/clean'` then `registerStyle(clean)`):
+`clean`, `retro`, `glassmorphism`, `command-center`, `bioluminescent`, `clay`, `dopamine`, `editorial`, `liquid-glass`, `prismatic`
+
+Modes: `light`, `dark`, `auto`
+Shapes: `sharp`, `rounded`, `pill`
+
+### Atom Capabilities
+- **Arbitrary transitions**: `_trans[color_0.15s_ease]` — underscores become spaces
+- **Opacity modifiers**: Work on all semantic color atoms — `_bgprimary/50`, `_bcborder/80`, `_fgmuted/60`
+- **Arbitrary values**: `_bg[#1a1a2e]`, `_w[calc(100%-2rem)]`, `_p[clamp(1rem,3vw,2rem)]`
+
+## Registry
+
+- `node_modules/decantr/src/registry/index.json` — Full API catalog
+- `node_modules/decantr/src/registry/components.json` — Component props/types
+- `node_modules/decantr/src/registry/archetypes/` — Domain archetypes (v2: `{pattern, preset, as}` references)
+- `node_modules/decantr/src/registry/patterns/` — Experience patterns (v2: presets within files)
+- `node_modules/decantr/src/registry/recipe-*.json` — Visual language recipes
+
+## Build Configuration
+
+In `decantr.config.json`:
+```json
+{
+  "build": {
+    "sizeBudget": {
+      "jsRaw": 102400,
+      "jsBrotli": 25600,
+      "cssRaw": 51200,
+      "totalBrotli": 51200,
+      "chunkRaw": 51200
+    }
+  },
+  "plugins": [
+    "./plugins/my-plugin.js",
+    ["@acme/decantr-plugin", { "option": true }]
+  ]
+}
+```
+See `reference/plugins.md` for plugin API documentation.
+
+## Commands
+
+- `npx decantr dev` — Dev server with hot reload
+- `npx decantr build` — Production build to `dist/`
+- `npx decantr test` — Run tests
+- `npx decantr validate` — Validate `decantr.essence.json`
+

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Aimi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.