@synetics/ui 0.7.0-alpha

package/TEST-FAILURE-ANALYSIS.md

@@ -0,0 +1,326 @@
+# Test Failure Analysis - Showcase Pages
+
+**Test Run Summary**: 33 failures | 72 passed (105 total tests)
+**Test Execution Date**: Current session
+**Framework**: Vitest 4.0.18 + jsdom
+
+## Critical Infrastructure Issues
+
+### Issue #1: Error Boundary Architecture - appendChild() Failure
+
+**Severity**: CRITICAL | **Affected**: Error Boundary, Control Flow, Context pages  
+**Root Cause**: Components throwing errors don't return DOM nodes
+
+**Error Message**:
+
+```
+TypeError: Failed to execute 'appendChild' on 'Node': parameter 1 is not of type 'Node'.
+```
+
+**Analysis**:
+
+1. JSX transformation calls components as functions
+2. `ErrorComponent` throws error directly → returns undefined
+3. Parent attempts `appendChild(undefined)` → TypeError
+4. Tryer/Catcher should catch this, but error occurs BEFORE Tryer can intercept
+
+**Architecture Problem**:
+The error occurs during the synchronous appendChild operation, which is OUTSIDE the try-catch block in Tryer. The transformer generates code that:
+
+```js
+container.appendChild(ErrorComponent()); // Throws BEFORE Tryer's try-catch
+```
+
+**Enterprise-Grade Fix Required**:
+
+- Transformer-level: Wrap ALL component invocations in micro-try-catch
+- Registry-level: Intercept component execution in REGISTRY.execute()
+- Runtime-level: DOM operations should validate node types before appendChild
+
+---
+
+### Issue #2: Catcher JSX Children API Mismatch
+
+**Severity**: HIGH | **Affected**: Error Boundary page  
+**Root Cause**: PSR transformer doesn't match Catcher API
+
+**Expected API** (from docs):
+
+```ts
+Catcher({
+  render: (errorInfo) => <div>{errorInfo.error.message}</div>
+})
+```
+
+**Actual Usage in PSR**:
+
+```jsx
+<Catcher>{(error, reset) => <div>{error.message}</div>}</Catcher>
+```
+
+**Problem**: Transformer passes children as `props.children`, but Catcher expects `props.render`
+
+**Enterprise-Grade Fix Required**:
+
+- Create JSX-aware Catcher component wrapper
+- Transform `<Catcher>{fn}</Catcher>` → `Catcher({ render: fn })`
+- OR: Update Catcher to accept both `render` prop AND `children` function
+
+---
+
+### Issue #3: Context Values Not Rendering
+
+**Severity**: HIGH | **Affected**: Context Test page  
+**Tests Failing**: 8/8 context tests
+
+**Expected**: Context values displayed in UI
+**Actual**: Only page title renders, no context-driven content
+
+**Failed Assertions**:
+
+```ts
+expect(container.textContent).toContain('Welcome, Alice!'); // ✗ Missing
+expect(themedBoxes.length).toBeGreaterThanOrEqual(3); // ✗ Found 0
+expect(container.textContent).toContain('Dark'); // ✗ Missing
+```
+
+**Root Cause Hypotheses**:
+
+1. **Context not propagating**: useContext() not finding provider values
+2. **Conditional rendering broken**: Context-dependent JSX not rendering
+3. **Signal reactivity lost**: Context signals not triggering re-renders
+
+**Enterprise-Grade Fix Required**:
+
+- Audit context-provider-consumer.test.ts integration test
+- Verify createContext → ProvideContext → useContext flow
+- Check if PSR transformer preserves context propagation
+
+---
+
+### Issue #4: Control Flow Components Not Rendering Content
+
+**Severity**: HIGH | **Affected**: Control Flow Test page  
+**Tests Failing**: 4/12 control flow tests
+
+**Show Component**:
+
+```ts
+expect(container.textContent).toContain('This content is shown'); // ✗ Missing
+```
+
+**For Component** (Keyed Lists):
+
+```ts
+expect(container.textContent).toContain('Apple'); // ✗ Missing
+expect(container.textContent).toContain('$1.20'); // ✗ Missing
+```
+
+**Index Component**:
+
+```ts
+expect(container.textContent).toContain('Item 0'); // ✗ Missing
+```
+
+**Root Cause**:
+
+- Show/For/Index components render but children don't appear
+- Likely: Incorrect JSX transformation of control flow children
+- Possible: Reactive dependencies not tracked properly
+
+**Enterprise-Grade Fix Required**:
+
+- Audit Show/For/Index implementation in synetics.dev
+- Verify children rendering logic in control flow components
+- Check PSR transformer handling of control flow JSX
+
+---
+
+### Issue #5: Navigation/Router Not Functional in Test Environment
+
+**Severity**: HIGH | **Affected**: All navigation tests (9/9 failures)  
+**Impact**: All showcase pages inaccessible via router in tests
+
+**Failed Tests**:
+
+```ts
+✗ should render all navigation buttons
+✗ should have navigation buttons with proper styling
+✗ should display home page by default
+✗ should navigate to reactivity page
+✗ should navigate to about page
+✗ should update currentPath signal on navigation
+✗ should load control flow page content
+✗ should load context page content
+✗ should navigate back from about to home
+```
+
+**Root Cause**:
+
+- Router implementation not compatible with jsdom environment
+- Mock window.location/window.history in setup.ts insufficient
+- Hash-based routing not triggering route changes
+
+**Enterprise-Grade Fix Required**:
+
+- Implement router test doubles/mocks
+- Create MemoryRouter for test environment
+- Separate routing logic from browser APIs for testability
+
+---
+
+## Test Suite Health by Page
+
+| Page                         | Tests | Passed | Failed | Health  |
+| ---------------------------- | ----- | ------ | ------ | ------- |
+| Assignment Test              | 5     | 5      | 0      | ✅ 100% |
+| About                        | 6     | 6      | 0      | ✅ 100% |
+| Home                         | 6     | 6      | 0      | ✅ 100% |
+| JSX Test                     | 8     | 8      | 0      | ✅ 100% |
+| Reactivity Test              | 20    | 20     | 0      | ✅ 100% |
+| Resource Test                | 10    | 10     | 0      | ✅ 100% |
+| **Control Flow**             | 12    | **8**  | **4**  | ⚠️ 67%  |
+| **Context Test**             | 8     | **0**  | **8**  | ❌ 0%   |
+| **Error Boundary**           | 12    | **0**  | **12** | ❌ 0%   |
+| **Navigation (Integration)** | 9     | **0**  | **9**  | ❌ 0%   |
+| Context Integration          | 2     | 2      | 0      | ✅ 100% |
+| Reactivity Integration       | 7     | 7      | 0      | ✅ 100% |
+
+---
+
+## Working Features (Validation)
+
+### ✅ Core Reactivity
+
+- Signals: createSignal, reading, writing
+- Memos: createMemo, dependency tracking
+- Effects: createEffect, cleanup
+- Batch updates: batch()
+
+### ✅ JSX Fundamentals
+
+- Static attributes
+- Dynamic attributes (reactive)
+- Event handlers (onClick, onInput)
+- Inline styles
+- Ternary conditionals
+
+### ✅ Component Lifecycle
+
+- Component mounting
+- Component registration (REGISTRY.execute)
+- Counter component (complex reactivity + JSX)
+
+### ✅ Resource Loading (Surprising!)
+
+- createResource API
+- Loading states (user.isLoading)
+- Data fetching with signals
+- Refetch functionality
+
+### ✅ Routing (Partial)
+
+- About page toggleDetails() functionality
+- Route context access
+- Navigation button rendering
+
+---
+
+## Priority Fix Roadmap
+
+### P0: Error Boundary Architecture (Critical Path)
+
+**Blocks**: Error Boundary page, affects stability of all pages
+
+1. **Transformer Enhancement**: Wrap component invocations in safe execution
+2. **REGISTRY Hardening**: Add error catching in REGISTRY.execute()
+3. **Catcher API Unification**: Support both `render` prop and JSX children
+4. **Tryer Timing Fix**: Catch errors during appendChild operations
+
+### P0: Context System (Critical Path)
+
+**Blocks**: Context Test page, theme system, user auth demos
+
+1. **Context Propagation Audit**: Verify createContext → useContext flow
+2. **Provider Rendering**: Ensure ProvideContext wraps children correctly
+3. **Signal Integration**: Verify context signals trigger re-renders
+4. **Nested Context**: Test multiple contexts (theme + user + settings)
+
+### P1: Control Flow Rendering
+
+**Blocks**: Demonstration of core framework features
+
+1. **Show Component**: Fix conditional rendering of children
+2. **For Component**: Fix keyed list rendering
+3. **Index Component**: Fix indexed list rendering
+4. **Reactivity Tracking**: Ensure control flow re-renders on signal changes
+
+### P1: Router Test Infrastructure
+
+**Blocks**: Integration tests, realistic user flows
+
+1. **MemoryRouter**: Create in-memory router for tests
+2. **Route Mocking**: Mock currentPath signal
+3. **Navigation Testing**: Simulate route changes programmatically
+4. **History API**: Complete jsdom history implementation
+
+---
+
+## Non-Issues (False Alarms)
+
+### Resource Page - WORKING ✅
+
+**Initial Concern**: `user.isLoading` might need `user.isLoading()`  
+**Reality**: Tests pass 10/10. Resource API correctly implemented.
+
+### Reactivity Page - WORKING ✅
+
+**Initial Concern**: Complex reactive dependencies
+**Reality**: Tests pass 20/20. All signal/memo/effect patterns work.
+
+### Home/About Pages - WORKING ✅
+
+**Initial Concern**: Routing integration
+**Reality**: Tests pass 12/12. Pages render correctly in isolation.
+
+---
+
+## Architectural Insights
+
+### Framework Strengths (Validated by Tests)
+
+1. **Reactive Core**: Signals/memos/effects are rock-solid
+2. **JSX Transformation**: Static + dynamic attrs, events work perfectly
+3. **Component System**: Registration, lifecycle, nesting all functional
+4. **Resource Management**: Async data handling with loading states works
+
+### Framework Gaps (Exposed by Tests)
+
+1. **Error Boundary Integration**: Not catching errors during JSX render
+2. **Context System**: Provider-consumer flow has rendering issues
+3. **Control Flow Components**: Children rendering logic incomplete
+4. **Test Infrastructure**: Router not designed for jsdom environment
+
+---
+
+## Next Steps
+
+1. **Read Codebase**: Examine Tryer/Catcher + transformer error handling
+2. **Design Fixes**: Architecture-oriented solutions (no patches)
+3. **Implement**: Fix P0 issues (error boundaries + context)
+4. **Validate**: Re-run tests, ensure 100% pass rate
+5. **Document**: Update error-boundary documentation with JSX patterns
+
+## Uncertainty Threshold
+
+**STOP and report if**:
+
+- Fixes require changing transformer core architecture (>500 LOC)
+- Context system design fundamentally broken (requires redesign)
+- Error boundaries unsalvageable (need different pattern)
+
+**Proceed with confidence if**:
+
+- Fixes are localized (< 200 LOC per issue)
+- Patterns involve wrapping/adapting existing code
+- Solutions follow established Synetics patterns

package/console-mirror.html

@@ -0,0 +1,79 @@
+<!doctype html>
+<html>
+  <head>
+    <title>CAPTURE ALL CONSOLE</title>
+    <style>
+      body {
+        background: #000;
+        color: #0f0;
+        padding: 20px;
+        font-family: monospace;
+        font-size: 12px;
+      }
+      .console-log {
+        color: #0f0;
+      }
+      .console-warn {
+        color: #ff0;
+      }
+      .console-error {
+        color: #f00;
+        font-weight: bold;
+      }
+    </style>
+  </head>
+  <body>
+    <h1>CONSOLE OUTPUT MIRROR</h1>
+    <div id="console-output"></div>
+    <hr />
+    <h2>APP:</h2>
+    <div id="app" style="border: 2px solid red; padding: 20px; min-height: 100px"></div>
+
+    <script>
+      // Intercept all console methods
+      const output = document.getElementById('console-output');
+      const original = {
+        log: console.log,
+        warn: console.warn,
+        error: console.error,
+      };
+
+      function mirror(type, ...args) {
+        const div = document.createElement('div');
+        div.className = `console-${type}`;
+        div.textContent = `[${type.toUpperCase()}] ${args
+          .map((a) => (typeof a === 'object' ? JSON.stringify(a) : String(a)))
+          .join(' ')}`;
+        output.appendChild(div);
+        original[type](...args);
+      }
+
+      console.log = (...args) => mirror('log', ...args);
+      console.warn = (...args) => mirror('warn', ...args);
+      console.error = (...args) => mirror('error', ...args);
+
+      console.log('Console mirroring active');
+    </script>
+
+    <script type="module">
+      console.log('▶ Loading main-avatar-test...');
+
+      try {
+        const { bootstrapApp } = await import('@synetics/synetics.dev');
+        const { AvatarTest } = await import('./src/test-psr-avatar.syn');
+
+        console.log('bootstrapApp:', typeof bootstrapApp);
+        console.log('AvatarTest:', typeof AvatarTest);
+
+        bootstrapApp({
+          root: '#app',
+          component: AvatarTest,
+          props: {},
+        });
+      } catch (err) {
+        console.error('FATAL:', err.message);
+        console.error('Stack:', err.stack);
+      }
+    </script>
+  </body>
+</html>