Merge branch 'cline-dev-richard' into cline-dev

dev-docs/reference/COMMON-ISSUES.md

@@ -412,3 +412,44 @@ Found a solution not listed here? Add it!
 2. Follow the format: Symptom → Solutions
 3. Include specific commands when helpful
 4. Submit PR with your addition
+
+---
+
+## Jest / Test Runner Hangs on Webpack Build
+
+**Symptom**: `npm run test:editor -- --testPathPattern=Foo` hangs indefinitely.
+
+**Root cause**: `scripts/test-editor.ts` runs a full webpack compile before Jest. Can appear hung but is just slow (30-90s).
+
+**Rules**:
+
+- Always put test files in `tests/models/` not `tests/services/` (transform config only covers models/ path)
+- Never use `npx jest` directly - Babel cannot parse TypeScript `type` keyword without the full transform setup
+- Use `npm run test:editor` from root — it will eventually complete
+- Never use heredoc (`cat << EOF`) in terminal commands — use printf or write_to_file instead
+
+---
+
+## Pre-Existing Test Bundle Compilation Errors (Feb 2026)
+
+**Symptom**: `npm run test:editor` fails with webpack compilation errors before any tests run:
+
+```
+ERROR: Can't resolve '@noodl-views/panels/componentspanel/ComponentsPanel'
+ERROR: TS2339: Property 'pull' does not exist on type 'Git'
+```
+
+**Root cause**: Two pre-existing issues in the test bundle (unrelated to sprint work):
+
+1. `tests/components/componentspanel.js` references `@noodl-views/panels/componentspanel/ComponentsPanel` — this component was moved/deleted in an earlier refactor. The test file still has the old import path.
+
+2. `tests/git/git-remote*.spec.ts` and `tests/git/git-stash-merge.spec.ts` call `git.pull()` — this method was removed from the `Git` type in `packages/noodl-git/src/git.ts` during an earlier refactor.
+
+**Impact**: The webpack test bundle refuses to compile, so NO tests run (not just the failing ones).
+
+**Fix when prioritised**:
+
+1. Delete or stub `tests/components/componentspanel.js` (or update the import to match the current component location)
+2. Update the git test specs to use the current API (check what replaced `pull` in `packages/noodl-git/src/git.ts`)
+
+**Workaround**: Tests can be verified structurally (code review + type checking) while this is unresolved. The issue is in pre-existing test infra, not in sprint-added code.

dev-docs/reference/LEARNINGS.md

@@ -1855,6 +1855,22 @@ grep -r "var(--theme-spacing" packages/noodl-core-ui/src --include="*.scss"
 **Discovery:** Only custom overrides are stored in project metadata — never defaults. Defaults live in `DefaultTokens.ts` and are merged at load time. This keeps `project.json` lean and lets defaults be updated without migrations.
 **Location:** `StyleTokensModel._store()` uses `ProjectModel.instance.setMetaData('designTokens', data)`
 
+## TS Won't Narrow Discriminated Unions in Async IIFEs (2026-02-18)
+
+**Context**: UBAPanel `useUBASchema` hook — `SchemaParser.parse()` returns
+`ParseResult<T>` which is `{ success: true; data: T } | { success: false; errors: ParseError[] }`.
+
+**Discovery**: TypeScript refuses to narrow this inside an `(async () => { ... })()`,
+even with `const result` and an `if (result.success) {} else {}` pattern. Error:
+`Property 'errors' does not exist on type '{ success: true; ... }'`.
+
+**Fix**: In the `else` branch, cast explicitly with an inline `type FailResult = { ... }` alias.
+No need for `as any` — a precise cast is fine and type-safe.
+
+**Location**: `views/panels/UBAPanel/UBAPanel.tsx`, `useUBASchema`.
+
+---
+
 ## STYLE-001: DesignTokenPanel/ColorsTab pre-existed (2026-02-18)
 
 **Context:** Adding a new "Tokens" tab to the DesignTokenPanel.

dev-docs/tasks/phase-6-uba-system/PROGRESS-richard.md

@@ -0,0 +1,89 @@
+# UBA System — Richard's Progress
+
+## Sprint 2 — 18 Feb 2026
+
+### Session 1 (Sprint 1)
+
+- **UBA-001**: `types.ts` — Full type definitions (UBASchema, all field types, ParseResult discriminated union)
+- **UBA-002**: `SchemaParser.ts` — Instance-method parser with `normalise()`, validation, warnings
+- Tests: `UBASchemaParser.test.ts` (18 cases), `UBAConditions.test.ts` (12 cases)
+
+### Session 2 (Sprint 1)
+
+- **UBA-003**: Field renderers — StringField, TextField, NumberField, BooleanField, SecretField, UrlField, SelectField, MultiSelectField, FieldWrapper, FieldRenderer
+- **UBA-004**: `ConfigPanel.tsx` + `ConfigSection.tsx` + `useConfigForm.ts` — Full tabbed config form with validation, dirty state, required-field check, section error dots
+
+### Session 3 (Sprint 2)
+
+- **UBA-005**: `services/UBA/UBAClient.ts` — Static HTTP client
+
+  - `configure()`: POST to config endpoint, timeout, auth headers, JSON body
+  - `health()`: GET health endpoint, never throws, returns HealthResult
+  - `openDebugStream()`: SSE via EventSource, named event types, auth as query param
+  - Auth modes: bearer, api_key (custom header), basic (btoa)
+  - `UBAClientError` with status + body for non-2xx responses
+
+- **UBA-006** + **UBA-007**: `views/panels/UBAPanel/` — Editor panel
+  - `UBAPanel.tsx`: BasePanel + Tabs (Configure / Debug)
+    - `useUBASchema` hook: reads `ubaSchemaUrl` from project metadata, fetches + parses
+    - `SchemaLoader` UI: URL input field + error banner
+    - `onSave` → stores `ubaConfig` in project metadata + POSTs via UBAClient
+    - `useEventListener` for `importComplete` / `instanceHasChanged`
+  - `DebugStreamView.tsx`: Live SSE log viewer
+    - Connect/Disconnect toggle, Clear button
+    - Auto-scroll with manual override (40px threshold), max 500 events
+    - Per-event type colour coding (log/info/warn/error/metric)
+    - "Jump to latest" sticky button
+  - `UBAPanel.module.scss`: All design tokens, no hardcoded colors
+  - **Test registration**: `tests/models/index.ts` + `tests/services/index.ts` created; `tests/index.ts` updated
+
+## Status
+
+| Task                         | Status  | Notes                            |
+| ---------------------------- | ------- | -------------------------------- |
+| UBA-001 Types                | ✅ Done |                                  |
+| UBA-002 SchemaParser         | ✅ Done | Instance method `.parse()`       |
+| UBA-003 Field Renderers      | ✅ Done | 8 field types                    |
+| UBA-004 ConfigPanel          | ✅ Done | Tabs, validation, dirty state    |
+| UBA-005 UBAClient            | ✅ Done | configure/health/openDebugStream |
+| UBA-006 ConfigPanel mounting | ✅ Done | UBAPanel with project metadata   |
+| UBA-007 Debug Stream Panel   | ✅ Done | SSE viewer in Debug tab          |
+
+### Session 4 (Sprint 2)
+
+- **UBA-008**: `router.setup.ts` — Registered UBAPanel in editor sidebar
+
+  - Added `uba` route with `UBAPanel` component
+  - Panel accessible via editor sidebar navigation
+
+- **UBA-009**: `UBAPanel.tsx` + `UBAPanel.module.scss` — Health indicator widget
+
+  - `useUBAHealth` hook: polls `UBAClient.health()` every 30s, never throws
+  - `HealthBadge` component: dot + label, 4 states (unknown/checking/healthy/unhealthy)
+  - Animated pulse on `checking` state; green/red semantic colours with `--theme-color-success/danger` tokens + fallbacks
+  - Shown above ConfigPanel when `schema.backend.endpoints.health` is present
+  - `configureTabContent` wrapper div for flex layout
+
+- **Test fixes**: `UBASchemaParser.test.ts`
+  - Added `isFailure<T>()` type guard (webpack ts-loader friendly discriminated union narrowing)
+  - Replaced all `if (!result.success)` with `if (isFailure(result))`
+  - Fixed destructuring discard pattern `_sv`/`_b` → `_` with `eslint-disable-next-line`
+
+## Status
+
+| Task                         | Status  | Notes                            |
+| ---------------------------- | ------- | -------------------------------- |
+| UBA-001 Types                | ✅ Done |                                  |
+| UBA-002 SchemaParser         | ✅ Done | Instance method `.parse()`       |
+| UBA-003 Field Renderers      | ✅ Done | 8 field types                    |
+| UBA-004 ConfigPanel          | ✅ Done | Tabs, validation, dirty state    |
+| UBA-005 UBAClient            | ✅ Done | configure/health/openDebugStream |
+| UBA-006 ConfigPanel mounting | ✅ Done | UBAPanel with project metadata   |
+| UBA-007 Debug Stream Panel   | ✅ Done | SSE viewer in Debug tab          |
+| UBA-008 Panel registration   | ✅ Done | Sidebar route in router.setup.ts |
+| UBA-009 Health indicator     | ✅ Done | useUBAHealth + HealthBadge       |
+
+## Next Up
+
+- STYLE tasks: Any remaining style overhaul items
+- UBA-010: Consider E2E integration test with mock backend

dev-docs/tasks/phase-9-styles-overhaul/PROGRESS-richard.md

@@ -0,0 +1,72 @@
+# Phase 9: Styles Overhaul — Richard's Progress
+
+_Branch: `cline-dev-richard`_
+
+---
+
+## Sprint 1 — 18 Feb 2026
+
+### STYLE-005: Smart Style Suggestion Engine ✅ (committed 05379c9)
+
+**Files created:**
+
+- `packages/noodl-editor/src/editor/src/services/StyleAnalyzer/types.ts` — TypeScript interfaces: `ElementReference`, `RepeatedValue`, `VariantCandidate`, `StyleAnalysisResult`, `StyleSuggestion`, `StyleAnalysisOptions`, `TokenModelLike`, `SUGGESTION_THRESHOLDS`
+- `packages/noodl-editor/src/editor/src/services/StyleAnalyzer/StyleAnalyzer.ts` — Static analyzer class:
+  - `analyzeProject(options?)` — scans all visual nodes for repeated raw colors/spacing (threshold: 3) and variant candidates (threshold: 3 overrides)
+  - `analyzeNode(nodeId)` — per-node analysis for property panel integration
+  - `toSuggestions(result)` — converts analysis to ordered `StyleSuggestion[]`
+  - `TokenModelLike` injected via options to avoid static singleton coupling
+- `packages/noodl-editor/src/editor/src/services/StyleAnalyzer/SuggestionActionHandler.ts` — `executeSuggestionAction()`:
+  - repeated-color/spacing → calls `tokenModel.setToken()` + replaces all occurrences with `var(--token-name)`
+  - variant-candidate → sets `_variant` param on node
+- `packages/noodl-editor/src/editor/src/services/StyleAnalyzer/index.ts` — barrel export
+- `packages/noodl-core-ui/src/components/StyleSuggestions/SuggestionBanner.tsx` — Compact banner UI (accept / ignore / never-show)
+- `packages/noodl-core-ui/src/components/StyleSuggestions/SuggestionBanner.module.scss` — Styled with CSS tokens only
+- `packages/noodl-core-ui/src/components/StyleSuggestions/index.ts` — barrel export
+- `packages/noodl-editor/src/editor/src/hooks/useStyleSuggestions.ts` — Hook: runs analyzer on mount, exposes `activeSuggestion`, `pendingCount`, `dismissSession`, `dismissPermanent`, `refresh`
+
+**Pending (next session):**
+
+- Unit tests for `StyleAnalyzer` (value detection, threshold logic, `toSuggestions` ordering)
+- Wire `SuggestionBanner` into `ElementStyleSection` / property panel
+- Consider debounced auto-refresh on `componentAdded`/`nodeParametersChanged` events
+
+---
+
+## Previously Completed (before Sprint 1)
+
+### STYLE-001: Token System Enhancement ✅
+
+- `StyleTokensModel` — CRUD for design tokens
+- `TokenResolver` — resolves CSS var references
+- `DEFAULT_TOKENS` — baseline token set
+- `TOKEN_CATEGORIES` / `TOKEN_CATEGORY_GROUPS` — category definitions
+
+### STYLE-002: Element Configs ✅
+
+- `ElementConfigRegistry` — maps node types to `ElementConfig`
+- `ButtonConfig`, `GroupConfig`, `TextConfig`, `TextInputConfig`, `CheckboxConfig`
+- `VariantSelector` component
+
+### STYLE-003: Style Presets ✅
+
+- `StylePresetsModel` — manages presets
+- 5 presets: Modern, Minimal, Playful, Enterprise, Soft
+- `PresetCard`, `PresetSelector` UI components
+
+### STYLE-004: Property Panel Integration ✅
+
+- `ElementStyleSection` — groups style props with token picker
+- `SizePicker` — visual size selector
+- `TokenPicker` — token autocomplete input
+- Property panel HTML + TS wired up
+
+---
+
+## Outstanding Issues
+
+| Issue                                                                                        | Status                                              |
+| -------------------------------------------------------------------------------------------- | --------------------------------------------------- |
+| `StyleTokensModel.setToken()` — verify method name matches actual API                        | ⚠️ Needs verification before action handler is used |
+| `node.setParameter()` / `node.getParameter()` — verify these are valid NodeGraphNode methods | ⚠️ Needs verification                               |
+| StyleAnalyzer unit tests                                                                     | 📋 Planned                                          |