@makaio/framework 1.0.0-dev-1781022866275 → 1.0.0-dev-1781023871421

package/dist/ui-kernel/index.d.mts

@@ -0,0 +1,2793 @@
+import { r as PageSurfaceConfig, s as SurfaceId } from "../schemas-DVF1A4DF.mjs";
+import * as _$zod from "zod";
+import { z } from "zod";
+import * as _$_makaio_core0 from "@makaio/framework/core";
+import { IMakaioBus } from "@makaio/framework/bus";
+import { UiContextSnapshot, UiNavigationLevel, UiScope } from "@makaio/framework/contracts";
+import { ClientRecord } from "@makaio/framework/services/settings/storage";
+import { ExtensionInfo } from "@makaio/framework/kernel";
+import * as _$zod_v4_core0 from "zod/v4/core";
+import { ComponentType } from "react";
+
+//#region ui/kernel/src/widgets/scope-registry.d.ts
+/** Widget scope type declared by the shared UI contribution contract. */
+type WidgetScope = UiScope;
+/**
+ * Widget scope definition.
+ */
+interface WidgetScopeDefinition {
+  /** Display label */
+  label: string;
+  /** Description for UI */
+  description?: string;
+}
+/**
+ * Widget scope registry implementation.
+ *
+ * Manages registration and lookup of widget scopes with subscription support.
+ */
+declare class WidgetScopeRegistryImpl {
+  private scopes;
+  private listeners;
+  /**
+   * Register a new widget scope.
+   * @param scope - Scope identifier declared through `UiScopeMap`.
+   * @param definition - Scope definition with label and description
+   */
+  register(scope: UiScope, definition: WidgetScopeDefinition): void;
+  /**
+   * Check if a scope is registered.
+   * @param scope - Scope identifier to check
+   * @returns True if scope exists
+   */
+  has(scope: UiScope): boolean;
+  /**
+   * Get all registered scopes.
+   * @returns Map of scope identifiers to definitions
+   */
+  getAll(): Map<UiScope, WidgetScopeDefinition>;
+  /**
+   * Subscribe to scope registry changes.
+   * @param listener - Callback function when scopes change
+   * @returns Unsubscribe function
+   */
+  subscribe(listener: () => void): () => void;
+  private notify;
+}
+/**
+ * Global widget scope registry instance.
+ */
+declare const widgetScopeRegistry: WidgetScopeRegistryImpl;
+/**
+ * Returns true when a widget's `scope` (single value or array) matches
+ * `targetScope`. When `includeAny` is true (the default), widgets scoped
+ * to `'any'` also match — matching the canonical "available everywhere"
+ * semantics used across surfaces.
+ *
+ * Hooks and other snapshot consumers can call this predicate directly instead
+ * of re-implementing the same single-value-vs-array and `'any'` matching
+ * rules locally.
+ * @param scope - The widget's `scope` field (single value or array).
+ * @param targetScope - The scope being looked up.
+ * @param includeAny - When true, widgets scoped `'any'` also match. Defaults to true.
+ * @returns Whether the widget's scope matches `targetScope`.
+ */
+declare function widgetMatchesScope(scope: WidgetScope | readonly WidgetScope[], targetScope: WidgetScope, includeAny?: boolean): boolean;
+//#endregion
+//#region ui/kernel/src/utils/component-types.d.ts
+/**
+ * Structural component contract accepted by kernel registries.
+ * @typeParam TProps - Props accepted by the component.
+ */
+type ComponentLike<TProps extends object = Record<string, unknown>> = ComponentType<TProps>;
+/**
+ * Shared icon component props used by kernel-tier contracts.
+ */
+interface IconComponentProps {
+  size?: number;
+  className?: string;
+}
+/**
+ * Structural icon component contract for navigation/page metadata.
+ */
+type IconComponentLike = ComponentLike<IconComponentProps>;
+/**
+ * Lazy-loaded component module shape.
+ * @typeParam TProps - Props accepted by the default-exported component.
+ */
+interface LazyComponentModule<TProps extends object = Record<string, unknown>> {
+  default: ComponentLike<TProps>;
+}
+//#endregion
+//#region ui/kernel/src/widgets/types.d.ts
+/** Framework fallback context when no host has selected a narrower context. */
+declare const DEFAULT_WIDGET_UI_CONTEXT: UiContextSnapshot;
+/**
+ * Values for widget size
+ * 'small' | 'medium' | 'large' | 'full-width'
+ */
+type WidgetSize = 'small' | 'medium' | 'large' | 'full-width';
+/**
+ * Props passed to all widget components
+ */
+interface WidgetProps<TConfig = Record<string, unknown>> {
+  /** Current size of the widget */
+  size: WidgetSize;
+  /** Widget instance configuration */
+  config: TConfig;
+  /** Callback to update configuration */
+  updateConfig: (config: Partial<TConfig>) => void;
+  /** Active host UI context for this widget surface. */
+  uiContext: UiContextSnapshot;
+}
+/**
+ * Context passed to a widget's custom activation handler.
+ *
+ * Provides everything the handler needs to perform side-effects: the bus for
+ * further RPCs and the identity of the widget instance that was activated.
+ */
+interface WidgetActivationContext {
+  /** The MakaioBus instance for emitting events or issuing RPCs. */
+  bus: IMakaioBus;
+  /** Widget definition ID (same as `WidgetDefinition.id`). */
+  widgetId: string;
+  /** Widget instance ID within the current layout. */
+  instanceId: string;
+}
+/**
+ * Declarative activation behaviour for a widget.
+ *
+ * When a user clicks an activatable widget tile, the `WidgetGrid` evaluates
+ * these fields in order:
+ *
+ * 1. `pageId` — Opens the named Page in the current window via
+ *    `usePageOverlayStore.openPage`.
+ * 2. `windowId` — Creates or focuses a named window via the
+ *    `host.window.create` RPC.
+ * 3. `onActivate` — Runs a custom async handler with full bus access.
+ *
+ * All three may be present; all will execute. Omit fields that are not needed.
+ */
+interface WidgetActivation {
+  /**
+   * Page ID to open in the current window when the widget is activated.
+   *
+   * The Page's `mode` field determines how it is presented (e.g. `'sheet'`
+   * for a fullscreen overlay). The `WidgetGrid` calls
+   * `usePageOverlayStore.getState().openPage(pageId)`.
+   */
+  pageId?: string;
+  /**
+   * Window registration ID (format: `packageName:windowId`) to create or
+   * focus when the widget is activated.
+   *
+   * The `WidgetGrid` issues a `host.window.create` RPC with this value as
+   * the `registrationId`.
+   */
+  windowId?: string;
+  /**
+   * Custom activation handler called after declarative activation (if any).
+   *
+   * Receives a {@link WidgetActivationContext} with the bus, widgetId, and
+   * instanceId. Runs after `pageId`/`windowId` activation so it can react to
+   * the side-effects they produce.
+   * @param ctx - Activation context with bus access and widget identity.
+   * @returns A promise that resolves when the handler is complete.
+   */
+  onActivate?: (ctx: WidgetActivationContext) => Promise<void>;
+}
+/**
+ * Definition of a widget available in the system
+ */
+interface WidgetDefinition<TConfig = Record<string, unknown>> {
+  /** Unique identifier for the widget type */
+  id: string;
+  /** Display name */
+  name: string;
+  /** Description shown in palette */
+  description?: string;
+  /**
+   * Scope(s) where this widget can be used
+   * - Single scope: 'global' or any host-registered scope
+   * - Multiple scopes: ['global', '<host-scope>'] (Available in both contexts)
+   */
+  scope: WidgetScope | WidgetScope[];
+  /**
+   * React component implementing the widget.
+   * Must accept WidgetProps.
+   */
+  component: ComponentLike<WidgetProps<TConfig>>;
+  /**
+   * Supported sizes. First one is default.
+   */
+  supportedSizes: WidgetSize[];
+  /**
+   * Default size when added
+   */
+  defaultSize: WidgetSize;
+  /**
+   * Optional size hint for the `'tray'` scope. If provided, `useTrayLayout`
+   * uses this instead of `defaultSize` to choose the tray placement height.
+   * Use this when a widget should render compactly in the tray (e.g. a
+   * single-row status indicator) while remaining full-size on a dashboard.
+   */
+  trayDefaultSize?: WidgetSize;
+  /**
+   * Default configuration
+   */
+  defaultConfig?: TConfig;
+  /**
+   * Whether multiple instances of this widget are allowed
+   */
+  allowMultiple?: boolean;
+  /**
+   * Optional activation behaviour when the user clicks the widget tile.
+   *
+   * When present, the `WidgetGrid` renders the tile with a pointer cursor and
+   * executes the declarative steps defined here on click (outside edit mode).
+   * See {@link WidgetActivation} for the full dispatch sequence.
+   */
+  activate?: WidgetActivation;
+}
+/**
+ * Erase the config type parameter for heterogeneous widget storage.
+ *
+ * `WidgetDefinition<TConfig>` is invariant in `TConfig`: `WidgetProps` has
+ * `TConfig` in both covariant (`config`) and contravariant (`updateConfig`)
+ * positions, so no single generic instantiation can accept all concrete
+ * `WidgetDefinition<T>`. TypeScript lacks existential types, which is why the
+ * registry keeps one explicit variance-boundary helper here.
+ *
+ * This generic utility provides a single, documented variance boundary.
+ * TypeScript infers `T` from each call site — callers are fully type-safe.
+ * At runtime, config values always flow as `Record<string, unknown>` through
+ * the registry → layout → render pipeline.
+ * @param definition - Concretely-typed widget definition
+ * @returns The same definition typed for rendering with erased config
+ */
+declare function eraseWidgetConfig<T extends Record<string, unknown>>(definition: WidgetDefinition<T>): WidgetDefinition;
+/**
+ * Active widget instance in a layout
+ */
+interface WidgetInstance {
+  /** Unique ID for this widget instance */
+  instanceId: string;
+  /** ID of the widget definition */
+  widgetId: string;
+  /** Current size */
+  size: WidgetSize;
+  /** Instance specific configuration */
+  config?: Record<string, unknown>;
+}
+/**
+ * Identifiers for standard layout slots
+ */
+type WidgetSlotId = 'main' | 'sidebar-left' | 'sidebar-right' | 'bottom';
+/**
+ * State of a single widget slot
+ */
+interface WidgetSlotState {
+  /** ID of the slot */
+  id: WidgetSlotId;
+  /** Widgets currently in this slot */
+  widgets: WidgetInstance[];
+}
+/**
+ * Widget placement in a grid.
+ *
+ * `size` is the semantic size used for default layout definitions and widget
+ * palette drops. After a user resize, `w` and `h` store the actual grid
+ * dimensions and take precedence over `SIZE_MAPPING[size]` for rendering.
+ * The semantic `size` is re-derived from `w`/`h` for the widget's responsive
+ * rendering prop.
+ */
+interface WidgetPlacement {
+  instanceId: string;
+  widgetId: string;
+  col: number;
+  row: number;
+  size: WidgetSize;
+  /** Grid width in columns. When absent, derived from `size` via SIZE_MAPPING. */
+  w?: number;
+  /** Grid height in rows. When absent, derived from `size` via SIZE_MAPPING. */
+  h?: number;
+  config?: Record<string, unknown>;
+  /** When true, the placement is non-removable and non-draggable regardless of edit mode. */
+  locked?: boolean;
+}
+/**
+ * Persisted widget layout
+ */
+interface WidgetLayout {
+  version: 1;
+  placements: WidgetPlacement[];
+}
+/**
+ * Runtime validator for persisted widget placements.
+ * @param value - Candidate placement payload.
+ * @returns True when the payload matches the widget placement contract.
+ */
+declare function isWidgetPlacement(value: unknown): value is WidgetPlacement;
+/**
+ * Runtime validator for persisted widget layouts.
+ * @param value - Candidate layout payload.
+ * @returns True when the payload matches the widget layout contract.
+ */
+declare function isWidgetLayout(value: unknown): value is WidgetLayout;
+//#endregion
+//#region ui/kernel/src/utils/RegistryBase.d.ts
+/**
+ * RegistryBase - Base class for implementing registries with subscription support
+ *
+ * Provides:
+ * - Map-based storage for items
+ * - Subscription mechanism for notifications
+ * - Protected methods for mutation notifications
+ *
+ * Subclasses define their own public API while using the base infrastructure.
+ * @packageDocumentation
+ */
+/**
+ * Base class for registries with subscription support.
+ *
+ * Provides storage and notification infrastructure.
+ * Subclasses are free to define their own public API without
+ * signature constraints.
+ * @example
+ * ```ts
+ * class MyRegistry extends RegistryBase<string, MyType> {
+ *   public register(item: MyType): void {
+ *     this.items.set(item.id, item);
+ *     this.notify();
+ *   }
+ *
+ *   public get(id: string): MyType | undefined {
+ *     return this.items.get(id);
+ *   }
+ * }
+ * ```
+ */
+declare class RegistryBase<TKey, TValue> {
+  /**
+   * Internal storage map.
+   * Subclasses can access this directly to implement their API.
+   */
+  protected items: Map<TKey, TValue>;
+  /**
+   * Internal set of subscription listeners.
+   */
+  private listeners;
+  /**
+   * Subscribe to registry mutations.
+   * @param listener - Callback to invoke on mutations
+   * @returns Unsubscribe function
+   * @example
+   * ```ts
+   * const unsubscribe = registry.subscribe(() => {
+   *   console.log('Registry changed');
+   * });
+   * ```
+   */
+  subscribe(listener: () => void): () => void;
+  /**
+   * Notify all subscribers of a mutation.
+   *
+   * Iterates all listeners unconditionally so that a throwing listener cannot
+   * prevent delivery to subsequent subscribers. The first error encountered is
+   * re-thrown after the full iteration completes.
+   * @example
+   * ```ts
+   * public register(item: MyType): void {
+   *   this.items.set(item.id, item);
+   *   this.notify(); // Notify subscribers
+   * }
+   * ```
+   */
+  protected notify(): void;
+  /**
+   * Check if an item is registered.
+   * @param key - Item key
+   * @returns True if item exists
+   */
+  has(key: TKey): boolean;
+  /**
+   * Get number of registered items.
+   * @returns Count of items
+   */
+  size(): number;
+}
+//#endregion
+//#region ui/kernel/src/widgets/WidgetRegistry.d.ts
+/**
+ * Registry for managing widget definitions.
+ *
+ * Extends {@link RegistryBase} for Map-based storage and subscription support.
+ * Domain-specific methods handle scoped queries, cache invalidation, and
+ * duplicate-safe registration semantics.
+ */
+declare class WidgetRegistry extends RegistryBase<string, WidgetDefinition> {
+  private cachedAll;
+  /**
+   * Register a widget definition.
+   *
+   * Returns `false` without throwing when the widget ID is already present,
+   * preserving idempotent registration semantics.
+   * @param definition - Concretely-typed widget definition
+   * @returns `true` when this call acquired the widget ID; `false` on duplicate
+   */
+  register<TConfig extends Record<string, unknown>>(definition: WidgetDefinition<TConfig>): boolean;
+  /**
+   * Register multiple widget definitions at once.
+   * @param definitions - Array of widget definitions to register
+   */
+  registerAll(definitions: readonly WidgetDefinition[]): void;
+  /**
+   * Get a single widget definition by ID.
+   * @param widgetId - Widget identifier
+   * @returns Widget definition or `undefined` if not registered
+   */
+  get(widgetId: string): WidgetDefinition | undefined;
+  /**
+   * Get all registered widget definitions.
+   *
+   * Result is cached and invalidated on any mutation. The returned array is
+   * frozen to prevent callers from mutating the registry's internal cache.
+   * @returns Frozen snapshot array of all widget definitions
+   */
+  getAll(): ReadonlyArray<WidgetDefinition>;
+  /**
+   * Get widget definitions available in a given scope.
+   * @param scope - Target scope to filter by
+   * @param includeAny - When `true` (default), also include widgets with `"any"` scope
+   * @returns Filtered array of widget definitions
+   */
+  getByScope(scope: WidgetScope, includeAny?: boolean): WidgetDefinition[];
+  /**
+   * Unregister a widget by ID.
+   * @param widgetId - Widget identifier to remove
+   * @returns `true` when the widget existed and was removed; `false` otherwise
+   */
+  unregister(widgetId: string): boolean;
+  /**
+   * Remove all registered widget definitions.
+   *
+   * No-ops silently when the registry is already empty.
+   */
+  clear(): void;
+}
+/** Global widget registry instance */
+declare const widgetRegistry: WidgetRegistry;
+//#endregion
+//#region ui/kernel/src/widgets/schemas.d.ts
+/**
+ * Widget definition schema.
+ *
+ * Note: `component` is `z.unknown()` because React components are not
+ * serializable. This matches the capability pattern where providers
+ * use `z.unknown()`. The bus is same-process so serialization isn't needed.
+ * @param id - Unique widget identifier
+ * @param name - Display name
+ * @param scope - Where this widget can appear
+ * @param description - Short description (optional)
+ * @param supportedSizes - Array of supported sizes
+ * @param defaultSize - Default size when added to a slot
+ * @param component - React component to render (non-serializable)
+ * @param defaultConfig - Default configuration (optional)
+ * @param allowMultiple - Whether multiple instances are allowed
+ */
+declare const WidgetDefinitionSchema: z.ZodObject<{
+  id: z.ZodString;
+  name: z.ZodString;
+  scope: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>;
+  description: z.ZodOptional<z.ZodString>;
+  supportedSizes: z.ZodArray<z.ZodEnum<{
+    small: "small";
+    medium: "medium";
+    large: "large";
+    "full-width": "full-width";
+  }>>;
+  defaultSize: z.ZodEnum<{
+    small: "small";
+    medium: "medium";
+    large: "large";
+    "full-width": "full-width";
+  }>;
+  component: z.ZodUnknown & z.ZodType<{} | null, unknown, z.core.$ZodTypeInternals<{} | null, unknown>>;
+  defaultConfig: z.ZodOptional<z.ZodUnknown>;
+  allowMultiple: z.ZodOptional<z.ZodBoolean>;
+  activate: z.ZodOptional<z.ZodObject<{
+    pageId: z.ZodOptional<z.ZodString>;
+    windowId: z.ZodOptional<z.ZodString>;
+    onActivate: z.ZodOptional<z.ZodUnknown & z.ZodType<Function, unknown, z.core.$ZodTypeInternals<Function, unknown>>>;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * Unregister payload schema.
+ */
+declare const UnregisterSchema: z.ZodObject<{
+  widgetId: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Widget activated payload schema.
+ *
+ * Emitted when a user clicks an activatable widget (one that has an `activate`
+ * field on its `WidgetDefinition`). This is a renderer-scoped local event and
+ * is never forwarded to transports.
+ * @param widgetId - The widget definition ID
+ * @param instanceId - The specific widget instance ID within the layout
+ */
+declare const ActivatedPayloadSchema: z.ZodObject<{
+  widgetId: z.ZodString;
+  instanceId: z.ZodString;
+}, z.core.$strip>;
+/**
+ * List request/response schemas.
+ */
+declare const ListRequestSchema: z.ZodObject<{
+  scope: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const ListResponseSchema: z.ZodObject<{
+  widgets: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    scope: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>;
+    description: z.ZodOptional<z.ZodString>;
+    supportedSizes: z.ZodArray<z.ZodEnum<{
+      small: "small";
+      medium: "medium";
+      large: "large";
+      "full-width": "full-width";
+    }>>;
+    defaultSize: z.ZodEnum<{
+      small: "small";
+      medium: "medium";
+      large: "large";
+      "full-width": "full-width";
+    }>;
+    component: z.ZodUnknown & z.ZodType<{} | null, unknown, z.core.$ZodTypeInternals<{} | null, unknown>>;
+    defaultConfig: z.ZodOptional<z.ZodUnknown>;
+    allowMultiple: z.ZodOptional<z.ZodBoolean>;
+    activate: z.ZodOptional<z.ZodObject<{
+      pageId: z.ZodOptional<z.ZodString>;
+      windowId: z.ZodOptional<z.ZodString>;
+      onActivate: z.ZodOptional<z.ZodUnknown & z.ZodType<Function, unknown, z.core.$ZodTypeInternals<Function, unknown>>>;
+    }, z.core.$strip>>;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * Widget domain schemas.
+ *
+ * Subjects for widget-related bus communication.
+ * Each key becomes a subject identifier as: `widget.{key}`
+ *
+ * All widget subjects are marked as local because widget definitions contain
+ * React components which cannot be serialized for transport (SharedWorker, WebSocket).
+ * @example
+ * ```typescript
+ * // List all global widgets
+ * const result = await bus.request(WidgetSubjects.list, {
+ *   scope: 'global',
+ * });
+ * ```
+ */
+declare const WidgetSchemas: {
+  /**
+   * Register a widget.
+   *
+   * Subject: `widget.register`
+   * Type: Local event (fire-and-forget, never sent to transports)
+   * Purpose: Plugins or built-in widgets emit this to register themselves.
+   * @example
+   * ```typescript
+   * bus.emit(WidgetSubjects.register, {
+   *   id: 'project-picker',
+   *   name: 'Project Picker',
+   *   scope: 'global',
+   *   supportedSizes: ['small', 'medium'],
+   *   defaultSize: 'medium',
+   *   component: ProjectPickerComponent,
+   * });
+   * ```
+   */
+  register: _$_makaio_core0.LocalSubjectSchema<z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    scope: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>;
+    description: z.ZodOptional<z.ZodString>;
+    supportedSizes: z.ZodArray<z.ZodEnum<{
+      small: "small";
+      medium: "medium";
+      large: "large";
+      "full-width": "full-width";
+    }>>;
+    defaultSize: z.ZodEnum<{
+      small: "small";
+      medium: "medium";
+      large: "large";
+      "full-width": "full-width";
+    }>;
+    component: z.ZodUnknown & z.ZodType<{} | null, unknown, z.core.$ZodTypeInternals<{} | null, unknown>>;
+    defaultConfig: z.ZodOptional<z.ZodUnknown>;
+    allowMultiple: z.ZodOptional<z.ZodBoolean>;
+    activate: z.ZodOptional<z.ZodObject<{
+      pageId: z.ZodOptional<z.ZodString>;
+      windowId: z.ZodOptional<z.ZodString>;
+      onActivate: z.ZodOptional<z.ZodUnknown & z.ZodType<Function, unknown, z.core.$ZodTypeInternals<Function, unknown>>>;
+    }, z.core.$strip>>;
+  }, z.core.$strip>>;
+  /**
+   * Unregister a widget.
+   *
+   * Subject: `widget.unregister`
+   * Type: Local event (fire-and-forget, never sent to transports)
+   * Purpose: Remove a widget from the registry by ID.
+   * @param widgetId - Widget ID to unregister
+   * @example
+   * ```typescript
+   * bus.emit(WidgetSubjects.unregister, {
+   *   widgetId: 'project-picker',
+   * });
+   * ```
+   */
+  unregister: _$_makaio_core0.LocalSubjectSchema<z.ZodObject<{
+    widgetId: z.ZodString;
+  }, z.core.$strip>>;
+  /**
+   * List all registered widgets.
+   *
+   * Subject: `widget.list`
+   * Type: Local request (RPC, never sent to transports)
+   * Purpose: Query available widgets, optionally filtered by scope.
+   * @param scope - Widget scope to filter by (optional)
+   * @returns Array of widget definitions
+   * @example
+   * ```typescript
+   * // List all widgets
+   * const allWidgets = await bus.request(WidgetSubjects.list, {});
+   *
+   * // List only global widgets
+   * const globalWidgets = await bus.request(WidgetSubjects.list, {
+   *   scope: 'global',
+   * });
+   * ```
+   */
+  list: _$_makaio_core0.LocalSubjectSchema<{
+    request: z.ZodObject<{
+      scope: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    response: z.ZodObject<{
+      widgets: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        scope: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>;
+        description: z.ZodOptional<z.ZodString>;
+        supportedSizes: z.ZodArray<z.ZodEnum<{
+          small: "small";
+          medium: "medium";
+          large: "large";
+          "full-width": "full-width";
+        }>>;
+        defaultSize: z.ZodEnum<{
+          small: "small";
+          medium: "medium";
+          large: "large";
+          "full-width": "full-width";
+        }>;
+        component: z.ZodUnknown & z.ZodType<{} | null, unknown, z.core.$ZodTypeInternals<{} | null, unknown>>;
+        defaultConfig: z.ZodOptional<z.ZodUnknown>;
+        allowMultiple: z.ZodOptional<z.ZodBoolean>;
+        activate: z.ZodOptional<z.ZodObject<{
+          pageId: z.ZodOptional<z.ZodString>;
+          windowId: z.ZodOptional<z.ZodString>;
+          onActivate: z.ZodOptional<z.ZodUnknown & z.ZodType<Function, unknown, z.core.$ZodTypeInternals<Function, unknown>>>;
+        }, z.core.$strip>>;
+      }, z.core.$strip>>;
+    }, z.core.$strip>;
+  }>;
+  /**
+   * Emitted when a user activates a widget by clicking it.
+   *
+   * Subject: `widget.activated`
+   * Type: Local event (fire-and-forget, never sent to transports)
+   * Purpose: Signals that a widget with an `activate` field was clicked.
+   *   Consumers (e.g. analytics, debug tooling) can subscribe to this event
+   *   to observe widget activation without coupling to the grid implementation.
+   * @param widgetId - The widget definition ID
+   * @param instanceId - The widget instance ID within the layout
+   * @example
+   * ```typescript
+   * bus.on(WidgetSubjects.activated, (ctx) => {
+   *   console.log(`Widget activated: ${ctx.payload.widgetId}`);
+   * });
+   * ```
+   */
+  activated: _$_makaio_core0.LocalSubjectSchema<z.ZodObject<{
+    widgetId: z.ZodString;
+    instanceId: z.ZodString;
+  }, z.core.$strip>>;
+};
+/**
+ * Raw (unwrapped) schemas for direct validation in tests.
+ *
+ * Use these for schema validation tests. For bus communication,
+ * use WidgetSubjects from namespace.ts.
+ * @internal
+ */
+declare const WidgetRawSchemas: {
+  readonly register: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    scope: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>;
+    description: z.ZodOptional<z.ZodString>;
+    supportedSizes: z.ZodArray<z.ZodEnum<{
+      small: "small";
+      medium: "medium";
+      large: "large";
+      "full-width": "full-width";
+    }>>;
+    defaultSize: z.ZodEnum<{
+      small: "small";
+      medium: "medium";
+      large: "large";
+      "full-width": "full-width";
+    }>;
+    component: z.ZodUnknown & z.ZodType<{} | null, unknown, z.core.$ZodTypeInternals<{} | null, unknown>>;
+    defaultConfig: z.ZodOptional<z.ZodUnknown>;
+    allowMultiple: z.ZodOptional<z.ZodBoolean>;
+    activate: z.ZodOptional<z.ZodObject<{
+      pageId: z.ZodOptional<z.ZodString>;
+      windowId: z.ZodOptional<z.ZodString>;
+      onActivate: z.ZodOptional<z.ZodUnknown & z.ZodType<Function, unknown, z.core.$ZodTypeInternals<Function, unknown>>>;
+    }, z.core.$strip>>;
+  }, z.core.$strip>;
+  readonly unregister: z.ZodObject<{
+    widgetId: z.ZodString;
+  }, z.core.$strip>;
+  readonly list: {
+    readonly request: z.ZodObject<{
+      scope: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    readonly response: z.ZodObject<{
+      widgets: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        scope: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>;
+        description: z.ZodOptional<z.ZodString>;
+        supportedSizes: z.ZodArray<z.ZodEnum<{
+          small: "small";
+          medium: "medium";
+          large: "large";
+          "full-width": "full-width";
+        }>>;
+        defaultSize: z.ZodEnum<{
+          small: "small";
+          medium: "medium";
+          large: "large";
+          "full-width": "full-width";
+        }>;
+        component: z.ZodUnknown & z.ZodType<{} | null, unknown, z.core.$ZodTypeInternals<{} | null, unknown>>;
+        defaultConfig: z.ZodOptional<z.ZodUnknown>;
+        allowMultiple: z.ZodOptional<z.ZodBoolean>;
+        activate: z.ZodOptional<z.ZodObject<{
+          pageId: z.ZodOptional<z.ZodString>;
+          windowId: z.ZodOptional<z.ZodString>;
+          onActivate: z.ZodOptional<z.ZodUnknown & z.ZodType<Function, unknown, z.core.$ZodTypeInternals<Function, unknown>>>;
+        }, z.core.$strip>>;
+      }, z.core.$strip>>;
+    }, z.core.$strip>;
+  };
+  readonly activated: z.ZodObject<{
+    widgetId: z.ZodString;
+    instanceId: z.ZodString;
+  }, z.core.$strip>;
+};
+/**
+ * Type exports for external use.
+ *
+ * These types are inferred from the Zod schemas and provide
+ * type safety when working with widget-related bus messages.
+ */
+type WidgetDefinitionPayload = z.infer<typeof WidgetDefinitionSchema>;
+type UnregisterPayload = z.infer<typeof UnregisterSchema>;
+type ListWidgetsRequest = z.infer<typeof ListRequestSchema>;
+type ListWidgetsResponse = z.infer<typeof ListResponseSchema>;
+/** Payload of the `widget.activated` event. */
+type WidgetActivatedPayload = z.infer<typeof ActivatedPayloadSchema>;
+//#endregion
+//#region ui/kernel/src/widgets/namespace.d.ts
+declare const WidgetNamespace: _$_makaio_core0.BusNamespaceDefinition<"widget", {
+  register: _$_makaio_core0.LocalSubjectSchema<_$zod.ZodObject<{
+    id: _$zod.ZodString;
+    name: _$zod.ZodString;
+    scope: _$zod.ZodUnion<readonly [_$zod.ZodString, _$zod.ZodArray<_$zod.ZodString>]>;
+    description: _$zod.ZodOptional<_$zod.ZodString>;
+    supportedSizes: _$zod.ZodArray<_$zod.ZodEnum<{
+      small: "small";
+      medium: "medium";
+      large: "large";
+      "full-width": "full-width";
+    }>>;
+    defaultSize: _$zod.ZodEnum<{
+      small: "small";
+      medium: "medium";
+      large: "large";
+      "full-width": "full-width";
+    }>;
+    component: _$zod.ZodUnknown & _$zod.ZodType<{} | null, unknown, _$zod_v4_core0.$ZodTypeInternals<{} | null, unknown>>;
+    defaultConfig: _$zod.ZodOptional<_$zod.ZodUnknown>;
+    allowMultiple: _$zod.ZodOptional<_$zod.ZodBoolean>;
+    activate: _$zod.ZodOptional<_$zod.ZodObject<{
+      pageId: _$zod.ZodOptional<_$zod.ZodString>;
+      windowId: _$zod.ZodOptional<_$zod.ZodString>;
+      onActivate: _$zod.ZodOptional<_$zod.ZodUnknown & _$zod.ZodType<Function, unknown, _$zod_v4_core0.$ZodTypeInternals<Function, unknown>>>;
+    }, _$zod_v4_core0.$strip>>;
+  }, _$zod_v4_core0.$strip>>;
+  unregister: _$_makaio_core0.LocalSubjectSchema<_$zod.ZodObject<{
+    widgetId: _$zod.ZodString;
+  }, _$zod_v4_core0.$strip>>;
+  list: _$_makaio_core0.LocalSubjectSchema<{
+    request: _$zod.ZodObject<{
+      scope: _$zod.ZodOptional<_$zod.ZodString>;
+    }, _$zod_v4_core0.$strip>;
+    response: _$zod.ZodObject<{
+      widgets: _$zod.ZodArray<_$zod.ZodObject<{
+        id: _$zod.ZodString;
+        name: _$zod.ZodString;
+        scope: _$zod.ZodUnion<readonly [_$zod.ZodString, _$zod.ZodArray<_$zod.ZodString>]>;
+        description: _$zod.ZodOptional<_$zod.ZodString>;
+        supportedSizes: _$zod.ZodArray<_$zod.ZodEnum<{
+          small: "small";
+          medium: "medium";
+          large: "large";
+          "full-width": "full-width";
+        }>>;
+        defaultSize: _$zod.ZodEnum<{
+          small: "small";
+          medium: "medium";
+          large: "large";
+          "full-width": "full-width";
+        }>;
+        component: _$zod.ZodUnknown & _$zod.ZodType<{} | null, unknown, _$zod_v4_core0.$ZodTypeInternals<{} | null, unknown>>;
+        defaultConfig: _$zod.ZodOptional<_$zod.ZodUnknown>;
+        allowMultiple: _$zod.ZodOptional<_$zod.ZodBoolean>;
+        activate: _$zod.ZodOptional<_$zod.ZodObject<{
+          pageId: _$zod.ZodOptional<_$zod.ZodString>;
+          windowId: _$zod.ZodOptional<_$zod.ZodString>;
+          onActivate: _$zod.ZodOptional<_$zod.ZodUnknown & _$zod.ZodType<Function, unknown, _$zod_v4_core0.$ZodTypeInternals<Function, unknown>>>;
+        }, _$zod_v4_core0.$strip>>;
+      }, _$zod_v4_core0.$strip>>;
+    }, _$zod_v4_core0.$strip>;
+  }>;
+  activated: _$_makaio_core0.LocalSubjectSchema<_$zod.ZodObject<{
+    widgetId: _$zod.ZodString;
+    instanceId: _$zod.ZodString;
+  }, _$zod_v4_core0.$strip>>;
+}>;
+declare const WidgetSubjects: _$_makaio_core0.BusSubjects<_$_makaio_core0.FlatSubjectDefinitions<"widget", {
+  register: _$_makaio_core0.LocalSubjectSchema<_$zod.ZodObject<{
+    id: _$zod.ZodString;
+    name: _$zod.ZodString;
+    scope: _$zod.ZodUnion<readonly [_$zod.ZodString, _$zod.ZodArray<_$zod.ZodString>]>;
+    description: _$zod.ZodOptional<_$zod.ZodString>;
+    supportedSizes: _$zod.ZodArray<_$zod.ZodEnum<{
+      small: "small";
+      medium: "medium";
+      large: "large";
+      "full-width": "full-width";
+    }>>;
+    defaultSize: _$zod.ZodEnum<{
+      small: "small";
+      medium: "medium";
+      large: "large";
+      "full-width": "full-width";
+    }>;
+    component: _$zod.ZodUnknown & _$zod.ZodType<{} | null, unknown, _$zod_v4_core0.$ZodTypeInternals<{} | null, unknown>>;
+    defaultConfig: _$zod.ZodOptional<_$zod.ZodUnknown>;
+    allowMultiple: _$zod.ZodOptional<_$zod.ZodBoolean>;
+    activate: _$zod.ZodOptional<_$zod.ZodObject<{
+      pageId: _$zod.ZodOptional<_$zod.ZodString>;
+      windowId: _$zod.ZodOptional<_$zod.ZodString>;
+      onActivate: _$zod.ZodOptional<_$zod.ZodUnknown & _$zod.ZodType<Function, unknown, _$zod_v4_core0.$ZodTypeInternals<Function, unknown>>>;
+    }, _$zod_v4_core0.$strip>>;
+  }, _$zod_v4_core0.$strip>>;
+  unregister: _$_makaio_core0.LocalSubjectSchema<_$zod.ZodObject<{
+    widgetId: _$zod.ZodString;
+  }, _$zod_v4_core0.$strip>>;
+  list: _$_makaio_core0.LocalSubjectSchema<{
+    request: _$zod.ZodObject<{
+      scope: _$zod.ZodOptional<_$zod.ZodString>;
+    }, _$zod_v4_core0.$strip>;
+    response: _$zod.ZodObject<{
+      widgets: _$zod.ZodArray<_$zod.ZodObject<{
+        id: _$zod.ZodString;
+        name: _$zod.ZodString;
+        scope: _$zod.ZodUnion<readonly [_$zod.ZodString, _$zod.ZodArray<_$zod.ZodString>]>;
+        description: _$zod.ZodOptional<_$zod.ZodString>;
+        supportedSizes: _$zod.ZodArray<_$zod.ZodEnum<{
+          small: "small";
+          medium: "medium";
+          large: "large";
+          "full-width": "full-width";
+        }>>;
+        defaultSize: _$zod.ZodEnum<{
+          small: "small";
+          medium: "medium";
+          large: "large";
+          "full-width": "full-width";
+        }>;
+        component: _$zod.ZodUnknown & _$zod.ZodType<{} | null, unknown, _$zod_v4_core0.$ZodTypeInternals<{} | null, unknown>>;
+        defaultConfig: _$zod.ZodOptional<_$zod.ZodUnknown>;
+        allowMultiple: _$zod.ZodOptional<_$zod.ZodBoolean>;
+        activate: _$zod.ZodOptional<_$zod.ZodObject<{
+          pageId: _$zod.ZodOptional<_$zod.ZodString>;
+          windowId: _$zod.ZodOptional<_$zod.ZodString>;
+          onActivate: _$zod.ZodOptional<_$zod.ZodUnknown & _$zod.ZodType<Function, unknown, _$zod_v4_core0.$ZodTypeInternals<Function, unknown>>>;
+        }, _$zod_v4_core0.$strip>>;
+      }, _$zod_v4_core0.$strip>>;
+    }, _$zod_v4_core0.$strip>;
+  }>;
+  activated: _$_makaio_core0.LocalSubjectSchema<_$zod.ZodObject<{
+    widgetId: _$zod.ZodString;
+    instanceId: _$zod.ZodString;
+  }, _$zod_v4_core0.$strip>>;
+}>, "widget">;
+//#endregion
+//#region ui/kernel/src/widgets/tray-layout.d.ts
+/**
+ * Derive a read-only `WidgetLayout` for the tray surface.
+ *
+ * Ordering contract:
+ * 1. Placements whose `widgetId` appears in `lockedWidgetIds` come first, in
+ *    the order they appear in `lockedWidgetIds`. These receive `locked: true`.
+ * 2. All other tray-scoped widgets follow in their registration order.
+ *
+ * All placements default to `w: TRAY_GRID_COLS` (full tray width). The row
+ * height `h` is derived from the widget's `trayDefaultSize` (if set) or
+ * `defaultSize`.
+ * @param allWidgets - Stable widget registry snapshot in registration order.
+ * @param lockedWidgetIds - Widget IDs pinned at the top of the tray.
+ * @returns Derived tray layout with deterministic placement order.
+ */
+declare function deriveTrayLayout(allWidgets: readonly WidgetDefinition[], lockedWidgetIds?: readonly string[]): WidgetLayout;
+//#endregion
+//#region ui/kernel/src/widgets/register.d.ts
+/**
+ * Register a widget with the widget system.
+ *
+ * Registers the widget in the local registry and emits a local bus event for
+ * any active observers.
+ * @param bus - Bus instance
+ * @param definition - Widget definition including component
+ * @returns `true` when this call acquired the widget ID
+ */
+declare function registerWidget(bus: IMakaioBus, definition: WidgetDefinition): boolean;
+/**
+ * Register multiple widgets at once.
+ * @param bus - Bus instance
+ * @param definitions - Array of widget definitions
+ * @returns IDs that were newly registered by this call
+ */
+declare function registerWidgets(bus: IMakaioBus, definitions: readonly WidgetDefinition[]): string[];
+/**
+ * Unregister a widget by ID.
+ * @param bus - Bus instance
+ * @param widgetId - Widget ID to unregister
+ * @returns `true` when the widget existed and was removed
+ */
+declare function unregisterWidget(bus: IMakaioBus, widgetId: string): boolean;
+//#endregion
+//#region ui/kernel/src/widgets/subscriptions.d.ts
+/**
+ * Subscribe to widget bus events.
+ *
+ * Wires bus events to the internal widget registry.
+ * Call once at app startup after bus is ready.
+ * @param bus - Bus instance
+ * @returns Cleanup function to unsubscribe all handlers
+ */
+declare function subscribeToWidgetEvents(bus: IMakaioBus): () => void;
+//#endregion
+//#region ui/kernel/src/navigation/types.d.ts
+/**
+ * Navigation hierarchy level.
+ *
+ * Host products extend the available levels through `UiNavigationLevelMap`.
+ * Framework-owned levels are `root` and `any`.
+ */
+type NavigationLevel = UiNavigationLevel;
+/**
+ * Navigation action - what happens when a target is selected.
+ *
+ * The `focus` action uses a plain `string` focus context identifier.
+ * (The `FocusContextId` branded type is intentionally not used at the kernel
+ * tier — plain strings keep this tier portable across focus-context implementations.)
+ */
+type NavigationAction = {
+  type: 'focus';
+  focusContext: string;
+} | {
+  type: 'page';
+  pageId: string;
+} | {
+  type: 'command';
+  commandId: string;
+} | {
+  type: 'callback';
+  handler: () => void;
+} | {
+  type: 'external';
+  url: string;
+};
+/**
+ * Extensible navigation group map.
+ *
+ * Plugins extend via module augmentation:
+ * ```typescript
+ * declare module '@makaio/framework/ui-kernel' {
+ *   interface NavigationGroupMap {
+ *     'my-plugin-section': true;
+ *   }
+ * }
+ * ```
+ */
+interface NavigationGroupMap {
+  /** Workspace-switching pages (Dashboard, Chat, Git) */
+  navigate: true;
+  /** Analytics and reporting pages */
+  analytics: true;
+  /** Quick-access overlay pages (Settings, Projects, Sessions) */
+  'quick-access': true;
+}
+/**
+ * Navigation group identifier.
+ * Type-safe via declaration merging of NavigationGroupMap.
+ */
+type NavigationGroup = keyof NavigationGroupMap;
+/**
+ * Navigation target - an item that appears in navigation UI.
+ *
+ * Registered via NavigationRegistry and queried by navigation components
+ * (KaiTrigger hover, Quick Prompt suggestions, breadcrumb dropdowns).
+ */
+interface NavigationTarget {
+  /** Unique identifier */
+  id: string;
+  /** Display label */
+  label: string;
+  /** Optional description for autocomplete/tooltips */
+  description?: string;
+  /** Icon component (lucide-react style) */
+  icon?: IconComponentLike;
+  /** Navigation level where this target is available */
+  level: NavigationLevel;
+  /** What happens on navigation */
+  action: NavigationAction;
+  /** Keyboard shortcut hint (display only, actual binding is separate) */
+  shortcut?: string;
+  /** Order in navigation list (lower = first, default = 50) */
+  order?: number;
+  /** Group for visual separation */
+  group?: NavigationGroup;
+  /**
+   * Dynamic visibility condition.
+   * Called when building navigation list - return false to hide.
+   */
+  when?: () => boolean;
+  /**
+   * Whether this target is currently active/selected.
+   * Called when rendering - return true to show active state.
+   */
+  isActive?: () => boolean;
+}
+/**
+ * Options for querying navigation targets.
+ */
+interface NavigationQueryOptions {
+  /** Filter by navigation level (includes 'any' targets) */
+  level?: NavigationLevel;
+  /** Filter by group */
+  group?: NavigationGroup;
+  /** Include targets where when() returns false */
+  includeHidden?: boolean;
+}
+//#endregion
+//#region ui/kernel/src/pages/page-definition-types.d.ts
+/**
+ * Navigation level where a page is available.
+ *
+ * Host products extend the available levels through `UiNavigationLevelMap`.
+ * Framework-owned levels are `root` and `any`.
+ */
+type PageLevel = UiNavigationLevel;
+/**
+ * Page mode determines UI behavior when navigating to a page.
+ *
+ * - `switch`: Changes workspace focus. Page content takes over the main workspace area.
+ *   Appears in sidebar "Navigate" section. Example: Home, Status, Chat pages.
+ *
+ * - `peek`: Opens as a constrained overlay that preserves workspace state underneath.
+ *   Small modal (~800px). Example: Future pickers, quick-reference lookups.
+ *
+ * - `cover`: Legacy full-viewport overlay mode. Kept during the transition
+ *   for existing registered pages.
+ *
+ * - `sheet`: Opens as a full-viewport sheet overlay that preserves workspace
+ *   state underneath. New fullscreen overlays should use this mode.
+ */
+type PageMode = 'switch' | 'peek' | 'cover' | 'sheet';
+/**
+ * Check if a page mode uses the overlay system (pageOverlayStore).
+ *
+ * `peek`, `cover`, and `sheet` modes open via the overlay store, while
+ * `switch` changes workspace focus. This helper centralizes the mode
+ * classification to avoid duplicating mode checks.
+ * @param mode - The page mode to check
+ * @returns True if the mode opens an overlay (peek, cover, or sheet)
+ */
+declare function isOverlayMode(mode: PageMode): boolean;
+/**
+ * Props passed to all page components when rendered.
+ *
+ * This standardized interface ensures consistency across all page implementations,
+ * whether built-in or plugin-provided.
+ */
+interface PageComponentProps {
+  /**
+   * Optional CSS class name for the page container.
+   * Applied to the root element of the page for custom styling.
+   */
+  className?: string;
+  /**
+   * Internal route within the page (for peek mode with sub-navigation).
+   *
+   * Example: For Settings page, this might be 'appearance' or 'extensions/example'
+   * to navigate to specific settings sections.
+   *
+   * Defaults to null (no internal route, show default page view).
+   */
+  internalRoute?: string | null;
+  /**
+   * Callback for internal navigation within the page.
+   *
+   * Pages call this when user navigates between sub-sections (tabs, panels, etc.)
+   * to update the URL and maintain navigation history.
+   * @param route - The new internal route path
+   */
+  onNavigate?: (route: string) => void;
+}
+/**
+ * Unified page definition — single source of truth for page identity,
+ * navigation behavior, and rendering.
+ *
+ * Pages are defined as pure data in `web/pages` and registered into
+ * PageDefinitionRegistry at app startup. This replaces hardcoded page
+ * mappings and navigation targets.
+ * @example
+ * ```typescript
+ * import { Settings } from 'lucide-react';
+ *
+ * export const settingsPageDefinition: PageDefinition = {
+ *   id: 'settings',
+ *   name: 'Settings',
+ *   description: 'Application settings and configuration',
+ *   icon: Settings,
+ *   mode: 'peek',
+ *   level: 'any',
+ *   component: () => import('@makaio/framework/ui-views').then(m => ({ default: m.SettingsView })),
+ *   group: 'quick-access',
+ *   order: 100,
+ *   shortcut: '⌘,',
+ * };
+ * ```
+ */
+interface PageDefinition {
+  /**
+   * Unique page identifier.
+   *
+   * Built-in pages use simple IDs: 'settings', 'sessions', 'home'
+   * Plugin pages use namespaced IDs: 'plugin-name:page-id'
+   * @example 'settings'
+   * @example 'example-plugin:details'
+   */
+  id: string;
+  /**
+   * Display name for sidebar, slash command, overlay title.
+   *
+   * Keep concise (1-2 words) for sidebar display.
+   * @example 'Settings'
+   * @example 'Runtime Status'
+   */
+  name: string;
+  /**
+   * Description for autocomplete tooltips and slash command suggestions.
+   *
+   * Shown in Quick Prompt suggestions and sidebar tooltips.
+   * One sentence describing what the page does.
+   * @example 'Application settings and configuration'
+   */
+  description?: string;
+  /**
+   * Icon component for sidebar and command palette.
+   *
+   * Use lucide-react icons directly (sync import).
+   * Icons are tree-shaken and tiny, no need for lazy loading.
+   * @example Settings (from 'lucide-react')
+   */
+  icon?: IconComponentLike;
+  /**
+   * Page mode determines navigation behavior.
+   *
+   * - `switch`: Takes over workspace, shows in "Navigate" section
+   * - `peek`: Small overlay preserving state, shows in "Quick Access" section
+   * - `cover`: Legacy full-viewport overlay mode
+   * - `sheet`: Full-viewport sheet overlay preserving workspace state
+   */
+  mode: PageMode;
+  /**
+   * Navigation level where this page is available.
+   *
+   * Pages with `level: 'any'` are always available.
+   * Pages with specific levels only appear when that context is active.
+   *
+   * The query system automatically includes 'any' pages when filtering by level.
+   * @example 'any' - Settings available everywhere
+   * @example 'root' - Root shell pages
+   */
+  level: PageLevel;
+  /**
+   * Lazy-loaded page component for code splitting.
+   *
+   * Must return a module with a default export that accepts PageComponentProps.
+   * Use dynamic import for automatic code splitting.
+   * @example
+   * ```typescript
+   * () => import('./SettingsView.js').then(m => (\{ default: m.SettingsView \}))
+   * ```
+   */
+  component: () => Promise<LazyComponentModule<PageComponentProps>>;
+  /**
+   * Display order in sidebar (lower = first).
+   *
+   * Applied automatically during registration if omitted (defaults to 50).
+   */
+  order?: number;
+  /**
+   * Navigation group for sidebar visual organization.
+   *
+   * Groups create visual separation in navigation UI.
+   * Applied automatically during registration if omitted (defaults to 'navigate').
+   */
+  group?: NavigationGroup;
+  /**
+   * Keyboard shortcut hint (display-only).
+   *
+   * Shown in sidebar and tooltips. Actual keyboard binding
+   * is registered separately through the keybinding system.
+   * @example '⌘,' - Command+Comma for Settings
+   * @example '⌘S' - Command+S for Search
+   */
+  shortcut?: string;
+  /**
+   * Dynamic visibility condition.
+   *
+   * Called when building navigation lists. Return false to hide
+   * the page from sidebar and command palette.
+   *
+   * Use for feature flags, permission checks, or context-dependent availability.
+   * @returns True to show the page, false to hide it
+   * @example
+   * ```typescript
+   * () => featureFlags.pageEnabled
+   * ```
+   */
+  when?: () => boolean;
+  /**
+   * Whether this page is currently active/selected.
+   *
+   * Called when rendering sidebar to show active indicator.
+   * Used for visual feedback of current page.
+   * @returns True to show active state, false otherwise
+   * @example
+   * ```typescript
+   * () => focusStore.getState().activeFocus.id === 'settings'
+   * ```
+   */
+  isActive?: () => boolean;
+  /**
+   * Focus context identifier for switch-mode pages.
+   *
+   * When set, switching to this page sets the active focus context.
+   * Only relevant for mode='switch' pages.
+   * Plain string (not a branded FocusContextId) for kernel-tier portability.
+   * @example 'chat' - Switching to chat page activates chat focus context
+   * @example 'settings' - Switching to settings page activates settings focus context
+   */
+  focusContext?: string;
+  /**
+   * Extract the active section ID from an internal route.
+   *
+   * Used by PageCoverView to highlight the active sidebar entry
+   * when the page has registered sections in PageSectionRegistry.
+   * Return null for overview/non-section routes.
+   * @param internalRoute - The current internal route (e.g., '/settings/relay')
+   * @returns Section ID if route maps to a section, null otherwise
+   * @example
+   * ```typescript
+   * // Settings page: /settings/relay → 'relay', /settings/adapters/openai → null
+   * parseSectionId: (route) => {
+   *   if (!route) return null;
+   *   const match = route.match(/^\/settings\/([^/]+)$/);
+   *   return match?.[1] ?? null;
+   * }
+   * ```
+   */
+  parseSectionId?: (internalRoute: string | null) => string | null;
+  /**
+   * Surface visibility configuration.
+   *
+   * Controls which rendering surfaces (web, mobile, electron) can display this page.
+   * Uses either explicit surface IDs or capability requirements.
+   * - Omitted: available on every surface (backward-compatible default)
+   * - `{ surfaces: ['web'] }`: web only
+   * - `{ surfaces: ['mobile'] }`: mobile only
+   * - `{ requiredCapabilities: ['dom'] }`: any surface with DOM access
+   * @example
+   * ```typescript
+   * { surfaces: ['web', 'electron'] } // Web and desktop only
+   * ```
+   * @example
+   * ```typescript
+   * { requiredCapabilities: ['touch'] } // Touch-capable surfaces
+   * ```
+   */
+  surface?: PageSurfaceConfig;
+  /**
+   * Which Electron window(s) this page appears in, identified by qualified
+   * registration ID (`{packageName}:{windowId}`).
+   *
+   * When omitted or `undefined`, the page is visible in all windows.
+   * Accepts a single ID or an array for pages shared across multiple windows.
+   * @example
+   * ```typescript
+   * windowId: 'makaio.workspace-window:main' // Only in workspace windows
+   * ```
+   * @example
+   * ```typescript
+   * windowId: ['makaio.workspace-window:main', 'makaio.chat:main'] // Multiple windows
+   * ```
+   */
+  windowId?: string | string[];
+}
+/**
+ * Query options for filtering page definitions.
+ *
+ * All filters are optional and combine with AND logic.
+ * Level filter automatically includes pages with level='any'.
+ */
+interface PageDefinitionQueryOptions {
+  /**
+   * Filter by page mode.
+   * @example
+   * ```typescript
+   * \{ mode: 'peek' \} // Only overlay pages
+   * ```
+   */
+  mode?: PageMode;
+  /**
+   * Filter by navigation level.
+   * Automatically includes pages with level='any'.
+   * @example
+   * ```typescript
+   * \{ level: 'root' \} // Root and 'any' pages
+   * ```
+   */
+  level?: PageLevel;
+  /**
+   * Filter by navigation group.
+   * @example
+   * ```typescript
+   * \{ group: 'quick-access' \} // Only quick access pages
+   * ```
+   */
+  group?: NavigationGroup;
+  /**
+   * Filter by rendering surface.
+   *
+   * When set, only pages available on this surface are returned.
+   * Pages with `surface` omitted are always included (available everywhere).
+   * Pages that declare only `requiredCapabilities` are excluded — a SurfaceId
+   * alone is not sufficient to evaluate capability requirements. Use
+   * `isPageVisibleOnSurface(page, surfaceDeclaration)` at the surface runtime to
+   * include capability-gated pages with their full capability set.
+   * @example
+   * ```typescript
+   * \{ surface: 'mobile' \} // Pages available on mobile
+   * ```
+   */
+  surface?: SurfaceId;
+  /**
+   * Include pages where when() returns false.
+   *
+   * Defaults to false (hidden pages excluded from results).
+   */
+  includeHidden?: boolean;
+}
+//#endregion
+//#region ui/kernel/src/pages/types.d.ts
+/**
+ * Normalized slot identifiers.
+ * Pages pick from this vocabulary - they don't invent custom names.
+ */
+type SlotId = 'main' | 'sidebar-left' | 'sidebar-right' | 'detail-panel' | 'bottom-panel' | 'widget-zone';
+/**
+ * Slot definition - how a content area behaves.
+ * All slots are grids with dynamic column calculation.
+ */
+interface SlotDefinition {
+  /** Normalized slot identifier */
+  id: SlotId;
+  /** Human-readable name for UI (e.g., "Main Content", "Details Panel") */
+  name: string;
+  /** Which widget sizes this slot accepts - used for compatibility filtering */
+  acceptsSizes: WidgetSize[];
+  /**
+   * Minimum width per column in pixels.
+   * Drives dynamic column count: cols = floor(width / minColumnWidth)
+   */
+  minColumnWidth: number;
+  /** Maximum columns (cap for very wide slots) */
+  maxColumns: number;
+  /** Whether slot can be collapsed by user */
+  collapsible?: boolean;
+  /** Default collapsed state */
+  defaultCollapsed?: boolean;
+}
+/**
+ * Content that can be placed in a slot.
+ * References widgets/views by ID - actual components resolved at runtime.
+ */
+type SlotContent = {
+  type: 'view';
+  viewId: string;
+  props?: Record<string, unknown>;
+} | {
+  type: 'widget';
+  widgetId: string;
+  config?: Record<string, unknown>;
+};
+/**
+ * Content placement with mandatory flag and optional position.
+ */
+interface SlotPlacement {
+  /**
+   * Stable unique identifier for this placement instance.
+   * Used as React key and for layout persistence.
+   */
+  instanceId: string;
+  /** What to render */
+  content: SlotContent;
+  /** If true, user cannot remove this from the slot */
+  mandatory: boolean;
+  /**
+   * Initial position in grid (col, row).
+   * If omitted, auto-placed by grid layout engine.
+   */
+  position?: {
+    col: number;
+    row: number;
+  };
+}
+/**
+ * Map of slot IDs to placements.
+ */
+type SlotPlacementMap = Partial<Record<SlotId, SlotPlacement[]>>;
+/**
+ * Page declaration - registered by core or extensions.
+ * Declarative definition of a page's structure and default content.
+ */
+interface PageDeclaration {
+  /**
+   * Unique page identifier.
+   * Framework pages: 'dashboard', 'settings'
+   * Plugin pages: 'plugin-name:page-id' (namespaced)
+   */
+  id: string;
+  /** Human-readable name */
+  name: string;
+  /** Description shown in page listings */
+  description?: string;
+  /**
+   * Navigation level where this page is available.
+   * - `'root'`: Only at the framework root level
+   * - `'any'`: Available at all levels — matched by every `getByLevel()` query
+   * - Host-specific levels are added through `UiNavigationLevelMap`
+   *   declaration merging.
+   *
+   * If omitted, the page matches every level query when `includeAny` is true
+   * (equivalent to setting `level: 'any'`).
+   */
+  level?: PageLevel;
+  /**
+   * Route path (for URL-based routing in web/ui).
+   * Built-in: '/git', '/dashboard'
+   * Plugin: '/extensions/<plugin-name>/<route>'
+   * Optional - pages can exist without routes (focus-based only)
+   */
+  route?: string;
+  /**
+   * Widget scope for this page context.
+   * Determines which widgets are available for the active UI context.
+   * Hosts and extensions add domain scopes through `UiScopeMap` declaration merging.
+   */
+  scope: WidgetScope;
+  /** Slots this page provides - uses normalized SlotId vocabulary */
+  slots: SlotDefinition[];
+  /** Default content per slot */
+  defaultContent: SlotPlacementMap;
+  /** Page-level icon for navigation (lazy-loaded) */
+  icon?: () => Promise<LazyComponentModule<Pick<IconComponentProps, 'size'>>>;
+  /** Page-level layout constraints */
+  layout?: {
+    /** Minimum page width before horizontal scroll */minWidth?: number;
+  };
+}
+//#endregion
+//#region ui/kernel/src/extensions/types.d.ts
+/**
+ * Props passed to the shell's root layout component.
+ */
+interface ShellProps {
+  /** Bus instance for handler registration and event emission. */
+  bus: IMakaioBus;
+}
+/**
+ * Shell contribution — provides the workspace chrome.
+ *
+ * An extension that supplies this takes over the root layout of the renderer.
+ * Only one extension should provide a shell; if multiple do, last-wins.
+ */
+interface ShellContribution {
+  /**
+   * Root layout component — replaces the shell's content area entirely.
+   * Receives {@link ShellProps} from the host renderer.
+   */
+  component: ComponentLike<ShellProps>;
+}
+/**
+ * Returned by an extension's browser entry point factory.
+ *
+ * Every field is optional; an extension declares only the surfaces it contributes.
+ * The browser loader merges contributions from all loaded extensions in load order.
+ */
+interface ExtensionBrowserContribution {
+  /**
+   * Workspace chrome — the root layout component.
+   *
+   * Only one extension should provide this. If multiple do, last-wins.
+   * The framework loader renders its own fallback shell when no extension
+   * provides workspace chrome.
+   */
+  shell?: ShellContribution;
+  /** Slot-based page layout declarations registered into {@link pageRegistry}. */
+  pages?: PageDeclaration[];
+  /** Navigable page definitions registered into {@link pageDefinitionRegistry}. */
+  pageDefinitions?: PageDefinition[];
+  /** Standard widget contributions. */
+  widgets?: readonly WidgetDefinition[];
+  /** Called on extension unload to release browser-side resources. */
+  destroy?: () => void;
+}
+/**
+ * Runtime context passed to an extension browser factory.
+ */
+interface ExtensionBrowserFactoryContext {
+  /** Browser bus instance owned by the loader surface. */
+  bus: IMakaioBus;
+}
+/**
+ * Browser entry point shape — the default export of extension browser bundles.
+ *
+ * The browser loader calls this factory once per page load to obtain the
+ * extension's UI contributions.
+ * @param context - Runtime context supplied by the browser loader.
+ * @returns Browser UI contribution for this extension.
+ */
+type ExtensionBrowserFactory = (context: ExtensionBrowserFactoryContext) => ExtensionBrowserContribution;
+//#endregion
+//#region ui/kernel/src/extensions/browser-factory-registry.d.ts
+/**
+ * Register a browser factory for an extension.
+ *
+ * Throws if a different factory is already registered for `extensionName`.
+ * Re-registering the identical factory reference is a no-op (idempotent).
+ * The name is trimmed before use; `' acme.ext '` and `'acme.ext'` refer to
+ * the same entry. These hot-reload and bundler-fallback invariants are locked
+ * down in browser-factory-registry.test.ts.
+ * @param extensionName - Canonical extension name from the extension manifest.
+ * @param factory - Browser contribution factory for that extension.
+ * @throws Error if `extensionName` is empty or whitespace-only.
+ * @throws Error if `factory` is not a function.
+ * @throws Error if a different factory is already registered for this extension name.
+ */
+declare function registerExtensionBrowserFactory(extensionName: string, factory: ExtensionBrowserFactory): void;
+/**
+ * Unregister a browser factory for an extension.
+ *
+ * The name is trimmed before use; `' acme.ext '` and `'acme.ext'` refer to
+ * the same entry.
+ * @param extensionName - Canonical extension name from the extension manifest.
+ * @throws Error if `extensionName` is empty or whitespace-only.
+ */
+declare function unregisterExtensionBrowserFactory(extensionName: string): void;
+/**
+ * Clear all registered browser factories.
+ *
+ * Exposed for test isolation and hot-reload-like teardown flows where the
+ * process outlives a single extension load cycle.
+ */
+declare function clearExtensionBrowserFactories(): void;
+/**
+ * Read a registered browser factory for an extension.
+ *
+ * The name is trimmed before use; `' acme.ext '` and `'acme.ext'` refer to
+ * the same entry.
+ * @param extensionName - Canonical extension name from the extension manifest.
+ * @returns The registered browser factory, if any.
+ * @throws Error if `extensionName` is empty or whitespace-only.
+ */
+declare function getRegisteredExtensionBrowserFactory(extensionName: string): ExtensionBrowserFactory | undefined;
+//#endregion
+//#region ui/kernel/src/extensions/browser-factory-resolution.d.ts
+/**
+ * Result of resolving an extension browser factory from module and registry sources.
+ */
+type ExtensionBrowserFactoryResolution = {
+  readonly kind: 'resolved';
+  readonly factory: ExtensionBrowserFactory;
+} | {
+  readonly kind: 'invalid';
+  readonly reason: string;
+};
+/**
+ * Resolve an extension browser factory from the imported module default export
+ * and the registry fallback populated during module evaluation.
+ *
+ * The default export remains the primary contract.  The registry is a fallback
+ * seam for environments where the bundler strips the runtime-loaded chunk's
+ * export while still evaluating the module side effect that registered it.
+ * @param moduleDefault - Imported module default export.
+ * @param registeredFactory - Registry fallback for the extension, if any.
+ * @returns A resolved factory or an explicit invalid reason for logging.
+ */
+declare function resolveExtensionBrowserFactory(moduleDefault: unknown, registeredFactory: ExtensionBrowserFactory | undefined): ExtensionBrowserFactoryResolution;
+//#endregion
+//#region ui/kernel/src/extensions/cleanup-stack.d.ts
+/**
+ * Cleanup-stack helper for browser extension registration.
+ *
+ * Registrations are treated as transactional stacks: when a later step fails,
+ * already-registered resources are unwound in reverse order.
+ * @packageDocumentation
+ */
+/**
+ * Runs all cleanup callbacks in reverse registration order.
+ *
+ * Errors are logged and suppressed so teardown continues for the remaining
+ * callbacks.
+ * @param cleanups - Registered cleanup callbacks.
+ * @param scope - Log prefix describing the failing teardown scope.
+ */
+declare function runCleanupsInReverse(cleanups: ReadonlyArray<() => void>, scope: string): void;
+//#endregion
+//#region ui/kernel/src/extensions/registration-utils.d.ts
+/**
+ * Register framework-level extension UI contributions.
+ *
+ * Phase 1 of the framework UI split keeps the contribution contract narrow but
+ * fully functional: page declarations populate the page registry, page
+ * definitions populate the page definition registry, and widgets are mirrored
+ * through the widget bus-backed registration flow.
+ *
+ * Registration is treated as transactional: if a later step throws, already-
+ * registered items are unwound in reverse order before the error propagates.
+ *
+ * The returned `unregisterAll` function tears down all successful registrations
+ * in reverse order (last-registered first), matching standard stack-teardown
+ * conventions. Callers must invoke it exactly once when the extension unloads.
+ * @param bus - Bus used to publish widget registration events.
+ * @param extensionName - Unique extension name for diagnostics.
+ * @param contribution - Browser contribution returned by the extension factory.
+ * @returns A single cleanup function that undoes all successful registrations in reverse order.
+ */
+declare function registerExtensionUI(bus: IMakaioBus, extensionName: string, contribution: ExtensionBrowserContribution): () => void;
+//#endregion
+//#region ui/kernel/src/extensions/shell-style.d.ts
+/**
+ * Shared shell fallback styling constants.
+ *
+ * These inline values are intentionally kept outside the theme pipeline so the
+ * boot splash and empty/error fallback UI render before extension chrome loads.
+ * They mirror ui-theme tokens because boot UI can render before renderer CSS
+ * has loaded.
+ * @packageDocumentation
+ */
+/** Background colour for shell-level fallback and boot-splash UI. */
+declare const SHELL_BG_COLOR = "#0d1117";
+/** Text colour for shell-level fallback and boot-splash UI. */
+declare const SHELL_TEXT_COLOR = "#e9eaed";
+/** Font stack for shell-level fallback and boot-splash UI. */
+declare const SHELL_FONT_FAMILY = "system-ui, sans-serif";
+//#endregion
+//#region ui/kernel/src/runtime/wait-for-runtime-ready.d.ts
+/**
+ * Result produced when the runtime readiness promise settles.
+ *
+ * - `'ready'`     — runtime booted successfully
+ * - `'cancelled'` — waiter was cleaned up before readiness (e.g. React unmount)
+ * - `'timeout'`   — runtime did not become ready within the allowed window
+ */
+type RuntimeReadyWaitResult = 'ready' | 'cancelled' | 'timeout';
+/**
+ * Readiness waiter handle for runtime boot synchronisation.
+ */
+interface RuntimeReadyWaiter {
+  /**
+   * Cancel the waiter and resolve the `ready` promise with `'cancelled'`.
+   *
+   * Idempotent — safe to call multiple times.
+   */
+  cleanup: () => void;
+  /**
+   * Promise that resolves when the runtime is ready, the waiter is cancelled,
+   * or the timeout window expires.
+   *
+   * Resolves with `'ready'`, `'cancelled'`, or `'timeout'`. May reject if the
+   * readiness probe itself fails (e.g. transport error) — callers should
+   * wrap in try/catch.
+   */
+  ready: Promise<RuntimeReadyWaitResult>;
+}
+/**
+ * Wait for the Makaio runtime to finish booting.
+ *
+ * Subscribes to `kernel.ready` before probing `kernel.isReady` so callers do
+ * not miss the one-shot event while the RPC is in flight.  When the readiness
+ * RPC is unavailable, this falls back to the event path for pre-boot callers.
+ *
+ * A timeout ensures the waiter never hangs indefinitely — if the runtime does
+ * not become ready within `timeoutMs`, the promise resolves with `'timeout'`
+ * so the caller can show an error UI instead of spinning forever.
+ *
+ * Cleanup is idempotent — `bus.on()` returns an unsubscribe function that is
+ * safe to call multiple times.  Both the event handler and the RPC success path
+ * call `cleanup()`, and the consumer may call it again on unmount; all three
+ * are no-ops after the first invocation.
+ * @param bus - Bus used for readiness queries and subscriptions.
+ * @param timeoutMs - Maximum wait before resolving `'timeout'`. Defaults to 30 s.
+ * @returns Cleanup for the ready listener and a promise that resolves at readiness.
+ */
+declare function createRuntimeReadyWaiter(bus: IMakaioBus, timeoutMs?: number): RuntimeReadyWaiter;
+//#endregion
+//#region ui/kernel/src/pages/page-section-types.d.ts
+/**
+ * Props passed to all page section components.
+ *
+ * Page sections use these props for navigation and styling.
+ */
+interface PageSectionProps {
+  /**
+   * Navigate back to the parent page's overview.
+   * Call this when user clicks back or cancels.
+   */
+  onNavigateBack: () => void;
+  /**
+   * Navigate to another path within the parent page.
+   * @param path - Path to navigate to
+   */
+  onNavigate: (path: string) => void;
+  /** Optional CSS class name for styling */
+  className?: string;
+}
+/**
+ * Status types for page sections.
+ * Discriminated union for type-safe status badge rendering.
+ */
+type PageSectionStatus = {
+  type: 'connected';
+  label?: string;
+} | {
+  type: 'connecting';
+  label?: string;
+} | {
+  type: 'disconnected';
+  label?: string;
+} | {
+  type: 'warning';
+  label: string;
+} | {
+  type: 'error';
+  label: string;
+} | {
+  type: 'not-configured';
+} | {
+  type: 'configured';
+  count?: number;
+};
+/**
+ * Definition of a page section available in the system.
+ *
+ * Page sections registered here appear in parent page navigation
+ * and can be routed to via their parent page.
+ */
+interface PageSectionDefinition<TProps extends PageSectionProps = PageSectionProps> {
+  /** Unique identifier within parent page */
+  id: string;
+  /** ID of the parent page this section belongs to */
+  parentPageId: string;
+  /** Display name */
+  name: string;
+  /** Optional description */
+  description?: string;
+  /** Optional icon component */
+  icon?: IconComponentLike;
+  /** Optional category for grouping within parent page */
+  category?: string;
+  /**
+   * Order within category.
+   *
+   * Lower numbers appear first. Default: 100.
+   */
+  order?: number;
+  /** Section content component */
+  component: ComponentLike<TProps>;
+  /**
+   * Optional function to get current status for overview card.
+   *
+   * Called when rendering the overview to show status badges.
+   * Return null to show no status.
+   * @returns Current status or null
+   */
+  getStatus?: () => PageSectionStatus | null;
+}
+//#endregion
+//#region ui/kernel/src/pages/PageDefinitionRegistry.d.ts
+/**
+ * Filter a page-definition snapshot with the same semantics as registry.query().
+ *
+ * This keeps query logic reusable for hooks that must derive results from the
+ * exact `useSyncExternalStore` snapshot they subscribed to, avoiding live-store
+ * re-reads while still evaluating `when()` during render.
+ * @param pages - Snapshot of page definitions to filter.
+ * @param options - Query filters.
+ * @returns Filtered pages in snapshot order.
+ */
+declare function queryPageDefinitions(pages: ReadonlyArray<PageDefinition>, options?: PageDefinitionQueryOptions): PageDefinition[];
+/**
+ * Unified registry for page definitions.
+ *
+ * Manages all page definitions (built-in and plugin-provided) with:
+ * - Validation on registration
+ * - Default values for order and group
+ * - Sorted caching (by order field)
+ * - Query filtering by mode, level, group, visibility
+ * - Subscription for reactive UI updates
+ * @example
+ * ```typescript
+ * // Register a page
+ * const cleanup = pageDefinitionRegistry.register({
+ *   id: 'settings',
+ *   name: 'Settings',
+ *   mode: 'peek',
+ *   level: 'any',
+ *   component: () => import('./SettingsView.js').then(m => ({ default: m.SettingsView })),
+ * });
+ *
+ * // Query pages
+ * const peekPages = pageDefinitionRegistry.query({ mode: 'peek' });
+ * const rootPages = pageDefinitionRegistry.query({ level: 'root' });
+ *
+ * // Subscribe to changes
+ * const unsubscribe = pageDefinitionRegistry.subscribe(() => {
+ *   console.log('Registry changed');
+ * });
+ * ```
+ */
+declare class PageDefinitionRegistry extends RegistryBase<string, PageDefinition> {
+  /**
+   * Cached sorted array of all pages.
+   * Invalidated on mutation.
+   */
+  private cachedAll;
+  /**
+   * Register a page definition.
+   *
+   * Validates the definition, applies defaults for order and group,
+   * and notifies subscribers.
+   * @param definition - The page to register
+   * @returns Cleanup function to unregister this page
+   * @throws Error if page with same ID already exists
+   * @throws Error if definition validation fails
+   */
+  register(definition: PageDefinition): () => void;
+  /**
+   * Get page definition by ID.
+   * @param id - Page identifier
+   * @returns Page definition or undefined if not registered
+   */
+  get(id: string): PageDefinition | undefined;
+  /**
+   * Get all registered pages, sorted by order field.
+   *
+   * Results are cached until registry is mutated.
+   * @returns Array of all page definitions, sorted by order (lower = first)
+   */
+  getAll(): ReadonlyArray<PageDefinition>;
+  /**
+   * Query pages with filters.
+   *
+   * All filters are optional and combine with AND logic:
+   * - mode: Exact match on page mode
+   * - level: Matches level or 'any' (see matchesLevel)
+   * - group: Exact match on navigation group
+   * - surface: Matches pages available on the given surface (see matchesSurface)
+   * - includeHidden: If false (default), exclude pages where when() returns false
+   * @param options - Query filters
+   * @returns Filtered pages, sorted by order
+   * @example
+   * ```typescript
+   * // Get all peek mode pages
+   * const peekPages = registry.query({ mode: 'peek' });
+   *
+   * // Get root-level pages (includes 'any' pages)
+   * const rootPages = registry.query({ level: 'root' });
+   *
+   * // Get all pages including hidden ones
+   * const allPages = registry.query({ includeHidden: true });
+   * ```
+   */
+  query(options?: PageDefinitionQueryOptions): PageDefinition[];
+  /**
+   * Unregister a page by ID.
+   *
+   * Removes the page and notifies subscribers.
+   * @param id - Page identifier
+   * @returns True if page was unregistered, false if not found
+   */
+  unregister(id: string): boolean;
+  /**
+   * Clear all registered pages.
+   *
+   * Removes all pages and notifies subscribers.
+   * Used primarily for testing or complete app teardown.
+   */
+  clear(): void;
+  /**
+   * Invalidate internal caches.
+   * Called after any mutation to force re-computation on next access.
+   */
+  private invalidateCache;
+}
+/**
+ * Global page definition registry instance.
+ *
+ * Singleton registry used throughout the application.
+ * Pages are registered at app startup via registerCorePages().
+ */
+declare const pageDefinitionRegistry: PageDefinitionRegistry;
+//#endregion
+//#region ui/kernel/src/pages/PageRegistry.d.ts
+/**
+ * Registry for managing page declarations.
+ */
+declare class PageRegistry extends RegistryBase<string, PageDeclaration> {
+  private cachedAll;
+  /**
+   * Register a page declaration.
+   * @param declaration - The page to register
+   * @returns Cleanup function to unregister
+   * @throws If page with same ID already exists, route is already registered, or declaration is invalid
+   */
+  register(declaration: PageDeclaration): () => void;
+  /**
+   * Get page by ID.
+   * @param id - Page identifier
+   * @returns Page declaration or undefined
+   */
+  get(id: string): PageDeclaration | undefined;
+  /**
+   * Get all registered pages.
+   *
+   * Result is cached and invalidated on any mutation. The returned array is
+   * frozen to prevent callers from mutating the registry's internal cache.
+   * @returns Frozen snapshot array of all page declarations
+   */
+  getAll(): ReadonlyArray<PageDeclaration>;
+  /**
+   * Get all pages that have routes (for router integration).
+   * @returns Array of routable page declarations
+   */
+  getRoutablePages(): PageDeclaration[];
+  /**
+   * Get pages by scope.
+   * @param scope - Widget scope to filter by
+   * @param includeAny - Include pages with 'any' scope (default: true)
+   * @returns Filtered pages
+   */
+  getByScope(scope: PageDeclaration['scope'], includeAny?: boolean): PageDeclaration[];
+  /**
+   * Get pages by navigation level.
+   * @param level - Navigation level to filter by
+   * @param includeAny - Include pages with 'any' level (default: true)
+   * @returns Filtered pages
+   */
+  getByLevel(level: PageLevel, includeAny?: boolean): PageDeclaration[];
+  /**
+   * Unregister a page by ID.
+   * @param id - Page identifier
+   * @returns True if page was unregistered, false if not found
+   */
+  unregister(id: string): boolean;
+  /**
+   * Clear all registered pages.
+   *
+   * No-ops silently when the registry is already empty, avoiding a
+   * spurious subscriber notification.
+   */
+  clear(): void;
+  /**
+   * Invalidate internal caches.
+   */
+  private invalidateCache;
+}
+/** Global page registry instance */
+declare const pageRegistry: PageRegistry;
+//#endregion
+//#region ui/kernel/src/pages/PageSectionRegistry.d.ts
+/**
+ * Registry for managing page section definitions.
+ *
+ * Provides registration, lookup, and filtering by parent page and category.
+ * Uses composite keys (parentPageId:sectionId) and caching for performance.
+ */
+declare class PageSectionRegistry extends RegistryBase<string, PageSectionDefinition> {
+  private cachedByParent;
+  /**
+   * Register a page section definition.
+   *
+   * Idempotent: if section is already registered, skips and returns cleanup.
+   * This supports React StrictMode which double-invokes effects.
+   * @param definition - Page section definition to register
+   * @returns Cleanup function to unregister the section
+   */
+  register(definition: PageSectionDefinition): () => void;
+  /**
+   * Get page section definition by parent page ID and section ID.
+   * @param parentPageId - Parent page ID
+   * @param sectionId - Section ID
+   * @returns Section definition or undefined if not found
+   */
+  get(parentPageId: string, sectionId: string): PageSectionDefinition | undefined;
+  /**
+   * Get all sections for a parent page, sorted by order.
+   * @param parentPageId - Parent page ID
+   * @returns Array of section definitions sorted by order
+   */
+  getByParent(parentPageId: string): PageSectionDefinition[];
+  /**
+   * Get sections filtered by parent page and category.
+   * @param parentPageId - Parent page ID
+   * @param category - Category to filter by
+   * @returns Array of matching section definitions, sorted by order
+   */
+  getByParentAndCategory(parentPageId: string, category: string): PageSectionDefinition[];
+  /**
+   * Remove section from registry.
+   * @param parentPageId - Parent page ID
+   * @param sectionId - Section ID
+   * @returns True if section was removed
+   */
+  unregister(parentPageId: string, sectionId: string): boolean;
+  /**
+   * Clear all sections.
+   */
+  clear(): void;
+  /**
+   * Create composite key from parent page ID and section ID.
+   * @param parentPageId - Parent page ID
+   * @param sectionId - Section ID
+   * @returns Composite key
+   */
+  private makeKey;
+  /**
+   * Invalidate internal caches.
+   */
+  private invalidateCache;
+}
+/**
+ * Global page section registry instance
+ */
+declare const pageSectionRegistry: PageSectionRegistry;
+//#endregion
+//#region ui/kernel/src/pages/registerPageBusHandler.d.ts
+/**
+ * Register bus handler that serves page metadata from the registry.
+ * @param bus - The MakaioBus instance to register on
+ * @returns Cleanup function to unregister the handler
+ * @example
+ * ```typescript
+ * import { registerPageBusHandler } from '@makaio/framework/ui-kernel';
+ * import { useBus } from '@makaio/framework/ui-hooks';
+ *
+ * function App() {
+ *   const bus = useBus();
+ *
+ *   useEffect(() => {
+ *     const cleanup = registerPageBusHandler(bus);
+ *     return cleanup;
+ *   }, [bus]);
+ * }
+ * ```
+ */
+declare function registerPageBusHandler(bus: IMakaioBus): () => void;
+//#endregion
+//#region ui/kernel/src/pages/persistence.d.ts
+interface PageLayoutPersistenceContext {
+  /** UI scope for this persisted layout. */
+  readonly scope: UiScope;
+  /** Optional host context identifier within the scope. */
+  readonly contextId?: string | null;
+}
+/**
+ * Build preference key for page layout.
+ * @param pageId - Page identifier
+ * @param context - Generic UI context identity.
+ * @returns Preference key context string
+ */
+declare function buildPageLayoutKey(pageId: string, context: PageLayoutPersistenceContext): string;
+/**
+ * Preference categories for page-related data.
+ */
+declare const PAGE_PREFERENCE_CATEGORIES: {
+  /** User's slot content customizations */readonly layout: "page-layout"; /** User's collapsed/expanded slot states */
+  readonly slotState: "page-slot-state"; /** User's edit mode preferences */
+  readonly editMode: "page-edit-mode";
+};
+//#endregion
+//#region ui/kernel/src/navigation/NavigationRegistry.d.ts
+/**
+ * Registry for managing navigation targets.
+ *
+ * Navigation targets are items that appear in navigation UI:
+ * - Quick Prompt suggestions
+ * - KaiTrigger hover menu
+ * - Breadcrumb dropdowns
+ * @example
+ * ```typescript
+ * navigationRegistry.register({
+ *   id: 'settings',
+ *   label: 'Settings',
+ *   icon: Settings,
+ *   level: 'root',
+ *   action: { type: 'focus', focusContext: 'settings' },
+ *   group: 'quick-access',
+ * });
+ *
+ * const targets = navigationRegistry.getByLevel('root');
+ * ```
+ */
+declare class NavigationRegistry extends RegistryBase<string, NavigationTarget> {
+  private cachedAll;
+  /**
+   * Register a navigation target.
+   * @param target - The navigation target to register
+   * @returns Cleanup function to unregister
+   * @throws If target with same ID already exists or target is invalid
+   */
+  register(target: NavigationTarget): () => void;
+  /**
+   * Get navigation target by ID.
+   * @param id - Target identifier
+   * @returns Navigation target or undefined
+   */
+  get(id: string): NavigationTarget | undefined;
+  /**
+   * Get all registered navigation targets.
+   * @returns Frozen readonly array of all targets sorted by order
+   */
+  getAll(): ReadonlyArray<NavigationTarget>;
+  /**
+   * Query navigation targets with filters.
+   * @param options - Query options
+   * @returns Filtered and sorted targets
+   */
+  query(options?: NavigationQueryOptions): NavigationTarget[];
+  /**
+   * Get targets available at a specific navigation level.
+   * @param level - Navigation level
+   * @returns Targets available at this level
+   */
+  getByLevel(level: NavigationLevel): NavigationTarget[];
+  /**
+   * Get targets in a specific group.
+   * @param group - Navigation group
+   * @returns Targets in this group
+   */
+  getByGroup(group: NavigationTarget['group']): NavigationTarget[];
+  /**
+   * Unregister a navigation target by ID.
+   * @param id - Target identifier
+   * @returns True if target was unregistered, false if not found
+   */
+  unregister(id: string): boolean;
+  /**
+   * Clear all registered navigation targets.
+   */
+  clear(): void;
+  /**
+   * Invalidate internal caches.
+   */
+  private invalidateCache;
+}
+/** Global navigation registry instance */
+declare const navigationRegistry: NavigationRegistry;
+//#endregion
+//#region ui/kernel/src/navigation/navigation-group-config.d.ts
+/**
+ * Configuration for a navigation group.
+ *
+ * Defines display label and sort order for groups in navigation UI.
+ */
+interface NavigationGroupConfig {
+  /** Navigation group identifier */
+  readonly id: NavigationGroup;
+  /** Display label for the group */
+  readonly label: string;
+  /** Sort order (lower appears first) */
+  readonly order: number;
+}
+/**
+ * Default navigation group configurations.
+ *
+ * Built-in groups for standard navigation patterns:
+ * - `navigate`: Workspace-switching pages (Dashboard, Chat, Git)
+ * - `analytics`: Analytics and reporting pages
+ * - `quick-access`: Quick-access overlay pages (Settings, Projects, Sessions)
+ */
+declare const defaultNavigationGroups: ReadonlyArray<NavigationGroupConfig>;
+//#endregion
+//#region ui/kernel/src/navigation/deriveBrowserTarget.d.ts
+/**
+ * Browser-side navigation URL target derivation.
+ * @packageDocumentation
+ */
+/**
+ * Maps a navigation URL to a `window.open` target name for browser singleton/reuse semantics.
+ *
+ * Used as a fallback when the bus RPC is unavailable. Under normal operation,
+ * the bus handler handles everything.
+ *
+ * Routing rules:
+ * - `/apps/:packageName` → `apps-{packageName}` (package-level singleton)
+ * - `/project/:id` → `project-{id}`
+ * - `/chat/:sessionId` → `chat-{sessionId}`
+ * - `/chat` → `_blank` (always a new window)
+ * - Single-segment static routes → that segment as a named target
+ * - Everything else → `_blank`
+ * @param url - Target URL path, e.g. '/apps/makaio.project-overview/main' or '/project/abc-123'
+ * @returns Target name for `window.open()` — named targets reuse windows, '_blank' always opens new
+ */
+declare function deriveBrowserTarget(url: string): string;
+//#endregion
+//#region ui/kernel/src/navigation/ui-schemas.d.ts
+/**
+ * UI surface domain schemas.
+ *
+ * Covers lifecycle events emitted by web surfaces (React apps) to signal
+ * rendering milestones. Surface-agnostic — any web surface (Electron, browser,
+ * mobile) can emit these events.
+ *
+ * Each key becomes a subject identifier as: `ui.{key}`
+ * @example
+ * ```typescript
+ * // Listen for any UI surface becoming ready
+ * bus.on(UiSubjects.ready, (ctx) => {
+ *   console.log(`${ctx.payload.surface} UI rendered`);
+ * });
+ * ```
+ */
+declare const UiSchemas: {
+  /**
+   * Emitted when a web surface has mounted its React tree and is visually ready.
+   *
+   * Fired once per surface mount (deduplicated across React StrictMode
+   * double-invocations). Consumers can use this to confirm that the UI is
+   * actually rendered, not just that a window or tab was opened.
+   *
+   * Subject: `ui.ready`
+   * Type: Event
+   */
+  ready: z.ZodObject<{
+    surface: z.ZodEnum<{
+      web: "web";
+      mobile: "mobile";
+      electron: "electron";
+      electrobun: "electrobun";
+      tray: "tray";
+    }>;
+    timestamp: z.ZodNumber;
+  }, z.core.$strip>;
+  /**
+   * Request to navigate to a URL.
+   *
+   * Handlers at different priorities decide what to do with the intent:
+   * - Electron main process (priority 100): parse URL, find-or-create window
+   * - Browser app shell (priority 10): open URL via window.open()
+   *
+   * Subject: `ui.navigate`
+   * Type: Request RPC
+   */
+  navigate: {
+    request: z.ZodObject<{
+      url: z.ZodString;
+    }, z.core.$strip>;
+    response: z.ZodObject<{
+      action: z.ZodEnum<{
+        focused: "focused";
+        opened: "opened";
+        navigated: "navigated";
+      }>;
+    }, z.core.$strip>;
+  };
+  /**
+   * Show the popover panel.
+   *
+   * Idempotent: when the popover is already visible this request is a no-op
+   * and the popover remains open. When `x` / `y` are provided the popover is
+   * anchored near that screen coordinate (e.g. the tray icon position); exact
+   * placement and clamping are host-specific. When omitted the host chooses a
+   * default position (typically centered on the primary display work area).
+   *
+   * Subject: `ui.popover.show`
+   * Type: Request RPC
+   */
+  'popover.show': {
+    request: z.ZodObject<{
+      x: z.ZodOptional<z.ZodNumber>;
+      y: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+    response: z.ZodObject<{
+      shown: z.ZodBoolean;
+    }, z.core.$strip>;
+  };
+  /**
+   * Fired when the global keyboard shortcut is triggered.
+   *
+   * Reserved for external listeners (e.g. extensions on a separate bus
+   * client) that want to react to the hotkey. The core Electron hotkey
+   * handler uses `bus.request(ui.popover.show)` directly instead of
+   * emitting this event, because local events don't fire local handlers
+   * on the same bus instance.
+   *
+   * Subject: `ui.shortcut.triggered`
+   * Type: Event
+   */
+  'shortcut.triggered': z.ZodObject<{
+    accelerator: z.ZodString;
+  }, z.core.$strip>;
+};
+/** Payload of the `ui.ready` event. */
+type UiReadyEvent = z.infer<(typeof UiSchemas)['ready']>;
+/** Payload of the `ui.navigate` request. */
+type UiNavigateRequest = z.infer<(typeof UiSchemas)['navigate']['request']>;
+/** Response from the `ui.navigate` RPC. */
+type UiNavigateResponse = z.infer<(typeof UiSchemas)['navigate']['response']>;
+/** Possible navigation actions returned by `ui.navigate`. */
+type UiNavigateAction = UiNavigateResponse['action'];
+/** Request payload for `ui.popover.show`. */
+type UiPopoverShowRequest = z.infer<(typeof UiSchemas)['popover.show']['request']>;
+/** Response from `ui.popover.show`. */
+type UiPopoverShowResponse = z.infer<(typeof UiSchemas)['popover.show']['response']>;
+/** Payload of the `ui.shortcut.triggered` event. */
+type UiShortcutTriggeredEvent = z.infer<(typeof UiSchemas)['shortcut.triggered']>;
+//#endregion
+//#region ui/kernel/src/navigation/ui-namespace.d.ts
+/**
+ * Bus namespace definition for UI surface lifecycle events.
+ *
+ * This is the canonical public namespace definition for the `ui.*`
+ * contract and should be imported by all producers/consumers.
+ * @example
+ * ```typescript
+ * // Emit the ready event after the React tree mounts
+ * bus.emit(UiSubjects.ready, { surface: 'electron', timestamp: Date.now() });
+ *
+ * // Request navigation
+ * await bus.request(UiSubjects.navigate, { url: '/project/abc-123' });
+ * ```
+ */
+declare const UiNamespace: _$_makaio_core0.BusNamespaceDefinition<"ui", {
+  ready: _$zod.ZodObject<{
+    surface: _$zod.ZodEnum<{
+      web: "web";
+      mobile: "mobile";
+      electron: "electron";
+      electrobun: "electrobun";
+      tray: "tray";
+    }>;
+    timestamp: _$zod.ZodNumber;
+  }, _$zod_v4_core0.$strip>;
+  navigate: {
+    request: _$zod.ZodObject<{
+      url: _$zod.ZodString;
+    }, _$zod_v4_core0.$strip>;
+    response: _$zod.ZodObject<{
+      action: _$zod.ZodEnum<{
+        focused: "focused";
+        opened: "opened";
+        navigated: "navigated";
+      }>;
+    }, _$zod_v4_core0.$strip>;
+  };
+  'popover.show': {
+    request: _$zod.ZodObject<{
+      x: _$zod.ZodOptional<_$zod.ZodNumber>;
+      y: _$zod.ZodOptional<_$zod.ZodNumber>;
+    }, _$zod_v4_core0.$strip>;
+    response: _$zod.ZodObject<{
+      shown: _$zod.ZodBoolean;
+    }, _$zod_v4_core0.$strip>;
+  };
+  'shortcut.triggered': _$zod.ZodObject<{
+    accelerator: _$zod.ZodString;
+  }, _$zod_v4_core0.$strip>;
+}>;
+/**
+ * Typed subject tree for the UI namespace.
+ *
+ * Use this for all emit/on calls instead of raw string subjects.
+ */
+declare const UiSubjects: _$_makaio_core0.BusSubjects<_$_makaio_core0.FlatSubjectDefinitions<"ui", {
+  ready: _$zod.ZodObject<{
+    surface: _$zod.ZodEnum<{
+      web: "web";
+      mobile: "mobile";
+      electron: "electron";
+      electrobun: "electrobun";
+      tray: "tray";
+    }>;
+    timestamp: _$zod.ZodNumber;
+  }, _$zod_v4_core0.$strip>;
+  navigate: {
+    request: _$zod.ZodObject<{
+      url: _$zod.ZodString;
+    }, _$zod_v4_core0.$strip>;
+    response: _$zod.ZodObject<{
+      action: _$zod.ZodEnum<{
+        focused: "focused";
+        opened: "opened";
+        navigated: "navigated";
+      }>;
+    }, _$zod_v4_core0.$strip>;
+  };
+  'popover.show': {
+    request: _$zod.ZodObject<{
+      x: _$zod.ZodOptional<_$zod.ZodNumber>;
+      y: _$zod.ZodOptional<_$zod.ZodNumber>;
+    }, _$zod_v4_core0.$strip>;
+    response: _$zod.ZodObject<{
+      shown: _$zod.ZodBoolean;
+    }, _$zod_v4_core0.$strip>;
+  };
+  'shortcut.triggered': _$zod.ZodObject<{
+    accelerator: _$zod.ZodString;
+  }, _$zod_v4_core0.$strip>;
+}>, "ui">;
+//#endregion
+//#region ui/kernel/src/onboarding/types.d.ts
+/**
+ * Kai mascot state for a step.
+ *
+ * Controls the mascot animation shown alongside the step content.
+ * Inlined here to avoid coupling kernel to `\@makaio/ui-components`.
+ */
+type OnboardingKaiState = 'wave' | 'loading' | 'neutral' | 'success' | 'smile';
+/**
+ * Information about an adapter driver.
+ *
+ * Structural type that mirrors `AdapterInfo` from
+ * `\@makaio/services/settings/namespace` to avoid a platform-services
+ * dependency at the kernel tier.
+ */
+interface AdapterInfo {
+  /** Adapter driver name (e.g., 'claude-code', 'openai-node') */
+  adapterName: string;
+  /** Human-readable display name for UI */
+  displayName: string;
+  /** Short description for tooltips/selection UI */
+  description?: string;
+  /** Whether this adapter driver is enabled in runtime config */
+  enabled: boolean;
+  /** Number of configured instances for this adapter */
+  configCount: number;
+  /** Whether this adapter currently has a registered log-import provider */
+  supportsLogImport: boolean;
+  /** Help links for setup and documentation. */
+  helpLinks?: Array<{
+    label: string;
+    url: string;
+  }>;
+  /** Setup instructions in Markdown format. */
+  instructions?: string;
+  /** Readiness signal describing required configuration work, if any. */
+  readiness?: 'ready' | 'missing-credentials' | 'needs-setup';
+  /** Stable client identifier this adapter belongs to. */
+  clientId?: string;
+  /** Wire protocol this adapter speaks (for provider matching). */
+  protocol?: 'anthropic' | 'openai';
+  /** Provider definition IDs this adapter can run against. */
+  providerDefinitionIds?: string[];
+}
+/**
+ * Context evaluated once at the start of the onboarding flow.
+ *
+ * Used by step {@link OnboardingStepDefinition.condition} callbacks to decide
+ * whether a step should be included in the active flow.
+ */
+interface OnboardingContext {
+  /** Adapters available at flow start. */
+  readonly adapters: ReadonlyArray<AdapterInfo>;
+  /** Extensions loaded at flow start. */
+  readonly extensions: ReadonlyArray<ExtensionInfo>;
+  /** Client records available at flow start. */
+  readonly clients: ReadonlyArray<ClientRecord>;
+}
+/**
+ * Props injected into every step component by the orchestrator.
+ *
+ * The flow-state and action props (flowState, actions) are injected
+ * separately at the `\@makaio/ui-hooks` tier via `useOnboardingFlow`.
+ * This base interface carries only the navigation callbacks so that
+ * step components can be typed against the kernel contract.
+ */
+interface OnboardingStepProps {
+  /** Advance to the next step. */
+  onNext: () => void;
+  /** Return to the previous step. */
+  onBack: () => void;
+  /** Skip the entire onboarding flow. */
+  onSkip: () => void;
+  /** Complete the flow (call only from the final step). */
+  onComplete: () => void;
+}
+/**
+ * Declarative definition of one onboarding step.
+ *
+ * Steps are registered via {@link OnboardingStepRegistry} and sorted by
+ * {@link OnboardingStepDefinition.order} before display.
+ * @example
+ * ```typescript
+ * const cleanup = onboardingStepRegistry.register({
+ *   id: 'welcome',
+ *   title: 'Welcome',
+ *   kaiState: 'wave',
+ *   order: 10,
+ *   component: WelcomeStep,
+ * });
+ * ```
+ */
+interface OnboardingStepDefinition {
+  /** Stable unique identifier. Must be non-empty. */
+  id: string;
+  /** Display title shown in the progress indicator. */
+  title: string;
+  /** Mascot state rendered alongside this step. */
+  kaiState: OnboardingKaiState;
+  /**
+   * Sort order. Lower values appear earlier.
+   * Built-in steps use 10–50. Plugin steps should use 100+.
+   */
+  order: number;
+  /**
+   * The step content component.
+   *
+   * Typed as `object` because a callable/exotic union
+   * (`((...args: unknown[]) => unknown) | (new (...args: unknown[]) => unknown)`)
+   * fails due to contravariance on `ComponentClass` constructor params —
+   * `unknown` is not assignable to the concrete props. `object` is the widest
+   * type that all `ComponentLike<P>` values satisfy while still rejecting
+   * primitives. `validateStepDefinition` enforces the callable/exotic shape
+   * at runtime; the hooks tier narrows back to `ComponentLike<OnboardingStepProps>`
+   * at retrieval time via `narrowToHooksStepDefinitions`.
+   */
+  component: object;
+  /**
+   * Optional condition evaluated once at mount with the pre-flow adapter state.
+   * Return false to exclude this step from the active flow.
+   * @remarks
+   * Conditions are evaluated exactly once when the flow mounts, using the
+   * adapter and plugin snapshot at that moment. Do not depend on mutable
+   * flow state — that state does not exist yet when conditions run.
+   * @param context - Snapshot of the onboarding context at flow start.
+   */
+  condition?: (context: OnboardingContext) => boolean;
+  /** Whether the user can skip this step individually. */
+  skippable?: boolean;
+}
+//#endregion
+//#region ui/kernel/src/onboarding/OnboardingStepRegistry.d.ts
+/**
+ * Registry for onboarding step definitions.
+ *
+ * Steps are registered declaratively and sorted by their `order` field for display.
+ * The registry is idempotent: re-registering a step with the same ID silently
+ * replaces the previous registration, making it safe to call from React StrictMode
+ * double-invoked effects.
+ * @example
+ * ```typescript
+ * // Register a step
+ * const cleanup = onboardingStepRegistry.register({
+ *   id: 'welcome',
+ *   title: 'Welcome',
+ *   kaiState: 'wave',
+ *   order: 10,
+ *   component: WelcomeStep,
+ * });
+ *
+ * // Retrieve all steps sorted by order
+ * const steps = onboardingStepRegistry.getAll();
+ *
+ * // Subscribe to changes
+ * const unsubscribe = onboardingStepRegistry.subscribe(() => {
+ *   console.log('Registry changed');
+ * });
+ *
+ * // Cleanup on unmount
+ * cleanup();
+ * ```
+ */
+declare class OnboardingStepRegistry extends RegistryBase<string, OnboardingStepDefinition> {
+  /**
+   * Cached sorted array of all steps.
+   * Invalidated on every mutation.
+   */
+  private cachedAll;
+  /**
+   * Register an onboarding step definition.
+   *
+   * Idempotent: if a step with the same ID is already registered it is
+   * silently replaced. This makes registration safe to call from React
+   * StrictMode double-invoked effects.
+   *
+   * Validates required fields before storing.
+   * @param definition - The step to register
+   * @returns Cleanup function that unregisters this step when called
+   * @throws Error if definition validation fails
+   */
+  register(definition: OnboardingStepDefinition): () => void;
+  /**
+   * Get a step definition by ID.
+   * @param id - Step identifier
+   * @returns Step definition or undefined if not registered
+   */
+  get(id: string): OnboardingStepDefinition | undefined;
+  /**
+   * Get all registered steps, sorted ascending by order.
+   *
+   * Results are cached until the registry is mutated.
+   * @returns Array of all step definitions, sorted by order (lower = first)
+   */
+  getAll(): ReadonlyArray<OnboardingStepDefinition>;
+  /**
+   * Unregister a step by ID.
+   *
+   * Removes the step and notifies subscribers.
+   * @param id - Step identifier
+   * @returns True if the step was found and removed, false if not registered
+   */
+  unregister(id: string): boolean;
+  /**
+   * Clear all registered steps.
+   *
+   * Used primarily for testing or complete app teardown.
+   */
+  clear(): void;
+  /**
+   * Invalidate the sorted cache.
+   * Called after any mutation to force re-computation on next {@link getAll} access.
+   */
+  private invalidateCache;
+}
+/**
+ * Global onboarding step registry instance.
+ *
+ * Singleton used throughout the application.
+ * Built-in steps are registered at app startup.
+ */
+declare const onboardingStepRegistry: OnboardingStepRegistry;
+//#endregion
+//#region ui/kernel/src/onboarding/plugin-categories.d.ts
+/**
+ * plugin-categories — Plugin category domain logic for onboarding.
+ *
+ * Defines the canonical plugin category configuration, default-enabled
+ * derivation, and category lookup. Pure constants with no runtime side effects.
+ *
+ * The `persistPluginEnabled` bus helper lives in `\@makaio/ui-hooks` (it
+ * performs bus requests and requires `\@makaio/services-core`).
+ * @packageDocumentation
+ */
+/**
+ * Category metadata including which plugin names belong here and what the
+ * default enabled state is for newly discovered members.
+ */
+interface PluginCategory {
+  /** Display label */
+  readonly label: string;
+  /** Set of plugin names that belong to this category */
+  readonly members: ReadonlySet<string>;
+  /** Whether extensions in this category start enabled by default */
+  readonly defaultEnabled: boolean;
+  /**
+   * When true, toggles for this category are disabled (always-on).
+   * Used for Essential extensions.
+   */
+  readonly alwaysEnabled: boolean;
+}
+/**
+ * Ordered list of plugin categories used to partition the full plugin list.
+ *
+ * Immutability is enforced structurally: the array is `ReadonlyArray` and
+ * each category's `members` field is typed as `ReadonlySet<string>`, so
+ * TypeScript prevents mutation at all call sites. Runtime freeze is not
+ * applied — this constant is consumed only by TypeScript callers in the
+ * framework shell.
+ */
+declare const PLUGIN_CATEGORIES: ReadonlyArray<PluginCategory>;
+/**
+ * Derive the initial enabled state for a plugin based on its category.
+ * @param category - The category this plugin belongs to
+ * @returns True when the plugin should be toggled on by default
+ */
+declare function deriveDefaultEnabled(category: PluginCategory): boolean;
+/**
+ * Find which category a plugin belongs to, or return a synthetic "Other" category
+ * when the plugin name is not listed in any known category.
+ * @param pluginName - Plugin name to categorise
+ * @returns The matching {@link PluginCategory}, or a catch-all "Other" category
+ */
+declare function findCategory(pluginName: string): PluginCategory;
+//#endregion
+//#region ui/kernel/src/tray-config.d.ts
+/**
+ * Shared tray popover sizing constants.
+ *
+ * Centralises every pixel and grid value that must agree between the Electron
+ * main-process window creation (`tray-popover.ts`) and the React canvas layout
+ * (`tray-view.tsx`). A single edit here propagates to both surfaces.
+ * @packageDocumentation
+ */
+/** Tray popover window width in CSS/screen pixels. */
+declare const TRAY_WINDOW_WIDTH_PX = 480;
+/** Tray popover window height in CSS/screen pixels. */
+declare const TRAY_WINDOW_HEIGHT_PX = 500;
+/**
+ * Horizontal padding on each side applied by the canvas container when in
+ * fixed mode (`.fixed .gridArea { padding: 8px }`). Subtracted from the
+ * window width on both sides to derive the usable grid width.
+ */
+declare const TRAY_CANVAS_HORIZONTAL_PADDING_PX = 8;
+/** Number of grid columns in the tray canvas (non-responsive, fixed). */
+declare const TRAY_GRID_COLS = 2;
+/** Row height in pixels for the tray widget grid. */
+declare const TRAY_ROW_HEIGHT_PX = 60;
+/** Cell margin tuple `[horizontal, vertical]` in pixels used by the tray `react-grid-layout` instance. */
+declare const TRAY_CELL_MARGIN: [number, number];
+/**
+ * Effective grid width passed to the non-responsive `GridLayout`.
+ *
+ * Derived as: `TRAY_WINDOW_WIDTH_PX - 2 * TRAY_CANVAS_HORIZONTAL_PADDING_PX`
+ * = 480 - 16 = 464 px.
+ */
+declare const TRAY_GRID_WIDTH_PX: number;
+//#endregion
+export { type AdapterInfo, type ComponentLike, DEFAULT_WIDGET_UI_CONTEXT, type ExtensionBrowserContribution, type ExtensionBrowserFactory, type ExtensionBrowserFactoryContext, type ExtensionBrowserFactoryResolution, type IconComponentLike, type IconComponentProps, type LazyComponentModule, type ListWidgetsRequest, type ListWidgetsResponse, type NavigationAction, type NavigationGroup, type NavigationGroupConfig, type NavigationGroupMap, type NavigationLevel, type NavigationQueryOptions, NavigationRegistry, type NavigationTarget, type OnboardingContext, type OnboardingKaiState, type OnboardingStepDefinition, type OnboardingStepProps, OnboardingStepRegistry, PAGE_PREFERENCE_CATEGORIES, PLUGIN_CATEGORIES, type PageComponentProps, type PageDeclaration, type PageDefinition, type PageDefinitionQueryOptions, PageDefinitionRegistry, type PageLayoutPersistenceContext, type PageLevel, type PageMode, PageRegistry, type PageSectionDefinition, type PageSectionProps, PageSectionRegistry, type PageSectionStatus, type PluginCategory, RegistryBase, type RuntimeReadyWaitResult, type RuntimeReadyWaiter, SHELL_BG_COLOR, SHELL_FONT_FAMILY, SHELL_TEXT_COLOR, type ShellContribution, type ShellProps, type SlotContent, type SlotDefinition, type SlotId, type SlotPlacement, type SlotPlacementMap, TRAY_CANVAS_HORIZONTAL_PADDING_PX, TRAY_CELL_MARGIN, TRAY_GRID_COLS, TRAY_GRID_WIDTH_PX, TRAY_ROW_HEIGHT_PX, TRAY_WINDOW_HEIGHT_PX, TRAY_WINDOW_WIDTH_PX, UiNamespace, type UiNavigateAction, type UiNavigateRequest, type UiNavigateResponse, type UiPopoverShowRequest, type UiPopoverShowResponse, type UiReadyEvent, UiSchemas, type UiShortcutTriggeredEvent, UiSubjects, type UnregisterPayload, type WidgetActivatedPayload, type WidgetActivation, type WidgetActivationContext, type WidgetDefinition, type WidgetDefinitionPayload, type WidgetInstance, type WidgetLayout, WidgetNamespace, type WidgetPlacement, type WidgetProps, WidgetRawSchemas, WidgetRegistry, WidgetSchemas, type WidgetScope, type WidgetScopeDefinition, type WidgetSize, type WidgetSlotId, type WidgetSlotState, WidgetSubjects, buildPageLayoutKey, clearExtensionBrowserFactories, createRuntimeReadyWaiter, defaultNavigationGroups, deriveBrowserTarget, deriveDefaultEnabled, deriveTrayLayout, eraseWidgetConfig, findCategory, getRegisteredExtensionBrowserFactory, isOverlayMode, isWidgetLayout, isWidgetPlacement, navigationRegistry, onboardingStepRegistry, pageDefinitionRegistry, pageRegistry, pageSectionRegistry, queryPageDefinitions, registerExtensionBrowserFactory, registerExtensionUI, registerPageBusHandler, registerWidget, registerWidgets, resolveExtensionBrowserFactory, runCleanupsInReverse, subscribeToWidgetEvents, unregisterExtensionBrowserFactory, unregisterWidget, widgetMatchesScope, widgetRegistry, widgetScopeRegistry };