@nuraly/lumenjs 0.2.0 → 0.5.0

package/README.md

@@ -7,6 +7,8 @@
 
 # LumenJS
 
+> **Mirror**: This repository is a read-only mirror of the original private repository, automatically synced on push to main.
+
 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, i18n, and a visual editor — all powered by Vite.
 
 ## Getting Started
@@ -68,6 +70,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,15 +81,45 @@ 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>`;
   }
 }
 ```
 
+### Splitting large loaders
+
+For folder routes (`pages/foo/index.ts`), you can move the loader into a co-located `_loader.ts` file. The framework discovers it automatically — no import or wrapper needed in the page file.
+
+```
+pages/
+└── dashboard/
+    ├── index.ts      ← page component only
+    └── _loader.ts    ← auto-discovered loader
+```
+
+```typescript
+// pages/dashboard/_loader.ts
+export async function loader({ user }) {
+  const stats = await db.getStats(user.id);
+  return { stats };
+}
+```
+
+```typescript
+// pages/dashboard/index.ts — no loader here at all
+export class PageDashboard extends LitElement {
+  static properties = { stats: { type: Array } };
+  stats = [];
+  render() { ... }
+}
+```
+
+Both patterns work side by side — the inline loader always takes precedence. Only folder routes (`index.ts`) support `_loader.ts` discovery; flat pages (`about.ts`) keep the loader inline.
+
 ### Loader Context
 
 | Property | Type | Description |
@@ -110,16 +144,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 +224,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,9 +6,20 @@ 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;
+        // Co-located _loader.ts for folder index pages
+        if (path.basename(entry.filePath).replace(/\.(ts|js)$/, '') === 'index') {
+            const dir = path.dirname(entry.filePath);
+            for (const ext of ['.ts', '.js']) {
+                const loaderFile = path.join(dir, `_loader${ext}`);
+                if (fs.existsSync(loaderFile)) {
+                    const entryDir = path.dirname(entry.name);
+                    serverEntries[`pages/${entryDir}/_loader`] = loaderFile;
+                    break;
+                }
+            }
         }
     }
     for (const entry of layoutEntries) {

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/scan.js

@@ -14,8 +14,11 @@ function analyzePageFile(filePath) {
                 return false;
             return true;
         };
+        const hasColocatedLoader = path.basename(filePath).replace(/\.(ts|js)$/, '') === 'index' &&
+            (fs.existsSync(path.join(path.dirname(filePath), '_loader.ts')) ||
+                fs.existsSync(path.join(path.dirname(filePath), '_loader.js')));
         return {
-            hasLoader: hasExportBefore(/export\s+(async\s+)?function\s+loader\s*\(/),
+            hasLoader: hasExportBefore(/export\s+(async\s+)?function\s+loader\s*\(/) || hasColocatedLoader,
             hasSubscribe: hasExportBefore(/export\s+(async\s+)?function\s+subscribe\s*\(/),
             hasSocket: /export\s+(function|const)\s+socket[\s(=]/.test(content),
             hasAuth: hasExportBefore(/export\s+const\s+auth\s*=/),

package/dist/build/serve-loaders.js

@@ -207,14 +207,24 @@ export async function handleLoaderRequest(manifest, serverDir, pagesDir, pathnam
     }
     try {
         const mod = await import(modulePath);
-        if (!mod.loader || typeof mod.loader !== 'function') {
+        let loaderFn = mod.loader && typeof mod.loader === 'function' ? mod.loader : null;
+        // Fallback: co-located _loader.js for folder index pages
+        if (!loaderFn && path.basename(modulePath, '.js') === 'index') {
+            const colocated = path.join(path.dirname(modulePath), '_loader.js');
+            if (fs.existsSync(colocated)) {
+                const loaderMod = await import(colocated);
+                if (loaderMod.loader && typeof loaderMod.loader === 'function')
+                    loaderFn = loaderMod.loader;
+            }
+        }
+        if (!loaderFn) {
             res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
             res.end(JSON.stringify({ __nk_no_loader: true }));
             return;
         }
         const locale = query.__locale;
         delete query.__locale;
-        const result = await mod.loader({ params: matched.params, query, url: pagePath, headers, locale, user: user ?? null });
+        const result = await loaderFn({ params: matched.params, query, url: pagePath, headers, locale, user: user ?? null });
         if (isRedirectResponse(result)) {
             res.writeHead(result.status || 302, { Location: result.location });
             res.end();

package/dist/build/serve-ssr.js

@@ -18,10 +18,19 @@ export async function handlePageRoute(manifest, serverDir, pagesDir, pathname, q
         if (fs.existsSync(modulePath)) {
             try {
                 const mod = await import(modulePath);
-                // Run loader
+                // Run loader (inline or co-located _loader.js)
                 let loaderData = undefined;
-                if (mod.loader && typeof mod.loader === 'function') {
-                    loaderData = await mod.loader({ params: matched.params, query: {}, url: pathname, headers: req.headers, user: req.nkAuth?.user ?? null });
+                let loaderFn = mod.loader && typeof mod.loader === 'function' ? mod.loader : null;
+                if (!loaderFn && path.basename(modulePath, '.js') === 'index') {
+                    const colocated = path.join(path.dirname(modulePath), '_loader.js');
+                    if (fs.existsSync(colocated)) {
+                        const loaderMod = await import(colocated);
+                        if (loaderMod.loader && typeof loaderMod.loader === 'function')
+                            loaderFn = loaderMod.loader;
+                    }
+                }
+                if (loaderFn) {
+                    loaderData = await loaderFn({ params: matched.params, query: {}, url: pathname, headers: req.headers, user: req.nkAuth?.user ?? null });
                     if (isRedirectResponse(loaderData)) {
                         res.writeHead(loaderData.status || 302, { Location: loaderData.location });
                         res.end();

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/communication/server.js

@@ -70,6 +70,7 @@ export function createCommunicationHandler(options = {}) {
                 }
             },
             broadcastAll: ctx.room.broadcastAll,
+            db: options.db,
         };
         // Broadcast online status if this is the user's first socket
         if (isFirstSocket) {

package/dist/communication/signaling.d.ts

@@ -8,6 +8,8 @@ export interface SignalingContext {
     emitToSocket: (socketId: string, data: any) => void;
     /** Broadcast to all sockets in a room */
     broadcastAll: (room: string, data: any) => void;
+    /** Optional database for persisting call logs */
+    db?: any;
 }
 export declare function handleCallInitiate(ctx: SignalingContext, data: {
     conversationId: string;

package/dist/communication/signaling.js

@@ -130,6 +130,47 @@ export function handleCallHangup(ctx, data) {
                 data: { callId: data.callId, state: 'ended', endReason: data.reason },
             });
         }
+        // Persist call log as a message in the conversation
+        if (ctx.db && call.conversationId) {
+            try {
+                const callStatus = data.reason === 'rejected' ? 'declined'
+                    : data.reason === 'missed' ? 'missed'
+                        : 'completed';
+                const attachment = JSON.stringify({
+                    callType: call.type || 'audio',
+                    callStatus,
+                    duration: data.duration || null,
+                });
+                const msgId = `call-${data.callId}`;
+                const isPg = !!ctx.db.isPg;
+                if (isPg) {
+                    ctx.db.run(`INSERT INTO messages (id, conversation_id, sender_id, content, type, attachment, created_at)
+             VALUES ($1, $2, $3, $4, $5, $6, NOW()) ON CONFLICT (id) DO NOTHING`, msgId, call.conversationId, call.callerId, '', 'call', attachment);
+                    ctx.db.run(`UPDATE conversations SET updated_at = NOW() WHERE id = $1`, call.conversationId);
+                }
+                else {
+                    ctx.db.run(`INSERT OR IGNORE INTO messages (id, conversation_id, sender_id, content, type, attachment, created_at)
+             VALUES (?, ?, ?, '', 'call', ?, datetime('now'))`, msgId, call.conversationId, call.callerId, attachment);
+                    ctx.db.run(`UPDATE conversations SET updated_at = datetime('now') WHERE id = ?`, call.conversationId);
+                }
+                // Broadcast call message to all participants
+                const callMsg = {
+                    id: msgId,
+                    conversationId: call.conversationId,
+                    senderId: call.callerId,
+                    content: '',
+                    type: 'call',
+                    attachment: { callType: call.type || 'audio', callStatus, duration: data.duration || null },
+                    createdAt: new Date().toISOString(),
+                };
+                for (const uid of allUsers) {
+                    emitToUser(ctx, uid, { event: 'message:new', data: callMsg });
+                }
+                // Also emit to the caller
+                emitToUser(ctx, ctx.userId, { event: 'message:new', data: callMsg });
+            }
+            catch { }
+        }
         ctx.store.removeCall(data.callId);
     }
 }

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 {
@@ -158,7 +159,21 @@ export function lumenLoadersPlugin(pagesDir) {
                     // Provide minimal DOM shims for SSR so Lit class definitions don't crash
                     installDomShims();
                     const mod = await server.ssrLoadModule(filePath);
-                    if (!mod.loader || typeof mod.loader !== 'function') {
+                    let loaderFn = mod.loader && typeof mod.loader === 'function' ? mod.loader : null;
+                    // Fallback: co-located _loader.ts for folder index pages
+                    if (!loaderFn && path.basename(filePath).replace(/\.(ts|js)$/, '') === 'index') {
+                        for (const ext of ['.ts', '.js']) {
+                            const colocated = path.join(path.dirname(filePath), `_loader${ext}`);
+                            if (fs.existsSync(colocated)) {
+                                const loaderMod = await server.ssrLoadModule(colocated);
+                                if (loaderMod.loader && typeof loaderMod.loader === 'function') {
+                                    loaderFn = loaderMod.loader;
+                                }
+                                break;
+                            }
+                        }
+                    }
+                    if (!loaderFn) {
                         // No loader — return empty data
                         res.statusCode = 200;
                         res.setHeader('Content-Type', 'application/json');
@@ -204,7 +219,7 @@ export function lumenLoadersPlugin(pagesDir) {
                         }
                         catch { }
                     }
-                    const result = await mod.loader({ params, query, url: pagePath, headers: req.headers, locale, user });
+                    const result = await loaderFn({ params, query, url: pagePath, headers: req.headers, locale, user });
                     if (isRedirectResponse(result)) {
                         res.statusCode = result.status || 302;
                         res.setHeader('Location', result.location);

package/dist/dev-server/ssr-render.js

@@ -44,10 +44,22 @@ export async function ssrRenderPage(server, pagesDir, pathname, headers, locale,
         const mod = await server.ssrLoadModule(pageModuleUrl);
         if (registry)
             registry.__nk_bypass_get = false;
-        // Run loader if present
+        // Run loader if present (inline or co-located _loader.ts)
         let loaderData = undefined;
-        if (mod.loader && typeof mod.loader === 'function') {
-            loaderData = await mod.loader({ params, query: {}, url: pathname, headers: headers || {}, locale, user: user ?? null });
+        let loaderFn = mod.loader && typeof mod.loader === 'function' ? mod.loader : null;
+        if (!loaderFn && path.basename(filePath).replace(/\.(ts|js)$/, '') === 'index') {
+            for (const ext of ['.ts', '.js']) {
+                const colocated = path.join(path.dirname(filePath), `_loader${ext}`);
+                if (fs.existsSync(colocated)) {
+                    const loaderMod = await server.ssrLoadModule('/' + path.relative(path.resolve(pagesDir, '..'), colocated).replace(/\\/g, '/'));
+                    if (loaderMod.loader && typeof loaderMod.loader === 'function')
+                        loaderFn = loaderMod.loader;
+                    break;
+                }
+            }
+        }
+        if (loaderFn) {
+            loaderData = await loaderFn({ params, query: {}, url: pathname, headers: headers || {}, locale, user: user ?? null });
             if (loaderData && typeof loaderData === 'object' && loaderData.__nk_redirect) {
                 return { html: '', loaderData: null, redirect: { location: loaderData.location, status: loaderData.status || 302 } };
             }

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.