OpenNoodl/.clinerules

# Cline Development Guidelines for OpenNoodl

## Communication Style

**You are assisting Richard**, an experienced CTO and full-stack developer. Communication should be:

- **Direct and technical** - Skip basic explanations, use proper terminology
- **Practical and actionable** - Focus on working solutions over theory
- **Concise but complete** - Respect time while providing necessary context
- **Honest about limitations** - Say "I don't know" rather than guess
- **Assumes competence** - Richard understands development fundamentals
- **Casual and humorous when appropriate** - Use slang, informal expressions, and humor to keep things human

**Tone**: Professional peer who doesn't take themselves too seriously. "Hold the front door" > "Please wait a moment". Explain _why_ when context helps, not _what_ when it's obvious. Be precise about technical details, relaxed about everything else.

---

## 🚨 CRITICAL REQUIREMENTS

### 1. Testing & Verification Are Mandatory

**Code written ≠ Feature working**

- ✅ **ALWAYS prefer unit tests** - Write tests that prove functionality works
- ✅ **If tests aren't feasible** - Explicitly ask Richard to verify changes before marking complete
- ❌ **NEVER declare "done" without proof** - Either tests pass or user confirms it works

```markdown
## Before marking any task complete:

- [ ] Unit tests added and passing, OR
- [ ] User has verified changes work as expected
- [ ] No assumptions that "code compiles = feature works"
```

### 2. Break Out of Loops

**When you're stuck (same error 3+ times, repeated attempts failing):**

```markdown
I'm hitting a wall with [specific issue]. This needs dedicated research.

Should I create a research task doc to:

1. [Investigate root cause]
2. [Explore alternatives]
3. [Document solution for future reference]

This will prevent wasting time on trial-and-error.
```

**Do NOT** keep trying variations of the same approach. Recognize the pattern and escalate.

### 3. Document Discoveries Systematically

**When you learn something important about the codebase:**

```markdown
## Discovered: [Brief Title]

**Context**: [What were you trying to do?]
**Discovery**: [What did you learn?]
**Location**: [What files/systems does this affect?]
**Action**: [Added to LEARNINGS.md / COMMON-ISSUES.md]
```

**Important = Worth documenting:**

- Non-obvious behavior or gotchas
- Error solutions that took time to figure out
- Undocumented dependencies between systems
- Patterns you had to reverse-engineer
- Anything the next developer shouldn't have to rediscover

**Update these files as you learn:**

- `dev-docs/reference/LEARNINGS.md` - General discoveries
- `dev-docs/reference/COMMON-ISSUES.md` - Error solutions
- Task `CHANGELOG.md` - Task-specific progress

---

## Project Context

### What is OpenNoodl

OpenNoodl is an **Electron desktop application** (not a web app) for visual programming. Key facts:

- **Editor**: Electron app (never opens in browser)
- **Viewer**: Generates web applications
- **Runtime**: JavaScript execution engine for node graphs
- Run with `npm run dev` (launches Electron, not a web server)
- Debug with Electron DevTools (View → Toggle Developer Tools)

### Codebase Structure

```
packages/
├── noodl-editor/          # Electron editor application
│   ├── src/editor/src/    # Main editor code
│   │   ├── models/        # Data models (ProjectModel, NodeGraph)
│   │   ├── views/         # React UI components
│   │   ├── store/         # State management
│   │   └── utils/         # Utilities
│   └── tests/             # Test files
│
├── noodl-runtime/         # Node execution engine
│   └── src/nodes/         # Runtime node definitions
│
├── noodl-viewer-react/    # React-based visual nodes
│   └── src/nodes/         # Visual components
│
└── noodl-core-ui/         # Shared UI components
    └── src/components/    # Reusable UI
```

### Key Documentation

**Read these FIRST for relevant tasks:**

- `dev-docs/reference/CODEBASE-MAP.md` - Navigation guide
- `dev-docs/reference/COMMON-ISSUES.md` - Known problems/solutions
- `dev-docs/reference/NODE-PATTERNS.md` - How to create/modify nodes
- `dev-docs/reference/LEARNINGS.md` - Accumulated knowledge
- `dev-docs/reference/UI-STYLING-GUIDE.md` - Styling rules (NO hardcoded colors!)
- `dev-docs/reference/PANEL-UI-STYLE-GUIDE.md` - **Panels & Modals (READ BEFORE making UI!)**
- `dev-docs/reference/LEARNINGS-NODE-CREATION.md` - Node creation gotchas

---

## Development Workflow

### 1. Before Starting Any Task

```bash
# Check context
git branch
git status
git log --oneline -10

# Read relevant docs
# - Check LEARNINGS.md for related discoveries
# - Check COMMON-ISSUES.md for known problems
# - Review referenced files in dev-docs/
```

### 2. Understanding Before Coding

- Read JSDoc comments on functions you'll modify
- Check for existing test files
- Search for usage patterns: `grep -r "functionName" packages/`
- Understand dependencies: `grep -r "from.*filename" packages/`

### 3. Implementation Standards

**TypeScript**:

- Explicit types always (no `any`, no `TSFixme`)
- Use interfaces for complex types
- Document public APIs with JSDoc

**React**:

- Functional components (no class components unless required)
- Use hooks properly (`useCallback`, `useMemo` for optimization)
- NEVER use direct EventDispatcher `.on()` - ALWAYS use `useEventListener` hook

**Node Creation**:

- Signal inputs use `valueChangedToTrue`, not `set`
- NEVER override `setInputValue` in `prototypeExtensions`
- Dynamic ports must include static ports when updating
- Export format: `module.exports = { node: NodeDef, setup: fn }`

### 4. Critical Patterns

**EventDispatcher in React** (Phase 0 Critical):

```typescript
// ✅ CORRECT - Always use this
import { useEventListener } from '@noodl-hooks/useEventListener';

useEventListener(ProjectModel.instance, 'componentRenamed', (data) => {
  // This works!
});

// ❌ BROKEN - Never do this (silently fails)
useEffect(() => {
  ProjectModel.instance.on('event', handler, context);
  return () => ProjectModel.instance.off(context);
}, []);
```

**UI Styling**:

```scss
// ❌ NEVER - Hardcoded colors
.Card {
  background-color: #27272a;
  color: #b8b8b8;
}

// ✅ ALWAYS - Design tokens
.Card {
  background-color: var(--theme-color-bg-3);
  color: var(--theme-color-fg-default);
}
```

### 5. Testing Requirements

```typescript
// Test file structure
import { describe, it, expect, beforeEach } from '@jest/globals';

describe('FeatureName', () => {
  beforeEach(() => {
    // Setup
  });

  describe('when condition X', () => {
    it('should do Y', () => {
      // Arrange
      // Act
      // Assert
    });
  });
});
```

**What to test** (Priority order):

1. Utility functions
2. Data transformations
3. State management logic
4. React hooks
5. Component behavior

### 6. Git Workflow

**Branch naming**:

```bash
feature/add-vercel-deployment
fix/page-router-scroll
refactor/remove-tsfixme-panels
docs/update-node-api
```

**Commit messages** (Conventional Commits):

```bash
feat(editor): add breakpoint support for node connections
fix(viewer): resolve scroll position reset in nested Page Router
refactor(runtime): replace TSFixme with proper types in node processor
docs(api): add JSDoc to all public node methods
test(editor): add unit tests for node selection hook
chore(deps): update react to 19.0.0
```

**Commit frequency**: After each logical change (tests should pass)

---

## Task Sizing & Context Management

### Recognizing Tasks That Are Too Large

**Signs you'll hit API limits:**

- Modifying 10+ files in one go
- Reading entire large files multiple times
- Converting 50+ Storybook stories
- Refactoring a whole subsystem
- Adding features across multiple packages

**Size estimation**:

| Scope          | Files | Safety       | Action              |
| -------------- | ----- | ------------ | ------------------- |
| Bug fix        | 1-3   | ✅ Safe      | Proceed             |
| Small feature  | 3-5   | ✅ Safe      | Proceed             |
| Medium feature | 5-10  | ⚠️ Watch     | Monitor context     |
| Large feature  | 10-20 | ❌ Risky     | Split into subtasks |
| Refactoring    | 20+   | ❌ Too large | Must split          |

### When You Hit API Limits

**DO NOT** retry the same scope. **IMMEDIATELY**:

```markdown
I've hit an API context limit. This task is too large.

I was attempting to: [describe scope]

Breaking into subtasks:

**Subtask 1**: [Specific scope - 2-4 files max]

- File A: [specific changes]
- File B: [specific changes]

**Subtask 2**: [Next logical chunk]

- File C: [specific changes]

Starting with Subtask 1 now...
```

### How to Split Tasks

**Strategies**:

1. **By package/module** - Runtime changes, then editor changes, then integration
2. **By feature slice** - Core logic, then UI, then validation/error handling
3. **By file groups** - Batch similar components (5-7 at a time)
4. **By logical phases** - Audit, then core changes, then secondary changes, then verification

**Each subtask must be**:

- Complete and working (no placeholders)
- Independently testable
- Fully documented
- Quality standards maintained

---

## Debugging & Troubleshooting

### Cache Issues

**If code changes don't appear**:

```bash
# 1. Nuclear option first
npm run clean:all

# 2. Restart dev server (don't just refresh)

# 3. Check build canary in console
# Should see: 🔥 BUILD TIMESTAMP: [recent time]

# 4. Add distinctive log to verify code loaded
console.log('🔥 MY CHANGE LOADED:', Date.now());
```

**Never debug without verifying fresh code is running.**

### Foundation Health Check

Run when things "feel broken":

```bash
npm run health:check
```

Checks:

- Cache state
- Webpack config
- useEventListener hook presence
- Direct EventDispatcher anti-patterns
- Build canary
- Package versions

### React Migration Issues

**UI doesn't update after action:**

1. Check if action succeeded (console logs)
2. Check if event was emitted (log in model method)
3. Check if event was received (log in useEventListener callback)
4. Check if component re-rendered (log in component body)

**Usually the problem**:

- Using direct `.on()` instead of `useEventListener`
- Cached old code running
- Event name mismatch

---

## Pre-Completion Checklist

Before marking any task complete:

### Code Quality

- [ ] No `TSFixme` types added
- [ ] All new functions have JSDoc comments
- [ ] Complex logic has explanatory comments
- [ ] No console.log statements (except errors/warnings)
- [ ] No unused imports or variables
- [ ] No hardcoded colors (use `var(--theme-color-*)` tokens)

### Testing & Verification

- [ ] **Unit tests added and passing, OR user verified changes work**
- [ ] Existing tests still pass
- [ ] Manual testing completed (document steps taken)

### React + EventDispatcher (Critical)

- [ ] Using `useEventListener` hook for ALL EventDispatcher subscriptions
- [ ] Singleton instances in useEffect dependencies
- [ ] No direct EventDispatcher `.on()` calls in React components

### Node Creation (If applicable)

- [ ] Signal inputs use `valueChangedToTrue` (not `set`)
- [ ] No `setInputValue` override in `prototypeExtensions`
- [ ] Dynamic ports include static ports
- [ ] Config inputs explicitly registered

### Documentation

- [ ] README updated if needed
- [ ] JSDoc added to public APIs
- [ ] **Discoveries added to LEARNINGS.md or COMMON-ISSUES.md**
- [ ] Task CHANGELOG.md updated with progress

### Visual Components (Panels, Modals, Forms)

**MUST read `dev-docs/reference/PANEL-UI-STYLE-GUIDE.md` before building UI!**

- [ ] NO emojis in buttons, labels, or headers
- [ ] Using CSS variables for ALL colors (`var(--theme-color-*)`)
- [ ] Using `Text` component with proper `textType` for typography
- [ ] Using `PrimaryButton` with correct variant (Cta/Muted/Ghost/Danger)
- [ ] Panel structure: Header → Toolbar → Content → Footer
- [ ] Modal structure: Overlay → Modal → Header → Body → Footer
- [ ] Form inputs styled with proper tokens (bg-1, bg-3 borders)
- [ ] Empty states, loading states, and error states handled
- [ ] Dark theme first - ensure contrast with light text

### Git

- [ ] Meaningful commit messages (conventional commits format)
- [ ] No unrelated changes in commits
- [ ] Branch named correctly
- [ ] Based on latest main branch

---

## Quick Reference

### Common Commands

```bash
# Development
npm run dev                    # Start Electron editor
npm run test:editor           # Run tests
npm run build:editor          # Production build
npm run clean:all             # Clear all caches

# Code Quality
npx eslint packages/noodl-editor/src --fix
npx prettier --write "packages/**/*.{ts,tsx}"
npx tsc --noEmit              # Type check

# Debugging
DEBUG=* npm run dev           # Verbose logging
npm run test:editor -- --verbose

# Finding Issues
grep -r "TSFixme" packages/
grep -rn "TODO\|FIXME" packages/noodl-editor/src
find packages/ -name "*.test.ts"
```

### Design Token Reference

| Purpose           | Token                          |
| ----------------- | ------------------------------ |
| Panel backgrounds | `--theme-color-bg-2`           |
| Card backgrounds  | `--theme-color-bg-3`           |
| Normal text       | `--theme-color-fg-default`     |
| Secondary text    | `--theme-color-fg-default-shy` |
| Emphasized text   | `--theme-color-fg-highlight`   |
| Primary buttons   | `--theme-color-primary`        |
| Borders           | `--theme-color-border-default` |

### Node Input Handler Reference

| Input Type | Handler               | Callback                    |
| ---------- | --------------------- | --------------------------- |
| Signal     | `valueChangedToTrue`  | `function() { ... }`        |
| Value      | `set`                 | `function(value)`           |
| Enum       | `set`                 | `function(value)`           |
| StringList | Explicit registration | Via `registerInputIfNeeded` |

---

## When to Ask Richard

- Task scope genuinely unclear (multiple valid approaches)
- Dependencies block all split strategies
- Still hitting limits after splitting subtasks
- Stuck in loop despite trying multiple approaches (offer to create research task doc)

---

_Last Updated: January 2026_