decantr 0.1.0

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.

package/README.md

@@ -0,0 +1,70 @@
+# decantr
+
+AI-first web framework. Zero dependencies. Native JS/CSS/HTML.
+
+Decantr is designed for LLMs to generate, read, and maintain — not for human readability. Every project follows predictable patterns with machine-readable manifests so AI agents can understand and modify code without parsing source files.
+
+## Quick Start
+
+```bash
+npx decantr init
+npm install
+npx decantr dev
+```
+
+## Features
+
+- **Zero dependencies** — Pure JavaScript, CSS, HTML
+- **Signal-based reactivity** — Fine-grained DOM updates, no virtual DOM
+- **Direct DOM rendering** — `h()` creates real elements, no diffing overhead
+- **Atomic CSS** — Terse, auto-generated utility classes (`p4`, `bg1`, `flex`)
+- **Dual router** — Hash or History API, user chooses at init
+- **Built-in test runner** — Wraps `node:test` with DOM testing helpers
+- **AI manifests** — `.decantr/` directory with JSON schemas for LLM consumption
+- **< 2KB gzipped** — Hello world JS runtime under 2KB gzipped
+
+## Architecture
+
+```
+decantr/core    — h(), text(), cond(), list(), mount()
+decantr/state   — createSignal, createEffect, createMemo, createStore, batch
+decantr/router  — createRouter, link, navigate, useRoute
+decantr/css     — css(), define()
+decantr/test    — render, fire, flush + node:test re-exports
+```
+
+## CLI Commands
+
+```bash
+decantr init          # Scaffold a new project
+decantr dev           # Start dev server with hot reload
+decantr build         # Production build
+decantr test          # Run tests
+decantr test --watch  # Run tests in watch mode
+```
+
+## Component Pattern
+
+Every component is a function that returns an HTMLElement:
+
+```javascript
+import { h, text } from 'decantr/core';
+import { createSignal } from 'decantr/state';
+
+export function Counter({ initial = 0 } = {}) {
+  const [count, setCount] = createSignal(initial);
+  return h('div', { class: 'flex gap2 p4' },
+    h('button', { onclick: () => setCount(c => c - 1) }, '-'),
+    h('span', null, text(() => String(count()))),
+    h('button', { onclick: () => setCount(c => c + 1) }, '+')
+  );
+}
+```
+
+## Requirements
+
+- Node.js >= 22.0.0
+
+## License
+
+MIT

package/cli/commands/build.js

@@ -0,0 +1,17 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+export async function run() {
+  const cwd = process.cwd();
+  let config = { build: { outDir: 'dist', inline: false, sourcemap: false } };
+
+  try {
+    const raw = await readFile(join(cwd, 'decantr.config.json'), 'utf-8');
+    config = JSON.parse(raw);
+  } catch (e) {
+    // Use defaults
+  }
+
+  const { build } = await import('../../tools/builder.js');
+  await build(cwd, config.build || {});
+}

package/cli/commands/dev.js

@@ -0,0 +1,18 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+export async function run() {
+  const cwd = process.cwd();
+  let config = { dev: { port: 3000 } };
+
+  try {
+    const raw = await readFile(join(cwd, 'decantr.config.json'), 'utf-8');
+    config = JSON.parse(raw);
+  } catch (e) {
+    // Use defaults
+  }
+
+  const port = config.dev?.port || 3000;
+  const { startDevServer } = await import('../../tools/dev-server.js');
+  startDevServer(cwd, port);
+}

package/cli/commands/init.js

@@ -0,0 +1,247 @@
+import { createInterface } from 'node:readline/promises';
+import { stdin, stdout } from 'node:process';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join, basename } from 'node:path';
+
+const templates = {
+  packageJson: (name) => JSON.stringify({
+    name,
+    version: '0.1.0',
+    type: 'module',
+    scripts: {
+      dev: 'decantr dev',
+      build: 'decantr build',
+      test: 'decantr test'
+    },
+    dependencies: {
+      decantr: '^0.1.0'
+    }
+  }, null, 2),
+
+  config: (name, routerMode, port) => JSON.stringify({
+    $schema: 'https://decantr.ai/schemas/config.v1.json',
+    name,
+    router: routerMode,
+    dev: { port },
+    build: { outDir: 'dist', inline: false, sourcemap: false }
+  }, null, 2),
+
+  indexHtml: (name) => `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width,initial-scale=1">
+  <title>${name}</title>
+  <style>:root{--c0:#111;--c1:#2563eb;--c2:#f8fafc;--c3:#e2e8f0;--c4:#94a3b8;--c5:#475569;--c6:#1e293b;--c7:#f59e0b;--c8:#10b981;--c9:#ef4444}*{margin:0;box-sizing:border-box}body{font-family:system-ui,-apple-system,sans-serif;color:var(--c0);background:var(--c2)}</style>
+</head>
+<body>
+  <div id="app"></div>
+  <script type="module" src="/src/app.js"></script>
+</body>
+</html>`,
+
+  appJs: (routerMode, includeCounter) => `import { h, mount } from 'decantr/core';
+import { createRouter, link } from 'decantr/router';
+import { Home } from './pages/home.js';
+import { About } from './pages/about.js';
+
+const router = createRouter({
+  mode: '${routerMode}',
+  routes: [
+    { path: '/', component: Home },
+    { path: '/about', component: About }
+  ]
+});
+
+function App() {
+  return h('div', null,
+    h('nav', { class: 'flex gap4 p4 bg1' },
+      link({ href: '/', class: 'fg2 nounder' }, 'Home'),
+      link({ href: '/about', class: 'fg2 nounder' }, 'About')
+    ),
+    router.outlet()
+  );
+}
+
+mount(document.getElementById('app'), App);
+`,
+
+  homeJs: (includeCounter) => `import { h } from 'decantr/core';
+${includeCounter ? "import { Counter } from '../components/counter.js';\n" : ''}
+/** @returns {HTMLElement} */
+export function Home() {
+  return h('main', { class: 'p8' },
+    h('h1', { class: 't32 bold' }, 'Welcome to Decantr'),
+    h('p', { class: 'py4 fg5' }, 'AI-first web framework. Zero dependencies.')${includeCounter ? ',\n    h(\'div\', { class: \'py4\' }, Counter({ initial: 0 }))' : ''}
+  );
+}
+`,
+
+  aboutJs: () => `import { h } from 'decantr/core';
+
+/** @returns {HTMLElement} */
+export function About() {
+  return h('main', { class: 'p8' },
+    h('h1', { class: 't32 bold' }, 'About'),
+    h('p', { class: 'py4 fg5' }, 'Built with Decantr — the AI-first framework.')
+  );
+}
+`,
+
+  counterJs: () => `import { h, text } from 'decantr/core';
+import { createSignal } from 'decantr/state';
+
+/**
+ * @param {{ initial?: number }} props
+ * @returns {HTMLElement}
+ */
+export function Counter({ initial = 0 } = {}) {
+  const [count, setCount] = createSignal(initial);
+
+  return h('div', { class: 'flex gap2 p4 aic' },
+    h('button', { onclick: () => setCount(c => c - 1), class: 'p2 px4 r2 bg1 fg2 pointer b0 t16' }, '-'),
+    h('span', { class: 'p2 t20 bold' }, text(() => String(count()))),
+    h('button', { onclick: () => setCount(c => c + 1), class: 'p2 px4 r2 bg1 fg2 pointer b0 t16' }, '+')
+  );
+}
+`,
+
+  counterTestJs: () => `import { describe, it, assert, render, fire, flush } from 'decantr/test';
+import { Counter } from '../src/components/counter.js';
+
+describe('Counter', () => {
+  it('renders with initial value', () => {
+    const { container } = render(() => Counter({ initial: 5 }));
+    assert.ok(container.textContent.includes('5'));
+  });
+
+  it('increments on + click', async () => {
+    const { container, getByText } = render(() => Counter({ initial: 0 }));
+    fire(getByText('+'), 'click');
+    await flush();
+    assert.ok(container.textContent.includes('1'));
+  });
+
+  it('decrements on - click', async () => {
+    const { container, getByText } = render(() => Counter({ initial: 5 }));
+    fire(getByText('-'), 'click');
+    await flush();
+    assert.ok(container.textContent.includes('4'));
+  });
+});
+`,
+
+  manifest: (name, routerMode) => JSON.stringify({
+    $schema: 'https://decantr.ai/schemas/manifest.v1.json',
+    version: '0.1.0',
+    name,
+    router: routerMode,
+    entrypoint: 'src/app.js',
+    shell: 'public/index.html',
+    mountTarget: '#app',
+    components: '.decantr/components.json',
+    routes: '.decantr/routes.json',
+    state: '.decantr/state.json'
+  }, null, 2),
+
+  components: (includeCounter) => JSON.stringify({
+    $schema: 'https://decantr.ai/schemas/components.v1.json',
+    components: includeCounter ? [{
+      id: 'counter',
+      file: 'src/components/counter.js',
+      exportName: 'Counter',
+      description: 'Increment/decrement counter with display',
+      props: [{ name: 'initial', type: 'number', default: 0, required: false }],
+      signals: ['count'],
+      effects: [],
+      children: false
+    }] : []
+  }, null, 2),
+
+  routes: (routerMode) => JSON.stringify({
+    $schema: 'https://decantr.ai/schemas/routes.v1.json',
+    mode: routerMode,
+    routes: [
+      { path: '/', component: 'home', file: 'src/pages/home.js', exportName: 'Home', title: 'Home' },
+      { path: '/about', component: 'about', file: 'src/pages/about.js', exportName: 'About', title: 'About' }
+    ]
+  }, null, 2),
+
+  state: (includeCounter) => JSON.stringify({
+    $schema: 'https://decantr.ai/schemas/state.v1.json',
+    signals: includeCounter ? [{
+      id: 'count',
+      file: 'src/components/counter.js',
+      type: 'number',
+      initial: 0,
+      usedBy: ['Counter']
+    }] : [],
+    effects: [],
+    memos: []
+  }, null, 2)
+};
+
+async function ask(rl, question, defaultVal) {
+  const answer = await rl.question(`${question} (${defaultVal}): `);
+  return answer.trim() || defaultVal;
+}
+
+async function askChoice(rl, question, options, defaultVal) {
+  console.log(`\n${question}`);
+  options.forEach((opt, i) => console.log(`  ${i + 1}) ${opt}`));
+  const answer = await rl.question(`Choose [${defaultVal}]: `);
+  const idx = parseInt(answer.trim()) - 1;
+  return (idx >= 0 && idx < options.length) ? options[idx] : defaultVal;
+}
+
+export async function run() {
+  const rl = createInterface({ input: stdin, output: stdout });
+  const cwd = process.cwd();
+
+  console.log('\n  decantr init — Create a new project\n');
+
+  try {
+    const name = await ask(rl, 'Project name?', basename(cwd));
+    const routerMode = await askChoice(rl, 'Router mode?', ['history', 'hash'], 'history');
+    const includeCounterAnswer = await askChoice(rl, 'Include example counter component?', ['yes', 'no'], 'yes');
+    const includeCounter = includeCounterAnswer === 'yes';
+    const port = parseInt(await ask(rl, 'Dev server port?', '3000'));
+
+    // Create directories
+    const dirs = ['src/pages', 'src/components', 'public', '.decantr', 'test'];
+    for (const dir of dirs) {
+      await mkdir(join(cwd, dir), { recursive: true });
+    }
+
+    // Write files
+    const files = [
+      ['package.json', templates.packageJson(name)],
+      ['decantr.config.json', templates.config(name, routerMode, port)],
+      ['public/index.html', templates.indexHtml(name)],
+      ['src/app.js', templates.appJs(routerMode, includeCounter)],
+      ['src/pages/home.js', templates.homeJs(includeCounter)],
+      ['src/pages/about.js', templates.aboutJs()],
+      ['.decantr/manifest.json', templates.manifest(name, routerMode)],
+      ['.decantr/components.json', templates.components(includeCounter)],
+      ['.decantr/routes.json', templates.routes(routerMode)],
+      ['.decantr/state.json', templates.state(includeCounter)]
+    ];
+
+    if (includeCounter) {
+      files.push(['src/components/counter.js', templates.counterJs()]);
+      files.push(['test/counter.test.js', templates.counterTestJs()]);
+    }
+
+    for (const [path, content] of files) {
+      await writeFile(join(cwd, path), content + '\n');
+    }
+
+    console.log(`\n  Project "${name}" created successfully!\n`);
+    console.log('  Next steps:');
+    console.log('    npm install');
+    console.log('    npx decantr dev\n');
+
+  } finally {
+    rl.close();
+  }
+}

package/cli/commands/test.js

@@ -0,0 +1,38 @@
+import { spawn } from 'node:child_process';
+import { glob } from 'node:fs';
+import { join } from 'node:path';
+
+export async function run() {
+  const cwd = process.cwd();
+  const args = process.argv.slice(3);
+  const watch = args.includes('--watch');
+
+  const testArgs = ['--test'];
+  if (watch) testArgs.push('--watch');
+
+  // Find test files
+  const testFiles = [];
+  const pattern = join(cwd, 'test', '**', '*.test.js');
+
+  // Use node:fs glob (Node 22+)
+  const { glob: fsGlob } = await import('node:fs/promises');
+  for await (const file of fsGlob(pattern)) {
+    testFiles.push(file);
+  }
+
+  if (testFiles.length === 0) {
+    console.log('No test files found in test/**/*.test.js');
+    return;
+  }
+
+  testArgs.push(...testFiles);
+
+  const child = spawn('node', testArgs, {
+    cwd,
+    stdio: 'inherit'
+  });
+
+  child.on('exit', (code) => {
+    process.exit(code || 0);
+  });
+}

package/cli/index.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+
+import { parseArgs } from 'node:util';
+
+const { positionals } = parseArgs({ allowPositionals: true, strict: false });
+const command = positionals[0];
+
+switch (command) {
+  case 'init':
+    await import('./commands/init.js').then(m => m.run());
+    break;
+  case 'dev':
+    await import('./commands/dev.js').then(m => m.run());
+    break;
+  case 'build':
+    await import('./commands/build.js').then(m => m.run());
+    break;
+  case 'test':
+    await import('./commands/test.js').then(m => m.run());
+    break;
+  default:
+    console.log(`
+  decantr v0.1.0 — AI-first web framework
+
+  Commands:
+    init     Create a new decantr project
+    dev      Start development server
+    build    Build for production
+    test     Run tests
+
+  Usage:
+    npx decantr init
+    npx decantr dev
+    npx decantr build
+    npx decantr test [--watch]
+`);
+    break;
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "decantr",
+  "version": "0.1.0",
+  "description": "AI-first web framework. Zero dependencies. Native JS/CSS/HTML.",
+  "type": "module",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "bin": {
+    "decantr": "./cli/index.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./src/core/index.js"
+    },
+    "./core": {
+      "import": "./src/core/index.js"
+    },
+    "./state": {
+      "import": "./src/state/index.js"
+    },
+    "./router": {
+      "import": "./src/router/index.js"
+    },
+    "./css": {
+      "import": "./src/css/index.js"
+    },
+    "./test": {
+      "import": "./src/test/index.js"
+    }
+  },
+  "files": [
+    "src/",
+    "cli/",
+    "tools/"
+  ],
+  "scripts": {
+    "test": "node --test test/**/*.test.js"
+  },
+  "keywords": [
+    "framework",
+    "ai",
+    "llm",
+    "web",
+    "signals",
+    "zero-dependency"
+  ],
+  "license": "MIT",
+  "author": "David Aimi",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/david-aimi/decantr"
+  },
+  "homepage": "https://decantr.ai"
+}

package/src/core/index.js

@@ -0,0 +1,176 @@
+import { createEffect } from '../state/index.js';
+export { onMount, onDestroy } from './lifecycle.js';
+import { drainMountQueue, drainDestroyQueue } from './lifecycle.js';
+
+/**
+ * @param {string} tag
+ * @param {Object|null} props
+ * @param {...(string|number|Node|Function)} children
+ * @returns {HTMLElement}
+ */
+export function h(tag, props, ...children) {
+  const el = document.createElement(tag);
+
+  if (props) {
+    for (const key in props) {
+      const val = props[key];
+      if (key.startsWith('on') && typeof val === 'function') {
+        el.addEventListener(key.slice(2).toLowerCase(), val);
+      } else if (typeof val === 'function' && key !== 'ref') {
+        createEffect(() => {
+          const v = val();
+          if (key === 'class' || key === 'className') {
+            el.className = v;
+          } else if (key === 'style' && typeof v === 'object') {
+            Object.assign(el.style, v);
+          } else {
+            el.setAttribute(key, v);
+          }
+        });
+      } else if (key === 'ref' && typeof val === 'function') {
+        val(el);
+      } else if (key === 'class' || key === 'className') {
+        el.className = val;
+      } else if (key === 'style' && typeof val === 'object') {
+        Object.assign(el.style, val);
+      } else if (val !== false && val != null) {
+        el.setAttribute(key, val === true ? '' : String(val));
+      }
+    }
+  }
+
+  appendChildren(el, children);
+  return el;
+}
+
+/**
+ * @param {Function} getter
+ * @returns {Text}
+ */
+export function text(getter) {
+  const node = document.createTextNode('');
+  createEffect(() => {
+    node.nodeValue = String(getter());
+  });
+  return node;
+}
+
+/**
+ * @param {Function} condition
+ * @param {Function} thenFn
+ * @param {Function} [elseFn]
+ * @returns {HTMLElement}
+ */
+export function cond(condition, thenFn, elseFn) {
+  const container = document.createElement('d-cond');
+  let currentNode = null;
+
+  createEffect(() => {
+    const result = condition();
+    if (currentNode) {
+      container.removeChild(currentNode);
+      currentNode = null;
+    }
+    const fn = result ? thenFn : elseFn;
+    if (fn) {
+      currentNode = fn();
+      if (currentNode) container.appendChild(currentNode);
+    }
+  });
+
+  return container;
+}
+
+/**
+ * @param {Function} itemsGetter
+ * @param {Function} keyFn
+ * @param {Function} renderFn
+ * @returns {HTMLElement}
+ */
+export function list(itemsGetter, keyFn, renderFn) {
+  const container = document.createElement('d-list');
+  /** @type {Map<*, {node: Node}>} */
+  let currentMap = new Map();
+
+  createEffect(() => {
+    const items = itemsGetter();
+    const newMap = new Map();
+    const newNodes = [];
+
+    for (let i = 0; i < items.length; i++) {
+      const item = items[i];
+      const key = keyFn(item, i);
+      const existing = currentMap.get(key);
+
+      if (existing) {
+        newMap.set(key, existing);
+        newNodes.push(existing.node);
+      } else {
+        const node = renderFn(item, i);
+        newMap.set(key, { node });
+        newNodes.push(node);
+      }
+    }
+
+    // Remove nodes no longer in list
+    for (const [key, entry] of currentMap) {
+      if (!newMap.has(key) && entry.node.parentNode === container) {
+        container.removeChild(entry.node);
+      }
+    }
+
+    // Append/reorder
+    for (let i = 0; i < newNodes.length; i++) {
+      const node = newNodes[i];
+      const current = container.childNodes[i];
+      if (node !== current) {
+        container.insertBefore(node, current || null);
+      }
+    }
+
+    currentMap = newMap;
+  });
+
+  return container;
+}
+
+/**
+ * @param {HTMLElement} root
+ * @param {Function} component
+ */
+export function mount(root, component) {
+  const result = component();
+  if (result) root.appendChild(result);
+  // Flush mount queue
+  const fns = drainMountQueue();
+  for (const fn of fns) {
+    const cleanup = fn();
+    if (typeof cleanup === 'function') {
+      // store cleanup for later
+    }
+  }
+}
+
+/**
+ * @param {HTMLElement} el
+ * @param {Array} children
+ */
+function appendChildren(el, children) {
+  for (let i = 0; i < children.length; i++) {
+    const child = children[i];
+    if (child == null || child === false) continue;
+    if (Array.isArray(child)) {
+      appendChildren(el, child);
+    } else if (child && typeof child === 'object' && child.nodeType) {
+      el.appendChild(child);
+    } else if (typeof child === 'function') {
+      const textNode = document.createTextNode('');
+      createEffect(() => {
+        textNode.nodeValue = String(child());
+      });
+      el.appendChild(textNode);
+    } else {
+      el.appendChild(document.createTextNode(String(child)));
+    }
+  }
+}