create-lego-one 2.0.12 → 2.0.14

package/template/docs/framework/plans/07-communication-system.md

@@ -0,0 +1,1106 @@
+# Communication System Implementation Plan
+
+> **For AI Implementing This Plan:** This is document 07 of 13. Complete documents 01-06 first.
+
+**Goal:** Implement Garfish channel bus for inter-plugin communication, custom toast notification system using channels as demonstration, and state synchronization between host and plugins.
+
+**Architecture:** Use Garfish's built-in channel system for pub/sub messaging. Plugins can publish events and host can subscribe (and vice versa). Toast system demonstrates plugin→host communication pattern.
+
+**Tech Stack:** Garfish channels, React hooks, Zustand state bridge, TypeScript
+
+---
+
+## Prerequisites
+
+- ✅ Completed `01-infrastructure-setup.md`
+- ✅ Completed `02-pocketbase-setup.md`
+- ✅ Completed `03-host-kernel.md` (shared state bridge)
+- ✅ Completed `04-auth-system.md`
+- ✅ Completed `05-multitenancy-rbac.md`
+- ✅ Completed `06-ui-components.md` (toast components)
+
+---
+
+## Task 1: Create Garfish Channel Types and Interfaces
+
+**Files:**
+- Create: `host/src/kernel/channels/types.ts`
+- Create: `host/src/kernel/channels/events.ts`
+
+### Step 1: Create channel types
+
+**File:** `host/src/kernel/channels/types.ts`
+
+```typescript
+import type { Garfish } from 'garfish';
+
+/**
+ * Channel names for different communication topics
+ */
+export enum ChannelName {
+  TOAST = 'lego:toast',
+  NAVIGATION = 'lego:navigation',
+  STATE_UPDATE = 'lego:state:update',
+  PLUGIN_READY = 'lego:plugin:ready',
+  PLUGIN_ERROR = 'lego:plugin:error',
+  AUTH_CHANGE = 'lego:auth:change',
+  ORGANIZATION_CHANGE = 'lego:organization:change',
+}
+
+/**
+ * Base event interface
+ */
+export interface ChannelEvent {
+  id: string;
+  timestamp: number;
+  source?: string; // Plugin name or 'host'
+}
+
+/**
+ * Toast event data
+ */
+export interface ToastEventData extends ChannelEvent {
+  type: 'success' | 'error' | 'info' | 'warning';
+  title: string;
+  description?: string;
+  duration?: number;
+}
+
+/**
+ * Navigation event data
+ */
+export interface NavigationEventData extends ChannelEvent {
+  path: string;
+  replace?: boolean;
+}
+
+/**
+ * State update event data
+ */
+export interface StateUpdateEventData extends ChannelEvent {
+  key: string;
+  value: unknown;
+}
+
+/**
+ * Plugin ready event data
+ */
+export interface PluginReadyEventData extends ChannelEvent {
+  pluginName: string;
+  version: string;
+}
+
+/**
+ * Plugin error event data
+ */
+export interface PluginErrorEventData extends ChannelEvent {
+  pluginName: string;
+  error: string;
+  stack?: string;
+}
+
+/**
+ * Auth change event data
+ */
+export interface AuthChangeEventData extends ChannelEvent {
+  isAuthenticated: boolean;
+  userId?: string;
+  organizationId?: string;
+}
+
+/**
+ * Organization change event data
+ */
+export interface OrganizationChangeEventData extends ChannelEvent {
+  organizationId: string;
+  organizationName: string;
+}
+
+/**
+ * Channel message payload
+ */
+export type ChannelMessage =
+  | { channel: ChannelName.TOAST; data: ToastEventData }
+  | { channel: ChannelName.NAVIGATION; data: NavigationEventData }
+  | { channel: ChannelName.STATE_UPDATE; data: StateUpdateEventData }
+  | { channel: ChannelName.PLUGIN_READY; data: PluginReadyEventData }
+  | { channel: ChannelName.PLUGIN_ERROR; data: PluginErrorEventData }
+  | { channel: ChannelName.AUTH_CHANGE; data: AuthChangeEventData }
+  | { channel: ChannelName.ORGANIZATION_CHANGE; data: OrganizationChangeEventData };
+
+/**
+ * Channel subscriber callback
+ */
+export type ChannelSubscriber<T = ChannelMessage> = (data: T) => void | Promise<void>;
+
+/**
+ * Channel API
+ */
+export interface ChannelAPI {
+  publish: <T extends ChannelMessage>(message: T) => void;
+  subscribe: <T extends ChannelMessage>(
+    channel: ChannelName,
+    callback: ChannelSubscriber<T>
+  ) => () => void; // Returns unsubscribe function
+  unsubscribe: (channel: ChannelName, callback: ChannelSubscriber) => void;
+}
+```
+
+### Step 2: Create event constants
+
+**File:** `host/src/kernel/channels/events.ts`
+
+```typescript
+/**
+ * Event constants for type-safe event publishing
+ */
+export const Events = {
+  TOAST: {
+    SUCCESS: (title: string, description?: string) => ({
+      type: 'success' as const,
+      title,
+      description,
+    }),
+    ERROR: (title: string, description?: string) => ({
+      type: 'error' as const,
+      title,
+      description,
+    }),
+    INFO: (title: string, description?: string) => ({
+      type: 'info' as const,
+      title,
+      description,
+    }),
+    WARNING: (title: string, description?: string) => ({
+      type: 'warning' as const,
+      title,
+      description,
+    }),
+  },
+} as const;
+```
+
+---
+
+## Task 2: Create Channel Bus Service
+
+**Files:**
+- Create: `host/src/kernel/channels/ChannelBus.ts`
+
+### Step 1: Create channel bus singleton
+
+**File:** `host/src/kernel/channels/ChannelBus.ts`
+
+```typescript
+import Garfish from 'garfish';
+import type {
+  ChannelName,
+  ChannelMessage,
+  ChannelSubscriber,
+  ChannelAPI,
+} from './types';
+
+/**
+ * ChannelBus - Singleton service for inter-plugin communication using Garfish channels
+ */
+class ChannelBus implements ChannelAPI {
+  private garfishInstance: typeof Garfish | null = null;
+  private subscribers: Map<ChannelName, Set<ChannelSubscriber>> = new Map();
+  private initialized = false;
+
+  /**
+   * Initialize the channel bus with Garfish instance
+   */
+  initialize(garfish: typeof Garfish): void {
+    if (this.initialized) {
+      console.warn('[ChannelBus] Already initialized');
+      return;
+    }
+
+    this.garfishInstance = garfish;
+    this.initialized = true;
+
+    console.log('[ChannelBus] Initialized');
+  }
+
+  /**
+   * Publish a message to a channel
+   */
+  publish<T extends ChannelMessage>(message: T): void {
+    if (!this.initialized || !this.garfishInstance) {
+      console.warn('[ChannelBus] Not initialized, cannot publish message');
+      return;
+    }
+
+    const { channel, data } = message;
+
+    // Add metadata
+    const enrichedData = {
+      ...data,
+      id: data.id || this.generateId(),
+      timestamp: data.timestamp || Date.now(),
+      source: data.source || 'host',
+    };
+
+    // Publish via Garfish channel
+    try {
+      this.garfishInstance.channel.emit(channel, enrichedData);
+    } catch (error) {
+      console.error('[ChannelBus] Failed to publish message:', error);
+    }
+
+    // Also notify local subscribers (in same app context)
+    const channelSubscribers = this.subscribers.get(channel);
+    if (channelSubscribers) {
+      channelSubscribers.forEach((callback) => {
+        try {
+          callback({ channel, data: enrichedData } as T);
+        } catch (error) {
+          console.error('[ChannelBus] Subscriber callback error:', error);
+        }
+      });
+    }
+  }
+
+  /**
+   * Subscribe to a channel
+   * Returns unsubscribe function
+   */
+  subscribe<T extends ChannelMessage>(
+    channel: ChannelName,
+    callback: ChannelSubscriber<T>
+  ): () => void {
+    if (!this.initialized || !this.garfishInstance) {
+      console.warn('[ChannelBus] Not initialized, subscription may not work');
+    }
+
+    // Add to local subscribers
+    if (!this.subscribers.has(channel)) {
+      this.subscribers.set(channel, new Set());
+    }
+    this.subscribers.get(channel)!.add(callback as ChannelSubscriber);
+
+    // Also subscribe to Garfish channel for cross-app communication
+    if (this.garfishInstance) {
+      try {
+        this.garfishInstance.channel.on(channel, callback as any);
+      } catch (error) {
+        console.error('[ChannelBus] Failed to subscribe to Garfish channel:', error);
+      }
+    }
+
+    console.log(`[ChannelBus] Subscribed to channel: ${channel}`);
+
+    // Return unsubscribe function
+    return () => this.unsubscribe(channel, callback as ChannelSubscriber);
+  }
+
+  /**
+   * Unsubscribe from a channel
+   */
+  unsubscribe(channel: ChannelName, callback: ChannelSubscriber): void {
+    // Remove from local subscribers
+    const channelSubscribers = this.subscribers.get(channel);
+    if (channelSubscribers) {
+      channelSubscribers.delete(callback);
+    }
+
+    // Also unsubscribe from Garfish channel
+    if (this.garfishInstance) {
+      try {
+        this.garfishInstance.channel.off(channel, callback as any);
+      } catch (error) {
+        console.error('[ChannelBus] Failed to unsubscribe from Garfish channel:', error);
+      }
+    }
+
+    console.log(`[ChannelBus] Unsubscribed from channel: ${channel}`);
+  }
+
+  /**
+   * Unsubscribe all from a channel
+   */
+  unsubscribeAll(channel: ChannelName): void {
+    const channelSubscribers = this.subscribers.get(channel);
+    if (channelSubscribers) {
+      channelSubscribers.forEach((callback) => {
+        if (this.garfishInstance) {
+          this.garfishInstance.channel.off(channel, callback as any);
+        }
+      });
+      channelSubscribers.clear();
+    }
+  }
+
+  /**
+   * Clear all subscribers
+   */
+  clear(): void {
+    this.subscribers.forEach((_, channel) => {
+      this.unsubscribeAll(channel);
+    });
+    this.subscribers.clear();
+  }
+
+  /**
+   * Generate unique ID for events
+   */
+  private generateId(): string {
+    return `evt_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+  }
+
+  /**
+   * Get list of active channels
+   */
+  getActiveChannels(): ChannelName[] {
+    return Array.from(this.subscribers.keys());
+  }
+
+  /**
+   * Get subscriber count for a channel
+   */
+  getSubscriberCount(channel: ChannelName): number {
+    return this.subscribers.get(channel)?.size || 0;
+  }
+}
+
+// Export singleton instance
+export const channelBus = new ChannelBus();
+
+/**
+ * Initialize channel bus (call from host bootstrap)
+ */
+export function initializeChannelBus(garfish: typeof Garfish): void {
+  channelBus.initialize(garfish);
+}
+```
+
+---
+
+## Task 3: Create Toast Channel Integration
+
+**Files:**
+- Create: `host/src/kernel/channels/integrations/ToastIntegration.tsx`
+
+### Step 1: Create toast integration component
+
+**File:** `host/src/kernel/channels/integrations/ToastIntegration.tsx`
+
+```typescript
+import { useEffect } from 'react';
+import { toast } from '../../components/ui/use-toast';
+import { channelBus } from '../ChannelBus';
+import { ChannelName, type ToastEventData } from '../types';
+
+/**
+ * ToastIntegration - Listens to toast channel events and displays them
+ *
+ * This component subscribes to the TOAST channel and shows toasts
+ * when plugins publish events to it. This demonstrates plugin → host communication.
+ */
+export function ToastIntegration() {
+  useEffect(() => {
+    // Subscribe to toast channel
+    const unsubscribe = channelBus.subscribe<ToastEventData>(
+      ChannelName.TOAST,
+      ({ data }) => {
+        const { type, title, description, duration = 5000 } = data;
+
+        // Map toast type to variant
+        const variant = type === 'error' || type === 'warning' ? 'destructive' : 'default';
+
+        // Show toast
+        toast({
+          variant,
+          title,
+          description,
+          // Note: duration would need custom implementation
+          // The default toast doesn't support duration prop
+        });
+
+        console.log(`[ToastIntegration] Received toast:`, { type, title, description });
+      }
+    );
+
+    return () => {
+      unsubscribe();
+    };
+  }, []);
+
+  // This component doesn't render anything
+  return null;
+}
+
+/**
+ * Hook to publish toast events (for plugins to use)
+ */
+export function usePublishToast() {
+  return (data: Omit<ToastEventData, 'id' | 'timestamp' | 'source'>) => {
+    channelBus.publish({
+      channel: ChannelName.TOAST,
+      data: {
+        ...data,
+        id: `toast_${Date.now()}`,
+        timestamp: Date.now(),
+        source: 'plugin',
+      },
+    });
+  };
+}
+```
+
+---
+
+## Task 4: Create Channel Hooks for Plugins
+
+**Files:**
+- Create: `host/src/kernel/channels/hooks.ts`
+
+### Step 1: Create channel hooks
+
+**File:** `host/src/kernel/channels/hooks.ts`
+
+```typescript
+import { useEffect, useCallback, useRef } from 'react';
+import { channelBus } from './ChannelBus';
+import { ChannelName, type ChannelMessage, type ChannelSubscriber } from './types';
+
+/**
+ * Subscribe to a Garfish channel
+ *
+ * @param channel - The channel name to subscribe to
+ * @param callback - The callback function when messages are received
+ * @param deps - Dependencies for re-subscription
+ */
+export function useChannel<T extends ChannelMessage>(
+  channel: ChannelName,
+  callback: ChannelSubscriber<T>,
+  deps: React.DependencyList = []
+) {
+  const callbackRef = useRef(callback);
+
+  // Update callback ref without causing re-subscription
+  useEffect(() => {
+    callbackRef.current = callback;
+  }, [callback]);
+
+  useEffect(() => {
+    const unsubscribe = channelBus.subscribe<T>(channel, (data) => {
+      callbackRef.current(data);
+    });
+
+    return () => {
+      unsubscribe();
+    };
+  }, [channel, ...deps]);
+}
+
+/**
+ * Publish to a Garfish channel
+ *
+ * @returns A function to publish messages
+ */
+export function usePublish() {
+  return useCallback(<T extends ChannelMessage>(message: T) => {
+    channelBus.publish(message);
+  }, []);
+}
+
+/**
+ * Publish toast notifications
+ *
+ * @returns A function to publish toast messages
+ */
+export function useToastChannel() {
+  const publish = usePublish();
+
+  return useCallback((data: Omit<ChannelMessage & { channel: ChannelName.TOAST }, 'channel'>['data']) => {
+    publish({
+      channel: ChannelName.TOAST,
+      data: {
+        ...data,
+        id: `toast_${Date.now()}`,
+        timestamp: Date.now(),
+        source: 'plugin',
+      },
+    });
+  }, [publish]);
+}
+
+/**
+ * Publish navigation events
+ *
+ * @returns A function to publish navigation messages
+ */
+export function useNavigationChannel() {
+  const publish = usePublish();
+
+  return useCallback((path: string, replace = false) => {
+    publish({
+      channel: ChannelName.NAVIGATION,
+      data: {
+        path,
+        replace,
+        id: `nav_${Date.now()}`,
+        timestamp: Date.now(),
+        source: 'plugin',
+      },
+    });
+  }, [publish]);
+}
+
+/**
+ * Publish state updates
+ *
+ * @returns A function to publish state update messages
+ */
+export function useStateUpdateChannel() {
+  const publish = usePublish();
+
+  return useCallback((key: string, value: unknown) => {
+    publish({
+      channel: ChannelName.STATE_UPDATE,
+      data: {
+        key,
+        value,
+        id: `state_${Date.now()}`,
+        timestamp: Date.now(),
+        source: 'plugin',
+      },
+    });
+  }, [publish]);
+}
+
+/**
+ * Publish plugin ready event
+ *
+ * Call this when your plugin has finished initializing
+ */
+export function usePluginReady(pluginName: string, version: string) {
+  const publish = usePublish();
+
+  useEffect(() => {
+    publish({
+      channel: ChannelName.PLUGIN_READY,
+      data: {
+        pluginName,
+        version,
+        id: `ready_${Date.now()}`,
+        timestamp: Date.now(),
+        source: pluginName,
+      },
+    });
+  }, [pluginName, version, publish]);
+}
+
+/**
+ * Publish plugin error event
+ *
+ * Call this when your plugin encounters an error
+ */
+export function usePublishPluginError() {
+  const publish = usePublish();
+
+  return useCallback((pluginName: string, error: string, stack?: string) => {
+    publish({
+      channel: ChannelName.PLUGIN_ERROR,
+      data: {
+        pluginName,
+        error,
+        stack,
+        id: `error_${Date.now()}`,
+        timestamp: Date.now(),
+        source: pluginName,
+      },
+    });
+  }, [publish]);
+}
+
+/**
+ * Listen for auth changes
+ */
+export function useAuthChannel(callback: (data: ChannelMessage & { channel: ChannelName.AUTH_CHANGE })['data']) {
+  return useChannel(ChannelName.AUTH_CHANGE, callback, []);
+}
+
+/**
+ * Listen for organization changes
+ */
+export function useOrganizationChannel(callback: (data: ChannelMessage & { channel: ChannelName.ORGANIZATION_CHANGE })['data']) {
+  return useChannel(ChannelName.ORGANIZATION_CHANGE, callback, []);
+}
+```
+
+---
+
+## Task 5: Create Channel Provider and Integration
+
+**Files:**
+- Create: `host/src/kernel/channels/ChannelProvider.tsx`
+- Create: `host/src/kernel/channels/index.ts`
+
+### Step 1: Create channel provider component
+
+**File:** `host/src/kernel/channels/ChannelProvider.tsx`
+
+```typescript
+import { useEffect } from 'react';
+import { ToastIntegration } from './integrations/ToastIntegration';
+import { useGlobalKernelState } from '../shared-state';
+import { useAuth } from '../auth/hooks';
+import { usePublish } from './hooks';
+import { ChannelName } from './types';
+
+/**
+ * ChannelProvider - Sets up all channel integrations
+ *
+ * This component:
+ * 1. Renders the ToastIntegration component
+ * 2. Publishes auth changes when authentication state changes
+ * 3. Publishes organization changes when organization changes
+ */
+export function ChannelProvider() {
+  const { user, isAuthenticated } = useAuth();
+  const { organization } = useGlobalKernelState();
+  const publish = usePublish();
+
+  // Publish auth changes
+  useEffect(() => {
+    publish({
+      channel: ChannelName.AUTH_CHANGE,
+      data: {
+        isAuthenticated,
+        userId: user?.id,
+        organizationId: organization?.id,
+        id: `auth_${Date.now()}`,
+        timestamp: Date.now(),
+        source: 'host',
+      },
+    });
+  }, [isAuthenticated, user?.id, organization?.id, publish]);
+
+  // Publish organization changes
+  useEffect(() => {
+    if (organization) {
+      publish({
+        channel: ChannelName.ORGANIZATION_CHANGE,
+        data: {
+          organizationId: organization.id,
+          organizationName: organization.name,
+          id: `org_${Date.now()}`,
+          timestamp: Date.now(),
+          source: 'host',
+        },
+      });
+    }
+  }, [organization, publish]);
+
+  return (
+    <>
+      <ToastIntegration />
+    </>
+  );
+}
+```
+
+### Step 2: Create channels barrel export
+
+**File:** `host/src/kernel/channels/index.ts`
+
+```typescript
+export * from './types';
+export * from './events';
+export * from './ChannelBus';
+export * from './hooks';
+export * from './ChannelProvider';
+export * from './integrations/ToastIntegration';
+```
+
+---
+
+## Task 6: Update Bootstrap to Initialize Channel Bus
+
+**Files:**
+- Modify: `host/src/bootstrap.tsx`
+- Modify: `host/src/kernel/index.ts`
+
+### Step 1: Update bootstrap to initialize channels
+
+**File:** `host/src/bootstrap.tsx`
+
+```typescript
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import { BrowserRouter } from '@modern-js/runtime/router';
+import App from './App';
+import { registerSharedState } from './kernel/shared-state';
+import { PocketBaseProvider } from './kernel/providers';
+import { QueryProvider } from './kernel/providers';
+import { ThemeProvider } from './kernel/providers';
+import { Toaster } from './kernel/components/ui/toaster';
+import { ChannelProvider, initializeChannelBus } from './kernel/channels';
+import Garfish from 'garfish';
+
+// Register shared state bridge for plugins
+registerSharedState();
+
+// Initialize Garfish channel bus
+initializeChannelBus(Garfish);
+
+// Create root
+const container = document.getElementById('root');
+if (container) {
+  const root = createRoot(container);
+
+  root.render(
+    <StrictMode>
+      <BrowserRouter>
+        <ThemeProvider>
+          <QueryProvider>
+            <PocketBaseProvider>
+              <ChannelProvider />
+              <App />
+              <Toaster />
+            </PocketBaseProvider>
+          </QueryProvider>
+        </ThemeProvider>
+      </BrowserRouter>
+    </StrictMode>
+  );
+}
+```
+
+### Step 2: Update kernel exports
+
+**File:** `host/src/kernel/index.ts`
+
+```typescript
+export * from './shared-state';
+export * from './providers';
+export * from './lib/utils';
+export * from './components';
+export * from './channels';
+export * from './auth';
+export * from './rbac';
+```
+
+---
+
+## Task 7: Create Example Plugin Channel Usage
+
+**Files:**
+- Create: `packages/plugins/@lego/plugin-todo/src/channels.example.ts`
+
+### Step 1: Create example for plugin developers
+
+**File:** `packages/plugins/@lego/plugin-todo/src/channels.example.ts`
+
+```typescript
+/**
+ * Example: How plugins can use the channel system
+ *
+ * This file demonstrates how a plugin can:
+ * 1. Subscribe to host events (auth, organization changes)
+ * 2. Publish events to the host (toast notifications, navigation)
+ * 3. Communicate with other plugins
+ */
+
+import { useEffect } from 'react';
+import {
+  useToastChannel,
+  useAuthChannel,
+  useOrganizationChannel,
+  usePluginReady,
+  usePublishPluginError,
+} from '@lego/kernel/channels';
+
+// Example 1: Show toast notification from plugin
+export function useNotifySuccess() {
+  const publishToast = useToastChannel();
+
+  return (title: string, description?: string) => {
+    publishToast({
+      type: 'success',
+      title,
+      description,
+    });
+  };
+}
+
+// Example 2: Listen for auth changes
+export function useAuthListener() {
+  useAuthChannel((data) => {
+    console.log('[Plugin] Auth changed:', data);
+
+    if (data.isAuthenticated) {
+      console.log('[Plugin] User logged in:', data.userId);
+      // Refresh plugin data when user logs in
+    } else {
+      console.log('[Plugin] User logged out');
+      // Clear plugin data when user logs out
+    }
+  });
+}
+
+// Example 3: Listen for organization changes
+export function useOrganizationListener() {
+  useOrganizationChannel((data) => {
+    console.log('[Plugin] Organization changed:', data);
+    // Refresh plugin data for new organization
+  });
+}
+
+// Example 4: Notify host when plugin is ready
+export function usePluginReadyNotification() {
+  usePluginReady('@lego/plugin-todo', '1.0.0');
+}
+
+// Example 5: Report errors to host
+export function useErrorReporting() {
+  const publishError = usePublishPluginError();
+
+  return (error: Error) => {
+    publishError(
+      '@lego/plugin-todo',
+      error.message,
+      error.stack
+    );
+  };
+}
+
+// Example 6: Complete integration hook
+export function useChannelIntegration() {
+  const notifySuccess = useNotifySuccess();
+  const reportError = useErrorReporting();
+
+  // Notify when plugin initializes
+  usePluginReadyNotification();
+
+  // Listen to auth changes
+  useAuthListener();
+
+  // Listen to organization changes
+  useOrganizationListener();
+
+  return {
+    notifySuccess,
+    reportError,
+  };
+}
+```
+
+---
+
+## Task 8: Create Plugin Channel Hook Helper
+
+**Files:**
+- Create: `host/src/kernel/channels/plugin-hooks.ts`
+
+### Step 1: Create plugin-specific hooks
+
+**File:** `host/src/kernel/channels/plugin-hooks.ts`
+
+```typescript
+import { useCallback, useEffect } from 'react';
+import { useNavigate } from '@modern-js/runtime/router';
+import { channelBus } from './ChannelBus';
+import { ChannelName, type ToastEventData } from './types';
+
+/**
+ * Helper hook for plugins to access kernel channels
+ *
+ * This hook can be used from any plugin via the window bridge:
+ * window.__LEGO_KERNEL_STATE__?.usePluginChannels?.()
+ */
+export function usePluginChannels() {
+  const navigate = useNavigate();
+
+  // Show toast notification
+  const toast = useCallback((data: Omit<ToastEventData, 'id' | 'timestamp' | 'source'>) => {
+    channelBus.publish({
+      channel: ChannelName.TOAST,
+      data: {
+        ...data,
+        id: `toast_${Date.now()}`,
+        timestamp: Date.now(),
+        source: 'plugin',
+      },
+    });
+  }, []);
+
+  // Navigate to a path
+  const navigateTo = useCallback((path: string, replace = false) => {
+    // Use direct navigation instead of publishing to channel
+    // This avoids circular dependencies and works more reliably
+    navigate(path, { replace });
+  }, [navigate]);
+
+  // Subscribe to auth changes
+  const onAuthChange = useCallback((callback: (data: ToastEventData) => void) => {
+    return channelBus.subscribe(ChannelName.AUTH_CHANGE, callback);
+  }, []);
+
+  // Subscribe to organization changes
+  const onOrganizationChange = useCallback((callback: (data: any) => void) => {
+    return channelBus.subscribe(ChannelName.ORGANIZATION_CHANGE, callback);
+  }, []);
+
+  return {
+    toast,
+    navigateTo,
+    onAuthChange,
+    onOrganizationChange,
+  };
+}
+
+/**
+ * Register plugin channels helper to window bridge
+ */
+export function registerPluginChannels() {
+  if (typeof window !== 'undefined') {
+    (window as any).__LEGO_PLUGIN_CHANNELS__ = {
+      toast: (data: Omit<ToastEventData, 'id' | 'timestamp' | 'source'>) => {
+        channelBus.publish({
+          channel: ChannelName.TOAST,
+          data: {
+            ...data,
+            id: `toast_${Date.now()}`,
+            timestamp: Date.now(),
+            source: 'plugin',
+          },
+        });
+      },
+    };
+  }
+}
+```
+
+### Step 2: Update bridge to include channels
+
+**File:** `host/src/kernel/shared-state/bridge.ts`
+
+```typescript
+import { useGlobalKernelState } from './store';
+import { registerPluginChannels } from '../channels/plugin-hooks';
+
+// Declare window type for shared state
+declare global {
+  interface Window {
+    __LEGO_KERNEL_STATE__?: {
+      useGlobalKernelState: typeof useGlobalKernelState;
+    };
+    __LEGO_PLUGIN_CHANNELS__?: {
+      toast: (data: any) => void;
+    };
+  }
+}
+
+// Register shared state to window for plugin access
+export function registerSharedState() {
+  if (typeof window !== 'undefined') {
+    window.__LEGO_KERNEL_STATE__ = {
+      useGlobalKernelState,
+    };
+
+    // Also register plugin channels helper
+    registerPluginChannels();
+  }
+}
+
+// Hook for plugins to access kernel state
+export function useKernelState() {
+  return useGlobalKernelState;
+}
+```
+
+---
+
+## Verification
+
+### Step 1: Build the host
+
+**Run:**
+
+```bash
+cd host
+pnpm run build
+```
+
+Expected: Build completes without errors.
+
+### Step 2: Start development server
+
+**Run:**
+
+```bash
+cd host
+pnpm run dev
+```
+
+Expected: Server starts on http://localhost:8080
+
+### Step 3: Test channel system
+
+1. Open browser console on host app
+2. Access channel bus: `window.__LEGO_PLUGIN_CHANNELS__`
+3. Test toast from console:
+
+```javascript
+window.__LEGO_PLUGIN_CHANNELS__.toast({
+  type: 'success',
+  title: 'Test from console',
+  description: 'This toast was triggered from the browser console!'
+});
+```
+
+4. Should see a toast notification appear
+
+### Step 4: Test auth change events
+
+1. Login to the app
+2. Open browser console
+3. Subscribe to auth channel and verify events are published
+
+---
+
+## Summary
+
+After completing this document, you will have:
+
+1. ✅ Garfish channel bus singleton service
+2. ✅ Type-safe channel system with enum-defined channel names
+3. ✅ Toast integration demonstrating plugin→host communication
+4. ✅ Hooks for subscribing to and publishing channel events
+5. ✅ Channel provider that automatically publishes auth/org changes
+6. ✅ Plugin-friendly channel helpers via window bridge
+7. ✅ Example code showing how plugins use channels
+
+**Next:** `08-plugin-system.md` - Implement complete plugin architecture with slot injection, plugin config, and dynamic loading.
+
+---
+
+## Files Created
+
+```
+host/
+└── src/
+    └── kernel/
+        └── channels/
+            ├── types.ts
+            ├── events.ts
+            ├── ChannelBus.ts
+            ├── hooks.ts
+            ├── plugin-hooks.ts
+            ├── ChannelProvider.tsx
+            ├── integrations/
+            │   └── ToastIntegration.tsx
+            └── index.ts
+
+bootstrap.tsx (modified)
+kernel/shared-state/bridge.ts (modified)
+kernel/index.ts (modified)
+
+packages/plugins/@lego/plugin-todo/
+└── src/
+    └── channels.example.ts (example file)
+```