@ramme-io/kernel 1.3.0

package/src/engine/runtime/useSignal.ts

@@ -0,0 +1,40 @@
+import { useMemo } from 'react';
+import { useSignalStore } from './useSignalStore';
+// ❌ REMOVED: import { appManifest } from '../../config/app.manifest';
+// ✅ ADDED: Live Context
+import { useManifest } from './ManifestContext';
+
+export interface SignalState {
+  id: string;
+  value: any;
+  unit?: string;
+  min?: number;
+  max?: number;
+  timestamp?: number;
+  status: 'fresh' | 'stale';
+}
+
+export const useSignal = (signalId: string): SignalState => {
+  const signalData = useSignalStore((state) => state.signals[signalId]);
+  
+  // ✅ 1. Consume Live Manifest
+  const appManifest = useManifest();
+
+  // 2. Get Static Definition from Manifest (Live)
+  const signalDef = useMemo(() => {
+    return appManifest.domain.signals.find((s) => s.id === signalId);
+  }, [signalId, appManifest]); // Re-run if manifest updates
+
+  const value = signalData?.value ?? signalDef?.defaultValue ?? 0;
+  const isStale = signalData ? (Date.now() - signalData.timestamp > 10000) : true;
+
+  return {
+    id: signalId,
+    value: value,
+    unit: signalDef?.unit,
+    min: signalDef?.min,
+    max: signalDef?.max,
+    timestamp: signalData?.timestamp,
+    status: isStale ? 'stale' : 'fresh'
+  };
+};

package/src/engine/runtime/useSignalStore.ts

@@ -0,0 +1,94 @@
+import { create } from 'zustand';
+import { useEffect } from 'react';
+
+/**
+ * @file useSignalStore.ts
+ * @description The "Short-Term Memory" of the application.
+ *
+ * ARCHITECTURAL ROLE:
+ * This Zustand store holds the instantaneous value of every Signal (IoT sensor).
+ * It acts as the buffer between the high-speed data stream (MQTT/Simulation)
+ * and the UI components.
+ */
+
+// --- 1. SIGNAL STORE TYPES ---
+export interface SignalValue {
+  value: any;
+  timestamp: number;
+}
+
+interface SignalStore {
+  signals: Record<string, SignalValue>;
+  // Single update (used by UI controls)
+  updateSignal: (id: string, value: any) => void;
+  // Batch update (used by MQTT/Simulation)
+  updateSignals: (updates: Record<string, any>) => void;
+}
+
+// Initial State matches your dashboard IDs to prevent "undefined" errors on load
+const initialState = {
+  living_room_ac: { value: 72, timestamp: Date.now() },
+  living_room_hum: { value: 45, timestamp: Date.now() },
+  server_01: { value: 42, timestamp: Date.now() },
+  front_door_lock: { value: 'LOCKED', timestamp: Date.now() }
+};
+
+export const useSignalStore = create<SignalStore>((set) => ({
+  signals: initialState,
+  
+  updateSignal: (id, value) => set((state) => ({
+    signals: {
+      ...state.signals,
+      [id]: { value, timestamp: Date.now() }
+    }
+  })),
+
+  updateSignals: (updates) => set((state) => {
+    const newSignals = { ...state.signals };
+    Object.entries(updates).forEach(([id, val]) => {
+      newSignals[id] = { value: val, timestamp: Date.now() };
+    });
+    return { signals: newSignals };
+  })
+}));
+
+/**
+ * Hook to access specific signals in a component.
+ * Usage: const signals = useGeneratedSignals();
+ */
+export const useGeneratedSignals = () => {
+  return useSignalStore((state) => state.signals);
+};
+
+// --- 2. SIMULATION ENGINE (The Missing Piece) ---
+/**
+ * A hook that generates fake data for testing when no MQTT broker is connected.
+ * You can toggle this on/off via the manifest config.
+ */
+export const useSimulation = (isEnabled: boolean = true) => {
+  const { updateSignals } = useSignalStore();
+
+  useEffect(() => {
+    if (!isEnabled) return;
+
+    console.log("[System] Simulation Mode: ON 🎲");
+    const interval = setInterval(() => {
+      // Simulate random fluctuations
+      const updates: Record<string, any> = {};
+      
+      // Randomize values slightly around a baseline
+      updates['living_room_ac'] = Number((72 + (Math.random() * 4 - 2)).toFixed(1));
+      updates['living_room_hum'] = Number((45 + (Math.random() * 6 - 3)).toFixed(1));
+      updates['server_01'] = Math.floor(Math.random() * 100);
+      
+      // Randomly flip the lock status occasionally (1% chance)
+      if (Math.random() > 0.99) {
+         updates['front_door_lock'] = Math.random() > 0.5 ? 'LOCKED' : 'UNLOCKED';
+      }
+      
+      updateSignals(updates);
+    }, 2000); // Update every 2 seconds
+
+    return () => clearInterval(interval);
+  }, [isEnabled, updateSignals]);
+};

package/src/engine/runtime/useWorkflowEngine.ts

@@ -0,0 +1,89 @@
+import { useEffect } from 'react';
+import { useToast } from '@ramme-io/ui';
+import { useGeneratedSignals, useSimulation } from './useSignalStore';
+// ❌ REMOVED: import { appManifest } from '../../config/app.manifest';
+// ✅ ADDED: Live Context
+import { useManifest } from './ManifestContext';
+
+// ... (Interfaces can remain the same) ...
+interface ActionDefinition { type: string; config: Record<string, any>; }
+interface WorkflowDefinition { id: string; name: string; active: boolean; trigger: { type: string; config: { signalId: string; condition: string; }; }; actions: ActionDefinition[]; }
+
+export const useWorkflowEngine = () => {
+  const signals = useGeneratedSignals();
+  const { addToast } = useToast();
+  
+  // ✅ 1. Consume Live Manifest
+  const appManifest = useManifest();
+
+  // 2. Activate Simulation (Responsive to toggle)
+  useSimulation(appManifest.config.mockMode);
+
+  const executeAction = async (action: ActionDefinition, context: any) => {
+    // ... (Same execution logic as before) ...
+    console.log(`[Engine] Executing: ${action.type}`, action);
+    switch (action.type) {
+      case 'send_notification': addToast(action.config.message || 'Notification Sent', 'info'); break;
+      case 'update_resource': addToast(`Updating Resource: ${JSON.stringify(action.config)}`, 'success'); break;
+      case 'navigate': window.location.href = action.config.path; break;
+      case 'agent_task': 
+        addToast('AI Agent Analyzing...', 'info');
+        setTimeout(() => addToast('🤖 Agent: "System Nominal"', 'success', 3000), 1500);
+        break;
+    }
+  };
+
+  // 3. Watch Signals & Trigger Workflows (Live)
+  useEffect(() => {
+    if (!appManifest.domain?.workflows) return;
+
+    (appManifest.domain.workflows as unknown as WorkflowDefinition[]).forEach((flow) => {
+      if (!flow.active) return;
+
+      if (flow.trigger.type === 'signal_change') {
+        const signalId = flow.trigger.config.signalId;
+        const condition = flow.trigger.config.condition;
+        
+        // @ts-ignore
+        const signal = signals[signalId];
+        
+        if (signal) {
+          const val = signal.value;
+          try {
+            const isMet = checkCondition(val, condition); 
+            if (isMet) {
+              console.log(`[Engine] Trigger Fired: ${flow.name}`);
+              flow.actions.forEach(action => executeAction(action, { signal: val }));
+            }
+          } catch (e) {}
+        }
+      }
+    });
+  }, [signals, addToast, appManifest.domain.workflows]); // Added dependency
+
+  return { 
+    triggerWorkflow: (workflowId: string) => {
+      // ✅ 4. Manual Triggers now find new workflows instantly
+      const flow = appManifest.domain?.workflows?.find(w => w.id === workflowId);
+      if (flow) {
+        // @ts-ignore
+        flow.actions.forEach(action => executeAction(action, { manual: true }));
+      }
+    }
+  };
+};
+
+const checkCondition = (value: number, condition: string): boolean => {
+  if (!condition) return false;
+  const parts = condition.trim().split(' ');
+  const operator = parts[0];
+  const target = parseFloat(parts[1]);
+  switch (operator) {
+    case '>': return value > target;
+    case '<': return value < target;
+    case '>=': return value >= target;
+    case '<=': return value <= target;
+    case '==': return value === target;
+    default: return false;
+  }
+};

package/src/engine/types/manifest-types.ts

@@ -0,0 +1,45 @@
+// src/core/manifest-types.ts
+
+import { type IconName } from '@ramme-io/ui';
+
+/**
+ * Defines a simple navigation link structure used in menus.
+ */
+export interface ManifestLink {
+  id: string;
+  title: string;
+  path: string;
+  icon?: IconName;
+}
+
+/**
+ * The fundamental unit of the UI.
+ * Corresponds to a specific React component in the registry.
+ */
+export interface Block {
+  id: string;
+  type: string; // e.g., 'DeviceCard', 'StatCard', 'LineChart'
+  props: Record<string, any>; // Static props (title, default values)
+  layout?: {
+    colSpan?: number;
+    rowSpan?: number;
+  };
+}
+
+/**
+ * A horizontal container that groups blocks together.
+ * Maps to a CSS Grid or Flex container.
+ */
+export interface PageSection {
+  id: string;
+  title?: string;
+  description?: string;
+  layout?: {
+    columns?: number; // e.g., 3 (for a 3-column grid)
+    variant?: 'grid' | 'stack';
+  };
+  blocks: Block[];
+}
+
+// Note: PageDefinition and AppSpecification are exported from schema.ts
+// These types are kept here for backward compatibility but should use schema.ts types instead

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

@@ -0,0 +1,66 @@
+/**
+ * @file sitemap-entry.ts
+ * @repository ramme-app-starter
+ * @description This file defines the canonical TypeScript interface for a single
+ * sitemap entry. It is the "schema" or "contract" that governs the entire
+ * Sitemap-Driven Architecture.
+ *
+ * STRATEGIC IMPORTANCE:
+ * 1. Designer DX: It provides strict type-safety and autocompletion for any
+ * designer editing a `sitemap.ts` file, dramatically lowering the risk of errors.
+ * 2. Repo-Linking: It directly imports `IconName` from `@ramme-io/ui`, creating
+ * a type-safe link between our starter kit and our component library.
+ * 3. AI-Ready: This interface is the precise data structure that the AI Assistant
+ * in the (private) `ramme-app-builder` will be trained to generate.
+ * The "Architect" phase of the A.D.A.P.T. Framework will result in the
+ * AI creating an array of these objects.
+ */
+
+// Import the type definition for all available icon names from our open-source
+// UI library. This is a critical integration point.
+import { type IconName } from '@ramme-io/ui';
+
+/**
+ * Defines the required shape for a single entry in any `sitemap.ts` file.
+ */
+export interface SitemapEntry {
+  /**
+   * A unique string identifier.
+   * Used by React as the `key` prop during route generation.
+   * e.g., 'dashboard.home'
+   */
+  id: string;
+
+  /**
+   * The URL path segment for this route.
+   * e.g., 'home', 'users', 'settings'
+   */
+  path: string;
+
+  /**
+   * The human-readable name for the route.
+   * Used to populate navigation links, breadcrumbs, and page titles.
+   * e.g., 'Home', 'User Management'
+   */
+  title: string;
+
+  /**
+   * (Optional) The name of the icon to display in the navigation.
+   * This MUST be a valid `IconName` from the `@ramme-io/ui` library.
+   * e.g., 'home', 'users', 'settings'
+   */
+  icon?: IconName;
+
+  /**
+   * The actual React component to render when this route is active.
+   * e.g., DashboardPage, SettingsPage
+   */
+  component: React.ComponentType;
+
+  /**
+   * (Optional) An array of nested `SitemapEntry` objects.
+   * This is the property that enables recursive, nested navigation
+   * (e.g., /settings/profile, /settings/billing).
+   */
+  children?: SitemapEntry[];
+}

package/src/engine/validation/schema.ts

@@ -0,0 +1,189 @@
+import { z } from 'zod';
+
+/**
+ * @file schema.ts
+ * @description The "Application Constitution".
+ *
+ * ARCHITECTURAL ROLE:
+ * This file uses Zod to define the strict runtime validation rules for the 
+ * App Manifest. While `manifest-types.ts` handles compile-time TypeScript checks,
+ * this file handles runtime validation, ensuring that any JSON loaded into the 
+ * engine (whether from a file, API, or user input) is structurally sound.
+ *
+ * LAYERS DEFINED:
+ * 1. **SaaS Layer:** Data resources, fields, and tables.
+ * 2. **Physical Layer:** IoT signals, sensors, and entities.
+ * 3. **Logic Layer:** Workflows, triggers, and automated actions.
+ * 4. **Presentation Layer:** Pages, sections, and UI blocks.
+ */
+
+// ------------------------------------------------------------------
+// 1. DATA RESOURCE DEFINITIONS (SaaS Layer)
+// ------------------------------------------------------------------
+
+export const FieldSchema = z.object({
+  key: z.string(),
+  label: z.string(),
+  type: z.enum(['text', 'number', 'currency', 'date', 'boolean', 'status', 'email', 'image', 'textarea']),
+  required: z.boolean().optional(),
+  description: z.string().optional(),
+  defaultValue: z.any().optional(),
+});
+export type FieldDefinition = z.infer<typeof FieldSchema>;
+
+export const ResourceSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  fields: z.array(FieldSchema),
+  defaultView: z.enum(['table', 'grid', 'list']).optional(),
+  features: z.object({
+    searchable: z.boolean().optional(),
+    creatable: z.boolean().optional(),
+    editable: z.boolean().optional(),
+    deletable: z.boolean().optional(),
+    exportable: z.boolean().optional(),
+  }).optional(),
+});
+export type ResourceDefinition = z.infer<typeof ResourceSchema>;
+
+
+// ------------------------------------------------------------------
+// 2. SIGNAL & IOT DEFINITIONS (Physical Layer)
+// ------------------------------------------------------------------
+
+export const SignalSchema = z.object({
+  id: z.string().min(1, "Signal ID is required"),
+  label: z.string(),
+  description: z.string().optional(),
+  kind: z.enum(['sensor', 'actuator', 'setpoint', 'metric', 'status', 'kpi']),
+  source: z.enum(['mock', 'mqtt', 'http', 'derived', 'local']),
+  
+  // Connectivity
+  topic: z.string().optional(),      
+  endpoint: z.string().optional(),   
+  jsonPath: z.string().optional(),   
+  refreshRate: z.number().optional().default(1000), 
+  
+  // Values
+  defaultValue: z.any().optional(),
+  unit: z.string().optional(),       
+  min: z.number().optional(),
+  max: z.number().optional(),
+});
+export type SignalDefinition = z.infer<typeof SignalSchema>;
+
+export const EntitySchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  description: z.string().optional(),
+  type: z.string(), 
+  category: z.string().default('logical'), 
+  signals: z.array(z.string()), 
+  ui: z.object({
+    icon: z.string().optional(), 
+    color: z.string().optional(),
+    dashboardComponent: z.string().optional(),
+  }).optional(),
+});
+export type EntityDefinition = z.infer<typeof EntitySchema>;
+
+// ------------------------------------------------------------------
+// ✅ NEW: LOGIC & WORKFLOW DEFINITIONS
+// ------------------------------------------------------------------
+
+export const TriggerSchema = z.object({
+  id: z.string(),
+  type: z.enum(['signal_change', 'manual_action', 'schedule', 'webhook']),
+  config: z.record(z.string(), z.any()), 
+});
+
+export const ActionSchema = z.object({
+  id: z.string(),
+  type: z.enum([
+    'update_resource', 
+    'send_notification', 
+    'mqtt_publish', 
+    'api_call', 
+    'navigate', 
+    'agent_task'
+  ]),
+  config: z.record(z.string(), z.any()),
+});
+
+export const WorkflowSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  active: z.boolean().default(true),
+  trigger: TriggerSchema,
+  actions: z.array(ActionSchema),
+});
+export type WorkflowDefinition = z.infer<typeof WorkflowSchema>;
+export type ActionDefinition = z.infer<typeof ActionSchema>;
+
+
+// ------------------------------------------------------------------
+// 3. UI LAYOUT DEFINITIONS (Presentation Layer)
+// ------------------------------------------------------------------
+
+export const BlockSchema = z.object({
+  id: z.string(),
+  type: z.string(),
+  props: z.record(z.string(), z.any()), 
+  layout: z.object({
+    colSpan: z.number().optional(),
+    rowSpan: z.number().optional(),
+  }).optional(),
+});
+
+export const PageSectionSchema = z.object({
+  id: z.string(),
+  title: z.string().optional(),
+  description: z.string().optional(),
+  layout: z.object({ 
+    columns: z.number().optional(), 
+    variant: z.enum(['grid', 'stack', 'split']).optional() 
+  }).optional(),
+  blocks: z.array(BlockSchema),
+});
+
+export const PageSchema = z.object({
+  id: z.string(),
+  slug: z.string(),
+  title: z.string(),
+  description: z.string().optional(),
+  icon: z.string().optional(),
+  sections: z.array(PageSectionSchema),
+});
+export type PageDefinition = z.infer<typeof PageSchema>;
+
+
+// MASTER APP SPECIFICATION
+export const AppSpecificationSchema = z.object({
+  meta: z.object({
+    name: z.string(),
+    version: z.string(),
+    description: z.string().optional(),
+    author: z.string().optional(),
+    createdAt: z.string().optional(),
+  }),
+  
+  config: z.object({
+    theme: z.enum(['light', 'dark', 'system', 'corporate', 'midnight', 'blueprint']).default('system'),
+    mockMode: z.boolean().default(true),
+    brokerUrl: z.string().optional(),
+  }),
+
+  modules: z.array(z.string()).optional(),
+  resources: z.array(ResourceSchema).optional(),
+  
+  domain: z.object({
+    signals: z.array(SignalSchema),
+    entities: z.array(EntitySchema),
+    // ✅ ADDED WORKFLOWS HERE
+    workflows: z.array(WorkflowSchema).optional(),
+  }),
+
+  pages: z.array(PageSchema).optional(),
+});
+
+export type AppSpecification = z.infer<typeof AppSpecificationSchema>;

package/src/index.ts

@@ -0,0 +1,27 @@
+// Engine exports
+export * from './engine/runtime/ManifestContext';
+export * from './engine/runtime/MqttContext';
+export * from './engine/runtime/SitemapContext';
+export * from './engine/runtime/useAction';
+export * from './engine/runtime/useCrudLocalStorage';
+export * from './engine/runtime/useDataQuery';
+export * from './engine/runtime/useDynamicSitemap';
+export * from './engine/runtime/useJustInTimeSeeder';
+export * from './engine/runtime/useLiveBridge';
+export * from './engine/runtime/useSignal';
+export * from './engine/runtime/useSignalStore';
+export * from './engine/runtime/useWorkflowEngine';
+export * from './engine/runtime/data-seeder';
+
+export * from './engine/renderers/DynamicBlock';
+export * from './engine/renderers/DynamicPage';
+export * from './engine/renderers/route-generator';
+
+export * from './engine/types/manifest-types';
+export * from './engine/types/sitemap-entry';
+
+export * from './engine/validation/schema';
+
+// Component exports
+export { SmartTable } from './components/SmartTable';
+export { AutoForm } from './components/AutoForm';

package/tsconfig.json

@@ -0,0 +1,28 @@
+{
+    "compilerOptions": {
+      /* React Configuration (CRITICAL) */
+      "jsx": "react-jsx",
+      "types": ["node", "react", "react-dom"],
+      
+      /* Base Options */
+      "target": "ES2020",
+      "module": "ESNext",
+      "lib": ["ES2020", "DOM", "DOM.Iterable"],
+      "skipLibCheck": true,
+      
+      /* Module Resolution */
+      "moduleResolution": "bundler",
+      "resolveJsonModule": true,
+      "isolatedModules": true,
+      "esModuleInterop": true,
+  
+      /* Build Output */
+      "outDir": "dist",
+      "rootDir": "src",
+      "declaration": true,
+      "declarationMap": true,
+      "sourceMap": true,
+      "noEmit": false
+    },
+    "include": ["src"]
+  }