decantr 0.9.0

package/src/registry/recipe-clean.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "https://decantr.ai/schemas/recipe.v1.json",
+  "id": "clean",
+  "name": "Clean",
+  "style": "clean",
+  "mode": "light",
+  "description": "Professional, understated visual language. Subtle shadows, rounded corners, thin borders, smooth motion. No gradients, no glass, no glow. Closest to the shadcn/Tailwind aesthetic — universally appropriate.",
+  "setup": "import { setStyle, setMode } from 'decantr/css';\nsetStyle('clean');\nsetMode('light');",
+  "decorators": {
+    "cl-card": "Clean card with subtle shadow and rounded corners. Standard elevated container.",
+    "cl-divider": "Thin border divider with muted color. Use between sections.",
+    "cl-section": "Padded section wrapper with optional muted background.",
+    "cl-muted-bg": "Soft muted background for contrast sections. Apply to alternating page sections.",
+    "cl-badge-dot": "Small status dot before badge text. Minimal status indicator.",
+    "cl-subtle-hover": "Smooth hover background transition. For list items and nav links."
+  },
+  "compositions": {
+    "panel": {
+      "description": "Clean panel with shadow and rounded corners.",
+      "example": "const { div, span } = tags;\ndiv({ class: css('_b1 _r4 _shadow _bgbg') },\n  div({ class: css('_flex _aic _jcsb _px4 _py3 _borderB') },\n    span({ class: css('_textsm _bold') }, 'Panel Title')\n  ),\n  div({ class: css('_p4') },\n    // content here\n  )\n)"
+    },
+    "card": {
+      "wraps": "Card",
+      "description": "Standard card with subtle shadow. No extra decoration needed — clean style tokens handle the look.",
+      "example": "Card({},\n  Card.Header({},\n    span({ class: css('_heading5') }, 'Feature')\n  ),\n  Card.Body({},\n    p({ class: css('_fgmuted _textsm') }, 'Description text here')\n  )\n)"
+    },
+    "kpi": {
+      "wraps": "Statistic",
+      "description": "KPI metric in a simple bordered card.",
+      "example": "const { div } = tags;\ndiv({ class: css('_b1 _r4 _p4') },\n  Statistic({\n    label: 'Total Revenue',\n    value: 2450000,\n    prefix: '$',\n    trend: 'up',\n    trendValue: '+18.2%'\n  })\n)"
+    },
+    "table": {
+      "wraps": "DataTable",
+      "description": "DataTable in a bordered container with clean header.",
+      "example": "const { div, span } = tags;\ndiv({ class: css('_b1 _r4 _overflow[hidden]') },\n  div({ class: css('_flex _aic _jcsb _px4 _py3 _borderB') },\n    span({ class: css('_heading5') }, 'Users'),\n    span({ class: css('_textsm _fgmuted') }, '1,248 total')\n  ),\n  DataTable({ columns, data, sortable: true, paginate: true })\n)"
+    },
+    "form": {
+      "description": "Form in a card with clean layout.",
+      "example": "const { div, h2 } = tags;\nCard({ class: css('_mw[480px]') },\n  Card.Header({},\n    h2({ class: css('_heading4') }, 'Sign In')\n  ),\n  Card.Body({ class: css('_flex _col _gap3') },\n    Input({ label: 'Email', type: 'email' }),\n    Input({ label: 'Password', type: 'password' }),\n    Button({ variant: 'primary', class: css('_wfull') }, 'Continue')\n  )\n)"
+    },
+    "sidebar": {
+      "description": "Clean sidebar with muted background and simple nav items.",
+      "example": "const { aside, nav, span } = tags;\naside({ class: css('_flex _col _h[100vh] _w[240px] _borderR _bgmuted _p3') },\n  span({ class: css('_heading5 _mb6 _px3') }, 'App Name'),\n  nav({ class: css('_flex _col _gap1') },\n    // nav items: _flex _aic _gap2 _p2 _px3 _r2 _trans\n  )\n)"
+    },
+    "layout": {
+      "description": "Full page layout with sidebar and content area. Light background, no visual effects.",
+      "example": "const { div, main, header, span } = tags;\ndiv({ class: css('_grid _h[100vh] _bgbg'), style: 'grid-template-columns:240px 1fr' },\n  // sidebar with _bgmuted _borderR\n  // ...,\n  div({ class: css('_flex _col _overflow[hidden]') },\n    header({ class: css('_flex _aic _jcsb _px6 _py3 _borderB') },\n      span({ class: css('_heading4') }, 'Dashboard')\n    ),\n    main({ class: css('_flex _col _gap4 _p6 _overflow[auto]') },\n      // page content\n    )\n  )\n)"
+    },
+    "alert": {
+      "wraps": "Alert",
+      "description": "Standard Alert — clean tokens handle the styling.",
+      "example": "Alert({ variant: 'info' },\n  'Your subscription renews in 3 days.'\n)"
+    },
+    "modal": {
+      "wraps": "Modal",
+      "description": "Standard Modal with clean styling — no extra decoration needed.",
+      "example": "const { div, h2 } = tags;\nModal({\n  visible: showModal,\n  onClose: () => setShowModal(false)\n},\n  h2({ class: css('_heading4 _mb4') }, 'Confirm Action'),\n  div({ class: css('_flex _col _gap4') },\n    // modal content\n  )\n)"
+    },
+    "chart": {
+      "wraps": "Chart",
+      "description": "Chart in bordered container with clean header.",
+      "example": "const { div, span } = tags;\ndiv({ class: css('_b1 _r4 _overflow[hidden]') },\n  div({ class: css('_flex _aic _jcsb _px4 _py3 _borderB') },\n    span({ class: css('_bold') }, 'Revenue Trend'),\n    span({ class: css('_textxs _fgmuted') }, 'Last 30 days')\n  ),\n  Chart({ type: 'area', data: revenueData, x: 'date', y: 'amount', height: 300 })\n)"
+    }
+  }
+}

package/src/registry/recipe-command-center.json

@@ -0,0 +1,78 @@
+{
+  "$schema": "https://decantr.ai/schemas/recipe.v1.json",
+  "id": "command-center",
+  "name": "Command Center",
+  "style": "command-center",
+  "mode": "dark",
+  "description": "HUD/radar visual language. Monochromatic cyan, beveled frames, scanlines, status bars. All standard Decantr components work — this recipe describes how to COMPOSE them differently for the Command Center aesthetic.",
+  "setup": "import { setStyle, setMode } from 'decantr/css';\nsetStyle('command-center');\nsetMode('dark');",
+  "decorators": {
+    "cc-frame": "Beveled octagonal border frame. Apply to containers, panels, and section wrappers.",
+    "cc-frame-sm": "Smaller bevel variant for Cards and compact panels.",
+    "cc-corner": "Corner bracket decorations (top-left + bottom-right). Apply to section containers.",
+    "cc-scanline": "Subtle horizontal scanline overlay. Apply to data-heavy areas and backgrounds.",
+    "cc-grid": "Faint grid-line pattern background. Apply to page backgrounds and large containers.",
+    "cc-bar": "Status bar row — flex, uppercase, tracked, border-bottom. Use as panel headers.",
+    "cc-bar-bottom": "Status bar variant with border-top instead. Use as panel footers.",
+    "cc-blink": "Slow 2s pulse animation for status indicators and dots.",
+    "cc-glow": "Cyan glow shadow effect. Apply to important/active elements.",
+    "cc-glow-strong": "Stronger glow variant for hero KPIs and primary actions.",
+    "cc-glow-pulse": "Animated glow pulse (3s loop). Use sparingly for critical status.",
+    "cc-divider": "HUD-style dashed horizontal rule.",
+    "cc-label": "Uppercase micro label with wide letter-spacing.",
+    "cc-data": "Monospace tabular-nums readout styling for data values.",
+    "cc-indicator": "Square status dot (uses currentColor).",
+    "cc-indicator-ok": "Green status indicator.",
+    "cc-indicator-warn": "Warning status indicator.",
+    "cc-indicator-error": "Error status indicator.",
+    "cc-mesh": "Subtle radial gradient background for page-level containers."
+  },
+  "compositions": {
+    "panel": {
+      "description": "Standard HUD panel. Beveled frame with status bar header.",
+      "example": "const { div, span } = tags;\ndiv({ class: css('cc-frame') },\n  div({ class: css('cc-bar') },\n    span('SYSTEM STATUS'),\n    span({ class: css('cc-indicator cc-indicator-ok cc-blink') })\n  ),\n  div({ class: css('_p4') },\n    // content here\n  )\n)"
+    },
+    "card": {
+      "wraps": "Card",
+      "description": "Command Center card. Standard Card wrapped in cc-frame with status bar header.",
+      "example": "const { div, span, h3 } = tags;\ndiv({ class: css('cc-frame-sm') },\n  Card({},\n    Card.Header({},\n      div({ class: css('cc-bar') },\n        span({ class: css('cc-label') }, 'THREAT LEVEL'),\n        span({ class: css('cc-indicator cc-indicator-warn cc-blink') })\n      )\n    ),\n    Card.Body({},\n      span({ class: css('cc-data _heading2') }, '42')\n    ),\n    Card.Footer({ class: css('cc-bar-bottom') },\n      span({ class: css('cc-label') }, 'UPDATED 14:32:07')\n    )\n  )\n)"
+    },
+    "kpi": {
+      "wraps": "Statistic",
+      "description": "KPI metric display with HUD frame and glow.",
+      "example": "const { div } = tags;\ndiv({ class: css('cc-frame-sm cc-glow') },\n  Statistic({\n    title: 'ACTIVE THREATS',\n    value: () => count(),\n    icon: 'alert-triangle',\n    class: css('_bg[transparent]')\n  })\n)"
+    },
+    "table": {
+      "wraps": "DataTable",
+      "description": "Data table in HUD frame with scanline overlay and live status bar.",
+      "example": "const { div, span } = tags;\ndiv({ class: css('cc-frame cc-scanline') },\n  div({ class: css('cc-bar') },\n    span({ class: css('cc-label') }, 'SIGNAL LOG'),\n    span({ class: css('cc-label cc-blink') }, 'LIVE')\n  ),\n  DataTable({ columns, data })\n)"
+    },
+    "form": {
+      "description": "Form inputs in Command Center style. Standard components with cc-frame wrapper.",
+      "example": "const { div, span } = tags;\ndiv({ class: css('cc-frame') },\n  div({ class: css('cc-bar') },\n    span({ class: css('cc-label') }, 'AUTHENTICATION')\n  ),\n  div({ class: css('_p4 _flex _col _gap3') },\n    Input({ label: 'CALLSIGN' }),\n    Input({ label: 'ACCESS CODE', type: 'password' }),\n    Button({ variant: 'primary' }, 'AUTHORIZE')\n  )\n)"
+    },
+    "sidebar": {
+      "description": "Navigation sidebar with HUD frame and grid background.",
+      "example": "const { div, nav, span, a } = tags;\ndiv({ class: css('cc-frame cc-grid _h[100vh]') },\n  div({ class: css('cc-bar') },\n    span({ class: css('cc-label') }, 'NAV SYSTEM')\n  ),\n  nav({ class: css('_flex _col _gap1 _p3') },\n    a({ href: '#overview', class: css('_p2 _px3 cc-label') }, 'OVERVIEW'),\n    a({ href: '#fleet', class: css('_p2 _px3 cc-label') }, 'FLEET MAP'),\n    a({ href: '#alerts', class: css('_p2 _px3 cc-label') }, 'ALERTS')\n  )\n)"
+    },
+    "layout": {
+      "description": "Full page Command Center layout. CSS grid with sidebar + main content area.",
+      "example": "const { div, main, header, span } = tags;\ndiv({ class: css('_grid _h[100vh] cc-mesh'), style: 'grid-template-columns:240px 1fr' },\n  // sidebar (cc-frame + cc-grid)\n  // ...,\n  div({ class: css('_flex _col _overflow[hidden]') },\n    header({ class: css('cc-bar') },\n      span({ class: css('cc-label') }, 'COMMAND CENTER'),\n      span({ class: css('cc-data') }, new Date().toISOString())\n    ),\n    main({ class: css('_flex _col _gap4 _p4 _overflow[auto]') },\n      // page content — panels, kpis, tables\n    )\n  )\n)"
+    },
+    "alert": {
+      "wraps": "Alert",
+      "description": "Alert/notification in Command Center style.",
+      "example": "const { div, span } = tags;\ndiv({ class: css('cc-frame-sm') },\n  Alert({ variant: 'warning' },\n    span({ class: css('cc-label') }, 'WARNING: PERIMETER BREACH DETECTED')\n  )\n)"
+    },
+    "modal": {
+      "wraps": "Modal",
+      "description": "Modal dialog with HUD frame. Apply cc-frame to content panel via class.",
+      "example": "const { div, span } = tags;\nModal({\n  visible: showModal,\n  onClose: () => setShowModal(false),\n  class: css('cc-frame')\n},\n  div({ class: css('cc-bar') },\n    span({ class: css('cc-label') }, 'CONFIRM ACTION')\n  ),\n  div({ class: css('_p4') },\n    // modal content\n  )\n)"
+    },
+    "chart": {
+      "wraps": "Chart",
+      "description": "Chart area with HUD frame and scanline overlay.",
+      "example": "const { div, span } = tags;\ndiv({ class: css('cc-frame cc-scanline') },\n  div({ class: css('cc-bar') },\n    span({ class: css('cc-label') }, 'FUEL CONSUMPTION'),\n    span({ class: css('cc-data cc-blink') }, 'STREAMING')\n  ),\n  Chart({ type: 'line', data: fuelData, x: 'date', y: 'litres', height: 300 })\n)"
+    }
+  }
+}

package/src/registry/router.json

@@ -0,0 +1,73 @@
+{
+  "$schema": "https://decantr.ai/schemas/module.v1.json",
+  "module": "decantr/router",
+  "description": "Client-side routing — hash or history mode",
+  "functions": {
+    "createRouter": {
+      "params": [
+        {
+          "name": "config",
+          "type": "RouterConfig"
+        }
+      ],
+      "returns": "{ navigate: Function, outlet: Function, current: Function, path: Function, destroy: Function, onNavigate: Function }",
+      "description": "Create a router instance."
+    },
+    "navigate": {
+      "params": [
+        {
+          "name": "to",
+          "type": "string|{ name: string, params?: Object }"
+        },
+        {
+          "name": "opts",
+          "type": "{ replace?: boolean }",
+          "optional": true
+        }
+      ],
+      "description": "Navigate programmatically. Delegates to active router."
+    },
+    "link": {
+      "params": [
+        {
+          "name": "props",
+          "type": "{ href: string, activeClass?: string, exact?: boolean, class?: string }"
+        },
+        {
+          "name": "children",
+          "type": "...any"
+        }
+      ],
+      "returns": "HTMLAnchorElement",
+      "description": "Create a router-aware anchor element with active link detection."
+    },
+    "useRoute": {
+      "returns": "() => { path: string, params: Object, query: Object, component: Function|null, components: Function[], matched: boolean, name?: string, meta: Object }",
+      "description": "Get current route signal. The returned signal includes a `meta` field — an object merged from parent routes down to the matched leaf. Parent meta is applied first, child meta overrides. Example: `{ path: '/admin', meta: { requiresAuth: true, breadcrumb: 'Admin' }, component: AdminPage }`"
+    },
+    "useSearchParams": {
+      "returns": "[() => URLSearchParams, (params: Object|URLSearchParams) => void]",
+      "description": "Reactive search params. Returns [getter, setter] tuple. Getter returns URLSearchParams from current URL query string. Setter updates query params without triggering full navigation."
+    },
+    "onNavigate": {
+      "params": [
+        {
+          "name": "callback",
+          "type": "(to: Object, from: Object) => void"
+        }
+      ],
+      "returns": "() => void",
+      "description": "Subscribe to navigation events on the active router. Returns an unsubscribe function."
+    },
+    "back": {
+      "description": "Navigate back in history. Delegates to active router. /"
+    },
+    "forward": {
+      "description": "Navigate forward in history. Delegates to active router. /"
+    },
+    "isNavigating": {
+      "returns": "boolean",
+      "description": "Reactive boolean signal — true while lazy routes are resolving."
+    }
+  }
+}

package/src/registry/schema/README.md

@@ -0,0 +1,197 @@
+# Decantr Registry Extension Schemas
+
+Decantr's registry (patterns, recipes, archetypes, traits) is community-extensible. This document describes the JSON schemas for each registry type so you can create and share your own.
+
+## Discovery Mechanism
+
+1. **Local overrides:** Place files in your project's `src/registry/patterns/`, `src/registry/recipe-*.json`, or `src/registry/archetypes/`
+2. **NPM packages:** Packages with `"decantr-registry": true` in `package.json` are auto-scanned
+3. **CLI discovery:** `decantr generate` merges local + npm registries (local takes priority)
+
+---
+
+## Pattern Schema
+
+**Location:** `src/registry/patterns/{id}.json`
+
+```json
+{
+  "$schema": "https://decantr.ai/schemas/pattern.v1.json",
+  "id": "my-pattern",
+  "name": "My Pattern",
+  "description": "When and where to use this pattern.",
+  "components": ["ComponentA", "ComponentB"],
+  "default_blend": {
+    "layout": "stack | grid | row | flex",
+    "atoms": "_flex _col _gap4 _p4",
+    "slots": {
+      "slot-name": "Description of what goes in this slot"
+    }
+  },
+  "recipe_overrides": {
+    "recipe-id": {
+      "wrapper": "css-class-name",
+      "atoms": "additional-atoms",
+      "notes": "How to adapt this pattern for the recipe"
+    }
+  },
+  "code": {
+    "imports": "import { tags } from 'decantr/tags';...",
+    "example": "function MyPattern() { ... }"
+  }
+}
+```
+
+### Required Fields
+- `id` — Unique kebab-case identifier
+- `name` — Human-readable name
+- `description` — When/where/why to use this pattern
+- `components` — Array of component names used (from `decantr/components` or `decantr/chart`)
+- `default_blend` — Layout specification
+  - `layout` — One of: `stack` (vertical), `grid` (responsive cells), `row` (horizontal), `flex` (flexible)
+  - `atoms` — Space-separated atom classes for the container
+  - `slots` — Named semantic regions with descriptions
+
+### Optional Fields
+- `recipe_overrides` — Per-recipe visual customizations
+- `code.imports` — Import statements for the example
+- `code.example` — Complete working code example (highest-leverage field for LLM code generation)
+
+---
+
+## Recipe Schema
+
+**Location:** `src/registry/recipe-{id}.json`
+
+```json
+{
+  "$schema": "https://decantr.ai/schemas/recipe.v1.json",
+  "id": "my-recipe",
+  "name": "My Recipe",
+  "style": "auradecantism",
+  "mode": "dark",
+  "description": "Visual language description.",
+  "setup": "import { setStyle, setMode } from 'decantr/css';\nsetStyle('my-style');\nsetMode('dark');",
+  "decorators": {
+    "class-name": "What this decorator does and where to apply it"
+  },
+  "compositions": {
+    "panel": {
+      "description": "How to compose a panel with this recipe",
+      "example": "const { div } = tags;\ndiv({ class: css('...') }, ...)"
+    },
+    "card": {
+      "wraps": "Card",
+      "description": "How to style a Card component",
+      "example": "..."
+    }
+  }
+}
+```
+
+### Required Fields
+- `id` — Unique kebab-case identifier
+- `name` — Human-readable name
+- `style` — Which Decantr style this recipe is designed for
+- `mode` — Preferred color mode (`light`, `dark`, `auto`)
+- `description` — Visual language overview
+
+### Required Compositions (10 standard)
+Every recipe should include these 10 compositions for consistency:
+`panel`, `card`, `kpi`, `table`, `form`, `sidebar`, `layout`, `alert`, `modal`, `chart`
+
+### Optional Fields
+- `setup` — Code to initialize the style/mode
+- `decorators` — Custom CSS classes provided by the recipe's style
+- `compositions.*.wraps` — Which standard component this composition wraps
+
+---
+
+## Archetype Schema
+
+**Location:** `src/registry/archetypes/{id}.json`
+
+```json
+{
+  "$schema": "https://decantr.ai/schemas/archetype.v1.json",
+  "id": "my-archetype",
+  "name": "My Archetype",
+  "description": "Domain overview.",
+  "suggested_vintage": {
+    "styles": ["clean", "auradecantism"],
+    "modes": ["light", "auto"]
+  },
+  "tannins": ["auth", "search", "analytics"],
+  "pages": [
+    {
+      "id": "home",
+      "skeleton": "top-nav-main",
+      "default_blend": ["hero", { "cols": ["product-grid"], "at": "md" }, "cta-section"]
+    }
+  ]
+}
+```
+
+### Required Fields
+- `id` — Unique kebab-case identifier
+- `name` — Human-readable domain name
+- `description` — What kind of application this archetype represents
+- `pages` — Array of page definitions with `id`, `skeleton`, and `default_blend`
+
+### Blend Format
+Each item in `default_blend` is either:
+- `"pattern-id"` — Full-width pattern row
+- `{ "cols": ["a", "b"], "at": "lg" }` — Equal-width side-by-side, collapse below breakpoint
+- `{ "cols": ["a", "b"], "span": { "a": 3 }, "at": "md" }` — Weighted columns (a=3fr, b=1fr)
+
+---
+
+## Trait Schema
+
+**Location:** `src/registry/architect/traits.json`
+
+Traits are the compositional building blocks the LLM uses to dynamically compose archetypes.
+
+```json
+{
+  "traits": {
+    "trait-id": {
+      "description": "What this UI trait provides",
+      "triggers": ["keyword1", "keyword2"],
+      "skeleton": "skeleton-id or null",
+      "patterns": ["pattern-id"],
+      "co-occurs": {
+        "other-trait-id": 0.85
+      }
+    }
+  },
+  "composites": {
+    "composite-id": {
+      "description": "Pre-packaged trait combination",
+      "traits": ["trait-a", "trait-b", "trait-c"],
+      "suggested_vintage": { "style": "clean", "mode": "light" }
+    }
+  }
+}
+```
+
+### Trait Fields
+- `triggers` — Keywords that activate this trait from user intent
+- `skeleton` — Optional skeleton to use when this trait is the primary layout driver
+- `patterns` — Patterns this trait maps to
+- `co-occurs` — Other traits that commonly appear alongside, with affinity weight (0.0-1.0)
+
+### Composite Fields
+- `traits` — Ordered list of trait IDs that form this composite
+- `suggested_vintage` — Recommended style/mode for this composite
+
+---
+
+## Publishing a Registry Package
+
+1. Create your patterns/recipes/archetypes following the schemas above
+2. Add `"decantr-registry": true` to your `package.json`
+3. Place registry files under `src/registry/` in your package
+4. Publish to npm
+
+Users install your package and Decantr automatically discovers the registry files.