@nuraly/lumenjs 0.2.0 → 0.3.0

package/README.md

@@ -68,6 +68,8 @@ export class PageIndex extends LitElement {
 
 Export a `loader()` to fetch data server-side. It runs on SSR and via `/__nk_loader/<path>` during client-side navigation. Automatically stripped from client bundles.
 
+Declare each returned key as its own property — the framework spreads loader data onto the element automatically.
+
 ```typescript
 // pages/blog/[slug].ts
 export async function loader({ params }) {
@@ -77,11 +79,11 @@ export async function loader({ params }) {
 }
 
 export class BlogPost extends LitElement {
-  static properties = { loaderData: { type: Object } };
-  loaderData: any = {};
+  static properties = { post: { type: Object } };
+  post: any = null;
 
   render() {
-    return html`<h1>${this.loaderData.post?.title}</h1>`;
+    return html`<h1>${this.post?.title}</h1>`;
   }
 }
 ```
@@ -110,16 +112,20 @@ export function subscribe({ push }) {
 }
 
 export class PageDashboard extends LitElement {
-  static properties = { liveData: { type: Object } };
-  liveData: any = null;
+  static properties = {
+    time: { type: String },
+    count: { type: Number },
+  };
+  time = '';
+  count = 0;
 
   render() {
-    return html`<p>Server time: ${this.liveData?.time}</p>`;
+    return html`<p>Server time: ${this.time}</p>`;
   }
 }
 ```
 
-Return a cleanup function — it runs when the client disconnects.
+Each key from `push()` is spread as an individual property on the component — same as loader data. Return a cleanup function — it runs when the client disconnects.
 
 ## Layouts
 
@@ -186,6 +192,41 @@ npx lumenjs add tailwind    # Tailwind CSS via @tailwindcss/vite
 export default { integrations: ['nuralyui'] };
 ```
 
+## Visual Editor
+
+Start the dev server with `--editor-mode` to edit pages visually in the browser:
+
+```bash
+npx lumenjs dev --editor-mode
+```
+
+Click elements to select them, edit properties and styles in the side panel, double-click text to edit inline, or ask the AI assistant to make changes for you. Everything saves directly to your source files.
+
+### AI Backend
+
+The editor includes an AI assistant that can modify your components. It supports three backends:
+
+**Claude Code** (recommended) — uses your Pro/Max subscription, no API key needed:
+
+```bash
+npm install -g @anthropic-ai/claude-code
+claude login
+npm install @anthropic-ai/claude-agent-sdk
+npx lumenjs dev --editor-mode
+```
+
+**OpenCode** — coding agent server, configure it with DeepSeek or any LLM provider:
+
+```bash
+npm install -g opencode
+opencode serve                        # terminal 1
+npx lumenjs dev --editor-mode         # terminal 2
+```
+
+Configure the connection: `OPENCODE_URL` (default `http://localhost:4096`) and `OPENCODE_SERVER_PASSWORD` if auth is required.
+
+Set `AI_BACKEND` to force a specific backend (`claude-code` or `opencode`). Without it, the editor auto-detects: Claude Code (if CLI logged in) → OpenCode (fallback).
+
 ## CLI
 
 ```

package/dist/build/build-markdown.d.ts

@@ -0,0 +1,15 @@
+import type { BuildManifest } from '../shared/types.js';
+import type { PageEntry } from './scan.js';
+export interface MarkdownOptions {
+    serverDir: string;
+    clientDir: string;
+    pagesDir: string;
+    pageEntries: PageEntry[];
+    manifest: BuildManifest;
+}
+/**
+ * Generate static .md files for each page by SSR-rendering the component
+ * and converting the HTML to markdown. Written to clientDir so the
+ * production static file server picks them up (e.g., /docs/routing.md).
+ */
+export declare function generateMarkdownPages(opts: MarkdownOptions): Promise<void>;

package/dist/build/build-markdown.js

@@ -0,0 +1,90 @@
+import path from 'path';
+import fs from 'fs';
+import { pathToFileURL } from 'url';
+import { stripOuterLitMarkers, patchLoaderDataSpread } from '../shared/utils.js';
+import { installDomShims } from '../shared/dom-shims.js';
+import { htmlToMarkdown } from '../shared/html-to-markdown.js';
+/**
+ * Generate static .md files for each page by SSR-rendering the component
+ * and converting the HTML to markdown. Written to clientDir so the
+ * production static file server picks them up (e.g., /docs/routing.md).
+ */
+export async function generateMarkdownPages(opts) {
+    const { serverDir, clientDir, pagesDir, pageEntries, manifest } = opts;
+    // Skip if no pages
+    if (pageEntries.length === 0)
+        return;
+    // Load SSR runtime
+    const ssrRuntimePath = pathToFileURL(path.join(serverDir, 'ssr-runtime.js')).href;
+    let ssrRuntime;
+    try {
+        ssrRuntime = await import(ssrRuntimePath);
+    }
+    catch {
+        // No SSR runtime — skip markdown generation
+        return;
+    }
+    const { render, html, unsafeStatic } = ssrRuntime;
+    installDomShims();
+    let count = 0;
+    for (const page of pageEntries) {
+        // Skip dynamic routes (e.g., /blog/:slug)
+        if (page.routePath.includes(':'))
+            continue;
+        const moduleName = `pages/${page.name.replace(/\[(\w+)\]/g, '_$1_')}.js`;
+        let modulePath = path.join(serverDir, moduleName);
+        if (!fs.existsSync(modulePath)) {
+            modulePath = path.join(serverDir, moduleName.replace(/\[/g, '_').replace(/\]/g, '_'));
+        }
+        if (!fs.existsSync(modulePath))
+            continue;
+        try {
+            const mod = await import(pathToFileURL(modulePath).href);
+            // Run loader if present
+            let loaderData = undefined;
+            if (mod.loader && typeof mod.loader === 'function') {
+                loaderData = await mod.loader({ params: {}, query: {}, url: page.routePath, headers: {} });
+                if (loaderData?.__nk_redirect)
+                    continue;
+            }
+            // Get tag name from manifest
+            const route = manifest.routes.find(r => r.path === page.routePath);
+            const tagName = route?.tagName;
+            if (!tagName)
+                continue;
+            patchLoaderDataSpread(tagName);
+            const tag = unsafeStatic(tagName);
+            const template = loaderData !== undefined
+                ? html `<${tag} .loaderData=${loaderData}></${tag}>`
+                : html `<${tag}></${tag}>`;
+            let rendered = '';
+            for (const chunk of render(template)) {
+                rendered += typeof chunk === 'string' ? chunk : String(chunk);
+            }
+            rendered = stripOuterLitMarkers(rendered);
+            const markdown = htmlToMarkdown(rendered);
+            if (!markdown.trim())
+                continue;
+            // Write to clientDir so static serving picks it up
+            // /docs/routing → clientDir/docs/routing.md
+            const mdPath = page.routePath === '/'
+                ? path.join(clientDir, 'index.md')
+                : path.join(clientDir, page.routePath + '.md');
+            // Skip if user provided their own .md file (copied from public/ during client build)
+            if (fs.existsSync(mdPath))
+                continue;
+            const mdDir = path.dirname(mdPath);
+            if (!fs.existsSync(mdDir))
+                fs.mkdirSync(mdDir, { recursive: true });
+            fs.writeFileSync(mdPath, markdown);
+            count++;
+        }
+        catch (err) {
+            // Skip pages that fail to render
+            console.warn(`[LumenJS] Markdown generation skipped for ${page.routePath}: ${err?.message}`);
+        }
+    }
+    if (count > 0) {
+        console.log(`[LumenJS] Generated ${count} markdown page(s) for /llms.txt`);
+    }
+}

package/dist/build/build-server.js

@@ -6,10 +6,9 @@ export async function buildServer(opts) {
     console.log('[LumenJS] Building server bundle...');
     // Collect server entry points (pages with loaders + layouts with loaders + API routes)
     const serverEntries = {};
+    // Include all pages in server build (enables SSR for .md endpoints)
     for (const entry of pageEntries) {
-        if (entry.hasLoader || entry.hasSubscribe || entry.prerender) {
-            serverEntries[`pages/${entry.name}`] = entry.filePath;
-        }
+        serverEntries[`pages/${entry.name}`] = entry.filePath;
     }
     for (const entry of layoutEntries) {
         if (entry.hasLoader || entry.hasSubscribe) {

package/dist/build/build.js

@@ -2,11 +2,13 @@ import path from 'path';
 import fs from 'fs';
 import { getSharedViteConfig } from '../dev-server/server.js';
 import { readProjectConfig } from '../dev-server/config.js';
-import { filePathToTagName } from '../shared/utils.js';
+import { filePathToTagName, fileGetApiMethods } from '../shared/utils.js';
 import { scanPages, scanLayouts, scanApiRoutes, scanMiddleware, getLayoutDirsForPage } from './scan.js';
 import { buildClient } from './build-client.js';
 import { buildServer } from './build-server.js';
 import { prerenderPages } from './build-prerender.js';
+import { generateMarkdownPages } from './build-markdown.js';
+import { generateLlmsTxt } from '../llms/generate.js';
 export async function buildProject(options) {
     const { projectDir } = options;
     const outDir = options.outDir || path.join(projectDir, '.lumenjs');
@@ -79,7 +81,7 @@ export async function buildProject(options) {
             const relPath = path.relative(pagesDir, e.filePath).replace(/\\/g, '/');
             return {
                 path: e.routePath,
-                module: (e.hasLoader || e.hasSubscribe || e.hasSocket || e.prerender) ? `pages/${e.name.replace(/\[(\w+)\]/g, '_$1_')}.js` : '',
+                module: `pages/${e.name.replace(/\[(\w+)\]/g, '_$1_')}.js`,
                 hasLoader: e.hasLoader,
                 hasSubscribe: e.hasSubscribe,
                 tagName: filePathToTagName(relPath),
@@ -114,6 +116,28 @@ export async function buildProject(options) {
         prefetch: prefetchStrategy,
     };
     fs.writeFileSync(path.join(outDir, 'manifest.json'), JSON.stringify(manifest, null, 2));
+    // --- Generate llms.txt ---
+    const publicLlms = path.join(publicDir, 'llms.txt');
+    if (!fs.existsSync(publicLlms)) {
+        const llmsPages = pageEntries.map(e => ({
+            path: e.routePath,
+            hasLoader: e.hasLoader,
+            hasSubscribe: e.hasSubscribe,
+        }));
+        const llmsApiRoutes = apiEntries.map(e => ({
+            path: e.routePath,
+            methods: fileGetApiMethods(e.filePath),
+        })).filter(r => r.methods.length > 0);
+        const llmsContent = generateLlmsTxt({
+            title,
+            pages: llmsPages,
+            apiRoutes: llmsApiRoutes,
+            integrations,
+            i18n: i18nConfig ? { locales: i18nConfig.locales, defaultLocale: i18nConfig.defaultLocale } : undefined,
+        });
+        fs.writeFileSync(path.join(clientDir, 'llms.txt'), llmsContent);
+        console.log('[LumenJS] Generated llms.txt');
+    }
     // --- Pre-render phase ---
     await prerenderPages({
         serverDir,
@@ -123,6 +147,14 @@ export async function buildProject(options) {
         layoutEntries,
         manifest,
     });
+    // --- Generate .md files for each page (llms.txt per-page support) ---
+    await generateMarkdownPages({
+        serverDir,
+        clientDir,
+        pagesDir,
+        pageEntries,
+        manifest,
+    });
     console.log('[LumenJS] Build complete.');
     console.log(`  Output: ${outDir}`);
     console.log(`  Client assets: ${clientDir}`);

package/dist/build/serve-static.js

@@ -4,6 +4,8 @@ import { createGzip } from 'zlib';
 import { pipeline } from 'stream';
 export const MIME_TYPES = {
     '.html': 'text/html; charset=utf-8',
+    '.md': 'text/markdown; charset=utf-8',
+    '.txt': 'text/plain; charset=utf-8',
     '.js': 'application/javascript; charset=utf-8',
     '.mjs': 'application/javascript; charset=utf-8',
     '.css': 'text/css; charset=utf-8',
@@ -21,7 +23,6 @@ export const MIME_TYPES = {
     '.eot': 'application/vnd.ms-fontobject',
     '.otf': 'font/otf',
     '.map': 'application/json',
-    '.txt': 'text/plain; charset=utf-8',
     '.xml': 'application/xml',
     '.webmanifest': 'application/manifest+json',
 };

package/dist/build/serve.js

@@ -332,7 +332,7 @@ export async function serveProject(options) {
                 fs.createReadStream(filePath).pipe(res);
                 return;
             }
-            // 3. Static assets — try to serve from client dir
+            // 3. Static assets — try to serve from client dir (includes pre-generated .md files)
             if (pathname.includes('.')) {
                 const served = serveStaticFile(clientDir, pathname, req, res);
                 if (served)

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

@@ -75,6 +75,7 @@ export function lumenLlmsPlugin(projectDir) {
                         integrations: config.integrations,
                         i18n: config.i18n ? { locales: config.i18n.locales, defaultLocale: config.i18n.defaultLocale } : undefined,
                         db: config.db,
+                        baseUrl: '',
                     });
                     res.setHeader('Content-Type', 'text/plain; charset=utf-8');
                     res.setHeader('Cache-Control', 'no-store');

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

@@ -13,15 +13,16 @@ import { Plugin } from 'vite';
  *   }
  *
  *   export class PageItem extends LitElement {
- *     @property({ type: Object }) loaderData = {};
+ *     @property({ type: Object }) item = null;
+ *     @property({ type: Number }) timestamp = 0;
  *     render() {
- *       return html`<h1>${this.loaderData.item?.name}</h1>`;
+ *       return html`<h1>${this.item?.name}</h1>`;
  *     }
  *   }
  *
  * The loader runs server-side via /__nk_loader/<page-path>
  * Layout loaders run via /__nk_loader/__layout/?__dir=<dir>
- * The router auto-fetches and passes the result as `loaderData` property.
+ * The router auto-fetches and spreads each key as an individual property on the element.
  */
 export declare function lumenLoadersPlugin(pagesDir: string): Plugin;
 /**

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

@@ -16,15 +16,16 @@ import { installDomShims } from '../../shared/dom-shims.js';
  *   }
  *
  *   export class PageItem extends LitElement {
- *     @property({ type: Object }) loaderData = {};
+ *     @property({ type: Object }) item = null;
+ *     @property({ type: Number }) timestamp = 0;
  *     render() {
- *       return html`<h1>${this.loaderData.item?.name}</h1>`;
+ *       return html`<h1>${this.item?.name}</h1>`;
  *     }
  *   }
  *
  * The loader runs server-side via /__nk_loader/<page-path>
  * Layout loaders run via /__nk_loader/__layout/?__dir=<dir>
- * The router auto-fetches and passes the result as `loaderData` property.
+ * The router auto-fetches and spreads each key as an individual property on the element.
  */
 export function lumenLoadersPlugin(pagesDir) {
     return {

package/dist/editor/ai/types.d.ts

@@ -26,5 +26,5 @@ export interface AiStatusResult {
     configured: boolean;
     backend: 'claude-code' | 'opencode';
 }
-export declare const SYSTEM_PROMPT = "You are an AI coding assistant working inside a LumenJS project.\n\nLumenJS is a full-stack Lit web component framework with file-based routing, server loaders, SSR, and API routes.\n\nKey conventions:\n- Pages live in `pages/` directory \u2014 file path maps to URL route\n- Components are Lit web components (LitElement) auto-registered by file path\n- Layouts: `_layout.ts` in any directory for nested layouts (use <slot>)\n- API routes: `api/` directory with named exports (GET, POST, PUT, DELETE)\n- Server loaders: `export async function loader()` for server-side data fetching\n- Styles: use Tailwind CSS classes or Lit's `static styles` with css template tag\n- Config: `lumenjs.config.ts` at project root\n\nAuto-registration:\n- Pages and layouts are auto-registered by file path \u2014 do NOT add @customElement decorators.\n  `pages/about.ts` \u2192 `<page-about>`, `pages/blog/_layout.ts` \u2192 `<layout-blog>`\n\nServer loaders:\n- `export async function loader({ params, query, url, headers, locale })` at file top level.\n- Return a data object \u2192 available as `this.loaderData` on the page element.\n\nSubscribe (SSE):\n- `export async function subscribe({ params, headers, locale, push })` for real-time data.\n- Call `push(data)` to send events \u2192 available as `this.liveData` on the page element.\n\nMiddleware:\n- `_middleware.ts` in any directory applies to that route subtree.\n\nDynamic routes:\n- `[slug]` for dynamic params, `[...rest]` for catch-all.\n\nProperties:\n- Use `@property()` for public reactive props, `@state()` for internal state (from `lit/decorators.js`).\n\nExample \u2014 adding a new page (`pages/contact.ts`):\n```\nimport { LitElement, html, css } from 'lit';\nimport { property } from 'lit/decorators.js';\n\nexport default class extends LitElement {\n  static styles = css\\`/* styles here */\\`;\n  render() { return html\\`<h1>Contact</h1>\\`; }\n}\n```\n\nIMPORTANT \u2014 Styling rules:\n- When asked to change a style (color, font, spacing, etc.), find and UPDATE the EXISTING CSS rule in `static styles = css\\`...\\``. Do NOT add a new class or duplicate rule.\n- Never add inline `style=\"...\"` attributes on HTML template elements. Always modify the CSS rule in `static styles`.\n- Example: to change the h1 color, find the `h1 { ... }` rule in `static styles` and update its `color` property. Do not create a new class.\n- If no CSS rule exists for the element, add one to the existing `static styles` block \u2014 do not add a separate `<style>` tag.\n\nIMPORTANT \u2014 i18n / translation rules (when the project uses i18n):\n- Text content in templates uses `t('key')` from `@lumenjs/i18n` \u2014 NEVER replace a `t()` call with hardcoded text.\n- To change displayed text, edit the translation value in `locales/<locale>.json` \u2014 do NOT modify the template.\n- Example: to change the subtitle, update `\"home.subtitle\"` in `locales/en.json` (and other locale files like `locales/fr.json`).\n- To add new text, add a key to ALL locale JSON files and use `t('new.key')` in the template.\n- The dev server watches locale files and updates the page automatically via HMR.\n\nYou have full access to the filesystem and can run shell commands.\nWhen a task requires a new npm package, install it with `npm install <package>`.\nAfter npm install, the dev server will automatically restart to load the new dependency.\nVite's HMR will pick up file changes automatically \u2014 no manual restart needed.\n\nIMPORTANT \u2014 Be fast and direct:\n- Make changes immediately \u2014 do not explain what you will do before doing it.\n- Read the file, make the edit, done. Minimize tool calls.\n- For simple CSS/text changes, edit directly without reading first if you have the source context.\n- Keep responses under 2 sentences. The user sees the diff, not your explanation.\n";
+export declare const SYSTEM_PROMPT = "You are an AI coding assistant working inside a LumenJS project.\n\nLumenJS is a full-stack Lit web component framework with file-based routing, server loaders, SSR, and API routes.\n\nKey conventions:\n- Pages live in `pages/` directory \u2014 file path maps to URL route\n- Components are Lit web components (LitElement) auto-registered by file path\n- Layouts: `_layout.ts` in any directory for nested layouts (use <slot>)\n- API routes: `api/` directory with named exports (GET, POST, PUT, DELETE)\n- Server loaders: `export async function loader()` for server-side data fetching\n- Styles: use Tailwind CSS classes or Lit's `static styles` with css template tag\n- Config: `lumenjs.config.ts` at project root\n\nAuto-registration:\n- Pages and layouts are auto-registered by file path \u2014 do NOT add @customElement decorators.\n  `pages/about.ts` \u2192 `<page-about>`, `pages/blog/_layout.ts` \u2192 `<layout-blog>`\n\nServer loaders:\n- `export async function loader({ params, query, url, headers, locale })` at file top level.\n- Return a data object \u2192 each key is spread as an individual property on the page element (e.g., return `{ posts }` \u2192 access as `this.posts`).\n\nSubscribe (SSE):\n- `export async function subscribe({ params, headers, locale, push })` for real-time data.\n- Call `push(data)` to send events \u2192 each key is spread as an individual property on the page element (same as loader data).\n\nMiddleware:\n- `_middleware.ts` in any directory applies to that route subtree.\n\nDynamic routes:\n- `[slug]` for dynamic params, `[...rest]` for catch-all.\n\nProperties:\n- Use `@property()` for public reactive props, `@state()` for internal state (from `lit/decorators.js`).\n\nExample \u2014 adding a new page (`pages/contact.ts`):\n```\nimport { LitElement, html, css } from 'lit';\nimport { property } from 'lit/decorators.js';\n\nexport default class extends LitElement {\n  static styles = css\\`/* styles here */\\`;\n  render() { return html\\`<h1>Contact</h1>\\`; }\n}\n```\n\nIMPORTANT \u2014 Styling rules:\n- When asked to change a style (color, font, spacing, etc.), find and UPDATE the EXISTING CSS rule in `static styles = css\\`...\\``. Do NOT add a new class or duplicate rule.\n- Never add inline `style=\"...\"` attributes on HTML template elements. Always modify the CSS rule in `static styles`.\n- Example: to change the h1 color, find the `h1 { ... }` rule in `static styles` and update its `color` property. Do not create a new class.\n- If no CSS rule exists for the element, add one to the existing `static styles` block \u2014 do not add a separate `<style>` tag.\n\nIMPORTANT \u2014 i18n / translation rules (when the project uses i18n):\n- Text content in templates uses `t('key')` from `@lumenjs/i18n` \u2014 NEVER replace a `t()` call with hardcoded text.\n- To change displayed text, edit the translation value in `locales/<locale>.json` \u2014 do NOT modify the template.\n- Example: to change the subtitle, update `\"home.subtitle\"` in `locales/en.json` (and other locale files like `locales/fr.json`).\n- To add new text, add a key to ALL locale JSON files and use `t('new.key')` in the template.\n- The dev server watches locale files and updates the page automatically via HMR.\n\nYou have full access to the filesystem and can run shell commands.\nWhen a task requires a new npm package, install it with `npm install <package>`.\nAfter npm install, the dev server will automatically restart to load the new dependency.\nVite's HMR will pick up file changes automatically \u2014 no manual restart needed.\n\nIMPORTANT \u2014 Be fast and direct:\n- Make changes immediately \u2014 do not explain what you will do before doing it.\n- Read the file, make the edit, done. Minimize tool calls.\n- For simple CSS/text changes, edit directly without reading first if you have the source context.\n- Keep responses under 2 sentences. The user sees the diff, not your explanation.\n";
 export declare function buildPrompt(options: AiChatOptions): string;

package/dist/editor/ai/types.js

@@ -20,11 +20,11 @@ Auto-registration:
 
 Server loaders:
 - \`export async function loader({ params, query, url, headers, locale })\` at file top level.
-- Return a data object → available as \`this.loaderData\` on the page element.
+- Return a data object → each key is spread as an individual property on the page element (e.g., return \`{ posts }\` → access as \`this.posts\`).
 
 Subscribe (SSE):
 - \`export async function subscribe({ params, headers, locale, push })\` for real-time data.
-- Call \`push(data)\` to send events → available as \`this.liveData\` on the page element.
+- Call \`push(data)\` to send events → each key is spread as an individual property on the page element (same as loader data).
 
 Middleware:
 - \`_middleware.ts\` in any directory applies to that route subtree.

package/dist/llms/generate.d.ts

@@ -14,6 +14,8 @@ export interface LlmsApiRoute {
 }
 export interface LlmsTxtInput {
     title: string;
+    description?: string;
+    baseUrl?: string;
     pages: LlmsPage[];
     apiRoutes: LlmsApiRoute[];
     integrations: string[];
@@ -26,9 +28,21 @@ export interface LlmsTxtInput {
     };
 }
 /**
- * Generate the llms.txt content from project metadata and resolved page data.
+ * Generate the llms.txt content following the llmstxt.org spec.
+ *
+ * Structure: H1 title, blockquote summary, H2 sections with
+ * markdown links to each page (linking to .md versions).
  */
 export declare function generateLlmsTxt(input: LlmsTxtInput): string;
+/**
+ * Generate llms-full.txt — all page content inlined as one markdown document.
+ */
+export declare function generateLlmsFullTxt(input: LlmsTxtInput & {
+    pageContents: {
+        path: string;
+        markdown: string;
+    }[];
+}): string;
 /**
  * Try to resolve dynamic route entries by finding a parent/sibling index page
  * whose loader returns an array, then calling the dynamic page's loader for each item.

package/dist/llms/generate.js

@@ -1,62 +1,53 @@
 /**
- * Generate the llms.txt content from project metadata and resolved page data.
+ * Generate the llms.txt content following the llmstxt.org spec.
+ *
+ * Structure: H1 title, blockquote summary, H2 sections with
+ * markdown links to each page (linking to .md versions).
  */
 export function generateLlmsTxt(input) {
     const lines = [];
+    const base = input.baseUrl ? input.baseUrl.replace(/\/$/, '') : '';
     lines.push(`# ${input.title}`);
     lines.push('');
-    lines.push('> Built with LumenJS');
+    lines.push(`> ${input.description || `${input.title}. Built with LumenJS.`}`);
     lines.push('');
-    // Pages section
-    if (input.pages.length > 0) {
-        lines.push('## Pages');
+    // Group pages by top-level path segment
+    const groups = new Map();
+    for (const page of input.pages) {
+        const segments = page.path.split('/').filter(Boolean);
+        const section = segments.length > 0 ? segments[0] : 'pages';
+        if (!groups.has(section))
+            groups.set(section, []);
+        groups.get(section).push(page);
+    }
+    // Pages — grouped by section with links
+    for (const [section, pages] of groups) {
+        const sectionTitle = section.charAt(0).toUpperCase() + section.slice(1);
+        lines.push(`## ${sectionTitle}`);
         lines.push('');
-        for (const page of input.pages) {
-            lines.push(`### ${page.path}`);
+        for (const page of pages) {
             const isDynamic = page.path.includes(':');
-            if (isDynamic) {
-                // Dynamic route — show expanded entries if available
-                if (page.dynamicEntries && page.dynamicEntries.length > 0) {
-                    lines.push(`Dynamic route — ${page.dynamicEntries.length} ${page.dynamicEntries.length === 1 ? 'entry' : 'entries'}:`);
-                    lines.push('');
-                    for (const entry of page.dynamicEntries) {
-                        lines.push(`#### ${entry.path}`);
-                        if (entry.loaderData) {
-                            lines.push(flattenData(entry.loaderData));
-                        }
-                        lines.push('');
-                    }
-                }
-                else {
-                    lines.push('- Dynamic route');
-                    lines.push('');
-                }
-            }
-            else if (page.loaderData && typeof page.loaderData === 'object') {
-                // Static page with loader data
-                lines.push(flattenData(page.loaderData));
-                lines.push('');
-            }
-            else {
-                // Simple page
-                const features = [];
-                if (page.hasLoader)
-                    features.push('with loader data');
-                if (page.hasSubscribe)
-                    features.push('with live data');
-                lines.push(`- Server-rendered page${features.length ? ' ' + features.join(', ') : ''}`);
-                lines.push('');
-            }
+            const label = page.path === '/' ? 'Home' : page.path;
+            const features = [];
+            if (isDynamic)
+                features.push('dynamic');
+            if (page.hasLoader)
+                features.push('server data');
+            if (page.hasSubscribe)
+                features.push('live data');
+            const desc = features.length > 0 ? `: ${features.join(', ')}` : '';
+            // Link to .md version for LLM-readable content (skip dynamic routes)
+            const href = !isDynamic ? `${base}${page.path}.md` : `${base}${page.path}`;
+            lines.push(`- [${label}](${href})${desc}`);
         }
+        lines.push('');
     }
     // API Routes section
     if (input.apiRoutes.length > 0) {
-        lines.push('## API Routes');
+        lines.push('## API');
         lines.push('');
         for (const route of input.apiRoutes) {
-            for (const method of route.methods) {
-                lines.push(`- ${method} /api/${route.path}`);
-            }
+            lines.push(`- [${route.methods.join(', ')} /api/${route.path}](${base}/api/${route.path})`);
         }
         lines.push('');
     }
@@ -85,6 +76,25 @@ export function generateLlmsTxt(input) {
     }
     return lines.join('\n').trimEnd() + '\n';
 }
+/**
+ * Generate llms-full.txt — all page content inlined as one markdown document.
+ */
+export function generateLlmsFullTxt(input) {
+    const lines = [];
+    lines.push(`# ${input.title}`);
+    lines.push('');
+    lines.push(`> ${input.description || `${input.title}. Built with LumenJS.`}`);
+    lines.push('');
+    for (const page of input.pageContents) {
+        lines.push('---');
+        lines.push(`source: ${page.path}`);
+        lines.push('---');
+        lines.push('');
+        lines.push(page.markdown.trim());
+        lines.push('');
+    }
+    return lines.join('\n').trimEnd() + '\n';
+}
 /**
  * Flatten a loader data object into key-value text lines.
  */

package/dist/runtime/communication.d.ts

@@ -1,26 +1,65 @@
 /**
  * Client-side communication SDK.
- * Connects to the server via Socket.io and provides a clean API for chat, typing, and presence.
+ * Connects to the server via Socket.io and provides a clean API for chat, typing, presence, and calls.
  */
 /**
  * Connect to the communication socket.
- * Must be called before using any other functions.
+ * Reuses an existing socket if one is already connected.
  */
-export declare function connectChat(params?: Record<string, string>): Promise<void>;
-/** Join a conversation room to receive messages */
-export declare function joinConversation(conversationId: string): void;
-/** Leave a conversation room */
-export declare function leaveConversation(conversationId: string): void;
-/** Send a message */
-export declare function sendMessage(conversationId: string, content: string, type?: string): void;
-/** Mark a message as read */
-export declare function markRead(conversationId: string, messageId: string): void;
+export declare function connectChat(params?: Record<string, string>): Promise<any>;
+/** Get the underlying socket instance (for call-service or other integrations) */
+export declare function getSocket(): any;
+/** Set an externally-created socket (e.g. from call-service or router) */
+export declare function setSocket(socket: any): void;
+/** Send a message (text, image, file, audio) */
+export declare function sendMessage(conversationId: string, content: string, opts?: {
+    type?: string;
+    attachment?: any;
+    replyTo?: any;
+    encrypted?: boolean;
+}): void;
+/** Mark messages as read */
+export declare function markRead(conversationId: string, messageIds?: string[]): void;
 /** React to a message with an emoji (toggle) */
 export declare function reactToMessage(messageId: string, conversationId: string, emoji: string): void;
 /** Edit a message */
 export declare function editMessage(messageId: string, conversationId: string, content: string): void;
 /** Delete a message */
 export declare function deleteMessage(messageId: string, conversationId: string): void;
+/** Load messages for a conversation (lazy-load) */
+export declare function loadMessages(conversationId: string): void;
+/** Join a conversation room to receive messages */
+export declare function joinConversation(conversationId: string): void;
+/** Leave a conversation room */
+export declare function leaveConversation(conversationId: string): void;
+/** Start typing indicator */
+export declare function startTyping(conversationId: string): void;
+/** Stop typing indicator */
+export declare function stopTyping(conversationId: string): void;
+/** Update presence status */
+export declare function updatePresence(status: 'online' | 'offline' | 'away' | 'busy'): void;
+/** Request bulk presence sync for a list of user IDs */
+export declare function requestPresenceSync(userIds: string[]): void;
+/** Refresh notification/message badge counts */
+export declare function refreshBadge(): void;
+/** Listen for new messages */
+export declare function onMessage(handler: (message: any) => void): () => void;
+/** Listen for typing updates */
+export declare function onTyping(handler: (data: {
+    conversationId: string;
+    userId: string;
+    isTyping: boolean;
+}) => void): () => void;
+/** Listen for presence changes */
+export declare function onPresence(handler: (data: {
+    userId: string;
+    status: string;
+    lastSeen: string;
+}) => void): () => void;
+/** Listen for bulk presence sync response */
+export declare function onPresenceSync(handler: (data: {
+    presences: Record<string, any>;
+}) => void): () => void;
 /** Listen for reaction updates */
 export declare function onReactionUpdate(handler: (data: {
     messageId: string;
@@ -37,6 +76,14 @@ export declare function onMessageDeleted(handler: (data: {
     messageId: string;
     conversationId: string;
 }) => void): () => void;
+/** Listen for read receipts */
+export declare function onReadReceipt(handler: (data: any) => void): () => void;
+/** Listen for lazy-loaded conversation messages */
+export declare function onConversationMessages(handler: (data: {
+    conversationId: string;
+    messages: any[];
+    participants: any[];
+}) => void): () => void;
 /** Upload a file (returns attachment metadata) */
 export declare function uploadFile(file: Blob, filename: string, encrypted?: boolean): Promise<{
     id: string;
@@ -45,31 +92,9 @@ export declare function uploadFile(file: Blob, filename: string, encrypted?: boo
 }>;
 /** Fetch link previews for a text */
 export declare function fetchLinkPreviews(text: string): Promise<any[]>;
-/** Start typing indicator */
-export declare function startTyping(conversationId: string): void;
-/** Stop typing indicator */
-export declare function stopTyping(conversationId: string): void;
-/** Update presence status */
-export declare function updatePresence(status: 'online' | 'offline' | 'away' | 'busy'): void;
-/** Listen for new messages */
-export declare function onMessage(handler: (message: any) => void): () => void;
-/** Listen for typing updates */
-export declare function onTyping(handler: (data: {
-    conversationId: string;
-    userId: string;
-    isTyping: boolean;
-}) => void): () => void;
-/** Listen for presence changes */
-export declare function onPresence(handler: (data: {
-    userId: string;
-    status: string;
-    lastSeen: string;
-}) => void): () => void;
-/** Listen for read receipts */
-export declare function onReadReceipt(handler: (data: any) => void): () => void;
 /** Listen for incoming calls */
 export declare function onIncomingCall(handler: (call: any) => void): () => void;
-/** Listen for call state changes (initiating, ringing, connecting, connected, ended) */
+/** Listen for call state changes */
 export declare function onCallStateChanged(handler: (data: {
     callId: string;
     state: string;
@@ -94,11 +119,15 @@ export declare function onMediaChanged(handler: (data: {
     screenShare?: boolean;
 }) => void): () => void;
 /** Initiate an audio or video call */
-export declare function initiateCall(conversationId: string, type: 'audio' | 'video', calleeIds: string[]): void;
+export declare function initiateCall(conversationId: string, type: 'audio' | 'video', calleeIds: string[], caller?: {
+    callerName?: string;
+    callerInitials?: string;
+    callerColor?: string;
+}): void;
 /** Respond to an incoming call */
 export declare function respondToCall(callId: string, action: 'accept' | 'reject'): void;
 /** Hang up an active call */
-export declare function hangup(callId: string, reason?: string): void;
+export declare function hangup(callId: string, reason?: string, duration?: string | null): void;
 /** Toggle audio/video/screenshare during a call */
 export declare function toggleMedia(callId: string, opts: {
     audio?: boolean;

package/dist/runtime/communication.js

@@ -1,12 +1,12 @@
 /**
  * Client-side communication SDK.
- * Connects to the server via Socket.io and provides a clean API for chat, typing, and presence.
+ * Connects to the server via Socket.io and provides a clean API for chat, typing, presence, and calls.
  */
 let _socket = null;
 let _handlers = new Map();
 function emit(event, data) {
     if (!_socket)
-        throw new Error('Communication not connected. Call connectChat() first.');
+        return;
     _socket.emit(`nk:${event}`, data);
 }
 function addHandler(event, handler) {
@@ -22,15 +22,19 @@ function removeHandler(event, handler) {
 }
 /**
  * Connect to the communication socket.
- * Must be called before using any other functions.
+ * Reuses an existing socket if one is already connected.
  */
 export async function connectChat(params) {
-    if (_socket)
-        return;
+    if (_socket?.connected)
+        return _socket;
     const { io } = await import('socket.io-client');
     _socket = io('/nk/messages', {
         path: '/__nk_socketio/',
         query: { ...params, __params: JSON.stringify(params || {}) },
+        reconnection: true,
+        reconnectionAttempts: Infinity,
+        reconnectionDelay: 1000,
+        reconnectionDelayMax: 10000,
     });
     _socket.on('nk:data', (data) => {
         if (data?.event) {
@@ -41,22 +45,44 @@ export async function connectChat(params) {
             }
         }
     });
+    return _socket;
 }
-/** Join a conversation room to receive messages */
-export function joinConversation(conversationId) {
-    emit('conversation:join', { conversationId });
-}
-/** Leave a conversation room */
-export function leaveConversation(conversationId) {
-    emit('conversation:leave', { conversationId });
+/** Get the underlying socket instance (for call-service or other integrations) */
+export function getSocket() { return _socket; }
+/** Set an externally-created socket (e.g. from call-service or router) */
+export function setSocket(socket) {
+    if (_socket === socket)
+        return;
+    _socket = socket;
+    // Attach the nk:data handler if not already attached
+    if (_socket && !_socket.__nk_comm_attached) {
+        _socket.__nk_comm_attached = true;
+        _socket.on('nk:data', (data) => {
+            if (data?.event) {
+                const handlers = _handlers.get(data.event);
+                if (handlers) {
+                    for (const h of handlers)
+                        h(data.data);
+                }
+            }
+        });
+    }
 }
-/** Send a message */
-export function sendMessage(conversationId, content, type = 'text') {
-    emit('message:send', { conversationId, content, type });
+// ── Messages ─────────────────────────────────────────────────────
+/** Send a message (text, image, file, audio) */
+export function sendMessage(conversationId, content, opts) {
+    emit('message:send', {
+        conversationId,
+        content,
+        type: opts?.type || 'text',
+        ...(opts?.attachment ? { attachment: opts.attachment } : {}),
+        ...(opts?.replyTo ? { replyTo: opts.replyTo } : {}),
+        ...(opts?.encrypted ? { encrypted: true } : {}),
+    });
 }
-/** Mark a message as read */
-export function markRead(conversationId, messageId) {
-    emit('message:read', { conversationId, messageId });
+/** Mark messages as read */
+export function markRead(conversationId, messageIds) {
+    emit('message:read', { conversationId, ...(messageIds ? { messageIds } : {}) });
 }
 /** React to a message with an emoji (toggle) */
 export function reactToMessage(messageId, conversationId, emoji) {
@@ -70,6 +96,61 @@ export function editMessage(messageId, conversationId, content) {
 export function deleteMessage(messageId, conversationId) {
     emit('message:delete', { messageId, conversationId });
 }
+/** Load messages for a conversation (lazy-load) */
+export function loadMessages(conversationId) {
+    emit('conversation:load-messages', { conversationId });
+}
+/** Join a conversation room to receive messages */
+export function joinConversation(conversationId) {
+    emit('conversation:join', { conversationId });
+}
+/** Leave a conversation room */
+export function leaveConversation(conversationId) {
+    emit('conversation:leave', { conversationId });
+}
+// ── Typing ───────────────────────────────────────────────────────
+/** Start typing indicator */
+export function startTyping(conversationId) {
+    emit('typing:start', { conversationId });
+}
+/** Stop typing indicator */
+export function stopTyping(conversationId) {
+    emit('typing:stop', { conversationId });
+}
+// ── Presence ─────────────────────────────────────────────────────
+/** Update presence status */
+export function updatePresence(status) {
+    emit('presence:update', { status });
+}
+/** Request bulk presence sync for a list of user IDs */
+export function requestPresenceSync(userIds) {
+    emit('presence:sync', { userIds });
+}
+/** Refresh notification/message badge counts */
+export function refreshBadge() {
+    emit('badge:refresh', {});
+}
+// ── Event Listeners ──────────────────────────────────────────────
+/** Listen for new messages */
+export function onMessage(handler) {
+    addHandler('message:new', handler);
+    return () => removeHandler('message:new', handler);
+}
+/** Listen for typing updates */
+export function onTyping(handler) {
+    addHandler('typing:update', handler);
+    return () => removeHandler('typing:update', handler);
+}
+/** Listen for presence changes */
+export function onPresence(handler) {
+    addHandler('presence:changed', handler);
+    return () => removeHandler('presence:changed', handler);
+}
+/** Listen for bulk presence sync response */
+export function onPresenceSync(handler) {
+    addHandler('presence:sync', handler);
+    return () => removeHandler('presence:sync', handler);
+}
 /** Listen for reaction updates */
 export function onReactionUpdate(handler) {
     addHandler('message:reaction-update', handler);
@@ -85,6 +166,17 @@ export function onMessageDeleted(handler) {
     addHandler('message:deleted', handler);
     return () => removeHandler('message:deleted', handler);
 }
+/** Listen for read receipts */
+export function onReadReceipt(handler) {
+    addHandler('read-receipt:update', handler);
+    return () => removeHandler('read-receipt:update', handler);
+}
+/** Listen for lazy-loaded conversation messages */
+export function onConversationMessages(handler) {
+    addHandler('conversation:messages', handler);
+    return () => removeHandler('conversation:messages', handler);
+}
+// ── File Uploads & Link Previews ─────────────────────────────────
 /** Upload a file (returns attachment metadata) */
 export async function uploadFile(file, filename, encrypted = false) {
     const res = await fetch('/__nk_comm/upload', {
@@ -112,45 +204,13 @@ export async function fetchLinkPreviews(text) {
     const data = await res.json();
     return data.previews || [];
 }
-/** Start typing indicator */
-export function startTyping(conversationId) {
-    emit('typing:start', { conversationId });
-}
-/** Stop typing indicator */
-export function stopTyping(conversationId) {
-    emit('typing:stop', { conversationId });
-}
-/** Update presence status */
-export function updatePresence(status) {
-    emit('presence:update', { status });
-}
-/** Listen for new messages */
-export function onMessage(handler) {
-    addHandler('message:new', handler);
-    return () => removeHandler('message:new', handler);
-}
-/** Listen for typing updates */
-export function onTyping(handler) {
-    addHandler('typing:update', handler);
-    return () => removeHandler('typing:update', handler);
-}
-/** Listen for presence changes */
-export function onPresence(handler) {
-    addHandler('presence:changed', handler);
-    return () => removeHandler('presence:changed', handler);
-}
-/** Listen for read receipts */
-export function onReadReceipt(handler) {
-    addHandler('read-receipt:update', handler);
-    return () => removeHandler('read-receipt:update', handler);
-}
-// ── Calls ─────────────────────────────────────────────────────────
+// ── Calls ────────────────────────────────────────────────────────
 /** Listen for incoming calls */
 export function onIncomingCall(handler) {
     addHandler('call:incoming', handler);
     return () => removeHandler('call:incoming', handler);
 }
-/** Listen for call state changes (initiating, ringing, connecting, connected, ended) */
+/** Listen for call state changes */
 export function onCallStateChanged(handler) {
     addHandler('call:state-changed', handler);
     return () => removeHandler('call:state-changed', handler);
@@ -171,22 +231,22 @@ export function onMediaChanged(handler) {
     return () => removeHandler('call:media-changed', handler);
 }
 /** Initiate an audio or video call */
-export function initiateCall(conversationId, type, calleeIds) {
-    emit('call:initiate', { conversationId, type, calleeIds });
+export function initiateCall(conversationId, type, calleeIds, caller) {
+    emit('call:initiate', { conversationId, type, calleeIds, ...caller });
 }
 /** Respond to an incoming call */
 export function respondToCall(callId, action) {
     emit('call:respond', { callId, action });
 }
 /** Hang up an active call */
-export function hangup(callId, reason = 'completed') {
-    emit('call:hangup', { callId, reason });
+export function hangup(callId, reason = 'completed', duration) {
+    emit('call:hangup', { callId, reason, ...(duration ? { duration } : {}) });
 }
 /** Toggle audio/video/screenshare during a call */
 export function toggleMedia(callId, opts) {
     emit('call:media-toggle', { callId, ...opts });
 }
-// ── WebRTC Signaling ──────────────────────────────────────────────
+// ── WebRTC Signaling ─────────────────────────────────────────────
 /** Send SDP offer to a peer */
 export function sendOffer(callId, toUserId, sdp) {
     emit('signal:offer', { callId, fromUserId: '', toUserId, type: 'offer', sdp });

package/dist/runtime/router.js

@@ -170,7 +170,7 @@ export class NkRouter {
             es.onmessage = (e) => {
                 const pageEl = this.findPageElement(match.route.tagName);
                 if (pageEl)
-                    pageEl.liveData = JSON.parse(e.data);
+                    this.spreadData(pageEl, JSON.parse(e.data));
             };
             this.subscriptions.push(es);
         }
@@ -204,7 +204,7 @@ export class NkRouter {
                 socket.on('nk:data', (data) => {
                     const pageEl = this.findPageElement(match.route.tagName);
                     if (pageEl) {
-                        pageEl.liveData = data;
+                        this.spreadData(pageEl, data);
                         injectEmit();
                     }
                 });
@@ -217,7 +217,7 @@ export class NkRouter {
                 es.onmessage = (e) => {
                     const layoutEl = this.outlet?.querySelector(layout.tagName);
                     if (layoutEl)
-                        layoutEl.liveData = JSON.parse(e.data);
+                        this.spreadData(layoutEl, JSON.parse(e.data));
                 };
                 this.subscriptions.push(es);
             }

package/dist/shared/html-to-markdown.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Convert simple HTML to markdown.
+ * Handles the subset of HTML that Lit SSR produces for LumenJS pages.
+ * Not a full HTML parser — intentionally minimal.
+ */
+export declare function htmlToMarkdown(html: string): string;

package/dist/shared/html-to-markdown.js

@@ -0,0 +1,73 @@
+/**
+ * Convert simple HTML to markdown.
+ * Handles the subset of HTML that Lit SSR produces for LumenJS pages.
+ * Not a full HTML parser — intentionally minimal.
+ */
+export function htmlToMarkdown(html) {
+    let md = html;
+    // Extract content from declarative shadow DOM (<template shadowroot="open">...</template>)
+    md = md.replace(/<template\s+shadowroot(?:mode)?="open"[^>]*>([\s\S]*?)<\/template>/gi, '$1');
+    // Remove script/style tags and their content
+    md = md.replace(/<script[\s\S]*?<\/script>/gi, '');
+    md = md.replace(/<style[\s\S]*?<\/style>/gi, '');
+    md = md.replace(/<template[\s\S]*?<\/template>/gi, '');
+    // Remove Lit SSR markers (<!--lit-part-->, <!--/lit-part-->, etc.)
+    md = md.replace(/<!--[\s\S]*?-->/g, '');
+    // Headings
+    md = md.replace(/<h1[^>]*>([\s\S]*?)<\/h1>/gi, (_, c) => `# ${strip(c)}\n\n`);
+    md = md.replace(/<h2[^>]*>([\s\S]*?)<\/h2>/gi, (_, c) => `## ${strip(c)}\n\n`);
+    md = md.replace(/<h3[^>]*>([\s\S]*?)<\/h3>/gi, (_, c) => `### ${strip(c)}\n\n`);
+    md = md.replace(/<h4[^>]*>([\s\S]*?)<\/h4>/gi, (_, c) => `#### ${strip(c)}\n\n`);
+    // Links
+    md = md.replace(/<a[^>]*href="([^"]*)"[^>]*>([\s\S]*?)<\/a>/gi, (_, href, text) => `[${strip(text)}](${href})`);
+    // Bold / italic
+    md = md.replace(/<(strong|b)[^>]*>([\s\S]*?)<\/\1>/gi, (_, __, c) => `**${strip(c)}**`);
+    md = md.replace(/<(em|i)[^>]*>([\s\S]*?)<\/\1>/gi, (_, __, c) => `*${strip(c)}*`);
+    // Inline code
+    md = md.replace(/<code[^>]*>([\s\S]*?)<\/code>/gi, (_, c) => `\`${strip(c)}\``);
+    // Code blocks (pre > code or pre alone)
+    md = md.replace(/<pre[^>]*>\s*<code[^>]*>([\s\S]*?)<\/code>\s*<\/pre>/gi, (_, c) => `\n\`\`\`\n${decodeEntities(strip(c))}\n\`\`\`\n\n`);
+    md = md.replace(/<pre[^>]*>([\s\S]*?)<\/pre>/gi, (_, c) => `\n\`\`\`\n${decodeEntities(strip(c))}\n\`\`\`\n\n`);
+    // List items
+    md = md.replace(/<li[^>]*>([\s\S]*?)<\/li>/gi, (_, c) => `- ${strip(c).trim()}\n`);
+    // Table → simple text rows
+    md = md.replace(/<tr[^>]*>([\s\S]*?)<\/tr>/gi, (_, c) => {
+        const cells = [...c.matchAll(/<t[hd][^>]*>([\s\S]*?)<\/t[hd]>/gi)].map((m) => strip(m[1]).trim());
+        return cells.length > 0 ? `| ${cells.join(' | ')} |\n` : '';
+    });
+    // Paragraphs and divs → newlines
+    md = md.replace(/<\/p>/gi, '\n\n');
+    md = md.replace(/<br\s*\/?>/gi, '\n');
+    md = md.replace(/<\/div>/gi, '\n');
+    // Images
+    md = md.replace(/<img[^>]*alt="([^"]*)"[^>]*>/gi, (_, alt) => alt ? `[${alt}]` : '');
+    md = md.replace(/<img[^>]*>/gi, '');
+    // Strip all remaining HTML tags
+    md = md.replace(/<[^>]+>/g, '');
+    // Decode HTML entities
+    md = decodeEntities(md);
+    // Clean up whitespace
+    md = md.replace(/\n{3,}/g, '\n\n');
+    md = md.trim();
+    return md + '\n';
+}
+/** Strip HTML tags from a string. */
+function strip(html) {
+    return html.replace(/<[^>]+>/g, '').trim();
+}
+/** Decode common HTML entities. */
+function decodeEntities(text) {
+    return text
+        .replace(/&amp;/g, '&')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'")
+        .replace(/&rarr;/g, '→')
+        .replace(/&larr;/g, '←')
+        .replace(/&middot;/g, '·')
+        .replace(/&copy;/g, '©')
+        .replace(/\\u003c/g, '<')
+        .replace(/&#x27;/g, "'")
+        .replace(/&nbsp;/g, ' ');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuraly/lumenjs",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Full-stack Lit web component framework with file-based routing, server loaders, SSR, and API routes",
   "type": "module",
   "main": "dist/cli.js",

package/templates/blog/pages/index.ts

@@ -33,8 +33,8 @@ export async function loader() {
 }
 
 export class PageIndex extends LitElement {
-  static properties = { loaderData: { type: Object } };
-  loaderData: any = {};
+  static properties = { posts: { type: Array } };
+  posts: any[] = [];
 
   static styles = css`
     :host { display: block; }
@@ -49,7 +49,7 @@ export class PageIndex extends LitElement {
   `;
 
   render() {
-    const posts = this.loaderData.posts || [];
+    const posts = this.posts || [];
     return html`
       <h1>Blog</h1>
       <p class="subtitle">Thoughts and tutorials</p>

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

@@ -29,8 +29,19 @@ export async function loader({ params }: { params: { slug: string } }) {
 }
 
 export class PagePost extends LitElement {
-  static properties = { loaderData: { type: Object }, slug: { type: String } };
-  loaderData: any = {};
+  static properties = {
+    title: { type: String },
+    date: { type: String },
+    content: { type: String },
+    readingTime: { type: Number },
+    notFound: { type: Boolean },
+    slug: { type: String },
+  };
+  title = '';
+  date = '';
+  content = '';
+  readingTime = 0;
+  notFound = false;
   slug = '';
 
   static styles = css`
@@ -44,7 +55,7 @@ export class PagePost extends LitElement {
   `;
 
   render() {
-    if (this.loaderData.notFound) {
+    if (this.notFound) {
       return html`
         <a class="back" href="/posts">← Back to posts</a>
         <p class="not-found">Post not found.</p>
@@ -52,9 +63,9 @@ export class PagePost extends LitElement {
     }
     return html`
       <a class="back" href="/">← Back to posts</a>
-      <h1>${this.loaderData.title}</h1>
-      <div class="date">${this.loaderData.date} · ${this.loaderData.readingTime} min read</div>
-      <p class="content">${this.loaderData.content}</p>
+      <h1>${this.title}</h1>
+      <div class="date">${this.date} · ${this.readingTime} min read</div>
+      <p class="content">${this.content}</p>
     `;
   }
 }

package/templates/blog/pages/tag/[tag].ts

@@ -11,8 +11,9 @@ export async function loader({ params }: { params: { tag: string } }) {
 }
 
 export class PageTag extends LitElement {
-  static properties = { loaderData: { type: Object } };
-  loaderData: any = {};
+  static properties = { tag: { type: String }, posts: { type: Array } };
+  tag = '';
+  posts: any[] = [];
 
   static styles = css`
     :host { display: block; }
@@ -28,12 +29,11 @@ export class PageTag extends LitElement {
   `;
 
   render() {
-    const { tag, posts } = this.loaderData;
     return html`
       <a class="back" href="/">← All posts</a>
-      <h1>Tagged: ${tag}</h1>
-      <p class="subtitle">${posts?.length || 0} post${posts?.length !== 1 ? 's' : ''}</p>
-      ${(posts || []).map((p: any) => html`
+      <h1>Tagged: ${this.tag}</h1>
+      <p class="subtitle">${this.posts?.length || 0} post${this.posts?.length !== 1 ? 's' : ''}</p>
+      ${(this.posts || []).map((p: any) => html`
         <div class="post">
           <a href="/posts/${p.slug}">${p.title}</a>
           <div class="meta">${p.date}</div>

package/templates/dashboard/pages/index.ts

@@ -31,11 +31,11 @@ export function subscribe({ push }: { push: (data: any) => void }) {
 
 export class PageIndex extends LitElement {
   static properties = {
-    loaderData: { type: Object },
-    liveData: { type: Object },
+    stats: { type: Array },
+    updatedAt: { type: String },
   };
-  loaderData: any = {};
-  liveData: any = null;
+  stats: any[] = [];
+  updatedAt = '';
 
   static styles = css`
     :host { display: block; }
@@ -50,8 +50,8 @@ export class PageIndex extends LitElement {
   `;
 
   render() {
-    const stats = this.liveData?.stats || this.loaderData.stats || [];
-    const isLive = !!this.liveData;
+    const stats = this.stats || [];
+    const isLive = !!this.updatedAt;
     return html`
       <h1>Overview</h1>
       <div class="grid">
@@ -64,7 +64,7 @@ export class PageIndex extends LitElement {
       </div>
       ${isLive ? html`
         <div class="status">
-          <span class="dot"></span>Live — updated ${this.liveData.updatedAt ? new Date(this.liveData.updatedAt).toLocaleTimeString() : ''}
+          <span class="dot"></span>Live — updated ${this.updatedAt ? new Date(this.updatedAt).toLocaleTimeString() : ''}
         </div>
       ` : ''}
     `;

package/templates/default/pages/index.ts

@@ -5,8 +5,8 @@ export async function loader() {
 }
 
 export class PageIndex extends LitElement {
-  static properties = { loaderData: { type: Object } };
-  loaderData: any = {};
+  static properties = { title: { type: String } };
+  title = '';
 
   static styles = css`
     :host { display: block; max-width: 640px; margin: 0 auto; padding: 2rem; font-family: system-ui; }
@@ -17,7 +17,7 @@ export class PageIndex extends LitElement {
 
   render() {
     return html`
-      <h1>${this.loaderData.title}</h1>
+      <h1>${this.title}</h1>
       <p>Edit <code>pages/index.ts</code> to get started.</p>
     `;
   }