@nuraly/lumenjs 0.1.2 → 0.1.4

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

@@ -15,7 +15,6 @@ import { installDomShims } from '../../shared/dom-shims.js';
  *     return { item: data, timestamp: Date.now() };
  *   }
  *
- *   @customElement('page-item')
  *   export class PageItem extends LitElement {
  *     @property({ type: Object }) loaderData = {};
  *     render() {
@@ -31,6 +30,83 @@ export function lumenLoadersPlugin(pagesDir) {
     return {
         name: 'lumenjs-loaders',
         configureServer(server) {
+            // SSE subscribe middleware
+            server.middlewares.use(async (req, res, next) => {
+                if (!req.url?.startsWith('/__nk_subscribe/')) {
+                    return next();
+                }
+                const [pathname, queryString] = req.url.split('?');
+                // Parse query params
+                const query = {};
+                if (queryString) {
+                    for (const pair of queryString.split('&')) {
+                        const [key, val] = pair.split('=');
+                        query[decodeURIComponent(key)] = decodeURIComponent(val || '');
+                    }
+                }
+                // Handle layout subscribe: /__nk_subscribe/__layout/?__dir=<dir>
+                if (pathname === '/__nk_subscribe/__layout/' || pathname === '/__nk_subscribe/__layout') {
+                    const dir = query.__dir || '';
+                    await handleLayoutSubscribe(server, pagesDir, dir, query, req, res);
+                    return;
+                }
+                const pagePath = pathname.replace('/__nk_subscribe', '') || '/';
+                // Parse URL params
+                let params = {};
+                if (query.__params) {
+                    try {
+                        params = JSON.parse(query.__params);
+                    }
+                    catch { /* ignore */ }
+                    delete query.__params;
+                }
+                const filePath = resolvePageFile(pagesDir, pagePath);
+                if (filePath && !filePath.startsWith(path.resolve(pagesDir) + path.sep)) {
+                    res.statusCode = 400;
+                    res.end();
+                    return;
+                }
+                if (!filePath) {
+                    res.statusCode = 404;
+                    res.end();
+                    return;
+                }
+                if (Object.keys(params).length === 0) {
+                    Object.assign(params, extractRouteParams(pagesDir, pagePath, filePath));
+                }
+                try {
+                    installDomShims();
+                    const mod = await server.ssrLoadModule(filePath);
+                    if (!mod.subscribe || typeof mod.subscribe !== 'function') {
+                        res.statusCode = 204;
+                        res.end();
+                        return;
+                    }
+                    // Set SSE headers
+                    res.writeHead(200, {
+                        'Content-Type': 'text/event-stream',
+                        'Cache-Control': 'no-cache',
+                        'Connection': 'keep-alive',
+                    });
+                    const locale = query.__locale;
+                    const push = (data) => {
+                        res.write(`data: ${JSON.stringify(data)}\n\n`);
+                    };
+                    const cleanup = mod.subscribe({ params, push, headers: req.headers, locale, user: req.nkAuth?.user ?? null });
+                    res.on('close', () => {
+                        if (typeof cleanup === 'function')
+                            cleanup();
+                    });
+                }
+                catch (err) {
+                    console.error(`[LumenJS] Subscribe error for ${pagePath}:`, err);
+                    if (!res.headersSent) {
+                        res.statusCode = 500;
+                        res.end();
+                    }
+                }
+            });
+            // Loader middleware
             server.middlewares.use(async (req, res, next) => {
                 if (!req.url?.startsWith('/__nk_loader/')) {
                     return next();
@@ -60,8 +136,14 @@ export function lumenLoadersPlugin(pagesDir) {
                     catch { /* ignore */ }
                     delete query.__params;
                 }
-                // Find the page file
+                // Find the page file (validate path stays within pagesDir)
                 const filePath = resolvePageFile(pagesDir, pagePath);
+                if (filePath && !filePath.startsWith(path.resolve(pagesDir) + path.sep)) {
+                    res.statusCode = 400;
+                    res.setHeader('Content-Type', 'application/json');
+                    res.end(JSON.stringify({ error: 'Invalid page path' }));
+                    return;
+                }
                 if (!filePath) {
                     res.statusCode = 404;
                     res.setHeader('Content-Type', 'application/json');
@@ -86,7 +168,43 @@ export function lumenLoadersPlugin(pagesDir) {
                     // Extract locale from query if provided by the client router
                     const locale = query.__locale;
                     delete query.__locale;
-                    const result = await mod.loader({ params, query, url: pagePath, headers: req.headers, locale });
+                    // If auth middleware hasn't populated nkAuth, try to parse from cookie or bearer token
+                    let user = req.nkAuth?.user ?? null;
+                    if (!user) {
+                        try {
+                            const authConfigPath = path.join(pagesDir, '..', 'lumenjs.auth.ts');
+                            if (fs.existsSync(authConfigPath)) {
+                                const { loadAuthConfig } = await import('../../auth/config.js');
+                                const authCfg = await loadAuthConfig(path.join(pagesDir, '..'), server.ssrLoadModule.bind(server));
+                                if (authCfg) {
+                                    // Try bearer token first
+                                    const authHeader = req.headers.authorization;
+                                    if (authHeader?.startsWith('Bearer ')) {
+                                        const { verifyAccessToken } = await import('../../auth/token.js');
+                                        const tokenUser = verifyAccessToken(authHeader.slice(7), authCfg.session.secret);
+                                        if (tokenUser) {
+                                            user = tokenUser;
+                                            req.nkAuth = { user: tokenUser, session: { accessToken: authHeader.slice(7), expiresAt: 0, user: tokenUser } };
+                                        }
+                                    }
+                                    // Fall back to cookie
+                                    if (!user && req.headers.cookie) {
+                                        const { parseSessionCookie, decryptSession } = await import('../../auth/session.js');
+                                        const cookieVal = parseSessionCookie(req.headers.cookie, authCfg.session.cookieName);
+                                        if (cookieVal) {
+                                            const session = await decryptSession(cookieVal, authCfg.session.secret);
+                                            if (session?.user) {
+                                                user = session.user;
+                                                req.nkAuth = { user: session.user, session };
+                                            }
+                                        }
+                                    }
+                                }
+                            }
+                        }
+                        catch { }
+                    }
+                    const result = await mod.loader({ params, query, url: pagePath, headers: req.headers, locale, user });
                     if (isRedirectResponse(result)) {
                         res.statusCode = result.status || 302;
                         res.setHeader('Location', result.location);
@@ -126,45 +244,26 @@ export function lumenLoadersPlugin(pagesDir) {
             // Apply to page files and layout files within the pages directory
             if (!id.startsWith(pagesDir) || !id.endsWith('.ts'))
                 return;
-            if (!code.includes('export') || !code.includes('loader'))
-                return;
-            const hasLoader = /export\s+(async\s+)?function\s+loader\s*\(/.test(code);
-            if (!hasLoader)
+            const hasLoader = hasTopLevelServerFunction(code, 'loader');
+            const hasSubscribe = hasTopLevelServerFunction(code, 'subscribe');
+            if (!hasLoader && !hasSubscribe)
                 return;
-            // Find the loader function by tracking brace depth
-            const match = code.match(/export\s+(async\s+)?function\s+loader\s*\(/);
-            if (!match)
-                return;
-            const startIdx = match.index;
-            // Skip past the function signature's closing parenthesis (handles nested braces in type annotations)
-            let parenDepth = 1;
-            let sigIdx = startIdx + match[0].length;
-            while (sigIdx < code.length && parenDepth > 0) {
-                if (code[sigIdx] === '(')
-                    parenDepth++;
-                else if (code[sigIdx] === ')')
-                    parenDepth--;
-                sigIdx++;
+            let result = code;
+            // Strip loader function
+            if (hasLoader) {
+                result = stripServerFunction(result, 'loader');
             }
-            // Find the opening brace of the function body (after the closing paren and optional return type)
-            let braceStart = code.indexOf('{', sigIdx);
-            if (braceStart === -1)
-                return;
-            let depth = 1;
-            let i = braceStart + 1;
-            while (i < code.length && depth > 0) {
-                if (code[i] === '{')
-                    depth++;
-                else if (code[i] === '}')
-                    depth--;
-                i++;
+            // Strip subscribe function
+            if (hasSubscribe) {
+                result = stripServerFunction(result, 'subscribe');
             }
-            // Replace the entire loader function
-            const transformed = code.substring(0, startIdx)
-                + '// loader() — runs server-side only'
-                + code.substring(i);
-            const withFlag = transformed + '\nexport const __nk_has_loader = true;\n';
-            return { code: withFlag, map: null };
+            if (hasLoader) {
+                result += '\nexport const __nk_has_loader = true;\n';
+            }
+            if (hasSubscribe) {
+                result += '\nexport const __nk_has_subscribe = true;\n';
+            }
+            return { code: result, map: null };
         },
     };
 }
@@ -173,8 +272,13 @@ export function lumenLoadersPlugin(pagesDir) {
  * GET /__nk_loader/__layout/?__dir=dashboard
  */
 async function handleLayoutLoader(server, pagesDir, dir, req, res) {
-    // Resolve the layout file from the directory
-    const layoutDir = path.join(pagesDir, dir);
+    // Resolve the layout file from the directory (validate path stays within pagesDir)
+    const layoutDir = path.resolve(pagesDir, dir);
+    if (!layoutDir.startsWith(path.resolve(pagesDir) + path.sep) && layoutDir !== path.resolve(pagesDir)) {
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Invalid layout directory' }));
+        return;
+    }
     let layoutFile = null;
     for (const ext of ['.ts', '.js']) {
         const p = path.join(layoutDir, `_layout${ext}`);
@@ -209,7 +313,37 @@ async function handleLayoutLoader(server, pagesDir, dir, req, res) {
             }
         }
         const locale = query.__locale;
-        const result = await mod.loader({ params: {}, query: {}, url: `/__layout/${dir}`, headers: req.headers, locale });
+        // If auth middleware hasn't populated nkAuth, try to parse from cookie or bearer token
+        let user = req.nkAuth?.user ?? null;
+        if (!user) {
+            try {
+                const authConfigPath = path.join(pagesDir, '..', 'lumenjs.auth.ts');
+                if (fs.existsSync(authConfigPath)) {
+                    const { loadAuthConfig } = await import('../../auth/config.js');
+                    const authCfg = await loadAuthConfig(path.join(pagesDir, '..'), server.ssrLoadModule.bind(server));
+                    if (authCfg) {
+                        const authHeader = req.headers.authorization;
+                        if (authHeader?.startsWith('Bearer ')) {
+                            const { verifyAccessToken } = await import('../../auth/token.js');
+                            const tokenUser = verifyAccessToken(authHeader.slice(7), authCfg.session.secret);
+                            if (tokenUser)
+                                user = tokenUser;
+                        }
+                        if (!user && req.headers.cookie) {
+                            const { parseSessionCookie, decryptSession } = await import('../../auth/session.js');
+                            const cookieVal = parseSessionCookie(req.headers.cookie, authCfg.session.cookieName);
+                            if (cookieVal) {
+                                const session = await decryptSession(cookieVal, authCfg.session.secret);
+                                if (session?.user)
+                                    user = session.user;
+                            }
+                        }
+                    }
+                }
+            }
+            catch { }
+        }
+        const result = await mod.loader({ params: {}, query: {}, url: `/__layout/${dir}`, headers: req.headers, locale, user });
         if (isRedirectResponse(result)) {
             res.statusCode = result.status || 302;
             res.setHeader('Location', result.location);
@@ -310,6 +444,141 @@ function findDynamicPage(baseDir, segments) {
     }
     return null;
 }
+/**
+ * Check if code has a top-level export of a server function (before the class definition).
+ * In LumenJS, loader/subscribe are always declared before `export class`.
+ */
+function hasTopLevelServerFunction(code, fnName) {
+    const classStart = code.search(/export\s+class\s+\w+/);
+    const fnRegex = new RegExp(`export\\s+(async\\s+)?function\\s+${fnName}\\s*\\(`);
+    const match = fnRegex.exec(code);
+    if (!match)
+        return false;
+    // Real server functions appear before the class; code examples appear inside the class
+    if (classStart >= 0 && match.index > classStart)
+        return false;
+    return true;
+}
+/**
+ * Strip a named server-side function (loader/subscribe) from client code using brace-depth tracking.
+ */
+function stripServerFunction(code, fnName) {
+    const classStart = code.search(/export\s+class\s+\w+/);
+    const regex = new RegExp(`export\\s+(async\\s+)?function\\s+${fnName}\\s*\\(`);
+    const match = regex.exec(code);
+    if (!match)
+        return code;
+    // Only strip if the match is before the class (top-level, not inside a code example)
+    if (classStart >= 0 && match.index > classStart)
+        return code;
+    const startIdx = match.index;
+    let parenDepth = 1;
+    let sigIdx = startIdx + match[0].length;
+    while (sigIdx < code.length && parenDepth > 0) {
+        if (code[sigIdx] === '(')
+            parenDepth++;
+        else if (code[sigIdx] === ')')
+            parenDepth--;
+        sigIdx++;
+    }
+    let braceStart = code.indexOf('{', sigIdx);
+    if (braceStart === -1)
+        return code;
+    let depth = 1;
+    let i = braceStart + 1;
+    while (i < code.length && depth > 0) {
+        const ch = code[i];
+        // Skip string literals and template literals to avoid counting braces inside them
+        if (ch === "'" || ch === '"' || ch === '`') {
+            const quote = ch;
+            i++;
+            while (i < code.length && code[i] !== quote) {
+                if (code[i] === '\\')
+                    i++; // skip escaped char
+                i++;
+            }
+            i++; // skip closing quote
+            continue;
+        }
+        // Skip single-line comments
+        if (ch === '/' && code[i + 1] === '/') {
+            while (i < code.length && code[i] !== '\n')
+                i++;
+            continue;
+        }
+        // Skip multi-line comments
+        if (ch === '/' && code[i + 1] === '*') {
+            i += 2;
+            while (i < code.length - 1 && !(code[i] === '*' && code[i + 1] === '/'))
+                i++;
+            i += 2;
+            continue;
+        }
+        if (ch === '{')
+            depth++;
+        else if (ch === '}')
+            depth--;
+        i++;
+    }
+    return code.substring(0, startIdx)
+        + `// ${fnName}() — runs server-side only`
+        + code.substring(i);
+}
+/**
+ * Handle layout subscribe requests in dev mode.
+ * GET /__nk_subscribe/__layout/?__dir=<dir>
+ */
+async function handleLayoutSubscribe(server, pagesDir, dir, query, req, res) {
+    const layoutDir = path.resolve(pagesDir, dir);
+    if (!layoutDir.startsWith(path.resolve(pagesDir) + path.sep) && layoutDir !== path.resolve(pagesDir)) {
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Invalid layout directory' }));
+        return;
+    }
+    let layoutFile = null;
+    for (const ext of ['.ts', '.js']) {
+        const p = path.join(layoutDir, `_layout${ext}`);
+        if (fs.existsSync(p)) {
+            layoutFile = p;
+            break;
+        }
+    }
+    if (!layoutFile) {
+        res.statusCode = 204;
+        res.end();
+        return;
+    }
+    try {
+        installDomShims();
+        const mod = await server.ssrLoadModule(layoutFile);
+        if (!mod.subscribe || typeof mod.subscribe !== 'function') {
+            res.statusCode = 204;
+            res.end();
+            return;
+        }
+        res.writeHead(200, {
+            'Content-Type': 'text/event-stream',
+            'Cache-Control': 'no-cache',
+            'Connection': 'keep-alive',
+        });
+        const locale = query.__locale;
+        const push = (data) => {
+            res.write(`data: ${JSON.stringify(data)}\n\n`);
+        };
+        const cleanup = mod.subscribe({ params: {}, push, headers: req.headers, locale, user: req.nkAuth?.user ?? null });
+        res.on('close', () => {
+            if (typeof cleanup === 'function')
+                cleanup();
+        });
+    }
+    catch (err) {
+        console.error(`[LumenJS] Layout subscribe error for dir=${dir}:`, err);
+        if (!res.headersSent) {
+            res.statusCode = 500;
+            res.end();
+        }
+    }
+}
 /**
  * Extract dynamic route params by comparing URL segments against [param] file path segments.
  */

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

@@ -1,6 +1,6 @@
 import fs from 'fs';
 import path from 'path';
-import { dirToLayoutTagName, fileHasLoader, filePathToRoute, filePathToTagName } from '../../shared/utils.js';
+import { dirToLayoutTagName, fileHasLoader, fileHasSubscribe, fileHasAuth, fileHasMeta, fileHasStandalone, filePathToRoute, filePathToTagName } from '../../shared/utils.js';
 const VIRTUAL_MODULE_ID = 'virtual:lumenjs-routes';
 const RESOLVED_VIRTUAL_MODULE_ID = '\0' + VIRTUAL_MODULE_ID;
 /**
@@ -28,7 +28,7 @@ export function lumenRoutesPlugin(pagesDir) {
                 const tagName = dirToLayoutTagName(relativePath);
                 layouts.push({ dir: relativePath.replace(/\\/g, '/'), filePath, tagName });
             }
-            if (entry.isDirectory()) {
+            if (entry.isDirectory() && !entry.name.startsWith('_')) {
                 walkForLayouts(baseDir, path.join(relativePath, entry.name), layouts);
             }
         }
@@ -55,12 +55,18 @@ export function lumenRoutesPlugin(pagesDir) {
     function walkDir(baseDir, relativePath, routes) {
         const fullDir = path.join(baseDir, relativePath);
         const entries = fs.readdirSync(fullDir, { withFileTypes: true });
+        // Check if this subdirectory contains an index file (folder route)
+        // Only applies to subdirectories, not the root pages directory
+        const hasIndex = relativePath !== '' && entries.some(e => e.isFile() && /^index\.(ts|js)$/.test(e.name));
         for (const entry of entries) {
             const entryRelative = path.join(relativePath, entry.name);
-            if (entry.isDirectory()) {
+            if (entry.isDirectory() && !entry.name.startsWith('_')) {
                 walkDir(baseDir, entryRelative, routes);
             }
             else if (entry.isFile() && /\.(ts|js)$/.test(entry.name) && !entry.name.startsWith('_')) {
+                // In a folder route (has index file), only register the index file and dynamic param files
+                if (hasIndex && !/^index\.(ts|js)$/.test(entry.name) && !entry.name.startsWith('['))
+                    continue;
                 const routePath = filePathToRoute(entryRelative);
                 const componentPath = path.join(pagesDir, entryRelative);
                 const tagName = filePathToTagName(entryRelative);
@@ -98,18 +104,24 @@ export function lumenRoutesPlugin(pagesDir) {
                 const routeArray = routes
                     .map(r => {
                     const hasLoader = fileHasLoader(r.componentPath);
+                    const hasSubscribe = fileHasSubscribe(r.componentPath);
+                    const hasAuth = fileHasAuth(r.componentPath);
+                    const hasMeta = fileHasMeta(r.componentPath);
+                    const isStandalone = fileHasStandalone(r.componentPath);
                     const componentPath = r.componentPath.replace(/\\/g, '/');
-                    const chain = getLayoutChain(r.componentPath, layouts);
+                    // Standalone pages skip all layouts
+                    const chain = isStandalone ? [] : getLayoutChain(r.componentPath, layouts);
                     let layoutsStr = '';
                     if (chain.length > 0) {
                         const items = chain.map(l => {
                             const lHasLoader = fileHasLoader(l.filePath);
+                            const lHasSubscribe = fileHasSubscribe(l.filePath);
                             const lPath = l.filePath.replace(/\\/g, '/');
-                            return `{ tagName: ${JSON.stringify(l.tagName)}, loaderPath: ${JSON.stringify(l.dir)}${lHasLoader ? ', hasLoader: true' : ''}, load: () => import('${lPath}') }`;
+                            return `{ tagName: ${JSON.stringify(l.tagName)}, loaderPath: ${JSON.stringify(l.dir)}${lHasLoader ? ', hasLoader: true' : ''}${lHasSubscribe ? ', hasSubscribe: true' : ''}, load: () => import('${lPath}') }`;
                         });
                         layoutsStr = `, layouts: [${items.join(', ')}]`;
                     }
-                    return `  { path: ${JSON.stringify(r.path)}, tagName: ${JSON.stringify(r.tagName)}${hasLoader ? ', hasLoader: true' : ''}, load: () => import('${componentPath}')${layoutsStr} }`;
+                    return `  { path: ${JSON.stringify(r.path)}, tagName: ${JSON.stringify(r.tagName)}${hasLoader ? ', hasLoader: true' : ''}${hasSubscribe ? ', hasSubscribe: true' : ''}${hasMeta ? ', hasMeta: true' : ''}${hasAuth ? ', __nk_has_auth: true' : ''}, load: () => import('${componentPath}')${layoutsStr} }`;
                 })
                     .join(',\n');
                 return `export const routes = [\n${routeArray}\n];\n`;

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

@@ -0,0 +1,2 @@
+import { Plugin } from 'vite';
+export declare function lumenSocketIOPlugin(pagesDir: string): Plugin;

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

@@ -0,0 +1,51 @@
+import fs from 'fs';
+import path from 'path';
+import { fileHasSocket, filePathToRoute } from '../../shared/utils.js';
+export function lumenSocketIOPlugin(pagesDir) {
+    return {
+        name: 'lumenjs-socketio',
+        configureServer(server) {
+            if (!server.httpServer)
+                return;
+            import('../../shared/socket-io-setup.js').then(({ setupSocketIO }) => {
+                const routes = scanSocketRoutes(pagesDir);
+                setupSocketIO({
+                    httpServer: server.httpServer,
+                    loadModule: (fp) => server.ssrLoadModule(fp),
+                    routes,
+                    projectDir: path.dirname(pagesDir),
+                }).catch((err) => {
+                    console.warn('[LumenJS] Socket.IO setup failed:', err.message);
+                    console.warn('[LumenJS] Make sure socket.io is installed: lumenjs add socketio');
+                });
+            }).catch((err) => {
+                console.warn('[LumenJS] Socket.IO plugin load failed:', err.message);
+            });
+        },
+    };
+}
+function scanSocketRoutes(pagesDir) {
+    const routes = [];
+    if (!fs.existsSync(pagesDir))
+        return routes;
+    walkDir(pagesDir, '', routes, pagesDir);
+    return routes;
+}
+function walkDir(baseDir, relativePath, routes, pagesDir) {
+    const fullDir = path.join(baseDir, relativePath);
+    const entries = fs.readdirSync(fullDir, { withFileTypes: true });
+    for (const entry of entries) {
+        const entryRelative = path.join(relativePath, entry.name);
+        if (entry.isDirectory()) {
+            walkDir(baseDir, entryRelative, routes, pagesDir);
+        }
+        else if (entry.isFile() && /\.(ts|js)$/.test(entry.name) && !entry.name.startsWith('_')) {
+            const filePath = path.join(pagesDir, entryRelative);
+            const hasSocket = fileHasSocket(filePath);
+            if (hasSocket) {
+                const routePath = filePathToRoute(entryRelative);
+                routes.push({ path: routePath, hasSocket: true, filePath });
+            }
+        }
+    }
+}

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

@@ -1,5 +1,7 @@
 import { Plugin } from 'vite';
 /**
  * In editor mode, inject data-nk-source attributes into html`` template literals.
+ * Reads the original source file from disk to compute correct line numbers,
+ * since Vite's transform hook receives esbuild-compiled code with shifted lines.
  */
 export declare function sourceAnnotatorPlugin(projectDir: string): Plugin;

package/dist/dev-server/plugins/vite-plugin-source-annotator.js

@@ -1,21 +1,44 @@
 import path from 'path';
+import fs from 'fs';
 /**
  * In editor mode, inject data-nk-source attributes into html`` template literals.
+ * Reads the original source file from disk to compute correct line numbers,
+ * since Vite's transform hook receives esbuild-compiled code with shifted lines.
  */
 export function sourceAnnotatorPlugin(projectDir) {
     return {
         name: 'lumenjs-source-annotator',
+        enforce: 'pre',
         transform(code, id) {
             if (!id.startsWith(projectDir) || !id.endsWith('.ts'))
                 return;
             if (!code.includes('html`'))
                 return;
+            // Read the original source to get correct line numbers
+            let originalSource;
+            try {
+                originalSource = fs.readFileSync(id, 'utf-8');
+            }
+            catch {
+                originalSource = code;
+            }
             const relativePath = path.relative(projectDir, id);
+            // Build ordered list of html` base lines from original source
+            const originalBaseLines = [];
+            const origRegex = /html`/g;
+            let origMatch;
+            while ((origMatch = origRegex.exec(originalSource)) !== null) {
+                const before = originalSource.substring(0, origMatch.index + 5); // include 'html`'
+                originalBaseLines.push(before.split('\n').length);
+            }
+            let templateIndex = 0;
             const transformed = code.replace(/html`([\s\S]*?)`/g, (match, templateContent) => {
                 let offset = 0;
-                const beforeTemplate = code.substring(0, code.indexOf(match));
-                const baseLine = beforeTemplate.split('\n').length;
-                const annotated = templateContent.replace(/<([a-z][a-z0-9]*-[a-z0-9-]*)([\s>])/gi, (tagMatch, tagName, after) => {
+                // Use original source line for this Nth html` template
+                const baseLine = originalBaseLines[templateIndex] ?? code.substring(0, code.indexOf(match)).split('\n').length;
+                templateIndex++;
+                // Annotate both custom elements (tags with hyphens) and standard HTML elements
+                const annotated = templateContent.replace(/<((?:[a-z][a-z0-9]*-[a-z0-9-]*)|(?:div|section|article|aside|main|nav|header|footer|h[1-6]|p|span|a|ul|ol|li|button|form|input|textarea|select|label|img|table|tr|td|th|thead|tbody))([\s>])/gi, (tagMatch, tagName, after) => {
                     const beforeTag = templateContent.substring(0, templateContent.indexOf(tagMatch, offset));
                     const lineInTemplate = beforeTag.split('\n').length - 1;
                     offset = templateContent.indexOf(tagMatch, offset) + tagMatch.length;

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

@@ -0,0 +1,10 @@
+import type { Plugin } from 'vite';
+/**
+ * LumenJS storage plugin (dev mode).
+ *
+ * - Creates a LocalStorageAdapter pointing to `{projectDir}/uploads`
+ * - Registers it as the global storage singleton (`useStorage()`)
+ * - Serves uploaded files at `/uploads/*`
+ * - Handles presigned PUT requests at `/__nk_storage/upload/:token`
+ */
+export declare function lumenStoragePlugin(projectDir: string): Plugin;