@nuraly/lumenjs 0.1.2 → 0.1.3

package/README.md

@@ -1,6 +1,6 @@
 # LumenJS
 
-A full-stack web framework for [Lit](https://lit.dev/) web components. File-based routing, server loaders, SSR with hydration, nested layouts, API routes, and a Vite-powered dev server.
+A full-stack web framework for [Lit](https://lit.dev/) web components. File-based routing, server loaders, real-time subscriptions (SSE), SSR with hydration, nested layouts, API routes, and a Vite-powered dev server.
 
 ## Quick Start
 
@@ -49,9 +49,7 @@ Pages are Lit components in the `pages/` directory. The file path determines the
 ```typescript
 // pages/index.ts
 import { LitElement, html, css } from 'lit';
-import { customElement } from 'lit/decorators.js';
 
-@customElement('page-index')
 export class PageIndex extends LitElement {
   static styles = css`:host { display: block; }`;
 
@@ -61,6 +59,8 @@ export class PageIndex extends LitElement {
 }
 ```
 
+The custom element tag name is derived automatically from the file path — no `@customElement` decorator needed.
+
 ### Routing
 
 | File | URL | Tag |
@@ -85,9 +85,9 @@ export async function loader({ params, headers, query, url }) {
   return { post };
 }
 
-@customElement('page-blog-slug')
 export class BlogPost extends LitElement {
-  @property({ type: Object }) loaderData: any = {};
+  static properties = { loaderData: { type: Object } };
+  loaderData: any = {};
 
   render() {
     return html`<h1>${this.loaderData.post?.title}</h1>`;
@@ -117,13 +117,75 @@ export async function loader({ headers }) {
 }
 ```
 
+## Live Data (subscribe)
+
+Export a `subscribe()` function from any page or layout to push real-time data to the client over Server-Sent Events (SSE).
+
+```typescript
+// pages/dashboard.ts
+export async function loader() {
+  return { orders: await db.orders.findAll() };
+}
+
+export function subscribe({ push }) {
+  const stream = db.orders.watch();
+  stream.on('change', (change) => push({ type: 'order-update', data: change }));
+  return () => stream.close();
+}
+
+export class PageDashboard extends LitElement {
+  static properties = { loaderData: { type: Object }, liveData: { type: Object } };
+  loaderData: any = {};
+  liveData: any = null;
+
+  render() {
+    return html`
+      <h1>Orders (${this.loaderData.orders?.length})</h1>
+      ${this.liveData ? html`<p>Update: ${this.liveData.type}</p>` : ''}
+    `;
+  }
+}
+```
+
+The `subscribe()` function is a persistent server-side process tied to the page lifecycle:
+
+1. User opens page → framework opens SSE connection to `/__nk_subscribe/<path>`
+2. Server calls `subscribe()` — function keeps running (DB watchers, intervals, etc.)
+3. Call `push(data)` whenever you want → delivered to client → updates `liveData` property
+4. User navigates away → connection closes → cleanup function runs
+
+Like `loader()`, `subscribe()` is stripped from client bundles automatically.
+
+### Subscribe Context
+
+| Property | Type | Description |
+|---|---|---|
+| `params` | `Record<string, string>` | Dynamic route parameters |
+| `headers` | `Record<string, any>` | Request headers |
+| `locale` | `string` | Current locale (when i18n is configured) |
+| `push` | `(data: any) => void` | Send SSE event to client (JSON-serialized) |
+
+Return a cleanup function that is called when the client disconnects.
+
+### Layout Subscribe
+
+Layouts can also export `subscribe()` for global live data (notifications, presence, etc.):
+
+```typescript
+// pages/_layout.ts
+export function subscribe({ push }) {
+  const ws = new WebSocket('wss://notifications.example.com');
+  ws.on('message', (msg) => push(JSON.parse(msg)));
+  return () => ws.close();
+}
+```
+
 ## Nested Layouts
 
 Create `_layout.ts` in any directory to wrap all pages in that directory and its subdirectories.
 
 ```typescript
 // pages/_layout.ts
-@customElement('layout-root')
 export class RootLayout extends LitElement {
   render() {
     return html`
@@ -147,9 +209,9 @@ export async function loader({ headers }) {
   return { user };
 }
 
-@customElement('layout-dashboard')
 export class DashboardLayout extends LitElement {
-  @property({ type: Object }) loaderData: any = {};
+  static properties = { loaderData: { type: Object } };
+  loaderData: any = {};
 
   render() {
     return html`
@@ -259,7 +321,6 @@ my-app/
 ```typescript
 import { t, getLocale, setLocale } from '@lumenjs/i18n';
 
-@customElement('page-index')
 export class PageIndex extends LitElement {
   render() {
     return html`<h1>${t('home.title')}</h1>`;

package/dist/build/build.js

@@ -65,12 +65,12 @@ export async function buildProject(options) {
     // Collect server entry points (pages with loaders + layouts with loaders + API routes)
     const serverEntries = {};
     for (const entry of pageEntries) {
-        if (entry.hasLoader) {
+        if (entry.hasLoader || entry.hasSubscribe) {
             serverEntries[`pages/${entry.name}`] = entry.filePath;
         }
     }
     for (const entry of layoutEntries) {
-        if (entry.hasLoader) {
+        if (entry.hasLoader || entry.hasSubscribe) {
             const entryName = entry.dir ? `layouts/${entry.dir}/_layout` : 'layouts/_layout';
             serverEntries[entryName] = entry.filePath;
         }
@@ -124,6 +124,7 @@ export async function buildProject(options) {
                             'os', 'fs', 'path', 'url', 'util', 'crypto', 'http', 'https', 'net',
                             'stream', 'zlib', 'events', 'buffer', 'querystring', 'child_process',
                             'worker_threads', 'cluster', 'dns', 'tls', 'assert', 'constants',
+                            'better-sqlite3',
                         ],
                     },
                 },
@@ -163,8 +164,9 @@ export async function buildProject(options) {
             const relPath = path.relative(pagesDir, e.filePath).replace(/\\/g, '/');
             return {
                 path: e.routePath,
-                module: e.hasLoader ? `pages/${e.name}.js` : '',
+                module: (e.hasLoader || e.hasSubscribe) ? `pages/${e.name}.js` : '',
                 hasLoader: e.hasLoader,
+                hasSubscribe: e.hasSubscribe,
                 tagName: filePathToTagName(relPath),
                 ...(routeLayouts.length > 0 ? { layouts: routeLayouts } : {}),
             };
@@ -173,11 +175,13 @@ export async function buildProject(options) {
             path: `/api/${e.routePath}`,
             module: `api/${e.name}.js`,
             hasLoader: false,
+            hasSubscribe: false,
         })),
         layouts: layoutEntries.map(e => ({
             dir: e.dir,
-            module: e.hasLoader ? (e.dir ? `layouts/${e.dir}/_layout.js` : 'layouts/_layout.js') : '',
+            module: (e.hasLoader || e.hasSubscribe) ? (e.dir ? `layouts/${e.dir}/_layout.js` : 'layouts/_layout.js') : '',
             hasLoader: e.hasLoader,
+            hasSubscribe: e.hasSubscribe,
         })),
         ...(i18nConfig ? { i18n: i18nConfig } : {}),
     };

package/dist/build/scan.d.ts

@@ -3,11 +3,13 @@ export interface PageEntry {
     filePath: string;
     routePath: string;
     hasLoader: boolean;
+    hasSubscribe: boolean;
 }
 export interface LayoutEntry {
     dir: string;
     filePath: string;
     hasLoader: boolean;
+    hasSubscribe: boolean;
 }
 export interface ApiEntry {
     name: string;

package/dist/build/scan.js

@@ -1,6 +1,6 @@
 import fs from 'fs';
 import path from 'path';
-import { fileHasLoader, filePathToRoute } from '../shared/utils.js';
+import { fileHasLoader, fileHasSubscribe, filePathToRoute } from '../shared/utils.js';
 export function scanPages(pagesDir) {
     if (!fs.existsSync(pagesDir))
         return [];
@@ -54,7 +54,8 @@ function walkDir(baseDir, relativePath, entries, pagesDir) {
             const name = entryRelative.replace(/\.(ts|js)$/, '').replace(/\\/g, '/');
             const routePath = filePathToRoute(entryRelative);
             const hasLoader = fileHasLoader(filePath);
-            entries.push({ name, filePath, routePath, hasLoader });
+            const hasSubscribe = fileHasSubscribe(filePath);
+            entries.push({ name, filePath, routePath, hasLoader, hasSubscribe });
         }
     }
 }
@@ -65,7 +66,7 @@ function walkForLayouts(baseDir, relativePath, entries) {
         if (entry.isFile() && /^_layout\.(ts|js)$/.test(entry.name)) {
             const filePath = path.join(fullDir, entry.name);
             const dir = relativePath.replace(/\\/g, '/');
-            entries.push({ dir, filePath, hasLoader: fileHasLoader(filePath) });
+            entries.push({ dir, filePath, hasLoader: fileHasLoader(filePath), hasSubscribe: fileHasSubscribe(filePath) });
         }
         if (entry.isDirectory()) {
             walkForLayouts(baseDir, path.join(relativePath, entry.name), entries);

package/dist/build/serve-loaders.d.ts

@@ -1,4 +1,6 @@
 import http from 'http';
 import type { BuildManifest } from '../shared/types.js';
 export declare function handleLayoutLoaderRequest(manifest: BuildManifest, serverDir: string, queryString: string | undefined, headers: http.IncomingHttpHeaders, res: http.ServerResponse): Promise<void>;
+export declare function handleLayoutSubscribeRequest(manifest: BuildManifest, serverDir: string, queryString: string | undefined, headers: http.IncomingHttpHeaders, res: http.ServerResponse): Promise<void>;
+export declare function handleSubscribeRequest(manifest: BuildManifest, serverDir: string, pagesDir: string, pathname: string, queryString: string | undefined, headers: http.IncomingHttpHeaders, res: http.ServerResponse): Promise<void>;
 export declare function handleLoaderRequest(manifest: BuildManifest, serverDir: string, pagesDir: string, pathname: string, queryString: string | undefined, headers: http.IncomingHttpHeaders, res: http.ServerResponse): Promise<void>;

package/dist/build/serve-loaders.js

@@ -56,6 +56,116 @@ export async function handleLayoutLoaderRequest(manifest, serverDir, queryString
         res.end(JSON.stringify({ error: message }));
     }
 }
+export async function handleLayoutSubscribeRequest(manifest, serverDir, queryString, headers, res) {
+    const query = {};
+    if (queryString) {
+        for (const pair of queryString.split('&')) {
+            const [key, val] = pair.split('=');
+            query[decodeURIComponent(key)] = decodeURIComponent(val || '');
+        }
+    }
+    const dir = query.__dir || '';
+    const layout = (manifest.layouts || []).find(l => l.dir === dir);
+    if (!layout || !layout.hasSubscribe || !layout.module) {
+        res.writeHead(204);
+        res.end();
+        return;
+    }
+    const modulePath = path.join(serverDir, layout.module);
+    if (!fs.existsSync(modulePath)) {
+        res.writeHead(204);
+        res.end();
+        return;
+    }
+    try {
+        const mod = await import(modulePath);
+        if (!mod.subscribe || typeof mod.subscribe !== 'function') {
+            res.writeHead(204);
+            res.end();
+            return;
+        }
+        res.writeHead(200, {
+            'Content-Type': 'text/event-stream',
+            'Cache-Control': 'no-cache',
+            'Connection': 'keep-alive',
+        });
+        const locale = query.__locale;
+        const push = (data) => {
+            res.write(`data: ${JSON.stringify(data)}\n\n`);
+        };
+        const cleanup = mod.subscribe({ params: {}, push, headers, locale });
+        res.on('close', () => {
+            if (typeof cleanup === 'function')
+                cleanup();
+        });
+    }
+    catch (err) {
+        console.error(`[LumenJS] Layout subscribe error for dir=${dir}:`, err);
+        if (!res.headersSent) {
+            res.writeHead(500);
+            res.end();
+        }
+    }
+}
+export async function handleSubscribeRequest(manifest, serverDir, pagesDir, pathname, queryString, headers, res) {
+    const pagePath = pathname.replace('/__nk_subscribe', '') || '/';
+    const query = {};
+    if (queryString) {
+        for (const pair of queryString.split('&')) {
+            const [key, val] = pair.split('=');
+            query[decodeURIComponent(key)] = decodeURIComponent(val || '');
+        }
+    }
+    let params = {};
+    if (query.__params) {
+        try {
+            params = JSON.parse(query.__params);
+        }
+        catch { /* ignore */ }
+        delete query.__params;
+    }
+    const matched = matchRoute(manifest.routes.filter(r => r.hasSubscribe), pagePath);
+    if (!matched || !matched.route.module) {
+        res.writeHead(204);
+        res.end();
+        return;
+    }
+    const modulePath = path.join(serverDir, matched.route.module);
+    if (!fs.existsSync(modulePath)) {
+        res.writeHead(204);
+        res.end();
+        return;
+    }
+    try {
+        const mod = await import(modulePath);
+        if (!mod.subscribe || typeof mod.subscribe !== 'function') {
+            res.writeHead(204);
+            res.end();
+            return;
+        }
+        res.writeHead(200, {
+            'Content-Type': 'text/event-stream',
+            'Cache-Control': 'no-cache',
+            'Connection': 'keep-alive',
+        });
+        const locale = query.__locale;
+        const push = (data) => {
+            res.write(`data: ${JSON.stringify(data)}\n\n`);
+        };
+        const cleanup = mod.subscribe({ params: matched.params, push, headers, locale });
+        res.on('close', () => {
+            if (typeof cleanup === 'function')
+                cleanup();
+        });
+    }
+    catch (err) {
+        console.error(`[LumenJS] Subscribe error for ${pagePath}:`, err);
+        if (!res.headersSent) {
+            res.writeHead(500);
+            res.end();
+        }
+    }
+}
 export async function handleLoaderRequest(manifest, serverDir, pagesDir, pathname, queryString, headers, res) {
     const pagePath = pathname.replace('/__nk_loader', '') || '/';
     // Parse query params

package/dist/build/serve.js

@@ -5,13 +5,15 @@ import { readProjectConfig } from '../dev-server/config.js';
 import { installDomShims } from '../shared/dom-shims.js';
 import { serveStaticFile, sendCompressed } from './serve-static.js';
 import { handleApiRoute } from './serve-api.js';
-import { handleLoaderRequest, handleLayoutLoaderRequest } from './serve-loaders.js';
+import { handleLoaderRequest, handleLayoutLoaderRequest, handleSubscribeRequest, handleLayoutSubscribeRequest } from './serve-loaders.js';
 import { handlePageRoute } from './serve-ssr.js';
 import { renderErrorPage } from './error-page.js';
 import { handleI18nRequest } from './serve-i18n.js';
 import { resolveLocale } from '../dev-server/middleware/locale.js';
+import { setProjectDir } from '../db/context.js';
 export async function serveProject(options) {
     const { projectDir } = options;
+    setProjectDir(projectDir);
     const port = options.port || 3000;
     const outDir = path.join(projectDir, '.lumenjs');
     const clientDir = path.join(outDir, 'client');
@@ -62,12 +64,22 @@ export async function serveProject(options) {
                 handleI18nRequest(localesDir, manifest.i18n.locales, pathname, req, res);
                 return;
             }
-            // 4. Layout loader endpoint
+            // 4. Layout subscribe endpoint (SSE)
+            if (pathname === '/__nk_subscribe/__layout/' || pathname === '/__nk_subscribe/__layout') {
+                await handleLayoutSubscribeRequest(manifest, serverDir, queryString, req.headers, res);
+                return;
+            }
+            // 5. Subscribe endpoint (SSE)
+            if (pathname.startsWith('/__nk_subscribe/')) {
+                await handleSubscribeRequest(manifest, serverDir, pagesDir, pathname, queryString, req.headers, res);
+                return;
+            }
+            // 6. Layout loader endpoint
             if (pathname === '/__nk_loader/__layout/' || pathname === '/__nk_loader/__layout') {
                 await handleLayoutLoaderRequest(manifest, serverDir, queryString, req.headers, res);
                 return;
             }
-            // 5. Loader endpoint for client-side navigation
+            // 7. Loader endpoint for client-side navigation
             if (pathname.startsWith('/__nk_loader/')) {
                 await handleLoaderRequest(manifest, serverDir, pagesDir, pathname, queryString, req.headers, res);
                 return;

package/dist/db/context.d.ts

@@ -0,0 +1,2 @@
+export declare function setProjectDir(dir: string): void;
+export declare function getProjectDir(): string;

package/dist/db/context.js

@@ -0,0 +1,9 @@
+let _projectDir = null;
+export function setProjectDir(dir) {
+    _projectDir = dir;
+}
+export function getProjectDir() {
+    if (!_projectDir)
+        throw new Error('[LumenJS] Project directory not set');
+    return _projectDir;
+}

package/dist/db/index.d.ts

@@ -0,0 +1,19 @@
+import Database from 'better-sqlite3';
+export declare class LumenDb {
+    private db;
+    constructor(db: Database.Database);
+    /** SELECT multiple rows */
+    all<T = any>(sql: string, ...params: any[]): T[];
+    /** SELECT single row */
+    get<T = any>(sql: string, ...params: any[]): T | undefined;
+    /** INSERT/UPDATE/DELETE */
+    run(sql: string, ...params: any[]): {
+        changes: number;
+        lastInsertRowid: number | bigint;
+    };
+    /** Multi-statement DDL */
+    exec(sql: string): void;
+    /** Access the underlying better-sqlite3 instance */
+    get raw(): Database.Database;
+}
+export declare function useDb(): LumenDb;

package/dist/db/index.js

@@ -0,0 +1,79 @@
+import path from 'path';
+import fs from 'fs';
+import Database from 'better-sqlite3';
+import { getProjectDir } from './context.js';
+import { readProjectConfig } from '../dev-server/config.js';
+export class LumenDb {
+    constructor(db) {
+        this.db = db;
+    }
+    /** SELECT multiple rows */
+    all(sql, ...params) {
+        return this.db.prepare(sql).all(...params);
+    }
+    /** SELECT single row */
+    get(sql, ...params) {
+        return this.db.prepare(sql).get(...params);
+    }
+    /** INSERT/UPDATE/DELETE */
+    run(sql, ...params) {
+        const result = this.db.prepare(sql).run(...params);
+        return { changes: result.changes, lastInsertRowid: result.lastInsertRowid };
+    }
+    /** Multi-statement DDL */
+    exec(sql) {
+        this.db.exec(sql);
+    }
+    /** Access the underlying better-sqlite3 instance */
+    get raw() {
+        return this.db;
+    }
+}
+let _instance = null;
+export function useDb() {
+    if (_instance)
+        return _instance;
+    const projectDir = getProjectDir();
+    const config = readProjectConfig(projectDir);
+    const dbRelPath = config.db?.path || 'data/db.sqlite';
+    const dbPath = path.resolve(projectDir, dbRelPath);
+    // Auto-create directory
+    const dbDir = path.dirname(dbPath);
+    if (!fs.existsSync(dbDir)) {
+        fs.mkdirSync(dbDir, { recursive: true });
+    }
+    const db = new Database(dbPath);
+    db.pragma('journal_mode = WAL');
+    db.pragma('foreign_keys = ON');
+    _instance = new LumenDb(db);
+    // Run pending migrations
+    runMigrations(db, projectDir);
+    return _instance;
+}
+function runMigrations(db, projectDir) {
+    const migrationsDir = path.join(projectDir, 'data', 'migrations');
+    if (!fs.existsSync(migrationsDir))
+        return;
+    // Ensure tracking table exists
+    db.exec(`CREATE TABLE IF NOT EXISTS _lumen_migrations (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    name TEXT NOT NULL UNIQUE,
+    applied_at TEXT NOT NULL DEFAULT (datetime('now'))
+  )`);
+    const applied = new Set(db.prepare('SELECT name FROM _lumen_migrations').all()
+        .map((row) => row.name));
+    const files = fs.readdirSync(migrationsDir)
+        .filter(f => f.endsWith('.sql'))
+        .sort();
+    for (const file of files) {
+        if (applied.has(file))
+            continue;
+        const sql = fs.readFileSync(path.join(migrationsDir, file), 'utf-8');
+        const migrate = db.transaction(() => {
+            db.exec(sql);
+            db.prepare('INSERT INTO _lumen_migrations (name) VALUES (?)').run(file);
+        });
+        migrate();
+        console.log(`[LumenJS] Applied migration: ${file}`);
+    }
+}

package/dist/dev-server/config.d.ts

@@ -7,6 +7,9 @@ export interface ProjectConfig {
     title: string;
     integrations: string[];
     i18n?: I18nConfig;
+    db?: {
+        path?: string;
+    };
 }
 /**
  * Reads the project config from lumenjs.config.ts.

package/dist/dev-server/config.js

@@ -52,7 +52,21 @@ export function readProjectConfig(projectDir) {
         }
         catch { /* ignore */ }
     }
-    return { title, integrations, ...(i18n ? { i18n } : {}) };
+    // Parse db config
+    let db;
+    if (fs.existsSync(configPath)) {
+        try {
+            const configContent = fs.readFileSync(configPath, 'utf-8');
+            const dbMatch = configContent.match(/db\s*:\s*\{([\s\S]*?)\}/);
+            if (dbMatch) {
+                const block = dbMatch[1];
+                const pathMatch = block.match(/path\s*:\s*['"]([^'"]+)['"]/);
+                db = pathMatch ? { path: pathMatch[1] } : {};
+            }
+        }
+        catch { /* ignore */ }
+    }
+    return { title, integrations, ...(i18n ? { i18n } : {}), ...(db ? { db } : {}) };
 }
 /**
  * Reads the project title from lumenjs.config.ts (or returns default).

package/dist/dev-server/plugins/vite-plugin-loaders.d.ts

@@ -12,7 +12,6 @@ import { Plugin } from 'vite';
  *     return { item: data, timestamp: Date.now() };
  *   }
  *
- *   @customElement('page-item')
  *   export class PageItem extends LitElement {
  *     @property({ type: Object }) loaderData = {};
  *     render() {

package/dist/dev-server/plugins/vite-plugin-loaders.js

@@ -15,7 +15,6 @@ import { installDomShims } from '../../shared/dom-shims.js';
  *     return { item: data, timestamp: Date.now() };
  *   }
  *
- *   @customElement('page-item')
  *   export class PageItem extends LitElement {
  *     @property({ type: Object }) loaderData = {};
  *     render() {
@@ -31,6 +30,78 @@ export function lumenLoadersPlugin(pagesDir) {
     return {
         name: 'lumenjs-loaders',
         configureServer(server) {
+            // SSE subscribe middleware
+            server.middlewares.use(async (req, res, next) => {
+                if (!req.url?.startsWith('/__nk_subscribe/')) {
+                    return next();
+                }
+                const [pathname, queryString] = req.url.split('?');
+                // Parse query params
+                const query = {};
+                if (queryString) {
+                    for (const pair of queryString.split('&')) {
+                        const [key, val] = pair.split('=');
+                        query[decodeURIComponent(key)] = decodeURIComponent(val || '');
+                    }
+                }
+                // Handle layout subscribe: /__nk_subscribe/__layout/?__dir=<dir>
+                if (pathname === '/__nk_subscribe/__layout/' || pathname === '/__nk_subscribe/__layout') {
+                    const dir = query.__dir || '';
+                    await handleLayoutSubscribe(server, pagesDir, dir, query, req, res);
+                    return;
+                }
+                const pagePath = pathname.replace('/__nk_subscribe', '') || '/';
+                // Parse URL params
+                let params = {};
+                if (query.__params) {
+                    try {
+                        params = JSON.parse(query.__params);
+                    }
+                    catch { /* ignore */ }
+                    delete query.__params;
+                }
+                const filePath = resolvePageFile(pagesDir, pagePath);
+                if (!filePath) {
+                    res.statusCode = 404;
+                    res.end();
+                    return;
+                }
+                if (Object.keys(params).length === 0) {
+                    Object.assign(params, extractRouteParams(pagesDir, pagePath, filePath));
+                }
+                try {
+                    installDomShims();
+                    const mod = await server.ssrLoadModule(filePath);
+                    if (!mod.subscribe || typeof mod.subscribe !== 'function') {
+                        res.statusCode = 204;
+                        res.end();
+                        return;
+                    }
+                    // Set SSE headers
+                    res.writeHead(200, {
+                        'Content-Type': 'text/event-stream',
+                        'Cache-Control': 'no-cache',
+                        'Connection': 'keep-alive',
+                    });
+                    const locale = query.__locale;
+                    const push = (data) => {
+                        res.write(`data: ${JSON.stringify(data)}\n\n`);
+                    };
+                    const cleanup = mod.subscribe({ params, push, headers: req.headers, locale });
+                    res.on('close', () => {
+                        if (typeof cleanup === 'function')
+                            cleanup();
+                    });
+                }
+                catch (err) {
+                    console.error(`[LumenJS] Subscribe error for ${pagePath}:`, err);
+                    if (!res.headersSent) {
+                        res.statusCode = 500;
+                        res.end();
+                    }
+                }
+            });
+            // Loader middleware
             server.middlewares.use(async (req, res, next) => {
                 if (!req.url?.startsWith('/__nk_loader/')) {
                     return next();
@@ -126,45 +197,26 @@ export function lumenLoadersPlugin(pagesDir) {
             // Apply to page files and layout files within the pages directory
             if (!id.startsWith(pagesDir) || !id.endsWith('.ts'))
                 return;
-            if (!code.includes('export') || !code.includes('loader'))
-                return;
-            const hasLoader = /export\s+(async\s+)?function\s+loader\s*\(/.test(code);
-            if (!hasLoader)
-                return;
-            // Find the loader function by tracking brace depth
-            const match = code.match(/export\s+(async\s+)?function\s+loader\s*\(/);
-            if (!match)
+            const hasLoader = code.includes('export') && code.includes('loader') && /export\s+(async\s+)?function\s+loader\s*\(/.test(code);
+            const hasSubscribe = code.includes('export') && code.includes('subscribe') && /export\s+(async\s+)?function\s+subscribe\s*\(/.test(code);
+            if (!hasLoader && !hasSubscribe)
                 return;
-            const startIdx = match.index;
-            // Skip past the function signature's closing parenthesis (handles nested braces in type annotations)
-            let parenDepth = 1;
-            let sigIdx = startIdx + match[0].length;
-            while (sigIdx < code.length && parenDepth > 0) {
-                if (code[sigIdx] === '(')
-                    parenDepth++;
-                else if (code[sigIdx] === ')')
-                    parenDepth--;
-                sigIdx++;
+            let result = code;
+            // Strip loader function
+            if (hasLoader) {
+                result = stripServerFunction(result, 'loader');
             }
-            // Find the opening brace of the function body (after the closing paren and optional return type)
-            let braceStart = code.indexOf('{', sigIdx);
-            if (braceStart === -1)
-                return;
-            let depth = 1;
-            let i = braceStart + 1;
-            while (i < code.length && depth > 0) {
-                if (code[i] === '{')
-                    depth++;
-                else if (code[i] === '}')
-                    depth--;
-                i++;
+            // Strip subscribe function
+            if (hasSubscribe) {
+                result = stripServerFunction(result, 'subscribe');
+            }
+            if (hasLoader) {
+                result += '\nexport const __nk_has_loader = true;\n';
+            }
+            if (hasSubscribe) {
+                result += '\nexport const __nk_has_subscribe = true;\n';
             }
-            // Replace the entire loader function
-            const transformed = code.substring(0, startIdx)
-                + '// loader() — runs server-side only'
-                + code.substring(i);
-            const withFlag = transformed + '\nexport const __nk_has_loader = true;\n';
-            return { code: withFlag, map: null };
+            return { code: result, map: null };
         },
     };
 }
@@ -310,6 +362,90 @@ function findDynamicPage(baseDir, segments) {
     }
     return null;
 }
+/**
+ * Strip a named server-side function (loader/subscribe) from client code using brace-depth tracking.
+ */
+function stripServerFunction(code, fnName) {
+    const regex = new RegExp(`export\\s+(async\\s+)?function\\s+${fnName}\\s*\\(`);
+    const match = code.match(regex);
+    if (!match)
+        return code;
+    const startIdx = match.index;
+    let parenDepth = 1;
+    let sigIdx = startIdx + match[0].length;
+    while (sigIdx < code.length && parenDepth > 0) {
+        if (code[sigIdx] === '(')
+            parenDepth++;
+        else if (code[sigIdx] === ')')
+            parenDepth--;
+        sigIdx++;
+    }
+    let braceStart = code.indexOf('{', sigIdx);
+    if (braceStart === -1)
+        return code;
+    let depth = 1;
+    let i = braceStart + 1;
+    while (i < code.length && depth > 0) {
+        if (code[i] === '{')
+            depth++;
+        else if (code[i] === '}')
+            depth--;
+        i++;
+    }
+    return code.substring(0, startIdx)
+        + `// ${fnName}() — runs server-side only`
+        + code.substring(i);
+}
+/**
+ * Handle layout subscribe requests in dev mode.
+ * GET /__nk_subscribe/__layout/?__dir=<dir>
+ */
+async function handleLayoutSubscribe(server, pagesDir, dir, query, req, res) {
+    const layoutDir = path.join(pagesDir, dir);
+    let layoutFile = null;
+    for (const ext of ['.ts', '.js']) {
+        const p = path.join(layoutDir, `_layout${ext}`);
+        if (fs.existsSync(p)) {
+            layoutFile = p;
+            break;
+        }
+    }
+    if (!layoutFile) {
+        res.statusCode = 204;
+        res.end();
+        return;
+    }
+    try {
+        installDomShims();
+        const mod = await server.ssrLoadModule(layoutFile);
+        if (!mod.subscribe || typeof mod.subscribe !== 'function') {
+            res.statusCode = 204;
+            res.end();
+            return;
+        }
+        res.writeHead(200, {
+            'Content-Type': 'text/event-stream',
+            'Cache-Control': 'no-cache',
+            'Connection': 'keep-alive',
+        });
+        const locale = query.__locale;
+        const push = (data) => {
+            res.write(`data: ${JSON.stringify(data)}\n\n`);
+        };
+        const cleanup = mod.subscribe({ params: {}, push, headers: req.headers, locale });
+        res.on('close', () => {
+            if (typeof cleanup === 'function')
+                cleanup();
+        });
+    }
+    catch (err) {
+        console.error(`[LumenJS] Layout subscribe error for dir=${dir}:`, err);
+        if (!res.headersSent) {
+            res.statusCode = 500;
+            res.end();
+        }
+    }
+}
 /**
  * Extract dynamic route params by comparing URL segments against [param] file path segments.
  */

package/dist/dev-server/plugins/vite-plugin-routes.js

@@ -1,6 +1,6 @@
 import fs from 'fs';
 import path from 'path';
-import { dirToLayoutTagName, fileHasLoader, filePathToRoute, filePathToTagName } from '../../shared/utils.js';
+import { dirToLayoutTagName, fileHasLoader, fileHasSubscribe, filePathToRoute, filePathToTagName } from '../../shared/utils.js';
 const VIRTUAL_MODULE_ID = 'virtual:lumenjs-routes';
 const RESOLVED_VIRTUAL_MODULE_ID = '\0' + VIRTUAL_MODULE_ID;
 /**
@@ -98,18 +98,20 @@ export function lumenRoutesPlugin(pagesDir) {
                 const routeArray = routes
                     .map(r => {
                     const hasLoader = fileHasLoader(r.componentPath);
+                    const hasSubscribe = fileHasSubscribe(r.componentPath);
                     const componentPath = r.componentPath.replace(/\\/g, '/');
                     const chain = getLayoutChain(r.componentPath, layouts);
                     let layoutsStr = '';
                     if (chain.length > 0) {
                         const items = chain.map(l => {
                             const lHasLoader = fileHasLoader(l.filePath);
+                            const lHasSubscribe = fileHasSubscribe(l.filePath);
                             const lPath = l.filePath.replace(/\\/g, '/');
-                            return `{ tagName: ${JSON.stringify(l.tagName)}, loaderPath: ${JSON.stringify(l.dir)}${lHasLoader ? ', hasLoader: true' : ''}, load: () => import('${lPath}') }`;
+                            return `{ tagName: ${JSON.stringify(l.tagName)}, loaderPath: ${JSON.stringify(l.dir)}${lHasLoader ? ', hasLoader: true' : ''}${lHasSubscribe ? ', hasSubscribe: true' : ''}, load: () => import('${lPath}') }`;
                         });
                         layoutsStr = `, layouts: [${items.join(', ')}]`;
                     }
-                    return `  { path: ${JSON.stringify(r.path)}, tagName: ${JSON.stringify(r.tagName)}${hasLoader ? ', hasLoader: true' : ''}, load: () => import('${componentPath}')${layoutsStr} }`;
+                    return `  { path: ${JSON.stringify(r.path)}, tagName: ${JSON.stringify(r.tagName)}${hasLoader ? ', hasLoader: true' : ''}${hasSubscribe ? ', hasSubscribe: true' : ''}, load: () => import('${componentPath}')${layoutsStr} }`;
                 })
                     .join(',\n');
                 return `export const routes = [\n${routeArray}\n];\n`;

package/dist/dev-server/server.js

@@ -17,6 +17,7 @@ import { sourceAnnotatorPlugin } from './plugins/vite-plugin-source-annotator.js
 import { virtualModulesPlugin } from './plugins/vite-plugin-virtual-modules.js';
 import { i18nPlugin, loadTranslationsFromDisk } from './plugins/vite-plugin-i18n.js';
 import { resolveLocale } from './middleware/locale.js';
+import { setProjectDir } from '../db/context.js';
 // Re-export for backwards compatibility
 export { readProjectConfig, readProjectTitle, getLumenJSNodeModules, getLumenJSDirs } from './config.js';
 export { getNuralyUIAliases, resolveNuralyUIPaths } from './nuralyui-aliases.js';
@@ -82,6 +83,7 @@ export function getSharedViteConfig(projectDir, options) {
 }
 export async function createDevServer(options) {
     const { projectDir, port, editorMode = false, base = '/' } = options;
+    setProjectDir(projectDir);
     const pagesDir = path.join(projectDir, 'pages');
     const apiDir = path.join(projectDir, 'api');
     const publicDir = path.join(projectDir, 'public');

package/dist/runtime/router-data.d.ts

@@ -1,3 +1,5 @@
 export declare function fetchLoaderData(pathname: string, params: Record<string, string>): Promise<any>;
 export declare function fetchLayoutLoaderData(dir: string): Promise<any>;
+export declare function connectSubscribe(pathname: string, params: Record<string, string>): EventSource;
+export declare function connectLayoutSubscribe(dir: string): EventSource;
 export declare function render404(pathname: string): string;

package/dist/runtime/router-data.js

@@ -33,6 +33,26 @@ export async function fetchLayoutLoaderData(dir) {
         return undefined;
     return data;
 }
+export function connectSubscribe(pathname, params) {
+    const url = new URL(`/__nk_subscribe${pathname}`, location.origin);
+    if (Object.keys(params).length > 0) {
+        url.searchParams.set('__params', JSON.stringify(params));
+    }
+    const config = getI18nConfig();
+    if (config) {
+        url.searchParams.set('__locale', getLocale());
+    }
+    return new EventSource(url.toString());
+}
+export function connectLayoutSubscribe(dir) {
+    const url = new URL('/__nk_subscribe/__layout/', location.origin);
+    url.searchParams.set('__dir', dir);
+    const config = getI18nConfig();
+    if (config) {
+        url.searchParams.set('__locale', getLocale());
+    }
+    return new EventSource(url.toString());
+}
 export function render404(pathname) {
     return `<div style="display:flex;align-items:center;justify-content:center;min-height:80vh;font-family:system-ui,-apple-system,sans-serif;padding:2rem">
   <div style="text-align:center;max-width:400px">

package/dist/runtime/router.d.ts

@@ -1,6 +1,7 @@
 export interface LayoutInfo {
     tagName: string;
     hasLoader?: boolean;
+    hasSubscribe?: boolean;
     load?: () => Promise<any>;
     loaderPath?: string;
 }
@@ -8,6 +9,7 @@ export interface Route {
     path: string;
     tagName: string;
     hasLoader?: boolean;
+    hasSubscribe?: boolean;
     load?: () => Promise<any>;
     layouts?: LayoutInfo[];
     pattern?: RegExp;
@@ -23,14 +25,17 @@ export declare class NkRouter {
     private outlet;
     private currentTag;
     private currentLayoutTags;
+    private subscriptions;
     params: Record<string, string>;
     constructor(routes: Route[], outlet: HTMLElement, hydrate?: boolean);
     private compilePattern;
+    private cleanupSubscriptions;
     navigate(pathname: string, pushState?: boolean): Promise<void>;
     private matchRoute;
     private renderRoute;
     private buildLayoutTree;
     private createPageElement;
+    private findPageElement;
     private handleLinkClick;
     /** Strip locale prefix from a path for internal route matching. */
     private stripLocale;

package/dist/runtime/router.js

@@ -1,4 +1,4 @@
-import { fetchLoaderData, fetchLayoutLoaderData, render404 } from './router-data.js';
+import { fetchLoaderData, fetchLayoutLoaderData, connectSubscribe, connectLayoutSubscribe, render404 } from './router-data.js';
 import { hydrateInitialRoute } from './router-hydration.js';
 import { getI18nConfig, getLocale, stripLocalePrefix, buildLocalePath } from './i18n.js';
 /**
@@ -12,6 +12,7 @@ export class NkRouter {
         this.outlet = null;
         this.currentTag = null;
         this.currentLayoutTags = [];
+        this.subscriptions = [];
         this.params = {};
         this.outlet = outlet;
         this.routes = routes.map(r => ({
@@ -43,7 +44,14 @@ export class NkRouter {
         });
         return { pattern: new RegExp(`^${pattern}$`), paramNames };
     }
+    cleanupSubscriptions() {
+        for (const es of this.subscriptions) {
+            es.close();
+        }
+        this.subscriptions = [];
+    }
     async navigate(pathname, pushState = true) {
+        this.cleanupSubscriptions();
         const match = this.matchRoute(pathname);
         if (!match) {
             if (this.outlet)
@@ -55,6 +63,7 @@ export class NkRouter {
         if (pushState) {
             const localePath = this.withLocale(pathname);
             history.pushState(null, '', localePath);
+            window.scrollTo(0, 0);
         }
         this.params = match.params;
         // Lazy-load the page component if not yet registered
@@ -96,6 +105,28 @@ export class NkRouter {
             }
         }
         this.renderRoute(match.route, loaderData, layouts, layoutDataList);
+        // Set up SSE subscriptions for page
+        if (match.route.hasSubscribe) {
+            const es = connectSubscribe(pathname, match.params);
+            es.onmessage = (e) => {
+                const pageEl = this.findPageElement(match.route.tagName);
+                if (pageEl)
+                    pageEl.liveData = JSON.parse(e.data);
+            };
+            this.subscriptions.push(es);
+        }
+        // Set up SSE subscriptions for layouts
+        for (const layout of layouts) {
+            if (layout.hasSubscribe) {
+                const es = connectLayoutSubscribe(layout.loaderPath || '');
+                es.onmessage = (e) => {
+                    const layoutEl = this.outlet?.querySelector(layout.tagName);
+                    if (layoutEl)
+                        layoutEl.liveData = JSON.parse(e.data);
+                };
+                this.subscriptions.push(es);
+            }
+        }
     }
     matchRoute(pathname) {
         for (const route of this.routes) {
@@ -194,6 +225,11 @@ export class NkRouter {
         }
         return el;
     }
+    findPageElement(tagName) {
+        if (!this.outlet)
+            return null;
+        return this.outlet.querySelector(tagName) ?? this.outlet.querySelector(`${tagName}:last-child`);
+    }
     handleLinkClick(event) {
         const path = event.composedPath();
         const anchor = path.find((el) => el instanceof HTMLElement && el.tagName === 'A');

package/dist/shared/types.d.ts

@@ -2,11 +2,13 @@ export interface ManifestLayout {
     dir: string;
     module: string;
     hasLoader: boolean;
+    hasSubscribe: boolean;
 }
 export interface ManifestRoute {
     path: string;
     module: string;
     hasLoader: boolean;
+    hasSubscribe: boolean;
     tagName?: string;
     layouts?: string[];
 }

package/dist/shared/utils.d.ts

@@ -14,7 +14,7 @@ export declare function stripOuterLitMarkers(html: string): string;
 export declare function dirToLayoutTagName(dir: string): string;
 /**
  * Find the custom element tag name from a page module.
- * Pages use @customElement('page-xxx') which registers the element.
+ * Pages are auto-registered by the auto-define plugin based on file path.
  */
 export declare function findTagName(mod: Record<string, any>): string | null;
 /**
@@ -43,6 +43,10 @@ export declare function escapeHtml(text: string): string;
  * Check if a page/layout file exports a loader() function.
  */
 export declare function fileHasLoader(filePath: string): boolean;
+/**
+ * Check if a page/layout file exports a subscribe() function.
+ */
+export declare function fileHasSubscribe(filePath: string): boolean;
 /**
  * Convert a file path (relative to pages/) to a route path.
  */

package/dist/shared/utils.js

@@ -29,7 +29,7 @@ export function dirToLayoutTagName(dir) {
 }
 /**
  * Find the custom element tag name from a page module.
- * Pages use @customElement('page-xxx') which registers the element.
+ * Pages are auto-registered by the auto-define plugin based on file path.
  */
 export function findTagName(mod) {
     for (const key of Object.keys(mod)) {
@@ -109,6 +109,18 @@ export function fileHasLoader(filePath) {
         return false;
     }
 }
+/**
+ * Check if a page/layout file exports a subscribe() function.
+ */
+export function fileHasSubscribe(filePath) {
+    try {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        return /export\s+(async\s+)?function\s+subscribe\s*\(/.test(content);
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Convert a file path (relative to pages/) to a route path.
  */

package/package.json

@@ -1,14 +1,19 @@
 {
   "name": "@nuraly/lumenjs",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Full-stack Lit web component framework with file-based routing, server loaders, SSR, and API routes",
   "type": "module",
   "main": "dist/cli.js",
   "bin": {
     "lumenjs": "dist/cli.js"
   },
+  "exports": {
+    ".": "./dist/cli.js",
+    "./db": "./dist/db/index.js"
+  },
   "files": [
     "dist",
+    "templates",
     "README.md"
   ],
   "scripts": {
@@ -42,11 +47,13 @@
   "license": "MIT",
   "dependencies": {
     "@lit-labs/ssr": "^3.2.0",
+    "better-sqlite3": "^11.0.0",
     "glob": "^10.3.0",
     "lit": "^3.1.0",
     "vite": "^5.4.0"
   },
   "devDependencies": {
+    "@types/better-sqlite3": "^7.6.0",
     "@types/node": "^20.14.2",
     "@vitest/coverage-v8": "^4.0.18",
     "typescript": "^5.4.5",

package/templates/blog/api/posts.ts

@@ -0,0 +1,20 @@
+import { useDb } from '@nuraly/lumenjs/db';
+
+export function GET() {
+  const db = useDb();
+  const posts = db.all('SELECT id, title, slug, content, date FROM posts ORDER BY date DESC');
+  return { posts };
+}
+
+export function POST(req: { body: any }) {
+  const { title, slug, content } = req.body;
+  if (!title || !slug || !content) {
+    throw { status: 400, message: 'title, slug, and content are required' };
+  }
+  const db = useDb();
+  const result = db.run(
+    'INSERT INTO posts (title, slug, content) VALUES (?, ?, ?)',
+    title, slug, content
+  );
+  return { id: result.lastInsertRowid, title, slug, content };
+}

package/templates/blog/data/migrations/001_init.sql

@@ -0,0 +1,12 @@
+CREATE TABLE IF NOT EXISTS posts (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  title TEXT NOT NULL,
+  slug TEXT NOT NULL UNIQUE,
+  content TEXT NOT NULL,
+  date TEXT NOT NULL DEFAULT (date('now'))
+);
+
+INSERT INTO posts (title, slug, content, date) VALUES
+  ('Hello World', 'hello-world', 'Welcome to your new LumenJS blog! This post was loaded from SQLite.', '2025-01-15'),
+  ('Getting Started with LumenJS', 'getting-started', 'LumenJS makes it easy to build full-stack web apps with Lit web components and file-based routing.', '2025-01-20'),
+  ('SQLite Persistence', 'sqlite-persistence', 'LumenJS includes built-in SQLite support via better-sqlite3. Just use useDb() in your loaders and API routes.', '2025-01-25');

package/templates/blog/pages/index.ts

@@ -0,0 +1,39 @@
+import { LitElement, html, css } from 'lit';
+import { customElement, property } from 'lit/decorators.js';
+import { useDb } from '@nuraly/lumenjs/db';
+
+export function loader() {
+  const db = useDb();
+  const posts = db.all('SELECT id, title, slug, content, date FROM posts ORDER BY date DESC');
+  return { posts };
+}
+
+@customElement('page-home')
+export class PageHome extends LitElement {
+  @property({ type: Object }) data: any;
+
+  static styles = css`
+    :host { display: block; max-width: 720px; margin: 0 auto; padding: 2rem; font-family: system-ui, sans-serif; }
+    h1 { font-size: 2rem; margin-bottom: 1.5rem; }
+    .post { margin-bottom: 1.5rem; padding-bottom: 1.5rem; border-bottom: 1px solid #eee; }
+    .post h2 { margin: 0 0 0.25rem; }
+    .post a { color: #0066cc; text-decoration: none; }
+    .post a:hover { text-decoration: underline; }
+    .post .date { color: #666; font-size: 0.875rem; }
+    .post p { color: #333; margin: 0.5rem 0 0; }
+  `;
+
+  render() {
+    const posts = this.data?.posts || [];
+    return html`
+      <h1>Blog</h1>
+      ${posts.map((post: any) => html`
+        <div class="post">
+          <h2><a href="/posts/${post.slug}">${post.title}</a></h2>
+          <span class="date">${post.date}</span>
+          <p>${post.content}</p>
+        </div>
+      `)}
+    `;
+  }
+}

package/templates/blog/pages/posts/[slug].ts

@@ -0,0 +1,35 @@
+import { LitElement, html, css } from 'lit';
+import { customElement, property } from 'lit/decorators.js';
+import { useDb } from '@nuraly/lumenjs/db';
+
+export function loader({ params }: { params: { slug: string } }) {
+  const db = useDb();
+  const post = db.get('SELECT id, title, slug, content, date FROM posts WHERE slug = ?', params.slug);
+  return { post: post || null };
+}
+
+@customElement('page-post')
+export class PagePost extends LitElement {
+  @property({ type: Object }) data: any;
+
+  static styles = css`
+    :host { display: block; max-width: 720px; margin: 0 auto; padding: 2rem; font-family: system-ui, sans-serif; }
+    a { color: #0066cc; text-decoration: none; }
+    a:hover { text-decoration: underline; }
+    .date { color: #666; font-size: 0.875rem; }
+    .content { margin-top: 1rem; line-height: 1.6; color: #333; }
+  `;
+
+  render() {
+    const post = this.data?.post;
+    if (!post) {
+      return html`<p>Post not found. <a href="/">Back to blog</a></p>`;
+    }
+    return html`
+      <a href="/">&larr; Back to blog</a>
+      <h1>${post.title}</h1>
+      <span class="date">${post.date}</span>
+      <div class="content">${post.content}</div>
+    `;
+  }
+}

package/templates/dashboard/api/stats.ts

@@ -0,0 +1,7 @@
+import { useDb } from '@nuraly/lumenjs/db';
+
+export function GET() {
+  const db = useDb();
+  const stats = db.all('SELECT id, label, value, unit, updated_at FROM stats ORDER BY id');
+  return { stats };
+}

package/templates/dashboard/data/migrations/001_init.sql

@@ -0,0 +1,13 @@
+CREATE TABLE IF NOT EXISTS stats (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  label TEXT NOT NULL UNIQUE,
+  value REAL NOT NULL,
+  unit TEXT NOT NULL DEFAULT '',
+  updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+INSERT INTO stats (label, value, unit) VALUES
+  ('Total Users', 1284, 'users'),
+  ('Revenue', 42500, 'USD'),
+  ('Active Sessions', 89, 'sessions'),
+  ('Uptime', 99.97, '%');

package/templates/dashboard/pages/index.ts

@@ -0,0 +1,41 @@
+import { LitElement, html, css } from 'lit';
+import { customElement, property } from 'lit/decorators.js';
+import { useDb } from '@nuraly/lumenjs/db';
+
+export function loader() {
+  const db = useDb();
+  const stats = db.all('SELECT id, label, value, unit, updated_at FROM stats ORDER BY id');
+  return { stats };
+}
+
+@customElement('page-dashboard')
+export class PageDashboard extends LitElement {
+  @property({ type: Object }) data: any;
+
+  static styles = css`
+    :host { display: block; max-width: 960px; margin: 0 auto; padding: 2rem; font-family: system-ui, sans-serif; }
+    h1 { font-size: 2rem; margin-bottom: 1.5rem; }
+    .grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(200px, 1fr)); gap: 1rem; }
+    .card { background: #f9fafb; border: 1px solid #e5e7eb; border-radius: 8px; padding: 1.5rem; }
+    .card .label { font-size: 0.875rem; color: #6b7280; margin-bottom: 0.25rem; }
+    .card .value { font-size: 1.75rem; font-weight: 600; color: #111827; }
+    .card .unit { font-size: 0.75rem; color: #9ca3af; margin-left: 0.25rem; }
+  `;
+
+  render() {
+    const stats = this.data?.stats || [];
+    return html`
+      <h1>Dashboard</h1>
+      <div class="grid">
+        ${stats.map((stat: any) => html`
+          <div class="card">
+            <div class="label">${stat.label}</div>
+            <div class="value">
+              ${stat.value}<span class="unit">${stat.unit}</span>
+            </div>
+          </div>
+        `)}
+      </div>
+    `;
+  }
+}