@nuraly/lumenjs 0.1.0

package/dist/dev-server/plugins/vite-plugin-lit-hmr.js

@@ -0,0 +1,46 @@
+/**
+ * Lit HMR plugin — patches existing custom element prototypes instead of re-registering.
+ */
+export function litHmrPlugin(projectDir) {
+    return {
+        name: 'lumenjs-lit-hmr',
+        enforce: 'post',
+        transform(code, id) {
+            if (!id.startsWith(projectDir) || !id.endsWith('.ts'))
+                return;
+            const match = code.match(/(\w+)\s*=\s*__decorateClass\(\s*\[\s*\n?\s*customElement\(\s*"([^"]+)"\s*\)\s*\n?\s*\]\s*,\s*\1\s*\)/);
+            if (!match)
+                return;
+            const [fullMatch, className, tagName] = match;
+            const transformed = code.replace(fullMatch, `if (!customElements.get("${tagName}")) {\n  customElements.define("${tagName}", ${className});\n}`) + `
+// --- Lit HMR ---
+if (import.meta.hot) {
+  import.meta.hot.accept((newModule) => {
+    if (!newModule) return;
+    const NewClass = newModule.${className};
+    if (!NewClass) return;
+    const OldClass = customElements.get("${tagName}");
+    if (!OldClass) return;
+    const descriptors = Object.getOwnPropertyDescriptors(NewClass.prototype);
+    for (const [key, desc] of Object.entries(descriptors)) {
+      if (key === "constructor") continue;
+      Object.defineProperty(OldClass.prototype, key, desc);
+    }
+    if (NewClass.styles) {
+      OldClass.styles = NewClass.styles;
+      OldClass.elementStyles = undefined;
+      OldClass.finalizeStyles();
+    }
+    if (NewClass.properties) {
+      OldClass.properties = NewClass.properties;
+    }
+    document.querySelectorAll("${tagName}").forEach((el) => {
+      if (el.requestUpdate) el.requestUpdate();
+    });
+  });
+}
+`;
+            return { code: transformed, map: null };
+        }
+    };
+}

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

@@ -0,0 +1,38 @@
+import { Plugin } from 'vite';
+/**
+ * LumenJS Server Loaders plugin.
+ *
+ * Pages can export a `loader()` function that runs on the server.
+ * The router fetches the data before rendering the page.
+ *
+ * Usage in a page file:
+ *
+ *   export async function loader({ params, url }) {
+ *     const data = await fetchFromDB(params.id);
+ *     return { item: data, timestamp: Date.now() };
+ *   }
+ *
+ *   @customElement('page-item')
+ *   export class PageItem extends LitElement {
+ *     @property({ type: Object }) loaderData = {};
+ *     render() {
+ *       return html`<h1>${this.loaderData.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.
+ */
+export declare function lumenLoadersPlugin(pagesDir: string): Plugin;
+/**
+ * Map a URL path to a page file.
+ * /         → pages/index.ts
+ * /about    → pages/about.ts
+ * /blog/foo → pages/blog/[slug].ts or pages/blog/foo.ts
+ */
+export declare function resolvePageFile(pagesDir: string, urlPath: string): string | null;
+/**
+ * Extract dynamic route params by comparing URL segments against [param] file path segments.
+ */
+export declare function extractRouteParams(pagesDir: string, urlPath: string, filePath: string): Record<string, string>;

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

@@ -0,0 +1,320 @@
+import path from 'path';
+import fs from 'fs';
+import { isRedirectResponse } from '../../shared/utils.js';
+import { installDomShims } from '../../shared/dom-shims.js';
+/**
+ * LumenJS Server Loaders plugin.
+ *
+ * Pages can export a `loader()` function that runs on the server.
+ * The router fetches the data before rendering the page.
+ *
+ * Usage in a page file:
+ *
+ *   export async function loader({ params, url }) {
+ *     const data = await fetchFromDB(params.id);
+ *     return { item: data, timestamp: Date.now() };
+ *   }
+ *
+ *   @customElement('page-item')
+ *   export class PageItem extends LitElement {
+ *     @property({ type: Object }) loaderData = {};
+ *     render() {
+ *       return html`<h1>${this.loaderData.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.
+ */
+export function lumenLoadersPlugin(pagesDir) {
+    return {
+        name: 'lumenjs-loaders',
+        configureServer(server) {
+            server.middlewares.use(async (req, res, next) => {
+                if (!req.url?.startsWith('/__nk_loader/')) {
+                    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 loader requests: /__nk_loader/__layout/?__dir=<dir>
+                if (pathname === '/__nk_loader/__layout/' || pathname === '/__nk_loader/__layout') {
+                    const dir = query.__dir || '';
+                    await handleLayoutLoader(server, pagesDir, dir, req, res);
+                    return;
+                }
+                const pagePath = pathname.replace('/__nk_loader', '') || '/';
+                // Parse URL params passed as __params query
+                let params = {};
+                if (query.__params) {
+                    try {
+                        params = JSON.parse(query.__params);
+                    }
+                    catch { /* ignore */ }
+                    delete query.__params;
+                }
+                // Find the page file
+                const filePath = resolvePageFile(pagesDir, pagePath);
+                if (!filePath) {
+                    res.statusCode = 404;
+                    res.setHeader('Content-Type', 'application/json');
+                    res.end(JSON.stringify({ error: 'Page not found' }));
+                    return;
+                }
+                // Extract params from URL if not provided via __params query
+                if (Object.keys(params).length === 0) {
+                    Object.assign(params, extractRouteParams(pagesDir, pagePath, filePath));
+                }
+                try {
+                    // 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') {
+                        // No loader — return empty data
+                        res.statusCode = 200;
+                        res.setHeader('Content-Type', 'application/json');
+                        res.end(JSON.stringify({ __nk_no_loader: true }));
+                        return;
+                    }
+                    const result = await mod.loader({ params, query, url: pagePath, headers: req.headers });
+                    if (isRedirectResponse(result)) {
+                        res.statusCode = result.status || 302;
+                        res.setHeader('Location', result.location);
+                        res.end();
+                        return;
+                    }
+                    res.statusCode = 200;
+                    res.setHeader('Content-Type', 'application/json');
+                    res.end(JSON.stringify(result ?? null));
+                }
+                catch (err) {
+                    if (isRedirectResponse(err)) {
+                        res.statusCode = err.status || 302;
+                        res.setHeader('Location', err.location);
+                        res.end();
+                        return;
+                    }
+                    console.error(`[LumenJS] Loader error for ${pagePath}:`, err);
+                    const status = err?.status || 500;
+                    const message = err?.message || 'Loader failed';
+                    res.statusCode = status;
+                    res.setHeader('Content-Type', 'application/json');
+                    res.end(JSON.stringify({ error: message }));
+                }
+            });
+        },
+        /**
+         * Strip the loader() export from client bundles.
+         * Runs before esbuild (enforce: 'pre') so we operate on raw TypeScript source.
+         * Skip for SSR so ssrLoadModule can access the loader.
+         * Applies to both page files and _layout files.
+         */
+        enforce: 'pre',
+        transform(code, id, options) {
+            if (options?.ssr)
+                return;
+            // Apply to page files and layout files within the pages directory
+            if (!id.startsWith(pagesDir) || !id.endsWith('.ts'))
+                return;
+            if (!code.includes('export') || !code.includes('loader'))
+                return;
+            const hasLoader = /export\s+(async\s+)?function\s+loader\s*\(/.test(code);
+            if (!hasLoader)
+                return;
+            // Find the loader function by tracking brace depth
+            const match = code.match(/export\s+(async\s+)?function\s+loader\s*\(/);
+            if (!match)
+                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++;
+            }
+            // 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++;
+            }
+            // 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 };
+        },
+    };
+}
+/**
+ * Handle layout loader requests.
+ * 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);
+    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 = 200;
+        res.setHeader('Content-Type', 'application/json');
+        res.end(JSON.stringify({ __nk_no_loader: true }));
+        return;
+    }
+    try {
+        installDomShims();
+        const mod = await server.ssrLoadModule(layoutFile);
+        if (!mod.loader || typeof mod.loader !== 'function') {
+            res.statusCode = 200;
+            res.setHeader('Content-Type', 'application/json');
+            res.end(JSON.stringify({ __nk_no_loader: true }));
+            return;
+        }
+        const result = await mod.loader({ params: {}, query: {}, url: `/__layout/${dir}`, headers: req.headers });
+        if (isRedirectResponse(result)) {
+            res.statusCode = result.status || 302;
+            res.setHeader('Location', result.location);
+            res.end();
+            return;
+        }
+        res.statusCode = 200;
+        res.setHeader('Content-Type', 'application/json');
+        res.end(JSON.stringify(result ?? null));
+    }
+    catch (err) {
+        if (isRedirectResponse(err)) {
+            res.statusCode = err.status || 302;
+            res.setHeader('Location', err.location);
+            res.end();
+            return;
+        }
+        console.error(`[LumenJS] Layout loader error for dir=${dir}:`, err);
+        const status = err?.status || 500;
+        const message = err?.message || 'Layout loader failed';
+        res.statusCode = status;
+        res.setHeader('Content-Type', 'application/json');
+        res.end(JSON.stringify({ error: message }));
+    }
+}
+/**
+ * Map a URL path to a page file.
+ * /         → pages/index.ts
+ * /about    → pages/about.ts
+ * /blog/foo → pages/blog/[slug].ts or pages/blog/foo.ts
+ */
+export function resolvePageFile(pagesDir, urlPath) {
+    const relative = urlPath.replace(/^\//, '') || 'index';
+    const segments = relative.split('/');
+    // Try exact match
+    const exactPath = path.join(pagesDir, ...segments);
+    for (const ext of ['.ts', '.js']) {
+        if (fs.existsSync(exactPath + ext)) {
+            return exactPath + ext;
+        }
+    }
+    // Try index
+    const indexPath = path.join(pagesDir, ...segments, 'index');
+    for (const ext of ['.ts', '.js']) {
+        if (fs.existsSync(indexPath + ext)) {
+            return indexPath + ext;
+        }
+    }
+    // Try dynamic segments
+    return findDynamicPage(pagesDir, segments);
+}
+function findDynamicPage(baseDir, segments) {
+    if (segments.length === 0)
+        return null;
+    if (!fs.existsSync(baseDir))
+        return null;
+    const [current, ...rest] = segments;
+    const entries = fs.readdirSync(baseDir, { withFileTypes: true });
+    if (rest.length === 0) {
+        // Try exact or single-segment dynamic match first
+        for (const entry of entries) {
+            if (!entry.isFile())
+                continue;
+            const name = entry.name.replace(/\.(ts|js)$/, '');
+            if (name === current || (/^\[[^\.]/.test(name) && /^\[.+\]$/.test(name))) {
+                return path.join(baseDir, entry.name);
+            }
+        }
+        // Try catch-all [...name] file
+        for (const entry of entries) {
+            if (!entry.isFile())
+                continue;
+            const name = entry.name.replace(/\.(ts|js)$/, '');
+            if (/^\[\.\.\./.test(name)) {
+                return path.join(baseDir, entry.name);
+            }
+        }
+        return null;
+    }
+    // Try exact or single-segment dynamic directory match first
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        if (entry.name === current || (/^\[[^\.]/.test(entry.name) && /^\[.+\]$/.test(entry.name))) {
+            const result = findDynamicPage(path.join(baseDir, entry.name), rest);
+            if (result)
+                return result;
+        }
+    }
+    // Try catch-all [...name] file (consumes all remaining segments)
+    for (const entry of entries) {
+        if (!entry.isFile())
+            continue;
+        const name = entry.name.replace(/\.(ts|js)$/, '');
+        if (/^\[\.\.\./.test(name)) {
+            return path.join(baseDir, entry.name);
+        }
+    }
+    return null;
+}
+/**
+ * Extract dynamic route params by comparing URL segments against [param] file path segments.
+ */
+export function extractRouteParams(pagesDir, urlPath, filePath) {
+    const params = {};
+    const urlSegments = (urlPath.replace(/^\//, '') || 'index').split('/');
+    const fileRelative = path.relative(pagesDir, filePath).replace(/\.(ts|js)$/, '');
+    const fileSegments = fileRelative.split(path.sep);
+    for (let i = 0; i < fileSegments.length && i < urlSegments.length; i++) {
+        const catchAllMatch = fileSegments[i].match(/^\[\.\.\.(.+)\]$/);
+        if (catchAllMatch) {
+            // Catch-all: capture all remaining URL segments joined with /
+            params[catchAllMatch[1]] = urlSegments.slice(i).join('/');
+            break;
+        }
+        const match = fileSegments[i].match(/^\[(.+)\]$/);
+        if (match) {
+            params[match[1]] = urlSegments[i];
+        }
+    }
+    return params;
+}

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

@@ -0,0 +1,21 @@
+import { Plugin } from 'vite';
+export interface RouteEntry {
+    path: string;
+    componentPath: string;
+    tagName: string;
+}
+export interface LayoutEntry {
+    /** Relative directory within pages/ ('' for root) */
+    dir: string;
+    filePath: string;
+    tagName: string;
+}
+/**
+ * Scans pages/ directory and generates a virtual route manifest module.
+ * Supports:
+ *   pages/index.ts       → /
+ *   pages/about.ts       → /about
+ *   pages/blog/[slug].ts → /blog/:slug
+ *   pages/_layout.ts     → layout wrapping all pages in directory + subdirectories
+ */
+export declare function lumenRoutesPlugin(pagesDir: string): Plugin;

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

@@ -0,0 +1,157 @@
+import fs from 'fs';
+import path from 'path';
+import { dirToLayoutTagName, fileHasLoader, filePathToRoute } from '../../shared/utils.js';
+const VIRTUAL_MODULE_ID = 'virtual:lumenjs-routes';
+const RESOLVED_VIRTUAL_MODULE_ID = '\0' + VIRTUAL_MODULE_ID;
+/**
+ * Scans pages/ directory and generates a virtual route manifest module.
+ * Supports:
+ *   pages/index.ts       → /
+ *   pages/about.ts       → /about
+ *   pages/blog/[slug].ts → /blog/:slug
+ *   pages/_layout.ts     → layout wrapping all pages in directory + subdirectories
+ */
+export function lumenRoutesPlugin(pagesDir) {
+    function scanLayouts() {
+        if (!fs.existsSync(pagesDir))
+            return [];
+        const layouts = [];
+        walkForLayouts(pagesDir, '', layouts);
+        return layouts;
+    }
+    function walkForLayouts(baseDir, relativePath, layouts) {
+        const fullDir = path.join(baseDir, relativePath);
+        const entries = fs.readdirSync(fullDir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isFile() && /^_layout\.(ts|js)$/.test(entry.name)) {
+                const filePath = path.join(fullDir, entry.name);
+                const tagName = dirToLayoutTagName(relativePath);
+                layouts.push({ dir: relativePath.replace(/\\/g, '/'), filePath, tagName });
+            }
+            if (entry.isDirectory()) {
+                walkForLayouts(baseDir, path.join(relativePath, entry.name), layouts);
+            }
+        }
+    }
+    function scanPages() {
+        if (!fs.existsSync(pagesDir))
+            return [];
+        const routes = [];
+        walkDir(pagesDir, '', routes);
+        // Sort: static → dynamic → catch-all
+        routes.sort((a, b) => {
+            const aCatchAll = a.path.includes(':...');
+            const bCatchAll = b.path.includes(':...');
+            if (aCatchAll !== bCatchAll)
+                return aCatchAll ? 1 : -1;
+            const aDynamic = a.path.includes(':');
+            const bDynamic = b.path.includes(':');
+            if (aDynamic !== bDynamic)
+                return aDynamic ? 1 : -1;
+            return a.path.localeCompare(b.path);
+        });
+        return routes;
+    }
+    function walkDir(baseDir, relativePath, routes) {
+        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);
+            }
+            else if (entry.isFile() && /\.(ts|js)$/.test(entry.name) && !entry.name.startsWith('_')) {
+                const routePath = filePathToRoute(entryRelative);
+                const componentPath = path.join(pagesDir, entryRelative);
+                const tagName = filePathToTagName(entryRelative);
+                routes.push({ path: routePath, componentPath, tagName });
+            }
+        }
+    }
+    function filePathToTagName(filePath) {
+        const name = filePath
+            .replace(/\.(ts|js)$/, '')
+            .replace(/\\/g, '-')
+            .replace(/\//g, '-')
+            .replace(/\[\.\.\.([^\]]+)\]/g, '$1')
+            .replace(/\[([^\]]+)\]/g, '$1')
+            .toLowerCase();
+        return `page-${name}`;
+    }
+    /** Build the layout chain for a route based on its file path within pages/ */
+    function getLayoutChain(componentPath, layouts) {
+        const relativeToPages = path.relative(pagesDir, componentPath).replace(/\\/g, '/');
+        const dirParts = path.dirname(relativeToPages).split('/').filter(p => p && p !== '.');
+        const chain = [];
+        const rootLayout = layouts.find(l => l.dir === '');
+        if (rootLayout)
+            chain.push(rootLayout);
+        let currentDir = '';
+        for (const part of dirParts) {
+            currentDir = currentDir ? `${currentDir}/${part}` : part;
+            const layout = layouts.find(l => l.dir === currentDir);
+            if (layout)
+                chain.push(layout);
+        }
+        return chain;
+    }
+    return {
+        name: 'lumenjs-routes',
+        resolveId(id) {
+            if (id === VIRTUAL_MODULE_ID)
+                return RESOLVED_VIRTUAL_MODULE_ID;
+        },
+        load(id) {
+            if (id === RESOLVED_VIRTUAL_MODULE_ID) {
+                const routes = scanPages();
+                const layouts = scanLayouts();
+                const routeArray = routes
+                    .map(r => {
+                    const hasLoader = fileHasLoader(r.componentPath);
+                    const componentPath = r.componentPath.replace(/\\/g, '/');
+                    const chain = getLayoutChain(r.componentPath, layouts);
+                    let layoutsStr = '';
+                    if (chain.length > 0) {
+                        const items = chain.map(l => {
+                            const lHasLoader = fileHasLoader(l.filePath);
+                            const lPath = l.filePath.replace(/\\/g, '/');
+                            return `{ tagName: ${JSON.stringify(l.tagName)}, loaderPath: ${JSON.stringify(l.dir)}${lHasLoader ? ', hasLoader: 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} }`;
+                })
+                    .join(',\n');
+                return `export const routes = [\n${routeArray}\n];\n`;
+            }
+        },
+        configureServer(server) {
+            // Full-reload when route structure changes (file added/removed)
+            let lastRoutes = JSON.stringify(scanPages().map(r => r.path));
+            let lastLayouts = JSON.stringify(scanLayouts().map(l => l.dir));
+            const checkReload = () => {
+                const newRoutes = JSON.stringify(scanPages().map(r => r.path));
+                const newLayouts = JSON.stringify(scanLayouts().map(l => l.dir));
+                if (newRoutes !== lastRoutes || newLayouts !== lastLayouts) {
+                    lastRoutes = newRoutes;
+                    lastLayouts = newLayouts;
+                    const mod = server.moduleGraph.getModuleById(RESOLVED_VIRTUAL_MODULE_ID);
+                    if (mod) {
+                        server.moduleGraph.invalidateModule(mod);
+                        server.ws.send({ type: 'full-reload' });
+                    }
+                }
+            };
+            server.watcher.on('add', (file) => {
+                if (!file.startsWith(pagesDir))
+                    return;
+                checkReload();
+            });
+            server.watcher.on('unlink', (file) => {
+                if (!file.startsWith(pagesDir))
+                    return;
+                checkReload();
+            });
+        }
+    };
+}

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

@@ -0,0 +1,5 @@
+import { Plugin } from 'vite';
+/**
+ * In editor mode, inject data-nk-source attributes into html`` template literals.
+ */
+export declare function sourceAnnotatorPlugin(projectDir: string): Plugin;

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

@@ -0,0 +1,39 @@
+import path from 'path';
+/**
+ * In editor mode, inject data-nk-source attributes into html`` template literals.
+ */
+export function sourceAnnotatorPlugin(projectDir) {
+    return {
+        name: 'lumenjs-source-annotator',
+        transform(code, id) {
+            if (!id.startsWith(projectDir) || !id.endsWith('.ts'))
+                return;
+            if (!code.includes('html`'))
+                return;
+            const relativePath = path.relative(projectDir, id);
+            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) => {
+                    const beforeTag = templateContent.substring(0, templateContent.indexOf(tagMatch, offset));
+                    const lineInTemplate = beforeTag.split('\n').length - 1;
+                    offset = templateContent.indexOf(tagMatch, offset) + tagMatch.length;
+                    const line = baseLine + lineInTemplate;
+                    return `<${tagName} data-nk-source="${relativePath}:${line}"${after}`;
+                });
+                const dynamicAnnotated = annotated.replace(/<(h[1-6]|p|span|a|label|li|button|div)(\s[^>]*)?>([^<]*\$\{[^<]*)<\//gi, (m, tag, attrs, content) => {
+                    const attrStr = attrs || '';
+                    if (attrStr.includes('data-nk-dynamic'))
+                        return m;
+                    const escaped = content.trim().replace(/"/g, '&quot;').replace(/\$\{/g, '__NK_EXPR__');
+                    return `<${tag}${attrStr} data-nk-dynamic="${escaped}">${content}</`;
+                });
+                return 'html`' + dynamicAnnotated + '`';
+            });
+            if (transformed !== code) {
+                return { code: transformed, map: null };
+            }
+        }
+    };
+}

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

@@ -0,0 +1,5 @@
+import { Plugin } from 'vite';
+/**
+ * Virtual module plugin — serves compiled LumenJS runtime and editor modules.
+ */
+export declare function virtualModulesPlugin(runtimeDir: string, editorDir: string): Plugin;

package/dist/dev-server/plugins/vite-plugin-virtual-modules.js

@@ -0,0 +1,38 @@
+import fs from 'fs';
+import path from 'path';
+/**
+ * Virtual module plugin — serves compiled LumenJS runtime and editor modules.
+ */
+export function virtualModulesPlugin(runtimeDir, editorDir) {
+    return {
+        name: 'lumenjs-virtual-modules',
+        resolveId(id) {
+            if (id === '/@lumenjs/app-shell')
+                return '\0lumenjs:app-shell';
+            if (id === '/@lumenjs/router')
+                return '\0lumenjs:router';
+            if (id === '/@lumenjs/editor-bridge')
+                return '\0lumenjs:editor-bridge';
+            if (id === '/@lumenjs/element-annotator')
+                return '\0lumenjs:element-annotator';
+        },
+        load(id) {
+            if (id === '\0lumenjs:app-shell') {
+                let code = fs.readFileSync(path.join(runtimeDir, 'app-shell.js'), 'utf-8');
+                code = code.replace(/from\s+['"]\.\/router\.js['"]/g, "from '/@lumenjs/router'");
+                return code;
+            }
+            if (id === '\0lumenjs:router') {
+                return fs.readFileSync(path.join(runtimeDir, 'router.js'), 'utf-8');
+            }
+            if (id === '\0lumenjs:editor-bridge') {
+                let code = fs.readFileSync(path.join(editorDir, 'editor-bridge.js'), 'utf-8');
+                code = code.replace(/from\s+['"]\.\/element-annotator\.js['"]/g, "from '/@lumenjs/element-annotator'");
+                return code;
+            }
+            if (id === '\0lumenjs:element-annotator') {
+                return fs.readFileSync(path.join(editorDir, 'element-annotator.js'), 'utf-8');
+            }
+        }
+    };
+}