@nuraly/lumenjs 0.1.0

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

@@ -0,0 +1,23 @@
+import { ViteDevServer, UserConfig, Plugin } from 'vite';
+export { readProjectConfig, readProjectTitle, getLumenJSNodeModules, getLumenJSDirs } from './config.js';
+export type { ProjectConfig } from './config.js';
+export { getNuralyUIAliases, resolveNuralyUIPaths } from './nuralyui-aliases.js';
+export interface DevServerOptions {
+    projectDir: string;
+    port: number;
+    editorMode?: boolean;
+    base?: string;
+}
+/**
+ * Returns shared Vite config used by both dev and production builds.
+ * Includes NuralyUI aliases, lit dedup, loaders strip, auto-import, and virtual modules.
+ */
+export declare function getSharedViteConfig(projectDir: string, options?: {
+    mode?: 'development' | 'production';
+    integrations?: string[];
+}): {
+    resolve: UserConfig['resolve'];
+    esbuild: UserConfig['esbuild'];
+    plugins: Plugin[];
+};
+export declare function createDevServer(options: DevServerOptions): Promise<ViteDevServer>;

package/dist/dev-server/server.js

@@ -0,0 +1,155 @@
+import { createServer as createViteServer } from 'vite';
+import path from 'path';
+import fs from 'fs';
+import { createRequire } from 'module';
+import { pathToFileURL } from 'url';
+import { lumenRoutesPlugin } from './plugins/vite-plugin-routes.js';
+import { lumenApiRoutesPlugin } from './plugins/vite-plugin-api-routes.js';
+import { lumenLoadersPlugin } from './plugins/vite-plugin-loaders.js';
+import { generateIndexHtml } from './index-html.js';
+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 { 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 { virtualModulesPlugin } from './plugins/vite-plugin-virtual-modules.js';
+// Re-export for backwards compatibility
+export { readProjectConfig, readProjectTitle, getLumenJSNodeModules, getLumenJSDirs } from './config.js';
+export { getNuralyUIAliases, resolveNuralyUIPaths } from './nuralyui-aliases.js';
+/**
+ * Returns shared Vite config used by both dev and production builds.
+ * Includes NuralyUI aliases, lit dedup, loaders strip, auto-import, and virtual modules.
+ */
+export function getSharedViteConfig(projectDir, options) {
+    const mode = options?.mode || 'development';
+    const isDev = mode === 'development';
+    const pagesDir = path.join(projectDir, 'pages');
+    const lumenNodeModules = getLumenJSNodeModules();
+    const { runtimeDir, editorDir } = getLumenJSDirs();
+    // Resolve NuralyUI paths for aliases
+    const nuralyUIPaths = resolveNuralyUIPaths(projectDir);
+    const aliases = {};
+    if (nuralyUIPaths) {
+        Object.assign(aliases, getNuralyUIAliases(nuralyUIPaths.componentsPath, nuralyUIPaths.commonPath));
+    }
+    const resolve = {
+        alias: { ...aliases },
+        conditions: isDev ? ['development', 'browser'] : ['browser'],
+        dedupe: ['lit', 'lit-html', 'lit-element', '@lit/reactive-element'],
+    };
+    const esbuild = {
+        tsconfigRaw: {
+            compilerOptions: {
+                experimentalDecorators: true,
+                useDefineForClassFields: false,
+            }
+        }
+    };
+    const plugins = [
+        lumenRoutesPlugin(pagesDir),
+        lumenLoadersPlugin(pagesDir),
+        litDedupPlugin(lumenNodeModules, isDev),
+        autoImportPlugin(projectDir),
+        virtualModulesPlugin(runtimeDir, editorDir),
+    ];
+    // Conditionally add Tailwind plugin from the project's node_modules
+    if (options?.integrations?.includes('tailwind')) {
+        try {
+            const projectRequire = createRequire(pathToFileURL(path.join(projectDir, 'package.json')).href);
+            const tailwindMod = projectRequire('@tailwindcss/vite');
+            const tailwindPlugin = tailwindMod.default || tailwindMod;
+            plugins.unshift(tailwindPlugin());
+        }
+        catch {
+            console.warn('[LumenJS] Tailwind integration enabled but @tailwindcss/vite not found. Run: lumenjs add tailwind');
+        }
+    }
+    return { resolve, esbuild, plugins };
+}
+export async function createDevServer(options) {
+    const { projectDir, port, editorMode = false, base = '/' } = options;
+    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 } = config;
+    const shared = getSharedViteConfig(projectDir, { integrations });
+    const server = await createViteServer({
+        root: projectDir,
+        publicDir: fs.existsSync(publicDir) ? publicDir : undefined,
+        server: {
+            port,
+            host: true,
+            strictPort: false,
+            allowedHosts: true,
+            cors: true,
+            hmr: true,
+        },
+        resolve: shared.resolve,
+        plugins: [
+            ...shared.plugins,
+            lumenApiRoutesPlugin(apiDir, projectDir),
+            litHmrPlugin(projectDir),
+            ...(editorMode ? [sourceAnnotatorPlugin(projectDir)] : []),
+            {
+                name: 'lumenjs-index-html',
+                configureServer(server) {
+                    server.middlewares.use((req, res, next) => {
+                        if (req.url && !req.url.startsWith('/@') && !req.url.startsWith('/node_modules') &&
+                            !req.url.startsWith('/api/') && !req.url.startsWith('/__nk_loader/') &&
+                            !req.url.includes('.') && req.method === 'GET') {
+                            const pathname = req.url.split('?')[0];
+                            const SSR_PLACEHOLDER = '<!--__NK_SSR_CONTENT__-->';
+                            ssrRenderPage(server, pagesDir, pathname, req.headers).then(async (ssrResult) => {
+                                if (ssrResult?.redirect) {
+                                    res.writeHead(ssrResult.redirect.status, { Location: ssrResult.redirect.location });
+                                    res.end();
+                                    return;
+                                }
+                                const shellHtml = generateIndexHtml({
+                                    title,
+                                    editorMode,
+                                    ssrContent: ssrResult ? SSR_PLACEHOLDER : undefined,
+                                    loaderData: ssrResult?.loaderData,
+                                    layoutsData: ssrResult?.layoutsData,
+                                    integrations,
+                                });
+                                const transformed = await server.transformIndexHtml(req.url, shellHtml);
+                                const finalHtml = ssrResult
+                                    ? transformed.replace(SSR_PLACEHOLDER, ssrResult.html)
+                                    : transformed;
+                                res.setHeader('Content-Type', 'text/html');
+                                res.setHeader('Cache-Control', 'no-store');
+                                res.end(finalHtml);
+                            }).catch(err => {
+                                console.error('[LumenJS] SSR/HTML generation error:', err);
+                                const html = generateIndexHtml({ title, editorMode, integrations });
+                                server.transformIndexHtml(req.url, html).then(transformed => {
+                                    res.setHeader('Content-Type', 'text/html');
+                                    res.setHeader('Cache-Control', 'no-store');
+                                    res.end(transformed);
+                                }).catch(next);
+                            });
+                            return;
+                        }
+                        next();
+                    });
+                }
+            }
+        ],
+        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'],
+        },
+        ssr: {
+            noExternal: true,
+            external: ['node-domexception'],
+            resolve: {
+                conditions: ['node', 'import'],
+            },
+        },
+    });
+    return server;
+}

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

@@ -0,0 +1,20 @@
+import { ViteDevServer } from 'vite';
+export interface LayoutSSRData {
+    loaderPath: string;
+    data: any;
+}
+/**
+ * Server-side render a LumenJS page using @lit-labs/ssr.
+ * Wraps the page in its layout chain if layouts exist.
+ *
+ * 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>): Promise<{
+    html: string;
+    loaderData: any;
+    layoutsData?: LayoutSSRData[];
+    redirect?: {
+        location: string;
+        status: number;
+    };
+} | null>;

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

@@ -0,0 +1,170 @@
+import path from 'path';
+import fs from 'fs';
+import { resolvePageFile, extractRouteParams } from './plugins/vite-plugin-loaders.js';
+import { stripOuterLitMarkers, dirToLayoutTagName, findTagName } from '../shared/utils.js';
+import { installDomShims } from '../shared/dom-shims.js';
+/**
+ * Server-side render a LumenJS page using @lit-labs/ssr.
+ * Wraps the page in its layout chain if layouts exist.
+ *
+ * Returns pre-rendered HTML and loader data, or null on failure (falls back to CSR).
+ */
+export async function ssrRenderPage(server, pagesDir, pathname, headers) {
+    try {
+        const filePath = resolvePageFile(pagesDir, pathname);
+        if (!filePath)
+            return null;
+        const params = extractRouteParams(pagesDir, pathname, filePath);
+        // Install @lit-labs/ssr DOM shim via Vite's SSR module loader
+        await server.ssrLoadModule('@lit-labs/ssr/lib/install-global-dom-shim.js');
+        // Patch missing DOM APIs that NuralyUI components may use during SSR
+        installDomShims();
+        // 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.
+        const g = globalThis;
+        invalidateSsrModule(server, filePath);
+        clearSsrCustomElement(g);
+        // Load the page module via Vite (registers the custom element, applies transforms)
+        const mod = await server.ssrLoadModule(filePath);
+        // Run loader if present
+        let loaderData = undefined;
+        if (mod.loader && typeof mod.loader === 'function') {
+            loaderData = await mod.loader({ params, query: {}, url: pathname, headers: headers || {} });
+            if (loaderData && typeof loaderData === 'object' && loaderData.__nk_redirect) {
+                return { html: '', loaderData: null, redirect: { location: loaderData.location, status: loaderData.status || 302 } };
+            }
+        }
+        // Determine the custom element tag name
+        const tagName = findTagName(mod);
+        if (!tagName)
+            return null;
+        // Discover layout chain for this page
+        const layoutChain = discoverLayoutChain(pagesDir, filePath);
+        const layoutsData = [];
+        // Load layout modules and run their loaders
+        const layoutModules = [];
+        for (const layout of layoutChain) {
+            // Invalidate layout module cache and clear SSR element registry
+            invalidateSsrModule(server, layout.filePath);
+            clearSsrCustomElement(g);
+            const layoutMod = await server.ssrLoadModule(layout.filePath);
+            let layoutLoaderData = undefined;
+            if (layoutMod.loader && typeof layoutMod.loader === 'function') {
+                layoutLoaderData = await layoutMod.loader({ params: {}, query: {}, url: pathname, headers: headers || {} });
+                if (layoutLoaderData && typeof layoutLoaderData === 'object' && layoutLoaderData.__nk_redirect) {
+                    return { html: '', loaderData: null, redirect: { location: layoutLoaderData.location, status: layoutLoaderData.status || 302 } };
+                }
+            }
+            const layoutTagName = dirToLayoutTagName(layout.dir);
+            layoutModules.push({ tagName: layoutTagName, loaderData: layoutLoaderData });
+            layoutsData.push({ loaderPath: layout.dir, data: layoutLoaderData });
+        }
+        // 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');
+        // Render each element separately to avoid nesting Lit template markers.
+        const pageTag = unsafeStatic(tagName);
+        const pageTemplate = html `<${pageTag} .loaderData=${loaderData}></${pageTag}>`;
+        let pageHtml = '';
+        for (const chunk of render(pageTemplate)) {
+            pageHtml += typeof chunk === 'string' ? chunk : String(chunk);
+        }
+        pageHtml = stripOuterLitMarkers(pageHtml);
+        let htmlStr = pageHtml;
+        for (let i = layoutModules.length - 1; i >= 0; i--) {
+            const layoutTag = unsafeStatic(layoutModules[i].tagName);
+            const layoutData = layoutModules[i].loaderData;
+            const layoutTemplate = html `<${layoutTag} .loaderData=${layoutData}></${layoutTag}>`;
+            let layoutHtml = '';
+            for (const chunk of render(layoutTemplate)) {
+                layoutHtml += typeof chunk === 'string' ? chunk : String(chunk);
+            }
+            if (i > 0) {
+                layoutHtml = stripOuterLitMarkers(layoutHtml);
+            }
+            const closingTag = `</${layoutModules[i].tagName}>`;
+            const closingIdx = layoutHtml.lastIndexOf(closingTag);
+            if (closingIdx !== -1) {
+                htmlStr = layoutHtml.slice(0, closingIdx) + htmlStr + layoutHtml.slice(closingIdx);
+            }
+            else {
+                htmlStr = layoutHtml + htmlStr;
+            }
+        }
+        return { html: htmlStr, loaderData, layoutsData: layoutsData.length > 0 ? layoutsData : undefined };
+    }
+    catch (err) {
+        console.error('[LumenJS] SSR render failed, falling back to CSR:', err);
+        return null;
+    }
+}
+/**
+ * Discover layout files for a given page, from root → deepest directory.
+ */
+function discoverLayoutChain(pagesDir, pageFilePath) {
+    const relativeToPages = path.relative(pagesDir, pageFilePath).replace(/\\/g, '/');
+    const dirParts = path.dirname(relativeToPages).split('/').filter(p => p && p !== '.');
+    const chain = [];
+    // Check root layout
+    const rootLayout = findLayoutFile(pagesDir);
+    if (rootLayout)
+        chain.push({ dir: '', filePath: rootLayout });
+    // Check each directory level
+    let currentDir = pagesDir;
+    let relDir = '';
+    for (const part of dirParts) {
+        currentDir = path.join(currentDir, part);
+        relDir = relDir ? `${relDir}/${part}` : part;
+        const layoutFile = findLayoutFile(currentDir);
+        if (layoutFile)
+            chain.push({ dir: relDir, filePath: layoutFile });
+    }
+    return chain;
+}
+function findLayoutFile(dir) {
+    for (const ext of ['.ts', '.js']) {
+        const p = path.join(dir, `_layout${ext}`);
+        if (fs.existsSync(p))
+            return p;
+    }
+    return null;
+}
+/**
+ * Aggressively invalidate a module for SSR re-execution.
+ */
+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 urlMod = server.moduleGraph.getModuleById(filePath);
+    if (urlMod) {
+        server.moduleGraph.invalidateModule(urlMod);
+        urlMod.ssrModule = null;
+        urlMod.ssrTransformResult = null;
+    }
+}
+/**
+ * Patch the SSR customElements registry to allow re-registration.
+ */
+function clearSsrCustomElement(g) {
+    const registry = g.customElements;
+    if (!registry || registry.__nk_patched)
+        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);
+            }
+        }
+        return origDefine(name, ctor);
+    };
+}

package/dist/editor/click-select.d.ts

@@ -0,0 +1 @@
+export declare function setupClickToSelect(): void;

package/dist/editor/click-select.js

@@ -0,0 +1,46 @@
+import { findAnnotatedElement } from './element-annotator.js';
+import { sendToHost, getElementAttributes, getDynamicTexts, serializeRect, isPreviewMode } from './editor-bridge.js';
+export function setupClickToSelect() {
+    let clickTimer = null;
+    let lastClickResult = null;
+    document.addEventListener('click', (event) => {
+        if (isPreviewMode())
+            return;
+        const result = findAnnotatedElement(event);
+        if (!result)
+            return;
+        event.preventDefault();
+        event.stopPropagation();
+        // Delay dispatch to distinguish single-click from double-click
+        lastClickResult = result;
+        if (clickTimer)
+            clearTimeout(clickTimer);
+        clickTimer = setTimeout(() => {
+            if (!lastClickResult)
+                return;
+            sendToHost({
+                type: 'NK_ELEMENT_CLICKED',
+                payload: {
+                    sourceFile: lastClickResult.source.file,
+                    line: lastClickResult.source.line,
+                    tag: lastClickResult.source.tag,
+                    attributes: getElementAttributes(lastClickResult.element),
+                    nkId: lastClickResult.element.getAttribute('data-nk-id'),
+                    rect: serializeRect(lastClickResult.element.getBoundingClientRect()),
+                    dynamicTexts: getDynamicTexts(lastClickResult.element),
+                }
+            });
+            lastClickResult = null;
+        }, 250);
+    }, true);
+    document.addEventListener('dblclick', (event) => {
+        if (isPreviewMode())
+            return;
+        // Cancel the pending single-click
+        if (clickTimer) {
+            clearTimeout(clickTimer);
+            clickTimer = null;
+        }
+        lastClickResult = null;
+    }, true);
+}

package/dist/editor/editor-bridge.d.ts

@@ -0,0 +1,17 @@
+export interface NkEditorMessage {
+    type: 'NK_READY' | 'NK_ELEMENT_CLICKED' | 'NK_ELEMENT_HOVERED' | 'NK_SELECT_ELEMENT' | 'NK_HIGHLIGHT_ELEMENT' | 'NK_TEXT_CHANGED' | 'NK_SET_PREVIEW_MODE';
+    payload?: any;
+}
+export declare function isPreviewMode(): boolean;
+export declare function sendToHost(message: NkEditorMessage): void;
+export declare function getElementAttributes(el: HTMLElement): Record<string, string>;
+export declare function getDynamicTexts(el: HTMLElement): Array<{
+    tag: string;
+    expression: string;
+}>;
+export declare function serializeRect(rect: DOMRect): {
+    top: number;
+    left: number;
+    width: number;
+    height: number;
+};

package/dist/editor/editor-bridge.js

@@ -0,0 +1,101 @@
+/**
+ * LumenJS Editor Bridge — injected in editor mode.
+ *
+ * Handles click/hover detection on elements and communicates with the
+ * Studio host via postMessage. Follows the pattern from preview-iframe-bridge.ts.
+ */
+import { startAnnotator } from './element-annotator.js';
+import { setupClickToSelect } from './click-select.js';
+import { setupHoverDetection } from './hover-detect.js';
+import { setupInlineTextEdit } from './inline-text-edit.js';
+let previewMode = false;
+export function isPreviewMode() {
+    return previewMode;
+}
+export function sendToHost(message) {
+    if (window.parent && window.parent !== window) {
+        window.parent.postMessage(message, '*');
+    }
+}
+export function getElementAttributes(el) {
+    const attrs = {};
+    for (const attr of Array.from(el.attributes)) {
+        if (!attr.name.startsWith('data-nk-')) {
+            attrs[attr.name] = attr.value;
+        }
+    }
+    return attrs;
+}
+export function getDynamicTexts(el) {
+    const results = [];
+    const roots = [el];
+    if (el.shadowRoot)
+        roots.push(el.shadowRoot);
+    for (const root of roots) {
+        root.querySelectorAll('[data-nk-dynamic]').forEach((child) => {
+            const raw = child.getAttribute('data-nk-dynamic') || '';
+            if (raw) {
+                const expression = raw.replace(/__NK_EXPR__/g, '${');
+                results.push({ tag: child.tagName.toLowerCase(), expression });
+            }
+        });
+    }
+    return results;
+}
+export function serializeRect(rect) {
+    return { top: rect.top, left: rect.left, width: rect.width, height: rect.height };
+}
+function handleHostMessage(event) {
+    const message = event.data;
+    if (!message || typeof message !== 'object' || !message.type)
+        return;
+    switch (message.type) {
+        case 'NK_SELECT_ELEMENT': {
+            const { sourceFile, line } = message.payload || {};
+            const el = document.querySelector(`[data-nk-source="${sourceFile}:${line}"]`);
+            if (el instanceof HTMLElement) {
+                el.scrollIntoView({ behavior: 'smooth', block: 'center' });
+                el.style.outline = '2px solid #3b82f6';
+                setTimeout(() => { el.style.outline = ''; }, 2000);
+            }
+            break;
+        }
+        case 'NK_HIGHLIGHT_ELEMENT': {
+            document.querySelectorAll('[data-nk-highlight]').forEach(el => {
+                el.removeAttribute('data-nk-highlight');
+                el.style.outline = '';
+            });
+            if (message.payload) {
+                const { sourceFile, line } = message.payload;
+                const el = document.querySelector(`[data-nk-source="${sourceFile}:${line}"]`);
+                if (el instanceof HTMLElement) {
+                    el.setAttribute('data-nk-highlight', 'true');
+                    el.style.outline = '1px dashed #3b82f6';
+                }
+            }
+            break;
+        }
+        case 'NK_SET_PREVIEW_MODE': {
+            previewMode = !!message.payload;
+            document.body.style.cursor = previewMode ? '' : 'default';
+            break;
+        }
+    }
+}
+function initEditorBridge() {
+    if (window.self === window.top)
+        return; // Not in iframe
+    startAnnotator();
+    setupClickToSelect();
+    setupHoverDetection();
+    setupInlineTextEdit();
+    window.addEventListener('message', handleHostMessage);
+    sendToHost({ type: 'NK_READY' });
+}
+// Auto-init
+if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', initEditorBridge);
+}
+else {
+    initEditorBridge();
+}

package/dist/editor/element-annotator.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Element Annotator — adds `data-nk-source` attributes to rendered Lit elements.
+ *
+ * In editor mode, this module observes the DOM for custom elements (those with a tag
+ * containing a hyphen) and annotates them with source file and line info so the
+ * editor bridge can map clicks back to source code.
+ *
+ * Source mapping relies on the `data-nk-source` attribute format: "file:line"
+ * This attribute is injected by a Vite transform or manually by the framework.
+ */
+interface SourceInfo {
+    file: string;
+    line: number;
+    tag: string;
+}
+/**
+ * Parse a data-nk-source attribute value. Format: "file:line"
+ */
+export declare function parseSourceAttr(value: string): SourceInfo | null;
+/**
+ * Find the closest element with a data-nk-source attribute from an event.
+ * Traverses composed path for Shadow DOM support.
+ */
+export declare function findAnnotatedElement(event: Event): {
+    element: HTMLElement;
+    source: SourceInfo;
+} | null;
+/**
+ * Start observing the DOM and annotate custom elements with sequential IDs.
+ * This helps the editor uniquely identify elements for AST modifications.
+ */
+export declare function startAnnotator(): void;
+export {};

package/dist/editor/element-annotator.js

@@ -0,0 +1,83 @@
+/**
+ * Element Annotator — adds `data-nk-source` attributes to rendered Lit elements.
+ *
+ * In editor mode, this module observes the DOM for custom elements (those with a tag
+ * containing a hyphen) and annotates them with source file and line info so the
+ * editor bridge can map clicks back to source code.
+ *
+ * Source mapping relies on the `data-nk-source` attribute format: "file:line"
+ * This attribute is injected by a Vite transform or manually by the framework.
+ */
+let annotatorActive = false;
+/**
+ * Parse a data-nk-source attribute value. Format: "file:line"
+ */
+export function parseSourceAttr(value) {
+    const lastColon = value.lastIndexOf(':');
+    if (lastColon === -1)
+        return null;
+    const file = value.substring(0, lastColon);
+    const line = parseInt(value.substring(lastColon + 1), 10);
+    if (isNaN(line))
+        return null;
+    return { file, line, tag: '' };
+}
+/**
+ * Find the closest element with a data-nk-source attribute from an event.
+ * Traverses composed path for Shadow DOM support.
+ */
+export function findAnnotatedElement(event) {
+    const composedPath = event.composedPath();
+    for (const node of composedPath) {
+        if (!(node instanceof HTMLElement))
+            continue;
+        const sourceAttr = node.getAttribute('data-nk-source');
+        if (sourceAttr) {
+            const source = parseSourceAttr(sourceAttr);
+            if (source) {
+                source.tag = node.tagName.toLowerCase();
+                return { element: node, source };
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Start observing the DOM and annotate custom elements with sequential IDs.
+ * This helps the editor uniquely identify elements for AST modifications.
+ */
+export function startAnnotator() {
+    if (annotatorActive)
+        return;
+    annotatorActive = true;
+    let idCounter = 0;
+    const observer = new MutationObserver((mutations) => {
+        for (const mutation of mutations) {
+            for (const node of mutation.addedNodes) {
+                if (node instanceof HTMLElement) {
+                    annotateTree(node);
+                }
+            }
+        }
+    });
+    function annotateTree(root) {
+        // Annotate the root if it's a custom element without an ID
+        if (root.tagName.includes('-') && !root.hasAttribute('data-nk-id')) {
+            root.setAttribute('data-nk-id', `nk-${idCounter++}`);
+        }
+        // Walk children
+        const walker = document.createTreeWalker(root, NodeFilter.SHOW_ELEMENT);
+        let current = walker.nextNode();
+        while (current) {
+            const el = current;
+            if (el.tagName.includes('-') && !el.hasAttribute('data-nk-id')) {
+                el.setAttribute('data-nk-id', `nk-${idCounter++}`);
+            }
+            current = walker.nextNode();
+        }
+    }
+    // Annotate existing elements
+    annotateTree(document.body);
+    // Watch for new elements
+    observer.observe(document.body, { childList: true, subtree: true });
+}

package/dist/editor/hover-detect.d.ts

@@ -0,0 +1 @@
+export declare function setupHoverDetection(): void;