@ramme-io/kernel 1.3.0

package/src/components/SmartTable.tsx

@@ -0,0 +1,316 @@
+import React, { useState, useMemo, useCallback } from 'react';
+import { 
+  DataTable, 
+  Button, 
+  Icon, 
+  Card, 
+  Badge, 
+  useToast, 
+  SearchInput,
+  type ColDef,
+  type GridApi 
+} from '@ramme-io/ui';
+import { useJustInTimeSeeder } from '../engine/runtime/useJustInTimeSeeder';
+import { useCrudLocalStorage } from '../engine/runtime/useCrudLocalStorage';
+import { useManifest } from '../engine/runtime/ManifestContext';
+import { AutoForm } from './AutoForm';
+// ✅ IMPORT FieldDefinition specifically
+import type { ResourceDefinition, FieldDefinition } from '../engine/validation/schema';
+
+interface SmartTableProps {
+  dataId: string;
+  title?: string;
+  initialFilter?: Record<string, any>;
+  // Optional: Inject external dependency for metadata resolution
+  getResourceMeta?: (id: string) => { name: string; fields: FieldDefinition[] } | null;
+}
+
+export const SmartTable: React.FC<SmartTableProps> = ({ 
+  dataId, 
+  title,
+  getResourceMeta
+}) => {
+  const { addToast } = useToast();
+  const manifest = useManifest();
+
+  // --- 1. METADATA RESOLUTION ---
+  const meta = useMemo<ResourceDefinition | null>(() => {
+    const dynamicResource = manifest.resources?.find((r: ResourceDefinition) => r.id === dataId);
+    if (dynamicResource) return dynamicResource;
+
+    const staticMeta = getResourceMeta?.(dataId);
+    if (staticMeta) {
+      return {
+        ...staticMeta,
+        id: dataId,
+      } as unknown as ResourceDefinition; 
+    }
+    return null;
+  }, [manifest, dataId]);
+
+  // --- 2. DATA HYDRATION ---
+  const seedData = useJustInTimeSeeder(dataId, meta);
+  
+  const { 
+    data: rowData, 
+    createItem, 
+    updateItem, 
+    deleteItem 
+  } = useCrudLocalStorage<any>(`ramme_db_${dataId}`, seedData);
+
+  // --- 3. UI STATE ---
+  const [isEditOpen, setIsEditOpen] = useState(false);
+  const [currentRecord, setCurrentRecord] = useState<any>(null);
+  const [gridApi, setGridApi] = useState<GridApi | null>(null);
+  const [selectedRows, setSelectedRows] = useState<any[]>([]);
+  const [quickFilterText, setQuickFilterText] = useState('');
+
+  // --- 4. COLUMN DEFINITIONS (Desktop) ---
+  const columns = useMemo<ColDef[]>(() => {
+    if (!meta?.fields) return [];
+
+    const generatedCols: ColDef[] = meta.fields.map((f: FieldDefinition) => {
+      const col: ColDef = {
+        field: f.key,
+        headerName: f.label,
+        filter: true,
+        sortable: true,
+        resizable: true,
+        flex: 1,
+      };
+
+      if (f.type === 'currency') {
+        col.valueFormatter = (p: any) => p.value ? `$${Number(p.value).toLocaleString()}` : '';
+      }
+      if (f.type === 'date') {
+        col.valueFormatter = (p: any) => p.value ? new Date(p.value).toLocaleDateString() : '';
+      }
+      if (f.type === 'status') {
+        col.cellRenderer = (p: any) => {
+          const statusColors: any = {
+            active: 'bg-green-100 text-green-800',
+            paid: 'bg-green-100 text-green-800',
+            pending: 'bg-yellow-100 text-yellow-800',
+            inactive: 'bg-slate-100 text-slate-600',
+            overdue: 'bg-red-100 text-red-800'
+          };
+          const colorClass = statusColors[String(p.value).toLowerCase()] || 'bg-slate-100 text-slate-800';
+          return (
+            <span className={`px-2 py-0.5 rounded-full text-xs font-medium ${colorClass}`}>
+              {p.value}
+            </span>
+          );
+        };
+      }
+      return col;
+    });
+
+    if (generatedCols.length > 0) {
+      generatedCols[0].headerCheckboxSelection = true;
+      generatedCols[0].checkboxSelection = true;
+      generatedCols[0].minWidth = 180;
+    }
+
+    generatedCols.push({
+      headerName: "Actions",
+      field: "id",
+      width: 100,
+      pinned: 'right',
+      cellRenderer: (params: any) => (
+        <div className="flex items-center gap-1">
+          {/* ✅ FIXED: Explicit React.MouseEvent type */}
+          <Button variant="ghost" size="icon" className="h-8 w-8" onClick={(e: React.MouseEvent) => { e.stopPropagation(); setCurrentRecord(params.data); setIsEditOpen(true); }}>
+            <Icon name="edit-2" size={14} className="text-slate-500" />
+          </Button>
+        </div>
+      )
+    });
+
+    return generatedCols;
+  }, [meta]);
+
+  // --- 5. FIELD HELPERS (Mobile) ---
+  // ✅ FIXED: Explicit FieldDefinition type for 'f'
+  const titleField = useMemo(() => meta?.fields.find((f: FieldDefinition) => f.type === 'text' && f.key !== 'id') || meta?.fields[0], [meta]);
+  const statusField = useMemo(() => meta?.fields.find((f: FieldDefinition) => f.type === 'status'), [meta]);
+
+  // --- 6. HANDLERS ---
+  const onGridReady = useCallback((params: any) => {
+    setGridApi(params.api);
+  }, []);
+
+  const onSelectionChanged = useCallback(() => {
+    if (gridApi) {
+      setSelectedRows(gridApi.getSelectedRows());
+    }
+  }, [gridApi]);
+
+  const handleBulkDelete = () => {
+    if (confirm(`Delete ${selectedRows.length} items?`)) {
+      selectedRows.forEach(row => deleteItem(row.id));
+      setSelectedRows([]);
+      addToast(`${selectedRows.length} items deleted`, 'success');
+    }
+  };
+
+  const handleSave = (record: any) => {
+    if (record.id && currentRecord?.id) {
+      updateItem(record);
+      addToast('Item updated', 'success');
+    } else {
+      const { id, ...newItem } = record;
+      createItem(newItem);
+      addToast('Item created', 'success');
+    }
+    setIsEditOpen(false);
+  };
+
+  return (
+    <Card className="flex flex-col h-[600px] border border-border shadow-sm overflow-hidden bg-card">
+      
+      {/* --- HEADER --- */}
+      <div className="p-4 border-b border-border flex flex-col sm:flex-row justify-between items-start sm:items-center gap-4 bg-muted/5">
+        {selectedRows.length > 0 ? (
+          <div className="flex items-center gap-3 animate-in fade-in slide-in-from-left-2 duration-200">
+            <span className="bg-primary text-primary-foreground text-xs font-bold px-2 py-1 rounded-md">
+              {selectedRows.length} Selected
+            </span>
+            <Button size="sm" variant="danger" onClick={handleBulkDelete} iconLeft="trash-2">
+              Delete
+            </Button>
+          </div>
+        ) : (
+          <div className="flex items-center gap-2">
+            <div className="p-2 bg-primary/10 rounded-md text-primary">
+              <Icon name="table" size={18} />
+            </div>
+            <div>
+              <h3 className="text-base font-bold text-foreground leading-tight">
+                {title || meta?.name || dataId}
+              </h3>
+              <p className="text-xs text-muted-foreground">
+                {rowData.length} records found
+              </p>
+            </div>
+          </div>
+        )}
+
+        <div className="flex items-center gap-2 w-full sm:w-auto">
+          <div className="w-full sm:w-64">
+            <SearchInput 
+              placeholder="Quick search..." 
+              value={quickFilterText}
+              // ✅ FIXED: Explicit ChangeEvent type
+              onChange={(e: React.ChangeEvent<HTMLInputElement>) => {
+                setQuickFilterText(e.target.value);
+                gridApi?.updateGridOptions({ quickFilterText: e.target.value });
+              }}
+            />
+          </div>
+          <div className="h-6 w-px bg-border mx-1 hidden sm:block" />
+          <Button size="sm" variant="primary" iconLeft="plus" onClick={() => { setCurrentRecord({}); setIsEditOpen(true); }}>
+            Add
+          </Button>
+        </div>
+      </div>
+
+      {/* --- CONTENT AREA --- */}
+      <div className="flex-1 w-full bg-card relative overflow-hidden">
+        
+        {/* 🖥️ DESKTOP VIEW: The Power Grid */}
+        <div className="hidden md:block h-full">
+          <DataTable 
+            rowData={rowData} 
+            columnDefs={columns} 
+            onGridReady={onGridReady}
+            onSelectionChanged={onSelectionChanged}
+            rowSelection="multiple"
+            pagination={true}
+            paginationPageSize={10}
+            headerHeight={48}
+            rowHeight={48}
+            enableCellTextSelection={true}
+          />
+        </div>
+
+        {/* 📱 MOBILE VIEW: The Card List */}
+        <div className="block md:hidden h-full overflow-y-auto p-4 space-y-3 bg-muted/5">
+          {rowData.map((row) => (
+            <div key={row.id} className="bg-background border border-border rounded-lg p-4 shadow-sm relative group">
+              
+              {/* Header: Title + Status */}
+              <div className="flex justify-between items-start mb-2">
+                <div>
+                  <h4 className="font-semibold text-foreground">
+                    {titleField ? row[titleField.key] : row.id}
+                  </h4>
+                  <p className="text-xs text-muted-foreground font-mono mt-0.5 opacity-70">{row.id}</p>
+                </div>
+                {statusField && (
+                  <Badge variant={
+                    ['active', 'paid'].includes(String(row[statusField.key]).toLowerCase()) ? 'success' : 
+                    ['pending'].includes(String(row[statusField.key]).toLowerCase()) ? 'warning' : 'secondary'
+                  }>
+                    {row[statusField.key]}
+                  </Badge>
+                )}
+              </div>
+
+              {/* Body: Detailed Fields */}
+              <div className="space-y-1 text-sm text-muted-foreground mb-4">
+                 {meta?.fields
+                   // ✅ FIXED: Explicit FieldDefinition type for 'f'
+                   .filter((f: FieldDefinition) => f.key !== titleField?.key && f.key !== statusField?.key && f.key !== 'id')
+                   .slice(0, 3)
+                   .map((f: FieldDefinition) => (
+                     <div key={f.key} className="flex justify-between border-b border-dashed border-border/50 pb-1 last:border-0">
+                       <span className="opacity-70">{f.label}:</span>
+                       <span className="font-medium text-foreground">
+                         {f.type === 'currency' ? `$${Number(row[f.key]).toLocaleString()}` : 
+                          f.type === 'date' ? new Date(row[f.key]).toLocaleDateString() : row[f.key]}
+                       </span>
+                     </div>
+                   ))}
+              </div>
+
+              {/* Footer: Actions */}
+              <div className="flex gap-2 pt-2 border-t border-border/50">
+                 <Button 
+                   size="sm" 
+                   variant="outline" 
+                   className="flex-1 h-8 text-xs" 
+                   onClick={() => { setCurrentRecord(row); setIsEditOpen(true); }}
+                 >
+                   <Icon name="edit-2" size={12} className="mr-2"/> Edit
+                 </Button>
+                 <Button 
+                   size="sm" 
+                   variant="ghost" 
+                   className="text-destructive hover:bg-destructive/10 px-3 h-8"
+                   onClick={() => { if(confirm('Delete?')) deleteItem(row.id); }}
+                 >
+                   <Icon name="trash-2" size={14} />
+                 </Button>
+              </div>
+
+            </div>
+          ))}
+          
+          {rowData.length === 0 && (
+             <div className="text-center p-8 text-muted-foreground">No records found.</div>
+          )}
+        </div>
+
+      </div>
+
+      <AutoForm
+        isOpen={isEditOpen}
+        onClose={() => setIsEditOpen(false)}
+        onSubmit={handleSave}
+        title={meta?.name || 'Item'}
+        fields={meta?.fields || []}
+        initialData={currentRecord}
+      />
+    </Card>
+  );
+};

package/src/config/app.manifest.ts

@@ -0,0 +1,7 @@
+// packages/kernel/src/config/app.manifest.ts
+export const appManifest = {
+    name: "Ramme Starter",
+    version: "1.0.0",
+    capabilities: ["dashboard", "crm"],
+    navigation: []
+  };

package/src/engine/renderers/DynamicBlock.tsx

@@ -0,0 +1,84 @@
+import React from 'react';
+// @ts-ignore
+import { useGeneratedSignals } from '../runtime/useSignalStore';
+
+interface DynamicBlockProps {
+  block: any;
+  getComponent: (name: string) => React.FC<any>;
+  getMockData: (id: string) => any[];
+}
+
+/**
+ * @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) {
+    case 'fresh': return 'online';
+    case 'stale': return 'warning';
+    case 'disconnected': return 'offline';
+    case 'error': return 'error';
+    default: return 'offline';
+  }
+};
+
+export const DynamicBlock: React.FC<DynamicBlockProps> = ({ block, getComponent, getMockData }) => {
+  const Component = getComponent(block.type);
+  const signals = useGeneratedSignals();
+
+  const { signalId, dataId, ...staticProps } = block.props;
+  
+  const dynamicProps: Record<string, any> = { 
+    ...staticProps,
+    dataId,
+    signalId 
+  };
+
+  // --- DATA INJECTION ---
+  if (dataId) {
+    const resolvedData = getMockData(dataId);
+    dynamicProps.data = resolvedData || [];
+    dynamicProps.rowData = resolvedData || [];
+  }
+
+  // --- SIGNAL INJECTION ---
+  if (signalId && signals && signalId in signals) {
+    // @ts-ignore
+    const signalState = signals[signalId];
+
+    if (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;
+
+      // Extract Status
+      const rawStatus = (isSignalObject && 'status' in signalState)
+        ? signalState.status
+        : 'fresh'; // Default for raw values
+
+      dynamicProps.value = typeof rawValue === 'number' ? rawValue : String(rawValue);
+      
+      // ✅ FIX: Explicitly cast to String to satisfy TypeScript
+      dynamicProps.status = mapSignalStatus(String(rawStatus));
+    } else {
+      dynamicProps.status = mapSignalStatus('disconnected');
+    }
+  }
+
+  return <Component key={block.id} {...dynamicProps} />;
+};

package/src/engine/renderers/DynamicPage.tsx

@@ -0,0 +1,196 @@
+/**
+ * @file packages/kernel/src/engine/renderers/DynamicPage.tsx
+ * @description The main page renderer for the dashboard.
+ * * ARCHITECTURAL ROLE:
+ * This component is the "Engine Room" of the dashboard.
+ * It orchestrates the layout and delegates rendering to DynamicBlock.
+ */
+
+import React, { useMemo, type ReactNode } from 'react';
+import { 
+  Badge, 
+  StatCard, 
+  DeviceCard, 
+  BarChart, 
+  LineChart,
+  Button
+} from '@ramme-io/ui';
+
+// ✅ INTERNAL: Import your SmartTable (Logic Component)
+import { SmartTable } from '../../components/SmartTable';
+
+// ❌ DELETED: No more static data dependency
+// import { DATA_REGISTRY } from '../../data/mockData';
+
+// ✅ NEW: Import the unified Data Hook
+import { useJustInTimeSeeder } from '../runtime/useJustInTimeSeeder';
+
+import { useManifest, useBridgeStatus } from '../runtime/ManifestContext';
+import { Wifi, WifiOff, AlertTriangle, Loader2, Database, Wand2, LayoutTemplate } from 'lucide-react';
+
+// ------------------------------------------------------------------
+// 1. THE SAFETY REGISTRY
+// ------------------------------------------------------------------
+const COMPONENT_REGISTRY: Record<string, React.FC<any>> = {
+  'SmartTable': SmartTable,
+  'DataTable': SmartTable, 
+  'StatCard': StatCard,
+  'DeviceCard': DeviceCard,
+  'BarChart': BarChart,
+  'LineChart': LineChart,
+  'Button': Button,
+  'Unknown': ({ type }: { type: string }) => (
+    <div className="h-24 w-full border-2 border-dashed border-amber-300 bg-amber-50 rounded-lg flex flex-col items-center justify-center text-amber-700 text-sm">
+      <LayoutTemplate className="mb-2 opacity-50" size={20} />
+      <span>Unknown Component: <strong>{type}</strong></span>
+    </div>
+  )
+};
+
+const getComponent = (name: string) => {
+  return COMPONENT_REGISTRY[name] || COMPONENT_REGISTRY['Unknown'];
+};
+
+// ------------------------------------------------------------------
+// 2. ERROR BOUNDARY
+// ------------------------------------------------------------------
+interface ErrorBoundaryProps { children: ReactNode; }
+interface ErrorBoundaryState { hasError: boolean; error: string; }
+
+class BlockErrorBoundary extends React.Component<ErrorBoundaryProps, ErrorBoundaryState> {
+  constructor(props: ErrorBoundaryProps) {
+    super(props);
+    this.state = { hasError: false, error: '' };
+  }
+  static getDerivedStateFromError(error: Error): ErrorBoundaryState {
+    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;
+  }
+}
+
+// ------------------------------------------------------------------
+// 3. DYNAMIC BLOCK (New Sub-Component)
+// ------------------------------------------------------------------
+// We extracted this so we can use hooks (useJustInTimeSeeder) inside.
+const DynamicBlock = ({ block, manifest }: { block: any, manifest: any }) => {
+  const Component = getComponent(block.type);
+  const safeDataId = block.props.dataId?.toLowerCase();
+
+  // 1. Find the Schema (Resource Definition)
+  const resourceDef = useMemo(() => 
+    manifest.resources?.find((r: any) => r.id.toLowerCase() === safeDataId),
+  [manifest, safeDataId]);
+
+  // 2. Fetch Data (Using the Hook!)
+  // This automatically checks LocalStorage first, then falls back to JIT generation.
+  const resolvedData = useJustInTimeSeeder(safeDataId, resourceDef);
+
+  // 3. Detect if Data is JIT Generated (for the UI badge)
+  // Our JIT seeder prefixes IDs with 'jit_', so we can check that.
+  const isGenerated = resolvedData?.[0]?.id?.toString().startsWith('jit_');
+
+  // 4. Auto-Generate Columns (for SmartTable)
+  const autoColumns = useMemo(() => {
+    if (safeDataId && block.type === 'SmartTable' && !block.props.columnDefs && resourceDef) {
+        return 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 undefined;
+  }, [safeDataId, block.type, resourceDef, block.props.columnDefs]);
+
+  return (
+    <div style={{ gridColumn: `span ${block.layout?.colSpan || 1}`, gridRow: `span ${block.layout?.rowSpan || 1}` }} className="relative group">
+       <BlockErrorBoundary>
+          {/* Developer Debug Overlay */}
+          <div className="absolute -top-3 right-0 opacity-0 group-hover:opacity-100 transition-opacity z-20 pointer-events-none translate-y-2 group-hover:translate-y-0 duration-200">
+             <div className={`text-[10px] px-2 py-1 rounded-md shadow-lg border border-white/10 flex items-center gap-1.5 font-mono ${isGenerated ? 'bg-amber-600 text-white' : 'bg-slate-800 text-slate-200'}`}>
+                <span className="font-bold">{block.type}</span>
+                {safeDataId && <> <span className="opacity-40">|</span> {isGenerated ? <Wand2 size={10} className="animate-pulse"/> : <Database size={10}/>} {safeDataId}</>}
+             </div>
+          </div>
+          
+          <Component 
+             {...block.props} 
+             rowData={block.type === 'SmartTable' ? undefined : resolvedData} 
+             columnDefs={block.props.columnDefs || autoColumns}
+             className="w-full h-full" 
+          />
+       </BlockErrorBoundary>
+    </div>
+  );
+};
+
+// ------------------------------------------------------------------
+// 4. THE MAIN PAGE COMPONENT
+// ------------------------------------------------------------------
+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 flex flex-col items-center justify-center h-[50vh]">
+         <Loader2 className="animate-spin text-primary mb-4" size={32} /> 
+         <p className="text-muted-foreground">Loading Blueprint...</p>
+      </div>
+    );
+  }
+
+  const statusBadge = (
+    <div className={`flex items-center gap-2 px-3 py-1.5 rounded-full text-xs font-bold border transition-colors duration-300 ${isLive ? 'bg-green-100 text-green-700 border-green-200' : 'bg-slate-100 text-slate-500 border-slate-200'}`}>
+      {isLive ? <Wifi size={14} className="text-green-600 animate-pulse"/> : <WifiOff size={14} />}
+      {isLive ? 'LIVE BRIDGE' : 'STATIC MODE'}
+    </div>
+  );
+
+  return (
+    <div className="p-6 md:p-8 max-w-7xl mx-auto w-full space-y-8">
+      {/* Header */}
+      <header className="flex flex-col md:flex-row md:items-center justify-between gap-4 border-b border-border/40 pb-6">
+        <div className="space-y-1">
+          <h1 className="text-3xl font-bold tracking-tight text-foreground">{page.title}</h1>
+          {page.description && <p className="text-muted-foreground">{page.description}</p>}
+        </div>
+        <div className="flex items-center gap-2">{statusBadge}</div>
+      </header>
+
+      {/* Main Grid */}
+      <div className="grid gap-8 pb-20">
+        {page.sections?.map((section: any) => (
+          <section key={section.id} className="space-y-6">
+            {section.title && (
+              <div className="flex items-center gap-2 pb-2 border-b border-border/60">
+                 <h3 className="text-sm font-bold uppercase tracking-wider text-muted-foreground/80">{section.title}</h3>
+              </div>
+            )}
+            <div className="grid gap-6" style={{ gridTemplateColumns: `repeat(${section.layout?.columns || 1}, minmax(0, 1fr))` }}>
+              {section.blocks.map((block: any) => (
+                <DynamicBlock 
+                  key={block.id} 
+                  block={block} 
+                  manifest={manifest} 
+                />
+              ))}
+            </div>
+          </section>
+        ))}
+      </div>
+    </div>
+  );
+};

package/src/engine/renderers/route-generator.tsx

@@ -0,0 +1,47 @@
+/**
+ * @file route-generator.tsx
+ * @description This file is the core engine of the Sitemap-Driven Architecture.
+ * Its purpose is to dynamically generate all application routes by reading directly
+ * from a designer-friendly `sitemap` array. This abstracts all routing logic
+ * away from our designers, empowering them to manage the app's structure from
+ * a single, simple configuration file.
+ */
+
+import { Route, Navigate } from 'react-router-dom';
+// CORRECTED IMPORT: Point to the canonical type definition
+import type { SitemapEntry } from './sitemap-entry';
+
+/**
+ * Recursively generates React Router `<Route>` components from a sitemap array.
+ * @param {SitemapEntry[]} routes - The array of sitemap entries to process.
+ * @returns {JSX.Element[]} An array of React Router `<Route>` components.
+ */
+
+export const generateRoutes = (routes: SitemapEntry[]) => {
+  return routes.map((route) => {
+    // Check if the current route is a "parent" route with children
+    if (route.children && route.children.length > 0) {
+      // Get the path of the first child to use for redirection
+      const firstChildPath = route.children[0].path;
+      
+      return (
+        // Create the parent <Route> (e.g., /data)
+        <Route key={route.id} path={route.path} element={<route.component />}>
+          
+          {/* PROFESSIONAL PROTOTYPING: This is a key feature for DX.
+            It creates an "index" route that automatically redirects the user
+            from the parent path (e.g., /data) to its first child (e.g., /data/grid).
+            This prevents designers from ever seeing a blank parent page.
+          */}
+          <Route index element={<Navigate to={firstChildPath} replace />} />
+          
+          {/* Recursively generate all nested child routes */}
+          {generateRoutes(route.children)}
+        </Route>
+      );
+    }
+
+    // Standard case: This is a simple route with no children.
+    return <Route key={route.id} path={route.path} element={<route.component />} />;
+  });
+};

package/src/engine/renderers/sitemap-entry.ts

@@ -0,0 +1,6 @@
+export interface SitemapEntry {
+  id: string;
+  path: string;
+  component: React.ComponentType;
+  children?: SitemapEntry[];
+}