decantr 0.9.0

package/src/icons/index.js

@@ -0,0 +1,53 @@
+/**
+ * Icon data registry — internal API for icon path lookup.
+ * Essential icons (~50) are always available.
+ * Additional icons added via registerIcon() or bulk-imported via tools/icons.js.
+ */
+import { ESSENTIAL } from './essential.js';
+
+const icons = new Map(Object.entries(ESSENTIAL));
+
+/**
+ * Get SVG inner content for an icon by name.
+ * @param {string} name - Icon name (kebab-case)
+ * @returns {string|null}
+ */
+export function getIconPath(name) {
+  return icons.get(name) || null;
+}
+
+/**
+ * Register a custom icon (or override an existing one).
+ * @param {string} name - Icon name
+ * @param {string} pathData - SVG inner content (e.g. '<path d="..."/>')
+ */
+export function registerIcon(name, pathData) {
+  icons.set(name, pathData);
+}
+
+/**
+ * Register multiple icons at once.
+ * @param {Object<string, string>} iconMap - { name: svgInnerContent }
+ */
+export function registerIcons(iconMap) {
+  for (const [k, v] of Object.entries(iconMap)) {
+    icons.set(k, v);
+  }
+}
+
+/**
+ * Check if an icon is available.
+ * @param {string} name
+ * @returns {boolean}
+ */
+export function hasIcon(name) {
+  return icons.has(name);
+}
+
+/**
+ * Get all currently available icon names.
+ * @returns {string[]}
+ */
+export function getIconNames() {
+  return [...icons.keys()];
+}

package/src/plugins/index.js

@@ -0,0 +1,282 @@
+/**
+ * Decantr Plugin System
+ *
+ * Allows users to extend Decantr without forking. Plugins can register
+ * styles, patterns, recipes, and hook into build/dev/generate lifecycle.
+ *
+ * Plugin format in decantr.config.json:
+ *   "plugins": [
+ *     "@acme/decantr-plugin-auth",
+ *     ["./plugins/custom-style.js", { "theme": "corporate" }]
+ *   ]
+ *
+ * Each plugin exports a default function:
+ *   export default function(api, options) { ... }
+ *
+ * Zero third-party dependencies (the Decantr Way).
+ */
+
+import { resolve, isAbsolute } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+// ============================================================
+// Internal state
+// ============================================================
+
+/** @type {Array<{ name: string, hooks: Map<string, Function[]> }>} */
+const loadedPlugins = [];
+
+/** Registry extensions contributed by plugins */
+const extensions = {
+  /** @type {Map<string, object>} */
+  styles: new Map(),
+  /** @type {Map<string, object>} */
+  patterns: new Map(),
+  /** @type {Map<string, object>} */
+  recipes: new Map(),
+};
+
+/** Valid hook names — kept small and explicit */
+const VALID_HOOKS = new Set([
+  'onBuild',
+  'onDev',
+  'onGenerate',
+  'registerStyle',
+  'registerPattern',
+  'registerRecipe',
+]);
+
+// ============================================================
+// Plugin API (passed to each plugin function)
+// ============================================================
+
+/**
+ * Creates a sandboxed API object for a single plugin.
+ * @param {string} pluginName
+ * @param {Map<string, Function[]>} hooks
+ * @returns {object}
+ */
+function createPluginAPI(pluginName, hooks) {
+  return {
+    /**
+     * Register a lifecycle hook.
+     * @param {'onBuild'|'onDev'|'onGenerate'} hookName
+     * @param {Function} fn
+     */
+    onBuild(fn) {
+      if (typeof fn !== 'function') throw new Error(`[decantr:plugin:${pluginName}] onBuild handler must be a function`);
+      if (!hooks.has('onBuild')) hooks.set('onBuild', []);
+      hooks.get('onBuild').push(fn);
+    },
+
+    onDev(fn) {
+      if (typeof fn !== 'function') throw new Error(`[decantr:plugin:${pluginName}] onDev handler must be a function`);
+      if (!hooks.has('onDev')) hooks.set('onDev', []);
+      hooks.get('onDev').push(fn);
+    },
+
+    onGenerate(fn) {
+      if (typeof fn !== 'function') throw new Error(`[decantr:plugin:${pluginName}] onGenerate handler must be a function`);
+      if (!hooks.has('onGenerate')) hooks.set('onGenerate', []);
+      hooks.get('onGenerate').push(fn);
+    },
+
+    /**
+     * Register a custom style (theme).
+     * @param {string} id   - Style identifier (e.g. "corporate")
+     * @param {object} def  - Style definition: { name, seed, personality?, overrides? }
+     */
+    registerStyle(id, def) {
+      if (!id || typeof id !== 'string') throw new Error(`[decantr:plugin:${pluginName}] registerStyle requires a string id`);
+      if (!def || typeof def !== 'object') throw new Error(`[decantr:plugin:${pluginName}] registerStyle requires a definition object`);
+      if (!def.name) def.name = id;
+      if (!def.seed) throw new Error(`[decantr:plugin:${pluginName}] Style "${id}" must have seed colors`);
+      const style = { id, ...def };
+      extensions.styles.set(id, style);
+
+      // Also register via the hook mechanism so runHook('registerStyle') can propagate
+      if (!hooks.has('registerStyle')) hooks.set('registerStyle', []);
+      hooks.get('registerStyle').push(() => style);
+    },
+
+    /**
+     * Register a custom pattern.
+     * @param {string} id   - Pattern identifier (e.g. "ticket-board")
+     * @param {object} def  - Pattern definition: { name, description?, blend?, atoms? }
+     */
+    registerPattern(id, def) {
+      if (!id || typeof id !== 'string') throw new Error(`[decantr:plugin:${pluginName}] registerPattern requires a string id`);
+      if (!def || typeof def !== 'object') throw new Error(`[decantr:plugin:${pluginName}] registerPattern requires a definition object`);
+      if (!def.name) def.name = id;
+      extensions.patterns.set(id, { id, ...def });
+
+      if (!hooks.has('registerPattern')) hooks.set('registerPattern', []);
+      hooks.get('registerPattern').push(() => ({ id, ...def }));
+    },
+
+    /**
+     * Register a custom recipe (visual language overlay).
+     * @param {string} id   - Recipe identifier (e.g. "brutalist")
+     * @param {object} def  - Recipe definition: { name, style, mode?, description?, decorators?, compositions? }
+     */
+    registerRecipe(id, def) {
+      if (!id || typeof id !== 'string') throw new Error(`[decantr:plugin:${pluginName}] registerRecipe requires a string id`);
+      if (!def || typeof def !== 'object') throw new Error(`[decantr:plugin:${pluginName}] registerRecipe requires a definition object`);
+      if (!def.name) def.name = id;
+      extensions.recipes.set(id, { id, ...def });
+
+      if (!hooks.has('registerRecipe')) hooks.set('registerRecipe', []);
+      hooks.get('registerRecipe').push(() => ({ id, ...def }));
+    },
+  };
+}
+
+// ============================================================
+// Public API
+// ============================================================
+
+/**
+ * Load all plugins declared in config.plugins.
+ *
+ * Each entry is either:
+ *   - A string (bare module specifier or relative path)
+ *   - A [specifier, options] tuple
+ *
+ * @param {object} config - The full decantr.config.json object
+ * @param {object} [opts]
+ * @param {string} [opts.cwd] - Working directory for resolving relative paths
+ * @returns {Promise<void>}
+ */
+export async function loadPlugins(config, opts = {}) {
+  const cwd = opts.cwd || process.cwd();
+  const entries = config?.plugins;
+
+  if (!entries || !Array.isArray(entries) || entries.length === 0) return;
+
+  for (const entry of entries) {
+    let specifier, options;
+
+    if (typeof entry === 'string') {
+      specifier = entry;
+      options = {};
+    } else if (Array.isArray(entry) && entry.length >= 1) {
+      specifier = entry[0];
+      options = entry[1] || {};
+    } else {
+      console.warn(`[decantr] Invalid plugin entry — skipping: ${JSON.stringify(entry)}`);
+      continue;
+    }
+
+    if (typeof specifier !== 'string') {
+      console.warn(`[decantr] Plugin specifier must be a string — skipping: ${JSON.stringify(entry)}`);
+      continue;
+    }
+
+    // Derive a human-readable name
+    const pluginName = specifier.startsWith('.') ? specifier : specifier.replace(/^@[^/]+\//, '');
+
+    try {
+      // Resolve the module
+      let mod;
+      if (specifier.startsWith('.') || isAbsolute(specifier)) {
+        // Relative or absolute path — resolve against cwd
+        const fullPath = resolve(cwd, specifier);
+        mod = await import(pathToFileURL(fullPath).href);
+      } else {
+        // Bare specifier — let Node resolution handle it (node_modules)
+        mod = await import(specifier);
+      }
+
+      const pluginFn = mod.default || mod;
+
+      if (typeof pluginFn !== 'function') {
+        console.warn(`[decantr] Plugin "${pluginName}" does not export a function — skipping`);
+        continue;
+      }
+
+      // Create isolated hooks map and API for this plugin
+      const hooks = new Map();
+      const api = createPluginAPI(pluginName, hooks);
+
+      // Execute the plugin setup function
+      await pluginFn(api, options);
+
+      loadedPlugins.push({ name: pluginName, hooks });
+    } catch (err) {
+      console.error(`[decantr] Failed to load plugin "${pluginName}": ${err.message}`);
+    }
+  }
+}
+
+/**
+ * Run a named hook across all loaded plugins, in registration order.
+ *
+ * @param {string} hookName - One of: onBuild, onDev, onGenerate, registerStyle, registerPattern, registerRecipe
+ * @param {object} [context] - Hook-specific context object passed to each handler
+ * @returns {Promise<any[]>} - Array of results from each hook handler
+ */
+export async function runHook(hookName, context = {}) {
+  if (!VALID_HOOKS.has(hookName)) {
+    throw new Error(`[decantr] Unknown plugin hook: "${hookName}". Valid hooks: ${[...VALID_HOOKS].join(', ')}`);
+  }
+
+  const results = [];
+
+  for (const plugin of loadedPlugins) {
+    const handlers = plugin.hooks.get(hookName);
+    if (!handlers) continue;
+
+    for (const handler of handlers) {
+      try {
+        const result = await handler(context);
+        if (result !== undefined) results.push(result);
+      } catch (err) {
+        console.error(`[decantr] Plugin "${plugin.name}" hook "${hookName}" threw: ${err.message}`);
+      }
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Get all plugin-registered styles.
+ * @returns {Map<string, object>}
+ */
+export function getPluginStyles() {
+  return new Map(extensions.styles);
+}
+
+/**
+ * Get all plugin-registered patterns.
+ * @returns {Map<string, object>}
+ */
+export function getPluginPatterns() {
+  return new Map(extensions.patterns);
+}
+
+/**
+ * Get all plugin-registered recipes.
+ * @returns {Map<string, object>}
+ */
+export function getPluginRecipes() {
+  return new Map(extensions.recipes);
+}
+
+/**
+ * Get the list of loaded plugin names.
+ * @returns {string[]}
+ */
+export function getLoadedPlugins() {
+  return loadedPlugins.map(p => p.name);
+}
+
+/**
+ * Reset all plugin state. Primarily for testing.
+ */
+export function resetPlugins() {
+  loadedPlugins.length = 0;
+  extensions.styles.clear();
+  extensions.patterns.clear();
+  extensions.recipes.clear();
+}

package/src/registry/archetypes/content-site.json

@@ -0,0 +1,71 @@
+{
+  "$schema": "https://decantr.ai/schemas/archetype.v1.json",
+  "id": "content-site",
+  "name": "Content Site",
+  "description": "Blog, magazine, documentation, or knowledge base with articles, categories, and search.",
+  "pages": [
+    {
+      "id": "home",
+      "skeleton": "top-nav-main",
+      "patterns": ["hero", "post-list", "category-nav", "cta-section"],
+      "default_blend": [
+        "hero",
+        "category-nav",
+        "post-list",
+        "cta-section"
+      ]
+    },
+    {
+      "id": "category",
+      "skeleton": "top-nav-main",
+      "patterns": ["category-nav", "post-list", "pagination"],
+      "default_blend": [
+        "category-nav",
+        "post-list",
+        "pagination"
+      ]
+    },
+    {
+      "id": "article",
+      "skeleton": "top-nav-main",
+      "patterns": ["article-content", "table-of-contents", "author-card", "post-list"],
+      "default_blend": [
+        { "cols": ["article-content", "table-of-contents"], "span": { "article-content": 3 }, "at": "lg" },
+        "author-card",
+        "post-list"
+      ]
+    },
+    {
+      "id": "search",
+      "skeleton": "top-nav-main",
+      "patterns": ["search-bar", "post-list", "pagination"],
+      "default_blend": [
+        "search-bar",
+        "post-list",
+        "pagination"
+      ]
+    },
+    {
+      "id": "about",
+      "skeleton": "top-nav-main",
+      "patterns": ["detail-header"],
+      "default_blend": [
+        "detail-header"
+      ]
+    },
+    {
+      "id": "contact",
+      "skeleton": "top-nav-main",
+      "patterns": ["contact-form"],
+      "default_blend": ["contact-form"]
+    }
+  ],
+  "tannins": ["search", "content-state", "categories", "analytics"],
+  "skeletons": {
+    "top-nav-main": "Horizontal navigation bar + full-width main content area"
+  },
+  "suggested_vintage": {
+    "styles": ["clean", "glassmorphism"],
+    "modes": ["light", "auto"]
+  }
+}

package/src/registry/archetypes/docs-explorer.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://decantr.ai/schemas/archetype.v1.json",
+  "id": "docs-explorer",
+  "name": "Docs Explorer",
+  "description": "Interactive design-system and API documentation. 7-layer navigation (Foundations, Atoms, Tokens, Components, Patterns, Archetypes, Recipes) with registry-driven content, global search, live theming controls, and viewport simulation.",
+  "pages": [
+    { "id": "components", "skeleton": "sidebar-main", "patterns": ["component-showcase"], "default_blend": ["component-showcase"] },
+    { "id": "patterns", "skeleton": "sidebar-main", "patterns": ["detail-panel"], "default_blend": ["detail-panel"] },
+    { "id": "archetypes", "skeleton": "sidebar-main", "patterns": ["detail-panel"], "default_blend": ["detail-panel"] },
+    { "id": "recipes", "skeleton": "sidebar-main", "patterns": ["detail-panel"], "default_blend": ["detail-panel"] },
+    { "id": "foundations", "skeleton": "sidebar-main", "patterns": ["detail-panel"], "default_blend": ["detail-panel"] },
+    { "id": "atoms", "skeleton": "sidebar-main", "patterns": ["specimen-grid"], "default_blend": ["specimen-grid"] },
+    { "id": "tokens", "skeleton": "sidebar-main", "patterns": ["token-inspector"], "default_blend": ["token-inspector"] }
+  ],
+  "tannins": ["registry-data", "search", "theme-controls", "viewport-sim"],
+  "skeletons": {
+    "sidebar-main": "Explorer shell — persistent header with search trigger (Cmd+K), collapsible multi-layer sidebar with filter, scrollable main content, floating HUD for style/mode/shape/viewport switching"
+  },
+  "suggested_vintage": {
+    "styles": ["auradecantism", "clean", "command-center"],
+    "modes": ["dark", "auto"]
+  }
+}

package/src/registry/archetypes/ecommerce.json

@@ -0,0 +1,104 @@
+{
+  "$schema": "https://decantr.ai/schemas/archetype.v2.json",
+  "id": "ecommerce",
+  "name": "E-Commerce",
+  "description": "Online retail with product catalog, cart, checkout, and account management.",
+  "pages": [
+    {
+      "id": "home",
+      "skeleton": "top-nav-main",
+      "patterns": [
+        "hero",
+        { "pattern": "card-grid", "preset": "product", "as": "product-grid" },
+        "category-nav",
+        "testimonials",
+        "cta-section"
+      ],
+      "default_blend": [
+        "hero",
+        "category-nav",
+        { "pattern": "card-grid", "preset": "product", "as": "product-grid" },
+        "testimonials",
+        "cta-section"
+      ]
+    },
+    {
+      "id": "catalog",
+      "skeleton": "top-nav-main",
+      "patterns": [
+        "filter-sidebar",
+        { "pattern": "card-grid", "preset": "product", "as": "product-grid" },
+        "filter-bar",
+        "pagination"
+      ],
+      "default_blend": [
+        "filter-bar",
+        { "cols": ["filter-sidebar", "product-grid"], "span": { "product-grid": 3 }, "at": "md" },
+        "pagination"
+      ]
+    },
+    {
+      "id": "product",
+      "skeleton": "top-nav-main",
+      "patterns": [
+        "media-gallery",
+        "detail-panel",
+        "testimonials",
+        { "pattern": "card-grid", "preset": "product", "as": "product-grid" }
+      ],
+      "default_blend": [
+        { "cols": ["media-gallery", "detail-panel"], "at": "md" },
+        "testimonials",
+        { "pattern": "card-grid", "preset": "product", "as": "product-grid" }
+      ]
+    },
+    {
+      "id": "cart",
+      "skeleton": "top-nav-main",
+      "patterns": ["data-table", "pricing-table"],
+      "default_blend": [
+        { "cols": ["data-table", "pricing-table"], "span": { "data-table": 2 }, "at": "md" }
+      ]
+    },
+    {
+      "id": "checkout",
+      "skeleton": "minimal-header",
+      "patterns": ["wizard"],
+      "default_blend": [
+        "wizard"
+      ]
+    },
+    {
+      "id": "account",
+      "skeleton": "sidebar-main",
+      "patterns": ["form-sections", "order-history"],
+      "default_blend": [
+        "form-sections",
+        "order-history"
+      ]
+    },
+    {
+      "id": "login",
+      "skeleton": "centered",
+      "patterns": ["auth-form"],
+      "default_blend": ["auth-form"]
+    },
+    {
+      "id": "register",
+      "skeleton": "centered",
+      "patterns": ["auth-form"],
+      "default_blend": ["auth-form"]
+    }
+  ],
+  "tannins": ["auth", "cart-state", "search", "payments", "inventory", "wishlist"],
+  "skeletons": {
+    "top-nav-main": "Horizontal navigation bar + full-width main content area",
+    "sidebar-main": "Vertical sidebar navigation + main content area",
+    "minimal-header": "Slim header (logo + progress) + centered content",
+    "centered": "Centered card on background — for auth flows"
+  },
+  "suggested_vintage": {
+    "styles": ["clean", "glassmorphism", "auradecantism"],
+    "modes": ["light", "auto"]
+  }
+}

package/src/registry/archetypes/financial-dashboard.json

@@ -0,0 +1,77 @@
+{
+  "$schema": "https://decantr.ai/schemas/archetype.v1.json",
+  "id": "financial-dashboard",
+  "name": "Financial Dashboard",
+  "description": "Performance dashboard for financial services, lending, and banking. Portfolio overview with goal tracking, production monitoring, pipeline management, collections, and compliance.",
+  "extends": "saas-dashboard",
+  "pages": [
+    {
+      "id": "overview",
+      "skeleton": "sidebar-main",
+      "patterns": ["kpi-grid", "goal-tracker", "comparison-panel", "chart-grid"],
+      "default_blend": [
+        "kpi-grid",
+        { "cols": ["goal-tracker", "comparison-panel"], "at": "lg" },
+        "chart-grid"
+      ]
+    },
+    {
+      "id": "production",
+      "skeleton": "sidebar-main",
+      "patterns": ["kpi-grid", "chart-grid", "data-table", "filter-bar"],
+      "default_blend": ["filter-bar", "kpi-grid", "chart-grid", "data-table"]
+    },
+    {
+      "id": "pipeline",
+      "skeleton": "sidebar-main",
+      "patterns": ["pipeline-tracker", "filter-bar"],
+      "default_blend": ["filter-bar", "pipeline-tracker"]
+    },
+    {
+      "id": "approvals",
+      "skeleton": "sidebar-main",
+      "patterns": ["chart-grid", "comparison-panel", "data-table", "filter-bar"],
+      "default_blend": [
+        "filter-bar",
+        { "cols": ["chart-grid", "comparison-panel"], "at": "lg" },
+        "data-table"
+      ]
+    },
+    {
+      "id": "collections",
+      "skeleton": "sidebar-main",
+      "patterns": ["kpi-grid", "goal-tracker", "chart-grid", "data-table"],
+      "default_blend": ["kpi-grid", "goal-tracker", "chart-grid", "data-table"]
+    },
+    {
+      "id": "outreach",
+      "skeleton": "sidebar-main",
+      "patterns": ["scorecard", "data-table", "activity-feed"],
+      "default_blend": ["scorecard", { "cols": ["data-table", "activity-feed"], "at": "lg" }]
+    },
+    {
+      "id": "products",
+      "skeleton": "sidebar-main",
+      "patterns": ["data-table", "detail-panel"],
+      "default_blend": [{ "cols": ["data-table", "detail-panel"], "at": "md" }]
+    },
+    {
+      "id": "scorecard",
+      "skeleton": "sidebar-main",
+      "patterns": ["scorecard", "goal-tracker"],
+      "default_blend": ["scorecard", "goal-tracker"]
+    },
+    {
+      "id": "vendors",
+      "skeleton": "sidebar-main",
+      "patterns": ["data-table", "detail-panel", "form-sections"],
+      "default_blend": ["data-table", "detail-panel"]
+    }
+  ],
+  "tannins": ["portfolio-state", "pipeline-state", "compliance-state", "report-export"],
+  "skeletons": {},
+  "suggested_vintage": {
+    "styles": ["auradecantism", "command-center", "clean"],
+    "modes": ["dark", "auto"]
+  }
+}

package/src/registry/archetypes/index.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "https://decantr.ai/schemas/archetypes.v1.json",
+  "description": "Domain archetypes for the Decantation Process. Each archetype pre-maps page patterns, tannins, skeleton layouts, and suggested visual identity for a domain. Archetypes may use \"extends\" to inherit pages, tannins, and skeletons from a parent archetype. Child pages override parent pages by id; tannins are concatenated and deduped; skeletons are shallow-merged. Circular inheritance and depth > 5 are rejected.",
+  "archetypes": {
+    "ecommerce": {
+      "name": "E-Commerce",
+      "description": "Online retail — product catalog, cart, checkout, account management",
+      "file": "ecommerce.json"
+    },
+    "saas-dashboard": {
+      "name": "SaaS Dashboard",
+      "description": "Analytics/admin dashboard — KPIs, data tables, charts, settings",
+      "file": "saas-dashboard.json"
+    },
+    "portfolio": {
+      "name": "Portfolio",
+      "description": "Personal or agency showcase — projects, about, contact, blog",
+      "file": "portfolio.json"
+    },
+    "content-site": {
+      "name": "Content Site",
+      "description": "Blog, magazine, or documentation — articles, categories, search",
+      "file": "content-site.json"
+    },
+    "docs-explorer": {
+      "name": "Docs Explorer",
+      "description": "Interactive API and design-system documentation — layered navigation, registry-driven content, search, live theming",
+      "file": "docs-explorer.json"
+    },
+    "financial-dashboard": {
+      "name": "Financial Dashboard",
+      "description": "Performance dashboard for financial services, lending, and banking — portfolio overview, pipeline, collections, compliance",
+      "file": "financial-dashboard.json"
+    },
+    "recipe-community": {
+      "name": "Recipe Community",
+      "description": "AI-powered recipe sharing platform — recipes, cookbooks, photo-to-recipe AI, chef chat, community feed",
+      "file": "recipe-community.json"
+    }
+  }
+}