@hai3/react 0.3.0-alpha.0 → 0.4.0-alpha.0

package/CLAUDE.md

@@ -1,6 +1,6 @@
 # @hai3/react
 
-React bindings and hooks for HAI3 applications. Provides the React integration layer.
+React bindings and hooks for HAI3 applications. Provides the React integration layer with MFE (Microfrontend) support.
 
 ## React Layer
 
@@ -46,7 +46,13 @@ import { useHAI3 } from '@hai3/react';
 
 function MyComponent() {
   const app = useHAI3();
-  const screensets = app.screensetRegistry.getAll();
+
+  // Access MFE-enabled registry
+  const extensions = app.screensetsRegistry.getRegisteredExtensions();
+
+  // Access MFE actions
+  await app.actions.loadExtension({ extensionId: 'home' });
+  await app.actions.mountExtension({ extensionId: 'home', domainId: 'screen', container });
 }
 ```
 
@@ -56,11 +62,10 @@ Type-safe Redux hooks:
 
 ```tsx
 import { useAppDispatch, useAppSelector } from '@hai3/react';
-import { selectActiveScreen } from '@hai3/react';
 
 function MyComponent() {
   const dispatch = useAppDispatch();
-  const activeScreen = useAppSelector(selectActiveScreen);
+  const activeScreen = useAppSelector((state) => state.layout.screen.activeScreen);
 }
 ```
 
@@ -105,83 +110,213 @@ function HomeScreen() {
 }
 ```
 
-#### useNavigation
+#### useTheme
 
-Navigate between screens:
+Access theme utilities:
 
 ```tsx
-import { useNavigation } from '@hai3/react';
+import { useTheme } from '@hai3/react';
 
-function MyComponent() {
-  const { navigateToScreen, navigateToScreenset, currentScreen } = useNavigation();
+function ThemeToggle() {
+  const { currentTheme, themes, setTheme } = useTheme();
 
   return (
-    <button onClick={() => navigateToScreen('demo', 'home')}>
-      Go to Home
-    </button>
+    <select value={currentTheme} onChange={(e) => setTheme(e.target.value)}>
+      {themes.map((theme) => (
+        <option key={theme.id} value={theme.id}>{theme.name}</option>
+      ))}
+    </select>
   );
 }
 ```
 
-#### useTheme
+### MFE Hooks
 
-Access theme utilities:
+#### useMfeBridge
+
+Access the MFE bridge for child MFEs:
 
 ```tsx
-import { useTheme } from '@hai3/react';
+import { useMfeBridge } from '@hai3/react';
+import { HAI3_ACTION_LOAD_EXT, HAI3_SHARED_PROPERTY_THEME } from '@hai3/react';
 
-function ThemeToggle() {
-  const { currentTheme, themes, setTheme } = useTheme();
+function MyExtension() {
+  const bridge = useMfeBridge();
+
+  // Execute actions chain on parent
+  await bridge.executeActionsChain({
+    action: { type: HAI3_ACTION_LOAD_EXT, target: 'screen', payload: { extensionId: 'other' } }
+  });
+
+  // Get shared property
+  const theme = bridge.getProperty(HAI3_SHARED_PROPERTY_THEME);
+}
+```
+
+#### useSharedProperty
+
+Subscribe to shared property changes:
+
+```tsx
+import { useSharedProperty, HAI3_SHARED_PROPERTY_THEME } from '@hai3/react';
+
+function ThemedComponent() {
+  const theme = useSharedProperty(HAI3_SHARED_PROPERTY_THEME);
+
+  return <div style={{ backgroundColor: theme?.primaryColor }}>...</div>;
+}
+```
+
+#### useHostAction
+
+Invoke actions on the host application:
+
+```tsx
+import { useHostAction, HAI3_ACTION_LOAD_EXT } from '@hai3/react';
+
+function MyExtension() {
+  const loadExtension = useHostAction(HAI3_ACTION_LOAD_EXT);
+
+  const handleClick = () => {
+    loadExtension({ extensionId: 'other' });
+  };
+
+  return <button onClick={handleClick}>Load Extension</button>;
+}
+```
+
+#### useDomainExtensions
+
+Subscribe to extensions in a domain:
+
+```tsx
+import { useDomainExtensions } from '@hai3/react';
+
+function ScreenList() {
+  const screenExtensions = useDomainExtensions('screen');
 
   return (
-    <select value={currentTheme} onChange={(e) => setTheme(e.target.value)}>
-      {themes.map((theme) => (
-        <option key={theme.id} value={theme.id}>{theme.name}</option>
+    <ul>
+      {screenExtensions.map((ext) => (
+        <li key={ext.id}>{ext.title}</li>
       ))}
-    </select>
+    </ul>
   );
 }
 ```
 
-### Components
+#### useRegisteredPackages
+
+Subscribe to registered GTS packages:
+
+```tsx
+import { useRegisteredPackages } from '@hai3/react';
+
+function PackageList() {
+  const packages = useRegisteredPackages();
+
+  return (
+    <ul>
+      {packages.map((pkg) => (
+        <li key={pkg}>{pkg}</li>
+      ))}
+    </ul>
+  );
+}
+```
 
-#### AppRouter
+#### useActivePackage
 
-Renders screens with lazy loading:
+Subscribe to the active GTS package (the package of the currently mounted screen extension):
 
 ```tsx
-import { AppRouter } from '@hai3/react';
+import { useActivePackage } from '@hai3/react';
 
-function App() {
+function ActivePackageIndicator() {
+  const activePackage = useActivePackage();
+
+  if (!activePackage) {
+    return <div>No active screen</div>;
+  }
+
+  return <div>Active: {activePackage}</div>;
+}
+```
+
+### MFE Components
+
+#### MfeProvider
+
+Provide MFE context for child extensions:
+
+```tsx
+import { MfeProvider } from '@hai3/react';
+
+function MfeHost() {
   return (
-    <HAI3Provider>
-      <Layout>
-        <AppRouter
-          fallback={<Loading />}
-          errorFallback={(error) => <Error error={error} />}
-        />
-      </Layout>
-    </HAI3Provider>
+    <MfeProvider bridge={parentBridge}>
+      <ExtensionContainer />
+    </MfeProvider>
   );
 }
 ```
 
+#### ExtensionDomainSlot
+
+Render extensions into a domain slot:
+
+```tsx
+import { ExtensionDomainSlot } from '@hai3/react';
+
+function LayoutScreen() {
+  return (
+    <div>
+      <ExtensionDomainSlot
+        domainId="screen"
+        containerRef={screenContainerRef}
+        fallback={<Loading />}
+      />
+    </div>
+  );
+}
+```
+
+#### RefContainerProvider
+
+Provide container references for MFE mounting:
+
+```tsx
+import { RefContainerProvider } from '@hai3/react';
+
+function Layout() {
+  return (
+    <RefContainerProvider>
+      <ScreenContainer />
+      <SidebarContainer />
+    </RefContainerProvider>
+  );
+}
+```
+
+### Components
+
 ## Key Rules
 
 1. **Wrap with HAI3Provider** - Required for all hooks to work
-2. **Use hooks for state access** - Don't import selectors directly from @hai3/layout
+2. **Use hooks for state access** - Don't import selectors directly from @hai3/framework
 3. **Lazy load translations** - Use `useScreenTranslations` for screen-level i18n
-4. **NO Layout components here** - Layout and UI components belong in L4 (user's project via CLI scaffolding)
+4. **Use MFE hooks for extensions** - `useMfeBridge`, `useSharedProperty`, `useHostAction`, `useDomainExtensions`
+5. **NO Layout components here** - Layout and UI components belong in L4 (user's project via CLI scaffolding)
 
 ## Re-exports
 
 For convenience, this package re-exports everything from @hai3/framework:
 
 - All SDK primitives (eventBus, createStore, etc.)
-- All plugins (screensets, themes, layout, etc.)
+- All plugins (screensets, themes, layout, microfrontends, etc.)
 - All registries and factory functions
-- All selectors from @hai3/layout
-- All types
+- All types (including MFE types)
+- All MFE actions, selectors, and domain constants
 
 This allows users to import everything from `@hai3/react` without needing `@hai3/framework` directly.
 
@@ -189,7 +324,9 @@ This allows users to import everything from `@hai3/react` without needing `@hai3
 
 ### Components
 - `HAI3Provider` - Main context provider
-- `AppRouter` - Screen router
+- `MfeProvider` - MFE context provider
+- `ExtensionDomainSlot` - Domain slot renderer
+- `RefContainerProvider` - Container reference provider
 
 ### Hooks
 - `useHAI3` - Access app instance
@@ -197,13 +334,88 @@ This allows users to import everything from `@hai3/react` without needing `@hai3
 - `useAppSelector` - Typed selector
 - `useTranslation` - Translation utilities
 - `useScreenTranslations` - Screen translation loading
-- `useNavigation` - Navigation utilities
 - `useTheme` - Theme utilities
+- `useMfeBridge` - Access MFE bridge
+- `useSharedProperty` - Subscribe to shared property
+- `useHostAction` - Invoke host action
+- `useDomainExtensions` - Subscribe to domain extensions
+- `useRegisteredPackages` - Subscribe to registered GTS packages
+- `useActivePackage` - Subscribe to active GTS package
 
 ### Context
 - `HAI3Context` - React context (for advanced use)
+- `MfeContext` - MFE context (for advanced use)
 
 ### Types
-- `HAI3ProviderProps`, `AppRouterProps`
-- `UseTranslationReturn`, `UseNavigationReturn`, `UseThemeReturn`
+- `HAI3ProviderProps`
+- `MfeProviderProps`, `ExtensionDomainSlotProps`
+- `UseTranslationReturn`, `UseThemeReturn`
 - All types from @hai3/framework
+
+## Migration from Legacy API
+
+The `useNavigation` hook has been removed. Use MFE hooks and actions instead:
+
+### Removed Hook
+- `useNavigation()` (replaced by MFE actions and hooks)
+
+### Migration Examples
+
+**OLD**: Navigate using hook
+```tsx
+import { useNavigation } from '@hai3/react';
+
+function MyComponent() {
+  const { navigateToScreen } = useNavigation();
+
+  return (
+    <button onClick={() => navigateToScreen('demo', 'home')}>
+      Go Home
+    </button>
+  );
+}
+```
+
+**NEW**: Mount extension using app actions
+```tsx
+import { useHAI3 } from '@hai3/react';
+
+function MyComponent() {
+  const app = useHAI3();
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  const handleNavigate = async () => {
+    if (containerRef.current) {
+      await app.actions.mountExtension({
+        extensionId: 'home',
+        domainId: 'screen',
+        container: containerRef.current,
+      });
+    }
+  };
+
+  return (
+    <>
+      <button onClick={handleNavigate}>Go Home</button>
+      <div ref={containerRef} />
+    </>
+  );
+}
+```
+
+**NEW (Alternative)**: Use ExtensionDomainSlot
+```tsx
+import { ExtensionDomainSlot } from '@hai3/react';
+
+function MyComponent() {
+  return (
+    <ExtensionDomainSlot
+      domainId="screen"
+      containerRef={screenContainerRef}
+      fallback={<Loading />}
+    />
+  );
+}
+```
+
+See the MFE migration guide in the project documentation for detailed migration steps.

package/commands/hai3-new-mfe.md

@@ -0,0 +1,167 @@
+<!-- @standalone -->
+# hai3:new-mfe - Create New Microfrontend Package
+
+## PREREQUISITES (CRITICAL - STOP IF FAILED)
+
+1. MFE must be associated with a screenset
+2. Screenset must exist (run `hai3-new-screenset` first if needed)
+3. Vite and Module Federation must be configured
+
+## QUICK START
+
+For a screenset named `{screensetName}` with a new MFE:
+
+```bash
+# 1. Create the MFE package in src/mfe_packages/{screensetName}-mfe/
+cp -r packages/cli/template-sources/mfe-package/ src/mfe_packages/{screensetName}-mfe/
+
+# 2. Update variables in package.json and vite.config.ts:
+#    - Replace {{mfeName}} with your screenset name (camelCase)
+#    - Replace {{port}} with available port (3001, 3010, 3020, etc)
+#    - IMPORTANT: set preview script to "vite preview --port {{port}}"
+
+# 3. Install dependencies
+cd src/mfe_packages/{screensetName}-mfe
+npm install
+
+# 4. Create src/lifecycle.tsx that extends ThemeAwareReactLifecycle
+
+# 5. Regenerate MFE manifests so bootstrap.ts picks up the new package
+npm run generate:mfe-manifests
+```
+
+## CONFIGURATION REQUIREMENTS
+
+✅ **Correct preview script** (required for port auto-discovery):
+```json
+"preview": "vite preview --port {{port}}"
+```
+
+✅ **Correct dev script** (for hot reload):
+```json
+"dev": "vite --port {{port}}"
+```
+
+❌ **WRONG** (don't use this for dev):
+```json
+"dev": "vite build && vite preview --port {{port}}"
+```
+
+## PORT ALLOCATION
+
+Reserve ports for MFE packages:
+- **3001**: demo-mfe
+- **3010+**: (next available: 3010, 3020, 3030, ...)
+- **5173**: Main app
+
+## LIFECYCLE TEMPLATE
+
+Create `src/lifecycle.tsx`:
+
+```typescript
+import React from 'react';
+import type { ChildMfeBridge } from '@hai3/react';
+import { ThemeAwareReactLifecycle } from '@hai3/screensets/mfe/handler';
+import { YourScreen } from './screens/YourScreen';
+
+class Lifecycle extends ThemeAwareReactLifecycle {
+  constructor() {
+    super({
+      name: '{screensetName}',
+      version: '1.0.0',
+    });
+  }
+
+  async mount(shadowRoot: ShadowRoot, bridge: ChildMfeBridge) {
+    const div = document.createElement('div');
+    shadowRoot.appendChild(div);
+
+    // Initialize Tailwind/UIKit styles
+    const style = document.createElement('style');
+    style.textContent = tailwindStyles; // Import from @hai3/uikit
+    shadowRoot.appendChild(style);
+
+    // Render component
+    const root = ReactDOM.createRoot(div);
+    root.render(<YourScreen bridge={bridge} />);
+
+    return { root, div };
+  }
+}
+
+export default new Lifecycle();
+```
+
+## dev:all INTEGRATION (AUTOMATIC)
+
+After creating the MFE and running `npm run generate:mfe-manifests`, the `dev:all`
+script auto-discovers your new package — no manual configuration needed.
+
+`dev-all.ts` scans `src/mfe_packages/*/package.json` and reads the port from the
+`preview` (or `dev`) script using `--port NNNN`. The new MFE will automatically
+appear in the next `npm run dev:all` run.
+
+## VALIDATION
+
+After creation:
+
+```bash
+# Regenerate manifests (required after adding new MFE)
+npm run generate:mfe-manifests
+
+# Validate TypeScript
+npm run type-check
+
+# Check architecture compliance
+npm run arch:check
+
+# Run the dev server (picks up new MFE automatically)
+npm run dev:all
+
+# Verify MFE loads at http://localhost:5173
+# Open Studio Overlay (Ctrl+`) and check screenset
+```
+
+## TROUBLESHOOTING
+
+### Issue: MFE not appearing in screenset selector
+- Run `npm run generate:mfe-manifests` to regenerate manifests
+- Check mfe.json manifest is properly exported
+- Verify extensions are registered in manifest
+- Check browser console for errors
+
+### Issue: dev:all not picking up MFE port
+- Verify `preview` script has `--port NNNN` (e.g., `"vite preview --port 3010"`)
+- Check port is not in use (`lsof -i :3010`)
+- Restart dev server
+
+### Issue: Hot reload not working
+- Verify dev script uses `vite --port` (not `vite build && vite preview`)
+- Check port is not in use
+- Restart dev server
+
+### Issue: Redux/useSelector errors
+- MFE must use mock data (no Redux Provider in isolation)
+- Use `useState` for local state management
+- Do not import Redux hooks (@hai3/react)
+
+## BEST PRACTICES
+
+✅ **DO:**
+- Set `preview` script with `--port NNNN` for port auto-discovery
+- Use mock data with useState for UI-only MFEs
+- Keep MFE logic isolated and simple
+- Use @hai3/uikit components
+- Run `npm run generate:mfe-manifests` after creating the MFE
+
+❌ **DON'T:**
+- Import Redux hooks directly
+- Use vite build && vite preview in dev mode
+- Create complex state management in MFE
+- Hardcode ports without updating package.json preview script
+
+---
+
+See also:
+- `/packages/cli/template-sources/mfe-package/` for templates
+- `hai3-new-screenset.md` for screenset creation