create-vanillaforge 1.0.0

package/bin/cli.js

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+/**
+ * create-vanillaforge — project scaffolder
+ *
+ * Usage:
+ *   npx create-vanillaforge <project-name> [--template=<name>]
+ *
+ * Templates: minimal | full | todo-app | router-app
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { createInterface } from 'readline';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const TEMPLATES_DIR = path.join(__dirname, '..', 'templates');
+
+const TEMPLATES = [
+  {
+    name: 'minimal',
+    label: 'Minimal',
+    description: 'counter app, no plugins — best starting point',
+  },
+  {
+    name: 'full',
+    label: 'Full',
+    description: 'all plugins: icons, theme, alerts, fonts, store',
+  },
+  {
+    name: 'todo-app',
+    label: 'Todo App',
+    description: 'task list with filtering and localStorage',
+  },
+  {
+    name: 'router-app',
+    label: 'Router App',
+    description: 'multi-page app with routing and composition',
+  },
+];
+
+// ---------------------------------------------------------------------------
+// Argument parsing
+// ---------------------------------------------------------------------------
+
+function parseArgs(argv) {
+  const args = argv.slice(2);
+  let projectName = null;
+  let template = null;
+
+  for (const arg of args) {
+    if (arg.startsWith('--template=')) {
+      template = arg.slice('--template='.length);
+    } else if (!arg.startsWith('--')) {
+      projectName = arg;
+    }
+  }
+
+  return { projectName, template };
+}
+
+// ---------------------------------------------------------------------------
+// Prompt helpers
+// ---------------------------------------------------------------------------
+
+function ask(rl, question) {
+  return new Promise((resolve) => rl.question(question, resolve));
+}
+
+async function promptProjectName(rl) {
+  const answer = await ask(rl, 'Project name: ');
+  const name = answer.trim();
+  if (!name) {
+    console.error('Error: project name is required.');
+    process.exit(1);
+  }
+  return name;
+}
+
+async function promptTemplate(rl) {
+  console.log('\nWhich template would you like to use?\n');
+  TEMPLATES.forEach((t, i) => {
+    const num = String(i + 1).padStart(2);
+    console.log(`  ${num})  ${t.label.padEnd(12)} ${t.description}`);
+  });
+  console.log('');
+  const answer = await ask(rl, 'Template (1): ');
+  const index = (parseInt(answer.trim(), 10) || 1) - 1;
+  if (index < 0 || index >= TEMPLATES.length) {
+    console.error(`Error: invalid selection "${answer.trim()}".`);
+    process.exit(1);
+  }
+  return TEMPLATES[index].name;
+}
+
+// ---------------------------------------------------------------------------
+// File copy
+// ---------------------------------------------------------------------------
+
+function copyDir(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+function rewriteFile(filePath, replacements) {
+  let content = fs.readFileSync(filePath, 'utf8');
+  for (const [from, to] of replacements) {
+    content = content.split(from).join(to);
+  }
+  fs.writeFileSync(filePath, content, 'utf8');
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main() {
+  const { projectName: argName, template: argTemplate } = parseArgs(process.argv);
+
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+
+  const projectName = argName || (await promptProjectName(rl));
+  const template = argTemplate || (await promptTemplate(rl));
+
+  rl.close();
+
+  if (!TEMPLATES.find((t) => t.name === template)) {
+    console.error(`Error: unknown template "${template}". Choose from: ${TEMPLATES.map((t) => t.name).join(', ')}`);
+    process.exit(1);
+  }
+
+  const targetDir = path.resolve(process.cwd(), projectName);
+
+  if (fs.existsSync(targetDir)) {
+    console.error(`Error: directory "${projectName}" already exists.`);
+    process.exit(1);
+  }
+
+  const templateDir = path.join(TEMPLATES_DIR, template);
+  copyDir(templateDir, targetDir);
+
+  // Patch the app name into the generated files
+  const htmlPath = path.join(targetDir, 'index.html');
+  if (fs.existsSync(htmlPath)) {
+    rewriteFile(htmlPath, [['{{project-name}}', projectName]]);
+  }
+
+  const pkgPath = path.join(targetDir, 'package.json');
+  if (fs.existsSync(pkgPath)) {
+    rewriteFile(pkgPath, [['{{project-name}}', projectName]]);
+  }
+
+  console.log(`\nScaffolded "${projectName}" with the "${template}" template.\n`);
+  console.log('Next steps:\n');
+  console.log(`  cd ${projectName}`);
+  console.log('  npm install');
+  console.log('  npm run dev\n');
+  console.log('No build step needed for development. Open http://localhost:3000\n');
+}
+
+main().catch((err) => {
+  console.error(err.message || err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "create-vanillaforge",
+  "version": "1.0.0",
+  "description": "Scaffold a new VanillaForge project",
+  "type": "module",
+  "bin": {
+    "create-vanillaforge": "./bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "templates/"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "vanillaforge",
+    "scaffold",
+    "create-app",
+    "spa"
+  ],
+  "author": "Stephen Musyoka (https://github.com/Steve-GitCodex)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Steve-GitCodex/vanillaforge.git",
+    "directory": "create-vanillaforge"
+  }
+}

package/templates/full/index.html

@@ -0,0 +1,19 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>{{project-name}}</title>
+  <script type="importmap">
+  {
+    "imports": {
+      "vanillaforge": "./node_modules/vanillaforge/src/framework.js"
+    }
+  }
+  </script>
+</head>
+<body>
+  <div id="main-content"></div>
+  <script type="module" src="./src/app.js"></script>
+</body>
+</html>

package/templates/full/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "{{project-name}}",
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "npx http-server . -p 3000 -c-1 --cors -o"
+  },
+  "dependencies": {
+    "vanillaforge": "^1.9.0"
+  }
+}

package/templates/full/src/app.js

@@ -0,0 +1,25 @@
+import {
+  createApp,
+  iconsPlugin,
+  themePlugin,
+  alertsPlugin,
+  fontsPlugin,
+  storePlugin,
+} from 'vanillaforge';
+import { HomeComponent } from './components/home.js';
+
+const app = createApp({ appName: '{{project-name}}' });
+
+app.use(themePlugin, {
+  tokens: { primary: '#3b82f6', radius: '8px' },
+});
+app.use(iconsPlugin);
+app.use(alertsPlugin);
+app.use(fontsPlugin, { families: ['Inter'] });
+app.use(storePlugin);
+
+await app.initialize({
+  routes: { '/': HomeComponent },
+});
+
+await app.start();

package/templates/full/src/components/home.js

@@ -0,0 +1,70 @@
+import { BaseComponent } from 'vanillaforge';
+
+export class HomeComponent extends BaseComponent {
+  constructor(eventBus, props) {
+    super(eventBus, props);
+    this.name = 'home';
+    this.state = { count: 0 };
+    this._unsub = null;
+  }
+
+  async onInit() {
+    const store = this.service('store');
+    const saved = store.get('count') ?? 0;
+    this.state = { count: saved };
+    this._unsub = store.subscribe('count', (value) => {
+      this.setState({ count: value ?? 0 });
+    });
+  }
+
+  getLifecycle() {
+    return {
+      onUnmount: () => this._unsub?.(),
+    };
+  }
+
+  getTemplate() {
+    return `
+      <div style="max-width:520px;margin:80px auto;text-align:center">
+        <h1 style="margin-bottom:8px">{{project-name}}</h1>
+        <p style="color:var(--vf-text-muted);margin-bottom:32px">
+          Count: <strong>${this.state.count}</strong>
+        </p>
+        <div style="display:flex;gap:12px;justify-content:center">
+          <button class="vf-btn vf-btn-primary" data-action="increment">
+            ${this.icon('plus', { size: 16 })} Increment
+          </button>
+          <button class="vf-btn vf-btn-secondary" data-action="showInfo">
+            ${this.icon('info', { size: 16 })} Info
+          </button>
+          <button class="vf-btn vf-btn-danger" data-action="reset">
+            ${this.icon('close', { size: 16 })} Reset
+          </button>
+        </div>
+      </div>`;
+  }
+
+  getMethods() {
+    return {
+      increment: () => {
+        const store = this.service('store');
+        store.set('count', (store.get('count') ?? 0) + 1);
+      },
+
+      reset: async () => {
+        const alerts = this.service('alerts');
+        const ok = await alerts.confirm('Reset the counter to zero?', { danger: true });
+        if (ok) {
+          this.service('store').set('count', 0);
+          alerts.success('Counter reset.');
+        }
+      },
+
+      showInfo: () => {
+        this.service('alerts').info(
+          'Built with VanillaForge — icons, theme, alerts, fonts, and store. Zero external dependencies.'
+        );
+      },
+    };
+  }
+}

package/templates/minimal/index.html

@@ -0,0 +1,19 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>{{project-name}}</title>
+  <script type="importmap">
+  {
+    "imports": {
+      "vanillaforge": "./node_modules/vanillaforge/src/framework.js"
+    }
+  }
+  </script>
+</head>
+<body>
+  <div id="main-content"></div>
+  <script type="module" src="./src/app.js"></script>
+</body>
+</html>

package/templates/minimal/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "{{project-name}}",
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "npx http-server . -p 3000 -c-1 --cors -o"
+  },
+  "dependencies": {
+    "vanillaforge": "^1.9.0"
+  }
+}

package/templates/minimal/src/app.js

@@ -0,0 +1,35 @@
+import { createApp, BaseComponent } from 'vanillaforge';
+
+class HomeComponent extends BaseComponent {
+  constructor(eventBus, props) {
+    super(eventBus, props);
+    this.name = 'home';
+    this.state = { count: 0 };
+  }
+
+  getTemplate() {
+    return `
+      <div style="font-family:system-ui;max-width:480px;margin:80px auto;text-align:center">
+        <h1>VanillaForge</h1>
+        <p style="color:#666;margin-bottom:32px">Count: <strong>${this.state.count}</strong></p>
+        <button data-action="increment"
+          style="padding:10px 24px;border:none;border-radius:6px;background:#3b82f6;color:#fff;cursor:pointer;font-size:1rem">
+          Increment
+        </button>
+      </div>`;
+  }
+
+  getMethods() {
+    return {
+      increment: () => this.setState({ count: this.state.count + 1 }),
+    };
+  }
+}
+
+const app = createApp({ appName: '{{project-name}}' });
+
+await app.initialize({
+  routes: { '/': HomeComponent },
+});
+
+await app.start();

package/templates/router-app/index.html

@@ -0,0 +1,85 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>{{project-name}}</title>
+  <script type="importmap">
+  {
+    "imports": {
+      "vanillaforge": "./node_modules/vanillaforge/src/framework.js"
+    }
+  }
+  </script>
+  <style>
+    body { padding: 40px 20px; font-family: var(--vf-font-sans, system-ui, sans-serif); }
+    .shell { max-width: 640px; margin: 0 auto; }
+    .topbar { display:flex; align-items:center; gap:12px; margin-bottom:24px; }
+    .topbar h2 { font-size:1.1rem; }
+    .muted { color:var(--vf-text-muted); font-size:.85rem; }
+
+    .user-list { list-style:none; margin-top:16px; }
+    .component.user-card { display:block; }
+    .user-card { border-top:1px solid var(--vf-border); }
+    .user-card:first-child { border-top:none; }
+    .user-card-row {
+      display:flex; align-items:center;
+      justify-content:space-between; padding:14px 4px;
+    }
+    .user-card-link {
+      display:flex; align-items:center; gap:12px;
+      text-decoration:none; color:inherit; flex:1;
+    }
+    .user-card-link:hover .user-card-name { color:var(--vf-primary); }
+    .user-card-avatar {
+      width:36px; height:36px; border-radius:50%;
+      background:var(--vf-primary); color:#fff;
+      display:flex; align-items:center; justify-content:center;
+      font-weight:700; font-size:.95rem; flex-shrink:0;
+    }
+    .user-card-name { display:block; font-weight:600; }
+    .user-card-role { font-size:.82rem; color:var(--vf-text-muted); }
+    .user-card-actions { display:flex; align-items:center; gap:2px; }
+    .user-card-toggle, .user-card-remove {
+      background:none; border:none; cursor:pointer;
+      color:var(--vf-text-muted); padding:4px;
+      border-radius:var(--vf-radius-sm); display:flex; align-items:center;
+    }
+    .user-card-toggle:hover { background:var(--vf-border); color:var(--vf-text); }
+    .user-card-remove:hover { background:#fef2f2; color:var(--vf-danger,#ef4444); }
+    .user-card-bio {
+      padding:0 4px 14px 4px; color:var(--vf-text); font-size:.92rem; line-height:1.55;
+    }
+    .user-card-bio p { margin-bottom:10px; }
+    .user-card-detail-link {
+      display:inline-flex; align-items:center; gap:4px;
+      color:var(--vf-primary); text-decoration:none;
+      font-weight:600; font-size:.88rem;
+    }
+    .user-card-detail-link:hover { text-decoration:underline; }
+    .detail-header { display:flex; align-items:center; gap:16px; margin:16px 0; }
+    .detail-avatar {
+      width:56px; height:56px; border-radius:50%;
+      background:var(--vf-primary); color:#fff;
+      display:flex; align-items:center; justify-content:center;
+      font-weight:700; font-size:1.4rem; flex-shrink:0;
+    }
+    .back-link {
+      display:inline-flex; align-items:center; gap:6px;
+      margin-bottom:16px; color:var(--vf-primary);
+      text-decoration:none; font-weight:600;
+    }
+    .back-link:hover { text-decoration:underline; }
+  </style>
+</head>
+<body>
+  <div class="shell">
+    <div class="topbar">
+      <h2>{{project-name}}</h2>
+      <span class="muted">· routing + composition + icons + alerts</span>
+    </div>
+    <div id="main-content"></div>
+  </div>
+  <script type="module" src="./src/app.js"></script>
+</body>
+</html>

package/templates/router-app/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "{{project-name}}",
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "npx http-server . -p 3000 -c-1 --cors -o"
+  },
+  "dependencies": {
+    "vanillaforge": "^1.9.0"
+  }
+}

package/templates/router-app/src/app.js

@@ -0,0 +1,29 @@
+import { createApp, iconsPlugin, themePlugin, alertsPlugin } from 'vanillaforge';
+import { UsersList } from './components/users-list.js';
+import { UserDetail } from './components/user-detail.js';
+import { getUser } from './data/users.js';
+
+const basePath = window.location.pathname
+  .replace(/\/[^/]*\.[^/]*$/, '')
+  .replace(/\/$/, '');
+
+const app = createApp({
+  appName: '{{project-name}}',
+  router: { basePath },
+});
+
+app.use(themePlugin, { tokens: { primary: '#3b82f6', radius: '8px' } });
+app.use(iconsPlugin);
+app.use(alertsPlugin);
+
+await app.initialize({
+  routes: {
+    '/': UsersList,
+    '/users/:id': {
+      component: UserDetail,
+      loader: async ({ params }) => getUser(params.id),
+    },
+  },
+});
+
+await app.start();

package/templates/router-app/src/components/user-card.js

@@ -0,0 +1,65 @@
+import { BaseComponent } from 'vanillaforge';
+
+export class UserCard extends BaseComponent {
+  constructor(eventBus, props = {}) {
+    super(eventBus, props);
+    this.name = 'user-card';
+    this.state = { expanded: false };
+  }
+
+  getTemplate() {
+    const { user } = this.props;
+    const { expanded } = this.state;
+
+    return `
+      <li class="user-card" data-expanded="${expanded}">
+        <div class="user-card-row">
+          <a class="user-card-link" href="/users/${user.id}">
+            <div class="user-card-avatar">${user.name.charAt(0)}</div>
+            <div>
+              <strong class="user-card-name">${user.name}</strong>
+              <span class="user-card-role">${user.role}</span>
+            </div>
+          </a>
+          <div class="user-card-actions">
+            <button class="user-card-toggle" data-action="toggle"
+              title="${expanded ? 'Collapse' : 'Expand'}">
+              ${this.icon(expanded ? 'chevron-up' : 'chevron-down', { size: 18 })}
+            </button>
+            <button class="user-card-remove" data-action="remove"
+              title="Remove ${user.name}">
+              ${this.icon('trash', { size: 15 })}
+            </button>
+          </div>
+        </div>
+        ${expanded ? `
+          <div class="user-card-bio">
+            <p>${user.bio}</p>
+            <a class="user-card-detail-link" href="/users/${user.id}">
+              Full profile ${this.icon('arrow-right', { size: 14 })}
+            </a>
+          </div>` : ''}
+      </li>`;
+  }
+
+  getMethods() {
+    return {
+      toggle: () => this.setState({ expanded: !this.state.expanded }),
+
+      remove: () => {
+        const { user } = this.props;
+        const alerts = this.service('alerts');
+        if (!alerts) return;
+        alerts.confirm(`Remove ${user.name} from the list?`, {
+          title: 'Remove user',
+          confirmText: 'Remove',
+          danger: true,
+          onConfirm: () => {
+            alerts.success(`${user.name} removed`);
+            this.eventBus.emit('user:remove', { id: user.id });
+          },
+        });
+      },
+    };
+  }
+}

package/templates/router-app/src/components/user-detail.js

@@ -0,0 +1,42 @@
+import { BaseComponent } from 'vanillaforge';
+
+export class UserDetail extends BaseComponent {
+  constructor(eventBus, props = {}) {
+    super(eventBus, props);
+    this.name = 'user-detail';
+  }
+
+  get user() {
+    return this.props.data ?? null;
+  }
+
+  getTemplate() {
+    const user = this.user;
+
+    if (!user) {
+      return `
+        <section class="vf-card">
+          <h1>Not found</h1>
+          <p class="muted">No person with that id.</p>
+          <a class="back-link" href="/">
+            ${this.icon('arrow-left', { size: 16 })} Back to people
+          </a>
+        </section>`;
+    }
+
+    return `
+      <section class="vf-card">
+        <a class="back-link" href="/">
+          ${this.icon('arrow-left', { size: 16 })} Back to people
+        </a>
+        <div class="detail-header">
+          <div class="detail-avatar">${user.name.charAt(0)}</div>
+          <div>
+            <h1>${user.name}</h1>
+            <p style="color:var(--vf-primary);font-weight:600;margin-top:2px">${user.role}</p>
+          </div>
+        </div>
+        <p>${user.bio}</p>
+      </section>`;
+  }
+}

package/templates/router-app/src/components/users-list.js

@@ -0,0 +1,41 @@
+import { BaseComponent } from 'vanillaforge';
+import { UserCard } from './user-card.js';
+import { users as initialUsers } from '../data/users.js';
+
+export class UsersList extends BaseComponent {
+  constructor(eventBus, props = {}) {
+    super(eventBus, props);
+    this.name = 'users-list';
+    this.state = { users: [...initialUsers] };
+  }
+
+  async onInit() {
+    this.eventBus.on('user:remove', ({ id }) => {
+      this.setState({ users: this.state.users.filter((u) => u.id !== id) });
+    });
+  }
+
+  getTemplate() {
+    const { users } = this.state;
+
+    if (users.length === 0) {
+      return `
+        <section class="vf-card">
+          <h1>People</h1>
+          <p class="muted" style="margin-top:16px">No users left in the list.</p>
+        </section>`;
+    }
+
+    return `
+      <section class="vf-card">
+        <h1>People</h1>
+        <p class="muted">
+          ${this.icon('info', { size: 14 })}
+          Click a name to view the full profile, or use the toggle to expand.
+        </p>
+        <ul class="user-list">
+          ${users.map((u) => this.child(UserCard, { user: u }, u.id)).join('')}
+        </ul>
+      </section>`;
+  }
+}

package/templates/router-app/src/data/users.js

@@ -0,0 +1,10 @@
+export const users = [
+  { id: 1, name: 'Ada Lovelace',  role: 'Mathematician',       bio: 'Wrote the first algorithm intended for a machine.' },
+  { id: 2, name: 'Alan Turing',   role: 'Computer Scientist',  bio: 'Formalised computation and the Turing machine.' },
+  { id: 3, name: 'Grace Hopper',  role: 'Engineer',            bio: 'Pioneered machine-independent programming languages.' },
+  { id: 4, name: 'Dennis Ritchie',role: 'Programmer',          bio: 'Created the C language and co-created Unix.' },
+];
+
+export function getUser(id) {
+  return users.find((u) => u.id === Number(id)) || null;
+}

package/templates/todo-app/index.html

@@ -0,0 +1,32 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>{{project-name}}</title>
+  <script type="importmap">
+  {
+    "imports": {
+      "vanillaforge": "./node_modules/vanillaforge/src/framework.js"
+    }
+  }
+  </script>
+  <style>
+    *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+    body {
+      font-family: var(--vf-font-sans, system-ui, sans-serif);
+      background: var(--vf-background, #f4f5f7);
+      color: var(--vf-text, #0f172a);
+      min-height: 100vh;
+      padding: 48px 20px;
+    }
+    .app-shell { max-width: 600px; margin: 0 auto; }
+  </style>
+</head>
+<body>
+  <div class="app-shell">
+    <div id="main-content"></div>
+  </div>
+  <script type="module" src="./src/app.js"></script>
+</body>
+</html>

package/templates/todo-app/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "{{project-name}}",
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "npx http-server . -p 3000 -c-1 --cors -o"
+  },
+  "dependencies": {
+    "vanillaforge": "^1.9.0"
+  }
+}

package/templates/todo-app/src/app.js

@@ -0,0 +1,15 @@
+import { createApp, themePlugin, iconsPlugin, alertsPlugin } from 'vanillaforge';
+import { TodoApp } from './components/todo-app.js';
+
+const app = createApp({ appName: '{{project-name}}' });
+
+app.use(themePlugin);
+app.use(iconsPlugin);
+app.use(alertsPlugin);
+
+await app.initialize({
+  routes: { '/': TodoApp },
+  components: { 'todo-app': TodoApp },
+});
+
+await app.start();

package/templates/todo-app/src/components/todo-app.js

@@ -0,0 +1,173 @@
+import { BaseComponent } from 'vanillaforge';
+
+export class TodoApp extends BaseComponent {
+  constructor(eventBus, props) {
+    super(eventBus, props);
+    this.name = 'todo-app';
+    this.state = {
+      todos: this._load(),
+      newTodo: '',
+      filter: 'all',
+    };
+  }
+
+  _load() {
+    try {
+      const saved = localStorage.getItem('vf-todos');
+      return saved ? JSON.parse(saved) : [];
+    } catch {
+      return [];
+    }
+  }
+
+  _save() {
+    try {
+      localStorage.setItem('vf-todos', JSON.stringify(this.state.todos));
+    } catch {
+      // localStorage unavailable
+    }
+  }
+
+  _filtered() {
+    const { todos, filter } = this.state;
+    if (filter === 'active') return todos.filter((t) => !t.done);
+    if (filter === 'completed') return todos.filter((t) => t.done);
+    return todos;
+  }
+
+  _stats() {
+    const total = this.state.todos.length;
+    const done = this.state.todos.filter((t) => t.done).length;
+    return { total, done, active: total - done };
+  }
+
+  _esc(text) {
+    const d = document.createElement('div');
+    d.textContent = text;
+    return d.innerHTML;
+  }
+
+  getTemplate() {
+    const items = this._filtered();
+    const stats = this._stats();
+    const { filter } = this.state;
+    const filterBtn = (f, label) =>
+      `<button class="vf-btn ${filter === f ? 'vf-btn-primary' : 'vf-btn-secondary'}"
+         style="padding:6px 14px;font-size:.85rem" data-action="setFilter" data-filter="${f}">
+         ${label}
+       </button>`;
+
+    return `
+      <div class="vf-card" style="border-radius:16px;overflow:hidden;box-shadow:var(--vf-shadow-md)">
+        <div style="background:linear-gradient(135deg,#1e293b,#0f172a);color:#f8fafc;padding:28px 24px;text-align:center">
+          <h1 style="font-size:1.6rem;font-weight:700;letter-spacing:-.02em">Todos</h1>
+          <p style="color:#94a3b8;font-size:.9rem;margin-top:4px">Built with VanillaForge</p>
+        </div>
+        <div style="padding:24px">
+          <div style="display:flex;gap:10px;margin-bottom:20px">
+            <input type="text"
+              class="vf-input"
+              style="flex:1;padding:12px;border:2px solid var(--vf-border);border-radius:var(--vf-radius);font-size:1rem"
+              placeholder="What needs to be done?"
+              value="${this._esc(this.state.newTodo)}"
+              data-input="inputChange"
+              data-keydown="keyDown">
+            <button class="vf-btn vf-btn-primary" data-action="add"
+              style="padding:12px 20px">
+              ${this.icon('plus', { size: 18 })} Add
+            </button>
+          </div>
+
+          ${stats.total > 0 ? `
+            <div style="display:flex;gap:8px;margin-bottom:16px;flex-wrap:wrap">
+              ${filterBtn('all', 'All (' + stats.total + ')')}
+              ${filterBtn('active', 'Active (' + stats.active + ')')}
+              ${filterBtn('completed', 'Done (' + stats.done + ')')}
+              ${stats.done > 0 ? `
+                <button class="vf-btn vf-btn-danger"
+                  style="padding:6px 14px;font-size:.85rem;margin-left:auto"
+                  data-action="clearDone">
+                  Clear done
+                </button>` : ''}
+            </div>
+          ` : ''}
+
+          ${items.length > 0 ? `
+            <ul style="list-style:none">
+              ${items.map((t) => `
+                <li data-key="${t.id}"
+                  style="display:flex;align-items:center;gap:12px;padding:12px;border-radius:var(--vf-radius);
+                         margin-bottom:8px;background:${t.done ? 'var(--vf-border)' : 'var(--vf-surface)'}">
+                  <input type="checkbox" ${t.done ? 'checked' : ''}
+                    data-change="toggle" data-id="${t.id}"
+                    style="width:18px;height:18px;cursor:pointer;flex-shrink:0">
+                  <span style="flex:1;${t.done ? 'text-decoration:line-through;opacity:.5' : ''}">
+                    ${this._esc(t.text)}
+                  </span>
+                  <button class="vf-btn vf-btn-danger" data-action="remove" data-id="${t.id}"
+                    style="padding:4px 10px;font-size:.8rem">
+                    ${this.icon('trash', { size: 14 })}
+                  </button>
+                </li>
+              `).join('')}
+            </ul>
+          ` : `
+            <div style="text-align:center;padding:40px;color:var(--vf-text-muted)">
+              ${this.icon('check', { size: 40 })}
+              <p style="margin-top:12px">
+                ${filter === 'active' ? 'No active todos.' : filter === 'completed' ? 'Nothing completed yet.' : 'Add a todo above.'}
+              </p>
+            </div>
+          `}
+        </div>
+      </div>`;
+  }
+
+  getMethods() {
+    return {
+      inputChange: (e) => this.setState({ newTodo: e.target.value }, false),
+
+      keyDown: (e) => {
+        if (e.key === 'Enter') this.getMethods().add();
+      },
+
+      add: () => {
+        const text = this.state.newTodo.trim();
+        if (!text) return;
+        const todo = { id: Date.now(), text, done: false };
+        this.setState({ todos: [...this.state.todos, todo], newTodo: '' });
+        this._save();
+      },
+
+      toggle: (e) => {
+        const id = Number(e.target.dataset.id);
+        const todos = this.state.todos.map((t) =>
+          t.id === id ? { ...t, done: !t.done } : t
+        );
+        this.setState({ todos });
+        this._save();
+      },
+
+      remove: async (e) => {
+        const id = Number(e.target.closest('[data-id]').dataset.id);
+        const alerts = this.service('alerts');
+        const ok = alerts
+          ? await alerts.confirm('Delete this todo?', { danger: true })
+          : true;
+        if (ok) {
+          this.setState({ todos: this.state.todos.filter((t) => t.id !== id) });
+          this._save();
+        }
+      },
+
+      setFilter: (e) => {
+        this.setState({ filter: e.target.closest('[data-filter]').dataset.filter });
+      },
+
+      clearDone: () => {
+        this.setState({ todos: this.state.todos.filter((t) => !t.done) });
+        this._save();
+      },
+    };
+  }
+}