@nuraly/lumenjs 0.2.0 → 0.5.0

package/dist/llms/generate.d.ts

@@ -14,6 +14,8 @@ export interface LlmsApiRoute {
 }
 export interface LlmsTxtInput {
     title: string;
+    description?: string;
+    baseUrl?: string;
     pages: LlmsPage[];
     apiRoutes: LlmsApiRoute[];
     integrations: string[];
@@ -26,9 +28,21 @@ export interface LlmsTxtInput {
     };
 }
 /**
- * Generate the llms.txt content from project metadata and resolved page data.
+ * Generate the llms.txt content following the llmstxt.org spec.
+ *
+ * Structure: H1 title, blockquote summary, H2 sections with
+ * markdown links to each page (linking to .md versions).
  */
 export declare function generateLlmsTxt(input: LlmsTxtInput): string;
+/**
+ * Generate llms-full.txt — all page content inlined as one markdown document.
+ */
+export declare function generateLlmsFullTxt(input: LlmsTxtInput & {
+    pageContents: {
+        path: string;
+        markdown: string;
+    }[];
+}): string;
 /**
  * Try to resolve dynamic route entries by finding a parent/sibling index page
  * whose loader returns an array, then calling the dynamic page's loader for each item.

package/dist/llms/generate.js

@@ -1,62 +1,53 @@
 /**
- * Generate the llms.txt content from project metadata and resolved page data.
+ * Generate the llms.txt content following the llmstxt.org spec.
+ *
+ * Structure: H1 title, blockquote summary, H2 sections with
+ * markdown links to each page (linking to .md versions).
  */
 export function generateLlmsTxt(input) {
     const lines = [];
+    const base = input.baseUrl ? input.baseUrl.replace(/\/$/, '') : '';
     lines.push(`# ${input.title}`);
     lines.push('');
-    lines.push('> Built with LumenJS');
+    lines.push(`> ${input.description || `${input.title}. Built with LumenJS.`}`);
     lines.push('');
-    // Pages section
-    if (input.pages.length > 0) {
-        lines.push('## Pages');
+    // Group pages by top-level path segment
+    const groups = new Map();
+    for (const page of input.pages) {
+        const segments = page.path.split('/').filter(Boolean);
+        const section = segments.length > 0 ? segments[0] : 'pages';
+        if (!groups.has(section))
+            groups.set(section, []);
+        groups.get(section).push(page);
+    }
+    // Pages — grouped by section with links
+    for (const [section, pages] of groups) {
+        const sectionTitle = section.charAt(0).toUpperCase() + section.slice(1);
+        lines.push(`## ${sectionTitle}`);
         lines.push('');
-        for (const page of input.pages) {
-            lines.push(`### ${page.path}`);
+        for (const page of pages) {
             const isDynamic = page.path.includes(':');
-            if (isDynamic) {
-                // Dynamic route — show expanded entries if available
-                if (page.dynamicEntries && page.dynamicEntries.length > 0) {
-                    lines.push(`Dynamic route — ${page.dynamicEntries.length} ${page.dynamicEntries.length === 1 ? 'entry' : 'entries'}:`);
-                    lines.push('');
-                    for (const entry of page.dynamicEntries) {
-                        lines.push(`#### ${entry.path}`);
-                        if (entry.loaderData) {
-                            lines.push(flattenData(entry.loaderData));
-                        }
-                        lines.push('');
-                    }
-                }
-                else {
-                    lines.push('- Dynamic route');
-                    lines.push('');
-                }
-            }
-            else if (page.loaderData && typeof page.loaderData === 'object') {
-                // Static page with loader data
-                lines.push(flattenData(page.loaderData));
-                lines.push('');
-            }
-            else {
-                // Simple page
-                const features = [];
-                if (page.hasLoader)
-                    features.push('with loader data');
-                if (page.hasSubscribe)
-                    features.push('with live data');
-                lines.push(`- Server-rendered page${features.length ? ' ' + features.join(', ') : ''}`);
-                lines.push('');
-            }
+            const label = page.path === '/' ? 'Home' : page.path;
+            const features = [];
+            if (isDynamic)
+                features.push('dynamic');
+            if (page.hasLoader)
+                features.push('server data');
+            if (page.hasSubscribe)
+                features.push('live data');
+            const desc = features.length > 0 ? `: ${features.join(', ')}` : '';
+            // Link to .md version for LLM-readable content (skip dynamic routes)
+            const href = !isDynamic ? `${base}${page.path}.md` : `${base}${page.path}`;
+            lines.push(`- [${label}](${href})${desc}`);
         }
+        lines.push('');
     }
     // API Routes section
     if (input.apiRoutes.length > 0) {
-        lines.push('## API Routes');
+        lines.push('## API');
         lines.push('');
         for (const route of input.apiRoutes) {
-            for (const method of route.methods) {
-                lines.push(`- ${method} /api/${route.path}`);
-            }
+            lines.push(`- [${route.methods.join(', ')} /api/${route.path}](${base}/api/${route.path})`);
         }
         lines.push('');
     }
@@ -85,6 +76,25 @@ export function generateLlmsTxt(input) {
     }
     return lines.join('\n').trimEnd() + '\n';
 }
+/**
+ * Generate llms-full.txt — all page content inlined as one markdown document.
+ */
+export function generateLlmsFullTxt(input) {
+    const lines = [];
+    lines.push(`# ${input.title}`);
+    lines.push('');
+    lines.push(`> ${input.description || `${input.title}. Built with LumenJS.`}`);
+    lines.push('');
+    for (const page of input.pageContents) {
+        lines.push('---');
+        lines.push(`source: ${page.path}`);
+        lines.push('---');
+        lines.push('');
+        lines.push(page.markdown.trim());
+        lines.push('');
+    }
+    return lines.join('\n').trimEnd() + '\n';
+}
 /**
  * Flatten a loader data object into key-value text lines.
  */

package/dist/runtime/communication.d.ts

@@ -1,26 +1,65 @@
 /**
  * Client-side communication SDK.
- * Connects to the server via Socket.io and provides a clean API for chat, typing, and presence.
+ * Connects to the server via Socket.io and provides a clean API for chat, typing, presence, and calls.
  */
 /**
  * Connect to the communication socket.
- * Must be called before using any other functions.
+ * Reuses an existing socket if one is already connected.
  */
-export declare function connectChat(params?: Record<string, string>): Promise<void>;
-/** Join a conversation room to receive messages */
-export declare function joinConversation(conversationId: string): void;
-/** Leave a conversation room */
-export declare function leaveConversation(conversationId: string): void;
-/** Send a message */
-export declare function sendMessage(conversationId: string, content: string, type?: string): void;
-/** Mark a message as read */
-export declare function markRead(conversationId: string, messageId: string): void;
+export declare function connectChat(params?: Record<string, string>): Promise<any>;
+/** Get the underlying socket instance (for call-service or other integrations) */
+export declare function getSocket(): any;
+/** Set an externally-created socket (e.g. from call-service or router) */
+export declare function setSocket(socket: any): void;
+/** Send a message (text, image, file, audio) */
+export declare function sendMessage(conversationId: string, content: string, opts?: {
+    type?: string;
+    attachment?: any;
+    replyTo?: any;
+    encrypted?: boolean;
+}): void;
+/** Mark messages as read */
+export declare function markRead(conversationId: string, messageIds?: string[]): void;
 /** React to a message with an emoji (toggle) */
 export declare function reactToMessage(messageId: string, conversationId: string, emoji: string): void;
 /** Edit a message */
 export declare function editMessage(messageId: string, conversationId: string, content: string): void;
 /** Delete a message */
 export declare function deleteMessage(messageId: string, conversationId: string): void;
+/** Load messages for a conversation (lazy-load) */
+export declare function loadMessages(conversationId: string): void;
+/** Join a conversation room to receive messages */
+export declare function joinConversation(conversationId: string): void;
+/** Leave a conversation room */
+export declare function leaveConversation(conversationId: string): void;
+/** Start typing indicator */
+export declare function startTyping(conversationId: string): void;
+/** Stop typing indicator */
+export declare function stopTyping(conversationId: string): void;
+/** Update presence status */
+export declare function updatePresence(status: 'online' | 'offline' | 'away' | 'busy'): void;
+/** Request bulk presence sync for a list of user IDs */
+export declare function requestPresenceSync(userIds: string[]): void;
+/** Refresh notification/message badge counts */
+export declare function refreshBadge(): void;
+/** Listen for new messages */
+export declare function onMessage(handler: (message: any) => void): () => void;
+/** Listen for typing updates */
+export declare function onTyping(handler: (data: {
+    conversationId: string;
+    userId: string;
+    isTyping: boolean;
+}) => void): () => void;
+/** Listen for presence changes */
+export declare function onPresence(handler: (data: {
+    userId: string;
+    status: string;
+    lastSeen: string;
+}) => void): () => void;
+/** Listen for bulk presence sync response */
+export declare function onPresenceSync(handler: (data: {
+    presences: Record<string, any>;
+}) => void): () => void;
 /** Listen for reaction updates */
 export declare function onReactionUpdate(handler: (data: {
     messageId: string;
@@ -37,6 +76,14 @@ export declare function onMessageDeleted(handler: (data: {
     messageId: string;
     conversationId: string;
 }) => void): () => void;
+/** Listen for read receipts */
+export declare function onReadReceipt(handler: (data: any) => void): () => void;
+/** Listen for lazy-loaded conversation messages */
+export declare function onConversationMessages(handler: (data: {
+    conversationId: string;
+    messages: any[];
+    participants: any[];
+}) => void): () => void;
 /** Upload a file (returns attachment metadata) */
 export declare function uploadFile(file: Blob, filename: string, encrypted?: boolean): Promise<{
     id: string;
@@ -45,31 +92,9 @@ export declare function uploadFile(file: Blob, filename: string, encrypted?: boo
 }>;
 /** Fetch link previews for a text */
 export declare function fetchLinkPreviews(text: string): Promise<any[]>;
-/** Start typing indicator */
-export declare function startTyping(conversationId: string): void;
-/** Stop typing indicator */
-export declare function stopTyping(conversationId: string): void;
-/** Update presence status */
-export declare function updatePresence(status: 'online' | 'offline' | 'away' | 'busy'): void;
-/** Listen for new messages */
-export declare function onMessage(handler: (message: any) => void): () => void;
-/** Listen for typing updates */
-export declare function onTyping(handler: (data: {
-    conversationId: string;
-    userId: string;
-    isTyping: boolean;
-}) => void): () => void;
-/** Listen for presence changes */
-export declare function onPresence(handler: (data: {
-    userId: string;
-    status: string;
-    lastSeen: string;
-}) => void): () => void;
-/** Listen for read receipts */
-export declare function onReadReceipt(handler: (data: any) => void): () => void;
 /** Listen for incoming calls */
 export declare function onIncomingCall(handler: (call: any) => void): () => void;
-/** Listen for call state changes (initiating, ringing, connecting, connected, ended) */
+/** Listen for call state changes */
 export declare function onCallStateChanged(handler: (data: {
     callId: string;
     state: string;
@@ -94,11 +119,15 @@ export declare function onMediaChanged(handler: (data: {
     screenShare?: boolean;
 }) => void): () => void;
 /** Initiate an audio or video call */
-export declare function initiateCall(conversationId: string, type: 'audio' | 'video', calleeIds: string[]): void;
+export declare function initiateCall(conversationId: string, type: 'audio' | 'video', calleeIds: string[], caller?: {
+    callerName?: string;
+    callerInitials?: string;
+    callerColor?: string;
+}): void;
 /** Respond to an incoming call */
 export declare function respondToCall(callId: string, action: 'accept' | 'reject'): void;
 /** Hang up an active call */
-export declare function hangup(callId: string, reason?: string): void;
+export declare function hangup(callId: string, reason?: string, duration?: string | null): void;
 /** Toggle audio/video/screenshare during a call */
 export declare function toggleMedia(callId: string, opts: {
     audio?: boolean;

package/dist/runtime/communication.js

@@ -1,12 +1,12 @@
 /**
  * Client-side communication SDK.
- * Connects to the server via Socket.io and provides a clean API for chat, typing, and presence.
+ * Connects to the server via Socket.io and provides a clean API for chat, typing, presence, and calls.
  */
 let _socket = null;
 let _handlers = new Map();
 function emit(event, data) {
     if (!_socket)
-        throw new Error('Communication not connected. Call connectChat() first.');
+        return;
     _socket.emit(`nk:${event}`, data);
 }
 function addHandler(event, handler) {
@@ -22,15 +22,19 @@ function removeHandler(event, handler) {
 }
 /**
  * Connect to the communication socket.
- * Must be called before using any other functions.
+ * Reuses an existing socket if one is already connected.
  */
 export async function connectChat(params) {
-    if (_socket)
-        return;
+    if (_socket?.connected)
+        return _socket;
     const { io } = await import('socket.io-client');
     _socket = io('/nk/messages', {
         path: '/__nk_socketio/',
         query: { ...params, __params: JSON.stringify(params || {}) },
+        reconnection: true,
+        reconnectionAttempts: Infinity,
+        reconnectionDelay: 1000,
+        reconnectionDelayMax: 10000,
     });
     _socket.on('nk:data', (data) => {
         if (data?.event) {
@@ -41,22 +45,44 @@ export async function connectChat(params) {
             }
         }
     });
+    return _socket;
 }
-/** Join a conversation room to receive messages */
-export function joinConversation(conversationId) {
-    emit('conversation:join', { conversationId });
-}
-/** Leave a conversation room */
-export function leaveConversation(conversationId) {
-    emit('conversation:leave', { conversationId });
+/** Get the underlying socket instance (for call-service or other integrations) */
+export function getSocket() { return _socket; }
+/** Set an externally-created socket (e.g. from call-service or router) */
+export function setSocket(socket) {
+    if (_socket === socket)
+        return;
+    _socket = socket;
+    // Attach the nk:data handler if not already attached
+    if (_socket && !_socket.__nk_comm_attached) {
+        _socket.__nk_comm_attached = true;
+        _socket.on('nk:data', (data) => {
+            if (data?.event) {
+                const handlers = _handlers.get(data.event);
+                if (handlers) {
+                    for (const h of handlers)
+                        h(data.data);
+                }
+            }
+        });
+    }
 }
-/** Send a message */
-export function sendMessage(conversationId, content, type = 'text') {
-    emit('message:send', { conversationId, content, type });
+// ── Messages ─────────────────────────────────────────────────────
+/** Send a message (text, image, file, audio) */
+export function sendMessage(conversationId, content, opts) {
+    emit('message:send', {
+        conversationId,
+        content,
+        type: opts?.type || 'text',
+        ...(opts?.attachment ? { attachment: opts.attachment } : {}),
+        ...(opts?.replyTo ? { replyTo: opts.replyTo } : {}),
+        ...(opts?.encrypted ? { encrypted: true } : {}),
+    });
 }
-/** Mark a message as read */
-export function markRead(conversationId, messageId) {
-    emit('message:read', { conversationId, messageId });
+/** Mark messages as read */
+export function markRead(conversationId, messageIds) {
+    emit('message:read', { conversationId, ...(messageIds ? { messageIds } : {}) });
 }
 /** React to a message with an emoji (toggle) */
 export function reactToMessage(messageId, conversationId, emoji) {
@@ -70,6 +96,61 @@ export function editMessage(messageId, conversationId, content) {
 export function deleteMessage(messageId, conversationId) {
     emit('message:delete', { messageId, conversationId });
 }
+/** Load messages for a conversation (lazy-load) */
+export function loadMessages(conversationId) {
+    emit('conversation:load-messages', { conversationId });
+}
+/** Join a conversation room to receive messages */
+export function joinConversation(conversationId) {
+    emit('conversation:join', { conversationId });
+}
+/** Leave a conversation room */
+export function leaveConversation(conversationId) {
+    emit('conversation:leave', { conversationId });
+}
+// ── Typing ───────────────────────────────────────────────────────
+/** Start typing indicator */
+export function startTyping(conversationId) {
+    emit('typing:start', { conversationId });
+}
+/** Stop typing indicator */
+export function stopTyping(conversationId) {
+    emit('typing:stop', { conversationId });
+}
+// ── Presence ─────────────────────────────────────────────────────
+/** Update presence status */
+export function updatePresence(status) {
+    emit('presence:update', { status });
+}
+/** Request bulk presence sync for a list of user IDs */
+export function requestPresenceSync(userIds) {
+    emit('presence:sync', { userIds });
+}
+/** Refresh notification/message badge counts */
+export function refreshBadge() {
+    emit('badge:refresh', {});
+}
+// ── Event Listeners ──────────────────────────────────────────────
+/** Listen for new messages */
+export function onMessage(handler) {
+    addHandler('message:new', handler);
+    return () => removeHandler('message:new', handler);
+}
+/** Listen for typing updates */
+export function onTyping(handler) {
+    addHandler('typing:update', handler);
+    return () => removeHandler('typing:update', handler);
+}
+/** Listen for presence changes */
+export function onPresence(handler) {
+    addHandler('presence:changed', handler);
+    return () => removeHandler('presence:changed', handler);
+}
+/** Listen for bulk presence sync response */
+export function onPresenceSync(handler) {
+    addHandler('presence:sync', handler);
+    return () => removeHandler('presence:sync', handler);
+}
 /** Listen for reaction updates */
 export function onReactionUpdate(handler) {
     addHandler('message:reaction-update', handler);
@@ -85,6 +166,17 @@ export function onMessageDeleted(handler) {
     addHandler('message:deleted', handler);
     return () => removeHandler('message:deleted', handler);
 }
+/** Listen for read receipts */
+export function onReadReceipt(handler) {
+    addHandler('read-receipt:update', handler);
+    return () => removeHandler('read-receipt:update', handler);
+}
+/** Listen for lazy-loaded conversation messages */
+export function onConversationMessages(handler) {
+    addHandler('conversation:messages', handler);
+    return () => removeHandler('conversation:messages', handler);
+}
+// ── File Uploads & Link Previews ─────────────────────────────────
 /** Upload a file (returns attachment metadata) */
 export async function uploadFile(file, filename, encrypted = false) {
     const res = await fetch('/__nk_comm/upload', {
@@ -112,45 +204,13 @@ export async function fetchLinkPreviews(text) {
     const data = await res.json();
     return data.previews || [];
 }
-/** Start typing indicator */
-export function startTyping(conversationId) {
-    emit('typing:start', { conversationId });
-}
-/** Stop typing indicator */
-export function stopTyping(conversationId) {
-    emit('typing:stop', { conversationId });
-}
-/** Update presence status */
-export function updatePresence(status) {
-    emit('presence:update', { status });
-}
-/** Listen for new messages */
-export function onMessage(handler) {
-    addHandler('message:new', handler);
-    return () => removeHandler('message:new', handler);
-}
-/** Listen for typing updates */
-export function onTyping(handler) {
-    addHandler('typing:update', handler);
-    return () => removeHandler('typing:update', handler);
-}
-/** Listen for presence changes */
-export function onPresence(handler) {
-    addHandler('presence:changed', handler);
-    return () => removeHandler('presence:changed', handler);
-}
-/** Listen for read receipts */
-export function onReadReceipt(handler) {
-    addHandler('read-receipt:update', handler);
-    return () => removeHandler('read-receipt:update', handler);
-}
-// ── Calls ─────────────────────────────────────────────────────────
+// ── Calls ────────────────────────────────────────────────────────
 /** Listen for incoming calls */
 export function onIncomingCall(handler) {
     addHandler('call:incoming', handler);
     return () => removeHandler('call:incoming', handler);
 }
-/** Listen for call state changes (initiating, ringing, connecting, connected, ended) */
+/** Listen for call state changes */
 export function onCallStateChanged(handler) {
     addHandler('call:state-changed', handler);
     return () => removeHandler('call:state-changed', handler);
@@ -171,22 +231,22 @@ export function onMediaChanged(handler) {
     return () => removeHandler('call:media-changed', handler);
 }
 /** Initiate an audio or video call */
-export function initiateCall(conversationId, type, calleeIds) {
-    emit('call:initiate', { conversationId, type, calleeIds });
+export function initiateCall(conversationId, type, calleeIds, caller) {
+    emit('call:initiate', { conversationId, type, calleeIds, ...caller });
 }
 /** Respond to an incoming call */
 export function respondToCall(callId, action) {
     emit('call:respond', { callId, action });
 }
 /** Hang up an active call */
-export function hangup(callId, reason = 'completed') {
-    emit('call:hangup', { callId, reason });
+export function hangup(callId, reason = 'completed', duration) {
+    emit('call:hangup', { callId, reason, ...(duration ? { duration } : {}) });
 }
 /** Toggle audio/video/screenshare during a call */
 export function toggleMedia(callId, opts) {
     emit('call:media-toggle', { callId, ...opts });
 }
-// ── WebRTC Signaling ──────────────────────────────────────────────
+// ── WebRTC Signaling ─────────────────────────────────────────────
 /** Send SDP offer to a peer */
 export function sendOffer(callId, toUserId, sdp) {
     emit('signal:offer', { callId, fromUserId: '', toUserId, type: 'offer', sdp });

package/dist/runtime/router.js

@@ -170,7 +170,7 @@ export class NkRouter {
             es.onmessage = (e) => {
                 const pageEl = this.findPageElement(match.route.tagName);
                 if (pageEl)
-                    pageEl.liveData = JSON.parse(e.data);
+                    this.spreadData(pageEl, JSON.parse(e.data));
             };
             this.subscriptions.push(es);
         }
@@ -204,7 +204,7 @@ export class NkRouter {
                 socket.on('nk:data', (data) => {
                     const pageEl = this.findPageElement(match.route.tagName);
                     if (pageEl) {
-                        pageEl.liveData = data;
+                        this.spreadData(pageEl, data);
                         injectEmit();
                     }
                 });
@@ -217,7 +217,7 @@ export class NkRouter {
                 es.onmessage = (e) => {
                     const layoutEl = this.outlet?.querySelector(layout.tagName);
                     if (layoutEl)
-                        layoutEl.liveData = JSON.parse(e.data);
+                        this.spreadData(layoutEl, JSON.parse(e.data));
                 };
                 this.subscriptions.push(es);
             }

package/dist/runtime/webrtc.d.ts

@@ -66,7 +66,14 @@ export declare class GroupWebRTCManager {
     getRemoteStream(userId: string): MediaStream | null;
     getRemoteStreams(): Map<string, MediaStream>;
     /** Acquire local media — call once before adding peers */
-    startLocalMedia(video?: boolean, audio?: boolean): Promise<MediaStream>;
+    startLocalMedia(video?: boolean, audio?: boolean, deviceIds?: {
+        audioInputId?: string | null;
+        videoInputId?: string | null;
+    }): Promise<MediaStream>;
+    /** Replace the audio track on all peer connections (for switching mic mid-call) */
+    replaceAudioTrack(newTrack: MediaStreamTrack): Promise<void>;
+    /** Replace the video track on all peer connections (for switching camera mid-call) */
+    replaceVideoTrack(newTrack: MediaStreamTrack): Promise<void>;
     /** Create a peer connection for a remote user and optionally create an offer */
     addPeer(userId: string, isCaller: boolean): Promise<string | void>;
     /** Remove and close a peer connection */