npm package: @ramme-io/kernel
Description: [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
Latest version: 2.1.1

# @ramme-io/kernel

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**The core routing, rendering, and state engine for Ramme applications.**

The Kernel is the brain of every Ramme app. It reads your declarative configuration files (`app.manifest.ts` and `sitemap.ts`), constructs the routing tree, and dynamically renders the correct components via the component registry — all without you writing a single line of routing code.

---

## Architecture

The Kernel operates on three core inputs:

### 1. The Manifest (`app.manifest.ts`)

The global configuration for your application. Defines the app title, description, default theme, and high-level settings.

```typescript
// src/config/app.manifest.ts
export const appManifest = {
  name: 'My Ramme App',
  description: 'A hardware-accelerated dashboard.',
  theme: 'midnight',
  version: '1.0.0',
};
```

### 2. The Sitemap (`sitemap.ts`)

The declarative routing and navigation structure. Each entry defines a page, its path, the component to render, and its position in the navigation hierarchy.

```typescript
// src/config/sitemap.ts
export const sitemap = [
  {
    path: '/',
    label: 'Dashboard',
    icon: 'layout-dashboard',
    component: 'DashboardPage',
  },
  {
    path: '/settings',
    label: 'Settings',
    icon: 'settings',
    component: 'SettingsPage',
  },
];
```

### 3. The Component Registry (`component-registry.tsx`)

Maps the string-based component names from the sitemap to actual React components. This is what allows the Kernel to dynamically render your pages without hardcoded imports in the router.

```tsx
// src/core/component-registry.tsx
import { lazy } from 'react';

export const componentRegistry: Record<string, React.LazyExoticComponent<any>> = {
  DashboardPage: lazy(() => import('../pages/DashboardPage')),
  SettingsPage: lazy(() => import('../pages/SettingsPage')),
};
```

---

## How It Works

1. **Boot** — The Kernel reads `app.manifest.ts` and applies global settings (theme, metadata).
2. **Parse** — It ingests `sitemap.ts` and constructs a routing tree from the declarative page definitions.
3. **Resolve** — For each route, the Kernel looks up the `component` key in the component registry.
4. **Render** — The resolved React component is lazy-loaded and rendered inside the application shell.

The developer never writes `<Route>` elements manually. The Kernel handles all routing, code-splitting, and navigation generation from the sitemap alone.

---

## Integration

In a standard Ramme app (generated by `@ramme-io/create-app`), the Kernel is pre-wired. If integrating manually:

```tsx
import { ManifestProvider } from '@ramme-io/kernel';
import { appManifest } from './config/app.manifest';
import { sitemap } from './config/sitemap';
import { componentRegistry } from './core/component-registry';

export default function App() {
  return (
    <ManifestProvider
      manifest={appManifest}
      sitemap={sitemap}
      registry={componentRegistry}
    >
      {/* The Kernel renders your app here */}
    </ManifestProvider>
  );
}
```

---

## Key Exports

- **`ManifestProvider`** — The root context provider that hydrates the app with manifest and sitemap data.
- **`useManifest()`** — Hook to access the current app manifest from any component.
- **`useDevice()`** — Hook for consuming normalized telemetry data from connected hardware.
- **`MqttProvider`** — Context provider for real-time MQTT/Ably device communication.

---

## Documentation

For full documentation, visit [https://ramme.io/docs](https://ramme.io/docs).

---

## License

MIT License — Copyright © 2026 Ramme Framework.

See [LICENSE](LICENSE) for details.