@ramme-io/kernel 1.3.0

package/src/engine/runtime/ManifestContext.tsx

@@ -0,0 +1,81 @@
+import React, { createContext, useContext, useEffect, useState, useRef } from 'react';
+// ✅ FIX 2: Correct Path to Types
+import type { AppSpecification } from '../validation/schema';
+
+interface ManifestContextType {
+  manifest: AppSpecification;
+  isLive: boolean;
+}
+
+const ManifestContext = createContext<ManifestContextType | null>(null);
+
+interface ManifestProviderProps {
+  children: React.ReactNode;
+  manifest: AppSpecification;
+}
+
+export const ManifestProvider: React.FC<ManifestProviderProps> = ({ children, manifest: initialManifest }) => {
+  // 1. Initialize State
+  const [manifest, setManifest] = useState<AppSpecification>(initialManifest);
+  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) {
+    throw new Error('useManifest must be used within a ManifestProvider');
+  }
+  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/src/engine/runtime/MqttContext.tsx

@@ -0,0 +1,94 @@
+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;
+  lastMessage: Record<string, string>;
+  publish: (topic: string, message: string) => void;
+  subscribe: (topic: string) => void;
+  unsubscribe: (topic: string) => void;
+}
+
+const MqttContext = createContext<MqttContextType | null>(null);
+
+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);
+  const subscriptions = useRef<Set<string>>(new Set());
+
+  // ✅ 1. Consume Live Manifest
+  const appManifest = useManifest();
+
+  useEffect(() => {
+    // ✅ 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}...`);
+    
+    // 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: string, payload: Buffer) => {
+      const messageStr = payload.toString();
+      setLastMessage((prev) => ({ ...prev, [topic]: messageStr }));
+    });
+
+    client.on('error', (err) => {
+      console.error('[MQTT] Connection error: ', err);
+      client.end();
+    });
+
+    return () => {
+      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)) {
+      clientRef.current.subscribe(topic);
+      subscriptions.current.add(topic);
+    }
+  };
+
+  const unsubscribe = (topic: string) => {
+    if (clientRef.current && subscriptions.current.has(topic)) {
+      clientRef.current.unsubscribe(topic);
+      subscriptions.current.delete(topic);
+    }
+  };
+
+  const publish = (topic: string, message: string) => {
+    if (clientRef.current) {
+      clientRef.current.publish(topic, message);
+    }
+  };
+
+  return (
+    <MqttContext.Provider value={{ isConnected, lastMessage, subscribe, unsubscribe, publish }}>
+      {children}
+    </MqttContext.Provider>
+  );
+};
+
+export const useMqtt = () => {
+  const context = useContext(MqttContext);
+  if (!context) throw new Error('useMqtt must be used within an MqttProvider');
+  return context;
+};

package/src/engine/runtime/SitemapContext.tsx

@@ -0,0 +1,61 @@
+/**
+ * @file SitemapContext.tsx
+ * @repository ramme-app-starter
+ * @description This file implements a React Context for the sitemap.
+ *
+ * STRATEGIC IMPORTANCE:
+ * This context is the "plumbing" that makes our swappable layout
+ * strategy possible. It allows a top-level layout component (like
+ * `DashboardLayout.tsx` or `DocsLayout.tsx`) to "provide" its specific
+ * sitemap array (e.g., `dashboard.sitemap.ts`) to all of its children.
+ *
+ * Any component deep in the tree (like a sidebar, breadcrumbs, or page
+ * header) can then "consume" this sitemap data using the `useSitemap`
+ * hook to render the correct navigation, titles, and icons.
+ *
+ * This effectively decouples the navigation UI from the sitemap data,
+ * allowing us to change the entire application's IA simply by changing
+ * the data provided by the `SitemapProvider`.
+ */
+
+import { createContext, useContext } from 'react';
+// Import the canonical "schema" for a sitemap entry
+import type { SitemapEntry } from '../types/sitemap-entry';
+
+// 1. Create the context
+// We initialize it with an empty array as a safe default.
+// This context will hold the sitemap array specific to the active layout.
+const SitemapContext = createContext<SitemapEntry[]>([]);
+
+/**
+ * A custom hook to easily access the active sitemap array.
+ * This abstracts the `useContext` logic and provides a clean API
+ * for components that need to read the sitemap.
+ *
+ * @returns {SitemapEntry[]} The sitemap array provided by the nearest
+ * `SitemapProvider`.
+ */
+export const useSitemap = () => {
+  const context = useContext(SitemapContext);
+
+  // This is a critical developer-friendly check.
+  // If a component tries to call `useSitemap` outside of a layout
+  // that provides the context, we throw an explicit error.
+  if (context === undefined) {
+    throw new Error('useSitemap must be used within a SitemapProvider');
+  }
+  
+  return context;
+};
+
+// 3. Export the Provider
+// We export the Provider component directly. This is what our layout
+// components will use to wrap their content and supply the sitemap data.
+//
+// Example Usage (in a layout file):
+// <SitemapProvider value={dashboardSitemap}>
+//   <AppHeader />
+//   <AppSidebar />
+//   <Outlet />
+// </SitemapProvider>
+export const SitemapProvider = SitemapContext.Provider;

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

@@ -0,0 +1,39 @@
+/**
+ * @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
+ * provided by the Kernel/Manifest into the browser's storage.
+ */
+
+// 🔒 CRITICAL FIX: Changed from 'ramme_mock_' to 'ramme_db_' to match AuthContext
+// This ensures that the AuthProvider can actually find the 'users' table we seed.
+const DB_PREFIX = 'ramme_db_';
+
+export const initializeDataLake = (registry: Record<string, any[]>) => {
+  if (typeof window === 'undefined') return;
+
+  // Safety check: Don't crash if the registry is missing (e.g. during early boot)
+  if (!registry) {
+    console.warn('⚠️ [Data Lake] No registry provided to seeder. Skipping initialization.');
+    return;
+  }
+
+  console.groupCollapsed('🌊 [Data Lake] Initialization');
+  
+  Object.entries(registry).forEach(([key, seedData]) => {
+    const storageKey = `${DB_PREFIX}${key}`; 
+    const existing = localStorage.getItem(storageKey);
+
+    if (!existing) {
+      console.log(`✨ Seeding collection: ${key}`);
+      localStorage.setItem(storageKey, JSON.stringify(seedData));
+    } else {
+        // Optional: Debug log for existing data (helps verify persistence)
+        // console.log(`✅ Found existing data for: ${key}`);
+    }
+  });
+  
+  console.groupEnd();
+};

package/src/engine/runtime/useAction.ts

@@ -0,0 +1,64 @@
+import { useCallback } from 'react';
+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) => {
+    // 2. Find the Entity definition (Live)
+    const entity = domain.entities.find(e => e.id === entityId);
+    
+    if (!entity) {
+      console.warn(`[Action] Entity ID '${entityId}' not found in manifest.`);
+      return;
+    }
+
+    const signalId = entity.signals[0];
+    const signal = domain.signals.find(s => s.id === signalId);
+
+    if (!signal) {
+      console.warn(`[Action] No signal linked to entity: ${entityId}`);
+      return;
+    }
+
+    // --- Mock Mode ---
+    if (config.mockMode) {
+      console.log(`%c[Mock Action] Setting ${entity.name} to:`, 'color: #10b981; font-weight: bold;', value);
+      return;
+    }
+
+    // --- Live Mode (MQTT) ---
+    if (signal.source === 'mqtt' && signal.topic) {
+      if (!isConnected) {
+        console.warn('[Action] Cannot send: MQTT disconnected');
+        return;
+      }
+      const payload = typeof value === 'object' ? JSON.stringify(value) : String(value);
+      console.log(`[MQTT] Publishing to '${signal.topic}': ${payload}`);
+      publish(signal.topic, payload);
+    }
+
+    // --- Live Mode (HTTP) ---
+    if (signal.source === 'http' && signal.endpoint) {
+      try {
+        await fetch(signal.endpoint, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ id: signal.id, value })
+        });
+      } catch (err) {
+        console.log('[HTTP] (Simulation) Request sent.');
+      }
+    }
+
+  }, [config.mockMode, isConnected, publish, domain]);
+
+  return { sendAction };
+};

package/src/engine/runtime/useCrudLocalStorage.ts

@@ -0,0 +1,82 @@
+import { useState, useCallback } from 'react';
+
+/**
+ * @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 (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.
+ */
+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) {
+        return JSON.parse(item);
+      } else {
+        // Seed the "DB" if empty
+        window.localStorage.setItem(storageKey, JSON.stringify(initialData));
+        return initialData;
+      }
+    } catch (error) {
+      console.error(`[Data Lake] Error reading key "${storageKey}":`, error);
+      return initialData;
+    }
+  });
+
+  // 2. CREATE
+  const createItem = useCallback((newItem: Omit<T, 'id'>) => {
+    setData(prevData => {
+      // ✅ 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));
+      return updatedData;
+    });
+  }, [storageKey]);
+
+  // 3. UPDATE
+  const updateItem = useCallback((updatedItem: T) => {
+    setData(prevData => {
+      const updatedData = prevData.map(item =>
+        item.id === updatedItem.id ? updatedItem : item
+      );
+      window.localStorage.setItem(storageKey, JSON.stringify(updatedData));
+      return updatedData;
+    });
+  }, [storageKey]);
+
+  // 4. DELETE
+  const deleteItem = useCallback((id: T['id']) => {
+    setData(prevData => {
+      const updatedData = prevData.filter(item => item.id !== id);
+      window.localStorage.setItem(storageKey, JSON.stringify(updatedData));
+      return updatedData;
+    });
+  }, [storageKey]);
+
+  return { data, createItem, updateItem, deleteItem };
+};

package/src/engine/runtime/useDataQuery.ts

@@ -0,0 +1,98 @@
+import { useMemo } from 'react';
+
+/**
+ * @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';
+
+export interface SortOption {
+  field: string;
+  direction: SortDirection;
+}
+
+export interface FilterOption {
+  field: string;
+  operator: 'equals' | 'contains' | 'gt' | 'lt' | 'neq';
+  value: any;
+}
+
+export interface QueryOptions {
+  filters?: FilterOption[];
+  sort?: SortOption;
+  page?: number;
+  pageSize?: number;
+}
+
+export interface QueryResult<T> {
+  data: T[];
+  total: number;
+  pageCount: number;
+}
+
+// --- 2. Update the Hook Signature (Fixes ts(2345)) ---
+
+export function useDataQuery<T>(
+  rawData: T[], // <--- Now accepts an Array, NOT a string ID
+  options: QueryOptions = {}
+): QueryResult<T> {
+  const { filters, sort, page = 1, pageSize = 10 } = options;
+
+  // A. Filtering Logic
+  const filteredData = useMemo(() => {
+    if (!filters || filters.length === 0) return rawData;
+
+    return rawData.filter((item: any) => {
+      return filters.every((filter) => {
+        const itemValue = item[filter.field];
+        
+        switch (filter.operator) {
+          case 'equals': return itemValue == filter.value;
+          case 'neq': return itemValue != filter.value;
+          case 'contains': 
+            return String(itemValue).toLowerCase().includes(String(filter.value).toLowerCase());
+          case 'gt': return itemValue > filter.value;
+          case 'lt': return itemValue < filter.value;
+          default: return true;
+        }
+      });
+    });
+  }, [rawData, filters]);
+
+  // B. Sorting Logic
+  const sortedData = useMemo(() => {
+    if (!sort) return filteredData;
+
+    return [...filteredData].sort((a: any, b: any) => {
+      const aValue = a[sort.field];
+      const bValue = b[sort.field];
+      if (aValue < bValue) return sort.direction === 'asc' ? -1 : 1;
+      if (aValue > bValue) return sort.direction === 'asc' ? 1 : -1;
+      return 0;
+    });
+  }, [filteredData, sort]);
+
+  // C. Pagination Logic
+  const paginatedResult = useMemo(() => {
+    const startIndex = (page - 1) * pageSize;
+    return sortedData.slice(startIndex, startIndex + pageSize);
+  }, [sortedData, page, pageSize]);
+
+  return {
+    data: paginatedResult,
+    total: filteredData.length,
+    pageCount: Math.ceil(filteredData.length / pageSize),
+  };
+}

package/src/engine/runtime/useDynamicSitemap.tsx

@@ -0,0 +1,43 @@
+import { useMemo } from 'react';
+import { useManifest, useBridgeStatus } from './ManifestContext';
+import { DynamicPage } from '../renderers/DynamicPage';
+import { type SitemapEntry } from '../types/sitemap-entry';
+import { type IconName } from '@ramme-io/ui';
+
+/**
+ * @hook useDynamicSitemap
+ * @description 
+ * - In 'Static Mode' (npm run dev): Merges dynamic pages with the hardcoded sitemap.
+ * - In 'Live Mode' (Builder): REPLACES the sitemap entirely to show only the user's design.
+ */
+export const useDynamicSitemap = (staticSitemap: SitemapEntry[]) => {
+  const manifest = useManifest();
+  const status = useBridgeStatus();
+  const isLive = status === 'live'; // ✅ Detect Live Mode
+
+  return useMemo(() => {
+    // 1. Convert Manifest Pages -> Sitemap Entries
+    const dynamicEntries: SitemapEntry[] = (manifest.pages || []).map((page) => ({
+      id: page.id,
+      path: page.slug,
+      title: page.title,
+      icon: (page.icon as IconName) || 'layout',
+      component: () => <DynamicPage pageId={page.id} />
+    }));
+
+    // 2. ✅ OPTIMIZATION: Exclusive Mode
+    // If we are connected to the Builder (Live) AND have dynamic content,
+    // we drop the static "Showcase" pages. 
+    // This makes the Kernel feel like a blank slate to the user.
+    if (isLive && dynamicEntries.length > 0) {
+        // console.log("🚀 [Sitemap] Live Mode Active: Hiding static pages.");
+        return dynamicEntries;
+    }
+
+    // 3. Static/Hybrid Mode (Keep existing logic for local dev)
+    const staticIds = new Set(staticSitemap.map(s => s.id));
+    const uniqueDynamic = dynamicEntries.filter(d => !staticIds.has(d.id));
+
+    return [...staticSitemap, ...uniqueDynamic];
+  }, [manifest, staticSitemap, isLive]);
+};

package/src/engine/runtime/useJustInTimeSeeder.ts

@@ -0,0 +1,101 @@
+/**
+ * @file useJustInTimeSeeder.ts
+ * @description Runtime Data Generator for the Preview Engine.
+ * * ARCHITECTURAL NOTE:
+ * This hook is "Storage Aware." It does not import static files.
+ * It checks the 'ramme_db_' keys in localStorage (which were seeded by main.tsx).
+ * If data exists, it uses it. If not, it procedurally generates it.
+ */
+
+import { useMemo } from 'react';
+
+import type { ResourceDefinition, FieldDefinition } from '../validation/schema';
+
+// Match the prefix defined in data-seeder.ts
+const DB_PREFIX = 'ramme_db_';
+
+// Helper: Generate a semi-realistic value based on field type
+const generateValue = (field: FieldDefinition, index: number) => {
+  const i = index + 1;
+  const label = field.label || 'Item';
+  
+  switch (field.type) {
+    case 'text': 
+      return `${label} ${i}`;
+    case 'number': 
+      return Math.floor(Math.random() * 100) + 1;
+    case 'currency': 
+      return (Math.random() * 1000).toFixed(2);
+    case 'boolean': 
+      return Math.random() > 0.5;
+    case 'date': 
+      const d = new Date();
+      d.setDate(d.getDate() - (i * 2));
+      return d.toISOString().split('T')[0]; // Simple YYYY-MM-DD
+    case 'status': 
+      return ['Active', 'Pending', 'Inactive', 'Archived'][index % 4];
+    case 'email': 
+      return `user${i}@example.com`;
+    case 'image':
+      return `https://i.pravatar.cc/150?u=${i}`;
+    case 'textarea':
+      return `This is a sample description for ${label} ${i}. It contains enough text to test multi-line rendering.`;
+    default: 
+      return `${label}-${i}`;
+  }
+};
+
+export const useJustInTimeSeeder = (dataId: string, resourceDef?: ResourceDefinition | null) => {
+  return useMemo(() => {
+    if (!dataId) return [];
+
+    // 1. Priority: The Data Lake (Static Seed + User Edits)
+    // We trust that main.tsx has already seeded the "Golden Copy" from mockData.ts
+    // into localStorage. This ensures we see the EXACT same data as the rest of the app.
+    if (typeof window !== 'undefined') {
+      const storageKey = `${DB_PREFIX}${dataId}`;
+      const localData = localStorage.getItem(storageKey);
+      
+      if (localData) {
+        try {
+          const parsed = JSON.parse(localData);
+          // Only return if we actually have rows
+          if (Array.isArray(parsed) && parsed.length > 0) {
+            return parsed;
+          }
+        } catch (e) {
+          console.warn(`[JIT Seeder] Corrupt data in ${storageKey}, falling back to generation.`);
+        }
+      }
+    }
+
+    // 2. Fallback: JIT Generation (The "Safety Net")
+    // If we have a schema but absolutely zero data in storage, generate it now.
+    if (resourceDef) {
+      console.log(`🌱 [JIT Seeder] Generating 5 mock records for: ${dataId}`);
+      
+      const generatedData = Array.from({ length: 5 }).map((_, idx) => {
+        const row: Record<string, any> = { 
+          // Generate a robust ID that won't collide with future real IDs
+          id: `jit_${dataId}_${idx + 1}` 
+        };
+        
+        resourceDef.fields.forEach(field => {
+          if (field.key !== 'id') {
+            row[field.key] = generateValue(field, idx);
+          }
+        });
+        
+        return row;
+      });
+
+      // OPTIONAL: Persist this generated data so it doesn't regenerate on reload?
+      // localStorage.setItem(`${DB_PREFIX}${dataId}`, JSON.stringify(generatedData));
+      
+      return generatedData;
+    }
+
+    // 3. Empty State (No data, no schema)
+    return [];
+  }, [dataId, resourceDef]);
+};

package/src/engine/runtime/useLiveBridge.ts

@@ -0,0 +1,24 @@
+import { useState, useEffect } from 'react';
+import { AppSpecification } from '../validation/schema';
+import { useMqtt } from './MqttContext';
+
+const staticManifest = { name: 'loading', version: '0.0.0', capabilities: [], navigation: [] };
+
+export function useLiveBridge() {
+  // 👇 FIX: Cast the initial state to satisfy the compiler
+  const [manifest, setManifest] = useState<AppSpecification>(staticManifest as unknown as AppSpecification);
+  const { lastMessage, isConnected } = useMqtt();
+
+  useEffect(() => {
+    if (lastMessage && lastMessage.topic === 'ramme/manifest/update') {
+      try {
+        const payload = JSON.parse(lastMessage.payload.toString());
+        setManifest(payload);
+      } catch (e) {
+        console.error('Failed to parse manifest update', e);
+      }
+    }
+  }, [lastMessage]);
+
+  return { manifest, isLive: isConnected };
+}