@hai3/framework 0.2.0-alpha.0

package/CLAUDE.md

@@ -0,0 +1,161 @@
+# @hai3/framework
+
+Plugin-based application framework for HAI3 applications. Orchestrates SDK packages into cohesive applications.
+
+## Framework Layer
+
+This package is part of the **Framework Layer (L2)** - it depends on SDK packages (@hai3/state, @hai3/screensets, @hai3/api, @hai3/i18n). It provides the plugin architecture and **owns the layout slices** (header, footer, menu, sidebar, screen, popup, overlay).
+
+> **NOTE:** @hai3/uicore is deprecated. Layout slices are defined in @hai3/framework.
+
+## Core Concepts
+
+### Plugin Architecture
+
+Build applications by composing plugins:
+
+```typescript
+import { createHAI3, screensets, themes, layout, navigation, i18n } from '@hai3/framework';
+
+const app = createHAI3()
+  .use(screensets())
+  .use(themes())
+  .use(layout())
+  .use(navigation())
+  .use(i18n())
+  .build();
+```
+
+### Presets
+
+Pre-configured plugin combinations:
+
+```typescript
+import { createHAI3App, presets } from '@hai3/framework';
+
+// Full preset (default) - all plugins
+const fullApp = createHAI3App();
+
+// Or explicitly use presets
+const minimalApp = createHAI3()
+  .use(presets.minimal())  // screensets + themes only
+  .build();
+
+const headlessApp = createHAI3()
+  .use(presets.headless()) // screensets only
+  .build();
+```
+
+### Available Plugins
+
+| Plugin | Provides | Dependencies |
+|--------|----------|--------------|
+| `screensets()` | screensetRegistry, screenSlice | - |
+| `themes()` | themeRegistry, changeTheme action | - |
+| `layout()` | header, footer, menu, sidebar, popup, overlay slices | screensets |
+| `navigation()` | navigateToScreen, navigateToScreenset actions | screensets, routing |
+| `routing()` | routeRegistry, URL sync | screensets |
+| `i18n()` | i18nRegistry, setLanguage action | - |
+| `effects()` | Core effect coordination | - |
+
+### Built Application
+
+After calling `.build()`, access registries and actions:
+
+```typescript
+const app = createHAI3App();
+
+// Access registries
+app.screensetRegistry.getAll();
+app.themeRegistry.getCurrent();
+app.routeRegistry.hasScreen('demo', 'home');
+app.i18nRegistry.t('common:title');
+
+// Access store
+const state = app.store.getState();
+app.store.dispatch(someAction);
+
+// Access actions
+app.actions.navigateToScreen({ screensetId: 'demo', screenId: 'home' });
+app.actions.changeTheme({ themeId: 'dark' });
+app.actions.setLanguage({ language: 'es' });
+
+// Cleanup
+app.destroy();
+```
+
+## Creating Custom Plugins
+
+Extend HAI3 with custom functionality:
+
+```typescript
+import type { HAI3Plugin } from '@hai3/framework';
+
+export function myPlugin(): HAI3Plugin {
+  return {
+    name: 'my-plugin',
+    dependencies: ['screensets'], // Optional dependencies
+    provides: {
+      registries: { myRegistry: createMyRegistry() },
+      slices: [mySlice],
+      effects: [initMyEffects],
+      actions: { myAction: myActionHandler },
+    },
+    onInit(app) {
+      // Initialize after app is built
+    },
+    onDestroy(app) {
+      // Cleanup when app is destroyed
+    },
+  };
+}
+```
+
+## Key Rules
+
+1. **Use presets for common cases** - `createHAI3App()` for full apps
+2. **Compose plugins for customization** - Use `createHAI3().use()` pattern
+3. **Dependencies are auto-resolved** - Plugin order doesn't matter
+4. **Access via app instance** - All registries and actions on `app.*`
+5. **NO React in this package** - Framework is headless, use @hai3/react for React bindings
+
+## Re-exports
+
+For convenience, this package re-exports from SDK packages:
+
+- From @hai3/state: `eventBus`, `createStore`, `getStore`, `registerSlice`, `hasSlice`, `createSlice`
+- From @hai3/screensets: `LayoutDomain`, `ScreensetCategory`, `screensetRegistry`, contracts/types
+- From @hai3/api: `apiRegistry`, `BaseApiService`, `RestProtocol`, `MockPlugin`
+- From @hai3/i18n: `i18nRegistry`, `Language`, `SUPPORTED_LANGUAGES`, `getLanguageMetadata`
+
+**Layout Slices (owned by @hai3/framework):**
+- `layoutReducer`, `layoutDomainReducers`, `LAYOUT_SLICE_NAME`
+- Domain slices: `headerSlice`, `footerSlice`, `menuSlice`, `sidebarSlice`, `screenSlice`, `popupSlice`, `overlaySlice`
+- Domain actions: `headerActions`, `footerActions`, `menuActions`, `sidebarActions`, `screenActions`, `popupActions`, `overlayActions`
+- Individual reducer functions: `setMenuCollapsed`, `toggleSidebar`, `setActiveScreen`, etc.
+
+**NOTE:** `createAction` is NOT exported to consumers. Actions should be handwritten functions in screensets that contain business logic and emit events via `eventBus.emit()`.
+
+**NOTE:** "Selector" is Redux terminology and is not used in HAI3. Access state via `useAppSelector` hook from @hai3/react:
+```typescript
+const menu = useAppSelector((state: RootStateWithLayout) => state.layout.menu);
+```
+
+## Exports
+
+### Core
+- `createHAI3` - App builder factory
+- `createHAI3App` - Convenience function (full preset)
+- `presets` - Available presets (full, minimal, headless)
+
+### Plugins
+- `screensets`, `themes`, `layout`, `navigation`, `routing`, `i18n`, `effects`
+
+### Registries
+- `createScreensetRegistry`, `createThemeRegistry`, `createRouteRegistry`
+
+### Types
+- `HAI3Config`, `HAI3Plugin`, `HAI3App`, `HAI3AppBuilder`
+- `PluginFactory`, `PluginProvides`, `PluginLifecycle`
+- `Preset`, `Presets`, `ScreensetsConfig`
+- All re-exported types from SDK packages

package/commands/hai3-fix-violation.md

@@ -0,0 +1,48 @@
+<!-- @standalone -->
+# hai3:fix-violation - Fix Rule Violation
+
+## AI WORKFLOW (REQUIRED)
+1) Identify: Location (file:line), rule violated, category.
+2) Route: Use .ai/GUIDELINES.md to find target file.
+3) Summarize: Extract 3-7 applicable rules from target.
+4) Fix: Apply correction.
+5) Verify: Run checks.
+6) Report: What violated, rule applied, changes made, results.
+
+## STEP 1: Identify Violation
+- Find violating code location (file:line).
+- Classify category: typing | data flow | styling | registry | imports.
+
+## STEP 2: Route to Target File
+- Data flow/events -> .ai/targets/EVENTS.md
+- API services -> .ai/targets/SCREENSETS.md
+- src/screensets -> .ai/targets/SCREENSETS.md
+- src/themes -> .ai/targets/THEMES.md
+- Styling -> .ai/targets/STYLING.md
+
+## STEP 3: Read and Summarize Rules
+- REQUIRED: Read target file before making any change.
+- Summarize 3-7 applicable rules internally.
+
+## STEP 4: Apply Fix
+Change code to comply with target file rules.
+
+## STEP 5: Verify
+Run: npm run arch:check && npm run lint && npm run type-check
+REQUIRED: All checks must pass.
+
+## STEP 6: Report
+- What violated the rule.
+- Which rule was applied.
+- Changes made.
+- Verification results.
+
+## COMMON FIXES
+- Direct dispatch: BAD dispatch(setMenuItems(items)) -> GOOD navigateToScreen(screenId)
+- Hardcoded colors: BAD style with inline color -> GOOD className="text-primary"
+- Import violations: BAD import from '@hai3/uikit/src/Foo' -> GOOD import from '@hai3/uikit'
+- String literals: BAD screenId: 'dashboard' -> GOOD export const DASHBOARD_SCREEN_ID = 'dashboard'
+- Inline component: Extract to screens/screen/components/ or uikit/ per SCREENSETS.md
+- Inline style: BAD style with inline padding -> GOOD className="p-2" (except in uikit/base/)
+- Inline data: Move to api/domain/mocks.ts, fetch via event-driven flow
+- UIKit impurity: Move component from uikit/ to components/ if needs @hai3/uicore

package/commands/hai3-new-action.md

@@ -0,0 +1,120 @@
+<!-- @standalone -->
+# hai3:new-action - Create New Action
+
+## AI WORKFLOW (REQUIRED)
+1) Read .ai/targets/EVENTS.md before starting.
+2) Summarize 3-6 key rules.
+3) Gather requirements from user.
+4) Create OpenSpec proposal for approval.
+5) After approval, apply implementation.
+
+## GATHER REQUIREMENTS
+Ask user for:
+- Action purpose (e.g., "navigate to screen", "load user data").
+- Which screenset and domain (e.g., "chat/threads", "demo/navigation").
+- Event payload data.
+
+## STEP 1: Create OpenSpec Proposal
+Create `openspec/changes/add-{screenset}-{action}/` with:
+
+### proposal.md
+```markdown
+# Proposal: Add {ActionName} Action
+
+## Summary
+Add new action "{actionName}" to {screenset}/{domain} domain.
+
+## Details
+- Screenset: {screenset}
+- Domain: {domain}
+- Action: {actionName}
+- Event: {eventName}
+- Payload: {payloadFields}
+
+## Implementation
+Follow HAI3 event-driven flux pattern: Action -> Event -> Effect -> Slice.
+```
+
+### tasks.md
+```markdown
+# Tasks: Add {ActionName} Action
+
+- [ ] Define event in events/{domain}Events.ts
+- [ ] Create action in actions/{domain}Actions.ts
+- [ ] Create effect in effects/{domain}Effects.ts
+- [ ] Validate: `npm run arch:check`
+```
+
+## STEP 2: Wait for Approval
+Tell user: "I've created an OpenSpec proposal at `openspec/changes/add-{screenset}-{action}/`. Please review and run `/openspec:apply add-{screenset}-{action}` to implement."
+
+## STEP 3: Apply Implementation (after approval)
+When user runs `/openspec:apply`, execute:
+
+### 3.1 Define Event
+In src/screensets/{screenset}/events/{domain}Events.ts:
+```typescript
+import { SCREENSET_ID } from '../ids';
+
+const DOMAIN_ID = '{domain}';
+
+export const {Domain}Events = {
+  {EventName}: `${SCREENSET_ID}/${DOMAIN_ID}/{eventName}` as const,
+} as const;
+
+export type {EventName}Payload = {
+  // payload fields
+};
+
+declare module '@hai3/state' {
+  interface EventPayloadMap {
+    [{Domain}Events.{EventName}]: {EventName}Payload;
+  }
+}
+```
+
+### 3.2 Create Action
+In src/screensets/{screenset}/actions/{domain}Actions.ts:
+```typescript
+import { eventBus } from '@hai3/state';
+import { {Domain}Events } from '../events/{domain}Events';
+
+export const {actionName} = (params: ParamsType) => {
+  return (): void => {
+    eventBus.emit({Domain}Events.{EventName}, {
+      // payload
+    });
+  };
+};
+```
+
+### 3.3 Create Effect
+In src/screensets/{screenset}/effects/{domain}Effects.ts:
+```typescript
+import { eventBus, getStore } from '@hai3/state';
+import { {Domain}Events } from '../events/{domain}Events';
+
+export function init{Domain}Effects(): void {
+  const store = getStore();
+  eventBus.on({Domain}Events.{EventName}, (payload) => {
+    store.dispatch(set{Something}(payload.{field}));
+  });
+}
+```
+
+### 3.4 Validate
+```bash
+npm run arch:check
+```
+
+### 3.5 Mark Tasks Complete
+Update tasks.md to mark all completed tasks.
+
+## RULES
+- Actions use imperative names (selectScreen, changeTheme).
+- Events use past-tense names (screenSelected, themeChanged).
+- Actions are pure functions (no getState, no async thunks).
+- Actions return void (not Promise).
+- Effects update their own slice only.
+- Cross-domain communication only via events.
+- FORBIDDEN: Direct slice dispatch from actions/components.

package/commands/hai3-quick-ref.md

@@ -0,0 +1,63 @@
+<!-- @standalone -->
+# hai3:quick-ref - Quick Reference
+
+## Event-Driven
+- REQUIRED: Action emits event via eventBus.emit('event/name', payload).
+- REQUIRED: Effect subscribes via eventBus.on('event/name', handler).
+- REQUIRED: Effect updates slice via store.dispatch(setSlice(data)).
+- FORBIDDEN: Direct slice dispatch from actions or components.
+
+## Imports
+- Same package: BAD import from '@hai3/uikit/src/Foo' -> GOOD import from './Foo'.
+- Cross-branch app: BAD import from '../../core/layout' -> GOOD import from '@/core/layout'.
+- Cross-package: BAD import from '@hai3/uikit/src/internal' -> GOOD import from '@hai3/uikit'.
+
+## Components
+- REQUIRED: Check global @hai3/uikit first; screenset uikit only if missing.
+- App/screensets: REQUIRED import { Button } from '@hai3/uikit'.
+- FORBIDDEN: Raw HTML elements for UI.
+- FORBIDDEN: Inline component definitions in *Screen.tsx.
+
+## Component Placement
+- REQUIRED: Screenset uikit/ structure: base/, composite/, icons/.
+- REQUIRED: uikit/base/ for rare primitives (inline styles allowed).
+- REQUIRED: uikit/composite/ for screenset composites (theme tokens only).
+- REQUIRED: Shared components in screensets/{name}/components/.
+- REQUIRED: Screen-local components in screens/{screen}/components/.
+- REQUIRED: Screen files orchestrate components only.
+
+## Registry
+- REQUIRED: export const MY_DOMAIN = 'my-domain'.
+- REQUIRED: class MyService extends BaseApiService.
+- REQUIRED: declare module '@hai3/api' { interface ApiServicesMap }.
+- REQUIRED: apiRegistry.register(MY_DOMAIN, MyService).
+
+## Styling
+- Inline styles ONLY in screensets/*/uikit/base/ (rare local primitives).
+- BAD style={{ backgroundColor: '#fff' }} -> GOOD className="bg-background".
+- BAD style={{ color: '#000' }} -> GOOD className="text-foreground".
+- REQUIRED: Use Tailwind utilities, CSS variables elsewhere.
+
+## i18n
+- REQUIRED: i18nRegistry.registerLoader('screenset.demo', loader).
+- REQUIRED: Use t('screenset.demo:screens.home.title') format.
+- FORBIDDEN: Hardcoded strings in UI.
+
+## Commands
+- npm ci -> Install dependencies.
+- npm run dev -> Start dev server.
+- npm run arch:check -> Validate (CRITICAL before commits).
+- npm run type-check -> TypeScript validation.
+- npm run lint -> ESLint validation.
+
+## Invariants
+- REQUIRED: Event-driven architecture only.
+- REQUIRED: Registries follow Open/Closed principle.
+- REQUIRED: App deps limited to @hai3/react, @hai3/uikit, react, react-dom.
+- REQUIRED: Cross-domain communication via events only.
+- FORBIDDEN: String literals for IDs.
+- FORBIDDEN: any type or unsafe casts.
+
+## Docs
+- .ai/GUIDELINES.md -> Routing table.
+- .ai/targets/*.md -> Area-specific rules.

package/commands/hai3-rules.md

@@ -0,0 +1,43 @@
+<!-- @standalone -->
+# hai3:rules - Show HAI3 Rules for Specific Area
+
+Ask the user which area they want rules for, or detect from context.
+
+## ROUTING TABLE
+
+| Area | Target file |
+|------|-------------|
+| Data flow / events | .ai/targets/EVENTS.md |
+| API layer | .ai/targets/API.md |
+| packages/uicore | .ai/targets/UICORE.md |
+| packages/uikit | .ai/targets/UIKIT.md |
+| packages/uikit-contracts | .ai/targets/UIKIT_CONTRACTS.md |
+| src/screensets | .ai/targets/SCREENSETS.md |
+| src/themes | .ai/targets/THEMES.md |
+| Styling anywhere | .ai/targets/STYLING.md |
+| AI documentation | .ai/targets/AI.md |
+
+Then:
+
+1. Read the applicable target file
+2. Summarize the CRITICAL RULES section (3-7 rules)
+3. List STOP CONDITIONS
+4. Show PRE-DIFF CHECKLIST items
+5. Provide common violation examples with fixes
+
+Format output as:
+
+## Critical Rules
+[List 3-7 key rules in your own words]
+
+## Stop Conditions
+[When to stop and ask]
+
+## Common Violations
+[Show BAD -> GOOD examples]
+
+## Pre-Diff Checklist
+[Checklist from target file]
+
+## Reference
+Full rules: `.ai/targets/{FILE}.md`

package/commands/hai3-validate.md

@@ -0,0 +1,49 @@
+<!-- @standalone -->
+# hai3:validate - Validate Changes
+
+## AI WORKFLOW (REQUIRED)
+1) Read .ai/GUIDELINES.md and identify target file(s) for your changes.
+2) Summarize 3-7 key rules from applicable target file(s).
+3) Run validation checks.
+4) Report results.
+
+## STEP 1: Route to Target Files
+- Use .ai/GUIDELINES.md ROUTING section.
+- Read each applicable target file.
+- Summarize rules internally (not written).
+
+## STEP 2: Run Architecture Check
+```bash
+npm run arch:check
+```
+REQUIRED: Must pass with zero errors.
+
+## STEP 3: Check Common Violations
+- Direct slice dispatch (use event-driven actions instead).
+- Inline styles outside base uikit folders (uikit/base/ only).
+- Import violations (package internals, circular dependencies).
+- String literal IDs (must use constants or enums).
+- Inline component definitions in *Screen.tsx files.
+- Inline data arrays (must use API services).
+- @hai3/uicore imports in screensets/*/uikit/ folders.
+- Screenset uikit component when global @hai3/uikit has equivalent.
+
+## STEP 4: Verify Event-Driven Flow
+- Actions emit events (not dispatch slices).
+- Effects listen to events and update slices.
+- No prop drilling or callback-based state mutation.
+
+## STEP 5: Test via Chrome DevTools MCP
+STOP: If MCP WebSocket is closed, fix connection first.
+- Exercise all affected flows and screens.
+- Verify UI uses @hai3/uikit and theme tokens.
+- Verify event-driven behavior (no direct slice dispatch).
+- Check for console errors or missing registrations.
+
+## STEP 6: Report Results
+- List rules verified.
+- List any violations found.
+- Confirm npm run arch:check passed.
+
+## IF VIOLATIONS FOUND
+Use hai3:fix-violation command to correct issues.