@hai3/react 0.2.0-alpha.0

package/CLAUDE.md

@@ -0,0 +1,227 @@
+# @hai3/react
+
+React bindings and hooks for HAI3 applications. Provides the React integration layer.
+
+## React Layer
+
+This package is part of the **React Layer (L3)** - it depends only on @hai3/framework (not directly on SDK packages) and provides React-specific components and hooks.
+
+## Core Concepts
+
+### HAI3Provider
+
+Wrap your app with HAI3Provider to enable all hooks:
+
+```tsx
+import { HAI3Provider } from '@hai3/react';
+
+function App() {
+  return (
+    <HAI3Provider>
+      <YourApp />
+    </HAI3Provider>
+  );
+}
+
+// With configuration
+<HAI3Provider config={{ devMode: true }}>
+  <YourApp />
+</HAI3Provider>
+
+// With pre-built app
+const app = createHAI3().use(screensets()).build();
+<HAI3Provider app={app}>
+  <YourApp />
+</HAI3Provider>
+```
+
+### Available Hooks
+
+#### useHAI3
+
+Access the HAI3 app instance:
+
+```tsx
+import { useHAI3 } from '@hai3/react';
+
+function MyComponent() {
+  const app = useHAI3();
+  const screensets = app.screensetRegistry.getAll();
+}
+```
+
+#### useAppDispatch / useAppSelector
+
+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);
+}
+```
+
+#### useTranslation
+
+Access translation utilities:
+
+```tsx
+import { useTranslation } from '@hai3/react';
+
+function MyComponent() {
+  const { t, language, setLanguage, isRTL } = useTranslation();
+
+  return (
+    <div dir={isRTL ? 'rtl' : 'ltr'}>
+      <h1>{t('common:title')}</h1>
+      <p>{t('common:welcome', { name: 'John' })}</p>
+    </div>
+  );
+}
+```
+
+#### useScreenTranslations
+
+Load screen-level translations:
+
+```tsx
+import { useScreenTranslations } from '@hai3/react';
+
+const translations = {
+  en: () => import('./i18n/en.json'),
+  es: () => import('./i18n/es.json'),
+};
+
+function HomeScreen() {
+  const { isLoaded, error } = useScreenTranslations('demo', 'home', translations);
+
+  if (!isLoaded) return <Loading />;
+  if (error) return <Error error={error} />;
+
+  return <div>...</div>;
+}
+```
+
+#### useNavigation
+
+Navigate between screens:
+
+```tsx
+import { useNavigation } from '@hai3/react';
+
+function MyComponent() {
+  const { navigateToScreen, navigateToScreenset, currentScreen } = useNavigation();
+
+  return (
+    <button onClick={() => navigateToScreen('demo', 'home')}>
+      Go to Home
+    </button>
+  );
+}
+```
+
+#### useTheme
+
+Access theme utilities:
+
+```tsx
+import { useTheme } from '@hai3/react';
+
+function ThemeToggle() {
+  const { currentTheme, themes, setTheme } = useTheme();
+
+  return (
+    <select value={currentTheme} onChange={(e) => setTheme(e.target.value)}>
+      {themes.map((theme) => (
+        <option key={theme.id} value={theme.id}>{theme.name}</option>
+      ))}
+    </select>
+  );
+}
+```
+
+### Components
+
+#### TextLoader
+
+Prevents flash of untranslated content:
+
+```tsx
+import { TextLoader } from '@hai3/react';
+
+function Screen() {
+  return (
+    <TextLoader fallback={<Loading />}>
+      <h1>{t('screen.demo.home:title')}</h1>
+    </TextLoader>
+  );
+}
+```
+
+#### AppRouter
+
+Renders screens with lazy loading:
+
+```tsx
+import { AppRouter } from '@hai3/react';
+
+function App() {
+  return (
+    <HAI3Provider>
+      <Layout>
+        <AppRouter
+          fallback={<Loading />}
+          errorFallback={(error) => <Error error={error} />}
+        />
+      </Layout>
+    </HAI3Provider>
+  );
+}
+```
+
+## 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
+3. **Lazy load translations** - Use `useScreenTranslations` for screen-level i18n
+4. **Use TextLoader** - Wrap translated content to prevent FOUC
+5. **NO Layout components here** - Layout is in @hai3/uikit or user code
+
+## 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 registries and factory functions
+- All selectors from @hai3/layout
+- All types
+
+This allows users to import everything from `@hai3/react` without needing `@hai3/framework` directly.
+
+## Exports
+
+### Components
+- `HAI3Provider` - Main context provider
+- `AppRouter` - Screen router
+- `TextLoader` - Translation loading wrapper
+
+### Hooks
+- `useHAI3` - Access app instance
+- `useAppDispatch` - Typed dispatch
+- `useAppSelector` - Typed selector
+- `useTranslation` - Translation utilities
+- `useScreenTranslations` - Screen translation loading
+- `useNavigation` - Navigation utilities
+- `useTheme` - Theme utilities
+
+### Context
+- `HAI3Context` - React context (for advanced use)
+
+### Types
+- `HAI3ProviderProps`, `AppRouterProps`, `TextLoaderProps`
+- `UseTranslationReturn`, `UseNavigationReturn`, `UseThemeReturn`
+- All types from @hai3/framework

package/commands/hai3-duplicate-screenset.md

@@ -0,0 +1,58 @@
+<!-- @standalone -->
+# hai3:duplicate-screenset - Duplicate Screenset
+
+## AI WORKFLOW (REQUIRED)
+1) Read .ai/targets/SCREENSETS.md before starting.
+2) Gather requirements from user.
+3) Follow steps below.
+
+REQUIRED: Copy folder and update ids.ts only (2 steps, 96% reduction).
+REQUIRED: Pass arch:check with zero errors.
+REQUIRED: Test via Chrome DevTools MCP (never skip).
+
+## GATHER REQUIREMENTS
+Ask user for:
+- SOURCE screenset name (existing screenset to copy).
+- TARGET screenset name (camelCase, single word preferred).
+- TARGET category: Drafts | Mockups | Production.
+
+## STEP 1: Copy Screenset via CLI
+```bash
+hai3 screenset copy SOURCE TARGET --category={category}
+```
+The CLI automatically:
+- Copies all files (screens, slices, actions, events, effects, API, icons, i18n).
+- Updates ids.ts with TARGET_SCREENSET_ID and all SCREEN_IDs.
+- Everything auto-updates via template literals:
+  - Event enums: ${TARGET_SCREENSET_ID}/${DOMAIN_ID}/eventName.
+  - Icon IDs: ${TARGET_SCREENSET_ID}:iconName.
+  - API domain: ${TARGET_SCREENSET_ID}:serviceName.
+  - Redux state key.
+- Screenset auto-discovered (no manual registration).
+
+## STEP 2: Validate
+```bash
+npm run type-check
+npm run arch:check
+npm run lint
+grep -rn "OLD_SCREENSET_ID" src/screensets/TARGET/  # Must return 0 matches
+```
+
+## STEP 3: Test via Chrome DevTools MCP
+STOP: If MCP connection is broken, fix it first. NEVER skip testing.
+- npm run dev.
+- Verify TARGET in screenset selector.
+- Click TARGET screenset in dev panel.
+- Verify URL changes to target screenset.
+- Check 0 console errors.
+- Test all primary features.
+- Verify auto-discovery worked (screenset appears without manual registration).
+
+## CHECKLIST
+- [ ] Gather requirements (source, target name, category).
+- [ ] Run `hai3 screenset copy SOURCE TARGET --category={category}`.
+- [ ] Run type-check (MUST pass).
+- [ ] Run arch:check (MUST pass).
+- [ ] Run lint (MUST pass).
+- [ ] Verify zero occurrences of old screenset ID.
+- [ ] Test via Chrome DevTools MCP (NEVER skip).

package/commands/hai3-new-component.md

@@ -0,0 +1,76 @@
+<!-- @standalone -->
+# hai3:new-component - Add New UI Component
+
+## AI WORKFLOW (REQUIRED)
+1) Check if @hai3/uikit has equivalent component first.
+2) Gather requirements from user.
+3) Determine type: screenset composite (default) | screenset base (rare).
+4) Create OpenSpec proposal for approval.
+5) After approval, apply implementation.
+
+## CHECK GLOBAL UIKIT FIRST
+- REQUIRED: Before creating screenset component, verify @hai3/uikit lacks equivalent.
+- REQUIRED: Import from @hai3/uikit if component exists there.
+
+## GATHER REQUIREMENTS
+Ask user for:
+- Component name (e.g., "DataTable", "ColorPicker").
+- Component type: screenset composite (default) | screenset base (rare).
+- Component description and props.
+- If screenset base: justification why composite is insufficient.
+
+## IF SCREENSET COMPONENT
+
+### STEP 0: Determine Subfolder
+- uikit/composite/: Screenset-specific composites (theme tokens only).
+- uikit/base/: Rare primitives needing inline styles (needs strong justification).
+
+### STEP 1: Create OpenSpec Proposal
+Create openspec/changes/add-{screenset}-{component}/ with:
+
+#### proposal.md
+- Summary: Add new screenset-specific component to {screenset}.
+- Details: Screenset, component name, placement (base/composite), description, props.
+- Justification (if base/): Why global uikit insufficient, why composite insufficient.
+- Implementation: HAI3 patterns (no Redux, no business logic).
+
+#### tasks.md
+- Create component file in uikit/{base|composite}/.
+- Implement props interface.
+- Add theme token styling (or inline for base/).
+- Export from local index if needed.
+- Validate: npm run arch:check.
+- Test in UI.
+
+### STEP 2: Wait for Approval
+Tell user: "Review proposal at openspec/changes/add-{screenset}-{component}/."
+Tell user: "Run /openspec:apply add-{screenset}-{component} to implement."
+
+### STEP 3: Apply Implementation (after approval)
+When user runs /openspec:apply:
+
+#### 3.1 Create Component
+File: src/screensets/{screenset}/uikit/{base|composite}/{ComponentName}.tsx
+- composite/: Use theme tokens only (no inline styles).
+- base/: May use inline styles (rare, needs justification).
+- Must be reusable within the screenset.
+- NO @hai3/uicore imports (except types).
+- NO Redux or state management.
+- Accept value/onChange pattern for state.
+
+#### 3.2 Export
+Export from local index if needed.
+
+#### 3.3 Validation
+Run: npm run arch:check && npm run dev
+Test component in UI.
+
+#### 3.4 Mark Tasks Complete
+Update tasks.md to mark all completed tasks.
+
+## RULES
+- REQUIRED: Check @hai3/uikit first; screenset uikit only if missing.
+- REQUIRED: Screenset base components need strong justification.
+- FORBIDDEN: Redux, business logic, side effects in components.
+- FORBIDDEN: Inline styles outside uikit/base/.
+- REQUIRED: Accept value/onChange pattern for state.

package/commands/hai3-new-screen.md

@@ -0,0 +1,81 @@
+<!-- @standalone -->
+# hai3:new-screen - Add New Screen
+
+## PREREQUISITES (CRITICAL - STOP IF FAILED)
+FORBIDDEN: Proceeding without proposal.
+FORBIDDEN: Creating screen manually without OpenSpec workflow.
+
+## AI WORKFLOW (REQUIRED)
+1) Read .ai/targets/SCREENSETS.md and .ai/targets/EVENTS.md before starting.
+2) Gather requirements from user (including UI sections).
+3) Create OpenSpec proposal via `.claude/commands/openspec-proposal.md` (REQUIRED).
+4) After approval, implement via `.claude/commands/openspec-apply.md` (REQUIRED).
+
+## GATHER REQUIREMENTS
+Ask user for:
+- Screenset path (e.g., src/screensets/chat).
+- Screen name (camelCase).
+- UI sections (e.g., "header, form, data table").
+- Add to menu? (Y/N)
+
+## STEP 1: Create OpenSpec Proposal (REQUIRED)
+Execute openspec:proposal command (see `.claude/commands/openspec-proposal.md`).
+Proposal name: `add-{screenset}-{screen}`
+
+### proposal.md content
+```
+# Proposal: Add {ScreenName} Screen
+
+## Summary
+Add new screen "{screenName}" to {screenset} screenset.
+
+## Details
+- Screenset: {screenset}
+- Screen name: {screenName}
+- Add to menu: {Y/N}
+
+## Component Plan
+- REQUIRED: Use @hai3/uikit components first; local uikit only if missing.
+- uikit/base/: rare primitives (inline styles allowed, needs justification)
+- uikit/composite/: screenset composites (theme tokens only)
+- screens/{screen}/components/: screen-specific components
+
+## Data Flow
+- Uses existing screenset events/slices per EVENTS.md
+- Screen dispatches actions, never direct slice updates
+```
+
+### tasks.md minimum required tasks
+NOTE: Proposal may include additional tasks, but MUST include these:
+```
+- [ ] Add screen ID to ids.ts
+- [ ] Create components per Component Plan (BEFORE screen file)
+- [ ] Create screen (orchestrates components, follows EVENTS.md data flow)
+- [ ] Add i18n files for all languages
+- [ ] Add to menu (if requested)
+- [ ] Validate: `npm run type-check && npm run lint`
+- [ ] Test via Chrome DevTools MCP
+```
+
+## STEP 2: Wait for Approval
+Tell user: "Review proposal at `openspec/changes/add-{screenset}-{screen}/`."
+Tell user: "Execute openspec:apply command to implement."
+
+## STEP 3: Implementation (via openspec:apply)
+BEFORE executing openspec:apply, verify tasks.md contains all minimum required tasks above.
+Execute openspec:apply command (see `.claude/commands/openspec-apply.md`).
+Follow tasks.md strictly:
+1) Add screen ID to ids.ts.
+2) Create components BEFORE screen file per Component Plan.
+3) Create screen following data flow rules from .ai/targets/EVENTS.md:
+   - Use actions to trigger state changes
+   - FORBIDDEN: Direct slice dispatch from screen
+4) Add i18n with useScreenTranslations(). Export default.
+5) Add to menu if requested.
+6) Validate: `npm run type-check && npm run lint`.
+7) Test via Chrome DevTools MCP (REQUIRED):
+   - Navigate to new screen
+   - Verify screen renders without console errors
+   - Test UI interactions and data flow
+   - Verify translations load correctly
+   - STOP if MCP connection fails

package/commands/hai3-new-screenset.md

@@ -0,0 +1,85 @@
+<!-- @standalone -->
+# hai3:new-screenset - Create New Screenset
+
+## PREREQUISITES (CRITICAL - STOP IF FAILED)
+Run `hai3 --version`.
+STOP: If fails, tell user to install.
+FORBIDDEN: Proceeding without CLI tools.
+FORBIDDEN: Creating screenset manually or by copying peers.
+
+## AI WORKFLOW (REQUIRED)
+1) Check prerequisites above.
+2) Read .ai/targets/SCREENSETS.md and .ai/targets/EVENTS.md before starting.
+3) Gather requirements from user (including UI sections).
+4) Create OpenSpec proposal via `.claude/commands/openspec-proposal.md` (REQUIRED).
+5) After approval, implement via `.claude/commands/openspec-apply.md` (REQUIRED).
+
+## GATHER REQUIREMENTS
+Ask user for:
+- Screenset name (camelCase).
+- Category: Drafts | Mockups | Production.
+- Initial screens.
+- UI sections per screen (e.g., "stats cards, charts, activity feed").
+
+## STEP 1: Create OpenSpec Proposal (REQUIRED)
+Execute openspec:proposal command (see `.claude/commands/openspec-proposal.md`).
+Proposal name: `add-{screenset-name}`
+
+### proposal.md content
+```
+# Proposal: Add {ScreensetName} Screenset
+
+## Summary
+Add new {category} screenset "{screensetName}" with {screens} screen(s).
+
+## Details
+- Name: {screensetName}
+- Category: {category}
+- Initial screens: {screens}
+
+## Component Plan
+- REQUIRED: Use @hai3/uikit components first; local uikit only if missing.
+- uikit/base/: rare primitives (inline styles allowed, needs justification)
+- uikit/composite/: screenset composites (theme tokens only)
+- components/: multi-screen components
+- screens/{screen}/components/: screen-specific components
+
+## Data Flow
+- Events: {domain events per EVENTS.md}
+- State: slices/, events/, effects/, actions/
+- API: api/{Name}ApiService.ts with mocks
+```
+
+### tasks.md minimum required tasks
+NOTE: Proposal may include additional tasks, but MUST include these:
+```
+- [ ] Create screenset: `hai3 screenset create {name} --category={category}`
+- [ ] Create components per Component Plan (BEFORE screen file)
+- [ ] Implement data flow per EVENTS.md (actions emit events, effects update slices)
+- [ ] Add API service with mocks
+- [ ] Validate: `npm run type-check && npm run arch:check && npm run lint`
+- [ ] Test via Chrome DevTools MCP
+```
+
+## STEP 2: Wait for Approval
+Tell user: "Review proposal at `openspec/changes/add-{screenset-name}/`."
+Tell user: "Execute openspec:apply command to implement."
+
+## STEP 3: Implementation (via openspec:apply)
+BEFORE executing openspec:apply, verify tasks.md contains all minimum required tasks above.
+Execute openspec:apply command (see `.claude/commands/openspec-apply.md`).
+Follow tasks.md strictly:
+1) Create screenset via `hai3 screenset create` (REQUIRED).
+2) Create components BEFORE screen file per Component Plan.
+3) Implement data flow per .ai/targets/EVENTS.md:
+   - Actions emit events via eventBus.emit()
+   - Effects subscribe and update slices
+   - FORBIDDEN: Direct slice dispatch from components
+4) Add API service with mocks.
+5) Validate: `npm run type-check && npm run arch:check && npm run lint`.
+6) Test via Chrome DevTools MCP (REQUIRED):
+   - Navigate to new screenset
+   - Verify screen renders without console errors
+   - Test user interactions trigger correct events
+   - Verify state updates via Redux DevTools
+   - STOP if MCP connection fails