@nuraly/lumenjs 0.1.3 → 0.1.4

package/dist/shared/llms-txt.d.ts

@@ -0,0 +1,31 @@
+interface LlmsTxtPage {
+    path: string;
+    hasLoader: boolean;
+    hasSubscribe: boolean;
+    hasSocket: boolean;
+}
+interface LlmsTxtApiRoute {
+    path: string;
+    methods: string[];
+}
+interface LlmsTxtConfig {
+    title: string;
+    integrations: string[];
+    i18n?: {
+        locales: string[];
+        defaultLocale: string;
+    };
+}
+/**
+ * Generate the /llms.txt content for a LumenJS project.
+ */
+export declare function generateLlmsTxt(options: {
+    pages: LlmsTxtPage[];
+    apiRoutes: LlmsTxtApiRoute[];
+    config: LlmsTxtConfig;
+}): string;
+/**
+ * Detect exported HTTP methods from an API route file.
+ */
+export declare function detectApiMethods(filePath: string): string[];
+export {};

package/dist/shared/llms-txt.js

@@ -0,0 +1,85 @@
+import fs from 'fs';
+const HTTP_METHODS = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'];
+/**
+ * Generate the /llms.txt content for a LumenJS project.
+ */
+export function generateLlmsTxt(options) {
+    const { pages, apiRoutes, config } = options;
+    const lines = [];
+    lines.push(`# ${config.title}`);
+    lines.push('');
+    lines.push('> Built with LumenJS');
+    lines.push('');
+    // Pages section
+    if (pages.length > 0) {
+        lines.push('## Pages');
+        lines.push('');
+        for (const page of pages) {
+            lines.push(`### ${page.path}`);
+            const traits = [];
+            if (page.hasLoader)
+                traits.push('server loader');
+            if (page.hasSubscribe)
+                traits.push('live data (SSE)');
+            if (page.hasSocket)
+                traits.push('socket (bidirectional)');
+            if (page.path.includes(':'))
+                traits.push('dynamic route');
+            if (traits.length > 0) {
+                lines.push(`- ${traits.join(', ')}`);
+            }
+            lines.push('');
+        }
+    }
+    // API routes section
+    if (apiRoutes.length > 0) {
+        lines.push('## API Routes');
+        lines.push('');
+        for (const route of apiRoutes) {
+            for (const method of route.methods) {
+                const fullPath = route.path.startsWith('/api') ? route.path : `/api${route.path}`;
+                lines.push(`- ${method} ${fullPath}`);
+            }
+        }
+        lines.push('');
+    }
+    // Features section
+    const features = [];
+    if (config.i18n) {
+        features.push(`Internationalization (${config.i18n.locales.join(', ')})`);
+    }
+    if (config.integrations.includes('tailwind'))
+        features.push('Tailwind CSS');
+    if (config.integrations.includes('nuralyui'))
+        features.push('NuralyUI Components');
+    if (config.integrations.includes('socketio'))
+        features.push('Socket.IO');
+    if (features.length > 0) {
+        lines.push('## Features');
+        lines.push('');
+        for (const f of features) {
+            lines.push(`- ${f}`);
+        }
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+/**
+ * Detect exported HTTP methods from an API route file.
+ */
+export function detectApiMethods(filePath) {
+    try {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const methods = [];
+        for (const method of HTTP_METHODS) {
+            const regex = new RegExp(`export\\s+(async\\s+)?function\\s+${method}\\s*\\(`);
+            if (regex.test(content)) {
+                methods.push(method);
+            }
+        }
+        return methods;
+    }
+    catch {
+        return [];
+    }
+}

package/dist/shared/logger.d.ts

@@ -0,0 +1,32 @@
+import { IncomingMessage } from 'http';
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+export interface LogEntry {
+    level: LogLevel;
+    msg: string;
+    timestamp: string;
+    [key: string]: unknown;
+}
+export interface LoggerOptions {
+    level?: LogLevel;
+    json?: boolean;
+}
+export declare function configureLogger(opts: LoggerOptions): void;
+export declare const logger: {
+    debug: (msg: string, extra?: Record<string, unknown>) => void;
+    info: (msg: string, extra?: Record<string, unknown>) => void;
+    warn: (msg: string, extra?: Record<string, unknown>) => void;
+    error: (msg: string, extra?: Record<string, unknown>) => void;
+    fatal: (msg: string, extra?: Record<string, unknown>) => void;
+    /** Create a child logger with preset extra fields (e.g. requestId). */
+    child(fields: Record<string, unknown>): {
+        debug: (msg: string, extra?: Record<string, unknown>) => void;
+        info: (msg: string, extra?: Record<string, unknown>) => void;
+        warn: (msg: string, extra?: Record<string, unknown>) => void;
+        error: (msg: string, extra?: Record<string, unknown>) => void;
+        fatal: (msg: string, extra?: Record<string, unknown>) => void;
+    };
+    /** Log an HTTP request completion. */
+    request(req: IncomingMessage, statusCode: number, durationMs: number, extra?: Record<string, unknown>): void;
+};
+/** Auto-configure from environment. Call once at startup. */
+export declare function initLogger(): void;

package/dist/shared/logger.js

@@ -0,0 +1,93 @@
+const LEVEL_VALUES = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+    fatal: 4,
+};
+const LEVEL_COLORS = {
+    debug: '\x1b[36m', // cyan
+    info: '\x1b[32m', // green
+    warn: '\x1b[33m', // yellow
+    error: '\x1b[31m', // red
+    fatal: '\x1b[35m', // magenta
+};
+const RESET = '\x1b[0m';
+const DIM = '\x1b[2m';
+let globalLevel = 'info';
+let globalJson = false;
+export function configureLogger(opts) {
+    if (opts.level)
+        globalLevel = opts.level;
+    if (opts.json !== undefined)
+        globalJson = opts.json;
+}
+function shouldLog(level) {
+    return LEVEL_VALUES[level] >= LEVEL_VALUES[globalLevel];
+}
+function formatJson(entry) {
+    return JSON.stringify(entry);
+}
+function formatPretty(entry) {
+    const { level, msg, timestamp, ...extra } = entry;
+    const color = LEVEL_COLORS[level];
+    const ts = `${DIM}${timestamp}${RESET}`;
+    const lvl = `${color}${level.toUpperCase().padEnd(5)}${RESET}`;
+    const extraStr = Object.keys(extra).length > 0
+        ? ` ${DIM}${JSON.stringify(extra)}${RESET}`
+        : '';
+    return `${ts} ${lvl} ${msg}${extraStr}`;
+}
+function log(level, msg, extra) {
+    if (!shouldLog(level))
+        return;
+    const entry = {
+        level,
+        msg,
+        timestamp: new Date().toISOString(),
+        ...extra,
+    };
+    const formatted = globalJson ? formatJson(entry) : formatPretty(entry);
+    if (level === 'error' || level === 'fatal') {
+        process.stderr.write(formatted + '\n');
+    }
+    else {
+        process.stdout.write(formatted + '\n');
+    }
+}
+export const logger = {
+    debug: (msg, extra) => log('debug', msg, extra),
+    info: (msg, extra) => log('info', msg, extra),
+    warn: (msg, extra) => log('warn', msg, extra),
+    error: (msg, extra) => log('error', msg, extra),
+    fatal: (msg, extra) => log('fatal', msg, extra),
+    /** Create a child logger with preset extra fields (e.g. requestId). */
+    child(fields) {
+        return {
+            debug: (msg, extra) => log('debug', msg, { ...fields, ...extra }),
+            info: (msg, extra) => log('info', msg, { ...fields, ...extra }),
+            warn: (msg, extra) => log('warn', msg, { ...fields, ...extra }),
+            error: (msg, extra) => log('error', msg, { ...fields, ...extra }),
+            fatal: (msg, extra) => log('fatal', msg, { ...fields, ...extra }),
+        };
+    },
+    /** Log an HTTP request completion. */
+    request(req, statusCode, durationMs, extra) {
+        const level = statusCode >= 500 ? 'error' : statusCode >= 400 ? 'warn' : 'info';
+        log(level, `${req.method} ${req.url} ${statusCode} ${durationMs}ms`, {
+            method: req.method,
+            url: req.url,
+            status: statusCode,
+            duration: durationMs,
+            ...extra,
+        });
+    },
+};
+/** Auto-configure from environment. Call once at startup. */
+export function initLogger() {
+    const isProd = process.env.NODE_ENV === 'production';
+    configureLogger({
+        level: process.env.LOG_LEVEL || (isProd ? 'info' : 'debug'),
+        json: process.env.LOG_FORMAT === 'json' || isProd,
+    });
+}

package/dist/shared/meta.d.ts

@@ -0,0 +1,27 @@
+export interface PageMeta {
+    title?: string;
+    description?: string;
+    image?: string;
+    canonical?: string;
+    robots?: string;
+    type?: string;
+}
+export interface MetaTagOptions {
+    siteTitle?: string;
+    url?: string;
+    locale?: string;
+    i18nConfig?: {
+        locales: string[];
+        defaultLocale: string;
+        prefixDefault: boolean;
+    };
+}
+/**
+ * Generate HTML meta tags from a PageMeta object.
+ * Returns a string of HTML tags to inject into <head>.
+ */
+export declare function generateMetaTags(meta: PageMeta, options?: MetaTagOptions): string;
+/**
+ * Compute the full page title with optional site title suffix.
+ */
+export declare function computeTitle(meta: PageMeta | undefined, siteTitle: string): string;

package/dist/shared/meta.js

@@ -0,0 +1,71 @@
+import { escapeHtml } from './utils.js';
+/**
+ * Generate HTML meta tags from a PageMeta object.
+ * Returns a string of HTML tags to inject into <head>.
+ */
+export function generateMetaTags(meta, options) {
+    const tags = [];
+    const ogType = meta.type || 'website';
+    // og:type is always emitted
+    tags.push(`<meta property="og:type" content="${escapeHtml(ogType)}">`);
+    if (meta.description) {
+        tags.push(`<meta name="description" content="${escapeHtml(meta.description)}">`);
+        tags.push(`<meta property="og:description" content="${escapeHtml(meta.description)}">`);
+    }
+    if (meta.title) {
+        const fullTitle = options?.siteTitle ? `${meta.title} | ${options.siteTitle}` : meta.title;
+        tags.push(`<meta property="og:title" content="${escapeHtml(fullTitle)}">`);
+    }
+    if (meta.image) {
+        tags.push(`<meta property="og:image" content="${escapeHtml(meta.image)}">`);
+        tags.push(`<meta name="twitter:card" content="summary_large_image">`);
+        tags.push(`<meta name="twitter:image" content="${escapeHtml(meta.image)}">`);
+    }
+    if (meta.robots) {
+        tags.push(`<meta name="robots" content="${escapeHtml(meta.robots)}">`);
+    }
+    if (options?.url) {
+        tags.push(`<meta property="og:url" content="${escapeHtml(options.url)}">`);
+    }
+    if (options?.locale) {
+        tags.push(`<meta property="og:locale" content="${escapeHtml(options.locale)}">`);
+    }
+    // Canonical URL
+    const canonicalUrl = meta.canonical || options?.url;
+    if (canonicalUrl) {
+        tags.push(`<link rel="canonical" href="${escapeHtml(canonicalUrl)}">`);
+    }
+    // hreflang tags for i18n
+    if (options?.i18nConfig && options.url) {
+        const { locales, defaultLocale, prefixDefault } = options.i18nConfig;
+        // Strip any existing locale prefix to get the base path
+        let basePath = options.url;
+        for (const loc of locales) {
+            if (basePath.startsWith(`/${loc}/`) || basePath === `/${loc}`) {
+                basePath = basePath.slice(loc.length + 1) || '/';
+                break;
+            }
+        }
+        for (const loc of locales) {
+            const href = (loc === defaultLocale && !prefixDefault)
+                ? basePath
+                : `/${loc}${basePath === '/' ? '' : basePath}`;
+            tags.push(`<link rel="alternate" hreflang="${escapeHtml(loc)}" href="${escapeHtml(href)}">`);
+        }
+        // x-default points to the default locale URL
+        const xDefaultHref = prefixDefault
+            ? `/${defaultLocale}${basePath === '/' ? '' : basePath}`
+            : basePath;
+        tags.push(`<link rel="alternate" hreflang="x-default" href="${escapeHtml(xDefaultHref)}">`);
+    }
+    return tags.join('\n  ');
+}
+/**
+ * Compute the full page title with optional site title suffix.
+ */
+export function computeTitle(meta, siteTitle) {
+    if (meta?.title) {
+        return `${meta.title} | ${siteTitle}`;
+    }
+    return siteTitle;
+}

package/dist/shared/middleware-runner.d.ts

@@ -0,0 +1,9 @@
+export type ConnectMiddleware = (req: any, res: any, next: (err?: any) => void) => void;
+/**
+ * Chain Connect-style (req, res, next) middleware functions sequentially.
+ */
+export declare function runMiddlewareChain(middlewares: ConnectMiddleware[], req: any, res: any, done: (err?: any) => void): void;
+/**
+ * Validate and extract middleware array from a module's default export.
+ */
+export declare function extractMiddleware(mod: any): ConnectMiddleware[];

package/dist/shared/middleware-runner.js

@@ -0,0 +1,29 @@
+/**
+ * Chain Connect-style (req, res, next) middleware functions sequentially.
+ */
+export function runMiddlewareChain(middlewares, req, res, done) {
+    let index = 0;
+    function next(err) {
+        if (err)
+            return done(err);
+        if (index >= middlewares.length)
+            return done();
+        const mw = middlewares[index++];
+        try {
+            mw(req, res, next);
+        }
+        catch (e) {
+            done(e);
+        }
+    }
+    next();
+}
+/**
+ * Validate and extract middleware array from a module's default export.
+ */
+export function extractMiddleware(mod) {
+    const arr = mod?.default ?? mod;
+    if (!Array.isArray(arr))
+        return [];
+    return arr.filter((fn) => typeof fn === 'function');
+}

package/dist/shared/rate-limit.d.ts

@@ -0,0 +1,18 @@
+import type { IncomingMessage, ServerResponse } from 'http';
+export interface RateLimitConfig {
+    /** Time window in milliseconds. Default: 60000 (1 minute). */
+    windowMs?: number;
+    /** Max requests per window. Default: 100. */
+    max?: number;
+    /** Custom key generator. Default: IP address. */
+    keyGenerator?: (req: IncomingMessage) => string;
+    /** Paths to skip rate limiting. Default: static assets. */
+    skip?: (req: IncomingMessage) => boolean;
+    /** HTTP status code when rate limited. Default: 429. */
+    statusCode?: number;
+    /** Message sent when rate limited. */
+    message?: string;
+}
+export declare function createRateLimiter(config?: RateLimitConfig): (req: IncomingMessage, res: ServerResponse, next: (err?: any) => void) => void;
+/** Stricter rate limiter preset for auth endpoints (20 req/min). */
+export declare function createAuthRateLimiter(overrides?: Partial<RateLimitConfig>): (req: IncomingMessage, res: ServerResponse, next: (err?: any) => void) => void;

package/dist/shared/rate-limit.js

@@ -0,0 +1,71 @@
+const DEFAULT_CONFIG = {
+    windowMs: 60_000,
+    max: 2000,
+    keyGenerator: (req) => {
+        // Uses X-Forwarded-For when behind a trusted reverse proxy.
+        // If directly internet-facing, override keyGenerator to use req.socket.remoteAddress only.
+        return req.headers['x-forwarded-for']?.split(',')[0]?.trim()
+            || req.socket.remoteAddress
+            || 'unknown';
+    },
+    skip: (req) => {
+        const url = req.url || '';
+        return url.includes('.') && !url.startsWith('/api/');
+    },
+    statusCode: 429,
+    message: 'Too many requests, please try again later.',
+};
+export function createRateLimiter(config) {
+    const opts = { ...DEFAULT_CONFIG, ...config };
+    const buckets = new Map();
+    const refillRate = opts.max / opts.windowMs; // tokens per ms
+    // Cleanup stale entries every 5 minutes
+    const cleanupInterval = setInterval(() => {
+        const now = Date.now();
+        for (const [key, bucket] of buckets) {
+            if (now - bucket.lastRefill > opts.windowMs * 2) {
+                buckets.delete(key);
+            }
+        }
+    }, 5 * 60_000);
+    cleanupInterval.unref();
+    return (req, res, next) => {
+        if (opts.skip(req))
+            return next();
+        const key = opts.keyGenerator(req);
+        const now = Date.now();
+        let bucket = buckets.get(key);
+        if (!bucket) {
+            bucket = { tokens: opts.max, lastRefill: now };
+            buckets.set(key, bucket);
+        }
+        // Refill tokens based on elapsed time
+        const elapsed = now - bucket.lastRefill;
+        bucket.tokens = Math.min(opts.max, bucket.tokens + elapsed * refillRate);
+        bucket.lastRefill = now;
+        if (bucket.tokens < 1) {
+            const retryAfter = Math.ceil((1 - bucket.tokens) / refillRate / 1000);
+            res.writeHead(opts.statusCode, {
+                'Content-Type': 'application/json',
+                'Retry-After': String(retryAfter),
+                'X-RateLimit-Limit': String(opts.max),
+                'X-RateLimit-Remaining': '0',
+            });
+            res.end(JSON.stringify({ error: opts.message }));
+            return;
+        }
+        bucket.tokens -= 1;
+        res.setHeader('X-RateLimit-Limit', String(opts.max));
+        res.setHeader('X-RateLimit-Remaining', String(Math.floor(bucket.tokens)));
+        next();
+    };
+}
+/** Stricter rate limiter preset for auth endpoints (20 req/min). */
+export function createAuthRateLimiter(overrides) {
+    return createRateLimiter({
+        windowMs: 60_000,
+        max: 20,
+        skip: () => false,
+        ...overrides,
+    });
+}

package/dist/shared/request-id.d.ts

@@ -0,0 +1,5 @@
+import type { IncomingMessage, ServerResponse } from 'http';
+/** Attach a unique request ID to each request. Reuses incoming X-Request-ID if present. */
+export declare function createRequestIdMiddleware(): (req: IncomingMessage, res: ServerResponse, next: (err?: any) => void) => void;
+/** Get the request ID from a request object. */
+export declare function getRequestId(req: IncomingMessage): string | undefined;

package/dist/shared/request-id.js

@@ -0,0 +1,18 @@
+import { randomUUID } from 'crypto';
+const REQUEST_ID_HEADER = 'x-request-id';
+/** Attach a unique request ID to each request. Reuses incoming X-Request-ID if present. */
+export function createRequestIdMiddleware() {
+    return (req, res, next) => {
+        const existing = req.headers[REQUEST_ID_HEADER];
+        const requestId = (typeof existing === 'string' && existing) || randomUUID();
+        // Attach to request for downstream use
+        req.id = requestId;
+        // Echo back in response
+        res.setHeader('X-Request-ID', requestId);
+        next();
+    };
+}
+/** Get the request ID from a request object. */
+export function getRequestId(req) {
+    return req.id;
+}

package/dist/shared/route-matching.js

@@ -1,11 +1,26 @@
+function routeSpecificity(route) {
+    // Higher score = more specific = checked first.
+    // Each static segment adds 2, each dynamic segment adds 1, catch-all adds 0.
+    return route.path.replace(/^\//, '').split('/').filter(Boolean).reduce((score, seg) => {
+        if (seg.startsWith(':...'))
+            return score + 0;
+        if (seg.startsWith(':'))
+            return score + 1;
+        return score + 2;
+    }, 0);
+}
 export function matchRoute(routes, pathname) {
     const urlSegments = pathname.replace(/^\//, '').split('/').filter(Boolean);
-    for (const route of routes) {
+    const sorted = [...routes].sort((a, b) => routeSpecificity(b) - routeSpecificity(a));
+    for (const route of sorted) {
         const routeSegments = route.path.replace(/^\//, '').split('/').filter(Boolean);
         // Handle root route
         if (route.path === '/' && (pathname === '/' || pathname === '')) {
             return { route, params: {} };
         }
+        // Non-root routes with no segments can't match a non-empty pathname
+        if (routeSegments.length === 0 && urlSegments.length > 0)
+            continue;
         const params = {};
         let match = true;
         for (let i = 0; i < routeSegments.length; i++) {

package/dist/shared/security-headers.d.ts

@@ -0,0 +1,18 @@
+import type { IncomingMessage, ServerResponse } from 'http';
+export interface SecurityHeadersConfig {
+    /** Content-Security-Policy. Set to false to disable. */
+    contentSecurityPolicy?: string | false;
+    /** X-Frame-Options. Default: 'DENY'. Set to false to disable. */
+    frameOptions?: 'DENY' | 'SAMEORIGIN' | false;
+    /** X-Content-Type-Options: nosniff. Default: true. */
+    noSniff?: boolean;
+    /** Strict-Transport-Security. Default: 'max-age=31536000; includeSubDomains'. Set to false to disable. */
+    hsts?: string | false;
+    /** Referrer-Policy. Default: 'strict-origin-when-cross-origin'. Set to false to disable. */
+    referrerPolicy?: string | false;
+    /** Permissions-Policy. Default restricts camera, microphone, geolocation. Set to false to disable. */
+    permissionsPolicy?: string | false;
+    /** Cross-Origin-Opener-Policy. Default: 'same-origin'. Set to false to disable. */
+    crossOriginOpenerPolicy?: string | false;
+}
+export declare function createSecurityHeadersMiddleware(config?: SecurityHeadersConfig): (_req: IncomingMessage, res: ServerResponse, next: (err?: any) => void) => void;

package/dist/shared/security-headers.js

@@ -0,0 +1,38 @@
+const DEFAULTS = {
+    // Note: 'unsafe-inline' for script-src is required for Lit's template system.
+    // Override via securityHeaders config in lumenjs.config.ts for stricter policies.
+    contentSecurityPolicy: "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net; img-src 'self' data: blob: https:; font-src 'self' data: https://cdn.jsdelivr.net; connect-src 'self' ws: wss:; frame-ancestors 'none'",
+    frameOptions: 'DENY',
+    noSniff: true,
+    hsts: 'max-age=31536000; includeSubDomains',
+    referrerPolicy: 'strict-origin-when-cross-origin',
+    permissionsPolicy: 'camera=(), microphone=(), geolocation=()',
+    crossOriginOpenerPolicy: 'same-origin',
+};
+export function createSecurityHeadersMiddleware(config) {
+    const opts = { ...DEFAULTS, ...config };
+    return (_req, res, next) => {
+        if (opts.contentSecurityPolicy !== false) {
+            res.setHeader('Content-Security-Policy', opts.contentSecurityPolicy);
+        }
+        if (opts.frameOptions !== false) {
+            res.setHeader('X-Frame-Options', opts.frameOptions);
+        }
+        if (opts.noSniff) {
+            res.setHeader('X-Content-Type-Options', 'nosniff');
+        }
+        if (opts.hsts !== false) {
+            res.setHeader('Strict-Transport-Security', opts.hsts);
+        }
+        if (opts.referrerPolicy !== false) {
+            res.setHeader('Referrer-Policy', opts.referrerPolicy);
+        }
+        if (opts.permissionsPolicy !== false) {
+            res.setHeader('Permissions-Policy', opts.permissionsPolicy);
+        }
+        if (opts.crossOriginOpenerPolicy !== false) {
+            res.setHeader('Cross-Origin-Opener-Policy', opts.crossOriginOpenerPolicy);
+        }
+        next();
+    };
+}

package/dist/shared/socket-io-setup.d.ts

@@ -0,0 +1,11 @@
+export interface SocketRoute {
+    path: string;
+    hasSocket: boolean;
+    filePath: string;
+}
+export declare function setupSocketIO(options: {
+    httpServer: any;
+    loadModule: (filePath: string) => Promise<any>;
+    routes: SocketRoute[];
+    projectDir?: string;
+}): Promise<any>;

package/dist/shared/socket-io-setup.js

@@ -0,0 +1,51 @@
+import { createRequire } from 'module';
+import { pathToFileURL } from 'url';
+export async function setupSocketIO(options) {
+    // Resolve socket.io from the project's node_modules (not from lumenjs's own node_modules)
+    let SocketIOServer;
+    if (options.projectDir) {
+        const require = createRequire(pathToFileURL(options.projectDir + '/package.json').href);
+        const socketIo = require('socket.io');
+        SocketIOServer = socketIo.Server || socketIo.default?.Server || socketIo;
+    }
+    else {
+        const socketIo = await import('socket.io');
+        SocketIOServer = socketIo.Server;
+    }
+    const io = new SocketIOServer(options.httpServer, {
+        path: '/__nk_socketio/',
+        cors: { origin: process.env.NODE_ENV === 'production' ? false : '*' },
+    });
+    for (const route of options.routes) {
+        if (!route.hasSocket)
+            continue;
+        const ns = `/nk${route.path === '/' ? '/index' : route.path}`;
+        io.of(ns).on('connection', async (socket) => {
+            try {
+                const mod = await options.loadModule(route.filePath);
+                if (!mod.socket)
+                    return;
+                const push = (data) => socket.emit('nk:data', data);
+                const on = (event, handler) => {
+                    socket.on(`nk:${event}`, handler);
+                };
+                const room = {
+                    join: (name) => socket.join(name),
+                    leave: (name) => socket.leave(name),
+                    broadcast: (name, data) => socket.to(name).emit('nk:data', data),
+                    broadcastAll: (name, data) => io.of(ns).to(name).emit('nk:data', data),
+                };
+                const params = socket.handshake.query.__params
+                    ? JSON.parse(socket.handshake.query.__params) : {};
+                const locale = socket.handshake.query.__locale;
+                const cleanup = mod.socket({ on, push, room, params, headers: socket.handshake.headers, locale, socket });
+                socket.on('disconnect', () => { if (typeof cleanup === 'function')
+                    cleanup(); });
+            }
+            catch (err) {
+                console.error(`[LumenJS] Socket handler error for ${route.path}:`, err);
+            }
+        });
+    }
+    return io;
+}