@ramme-io/create-app 1.2.1 → 1.2.5

package/template/src/data/mock-charts.ts

@@ -1,37 +1,41 @@
-// src/data/mock-charts.ts
-import type { ChartData } from 'chart.js';
+/**
+ * @file mock-charts.ts
+ * @description The "Chart Data Lake".
+ *
+ * ARCHITECTURAL ROLE:
+ * This file stores the structured data required by Recharts components.
+ * Separating this from the tabular `mockData.ts` prevents bloat and allows
+ * for specific optimization of visualization data.
+ */
 
-// The centralized registry of "Heavy Data"
-export const MOCK_CHART_DATA: Record<string, ChartData<any>> = {
+// 1. Define a generic shape for Recharts data
+// Recharts expects an array of objects: [{ name: 'A', value: 10 }, ...]
+export type RechartsData = Record<string, any>[];
+
+export const MOCK_CHART_DATA: Record<string, RechartsData> = {
   
   // ID: energy_history
-  energy_history: {
-    labels: ["12am", "4am", "8am", "12pm", "4pm", "8pm"],
-    datasets: [
-      {
-        label: "Energy (kWh)",
-        data: [12, 19, 3, 5, 2, 3],
-        borderColor: "#3b82f6",
-        backgroundColor: "rgba(59, 130, 246, 0.5)",
-        tension: 0.4
-      }
-    ]
-  },
+  energy_history: [
+    { time: "12am", value: 12 },
+    { time: "4am", value: 19 },
+    { time: "8am", value: 3 },
+    { time: "12pm", value: 5 },
+    { time: "4pm", value: 2 },
+    { time: "8pm", value: 3 }
+  ],
 
   // ID: server_load
-  server_load: {
-    labels: ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"],
-    datasets: [
-      {
-        label: "CPU Load %",
-        data: [45, 52, 38, 70, 65, 30, 40],
-        borderColor: "#10b981",
-        backgroundColor: "rgba(16, 185, 129, 0.5)"
-      }
-    ]
-  }
+  server_load: [
+    { day: "Mon", load: 45 },
+    { day: "Tue", load: 52 },
+    { day: "Wed", load: 38 },
+    { day: "Thu", load: 70 },
+    { day: "Fri", load: 65 },
+    { day: "Sat", load: 30 },
+    { day: "Sun", load: 40 }
+  ]
 };
 
 export const getChartData = (id: string) => {
-  return MOCK_CHART_DATA[id] || null;
+  return MOCK_CHART_DATA[id] || [];
 };

package/template/src/{components → engine/renderers}/DynamicBlock.tsx

@@ -1,8 +1,23 @@
 import React from 'react';
-import { getComponent } from '../core/component-registry';
+import { getComponent } from '../../config/component-registry';
 // @ts-ignore
-import { useGeneratedSignals } from '../generated/hooks';
-import { getMockData } from '../data/mockData';
+import { useGeneratedSignals } from '../runtime/useSignalStore';
+import { getMockData } from '../../data/mockData';
+
+/**
+ * @file DynamicBlock.tsx
+ * @description The "Runtime Hydrator" for the application.
+ *
+ * ARCHITECTURAL ROLE:
+ * This component acts as the bridge between the Abstract Syntax Tree (JSON Manifest)
+ * and the concrete React UI.
+ *
+ * KEY RESPONSIBILITIES:
+ * 1. **Component Lookup:** Resolves string types ('StatCard') to actual React components.
+ * 2. **Signal Injection:** Subscribes to the real-time Signal Engine and feeds live values to props.
+ * 3. **Data Hydration:** Fetches static or async data (users, logs) based on `dataId`.
+ * 4. **Status Normalization:** Translates system-level signal states into UI-friendly status colors.
+ */
 
 const mapSignalStatus = (status: string): string => {
   switch (status) {
@@ -39,18 +54,23 @@ export const DynamicBlock: React.FC<any> = ({ block }) => {
     const signalState = signals[signalId];
 
     if (signalState) {
-      // ✅ FIX: Handle both Raw Values (Legacy) and Signal Objects (New)
-      // If it's an object with a 'value' property, use that. Otherwise use it directly.
-      const rawValue = (typeof signalState === 'object' && 'value' in signalState) 
+      // ✅ FIX: Check for null and handle objects vs raw values
+      const isSignalObject = typeof signalState === 'object' && signalState !== null;
+
+      // Extract Value
+      const rawValue = (isSignalObject && 'value' in signalState) 
         ? signalState.value 
         : signalState;
 
-      const status = (typeof signalState === 'object' && 'status' in signalState)
+      // Extract Status
+      const rawStatus = (isSignalObject && 'status' in signalState)
         ? signalState.status
         : 'fresh'; // Default for raw values
 
       dynamicProps.value = typeof rawValue === 'number' ? rawValue : String(rawValue);
-      dynamicProps.status = mapSignalStatus(status);
+      
+      // ✅ FIX: Explicitly cast to String to satisfy TypeScript
+      dynamicProps.status = mapSignalStatus(String(rawStatus));
     } else {
       dynamicProps.status = mapSignalStatus('disconnected');
     }

package/template/src/engine/renderers/DynamicPage.tsx

@@ -0,0 +1,150 @@
+import React, { Component, type ErrorInfo, useMemo } from 'react';
+import { PageHeader, Alert, Badge } from '@ramme-io/ui';
+import { useManifest, useBridgeStatus } from '../runtime/ManifestContext';
+import { getComponent } from '../../config/component-registry';
+import { getMockData } from '../../data/mockData'; // Keep as fallback
+import { Wifi, WifiOff, AlertTriangle, Loader2, Database, Wand2 } from 'lucide-react';
+
+// --- 🛠️ JIT DATA GENERATOR ---
+// This ensures the preview ALWAYS has data, even for new resources not yet in the DB.
+const generateJitData = (resourceDef: any, count = 10) => {
+  if (!resourceDef) return [];
+  
+  return Array.from({ length: count }).map((_, i) => {
+    const row: any = { id: i + 1 };
+    resourceDef.fields.forEach((f: any) => {
+      // Intelligent Mocking based on field type
+      if (f.type === 'status') {
+        row[f.key] = ['Active', 'Pending', 'Closed', 'Archived'][Math.floor(Math.random() * 4)];
+      } else if (f.type === 'boolean') {
+        row[f.key] = Math.random() > 0.3; // 70% true
+      } else if (f.type === 'number' || f.type === 'currency') {
+        row[f.key] = Math.floor(Math.random() * 1000) + 100;
+      } else if (f.type === 'date') {
+        const d = new Date();
+        d.setDate(d.getDate() - Math.floor(Math.random() * 30));
+        row[f.key] = d.toISOString().split('T')[0];
+      } else {
+        row[f.key] = `${f.label} ${i + 1}`;
+      }
+    });
+    return row;
+  });
+};
+
+// --- ERROR BOUNDARY ---
+class BlockErrorBoundary extends Component<{ children: React.ReactNode }, { hasError: boolean, error: string }> {
+  constructor(props: any) { super(props); this.state = { hasError: false, error: '' }; }
+  static getDerivedStateFromError(error: any) { return { hasError: true, error: error.message }; }
+  render() {
+    if (this.state.hasError) return (
+        <div className="h-full min-h-[100px] p-4 border-2 border-dashed border-red-300 bg-red-50/50 rounded-lg flex flex-col items-center justify-center text-red-600 text-xs">
+          <AlertTriangle size={16} className="mb-2 opacity-80" />
+          <span className="font-bold">Render Error</span>
+          <span className="opacity-75 text-center truncate max-w-[200px]">{this.state.error}</span>
+        </div>
+    );
+    return this.props.children;
+  }
+}
+
+// --- MAIN RENDERER ---
+export const DynamicPage = ({ pageId }: { pageId: string }) => {
+  const manifest = useManifest();
+  const status = useBridgeStatus();
+  const isLive = status === 'live';
+
+  const page = useMemo(() => manifest.pages?.find((p: any) => p.id === pageId), [manifest, pageId]);
+
+  if (!page) {
+    return (
+      <div className="p-8 space-y-4">
+         <Alert variant="info" title="Connecting..."><Loader2 className="animate-spin mr-2" size={16} /> Loading Page...</Alert>
+      </div>
+    );
+  }
+
+  return (
+    <div className="space-y-8 animate-in fade-in duration-300 pb-20 p-6 md:p-8">
+      {/* Header */}
+      <div className="flex flex-col md:flex-row md:items-start justify-between gap-4 border-b border-border pb-6">
+        <div>
+          <h1 className="text-3xl font-bold tracking-tight text-foreground">{page.title}</h1>
+          {page.description && <p className="text-muted-foreground text-lg">{page.description}</p>}
+        </div>
+        <div className={`flex items-center gap-2 px-3 py-1.5 rounded-full text-xs font-bold border ${isLive ? 'bg-green-100 text-green-700 border-green-200' : 'bg-slate-100 text-slate-500'}`}>
+          {isLive ? <Wifi size={14} className="text-green-600 animate-pulse"/> : <WifiOff size={14} />}
+          {isLive ? 'LIVE PREVIEW' : 'STATIC MODE'}
+        </div>
+      </div>
+      
+      {/* Grid Layout */}
+      <div className="grid gap-8">
+        {page.sections?.map((section: any) => (
+          <section key={section.id} className="space-y-4">
+            {section.title && (
+              <div className="flex items-center gap-2 pb-2 border-b border-dashed border-gray-200">
+                 <h3 className="text-sm font-bold uppercase tracking-wider text-muted-foreground">{section.title}</h3>
+              </div>
+            )}
+            <div className="grid gap-6" style={{ gridTemplateColumns: `repeat(${section.layout?.columns || 1}, minmax(0, 1fr))` }}>
+              {section.blocks.map((block: any) => {
+                const Component = getComponent(block.type);
+                const safeDataId = block.props.dataId?.toLowerCase();
+                
+                // --- 🛡️ HYBRID DATA STRATEGY ---
+                let resolvedData: any[] = [];
+                let isGenerated = false;
+                let autoColumns = undefined;
+
+                if (safeDataId) {
+                  // 1. Try Local Storage first
+                  resolvedData = getMockData(safeDataId); 
+                  
+                  // 2. If empty, Generate JIT Data from Manifest
+                  if (!resolvedData || resolvedData.length === 0) {
+                     const resourceDef = manifest.resources?.find((r: any) => r.id.toLowerCase() === safeDataId);
+                     if (resourceDef) {
+                        resolvedData = generateJitData(resourceDef);
+                        isGenerated = true; // Flag for debug overlay
+                     }
+                  }
+
+                  // 3. Auto-Generate Table Columns
+                  const resourceDef = manifest.resources?.find((r: any) => r.id.toLowerCase() === safeDataId);
+                  if (resourceDef && !block.props.columnDefs) {
+                    autoColumns = resourceDef.fields.map((f: any) => ({
+                      field: f.key, headerName: f.label, filter: true, flex: 1,
+                      cellRenderer: f.type === 'status' ? (p: any) => <Badge variant="secondary">{p.value}</Badge> : undefined
+                    }));
+                  }
+                }
+
+                return (
+                  <div key={block.id} style={{ gridColumn: `span ${block.layout?.colSpan || 1}`, gridRow: `span ${block.layout?.rowSpan || 1}` }} className="relative group">
+                     <BlockErrorBoundary>
+                        {/* Debug Overlay */}
+                        <div className="absolute top-2 right-2 opacity-0 group-hover:opacity-100 transition-opacity z-20 flex gap-1 pointer-events-none">
+                           <div className={`text-white text-[10px] px-2 py-1 rounded backdrop-blur-md flex items-center gap-1 ${isGenerated ? 'bg-amber-600/90' : 'bg-black/80'}`}>
+                              {block.type}
+                              {safeDataId && <> <span className="opacity-50">|</span> {isGenerated ? <Wand2 size={10}/> : <Database size={10}/>} {safeDataId} ({resolvedData.length})</>}
+                           </div>
+                        </div>
+                        
+                        <Component 
+                           {...block.props} 
+                           rowData={resolvedData} 
+                           columnDefs={block.props.columnDefs || autoColumns}
+                           className="w-full h-full shadow-sm bg-card rounded-xl border border-border" 
+                        />
+                     </BlockErrorBoundary>
+                  </div>
+                );
+              })}
+            </div>
+          </section>
+        ))}
+      </div>
+    </div>
+  );
+};

package/template/src/engine/runtime/ManifestContext.tsx

@@ -0,0 +1,79 @@
+import React, { createContext, useContext, useEffect, useState, useRef } from 'react';
+// ✅ FIX 1: Correct Path to Static Manifest
+import { appManifest as staticManifest } from '../../config/app.manifest';
+// ✅ FIX 2: Correct Path to Types
+import type { AppSpecification } from '../validation/schema';
+
+interface ManifestContextType {
+  manifest: AppSpecification;
+  isLive: boolean;
+}
+
+const ManifestContext = createContext<ManifestContextType>({ 
+  manifest: staticManifest, 
+  isLive: false 
+});
+
+export const ManifestProvider: React.FC<{ children: React.ReactNode }> = ({ children }) => {
+  // 1. Initialize State
+  const [manifest, setManifest] = useState<AppSpecification>(staticManifest);
+  const [isLive, setIsLive] = useState(false);
+  
+  // 2. Global Listener Guard (Refs persist across re-renders)
+  const isListening = useRef(false);
+
+  useEffect(() => {
+    // Prevent double-attaching listeners in StrictMode
+    if (isListening.current) return;
+    isListening.current = true;
+
+    // A. Define the Listener
+    const handleMessage = (event: MessageEvent) => {
+      // Security: Filter out noise, listen only for our specific event
+      if (event.data?.type === 'RAMME_SYNC_MANIFEST') {
+        const payload = event.data.payload;
+        // console.log("⚡️ [Context] Sync Received");
+        setManifest(payload);
+        setIsLive(true);
+      }
+    };
+
+    // B. Attach Listener
+    window.addEventListener('message', handleMessage);
+
+    // C. Send Handshake (ONCE per session)
+    // We check a global window property to ensure we never spam the parent,
+    // even if this Provider is unmounted and remounted by React Router.
+    if (window.parent !== window && !(window as any).__RAMME_HANDSHAKE_SENT) {
+       console.log("🔌 [Context] Handshake Sent 🤝");
+       window.parent.postMessage({ type: 'RAMME_CLIENT_READY' }, '*');
+       (window as any).__RAMME_HANDSHAKE_SENT = true;
+    }
+
+    // Cleanup
+    return () => {
+      window.removeEventListener('message', handleMessage);
+      isListening.current = false;
+    };
+  }, []);
+
+  return (
+    <ManifestContext.Provider value={{ manifest, isLive }}>
+      {children}
+    </ManifestContext.Provider>
+  );
+};
+
+// --- CONSUMER HOOKS ---
+
+export const useManifest = () => {
+  const context = useContext(ManifestContext);
+  if (!context) return staticManifest;
+  return context.manifest;
+};
+
+// Returns 'live' | 'static' string to match your UI components
+export const useBridgeStatus = () => {
+  const context = useContext(ManifestContext);
+  return context?.isLive ? 'live' : 'static';
+};

package/template/src/{contexts → engine/runtime}/MqttContext.tsx

@@ -1,5 +1,8 @@
 import React, { createContext, useContext, useEffect, useRef, useState } from 'react';
 import mqtt, { type MqttClient } from 'mqtt';
+// ❌ REMOVED: import { appManifest } from '../../config/app.manifest';
+// ✅ ADDED: Live Context
+import { useManifest } from './ManifestContext';
 
 interface MqttContextType {
   isConnected: boolean;
@@ -11,35 +14,42 @@ interface MqttContextType {
 
 const MqttContext = createContext<MqttContextType | null>(null);
 
-// Public Test Broker for "Out of the Box" functionality
-// In a real app, this comes from config.ts
-const DEFAULT_BROKER = 'wss://test.mosquitto.org:8081'; 
-
 export const MqttProvider: React.FC<{ children: React.ReactNode }> = ({ children }) => {
   const [isConnected, setIsConnected] = useState(false);
   const [lastMessage, setLastMessage] = useState<Record<string, string>>({});
   const clientRef = useRef<MqttClient | null>(null);
-  
-  // Track active subscriptions to avoid double-subscribing
   const subscriptions = useRef<Set<string>>(new Set());
 
+  // ✅ 1. Consume Live Manifest
+  const appManifest = useManifest();
+
   useEffect(() => {
-    console.log(`[MQTT] Connecting to ${DEFAULT_BROKER}...`);
+    // ✅ 2. Hot-Swap Broker Connection
+    // If you change the Broker URL in the Builder, this effect will re-run!
+    const brokerUrl = appManifest.config.brokerUrl || 'wss://test.mosquitto.org:8081';
+    console.log(`[MQTT] Connecting to ${brokerUrl}...`);
     
-    const client = mqtt.connect(DEFAULT_BROKER);
+    // Disconnect previous if exists
+    if (clientRef.current) {
+        clientRef.current.end();
+    }
+
+    const client = mqtt.connect(brokerUrl);
     clientRef.current = client;
 
     client.on('connect', () => {
       console.log('[MQTT] Connected ✅');
       setIsConnected(true);
+      // Re-subscribe to previous topics if needed
+      subscriptions.current.forEach(t => client.subscribe(t));
     });
 
-    client.on('message', (topic: any, message: { toString: () => any; }) => {
-      const payload = message.toString();
-      setLastMessage((prev) => ({ ...prev, [topic]: payload }));
+    client.on('message', (topic: string, payload: Buffer) => {
+      const messageStr = payload.toString();
+      setLastMessage((prev) => ({ ...prev, [topic]: messageStr }));
     });
 
-    client.on('error', (err: any) => {
+    client.on('error', (err) => {
       console.error('[MQTT] Connection error: ', err);
       client.end();
     });
@@ -48,11 +58,10 @@ export const MqttProvider: React.FC<{ children: React.ReactNode }> = ({ children
       console.log('[MQTT] Disconnecting...');
       client.end();
     };
-  }, []);
+  }, [appManifest.config.brokerUrl]); // Only re-connect if URL changes
 
   const subscribe = (topic: string) => {
     if (clientRef.current && !subscriptions.current.has(topic)) {
-      console.log(`[MQTT] Subscribing to: ${topic}`);
       clientRef.current.subscribe(topic);
       subscriptions.current.add(topic);
     }

package/template/src/{contexts → engine/runtime}/SitemapContext.tsx

@@ -20,7 +20,7 @@
 
 import { createContext, useContext } from 'react';
 // Import the canonical "schema" for a sitemap entry
-import type { SitemapEntry } from '../core/sitemap-entry';
+import type { SitemapEntry } from '../types/sitemap-entry';
 
 // 1. Create the context
 // We initialize it with an empty array as a safe default.

package/template/src/engine/runtime/data-seeder.ts

@@ -0,0 +1,47 @@
+// ✅ Match the export from your new mockData.ts
+import { DATA_REGISTRY } from '../../data/mockData'; 
+
+/**
+ * @file data-seeder.ts
+ * @description The "Big Bang" for the client-side database.
+ * * ARCHITECTURAL ROLE:
+ * This utility ensures that the LocalStorage "Data Lake" is never empty.
+ * On app launch, it checks if data exists. If not, it writes the seed data
+ * from `mockData.ts` into the browser's storage.
+ */
+
+// 🔒 SHARED CONSTANT: Ensure everyone uses the same key format
+const DB_PREFIX = 'ramme_mock_'; 
+
+export const initializeDataLake = () => {
+  if (typeof window === 'undefined') return;
+
+  console.groupCollapsed('🌊 [Data Lake] Initialization');
+  
+  Object.entries(DATA_REGISTRY).forEach(([key, seedData]) => {
+    // ✅ FIX: Use the prefix so getMockData() can find it
+    const storageKey = `${DB_PREFIX}${key}`; 
+    const existing = localStorage.getItem(storageKey);
+
+    if (!existing) {
+      console.log(`✨ Seeding collection: ${key} (${(seedData as any[]).length} records)`);
+      localStorage.setItem(storageKey, JSON.stringify(seedData));
+    } else {
+      console.log(`✅ Collection exists: ${key}`);
+    }
+  });
+
+  console.groupEnd();
+};
+
+/**
+ * Utility to clear the lake (useful for a "Reset Data" button)
+ */
+export const resetDataLake = () => {
+  Object.keys(DATA_REGISTRY).forEach((key) => {
+    const storageKey = `${DB_PREFIX}${key}`;
+    localStorage.removeItem(storageKey); 
+  });
+  console.log("🔥 Data Lake Evaporated (Cleared)");
+  window.location.reload();
+};

package/template/src/{hooks → engine/runtime}/useAction.ts

@@ -1,21 +1,25 @@
-// src/hooks/useAction.ts
 import { useCallback } from 'react';
-import { useMqtt } from '../contexts/MqttContext';
-import { appManifest } from '../config/app.manifest';
+import { useMqtt } from './MqttContext';
+// ❌ REMOVED: import { appManifest } from '../../config/app.manifest';
+// ✅ ADDED: Live Context
+import { useManifest } from './ManifestContext';
 
 export const useAction = () => {
   const { publish, isConnected } = useMqtt();
+  
+  // ✅ 1. Consume Live Manifest
+  const appManifest = useManifest();
   const { config, domain } = appManifest;
 
   const sendAction = useCallback(async (entityId: string, value: any) => {
-    // 1. Find the Entity definition
+    // 2. Find the Entity definition (Live)
     const entity = domain.entities.find(e => e.id === entityId);
+    
     if (!entity) {
-      console.warn(`[Action] Entity not found: ${entityId}`);
+      console.warn(`[Action] Entity ID '${entityId}' not found in manifest.`);
       return;
     }
 
-    // 2. Find the Primary Signal (The target of the action)
     const signalId = entity.signals[0];
     const signal = domain.signals.find(s => s.id === signalId);
 
@@ -24,12 +28,9 @@ export const useAction = () => {
       return;
     }
 
-    // 3. EXECUTE based on Mode & Source
-    
     // --- Mock Mode ---
     if (config.mockMode) {
       console.log(`%c[Mock Action] Setting ${entity.name} to:`, 'color: #10b981; font-weight: bold;', value);
-      // In a real app, we would update the local cache optimistically here
       return;
     }
 
@@ -46,9 +47,6 @@ export const useAction = () => {
 
     // --- Live Mode (HTTP) ---
     if (signal.source === 'http' && signal.endpoint) {
-      console.log(`[HTTP] POST to ${signal.endpoint}:`, value);
-      // Note: This will likely fail (404/405) against a static .json file, 
-      // but this is the correct code for a real API.
       try {
         await fetch(signal.endpoint, {
             method: 'POST',
@@ -56,8 +54,7 @@ export const useAction = () => {
             body: JSON.stringify({ id: signal.id, value })
         });
       } catch (err) {
-        // We expect this to fail on the static demo, so we suppress the error alert
-        console.log('[HTTP] (Simulation) Request sent.'); 
+        console.log('[HTTP] (Simulation) Request sent.');
       }
     }
 

package/template/src/{hooks → engine/runtime}/useCrudLocalStorage.ts

@@ -1,10 +1,12 @@
 import { useState, useCallback } from 'react';
 
 /**
- * A generic hook for performing CRUD (Create, Read, Update, Delete)
+ * @hook useCrudLocalStorage
+ * @description A generic hook for performing CRUD (Create, Read, Update, Delete)
  * operations on an array of items stored in the browser's localStorage.
+ * * It serves as the "Database Engine" for the mock runtime.
  *
- * @param storageKey The unique key for this data in localStorage.
+ * @param storageKey The unique key for this data in localStorage (e.g., 'ramme_db_users').
  * @param initialData The default data to seed localStorage with if it's empty.
  * @returns An object with the current data and functions to manipulate it.
  */
@@ -12,28 +14,43 @@ export const useCrudLocalStorage = <T extends { id: any }>(
   storageKey: string,
   initialData: T[]
 ) => {
+  // 1. Initialize State from LocalStorage
   const [data, setData] = useState<T[]>(() => {
+    // Safety check for Server-Side Rendering
+    if (typeof window === 'undefined') return initialData;
+    
     try {
       const item = window.localStorage.getItem(storageKey);
       if (item) {
-        // If data exists in localStorage, parse and return it.
         return JSON.parse(item);
       } else {
-        // Otherwise, seed localStorage with the initial data.
+        // Seed the "DB" if empty
         window.localStorage.setItem(storageKey, JSON.stringify(initialData));
         return initialData;
       }
     } catch (error) {
-      console.error("Error reading from localStorage", error);
+      console.error(`[Data Lake] Error reading key "${storageKey}":`, error);
       return initialData;
     }
   });
 
+  // 2. CREATE
   const createItem = useCallback((newItem: Omit<T, 'id'>) => {
     setData(prevData => {
-      // Find the highest existing ID to safely create a new one.
-      const maxId = prevData.reduce((max, item) => (item.id > max ? item.id : max), 0);
-      const fullNewItem = { ...newItem, id: maxId + 1 } as T;
+      // ✅ ROBUST ID GENERATION (Zero Jank)
+      // Detects if existing IDs are Numbers or Strings to prevent type conflicts.
+      let newId: any;
+      const isNumeric = prevData.length > 0 && typeof prevData[0].id === 'number';
+
+      if (isNumeric) {
+        const maxId = prevData.reduce((max, item) => (typeof item.id === 'number' && item.id > max ? item.id : max), 0);
+        newId = maxId + 1;
+      } else {
+        // Fallback for string IDs (e.g. 'usr_17354...')
+        newId = `id_${Date.now()}`;
+      }
+
+      const fullNewItem = { ...newItem, id: newId } as T;
       
       const updatedData = [...prevData, fullNewItem];
       window.localStorage.setItem(storageKey, JSON.stringify(updatedData));
@@ -41,6 +58,7 @@ export const useCrudLocalStorage = <T extends { id: any }>(
     });
   }, [storageKey]);
 
+  // 3. UPDATE
   const updateItem = useCallback((updatedItem: T) => {
     setData(prevData => {
       const updatedData = prevData.map(item =>
@@ -51,6 +69,7 @@ export const useCrudLocalStorage = <T extends { id: any }>(
     });
   }, [storageKey]);
 
+  // 4. DELETE
   const deleteItem = useCallback((id: T['id']) => {
     setData(prevData => {
       const updatedData = prevData.filter(item => item.id !== id);

package/template/src/{hooks → engine/runtime}/useDataQuery.ts

@@ -1,6 +1,20 @@
 import { useMemo } from 'react';
 
-// --- 1. Export the Missing Types (Fixes ts(2305)) ---
+/**
+ * @file useDataQuery.ts
+ * @description The "In-Memory Database Engine".
+ *
+ * ARCHITECTURAL ROLE:
+ * Since this application runs without a real backend, this hook acts as the
+ * SQL Query Engine. It takes raw arrays from the Data Lake and performs
+ * real-time filtering, sorting, and pagination before passing the result
+ * to the UI.
+ *
+ * CAPABILITIES:
+ * 1. WHERE: Supports complex filtering (equals, contains, gt, lt).
+ * 2. ORDER BY: Handles ascending/descending sorts on any field.
+ * 3. LIMIT/OFFSET: Calculates pagination slices automatically.
+ */
 
 export type SortDirection = 'asc' | 'desc';