decantr 0.9.0

package/tools/icons.js

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+/**
+ * Generic SVG icon importer — reads a directory of SVG files, extracts inner
+ * content, and writes a JS module that can be loaded via registerIcons().
+ *
+ * Usage:
+ *   node tools/icons.js <svg-dir> [output.js]
+ *
+ * Examples:
+ *   node tools/icons.js ./my-icons                    → src/icons/custom.js
+ *   node tools/icons.js ./brand-icons brand.js         → src/icons/brand.js
+ *   node tools/icons.js node_modules/some-icons/svgs   → src/icons/custom.js
+ *
+ * The generated file exports an ICONS object. Import and register in your app:
+ *   import { ICONS } from './icons/custom.js';
+ *   import { registerIcons } from 'decantr/icons';
+ *   registerIcons(ICONS);
+ *
+ * Also regenerates src/registry/icons.json with the current essential icon list.
+ *
+ * Run with no arguments to just regenerate the registry from essential.js:
+ *   node tools/icons.js
+ */
+import { readFileSync, writeFileSync, readdirSync, mkdirSync, existsSync } from 'node:fs';
+import { join, dirname, basename, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const root = join(__dirname, '..');
+const iconsOutDir = join(root, 'src', 'icons');
+const registryDir = join(root, 'src', 'registry');
+
+/**
+ * Extract the inner content of an SVG, stripping the outer <svg> wrapper.
+ */
+function extractInner(svgContent) {
+  let s = svgContent.replace(/<!--[\s\S]*?-->/g, '');
+  s = s.replace(/<svg[^>]*>/, '').replace(/<\/svg>\s*$/, '');
+  s = s.replace(/\s+/g, ' ').trim();
+  return s;
+}
+
+/**
+ * Read a directory of SVG files and return { name: innerContent } map.
+ */
+function importSVGs(dir) {
+  const absDir = resolve(dir);
+  if (!existsSync(absDir)) {
+    console.error(`Directory not found: ${absDir}`);
+    process.exit(1);
+  }
+  const files = readdirSync(absDir).filter(f => f.endsWith('.svg')).sort();
+  if (files.length === 0) {
+    console.error(`No .svg files found in: ${absDir}`);
+    process.exit(1);
+  }
+  const icons = {};
+  for (const file of files) {
+    const name = basename(file, '.svg');
+    const svg = readFileSync(join(absDir, file), 'utf-8');
+    icons[name] = extractInner(svg);
+  }
+  return icons;
+}
+
+/**
+ * Write icon data as a JS module.
+ */
+function writeIconModule(icons, outPath) {
+  const entries = Object.entries(icons)
+    .map(([k, v]) => `  '${k}': '${v.replace(/'/g, "\\'")}'`)
+    .join(',\n');
+  writeFileSync(outPath,
+    `// Generated by tools/icons.js — do not edit\nexport const ICONS = {\n${entries}\n};\n`
+  );
+}
+
+/**
+ * Regenerate src/registry/icons.json from essential.js.
+ */
+function updateRegistry() {
+  const essentialPath = join(iconsOutDir, 'essential.js');
+  if (!existsSync(essentialPath)) return;
+
+  const source = readFileSync(essentialPath, 'utf-8');
+  const names = [];
+  const re = /'([a-z][a-z0-9-]*)'\s*:/g;
+  let m;
+  while ((m = re.exec(source)) !== null) names.push(m[1]);
+
+  mkdirSync(registryDir, { recursive: true });
+  writeFileSync(join(registryDir, 'icons.json'), JSON.stringify({
+    generated: new Date().toISOString().split('T')[0],
+    source: 'decantr original icons',
+    essential: names.sort(),
+    essentialCount: names.length,
+    api: {
+      'icon(name, opts?)': 'Render icon as <span> with CSS mask-image',
+      'registerIcon(name, svgInner)': 'Add a single custom icon',
+      'registerIcons(map)': 'Bulk-register icons from { name: svgInner }',
+      'hasIcon(name)': 'Check if icon is available',
+      'getIconNames()': 'List all available icon names'
+    },
+    importGuide: 'node tools/icons.js <svg-dir> [output.js] — import SVG directory as JS module'
+  }, null, 2) + '\n');
+
+  console.log(`Registry: src/registry/icons.json (${names.length} essential icons)`);
+}
+
+// --- Main ---
+
+const args = process.argv.slice(2);
+
+if (args.length >= 1) {
+  // Import mode: read SVG directory, write JS module
+  const svgDir = args[0];
+  const outName = args[1] || 'custom.js';
+  const outPath = outName.includes('/') ? resolve(outName) : join(iconsOutDir, outName);
+
+  mkdirSync(dirname(outPath), { recursive: true });
+  const icons = importSVGs(svgDir);
+  writeIconModule(icons, outPath);
+
+  console.log(`Imported ${Object.keys(icons).length} icons from ${svgDir}`);
+  console.log(`  → ${outPath}`);
+  console.log(`\nUsage in your app:`);
+  console.log(`  import { ICONS } from './icons/${basename(outPath)}';`);
+  console.log(`  import { registerIcons } from 'decantr/icons';`);
+  console.log(`  registerIcons(ICONS);`);
+}
+
+// Always update registry
+updateRegistry();

package/tools/init-templates.js

@@ -0,0 +1,265 @@
+/**
+ * Template utilities for `decantr init`.
+ * Generates the minimal project skeleton files.
+ */
+import { readFile } from 'node:fs/promises';
+import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const frameworkRoot = resolve(__dirname, '..');
+
+/** Minimal CSS custom properties for initial page render (before JS hydrates the full token set) */
+export const THEME_CSS = {
+  'dark': ':root{--d-bg:#060918;--d-fg:#fafafa;--d-primary:#6500C6;--d-primary-hover:#7a1ad4;--d-muted:#8892a4;--d-border:rgba(255,255,255,0.08);--d-surface-1:rgba(12,15,40,0.55);--d-error:#D80F4A;--d-success:#00C388;--d-warning:#FDA303;--d-overlay:rgba(0,0,0,0.6);--d-radius:12px;--d-radius-lg:16px;--d-font:system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,sans-serif}',
+};
+
+export function packageJson(name) {
+  return JSON.stringify({
+    name,
+    version: '0.1.0',
+    type: 'module',
+    scripts: {
+      dev: 'decantr dev',
+      build: 'decantr build',
+      test: 'decantr test'
+    },
+    dependencies: {
+      decantr: '^0.4.0'
+    }
+  }, null, 2);
+}
+
+export function configJson(name) {
+  return JSON.stringify({
+    $schema: 'https://decantr.ai/schemas/config.v2.json',
+    name,
+    style: 'auradecantism',
+    mode: 'dark',
+    router: 'hash',
+    dev: { port: 4200 },
+    build: {
+      outDir: 'dist',
+      sourcemap: true,
+      treeShake: true,
+      codeSplit: true,
+      purgeCSS: true,
+      incremental: true,
+      analyze: true
+    }
+  }, null, 2);
+}
+
+export function indexHtml(name) {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width,initial-scale=1">
+  <title>${name}</title>
+  <style>${THEME_CSS.dark}*{margin:0;box-sizing:border-box}body{font-family:var(--d-font);color:var(--d-fg);background:var(--d-bg);min-height:100vh}a{color:var(--d-primary);text-decoration:none}a:hover{color:var(--d-primary-hover)}</style>
+</head>
+<body>
+  <div id="app"></div>
+  <script type="module" src="/src/app.js"></script>
+</body>
+</html>`;
+}
+
+export function manifestJson(name) {
+  return JSON.stringify({
+    $schema: 'https://decantr.ai/schemas/manifest.v2.json',
+    version: '0.4.0',
+    name,
+    entrypoint: 'src/app.js',
+    shell: 'public/index.html',
+    mountTarget: '#app'
+  }, null, 2);
+}
+
+export function claudeMd(name) {
+  return `# ${name}
+
+Built with [decantr](https://decantr.ai) v0.4.0 — AI-first web framework.
+
+## Quick Start
+
+**Read this first:** \`node_modules/decantr/reference/llm-primer.md\` — single-file guide with all imports, top atoms with Tailwind equivalences, component signatures, Chart API, skeleton code, and pattern examples. This covers 80% of code generation needs.
+
+## 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)
+
+## 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.
+
+**Blend format**: Each \`blend\` is an ordered array of rows:
+- \`"pattern-id"\` — full-width pattern row
+- \`{ "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)
+
+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. Density and tone match the Character.
+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
+{
+  "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"] }
+  ],
+  "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 } from 'decantr/state';
+import { createRouter, link, navigate, useRoute } from 'decantr/router';
+import { css, setStyle, setMode } from 'decantr/css';
+import { Button, Input, Card, Modal, Tabs, ... } from 'decantr/components';
+\`\`\`
+
+## Styles
+
+Available: \`auradecantism\` (default), \`clean\`, \`retro\`, \`glassmorphism\`, \`command-center\`
+Modes: \`light\`, \`dark\`, \`auto\`
+Shapes: \`sharp\`, \`rounded\`, \`pill\`
+
+## 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
+- \`node_modules/decantr/src/registry/patterns/\` — Experience patterns
+- \`node_modules/decantr/src/registry/recipe-*.json\` — Visual language recipes
+
+## 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\`
+- \`npx decantr generate\` — Generate code from \`decantr.essence.json\`
+`;
+}
+
+export function appJs() {
+  return `import { mount } from 'decantr/core';
+import { tags } from 'decantr/tags';
+import { css, define, setStyle, setMode } from 'decantr/css';
+import { Image, CodeBlock } from 'decantr/components';
+
+const { div, span, p, h1 } = tags;
+
+// Style and mode are set here for initial render.
+// After CLARIFY, these should match your essence vintage.
+// For sectioned essences, add a router.beforeEach guard to switch per section.
+setStyle('auradecantism');
+setMode('dark');
+
+define('_pink', 'color:#FE4474');
+
+function App() {
+  return div({ class: 'd-mesh ' + css('_flex _col _aic _jcc _minhscreen _gap6 _p6') },
+    Image({ src: '/images/logo-portrait.svg', alt: 'decantr', width: '120px', height: '120px', fit: 'contain', class: css('_mb2') }),
+    h1({ class: css('_fw[900] _ls[-0.04em] _lh[1] _t48 _fgfg') },
+      span('decantr'),
+      span({ class: css('_pink') }, '.'),
+      span('a'),
+      span({ class: css('_pink') }, 'i')
+    ),
+    p({ class: css('_t16 _fgmuted _tac') }, "You're all set up. Prompt your AI to start building."),
+    CodeBlock({ language: 'bash', copyable: false, class: css('_w[480px] _mw[100%]') },
+      '$ npx decantr dev\\n\\nThen tell your AI what to build:\\n\\n"Build me a SaaS dashboard with KPIs,\\n charts, and user management"'
+    )
+  );
+}
+
+mount(document.getElementById('app'), App);
+`;
+}
+
+export function essenceJson() {
+  return JSON.stringify({
+    "_comment": "Project DNA — generated by decantr init. Fill in during CLARIFY stage.",
+    "terroir": null,
+    "vintage": { "style": "auradecantism", "mode": "dark", "recipe": null, "shape": "rounded" },
+    "character": [],
+    "vessel": { "type": "spa", "routing": "hash" },
+    "structure": [],
+    "tannins": [],
+    "cork": {}
+  }, null, 2);
+}
+
+export async function agentsMd() {
+  return readFile(join(frameworkRoot, 'AGENTS.md'), 'utf-8');
+}

package/tools/install-hooks.sh

@@ -0,0 +1,5 @@
+#!/bin/sh
+HOOK_DIR="$(git rev-parse --show-toplevel)/.git/hooks"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+ln -sf "$SCRIPT_DIR/pre-commit" "$HOOK_DIR/pre-commit"
+echo "Pre-commit hook installed."

package/tools/migrations/0.5.0.js

@@ -0,0 +1,53 @@
+/**
+ * Migration: 0.5.0
+ *
+ * Breaking changes in v0.5.0:
+ * - "organs" renamed to "tannins"
+ * - "anatomy" renamed to "structure"
+ */
+
+export const version = '0.5.0';
+
+export function migrate(essence) {
+  const result = { ...essence };
+
+  // Rename organs → tannins (top-level)
+  if ('organs' in result && !('tannins' in result)) {
+    result.tannins = result.organs;
+    delete result.organs;
+  }
+
+  // Rename anatomy → structure (top-level)
+  if ('anatomy' in result && !('structure' in result)) {
+    result.structure = result.anatomy;
+    delete result.anatomy;
+  }
+
+  // Handle sectioned essences
+  if (Array.isArray(result.sections)) {
+    result.sections = result.sections.map(section => {
+      const s = { ...section };
+
+      if ('organs' in s && !('tannins' in s)) {
+        s.tannins = s.organs;
+        delete s.organs;
+      }
+
+      if ('anatomy' in s && !('structure' in s)) {
+        s.structure = s.anatomy;
+        delete s.anatomy;
+      }
+
+      return s;
+    });
+  }
+
+  // Rename shared_organs → shared_tannins
+  if ('shared_organs' in result && !('shared_tannins' in result)) {
+    result.shared_tannins = result.shared_organs;
+    delete result.shared_organs;
+  }
+
+  result.version = '0.5.0';
+  return result;
+}

package/tools/migrations/0.6.0.js

@@ -0,0 +1,95 @@
+/**
+ * Migration: 0.6.0
+ *
+ * Breaking changes in v0.6.0:
+ * - 13 domain-specific patterns consolidated into presets on generic patterns
+ * - Pattern references in blend arrays must use { pattern, preset, as } format
+ */
+
+export const version = '0.6.0';
+
+/**
+ * Map of old pattern names to their v2 preset equivalents.
+ * Keys are the old string references found in blend arrays.
+ * Values are the new { pattern, preset?, as? } objects.
+ */
+const PATTERN_RENAMES = {
+  'recipe-hero':         { pattern: 'hero', preset: 'image-overlay', as: 'recipe-hero' },
+  'cookbook-hero':        { pattern: 'hero', preset: 'image-overlay-compact', as: 'cookbook-hero' },
+  'product-grid':        { pattern: 'card-grid', preset: 'product', as: 'product-grid' },
+  'recipe-card-grid':    { pattern: 'card-grid', preset: 'content', as: 'recipe-card-grid' },
+  'cookbook-grid':        { pattern: 'card-grid', preset: 'collection', as: 'cookbook-grid' },
+  'feature-grid':        { pattern: 'card-grid', preset: 'icon', as: 'feature-grid' },
+  'profile-header':      { pattern: 'detail-header', preset: 'profile', as: 'profile-header' },
+  'recipe-stats-bar':    { pattern: 'stats-bar' },
+  'recipe-ingredients':  { pattern: 'checklist-card' },
+  'recipe-instructions': { pattern: 'steps-card' },
+  'nutrition-card':      { pattern: 'stat-card' },
+  'recipe-form-simple':  { pattern: 'form-sections', preset: 'creation', as: 'recipe-form-simple' },
+  'recipe-form-chef':    { pattern: 'form-sections', preset: 'structured', as: 'recipe-form-chef' },
+};
+
+/**
+ * Convert a single blend item if it matches an old pattern name.
+ */
+function migrateBlendItem(item) {
+  if (typeof item === 'string' && item in PATTERN_RENAMES) {
+    return { ...PATTERN_RENAMES[item] };
+  }
+
+  // Handle cols arrays — migrate column references inside
+  if (item && typeof item === 'object' && Array.isArray(item.cols)) {
+    const newCols = item.cols.map(col =>
+      (typeof col === 'string' && col in PATTERN_RENAMES) ? col : col
+    );
+    // Check if any col references need migrating (they stay as strings in cols)
+    // Cols are identifiers, not pattern references — no migration needed
+    return item;
+  }
+
+  return item;
+}
+
+/**
+ * Migrate all blend arrays in a structure array.
+ */
+function migrateStructure(structure) {
+  if (!Array.isArray(structure)) return structure;
+
+  return structure.map(page => {
+    if (!page.blend && !page.patterns) return page;
+
+    const blendKey = page.blend ? 'blend' : 'patterns';
+    const blend = page[blendKey];
+
+    if (!Array.isArray(blend)) return page;
+
+    return {
+      ...page,
+      [blendKey]: blend.map(migrateBlendItem),
+    };
+  });
+}
+
+export function migrate(essence) {
+  const result = { ...essence };
+
+  // Migrate top-level structure
+  if (Array.isArray(result.structure)) {
+    result.structure = migrateStructure(result.structure);
+  }
+
+  // Migrate sectioned essences
+  if (Array.isArray(result.sections)) {
+    result.sections = result.sections.map(section => {
+      if (!Array.isArray(section.structure)) return section;
+      return {
+        ...section,
+        structure: migrateStructure(section.structure),
+      };
+    });
+  }
+
+  result.version = '0.6.0';
+  return result;
+}