@nuraly/lumenjs 0.1.3 → 0.1.4

package/dist/dev-server/server.js

@@ -11,13 +11,21 @@ import { ssrRenderPage } from './ssr-render.js';
 import { readProjectConfig, getLumenJSNodeModules, getLumenJSDirs } from './config.js';
 import { getNuralyUIAliases, resolveNuralyUIPaths } from './nuralyui-aliases.js';
 import { litDedupPlugin } from './plugins/vite-plugin-lit-dedup.js';
+import { autoDefinePlugin } from './plugins/vite-plugin-auto-define.js';
 import { autoImportPlugin } from './plugins/vite-plugin-auto-import.js';
 import { litHmrPlugin } from './plugins/vite-plugin-lit-hmr.js';
 import { sourceAnnotatorPlugin } from './plugins/vite-plugin-source-annotator.js';
+import { editorApiPlugin } from './plugins/vite-plugin-editor-api.js';
 import { virtualModulesPlugin } from './plugins/vite-plugin-virtual-modules.js';
 import { i18nPlugin, loadTranslationsFromDisk } from './plugins/vite-plugin-i18n.js';
+import { authPlugin } from './plugins/vite-plugin-auth.js';
+import { communicationPlugin } from './plugins/vite-plugin-communication.js';
+import { lumenStoragePlugin } from './plugins/vite-plugin-storage.js';
+import { lumenSocketIOPlugin } from './plugins/vite-plugin-socketio.js';
 import { resolveLocale } from './middleware/locale.js';
 import { setProjectDir } from '../db/context.js';
+import { scanMiddleware, getMiddlewareDirsForPathname } from '../build/scan.js';
+import { runMiddlewareChain, extractMiddleware } from '../shared/middleware-runner.js';
 // Re-export for backwards compatibility
 export { readProjectConfig, readProjectTitle, getLumenJSNodeModules, getLumenJSDirs } from './config.js';
 export { getNuralyUIAliases, resolveNuralyUIPaths } from './nuralyui-aliases.js';
@@ -30,24 +38,37 @@ export function getSharedViteConfig(projectDir, options) {
     const isDev = mode === 'development';
     const pagesDir = path.join(projectDir, 'pages');
     const lumenNodeModules = getLumenJSNodeModules();
-    const { runtimeDir, editorDir } = getLumenJSDirs();
+    const { distDir, runtimeDir, editorDir } = getLumenJSDirs();
     // Resolve NuralyUI paths for aliases (only when nuralyui integration is enabled)
     const aliases = {};
     if (options?.integrations?.includes('nuralyui')) {
         const nuralyUIPaths = resolveNuralyUIPaths(projectDir);
         if (nuralyUIPaths) {
             Object.assign(aliases, getNuralyUIAliases(nuralyUIPaths.componentsPath, nuralyUIPaths.commonPath));
+            // Add root aliases for theme CSS imports
+            const nuralyUIRoot = path.resolve(nuralyUIPaths.componentsPath, '..');
+            aliases['@nuralyui-theme'] = path.join(nuralyUIRoot, 'shared/themes');
+            aliases['@nuralyui-common'] = nuralyUIPaths.commonPath;
         }
     }
     const resolve = {
         alias: {
             ...aliases,
-            // Map @lumenjs/i18n to the physical dist file so Vite resolves it
-            // without going through node_modules (it's not an npm package).
             '@lumenjs/i18n': path.join(runtimeDir, 'i18n.js'),
+            '@lumenjs/auth': path.join(runtimeDir, 'auth.js'),
+            '@nuraly/lumenjs-auth': path.join(runtimeDir, 'auth.js'),
+            '@lumenjs/communication': path.join(runtimeDir, 'communication.js'),
+            '@lumenjs/webrtc': path.join(runtimeDir, 'webrtc.js'),
+            '@lumenjs/db': path.join(distDir, 'db', 'client.js'),
+            '@lumenjs/permissions': path.join(distDir, 'permissions', 'index.js'),
+            '@lumenjs/storage': path.join(distDir, 'storage', 'index.js'),
+            '@nuraly/lumenjs': path.resolve(distDir, '..'),
         },
         conditions: isDev ? ['development', 'browser'] : ['browser'],
-        dedupe: ['lit', 'lit-html', 'lit-element', '@lit/reactive-element'],
+        // Note: resolve.dedupe is NOT used — it resolves via Node's algorithm
+        // which ignores Vite's resolve.conditions, picking the `default` export
+        // (prod proxy) instead of `development`. The litDedupPlugin handles
+        // single-copy resolution with correct conditions instead.
     };
     const esbuild = {
         tsconfigRaw: {
@@ -60,6 +81,7 @@ export function getSharedViteConfig(projectDir, options) {
     const plugins = [
         lumenRoutesPlugin(pagesDir),
         lumenLoadersPlugin(pagesDir),
+        autoDefinePlugin(pagesDir),
         litDedupPlugin(lumenNodeModules, isDev),
         virtualModulesPlugin(runtimeDir, editorDir),
     ];
@@ -83,12 +105,17 @@ export function getSharedViteConfig(projectDir, options) {
 }
 export async function createDevServer(options) {
     const { projectDir, port, editorMode = false, base = '/' } = options;
-    setProjectDir(projectDir);
     const pagesDir = path.join(projectDir, 'pages');
     const apiDir = path.join(projectDir, 'api');
     const publicDir = path.join(projectDir, 'public');
     const config = readProjectConfig(projectDir);
-    const { title, integrations, i18n: i18nConfig } = config;
+    const { title, integrations, i18n: i18nConfig, prefetch: prefetchStrategy } = config;
+    // Read optional head.html for blocking scripts (e.g. theme initialization)
+    const headHtmlPath = path.join(projectDir, 'head.html');
+    const headContent = fs.existsSync(headHtmlPath) ? fs.readFileSync(headHtmlPath, 'utf-8') : undefined;
+    // Set project dir for DB context (used by loaders, API routes, plugins)
+    setProjectDir(projectDir);
+    process.env.LUMENJS_PROJECT_DIR = projectDir;
     const shared = getSharedViteConfig(projectDir, { integrations });
     const server = await createViteServer({
         root: projectDir,
@@ -99,15 +126,90 @@ export async function createDevServer(options) {
             strictPort: false,
             allowedHosts: true,
             cors: true,
-            hmr: true,
+            hmr: process.env.HMR_CLIENT_PORT ? { clientPort: parseInt(process.env.HMR_CLIENT_PORT), protocol: process.env.HMR_PROTOCOL || 'wss', host: process.env.HMR_HOST || undefined } : true,
+            fs: {
+                allow: [projectDir, getLumenJSNodeModules(), path.resolve(getLumenJSNodeModules(), '..')],
+            },
         },
         resolve: shared.resolve,
         plugins: [
+            ...(integrations.includes('auth') ? [authPlugin(projectDir)] : []),
             ...shared.plugins,
+            ...(integrations.includes('communication') ? [communicationPlugin(projectDir)] : []),
+            lumenStoragePlugin(projectDir),
             lumenApiRoutesPlugin(apiDir, projectDir),
             litHmrPlugin(projectDir),
             ...(i18nConfig ? [i18nPlugin(projectDir, i18nConfig)] : []),
-            ...(editorMode ? [sourceAnnotatorPlugin(projectDir)] : []),
+            ...(editorMode ? [sourceAnnotatorPlugin(projectDir), editorApiPlugin(projectDir)] : []),
+            lumenSocketIOPlugin(pagesDir),
+            {
+                // Clear SSR module cache on file changes so the next SSR request uses fresh code.
+                // Without this, HMR updates the client but SSR keeps serving stale modules.
+                name: 'lumenjs-ssr-invalidate-on-change',
+                handleHotUpdate({ file, server }) {
+                    const mods = server.moduleGraph.getModulesByFile(file);
+                    if (mods) {
+                        for (const m of mods) {
+                            m.ssrModule = null;
+                            m.ssrTransformResult = null;
+                        }
+                    }
+                },
+            },
+            {
+                name: 'lumenjs-user-middleware',
+                config(config) {
+                    const entries = scanMiddleware(pagesDir);
+                    if (entries.length === 0)
+                        return;
+                    const npmDeps = new Set();
+                    for (const entry of entries) {
+                        try {
+                            const content = fs.readFileSync(entry.filePath, 'utf-8');
+                            const importMatches = content.matchAll(/(?:import|require)\s*(?:\(?\s*['"]([^./][^'"]*)['"]\s*\)?|.*from\s*['"]([^./][^'"]*)['"]\s*)/g);
+                            for (const m of importMatches) {
+                                const pkg = m[1] || m[2];
+                                if (pkg) {
+                                    const pkgName = pkg.startsWith('@') ? pkg.split('/').slice(0, 2).join('/') : pkg.split('/')[0];
+                                    npmDeps.add(pkgName);
+                                }
+                            }
+                        }
+                        catch { }
+                    }
+                    if (npmDeps.size > 0) {
+                        const existing = config.ssr?.external || [];
+                        return { ssr: { external: [...existing, ...npmDeps] } };
+                    }
+                },
+                configureServer(server) {
+                    server.middlewares.use(async (req, res, next) => {
+                        const pathname = (req.url || '/').split('?')[0];
+                        if (pathname.startsWith('/@') || pathname.startsWith('/node_modules') || pathname.includes('.')) {
+                            return next();
+                        }
+                        const middlewareEntries = scanMiddleware(pagesDir);
+                        if (middlewareEntries.length === 0)
+                            return next();
+                        const matchingDirs = getMiddlewareDirsForPathname(pathname, middlewareEntries);
+                        if (matchingDirs.length === 0)
+                            return next();
+                        const allMw = [];
+                        for (const entry of matchingDirs) {
+                            try {
+                                const mod = await server.ssrLoadModule(entry.filePath);
+                                allMw.push(...extractMiddleware(mod));
+                            }
+                            catch (err) {
+                                console.error(`[LumenJS] Failed to load _middleware.ts (${entry.dir || 'root'}):`, err);
+                            }
+                        }
+                        if (allMw.length === 0)
+                            return next();
+                        runMiddlewareChain(allMw, req, res, next);
+                    });
+                }
+            },
             {
                 name: 'lumenjs-index-html',
                 configureServer(server) {
@@ -138,7 +240,7 @@ export async function createDevServer(options) {
                                 translations = loadTranslationsFromDisk(projectDir, locale);
                             }
                             const SSR_PLACEHOLDER = '<!--__NK_SSR_CONTENT__-->';
-                            ssrRenderPage(server, pagesDir, pathname, req.headers, locale).then(async (ssrResult) => {
+                            ssrRenderPage(server, pagesDir, pathname, req.headers, locale, req.nkAuth?.user ?? undefined).then(async (ssrResult) => {
                                 if (ssrResult?.redirect) {
                                     res.writeHead(ssrResult.redirect.status, { Location: ssrResult.redirect.location });
                                     res.end();
@@ -154,6 +256,9 @@ export async function createDevServer(options) {
                                     locale,
                                     i18nConfig: i18nConfig || undefined,
                                     translations,
+                                    prefetch: prefetchStrategy,
+                                    authUser: ssrResult?.authUser ?? req.nkAuth?.user ?? undefined,
+                                    headContent,
                                 });
                                 const transformed = await server.transformIndexHtml(req.url, shellHtml);
                                 const finalHtml = ssrResult
@@ -164,7 +269,7 @@ export async function createDevServer(options) {
                                 res.end(finalHtml);
                             }).catch(err => {
                                 console.error('[LumenJS] SSR/HTML generation error:', err);
-                                const html = generateIndexHtml({ title, editorMode, integrations, locale, i18nConfig: i18nConfig || undefined, translations });
+                                const html = generateIndexHtml({ title, editorMode, integrations, locale, i18nConfig: i18nConfig || undefined, translations, prefetch: prefetchStrategy, headContent });
                                 server.transformIndexHtml(req.url, html).then(transformed => {
                                     res.setHeader('Content-Type', 'text/html');
                                     res.setHeader('Cache-Control', 'no-store');
@@ -180,12 +285,21 @@ export async function createDevServer(options) {
         ],
         esbuild: shared.esbuild,
         optimizeDeps: {
-            include: ['lit', 'lit/decorators.js', 'lit/directive.js', 'lit/directive-helpers.js', 'lit/async-directive.js', 'lit-html', 'lit-element', '@lit/reactive-element'],
-            exclude: ['@lumenjs/i18n'],
+            exclude: [
+                '@lumenjs/i18n',
+                '@nuraly/lumenjs-auth',
+                // Lit packages must NOT be pre-bundled — pre-bundling creates separate
+                // module entries (/.vite/deps/) alongside raw /@fs/ files, causing
+                // multiple lit-html instances. Instead, resolve.dedupe forces all lit
+                // imports to a single copy. The project's lit version MUST match
+                // lumenjs's lit version for dedupe to work.
+                'lit', 'lit-html', 'lit-element', '@lit/reactive-element',
+                '@lit-labs/ssr-client',
+            ],
         },
         ssr: {
             noExternal: true,
-            external: ['node-domexception'],
+            external: ['node-domexception', 'socket.io-client', 'xmlhttprequest-ssl', 'engine.io-client', 'better-sqlite3', '@lumenjs/db', '@lumenjs/permissions'],
             resolve: {
                 conditions: ['node', 'import'],
             },

package/dist/dev-server/ssr-render.d.ts

@@ -9,7 +9,7 @@ export interface LayoutSSRData {
  *
  * Returns pre-rendered HTML and loader data, or null on failure (falls back to CSR).
  */
-export declare function ssrRenderPage(server: ViteDevServer, pagesDir: string, pathname: string, headers?: Record<string, string | string[] | undefined>, locale?: string): Promise<{
+export declare function ssrRenderPage(server: ViteDevServer, pagesDir: string, pathname: string, headers?: Record<string, string | string[] | undefined>, locale?: string, user?: any): Promise<{
     html: string;
     loaderData: any;
     layoutsData?: LayoutSSRData[];
@@ -17,4 +17,5 @@ export declare function ssrRenderPage(server: ViteDevServer, pagesDir: string, p
         location: string;
         status: number;
     };
+    authUser?: any;
 } | null>;

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

@@ -1,7 +1,7 @@
 import path from 'path';
 import fs from 'fs';
 import { resolvePageFile, extractRouteParams } from './plugins/vite-plugin-loaders.js';
-import { stripOuterLitMarkers, dirToLayoutTagName, filePathToTagName } from '../shared/utils.js';
+import { stripOuterLitMarkers, dirToLayoutTagName, filePathToTagName, patchLoaderDataSpread } from '../shared/utils.js';
 import { installDomShims } from '../shared/dom-shims.js';
 import { loadTranslationsFromDisk } from './plugins/vite-plugin-i18n.js';
 /**
@@ -10,7 +10,7 @@ import { loadTranslationsFromDisk } from './plugins/vite-plugin-i18n.js';
  *
  * Returns pre-rendered HTML and loader data, or null on failure (falls back to CSR).
  */
-export async function ssrRenderPage(server, pagesDir, pathname, headers, locale) {
+export async function ssrRenderPage(server, pagesDir, pathname, headers, locale, user) {
     try {
         const filePath = resolvePageFile(pagesDir, pathname);
         if (!filePath)
@@ -20,32 +20,27 @@ export async function ssrRenderPage(server, pagesDir, pathname, headers, locale)
         await server.ssrLoadModule('@lit-labs/ssr/lib/install-global-dom-shim.js');
         // Patch missing DOM APIs that NuralyUI components may use during SSR
         installDomShims();
-        // Initialize i18n in the SSR context so t() works during render
-        if (locale) {
-            const projectDir = path.resolve(pagesDir, '..');
-            const translations = loadTranslationsFromDisk(projectDir, locale);
-            try {
-                // Load the same i18n module the page will import (via resolve.alias)
-                const i18nMod = await server.ssrLoadModule('@lumenjs/i18n');
-                if (i18nMod?.initI18n) {
-                    i18nMod.initI18n({ locales: [], defaultLocale: locale, prefixDefault: false }, locale, translations);
-                }
-            }
-            catch {
-                // i18n module not available — translations will show keys
-            }
-        }
         // Invalidate SSR module cache so we always get fresh content after file edits.
         // Also clear the custom element from the SSR registry so the new class is used.
+        // IMPORTANT: This must happen BEFORE i18n/auth init, because invalidation
+        // recursively clears all SSR-imported modules (including @lumenjs/i18n).
+        // If we init i18n first, then invalidate, the page reload gets a fresh i18n
+        // module instance with empty translations.
         const g = globalThis;
         invalidateSsrModule(server, filePath);
         clearSsrCustomElement(g);
         // Load the page module via Vite (registers the custom element, applies transforms)
+        // Bypass get() so auto-define re-registers fresh classes
+        const registry = g.customElements;
+        if (registry)
+            registry.__nk_bypass_get = true;
         const mod = await server.ssrLoadModule(filePath);
+        if (registry)
+            registry.__nk_bypass_get = false;
         // Run loader if present
         let loaderData = undefined;
         if (mod.loader && typeof mod.loader === 'function') {
-            loaderData = await mod.loader({ params, query: {}, url: pathname, headers: headers || {}, locale });
+            loaderData = await mod.loader({ 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 } };
             }
@@ -53,8 +48,8 @@ export async function ssrRenderPage(server, pagesDir, pathname, headers, locale)
         // Determine the custom element tag name from file path (matches client router)
         const relPath = path.relative(pagesDir, filePath).replace(/\\/g, '/');
         const tagName = filePathToTagName(relPath);
-        // Discover layout chain for this page
-        const layoutChain = discoverLayoutChain(pagesDir, filePath);
+        // Standalone pages skip all layouts
+        const layoutChain = mod.standalone ? [] : discoverLayoutChain(pagesDir, filePath);
         const layoutsData = [];
         // Load layout modules and run their loaders
         const layoutModules = [];
@@ -62,10 +57,14 @@ export async function ssrRenderPage(server, pagesDir, pathname, headers, locale)
             // Invalidate layout module cache and clear SSR element registry
             invalidateSsrModule(server, layout.filePath);
             clearSsrCustomElement(g);
+            if (registry)
+                registry.__nk_bypass_get = true;
             const layoutMod = await server.ssrLoadModule(layout.filePath);
+            if (registry)
+                registry.__nk_bypass_get = false;
             let layoutLoaderData = undefined;
             if (layoutMod.loader && typeof layoutMod.loader === 'function') {
-                layoutLoaderData = await layoutMod.loader({ params: {}, query: {}, url: pathname, headers: headers || {}, locale });
+                layoutLoaderData = await layoutMod.loader({ params: {}, query: {}, url: pathname, headers: headers || {}, locale, user: user ?? null });
                 if (layoutLoaderData && typeof layoutLoaderData === 'object' && layoutLoaderData.__nk_redirect) {
                     return { html: '', loaderData: null, redirect: { location: layoutLoaderData.location, status: layoutLoaderData.status || 302 } };
                 }
@@ -74,6 +73,38 @@ export async function ssrRenderPage(server, pagesDir, pathname, headers, locale)
             layoutModules.push({ tagName: layoutTagName, loaderData: layoutLoaderData });
             layoutsData.push({ loaderPath: layout.dir, data: layoutLoaderData });
         }
+        // Patch element classes to spread loaderData into individual properties
+        for (const lm of layoutModules) {
+            patchLoaderDataSpread(lm.tagName);
+        }
+        patchLoaderDataSpread(tagName);
+        // Initialize i18n in the SSR context AFTER all page/layout modules are loaded.
+        // This ensures t() uses the same module instance the components imported.
+        // Must happen after invalidation + module loading, because invalidateSsrModule
+        // recursively clears cached modules — if i18n was initialized before, the
+        // reloaded page/layout would get a fresh i18n instance with empty translations.
+        if (locale) {
+            const projectDir = path.resolve(pagesDir, '..');
+            const translations = loadTranslationsFromDisk(projectDir, locale);
+            try {
+                const i18nMod = await server.ssrLoadModule('@lumenjs/i18n');
+                if (i18nMod?.initI18n) {
+                    i18nMod.initI18n({ locales: [], defaultLocale: locale, prefixDefault: false }, locale, translations);
+                }
+            }
+            catch {
+                // i18n module not available — translations will show keys
+            }
+        }
+        // Initialize auth in the SSR context (same reason — after module loading)
+        if (user) {
+            try {
+                const authMod = await server.ssrLoadModule('@nuraly/lumenjs-auth');
+                if (authMod?.initAuth)
+                    authMod.initAuth(user);
+            }
+            catch { }
+        }
         // Load SSR render + lit/static-html.js through Vite (same module registry as page)
         const { render } = await server.ssrLoadModule('@lit-labs/ssr');
         const { html, unsafeStatic } = await server.ssrLoadModule('lit/static-html.js');
@@ -106,7 +137,7 @@ export async function ssrRenderPage(server, pagesDir, pathname, headers, locale)
                 htmlStr = layoutHtml + htmlStr;
             }
         }
-        return { html: htmlStr, loaderData, layoutsData: layoutsData.length > 0 ? layoutsData : undefined };
+        return { html: htmlStr, loaderData, layoutsData: layoutsData.length > 0 ? layoutsData : undefined, authUser: user ?? undefined };
     }
     catch (err) {
         console.error('[LumenJS] SSR render failed, falling back to CSR:', err);
@@ -145,41 +176,69 @@ function findLayoutFile(dir) {
     return null;
 }
 /**
- * Aggressively invalidate a module for SSR re-execution.
+ * Aggressively invalidate a module and all its SSR-imported dependencies.
+ * Without this, editing a component imported by a page/layout serves stale SSR.
  */
 function invalidateSsrModule(server, filePath) {
-    const byFile = server.moduleGraph.getModulesByFile(filePath);
-    if (byFile) {
-        for (const m of byFile) {
-            server.moduleGraph.invalidateModule(m);
-            m.ssrModule = null;
-            m.ssrTransformResult = null;
+    const visited = new Set();
+    function invalidateRecursive(id) {
+        if (visited.has(id))
+            return;
+        visited.add(id);
+        const mods = server.moduleGraph.getModulesByFile(id);
+        if (mods) {
+            for (const m of mods) {
+                server.moduleGraph.invalidateModule(m);
+                m.ssrModule = null;
+                m.ssrTransformResult = null;
+                // Recurse into SSR-imported modules
+                if (m.ssrImportedModules) {
+                    for (const dep of m.ssrImportedModules) {
+                        if (dep.file)
+                            invalidateRecursive(dep.file);
+                    }
+                }
+            }
+        }
+        const urlMod = server.moduleGraph.getModuleById(id);
+        if (urlMod) {
+            server.moduleGraph.invalidateModule(urlMod);
+            urlMod.ssrModule = null;
+            urlMod.ssrTransformResult = null;
         }
     }
-    const urlMod = server.moduleGraph.getModuleById(filePath);
-    if (urlMod) {
-        server.moduleGraph.invalidateModule(urlMod);
-        urlMod.ssrModule = null;
-        urlMod.ssrTransformResult = null;
-    }
+    invalidateRecursive(filePath);
 }
 /**
- * Patch the SSR customElements registry to allow re-registration.
+ * Patch the SSR customElements registry to allow re-registration,
+ * and proactively clear all definitions so auto-define guards pass.
  */
 function clearSsrCustomElement(g) {
     const registry = g.customElements;
-    if (!registry || registry.__nk_patched)
+    if (!registry)
         return;
-    registry.__nk_patched = true;
-    const origDefine = registry.define.bind(registry);
-    registry.define = (name, ctor) => {
-        if (registry.__definitions && registry.__definitions.has(name)) {
-            const oldCtor = registry.__definitions.get(name)?.ctor;
-            registry.__definitions.delete(name);
-            if (oldCtor && registry.__reverseDefinitions) {
-                registry.__reverseDefinitions.delete(oldCtor);
+    // Patch define() to allow re-registration and get() to bypass
+    // auto-define guards (one-time)
+    if (!registry.__nk_patched) {
+        registry.__nk_patched = true;
+        const origDefine = registry.define.bind(registry);
+        registry.define = (name, ctor) => {
+            if (registry.__definitions && registry.__definitions.has(name)) {
+                const oldCtor = registry.__definitions.get(name)?.ctor;
+                registry.__definitions.delete(name);
+                if (oldCtor && registry.__reverseDefinitions) {
+                    registry.__reverseDefinitions.delete(oldCtor);
+                }
             }
-        }
-        return origDefine(name, ctor);
-    };
+            return origDefine(name, ctor);
+        };
+        // Patch get() so auto-define's `if (!customElements.get('tag'))` guard
+        // always passes, allowing define() to re-register the fresh class.
+        const origGet = registry.get.bind(registry);
+        registry.get = (name) => {
+            if (registry.__nk_bypass_get)
+                return undefined;
+            return origGet(name);
+        };
+    }
 }

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

@@ -0,0 +1,20 @@
+/**
+ * AI backend router — selects between Claude Code and OpenCode based on:
+ *   1. AI_BACKEND env var ('claude-code' | 'opencode')
+ *   2. Auto-detection: Claude Code CLI first, then OpenCode server
+ */
+import type { AiChatOptions, AiChatResult, AiStatusResult } from './types.js';
+export type { AiChatOptions, AiChatResult, AiStatusResult } from './types.js';
+/**
+ * Stream an AI chat message using the configured backend.
+ */
+export declare function streamAiChat(projectDir: string, options: AiChatOptions): AiChatResult;
+/**
+ * Warm up the AI backend session in the background.
+ * Call on editor startup so the first user request is fast.
+ */
+export declare function warmUpAiSession(projectDir: string): Promise<void>;
+/**
+ * Check if any AI backend is available.
+ */
+export declare function checkAiStatus(): Promise<AiStatusResult>;

package/dist/editor/ai/backend.js

@@ -0,0 +1,104 @@
+/**
+ * AI backend router — selects between Claude Code and OpenCode based on:
+ *   1. AI_BACKEND env var ('claude-code' | 'opencode')
+ *   2. Auto-detection: Claude Code CLI first, then OpenCode server
+ */
+let resolvedBackend = null;
+async function detectBackend() {
+    if (resolvedBackend)
+        return resolvedBackend;
+    const explicit = process.env.AI_BACKEND;
+    if (explicit === 'claude-code' || explicit === 'opencode') {
+        resolvedBackend = explicit;
+        console.log(`[LumenJS] AI backend: ${explicit} (from AI_BACKEND env)`);
+        return resolvedBackend;
+    }
+    // Auto-detect: try Claude Code first (subscription-based, no server needed)
+    try {
+        const cc = await import('./claude-code-client.js');
+        const status = await cc.checkAiStatus();
+        if (status.configured) {
+            resolvedBackend = 'claude-code';
+            console.log('[LumenJS] AI backend: claude-code (auto-detected)');
+            return resolvedBackend;
+        }
+    }
+    catch {
+        // SDK not installed or CLI not found
+    }
+    // Fall back to OpenCode
+    resolvedBackend = 'opencode';
+    console.log('[LumenJS] AI backend: opencode (fallback)');
+    return resolvedBackend;
+}
+async function getClient() {
+    const backend = await detectBackend();
+    if (backend === 'claude-code') {
+        return import('./claude-code-client.js');
+    }
+    return import('./opencode-client.js');
+}
+/**
+ * Stream an AI chat message using the configured backend.
+ */
+export function streamAiChat(projectDir, options) {
+    const tokenCallbacks = [];
+    const doneCallbacks = [];
+    const errorCallbacks = [];
+    let innerResult = null;
+    const run = async () => {
+        try {
+            const client = await getClient();
+            innerResult = client.streamAiChat(projectDir, options);
+            // Forward callbacks registered before the client loaded
+            for (const cb of tokenCallbacks)
+                innerResult.onToken(cb);
+            for (const cb of doneCallbacks)
+                innerResult.onDone(cb);
+            for (const cb of errorCallbacks)
+                innerResult.onError(cb);
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            for (const cb of errorCallbacks)
+                cb(error);
+        }
+    };
+    run();
+    return {
+        get sessionId() { return innerResult?.sessionId || options.sessionId || ''; },
+        onToken: (cb) => { tokenCallbacks.push(cb); innerResult?.onToken(cb); },
+        onDone: (cb) => { doneCallbacks.push(cb); innerResult?.onDone(cb); },
+        onError: (cb) => { errorCallbacks.push(cb); innerResult?.onError(cb); },
+        abort: () => innerResult?.abort(),
+    };
+}
+/**
+ * Warm up the AI backend session in the background.
+ * Call on editor startup so the first user request is fast.
+ */
+export async function warmUpAiSession(projectDir) {
+    const backend = await detectBackend();
+    if (backend === 'claude-code') {
+        try {
+            const cc = await import('./claude-code-client.js');
+            await cc.warmUpSession(projectDir);
+            console.log('[LumenJS] AI session warmed up');
+        }
+        catch {
+            // Non-fatal
+        }
+    }
+}
+/**
+ * Check if any AI backend is available.
+ */
+export async function checkAiStatus() {
+    try {
+        const client = await getClient();
+        return client.checkAiStatus();
+    }
+    catch {
+        return { configured: false, backend: 'opencode' };
+    }
+}

package/dist/editor/ai/claude-code-client.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Claude Code AI client — uses the Claude Agent SDK (@anthropic-ai/claude-agent-sdk).
+ * Spawns the `claude` CLI as a subprocess. Requires Claude Code CLI installed and logged in.
+ * Works with Pro/Max subscription — no API key needed.
+ */
+import type { AiChatOptions, AiChatResult, AiStatusResult } from './types.js';
+/**
+ * Warm up by pre-spawning a Claude Code session. The first real request
+ * will resume this session, skipping CLI cold-start entirely.
+ */
+export declare function warmUpSession(projectDir: string): Promise<void>;
+/**
+ * Stream an AI chat message via Claude Code Agent SDK.
+ */
+export declare function streamAiChat(projectDir: string, options: AiChatOptions): AiChatResult;
+/**
+ * Check if Claude Code CLI is installed and the Agent SDK is importable.
+ * Both are required — the CLI alone isn't enough.
+ */
+export declare function checkAiStatus(): Promise<AiStatusResult>;