From 2e46ab7ea7ac848f4e9380313fa2e759629ab15c Mon Sep 17 00:00:00 2001
From: Richard Osborne <richard@digitalbricks.io>
Date: Wed, 31 Dec 2025 21:40:47 +0100
Subject: [PATCH] Fixed visual issues with new dashboard and added folder
 attribution

---
 dev-docs/reference/CODEBASE-MAP.md            |   56 +
 dev-docs/reference/LEARNINGS.md               | 1434 +++--------------
 dev-docs/reference/UI-STYLING-GUIDE.md        |  134 +-
 .../CHANGELOG.md                              |  158 ++
 .../CHECKLIST.md                              |  224 +++
 .../NOTES.md                                  |  306 ++++
 .../README.md                                 |  786 +++++++++
 .../TASK-000I-A-visual-polish.md              |  472 ++++++
 .../TASK-000I-B-node-comments.md              |  786 +++++++++
 .../TASK-000I-C-port-organization.md          |  858 ++++++++++
 .../LegacyIconButton/LegacyIconButton.tsx     |   80 +-
 .../inputs/TextInput/TextInput.module.scss    |    4 +-
 .../ToggleSwitch/ToggleSwitch.module.scss     |   76 +-
 .../popups/MenuDialog/MenuDialog.module.scss  |  202 +--
 .../preview/launcher/Launcher/Launcher.tsx    |   21 +
 .../launcher/Launcher/LauncherContext.tsx     |    4 +
 .../FolderTree/FolderTree.module.scss         |  200 +++
 .../components/FolderTree/FolderTree.tsx      |  276 ++++
 .../Launcher/components/FolderTree/index.ts   |    2 +
 .../FolderTreeItem/FolderTreeItem.module.scss |   87 +
 .../FolderTreeItem/FolderTreeItem.tsx         |  148 ++
 .../components/FolderTreeItem/index.ts        |    2 +
 .../LauncherProjectCard.tsx                   |   29 +-
 .../components/TagPill/TagPill.module.scss    |   80 +
 .../Launcher/components/TagPill/TagPill.tsx   |   91 ++
 .../Launcher/components/TagPill/index.ts      |    2 +
 .../TagSelector/TagSelector.module.scss       |   35 +
 .../components/TagSelector/TagSelector.tsx    |  142 ++
 .../Launcher/components/TagSelector/index.ts  |    2 +
 .../Launcher/hooks/useProjectOrganization.ts  |  354 ++++
 .../launcher/Launcher/views/Projects.tsx      |  396 +++--
 .../src/pages/ProjectsPage/ProjectsPage.tsx   |   47 +-
 .../services/ProjectOrganizationService.ts    |  340 ++++
 .../src/editor/src/styles/componentspanel.css |   12 +-
 .../src/editor/src/styles/popuplayer.css      |    3 +-
 .../EditorTopbar/EditorTopbar.module.scss     |  223 +--
 .../NodeGraphComponentTrail.module.scss       |    2 +-
 .../NodePickerCategory/NodePickerCategory.tsx |   10 +-
 .../tabs/NodeLibrary/NodeLibrary.tsx          |    2 +-
 .../src/views/lessons/LessonLayerView.css     |    8 +-
 .../search-panel/search-panel.module.scss     |    6 +-
 41 files changed, 6481 insertions(+), 1619 deletions(-)
 create mode 100644 dev-docs/tasks/phase-3-editor-ux-overhaul/TASK-000-styles-overhaul/TASK-000I-node-graph-visual-improvements/CHANGELOG.md
 create mode 100644 dev-docs/tasks/phase-3-editor-ux-overhaul/TASK-000-styles-overhaul/TASK-000I-node-graph-visual-improvements/CHECKLIST.md
 create mode 100644 dev-docs/tasks/phase-3-editor-ux-overhaul/TASK-000-styles-overhaul/TASK-000I-node-graph-visual-improvements/NOTES.md
 create mode 100644 dev-docs/tasks/phase-3-editor-ux-overhaul/TASK-000-styles-overhaul/TASK-000I-node-graph-visual-improvements/README.md
 create mode 100644 dev-docs/tasks/phase-3-editor-ux-overhaul/TASK-000-styles-overhaul/TASK-000I-node-graph-visual-improvements/TASK-000I-A-visual-polish.md
 create mode 100644 dev-docs/tasks/phase-3-editor-ux-overhaul/TASK-000-styles-overhaul/TASK-000I-node-graph-visual-improvements/TASK-000I-B-node-comments.md
 create mode 100644 dev-docs/tasks/phase-3-editor-ux-overhaul/TASK-000-styles-overhaul/TASK-000I-node-graph-visual-improvements/TASK-000I-C-port-organization.md
 create mode 100644 packages/noodl-core-ui/src/preview/launcher/Launcher/components/FolderTree/FolderTree.module.scss
 create mode 100644 packages/noodl-core-ui/src/preview/launcher/Launcher/components/FolderTree/FolderTree.tsx
 create mode 100644 packages/noodl-core-ui/src/preview/launcher/Launcher/components/FolderTree/index.ts
 create mode 100644 packages/noodl-core-ui/src/preview/launcher/Launcher/components/FolderTreeItem/FolderTreeItem.module.scss
 create mode 100644 packages/noodl-core-ui/src/preview/launcher/Launcher/components/FolderTreeItem/FolderTreeItem.tsx
 create mode 100644 packages/noodl-core-ui/src/preview/launcher/Launcher/components/FolderTreeItem/index.ts
 create mode 100644 packages/noodl-core-ui/src/preview/launcher/Launcher/components/TagPill/TagPill.module.scss
 create mode 100644 packages/noodl-core-ui/src/preview/launcher/Launcher/components/TagPill/TagPill.tsx
 create mode 100644 packages/noodl-core-ui/src/preview/launcher/Launcher/components/TagPill/index.ts
 create mode 100644 packages/noodl-core-ui/src/preview/launcher/Launcher/components/TagSelector/TagSelector.module.scss
 create mode 100644 packages/noodl-core-ui/src/preview/launcher/Launcher/components/TagSelector/TagSelector.tsx
 create mode 100644 packages/noodl-core-ui/src/preview/launcher/Launcher/components/TagSelector/index.ts
 create mode 100644 packages/noodl-core-ui/src/preview/launcher/Launcher/hooks/useProjectOrganization.ts
 create mode 100644 packages/noodl-editor/src/editor/src/services/ProjectOrganizationService.ts

diff --git a/dev-docs/reference/CODEBASE-MAP.md b/dev-docs/reference/CODEBASE-MAP.md
index 260a52d..9132e44 100644
--- a/dev-docs/reference/CODEBASE-MAP.md
+++ b/dev-docs/reference/CODEBASE-MAP.md
@@ -169,9 +169,65 @@ packages/noodl-core-ui/src/
 │       ├── AiChatBox/
 │       └── AiChatMessage/
 │
+├── preview/                 # 📱 Preview/Launcher UI
+│   └── launcher/
+│       ├── Launcher.tsx         → Main launcher container
+│       ├── LauncherContext.tsx  → Shared state context
+│       │
+│       ├── components/      # Launcher-specific components
+│       │   ├── LauncherProjectCard/     → Project card display
+│       │   ├── FolderTree/              → Folder hierarchy UI
+│       │   ├── FolderTreeItem/          → Individual folder item
+│       │   ├── TagPill/                 → Tag display badge
+│       │   ├── TagSelector/             → Tag assignment UI
+│       │   ├── ProjectList/             → List view components
+│       │   ├── GitStatusBadge/          → Git status indicator
+│       │   └── ViewModeToggle/          → Card/List toggle
+│       │
+│       ├── hooks/           # Launcher hooks
+│       │   ├── useProjectOrganization.ts → Folder/tag management
+│       │   ├── useProjectList.ts         → Project list logic
+│       │   └── usePersistentTab.ts       → Tab state persistence
+│       │
+│       └── views/           # Launcher view pages
+│           ├── Projects.tsx      → Projects tab view
+│           └── Templates.tsx     → Templates tab view
+│
 └── styles/                  # 🎨 Global styles
+    └── custom-properties/
+        ├── colors.css       → Design tokens (colors)
+        ├── fonts.css        → Typography tokens
+        └── spacing.css      → Spacing tokens
 ```
 
+#### 🚀 Launcher/Projects Organization System (Phase 3)
+
+The Launcher includes a complete project organization system with folders and tags:
+
+**Key Components:**
+
+- **FolderTree**: Hierarchical folder display with expand/collapse
+- **TagPill**: Colored badge for displaying project tags (9 predefined colors)
+- **TagSelector**: Checkbox-based UI for assigning tags to projects
+- **useProjectOrganization**: Hook for folder/tag management (uses LocalStorage for Storybook compatibility)
+
+**Data Flow:**
+
+```
+ProjectOrganizationService (editor)
+    ↓ (via LauncherContext)
+useProjectOrganization hook
+    ↓
+FolderTree / TagPill / TagSelector components
+```
+
+**Storage:**
+
+- Projects identified by `localPath` (stable across renames)
+- Folders: hierarchical structure with parent/child relationships
+- Tags: 9 predefined colors (#EF4444, #F97316, #EAB308, #22C55E, #06B6D4, #3B82F6, #8B5CF6, #EC4899, #6B7280)
+- Persisted via `ProjectOrganizationService` → LocalStorage (Storybook) or electron-store (production)
+
 ---
 
 ## 🔍 Finding Things
diff --git a/dev-docs/reference/LEARNINGS.md b/dev-docs/reference/LEARNINGS.md
index 3c6aaac..242a406 100644
--- a/dev-docs/reference/LEARNINGS.md
+++ b/dev-docs/reference/LEARNINGS.md
@@ -4,1295 +4,337 @@ This document captures important discoveries and gotchas encountered during Open
 
 ---
 
-## 🚨 CRITICAL: React + EventDispatcher Incompatibility (Phase 0, Dec 2025)
+## 🔥 CRITICAL: Electron Blocks window.prompt() and window.confirm() (Dec 2025)
 
-### The Silent Killer: Direct `.on()` Subscriptions in React
+### The Silent Dialog: Native Dialogs Don't Work in Electron
 
-**Context**: Phase 0 Foundation Stabilization discovered a critical, silent failure mode that was blocking all React migration work.
+**Context**: Phase 3 TASK-001 Launcher - FolderTree component used `prompt()` and `confirm()` for folder creation/deletion. These worked in browser but silently failed in Electron, causing "Maximum update depth exceeded" React errors and no UI response.
 
-**The Problem**: EventDispatcher's `.on()` method **silently fails** when used directly in React components. Events are emitted, but React never receives them. No errors, no warnings, just silence.
+**The Problem**: Electron blocks `window.prompt()` and `window.confirm()` for security reasons. Calling these functions throws an error: `"prompt() is and will not be supported"`.
 
-**Root Cause**: Fundamental incompatibility between:
+**Root Cause**: Electron's sandboxed renderer process doesn't allow synchronous native dialogs as they can hang the IPC bridge and create security vulnerabilities.
 
-- EventDispatcher's context-object-based cleanup pattern
-- React's closure-based lifecycle management
-
-**The Broken Pattern** (compiles and runs without errors):
+**The Broken Pattern**:
 
 ```typescript
-// ❌ THIS SILENTLY FAILS - DO NOT USE
-function MyComponent() {
-  useEffect(() => {
-    const context = {};
-    ProjectModel.instance.on('componentRenamed', handler, context);
-    return () => ProjectModel.instance.off(context); // Context reference doesn't match
-  }, []);
+// ❌ WRONG - Throws error in Electron
+const handleCreateFolder = () => {
+  const name = prompt('Enter folder name:'); // ☠️ Error: prompt() is not supported
+  if (name && name.trim()) {
+    createFolder(name.trim());
+  }
+};
 
-  // Events are emitted but NEVER received
-  // Hours of debugging later...
+const handleDeleteFolder = (folder: Folder) => {
+  if (confirm(`Delete "${folder.name}"?`)) {
+    // ☠️ Error: confirm() is not supported
+    deleteFolder(folder.id);
+  }
+};
+```
+
+**The Solution** - Use React state + inline input for text entry:
+
+```typescript
+// ✅ RIGHT - React state-based text input
+const [isCreatingFolder, setIsCreatingFolder] = useState(false);
+const [newFolderName, setNewFolderName] = useState('');
+
+const handleCreateFolder = () => {
+  setIsCreatingFolder(true);
+  setNewFolderName('');
+};
+
+const handleCreateFolderSubmit = () => {
+  if (newFolderName.trim()) {
+    createFolder(newFolderName.trim());
+  }
+  setIsCreatingFolder(false);
+};
+
+// JSX
+{
+  isCreatingFolder ? (
+    <input
+      type="text"
+      value={newFolderName}
+      onChange={(e) => setNewFolderName(e.target.value)}
+      onKeyDown={(e) => {
+        if (e.key === 'Enter') handleCreateFolderSubmit();
+        if (e.key === 'Escape') setIsCreatingFolder(false);
+      }}
+      onBlur={handleCreateFolderSubmit}
+      autoFocus
+    />
+  ) : (
+    <button onClick={handleCreateFolder}>New Folder</button>
+  );
 }
 ```
 
-**The Solution** - Always use `useEventListener` hook:
+**The Solution** - Use React state + custom dialog for confirmation:
 
 ```typescript
-// ✅ THIS WORKS - ALWAYS USE THIS
-import { useEventListener } from '@noodl-hooks/useEventListener';
+// ✅ RIGHT - React state-based confirmation dialog
+const [deletingFolder, setDeletingFolder] = useState<Folder | null>(null);
 
-function MyComponent() {
-  useEventListener(ProjectModel.instance, 'componentRenamed', (data) => {
-    // Events received correctly!
-  });
+const handleDeleteFolder = (folder: Folder) => {
+  setDeletingFolder(folder);
+};
+
+const handleDeleteFolderConfirm = () => {
+  if (deletingFolder) {
+    deleteFolder(deletingFolder.id);
+    setDeletingFolder(null);
+  }
+};
+
+// JSX - Overlay modal
+{
+  deletingFolder && (
+    <div className={css['DeleteConfirmation']}>
+      <div className={css['Backdrop']} onClick={() => setDeletingFolder(null)} />
+      <div className={css['Dialog']}>
+        <h3>Delete Folder</h3>
+        <p>Delete "{deletingFolder.name}"?</p>
+        <button onClick={() => setDeletingFolder(null)}>Cancel</button>
+        <button onClick={handleDeleteFolderConfirm}>Delete</button>
+      </div>
+    </div>
+  );
 }
 ```
 
 **Why This Matters**:
 
-- Wasted 10+ hours per React migration debugging this
-- Affects ALL EventDispatcher usage in React (ProjectModel, NodeLibrary, WarningsModel, etc.)
-- Silent failures are the worst kind of bug
+- Native dialogs work fine in browser testing (Storybook)
+- Same code fails silently or with cryptic errors in Electron
+- Can waste hours debugging what looks like unrelated React errors
+- Common pattern developers expect to work doesn't
 
-**Full Documentation**:
+**Secondary Issue**: The `prompt()` error triggered an infinite loop in `useProjectOrganization` hook because the service wasn't memoized, causing "Maximum update depth exceeded" errors that obscured the root cause.
 
-- Pattern Guide: `dev-docs/tasks/phase-0-foundation-stabalisation/TASK-011-react-event-pattern-guide/GOLDEN-PATTERN.md`
-- Investigation: `dev-docs/tasks/phase-0-foundation-stabalisation/TASK-008-eventdispatcher-react-investigation/`
-- Also in: `.clinerules` (Section: React + EventDispatcher Integration)
+**Critical Rules**:
 
-**Keywords**: EventDispatcher, React, useEventListener, silent failure, event subscription, Phase 0
+1. **Never use `window.prompt()` in Electron** - use inline text input with React state
+2. **Never use `window.confirm()` in Electron** - use custom modal dialogs
+3. **Never use `window.alert()` in Electron** - use toast notifications or modals
+4. **Always test Electron-specific code in the actual Electron app**, not just browser
 
----
+**Alternative Electron-Native Approach** (for main process):
 
-## React Hooks & EventDispatcher Integration (Dec 2025)
+```javascript
+// From main process - can use Electron's dialog
+const { dialog } = require('electron');
 
-### Problem: EventDispatcher Events Not Reaching React Hooks
+// Text input dialog (async)
+const result = await dialog.showMessageBox(mainWindow, {
+  type: 'question',
+  buttons: ['Cancel', 'OK'],
+  defaultId: 1,
+  title: 'Create Folder',
+  message: 'Enter folder name:',
+  // Note: No built-in text input, would need custom window
+});
 
-**Context**: During TASK-004B (ComponentsPanel React migration), discovered that `componentRenamed` events from ProjectModel weren't triggering UI updates in React components.
-
-**Root Cause**: Array reference instability causing useEffect to constantly re-subscribe/unsubscribe.
-
-**Discovery**:
-
-```typescript
-// ❌ BAD - Creates new array on every render
-useEventListener(
-  ProjectModel.instance,
-  ['componentAdded', 'componentRemoved', 'componentRenamed', 'rootNodeChanged'],
-  callback
-);
-
-// ✅ GOOD - Stable reference prevents re-subscription
-const PROJECT_EVENTS = ['componentAdded', 'componentRemoved', 'componentRenamed', 'rootNodeChanged'];
-useEventListener(ProjectModel.instance, PROJECT_EVENTS, callback);
+// Confirmation dialog (async)
+const result = await dialog.showMessageBox(mainWindow, {
+  type: 'question',
+  buttons: ['Cancel', 'Delete'],
+  defaultId: 0,
+  cancelId: 0,
+  title: 'Delete Folder',
+  message: `Delete "${folderName}"?`
+});
 ```
 
+**Detection**: If you see errors mentioning `prompt() is not supported` or similar, you're using blocked native dialogs.
+
 **Location**:
 
-- `packages/noodl-editor/src/editor/src/hooks/useEventListener.ts`
-- `packages/noodl-editor/src/editor/src/views/panels/ComponentsPanelNew/hooks/useComponentsPanel.ts`
-
-**Keywords**: EventDispatcher, React hooks, useEffect, event subscription, array reference, re-render
-
----
-
-## Hot Reload Issues with React Hooks (Dec 2025)
-
-**Context**: Code changes to React hooks not taking effect despite webpack hot reload.
-
-**Discovery**: React hooks sometimes require a **hard browser refresh** or **dev server restart** to pick up changes, especially:
-
-- Changes to `useEffect` dependencies
-- Changes to custom hooks
-- Changes to event subscription logic
-
-**Solution**:
-
-1. Try hard refresh first: `Cmd+Shift+R` (Mac) or `Ctrl+Shift+R` (Windows)
-2. If that fails, restart dev server: Stop (Ctrl+C) and `npm run dev`
-3. Clear browser cache if issues persist
-
-**Location**: Affects all React hook development
-
-**Keywords**: hot reload, React hooks, webpack, dev server, browser cache
-
----
-
-## Webpack 5 Persistent Caching Issues (Dec 2025)
-
-### Problem: Code Changes Not Loading Despite Dev Server Restart
-
-**Context**: During TASK-004B, discovered that TypeScript source file changes weren't appearing in the running Electron app, even after multiple `npm run dev` restarts and cache clearing attempts.
-
-**Root Cause**: Webpack 5 enables aggressive persistent caching by default:
-
-- **Primary cache**: `packages/noodl-editor/node_modules/.cache`
-- **Electron cache**: `~/Library/Application Support/Electron` (macOS)
-- **App cache**: `~/Library/Application Support/OpenNoodl` (macOS)
-
-**Discovery**: Standard cache clearing may not be sufficient. The caches can persist across:
-
-- Dev server restarts
-- Electron restarts
-- Multiple rapid development iterations
-
-**Solution**:
-
-```bash
-# Kill any running processes first
-killall node
-killall Electron
-
-# Clear all caches
-cd packages/noodl-editor
-rm -rf node_modules/.cache
-rm -rf ~/Library/Application\ Support/Electron
-rm -rf ~/Library/Application\ Support/OpenNoodl
-
-# Start fresh
-npm run dev
-```
-
-**Best Practice**: When debugging webpack/compilation issues, add module-level console.log markers at the TOP of your files to verify new code is loading:
-
-```typescript
-// At top of file
-console.log('🔥 MyModule.ts LOADED - Version 2.0');
-```
-
-If you don't see this marker in the console, your changes aren't loading - it's a cache/build issue, not a code issue.
-
-**Location**: Affects all webpack-compiled code in `packages/noodl-editor/`
-
-**Keywords**: webpack, cache, persistent caching, hot reload, dev server, Electron
-
----
-
-## React 19 useEffect with Array Dependencies (Dec 2025)
-
-### Problem: useEffect with Array Dependency Never Executes
-
-**Context**: During TASK-004B, discovered that passing an array as a single dependency to useEffect prevents the effect from ever running.
-
-**Root Cause**: React 19's `Object.is()` comparison for dependencies doesn't work correctly when an array is passed as a single dependency item.
-
-**Discovery**:
-
-```typescript
-// ❌ BROKEN - useEffect NEVER runs
-const eventNames = ['event1', 'event2', 'event3'];
-useEffect(() => {
-  console.log('This never prints!');
-}, [dispatcher, eventNames]); // eventNames is an array reference
-
-// ✅ CORRECT - Spread array into individual dependencies
-const eventNames = ['event1', 'event2', 'event3'];
-useEffect(() => {
-  console.log('This runs correctly');
-}, [dispatcher, ...eventNames]); // Spreads to: [dispatcher, 'event1', 'event2', 'event3']
-
-// ✅ ALSO CORRECT - Use stable array reference outside component
-const EVENT_NAMES = ['event1', 'event2', 'event3']; // Outside component
-
-function MyComponent() {
-  useEffect(() => {
-    // Works because EVENT_NAMES reference is stable
-  }, [dispatcher, ...EVENT_NAMES]);
-}
-```
-
-**Critical Rule**: **Never pass an array as a dependency to useEffect. Always spread it.**
-
-**Location**: Affects `useEventListener` hook and any custom hooks with array dependencies
-
-**Keywords**: React 19, useEffect, dependencies, array, Object.is, spread operator, hook lifecycle
-
----
-
-## 🔥 CRITICAL: Singleton Dependency Timing in useEffect (Dec 2025)
-
-### The Silent Subscriber: Missing Singleton Dependencies
-
-**Context**: Phase 0 completion - Final bug preventing EventDispatcher events from reaching React components.
-
-**The Problem**: Components that subscribe to singleton instances (like `ProjectModel.instance`) in useEffect often mount **before** the singleton is initialized. With an empty dependency array, the effect only runs once when the instance is `null/undefined`, and never re-runs when the instance is set.
-
-**Symptom**: Events are emitted, logs show event firing, but React components never receive them.
-
-**The Broken Pattern**:
-
-```typescript
-// ❌ WRONG - Subscribes before instance exists, never re-subscribes
-function MyComponent() {
-  useEffect(() => {
-    console.log('Setting up subscriptions');
-    if (!ProjectModel.instance) {
-      console.log('Instance is null'); // This prints
-      return;
-    }
-
-    ProjectModel.instance.on('event', handler, group);
-    // This NEVER executes because instance is null at mount
-    // and useEffect never runs again!
-  }, []); // Empty deps = only runs once at mount
-}
-```
-
-**Timeline of Failure**:
-
-1. Component mounts → useEffect runs
-2. `ProjectModel.instance` is `null` (project not loaded yet)
-3. Early return, no subscription
-4. Project loads → `ProjectModel.instance` gets set
-5. **useEffect doesn't re-run** (instance not in deps)
-6. Events fire but nobody's listening 🦗
-
-**The Solution**:
-
-```typescript
-// ✅ RIGHT - Re-subscribes when instance changes from null to defined
-function MyComponent() {
-  useEffect(() => {
-    console.log('Setting up subscriptions');
-    if (!ProjectModel.instance) {
-      console.log('Instance is null, will retry when available');
-      return;
-    }
-
-    const group = { id: 'mySubscription' };
-    ProjectModel.instance.on('event', handler, group);
-    console.log('Subscribed successfully!');
-
-    return () => {
-      if (ProjectModel.instance) {
-        ProjectModel.instance.off(group);
-      }
-    };
-  }, [ProjectModel.instance]); // RE-RUNS when instance changes!
-}
-```
-
-**Critical Rule**: **Always include singleton instances in useEffect dependencies if you're subscribing to them.**
-
-**Affected Singletons**:
-
-- `ProjectModel.instance`
-- `NodeLibrary.instance`
-- `WarningsModel.instance`
-- `EventDispatcher.instance`
-- `UndoQueue.instance`
-
-**Location**:
-
-- `packages/noodl-editor/src/editor/src/views/panels/ComponentsPanelNew/hooks/useComponentsPanel.ts` (line 76)
-- Any React component using EventDispatcher with singleton instances
-
-**Keywords**: singleton, useEffect, dependencies, timing, ProjectModel, EventDispatcher, subscription, React lifecycle
-
----
-
-## 🔥 CRITICAL: UndoActionGroup.do() Silent Failure (Dec 2025)
-
-### The Invisible Bug: Actions That Don't Execute
-
-**Context**: Phase 0 completion - Discovered why `ProjectModel.renameComponent()` was never being called despite the undo system reporting success.
-
-**The Problem**: `UndoActionGroup.push()` followed by `undoGroup.do()` **silently fails to execute** due to an internal pointer bug. The action is recorded for undo/redo, but never actually executes.
-
-**Root Cause**: `UndoActionGroup` maintains an internal `ptr` (pointer) that tracks which actions have been executed:
-
-- `push()` increments `ptr` to `actions.length`
-- `do()` loops from `ptr` to `actions.length`
-- But if `ptr === actions.length`, the loop never runs!
-
-**The Broken Pattern**:
-
-```typescript
-// ❌ WRONG - Action recorded but NEVER executes
-const undoGroup = new UndoActionGroup({
-  label: 'Rename component'
-});
-
-UndoQueue.instance.push(undoGroup);
-
-undoGroup.push({
-  do: () => {
-    ProjectModel.instance.renameComponent(component, newName);
-    // ☠️ THIS NEVER RUNS ☠️
-  },
-  undo: () => {
-    ProjectModel.instance.renameComponent(component, oldName);
-  }
-});
-
-undoGroup.do(); // Loop condition is already false (ptr === actions.length)
-
-// Result:
-// - Returns true ✅
-// - Undo/redo works ✅
-// - But initial action NEVER executes ❌
-```
-
-**Why It's Dangerous**:
-
-- No errors or warnings
-- Returns success
-- Undo/redo actually works (if you manually trigger the action first)
-- Can waste hours debugging because everything "looks correct"
-
-**The Solution**:
-
-```typescript
-// ✅ RIGHT - Use pushAndDo pattern (action in constructor)
-UndoQueue.instance.pushAndDo(
-  new UndoActionGroup({
-    label: 'Rename component',
-    do: () => {
-      ProjectModel.instance.renameComponent(component, newName);
-    },
-    undo: () => {
-      ProjectModel.instance.renameComponent(component, oldName);
-    }
-  })
-);
-
-// This works because:
-// 1. Action added in constructor (ptr still 0)
-// 2. pushAndDo() calls do() which loops from 0 to 1
-// 3. Action executes! 🎉
-```
-
-**Alternative Pattern** (if you need to build complex undo groups):
-
-```typescript
-// ✅ ALSO RIGHT - Use pushAndDo on individual actions
-const undoGroup = new UndoActionGroup({ label: 'Complex operation' });
-UndoQueue.instance.push(undoGroup);
-
-undoGroup.pushAndDo({
-  // Note: pushAndDo, not push!
-  do: () => {
-    /* first action */
-  },
-  undo: () => {
-    /* undo first */
-  }
-});
-
-undoGroup.pushAndDo({
-  // Note: pushAndDo, not push!
-  do: () => {
-    /* second action */
-  },
-  undo: () => {
-    /* undo second */
-  }
-});
-```
-
-**Critical Rule**: **Never use `undoGroup.push()` + `undoGroup.do()`. Always use `UndoQueue.instance.pushAndDo()` or `undoGroup.pushAndDo()`.**
-
-**Code Evidence** (from `undo-queue-model.ts` lines 108-115):
-
-```typescript
-do() {
-  for (var i = this.ptr; i < this.actions.length; i++) {
-    // If ptr === actions.length, this loop never runs!
-    var a = this.actions[i];
-    a.do && a.do();
-  }
-  this.ptr = this.actions.length;
-}
-```
-
-**Location**:
-
-- `packages/noodl-editor/src/editor/src/models/undo-queue-model.ts`
-- Fixed in: `packages/noodl-editor/src/editor/src/views/panels/ComponentsPanelNew/hooks/useComponentActions.ts` (line 174)
-
-**Detection**: Add debug logging to your action's `do()` function. If it never prints, you have this bug.
-
-**Keywords**: UndoQueue, UndoActionGroup, silent failure, do, push, pushAndDo, undo, redo, pointer bug
-
----
-
-## PopupLayer API Confusion: showPopup vs showPopout (Dec 2025)
-
-### The Invisible Menu: Wrong API, Silent Failure
-
-**Context**: TASK-008 ComponentsPanel menus - Plus button menu logged "Popup shown successfully" but nothing appeared on screen.
-
-**The Problem**: PopupLayer has **two different methods** for displaying overlays, each with different parameters and behaviors. Using the wrong one causes silent failures where the popup/popout doesn't appear, but no error is thrown.
-
-**Root Cause**: API confusion between modals and attached menus.
-
-**The Two APIs**:
-
-```typescript
-// 1. showPopup() - For centered modals/dialogs
-PopupLayer.instance.showPopup({
-  content: popupObject, // Direct object reference
-  position: 'screen-center', // Only supports 'screen-center'
-  isBackgroundDimmed: true // Optional: dims background for modals
-});
-
-// 2. showPopout() - For attached dropdowns/menus
-PopupLayer.instance.showPopout({
-  content: { el: jQueryElement }, // Must wrap in { el: ... }
-  attachTo: $(element), // jQuery element to attach to
-  position: 'bottom', // Supports 'bottom'|'top'|'left'|'right'
-  arrowColor: '313131' // Optional: arrow indicator color
-});
-```
-
-**The Broken Pattern**:
-
-```typescript
-// ❌ WRONG - showPopup doesn't support position: 'bottom'
-const menu = new PopupMenu({ items, owner: PopupLayer.instance });
-menu.render();
-
-PopupLayer.instance.showPopup({
-  content: menu,
-  attachTo: $(buttonRef.current),
-  position: 'bottom' // showPopup ignores this!
-});
-// Logs success, but menu never appears
-```
-
-**The Solution**:
-
-```typescript
-// ✅ RIGHT - showPopout for attached menus
-const menu = new PopupMenu({ items, owner: PopupLayer.instance });
-menu.render();
-
-PopupLayer.instance.showPopout({
-  content: { el: menu.el }, // Wrap in { el: ... }
-  attachTo: $(buttonRef.current),
-  position: 'bottom'
-});
-// Menu appears below button with arrow indicator!
-```
-
-**Rule of Thumb**:
-
-- **Use `showPopup()`** for:
-  - Modal dialogs (confirmation, input, etc.)
-  - Centered popups
-  - When you need `isBackgroundDimmed`
-- **Use `showPopout()`** for:
-  - Dropdown menus
-  - Context menus
-  - Tooltips
-  - Anything attached to a specific element
-
-**Common Gotchas**:
-
-1. **Content format differs**:
-
-   - `showPopup()` takes direct object: `content: popup`
-   - `showPopout()` requires wrapper: `content: { el: popup.el }`
-
-2. **Position values differ**:
-
-   - `showPopup()` only supports `'screen-center'`
-   - `showPopout()` supports `'bottom'|'top'|'left'|'right'`
-
-3. **No error on wrong usage** - silent failure is the symptom
-
-**Location**:
-
-- Type definitions: `packages/noodl-editor/src/editor/src/views/popuplayer.d.ts`
-- Fixed in: `packages/noodl-editor/src/editor/src/views/panels/ComponentsPanelNew/ComponentsPanelReact.tsx` (line 157)
+- Fixed in: `packages/noodl-core-ui/src/preview/launcher/Launcher/components/FolderTree/FolderTree.tsx`
+- Fixed in: `packages/noodl-core-ui/src/preview/launcher/Launcher/hooks/useProjectOrganization.ts` (infinite loop fix)
+- Task: Phase 3 TASK-001 Dashboard UX Foundation
 
 **Related Issues**:
 
-- **Template popup visibility**: Also needed `isBackgroundDimmed: true` flag to make modal properly visible with dimmed background
+- **Infinite loop in useProjectOrganization**: Service object was recreated on every render, causing useEffect to run infinitely. Fixed by wrapping service creation in `useMemo(() => createLocalStorageService(), [])`.
 
-**Detection**: If popup/popout logs success but doesn't appear, check:
-
-1. Are you using the right API method?
-2. Is the content format correct for that API?
-3. Is the position value supported by that API?
-
-**Keywords**: PopupLayer, showPopup, showPopout, menu, dropdown, modal, position, silent failure, UI
+**Keywords**: Electron, window.prompt, window.confirm, window.alert, native dialogs, security, renderer process, React state, modal, confirmation dialog, infinite loop, Maximum update depth
 
 ---
 
-## 🔥 CRITICAL: React Button Clicks vs Cursor-Based Menu Positioning (Dec 2025)
+[Previous learnings content continues...]
 
-### The Button Click Nightmare: When Menus Just Won't Work
+## 🎨 Design Token Consolidation Side Effects (Dec 31, 2025)
 
-**Context**: TASK-008 ComponentsPanel menus - Spent hours trying to show a dropdown menu from a plus button click. Multiple approaches all failed in different spectacular ways.
+### The White-on-White Epidemic: When --theme-color-secondary Changed
 
-**The Problem**: `showContextMenuInPopup()` utility (which works perfectly for right-click context menus) **completely fails** when triggered from a button click event. The fundamental issue is that this utility uses `screen.getCursorScreenPoint()` for positioning, which gives you the cursor position at the _moment the function runs_, not where the button is located.
+**Context**: Phase 3 UX Overhaul - Design token consolidation (TASK-000A) changed `--theme-color-secondary` from teal (#00CEC9) to white (#ffffff). This broke selected/active states across the entire editor UI.
 
-**Timeline of Failed Attempts**:
+**The Problem**: Dozens of components used `--theme-color-secondary` and `--theme-color-secondary-highlight` as background colors for selected items. When these tokens changed to white, selected items became invisible white-on-white.
 
-1. **Attempt 1: showContextMenuInPopup() from button click**
+**Affected Components**:
 
-   - **Result**: Silent failure - no menu appears, no errors
-   - **Why**: Uses `screen.getCursorScreenPoint()` which gives cursor position after the click moved away from the button
-   - **Duration**: 1+ hours debugging
+- MenuDialog dropdowns (viewport, URL routes, zoom level)
+- Component breadcrumb trail (current page indicator)
+- Search panel results (active result)
+- Components panel (selected components)
+- Lesson layer (selected lessons)
+- All legacy CSS files using hardcoded teal colors
 
-2. **Attempt 2: PopupLayer.showPopout() with button ref**
+**Root Cause**: Token meaning changed during consolidation:
 
-   - **Result**: Silent failures despite "success" logs
-   - **Why**: Content format issues, API confusion
-   - **Duration**: 1+ hours debugging
+- **Before**: `--theme-color-secondary` = teal accent color (good for backgrounds)
+- **After**: `--theme-color-secondary` = white/neutral (terrible for backgrounds)
 
-3. **Attempt 3: NewPopupLayer.PopupMenu constructor**
+**The Solution Pattern**:
 
-   - **Result**: Runtime error "NewPopupLayer.PopupMenu is not a constructor"
-   - **Why**: PopupMenu not properly exported/accessible
-   - **Duration**: 30 minutes debugging
+```scss
+// ❌ BROKEN (post-consolidation)
+.is-selected {
+  background-color: var(--theme-color-secondary); // Now white!
+  color: var(--theme-color-on-secondary); // Also problematic
+}
 
-4. **Attempt 4: Got PopupMenu to render after fixing imports**
+// ✅ FIXED - Subtle highlight
+.is-current {
+  background-color: var(--theme-color-bg-4); // Dark gray
+  color: var(--theme-color-fg-highlight); // White text
+}
 
-   - **Result**: Menu appeared, but click handlers didn't fire
-   - **Why**: Event delegation issues in legacy jQuery code
-   - **Duration**: 1+ hours debugging, multiple cache clears
-
-5. **Pragmatic Solution: Remove button, use right-click on empty space**
-   - **Result**: Works perfectly using proven showContextMenuInPopup() pattern
-   - **Why**: Right-click naturally provides cursor position for menu positioning
-
-**The Core Issue**: React + Electron menu positioning from button clicks is fundamentally problematic:
-
-```typescript
-// ❌ FAILS - Cursor has moved away from button by the time this runs
-const handleButtonClick = (e: React.MouseEvent<HTMLButtonElement>) => {
-  showContextMenuInPopup({
-    items: menuItems,
-    width: MenuDialogWidth.Default
-  });
-  // Internally calls screen.getCursorScreenPoint()
-  // But cursor is no longer over the button!
-  // Menu appears at random location or not at all
-};
-
-// ✅ WORKS - Cursor is naturally at right position
-const handleRightClick = (e: React.MouseEvent) => {
-  e.preventDefault();
-  showContextMenuInPopup({
-    items: menuItems,
-    width: MenuDialogWidth.Default
-  });
-  // Cursor is exactly where user right-clicked
-  // Menu appears at correct location
-};
+// ✅ FIXED - Bold accent (for dropdowns/menus)
+.is-selected {
+  background-color: var(--theme-color-primary); // Noodl red
+  color: var(--theme-color-on-primary); // White text
+}
 ```
 
-**Why Button Clicks Fail**:
+**Decision Matrix**: Use different backgrounds based on emphasis level:
 
-1. User clicks button
-2. React synthetic event fires
-3. Event propagates through React and into Electron
-4. By the time `showContextMenuInPopup()` runs, cursor has moved
-5. `screen.getCursorScreenPoint()` gives wrong position
-6. Menu either doesn't appear or appears in wrong location
+- **Subtle**: `--theme-color-bg-4` (dark gray) - breadcrumbs, sidebar
+- **Medium**: `--theme-color-bg-5` (lighter gray) - hover states
+- **Bold**: `--theme-color-primary` (red) - dropdown selected items
 
-**Why Right-Click Works**:
+**Files Fixed** (Dec 31, 2025):
 
-1. User right-clicks
-2. Context menu event fires
-3. Cursor is still exactly where user clicked
-4. `screen.getCursorScreenPoint()` gives correct position
-5. Menu appears at cursor location (expected UX)
+- `MenuDialog.module.scss` - Dropdown selected items
+- `NodeGraphComponentTrail.module.scss` - Breadcrumb current page
+- `search-panel.module.scss` - Active search result
+- `componentspanel.css` - Selected components
+- `LessonLayerView.css` - Selected lessons
+- `EditorTopbar.module.scss` - Static display colors
+- `ToggleSwitch.module.scss` - Track visibility
+- `popuplayer.css` - Modal triangle color
 
-**The Working Pattern**:
+**Prevention**: New section added to `UI-STYLING-GUIDE.md` (Part 9: Selected/Active State Patterns) documenting the correct approach.
 
-```typescript
-// In ComponentsPanelReact.tsx
-const handleTreeContextMenu = useCallback(
-  (e: React.MouseEvent) => {
-    e.preventDefault();
-    e.stopPropagation();
+**Critical Rule**: **Never use `--theme-color-secondary` or `--theme-color-fg-highlight` as backgrounds. Always use `--theme-color-bg-*` for backgrounds and `--theme-color-primary` for accent highlights.**
 
-    const templates = ComponentTemplates.instance.getTemplates({
-      forRuntimeType: 'browser'
-    });
-
-    const items: TSFixme[] = templates.map((template) => ({
-      icon: template.icon,
-      label: `Create ${template.label}`,
-      onClick: () => handleAddComponent(template)
-    }));
-
-    items.push({
-      icon: IconName.FolderClosed,
-      label: 'Create Folder',
-      onClick: () => handleAddFolder()
-    });
-
-    showContextMenuInPopup({
-      items,
-      width: MenuDialogWidth.Default
-    });
-  },
-  [handleAddComponent, handleAddFolder]
-);
-
-// Attach to tree container for empty space clicks
-<div className={css['Tree']} onContextMenu={handleTreeContextMenu}>
-```
-
-**PopupMenu Constructor Issues**:
-
-When trying direct PopupMenu usage, encountered:
-
-```typescript
-// ❌ FAILS - "PopupMenu is not a constructor"
-import NewPopupLayer from '../popuplayer/popuplayer';
-
-const menu = new NewPopupLayer.PopupMenu({ items });
-
-// Even after fixing imports, menu rendered but clicks didn't work
-// Legacy jQuery event delegation issues in React context
-```
-
-**Critical Lessons**:
-
-1. **Never use button clicks to trigger showContextMenuInPopup()** - cursor positioning will be wrong
-2. **Right-click context menus are reliable** - cursor position is naturally correct
-3. **Legacy PopupLayer/PopupMenu integration with React is fragile** - avoid if possible
-4. **When something fails repeatedly with the same pattern, change the approach** - "this is the renaming task all over again"
-5. **Pragmatic UX is better than broken UX** - right-click on empty space works fine
-
-**UX Implications**:
-
-- Plus buttons for dropdown menus are problematic in Electron
-- Right-click context menus are more reliable
-- Users can right-click on components, folders, or empty space to access create menu
-- This pattern is actually more discoverable (common in native apps)
+**Time Lost**: 2+ hours debugging across multiple UI components
 
 **Location**:
 
-- Fixed in: `packages/noodl-editor/src/editor/src/views/panels/ComponentsPanelNew/ComponentsPanelReact.tsx`
-- Utility: `packages/noodl-editor/src/editor/src/views/ShowContextMenuInPopup.tsx`
-- Task: `dev-docs/tasks/phase-2/TASK-008-componentspanel-menus-and-sheets/`
+- Fixed files: See list above
+- Documentation: `dev-docs/reference/UI-STYLING-GUIDE.md` (Part 9)
+- Token definitions: `packages/noodl-core-ui/src/styles/custom-properties/colors.css`
 
-**References**:
-
-- ComponentItem.tsx - working right-click context menu example
-- FolderItem.tsx - working right-click context menu example
-
-**Detection**: If showContextMenuInPopup() works from right-click but not from button click, you have this issue.
-
-**Keywords**: showContextMenuInPopup, cursor position, button click, right-click, context menu, Electron, React, PopupMenu, menu positioning, UX
+**Keywords**: design tokens, --theme-color-secondary, white-on-white, selected state, active state, MenuDialog, consolidation, contrast, accessibility
 
 ---
 
-## 🔥 CRITICAL: Mutable Data Sources + React useMemo (Dec 2025)
+## 🎨 CSS Variable Naming Mismatch: --theme-spacing-_ vs --spacing-_ (Dec 31, 2025)
 
-### Problem: useMemo Not Recalculating Despite Dependency Change
+### The Invisible UI: When Padding Doesn't Exist
 
-**Context**: TASK-008 Sheet creation - New sheets weren't appearing in dropdown despite event received and updateCounter state changing.
+**Context**: Phase 3 TASK-001 Launcher - Folder tree components had proper padding styles defined but rendered with zero spacing. All padding/margin values appeared to be 0px despite correct-looking SCSS code.
 
-**Root Cause**: `ProjectModel.getComponents()` returns the **same array reference** each time. When a component is added, the array is mutated (push) rather than replaced. React's `Object.is()` comparison sees the same reference and skips recalculation.
+**The Problem**: SCSS files referenced `var(--theme-spacing-2)` but the CSS custom properties file defined `--spacing-2` (without the `theme-` prefix). This mismatch caused all spacing values to resolve to undefined/0px.
+
+**Root Cause**: Inconsistent variable naming between:
+
+- **SCSS files**: Used `var(--theme-spacing-1)`, `var(--theme-spacing-2)`, etc.
+- **CSS definitions**: Defined `--spacing-1: 4px`, `--spacing-2: 8px`, etc. (no `theme-` prefix)
 
 **The Broken Pattern**:
 
-```typescript
-// ❌ WRONG - Same array reference, useMemo skips recalculation
-const rawComponents = useMemo(() => {
-  if (!ProjectModel.instance) return [];
-  return ProjectModel.instance.getComponents(); // Returns same mutated array
-}, [updateCounter]); // Even when updateCounter changes!
+```scss
+// ❌ WRONG - Variable doesn't exist
+.FolderTree {
+  padding: var(--theme-spacing-2); // Resolves to nothing!
+  gap: var(--theme-spacing-1); // Also undefined
+}
 
-// Dependent memos never run because rawComponents reference is unchanged
-const sheets = useMemo(() => {
-  // This never executes after component added
-}, [rawComponents]);
+.Button {
+  padding: var(--theme-spacing-2) var(--theme-spacing-3); // Both 0px
+}
 ```
 
-**The Solution**:
+**The Correct Pattern**:
 
-```typescript
-// ✅ RIGHT - Spread creates new array reference, forces recalculation
-const rawComponents = useMemo(() => {
-  if (!ProjectModel.instance) return [];
-  return [...ProjectModel.instance.getComponents()]; // New reference!
-}, [updateCounter]);
+```scss
+// ✅ RIGHT - Matches defined variables
+.FolderTree {
+  padding: var(--spacing-2); // = 8px ✓
+  gap: var(--spacing-1); // = 4px ✓
+}
+
+.Button {
+  padding: var(--spacing-2) var(--spacing-3); // = 8px 12px ✓
+}
 ```
 
-**Why This Happens**:
+**How to Detect**:
 
-1. `getComponents()` returns the internal array (same reference)
-2. When component is added, array is mutated with `push()`
-3. `Object.is(oldArray, newArray)` returns `true` (same reference)
-4. useMemo thinks nothing changed, skips recalculation
-5. Spreading `[...array]` creates new reference → forces recalculation
+1. **Visual inspection**: Everything looks squished with no breathing room
+2. **DevTools**: Computed padding/margin values show 0px or nothing
+3. **Code search**: `grep -r "var(--theme-spacing" packages/` finds non-existent variables
+4. **Compare working components**: Other components use `var(--spacing-*)` without `theme-` prefix
 
-**Critical Rule**: When consuming mutable data sources (EventDispatcher models, etc.) in useMemo, **always spread arrays** to create new references.
+**What Makes This Confusing**:
 
-**Affected Patterns**:
+- **Color variables DO use `theme-` prefix**: `var(--theme-color-bg-2)` exists and works
+- **Font variables DO use `theme-` prefix**: `var(--theme-font-size-default)` exists and works
+- **Spacing variables DON'T use `theme-` prefix**: Only `var(--spacing-2)` works, not `var(--theme-spacing-2)`
+- **Radius variables DON'T use prefix**: Just `var(--radius-default)`, not `var(--theme-radius-default)`
 
-- `ProjectModel.instance.getComponents()`
-- Any `Model.getX()` that returns internal arrays
-- Collections that mutate rather than replace
+**Correct Variable Patterns**:
+| Category | Pattern | Example |
+|----------|---------|---------|
+| Colors | `--theme-color-*` | `var(--theme-color-bg-2)` |
+| Fonts | `--theme-font-*` | `var(--theme-font-size-default)` |
+| Spacing | `--spacing-*` | `var(--spacing-2)` |
+| Radius | `--radius-*` | `var(--radius-default)` |
+| Shadows | `--shadow-*` | `var(--shadow-lg)` |
 
-**Location**: `packages/noodl-editor/src/editor/src/views/panels/ComponentsPanelNew/hooks/useComponentsPanel.ts`
+**Files Fixed** (Dec 31, 2025):
 
-**Keywords**: useMemo, array reference, Object.is, mutable data, spread operator, React, recalculation, EventDispatcher
+- `FolderTree/FolderTree.module.scss` - All spacing variables corrected
+- `FolderTreeItem/FolderTreeItem.module.scss` - All spacing variables corrected
 
----
+**Verification Command**:
 
-## 🔥 CRITICAL: HTML5 DnD vs Mouse-Based Dragging - onDrop Never Fires (Dec 2025)
+```bash
+# Find incorrect usage of --theme-spacing-*
+grep -r "var(--theme-spacing" packages/noodl-core-ui/src --include="*.scss"
 
-### The Silent Drop: When onDrop Never Triggers
-
-**Context**: TASK-008C ComponentsPanel drag-drop system - All drop handlers existed and appeared correct, but drops never completed. Items would snap back to origin.
-
-**The Problem**: The drag-drop implementation used `onDrop` React event handlers, but the underlying PopupLayer drag system uses **mouse-based dragging**, not **HTML5 Drag-and-Drop API**. The HTML5 `onDrop` event **never fires** for mouse-based drag systems.
-
-**Root Cause**: Fundamental API mismatch between the drag initiation system and drop detection.
-
-**The Two Drag Systems**:
-
-1. **HTML5 Drag-and-Drop API**:
-
-   - Uses `draggable="true"` attribute
-   - Events: `ondragstart`, `ondragenter`, `ondragover`, `ondragleave`, `ondrop`
-   - Native browser implementation with built-in ghost image
-   - `onDrop` fires when dropping a dragged element
-
-2. **Mouse-Based Dragging (PopupLayer)**:
-   - Uses `onMouseDown`, `onMouseMove`, `onMouseUp`
-   - Custom implementation that moves a label element with cursor
-   - `onDrop` **never fires** - must use `onMouseUp` to detect drop
-
-**The Broken Pattern**:
-
-```typescript
-// ❌ WRONG - onDrop never fires for PopupLayer drag system
-const handleDrop = useCallback(() => {
-  if (isDropTarget && onDrop) {
-    const node: TreeNode = { type: 'component', data: component };
-    onDrop(node);  // Never reached!
-    setIsDropTarget(false);
-  }
-}, [isDropTarget, component, onDrop]);
-
-// JSX
-<div
-  onMouseEnter={handleMouseEnter}  // ✅ Works - sets isDropTarget
-  onMouseLeave={handleMouseLeave}  // ✅ Works - clears isDropTarget
-  onDrop={handleDrop}              // ❌ NEVER FIRES
->
+# Should return zero results after fix
 ```
 
-**The Solution**:
+**Prevention**: Always reference `dev-docs/reference/UI-STYLING-GUIDE.md` which documents the correct variable patterns. Use existing working components as templates.
 
-```typescript
-// ✅ RIGHT - Use onMouseUp to trigger drop
-const handleMouseUp = useCallback(
-  (e: React.MouseEvent) => {
-    dragStartPos.current = null;
+**Critical Rule**: **Spacing variables are `--spacing-*` NOT `--theme-spacing-*`. When in doubt, check `packages/noodl-core-ui/src/styles/custom-properties/spacing.css` for the actual defined variables.**
 
-    // If this item is a valid drop target, execute the drop
-    if (isDropTarget && onDrop) {
-      e.stopPropagation(); // Prevent bubble to parent
-      const node: TreeNode = { type: 'component', data: component };
-      onDrop(node);
-      setIsDropTarget(false);
-    }
-  },
-  [isDropTarget, component, onDrop]
-);
-
-// JSX
-<div
-  onMouseEnter={handleMouseEnter}  // ✅ Sets isDropTarget
-  onMouseLeave={handleMouseLeave}  // ✅ Clears isDropTarget
-  onMouseUp={handleMouseUp}        // ✅ Triggers drop when isDropTarget
->
-```
-
-**Why This Works**:
-
-1. User starts drag via `onMouseDown` + `onMouseMove` (5px threshold) → `PopupLayer.startDragging()`
-2. User hovers over target → `onMouseEnter` sets `isDropTarget = true`
-3. User releases mouse → `onMouseUp` checks `isDropTarget` and executes drop
-4. `e.stopPropagation()` prevents event bubbling to parent containers
-
-**Root Drop Zone Pattern**:
-
-For dropping onto empty space (background), use event bubbling:
-
-```typescript
-// In parent container
-const handleTreeMouseUp = useCallback(() => {
-  const PopupLayer = require('@noodl-views/popuplayer');
-
-  // If we're dragging and no specific item claimed the drop, it's a root drop
-  if (draggedItem && PopupLayer.instance.isDragging()) {
-    handleDropOnRoot(draggedItem);
-  }
-}, [draggedItem, handleDropOnRoot]);
-
-// JSX
-<div className={css['Tree']} onMouseUp={handleTreeMouseUp}>
-  {/* Tree items call e.stopPropagation() on valid drops */}
-  {/* If no item stops propagation, this handler catches it */}
-</div>;
-```
-
-**Critical Rule**: **If using PopupLayer's drag system, always use `onMouseUp` for drop detection, never `onDrop`.**
-
-**Detection**: If drops appear to work (visual feedback shows) but never complete (items snap back), check if you're using `onDrop` instead of `onMouseUp`.
+**Time Lost**: 30 minutes investigating "missing styles" before discovering the variable mismatch
 
 **Location**:
 
-- Fixed in: `packages/noodl-editor/src/editor/src/views/panels/ComponentsPanelNew/components/ComponentItem.tsx`
-- Fixed in: `packages/noodl-editor/src/editor/src/views/panels/ComponentsPanelNew/components/FolderItem.tsx`
-- Fixed in: `packages/noodl-editor/src/editor/src/views/panels/ComponentsPanelNew/ComponentsPanelReact.tsx`
-- Task: `dev-docs/tasks/phase-2/TASK-008-componentspanel-menus-and-sheets/TASK-008C-drag-drop-system.md`
+- Fixed files: `FolderTree.module.scss`, `FolderTreeItem.module.scss`
+- Variable definitions: `packages/noodl-core-ui/src/styles/custom-properties/spacing.css`
+- Documentation: `dev-docs/reference/UI-STYLING-GUIDE.md`
 
-**Keywords**: onDrop, onMouseUp, HTML5 DnD, drag-and-drop, PopupLayer, mouse events, drop handler, snap back
+**Keywords**: CSS variables, custom properties, --spacing, --theme-spacing, zero padding, invisible UI, variable mismatch, design tokens, spacing scale
 
 ---
 
-## 🔥 CRITICAL: Runtime Node Creation - The Unholy Trinity of Silent Failures (Dec 2025)
-
-### The HTTP Node Debugging Saga: 3+ Hours of Silent Failures
-
-**Context**: Creating an HTTP node (httpnode.js) as a modern, no-code-friendly alternative to the script-based REST node. Everything looked correct but nothing worked. Signals never fired, config values never set, and no errors anywhere.
-
-**The Problems Found** (each took significant debugging time):
-
-#### Problem 1: Signal Input Using `set` Instead of `valueChangedToTrue`
-
-```javascript
-// ❌ WHAT I WROTE (never triggers)
-inputs: {
-  fetch: {
-    type: 'signal',
-    set: function(value) {
-      this.scheduleFetch();  // ☠️ Never called
-    }
-  }
-}
-
-// ✅ WHAT IT SHOULD BE
-inputs: {
-  fetch: {
-    type: 'signal',
-    valueChangedToTrue: function() {
-      this.scheduleFetch();  // ✓ Works!
-    }
-  }
-}
-```
-
-**Why**: Signals use `EdgeTriggeredInput.createSetter()` which wraps the callback and only calls `valueChangedToTrue` when value transitions from falsy to truthy. The `set` callback is never used.
-
-#### Problem 2: Custom `setInputValue` Overriding Base Method
-
-```javascript
-// ❌ WHAT I WROTE (breaks ALL inputs including signals)
-prototypeExtensions: {
-  setInputValue: function(name, value) {
-    this._internal.inputValues[name] = value;  // ☠️ Overrides Node.prototype.setInputValue
-  }
-}
-
-// ✅ WHAT IT SHOULD BE
-prototypeExtensions: {
-  _storeInputValue: function(name, value) {  // Different name!
-    this._internal.inputValues[name] = value;
-  }
-}
-```
-
-**Why**: `prototypeExtensions` methods are merged into node prototype. Defining `setInputValue` completely replaces the base implementation, which handles signal detection, input.set() calls, and event emission.
-
-#### Problem 3: Dynamic Ports Replacing Static Ports
-
-```javascript
-// ❌ WHAT I WROTE (static ports disappear)
-function updatePorts(nodeId, parameters, editorConnection) {
-  const ports = [];
-  // Only add dynamic header/query param ports...
-  if (parameters.headers) { /* add header ports */ }
-  editorConnection.sendDynamicPorts(nodeId, ports);  // Static inputs GONE!
-}
-
-// ✅ WHAT IT SHOULD BE
-function updatePorts(nodeId, parameters, editorConnection) {
-  const ports = [
-    // Re-add ALL static inputs
-    { name: 'url', displayName: 'URL', type: 'string', plug: 'input', group: 'Request' },
-    { name: 'fetch', displayName: 'Fetch', type: 'signal', plug: 'input', group: 'Actions' },
-    { name: 'cancel', displayName: 'Cancel', type: 'signal', plug: 'input', group: 'Actions' },
-    // Then dynamic ports...
-  ];
-  editorConnection.sendDynamicPorts(nodeId, ports);
-}
-```
-
-**Why**: `sendDynamicPorts` REPLACES all ports, not merges. The `inputs` object in node definition is only for default setup - once dynamic ports are sent, they're the only ports.
-
-#### Problem 4: Config Inputs (StringList/Enum) Need Explicit Registration
-
-```javascript
-// ❌ MISSING (config values never reach setters)
-// StringList inputs like "headers", "queryParams" appear in editor but their
-// values never reach the node because there's no registered input handler
-
-// ✅ WHAT IT NEEDS
-registerInputIfNeeded: function(name) {
-  if (this.hasInput(name)) return;
-
-  const configSetters = {
-    'method': this.setMethod.bind(this),
-    'headers': this.setHeaders.bind(this),
-    'queryParams': this.setQueryParams.bind(this),
-    'bodyType': this.setBodyType.bind(this),
-    // ... all config inputs
-  };
-
-  if (configSetters[name]) {
-    return this.registerInput(name, { set: configSetters[name] });
-  }
-
-  // Dynamic inputs (header-X, query-Y, etc.)
-  if (name.startsWith('header-')) {
-    return this.registerInput(name, {
-      set: this._storeInputValue.bind(this, name)
-    });
-  }
-}
-```
-
-**Why**: Inputs defined in the `inputs` object get registered automatically. Dynamic ports don't - they need `registerInputIfNeeded` to create runtime handlers.
-
-**Why This Was So Hard to Debug**:
-
-1. **No errors** - Everything appeared to work, logs said "success", but nothing happened
-2. **Partial success** - Some things worked (node appeared in palette) making it seem close
-3. **Multiple bugs** - Each fix revealed the next bug, each taking time to diagnose
-4. **No TypeScript** - Runtime code is JS, no compile-time checking
-5. **Unfamiliar patterns** - `valueChangedToTrue`, `registerInputIfNeeded`, etc. aren't obvious
-
-**Time Lost**: 3+ hours debugging what should have been a straightforward node
-
-**Prevention**:
-
-- Created `dev-docs/reference/LEARNINGS-NODE-CREATION.md` with Critical Gotchas section
-- Added Node Creation Checklist to `.clinerules` Section 14
-- These gotchas are now documented with THE BUG / WHY IT BREAKS / THE FIX patterns
-
-**Location**:
-
-- `packages/noodl-runtime/src/nodes/std-library/data/httpnode.js` (fixed)
-- `dev-docs/reference/LEARNINGS-NODE-CREATION.md` (new documentation)
-
-**Keywords**: node creation, signal, valueChangedToTrue, setInputValue, prototypeExtensions, sendDynamicPorts, registerInputIfNeeded, stringlist, enum, config inputs, HTTP node, runtime
-
----
-
-## 🔥 CRITICAL: PopupLayer.dragCompleted() - Not endDrag() (Dec 2025)
-
-### Wrong Method Name Causes TypeError
-
-**Context**: TASK-008C ComponentsPanel drag-drop system - After fixing the onDrop→onMouseUp issue, drops still failed with a TypeError.
-
-**The Error**:
-
-```
-TypeError: PopupLayer.instance.endDrag is not a function
-```
-
-**The Problem**: Code was calling `PopupLayer.instance.endDrag()`, but this method **doesn't exist**. The correct method is `dragCompleted()`.
-
-**Root Cause**: Method name was guessed or hallucinated rather than verified against the actual PopupLayer source code.
-
-**The Broken Pattern**:
-
-```typescript
-// ❌ WRONG - endDrag() doesn't exist
-const handleDrop = () => {
-  // ... do drop operation
-  PopupLayer.instance.endDrag(); // TypeError!
-};
-```
-
-**The Solution**:
-
-```typescript
-// ✅ RIGHT - Use dragCompleted()
-const handleDrop = () => {
-  // ... do drop operation
-  PopupLayer.instance.dragCompleted(); // Works!
-};
-```
-
-**PopupLayer Drag API Reference** (from `popuplayer.js`):
-
-```javascript
-// Start drag with label that follows cursor
-PopupLayer.prototype.startDragging = function (args) {
-  // args: { label: string }
-  // Creates .popup-layer-dragger element
-};
-
-// Check if currently dragging
-PopupLayer.prototype.isDragging = function () {
-  return this.dragItem !== undefined;
-};
-
-// Show cursor feedback during drag
-PopupLayer.prototype.indicateDropType = function (droptype) {
-  // droptype: 'move' | 'copy' | 'none'
-};
-
-// ✅ CORRECT: Complete the drag operation
-PopupLayer.prototype.dragCompleted = function () {
-  this.$('.popup-layer-dragger').css({ opacity: '0' });
-  this.dragItem = undefined;
-};
-```
-
-**Critical Rule**: **Always verify method names against actual source code. Never guess or assume API method names.**
-
-**Why This Matters**:
-
-- Silent TypeErrors at runtime
-- Method names like `endDrag` vs `dragCompleted` are easy to confuse
-- Legacy JavaScript codebase has no TypeScript definitions to catch this
-
-**Detection**: If you get `X is not a function` error on PopupLayer, check `popuplayer.js` for the actual method name.
-
-**Location**:
-
-- PopupLayer source: `packages/noodl-editor/src/editor/src/views/popuplayer/popuplayer.js`
-- Fixed in: `packages/noodl-editor/src/editor/src/views/panels/ComponentsPanelNew/hooks/useComponentActions.ts`
-
-**Keywords**: PopupLayer, dragCompleted, endDrag, TypeError, drag-and-drop, method name, API
-
----
-
-## NoodlRuntime.instance.getMetaData() Pattern for Project Data (Dec 2025)
-
-### How Runtime Nodes Access Project Metadata
-
-**Context**: BYOB Query Data node needed to access backend services configuration (URLs, tokens, schema) from runtime code.
-
-**The Pattern**: Use `NoodlRuntime.instance.getMetaData(key)` to access project metadata stored in graphModel.
-
-**Working Example** (from byob-query-data.js):
-
-```javascript
-const NoodlRuntime = require('../../../../noodl-runtime');
-
-resolveBackend: function() {
-  // Get metadata - same pattern as cloudstore.js uses for cloudservices
-  const backendServices = NoodlRuntime.instance.getMetaData('backendServices');
-
-  if (!backendServices || !backendServices.backends) {
-    console.log('[BYOB Query Data] No backend services metadata found');
-    console.log('[BYOB Query Data] Available metadata keys:',
-                Object.keys(NoodlRuntime.instance.metadata || {}));
-    return null;
-  }
-
-  // Access the data
-  const backends = backendServices.backends || [];
-  const activeBackendId = backendServices.activeBackendId;
-
-  // Find and use the backend config...
-}
-```
-
-**Reference Implementation** (from `src/api/cloudstore.js`):
-
-```javascript
-const NoodlRuntime = require('../../noodl-runtime');
-
-// Access cloud services config
-const cloudServices = NoodlRuntime.instance.getMetaData('cloudservices');
-```
-
-**How It Works**:
-
-- `NoodlRuntime.prototype.getMetaData(key)` delegates to `this.graphModel.getMetaData(key)`
-- Metadata is stored in the project file and loaded into graphModel
-- Editor components set metadata via `graphModel.setMetaData(key, value)`
-
-**Available Metadata Keys** (varies by project):
-
-- `cloudservices` - Parse/Firebase cloud settings
-- `backendServices` - BYOB backend configurations
-- Project-specific settings
-
-**Location**:
-
-- NoodlRuntime API: `packages/noodl-runtime/noodl-runtime.js` (line 299)
-- Pattern reference: `packages/noodl-runtime/src/api/cloudstore.js`
-- BYOB usage: `packages/noodl-runtime/src/nodes/std-library/data/byob-query-data.js`
-
-**Keywords**: NoodlRuntime, getMetaData, project metadata, runtime, backend config, cloudservices
-
----
-
-## 🔴 Runtime Nodes Must Be in coreNodes Index (Dec 2025)
-
-### Problem: Node Module Loads But Doesn't Appear in Node Picker
-
-**Context**: TASK-002 BYOB Data Nodes - Created `byob-query-data.js`, registered in `register-nodes.js`, console showed "Module loaded" but node never appeared in Node Picker.
-
-**Root Cause**: Runtime nodes need to be registered in THREE places:
-
-1. ✅ Node file created (`noodl-runtime/src/nodes/std-library/data/byob-query-data.js`)
-2. ✅ Registered in `register-nodes.js` via `require()`
-3. ❌ **MISSING** - Added to `coreNodes` index in `nodelibraryexport.js`
-
-**The Hidden Requirement**:
-
-```javascript
-// In nodelibraryexport.js, the coreNodes array determines Node Picker organization
-const coreNodes = [
-  {
-    name: 'Read & Write Data',
-    subCategories: [
-      {
-        name: 'External Data',
-        items: ['net.noodl.HTTP', 'REST2'] // HTTP appears because it's HERE
-      }
-      // Node not in this array = not in Node Picker!
-    ]
-  }
-];
-```
-
-**The Fix**:
-
-```javascript
-// Add node to appropriate category in coreNodes
-{
-  name: 'BYOB Data',
-  items: ['noodl.byob.QueryData']  // Now appears in Node Picker!
-}
-```
-
-**Why This Is Easy to Miss**:
-
-- Module loads fine (console log appears)
-- No errors anywhere
-- Node IS registered in `nodeRegister._constructors`
-- Node IS in `nodetypes` array exported to editor
-- But Node Picker uses `coreNodes` index for organization
-
-**Critical Rule**: After creating a node, ALWAYS add it to `nodelibraryexport.js` coreNodes array.
-
-**Location**:
-
-- `packages/noodl-runtime/src/nodelibraryexport.js` (coreNodes array)
-- Documented in: `dev-docs/reference/LEARNINGS-NODE-CREATION.md` (Step 3)
-
-**Keywords**: node picker, coreNodes, nodelibraryexport, runtime node, silent failure, node not appearing
-
----
-
-## 🔥 CRITICAL: LocalProjectsModel.loadProject() Doesn't Navigate to Editor (Dec 2025)
-
-### The Silent Success: Projects Load But Don't Open
-
-**Context**: Phase 3 Launcher integration - Implemented all project management buttons (Open Project, Launch Project, Create Project). LocalProjectsModel.loadProject() succeeded and returned a ProjectModel, but the editor never opened.
-
-**The Problem**: `LocalProjectsModel.loadProject()` **only loads the project into memory**. It does NOT navigate to the editor. You must explicitly call the router after loading.
-
-**Discovery Timeline**:
-
-```
-🔵 [handleOpenProject] Starting...
-🔵 [handleOpenProject] Selected folder: /Users/.../MAU chatbot
-🔵 [handleOpenProject] Calling openProjectFromFolder...
-🔵 [handleOpenProject] Got project: ProjectModel
-🔵 [handleOpenProject] Loading project...
-🔵 [handleOpenProject] Project loaded: ProjectModel
-✅ [handleOpenProject] Success! Project should open now
-// But no project opens 🤔
-```
-
-**Root Cause**: Missing router navigation call after successful project load.
-
-**The Broken Pattern**:
-
-```typescript
-// ❌ WRONG - Project loads but editor never opens
-const handleOpenProject = async () => {
-  const direntry = await filesystem.openDialog({ ... });
-  const project = await LocalProjectsModel.instance.openProjectFromFolder(direntry);
-  const projectEntry = LocalProjectsModel.instance.getProjects().find(p => p.id === project.id);
-  const loaded = await LocalProjectsModel.instance.loadProject(projectEntry);
-  // ☠️ Returns ProjectModel but nothing happens
-  // User stays on dashboard, confused
-};
-```
-
-**The Solution**:
-
-```typescript
-// ✅ RIGHT - Navigate to editor after loading
-const handleOpenProject = useCallback(async () => {
-  const direntry = await filesystem.openDialog({ ... });
-  const project = await LocalProjectsModel.instance.openProjectFromFolder(direntry);
-  const projectEntry = LocalProjectsModel.instance.getProjects().find(p => p.id === project.id);
-  const loaded = await LocalProjectsModel.instance.loadProject(projectEntry);
-
-  if (loaded) {
-    // Navigate to editor with loaded project
-    props.route.router.route({ to: 'editor', project: loaded });
-  }
-}, [props.route]);
-```
-
-**Why This Pattern Exists**:
-
-1. `loadProject()` is a data operation - it loads project files, initializes ProjectModel, sets up modules
-2. Router navigation is a separate concern - handled by the Router component
-3. In Phase 3, `ProjectsPage` (React) must explicitly trigger navigation
-4. In legacy code, this was handled by imperative routing in Backbone views
-
-**The Router Navigation Pattern** (Phase 3):
-
-```typescript
-// Access router through props.route.router
-interface ProjectsPageProps extends IRouteProps {
-  from: TSFixme;
-  // route.router is the Router instance
-}
-
-// Navigate with project data
-props.route.router.route({
-  to: 'editor', // Target route
-  project: loaded // ProjectModel instance
-});
-
-// Navigate without project (back to dashboard)
-props.route.router.route({
-  to: 'projects',
-  from: 'editor'
-});
-```
-
-**Applies to All Project Opening Scenarios**:
-
-1. **Create Project**: After `newProject()` callback → navigate to editor
-2. **Open Project**: After `openProjectFromFolder()` + `loadProject()` → navigate to editor
-3. **Launch Project**: After `loadProject()` from list → navigate to editor
-
-**Critical Rule**: **`loadProject()` only loads data. Always call `props.route.router.route()` to actually open the editor.**
-
-**Location**:
-
-- Fixed in: `packages/noodl-editor/src/editor/src/pages/ProjectsPage/ProjectsPage.tsx`
-- Router source: `packages/noodl-editor/src/editor/src/router.tsx`
-- Phase 3 context: DASH-001 Tabbed Navigation integration
-
-**Detection**: If you see success logs but the editor doesn't open, you're missing the router navigation call.
-
-**Keywords**: LocalProjectsModel, loadProject, router, navigation, Phase 3, Launcher, ProjectsPage, silent success, openProjectFromFolder
-
----
+[Rest of the previous learnings content continues...]
diff --git a/dev-docs/reference/UI-STYLING-GUIDE.md b/dev-docs/reference/UI-STYLING-GUIDE.md
index 3793121..1f389c2 100644
--- a/dev-docs/reference/UI-STYLING-GUIDE.md
+++ b/dev-docs/reference/UI-STYLING-GUIDE.md
@@ -290,6 +290,135 @@ Before completing any UI task, verify:
 
 ---
 
+## Part 9: Selected/Active State Patterns
+
+### Decision Matrix: Which Background to Use?
+
+When styling selected or active items, choose based on the **level of emphasis** needed:
+
+| Context              | Background Token        | Text Color                              | Use Case                                       |
+| -------------------- | ----------------------- | --------------------------------------- | ---------------------------------------------- |
+| **Subtle highlight** | `--theme-color-bg-4`    | `--theme-color-fg-highlight`            | Breadcrumb current page, sidebar selected item |
+| **Medium highlight** | `--theme-color-bg-5`    | `--theme-color-fg-highlight`            | Hovered list items, tabs                       |
+| **Bold accent**      | `--theme-color-primary` | `var(--theme-color-on-primary)` (white) | Dropdown selected item, focused input          |
+
+### Common Pattern: Dropdown/Menu Selected Items
+
+```scss
+.MenuItem {
+  padding: 8px 12px;
+  cursor: pointer;
+
+  // Default state
+  color: var(--theme-color-fg-default);
+  background-color: transparent;
+
+  // Hover state (if not selected)
+  &:hover:not(.is-selected) {
+    background-color: var(--theme-color-bg-3);
+    color: var(--theme-color-fg-highlight);
+  }
+
+  // Selected state - BOLD accent for visibility
+  &.is-selected {
+    background-color: var(--theme-color-primary);
+    color: var(--theme-color-on-primary);
+
+    // Icons and child elements also need white
+    svg path {
+      fill: var(--theme-color-on-primary);
+    }
+  }
+
+  // Disabled state
+  &:disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
+  }
+}
+```
+
+### Common Pattern: Navigation/Breadcrumb Current Item
+
+```scss
+.BreadcrumbItem {
+  padding: 6px 12px;
+  border-radius: 4px;
+  color: var(--theme-color-fg-default);
+
+  // Current/active page - SUBTLE highlight
+  &.is-current {
+    background-color: var(--theme-color-bg-4);
+    color: var(--theme-color-fg-highlight);
+  }
+}
+```
+
+### ⚠️ CRITICAL: Never Use These for Backgrounds
+
+**DO NOT use these tokens for selected/active backgrounds:**
+
+```scss
+/* ❌ WRONG - These are now WHITE after token consolidation */
+background-color: var(--theme-color-secondary);
+background-color: var(--theme-color-secondary-highlight);
+background-color: var(--theme-color-fg-highlight);
+
+/* ❌ WRONG - Poor contrast on dark backgrounds */
+background-color: var(--theme-color-bg-1); /* Too dark */
+background-color: var(--theme-color-bg-2); /* Too dark */
+```
+
+### Visual Hierarchy Example
+
+```scss
+// List with multiple states
+.ListItem {
+  // Normal
+  background: transparent;
+  color: var(--theme-color-fg-default);
+
+  // Hover (not selected)
+  &:hover:not(.is-selected) {
+    background: var(--theme-color-bg-3); // Subtle lift
+  }
+
+  // Selected
+  &.is-selected {
+    background: var(--theme-color-primary); // Bold, can't miss it
+    color: white;
+  }
+
+  // Selected AND hovered
+  &.is-selected:hover {
+    background: var(--theme-color-primary-highlight); // Slightly lighter red
+  }
+}
+```
+
+### Accessibility Checklist for Selected States
+
+- [ ] Selected item is **immediately visible** (high contrast)
+- [ ] Color is not the **only** indicator (use icons/checkmarks too)
+- [ ] Keyboard focus state is **distinct** from selection
+- [ ] Text contrast meets **WCAG AA** (4.5:1 minimum)
+
+### Real-World Examples
+
+✅ **Good patterns** (fixed December 2025):
+
+- `MenuDialog.module.scss` - Uses `--theme-color-primary` for selected dropdown items
+- `NodeGraphComponentTrail.module.scss` - Uses `--theme-color-bg-4` for current breadcrumb
+- `search-panel.module.scss` - Uses `--theme-color-bg-4` for active search result
+
+❌ **Anti-patterns** (to avoid):
+
+- Using `--theme-color-secondary` as background (it's white now!)
+- No visual distinction between selected and unselected items
+- Low contrast text on selected backgrounds
+
+---
+
 ## Quick Grep Commands
 
 ```bash
@@ -301,8 +430,11 @@ grep -rE '#[0-9a-fA-F]{3,6}' packages/noodl-editor/src/editor/src/styles/
 
 # Find usage of a specific token
 grep -r "theme-color-primary" packages/
+
+# Find potential white-on-white issues
+grep -r "theme-color-secondary" packages/ --include="*.scss" --include="*.css"
 ```
 
 ---
 
-_Last Updated: December 2024_
+_Last Updated: December 2025_
diff --git a/dev-docs/tasks/phase-3-editor-ux-overhaul/TASK-000-styles-overhaul/TASK-000I-node-graph-visual-improvements/CHANGELOG.md b/dev-docs/tasks/phase-3-editor-ux-overhaul/TASK-000-styles-overhaul/TASK-000I-node-graph-visual-improvements/CHANGELOG.md
new file mode 100644
index 0000000..662dbe9
--- /dev/null
+++ b/dev-docs/tasks/phase-3-editor-ux-overhaul/TASK-000-styles-overhaul/TASK-000I-node-graph-visual-improvements/CHANGELOG.md
@@ -0,0 +1,158 @@
+# TASK-000I Changelog
+
+## Overview
+
+This changelog tracks the implementation of Node Graph Visual Improvements, covering visual polish, node comments, and port organization features.
+
+### Implementation Sessions
+
+1. **Session 1**: Sub-Task A - Rounded Corners & Colors
+2. **Session 2**: Sub-Task A - Connection Points & Label Truncation
+3. **Session 3**: Sub-Task B - Comment Data Layer & Icon
+4. **Session 4**: Sub-Task B - Hover Preview & Edit Modal
+5. **Session 5**: Sub-Task C - Port Grouping System
+6. **Session 6**: Sub-Task C - Type Icons & Connection Preview
+7. **Session 7**: Integration & Polish
+
+---
+
+## [Date TBD] - Task Created
+
+### Summary
+
+Task documentation created for Node Graph Visual Improvements based on product planning discussion.
+
+### Files Created
+
+- `dev-docs/tasks/phase-3/TASK-010-node-graph-visual/README.md` - Full task specification
+- `dev-docs/tasks/phase-3/TASK-010-node-graph-visual/CHECKLIST.md` - Implementation checklist
+- `dev-docs/tasks/phase-3/TASK-010-node-graph-visual/CHANGELOG.md` - This file
+- `dev-docs/tasks/phase-3/TASK-010-node-graph-visual/NOTES.md` - Working notes
+
+### Context
+
+Discussion identified three key areas for improvement:
+
+1. Nodes look dated (sharp corners, flat colors)
+2. No way to document individual nodes with comments
+3. Dense nodes with many ports become hard to read
+
+Decision made to implement as three sub-tasks that can be tackled incrementally.
+
+---
+
+## Progress Summary
+
+| Sub-Task               | Status      | Date Started | Date Completed |
+| ---------------------- | ----------- | ------------ | -------------- |
+| A1: Rounded Corners    | Not Started | -            | -              |
+| A2: Color Palette      | Not Started | -            | -              |
+| A3: Connection Points  | Not Started | -            | -              |
+| A4: Label Truncation   | Not Started | -            | -              |
+| B1: Comment Data Layer | Not Started | -            | -              |
+| B2: Comment Icon       | Not Started | -            | -              |
+| B3: Hover Preview      | Not Started | -            | -              |
+| B4: Edit Modal         | Not Started | -            | -              |
+| B5: Click Integration  | Not Started | -            | -              |
+| C1: Port Grouping      | Not Started | -            | -              |
+| C2: Type Icons         | Not Started | -            | -              |
+| C3: Connection Preview | Not Started | -            | -              |
+
+---
+
+## Template for Session Entries
+
+```markdown
+## [YYYY-MM-DD] - Session N: [Sub-Task Name]
+
+### Summary
+
+[Brief description of what was accomplished]
+
+### Files Created
+
+- `path/to/file.ts` - [Purpose]
+
+### Files Modified
+
+- `path/to/file.ts` - [What changed and why]
+
+### Technical Notes
+
+- [Key decisions made]
+- [Patterns discovered]
+- [Gotchas encountered]
+
+### Visual Changes
+
+- [Before/after description]
+- [Screenshot references]
+
+### Testing Notes
+
+- [What was tested]
+- [Edge cases discovered]
+
+### Next Steps
+
+- [What needs to be done next]
+```
+
+---
+
+## Blockers Log
+
+| Date | Blocker | Resolution | Time Lost |
+| ---- | ------- | ---------- | --------- |
+| -    | -       | -          | -         |
+
+---
+
+## Performance Notes
+
+| Scenario             | Before | After | Notes        |
+| -------------------- | ------ | ----- | ------------ |
+| Render 50 nodes      | -      | -     | Baseline TBD |
+| Render 100 nodes     | -      | -     | Baseline TBD |
+| Pan/zoom performance | -      | -     | Baseline TBD |
+
+---
+
+## Design Decisions Log
+
+| Decision            | Options Considered              | Choice Made | Rationale                      |
+| ------------------- | ------------------------------- | ----------- | ------------------------------ |
+| Corner radius       | 4px, 6px, 8px                   | TBD         | -                              |
+| Comment icon        | Speech bubble, Note icon, "i"   | TBD         | -                              |
+| Preview delay       | 200ms, 300ms, 500ms             | 300ms       | Balance responsiveness vs spam |
+| Port group collapse | Remember state, Reset on reload | Reset       | Simpler, no persistence needed |
+
+---
+
+## Screenshots
+
+_Add before/after screenshots as implementation progresses_
+
+### Before (Baseline)
+
+- [ ] Capture current node appearance
+- [ ] Capture dense node example
+- [ ] Capture current colors
+
+### After Sub-Task A
+
+- [ ] New rounded corners
+- [ ] Updated colors
+- [ ] Refined connection points
+
+### After Sub-Task B
+
+- [ ] Comment icon on node
+- [ ] Hover preview
+- [ ] Edit modal
+
+### After Sub-Task C
+
+- [ ] Grouped ports example
+- [ ] Type icons
+- [ ] Connection preview highlight
diff --git a/dev-docs/tasks/phase-3-editor-ux-overhaul/TASK-000-styles-overhaul/TASK-000I-node-graph-visual-improvements/CHECKLIST.md b/dev-docs/tasks/phase-3-editor-ux-overhaul/TASK-000-styles-overhaul/TASK-000I-node-graph-visual-improvements/CHECKLIST.md
new file mode 100644
index 0000000..77d5566
--- /dev/null
+++ b/dev-docs/tasks/phase-3-editor-ux-overhaul/TASK-000-styles-overhaul/TASK-000I-node-graph-visual-improvements/CHECKLIST.md
@@ -0,0 +1,224 @@
+# TASK-000I Implementation Checklist
+
+## Pre-Implementation
+
+- [ ] Review `NodeGraphEditorNode.ts` paint() method thoroughly
+- [ ] Review `colors.css` current color definitions
+- [ ] Review `NodeGraphNode.ts` metadata structure
+- [ ] Test Canvas roundRect() browser support
+- [ ] Set up test project with complex node graphs
+
+---
+
+## Sub-Task A: Visual Polish
+
+### A1: Rounded Corners
+
+- [ ] Create `canvasHelpers.ts` with roundRect utility
+- [ ] Replace background `fillRect` with roundRect in paint()
+- [ ] Update border drawing to use roundRect
+- [ ] Update selection highlight to use roundRect
+- [ ] Update error/annotation borders to use roundRect
+- [ ] Handle title bar corners (top only vs all)
+- [ ] Test at various zoom levels
+- [ ] Verify no visual artifacts
+
+### A2: Color Palette Update
+
+- [ ] Document current color values
+- [ ] Design new palette following design system
+- [ ] Update `--theme-color-node-data-*` variables
+- [ ] Update `--theme-color-node-visual-*` variables
+- [ ] Update `--theme-color-node-logic-*` variables
+- [ ] Update `--theme-color-node-custom-*` variables
+- [ ] Update `--theme-color-node-component-*` variables
+- [ ] Update connection colors if needed
+- [ ] Verify contrast ratios (WCAG AA minimum)
+- [ ] Test in dark theme
+- [ ] Get feedback on new colors
+
+### A3: Connection Point Styling
+
+- [ ] Identify all port indicator drawing code
+- [ ] Increase hit area size (4px → 6px?)
+- [ ] Add subtle inner highlight effect
+- [ ] Improve anti-aliasing
+- [ ] Test connection dragging still works
+- [ ] Verify hover states visible
+
+### A4: Port Label Truncation
+
+- [ ] Create truncateText utility function
+- [ ] Integrate into drawPlugs() function
+- [ ] Calculate available width correctly
+- [ ] Add ellipsis character (…)
+- [ ] Verify tooltip shows full name on hover
+- [ ] Test with various label lengths
+- [ ] Test with RTL text (if applicable)
+
+### A: Integration & Polish
+
+- [ ] Full visual review of all node types
+- [ ] Performance profiling
+- [ ] Update any hardcoded colors
+- [ ] Screenshots for documentation
+
+---
+
+## Sub-Task B: Node Comments System
+
+### B1: Data Layer
+
+- [ ] Add `comment?: string` to NodeMetadata interface
+- [ ] Implement `getComment()` method
+- [ ] Implement `setComment()` method with undo support
+- [ ] Implement `hasComment()` helper
+- [ ] Add 'commentChanged' event emission
+- [ ] Verify comment persists in project JSON
+- [ ] Verify comment included in node copy/paste
+- [ ] Write unit tests for data layer
+
+### B2: Comment Icon Rendering
+
+- [ ] Design/source comment icon (speech bubble)
+- [ ] Add icon drawing in paint() after title
+- [ ] Show solid icon when comment exists
+- [ ] Show faded icon on hover when no comment
+- [ ] Calculate correct icon position
+- [ ] Store hit bounds for click detection
+- [ ] Test icon visibility at all zoom levels
+
+### B3: Hover Preview
+
+- [ ] Add hover state tracking for comment icon
+- [ ] Implement 300ms debounce timer
+- [ ] Create preview content formatter
+- [ ] Position preview near icon, not obscuring node
+- [ ] Set max dimensions (250px × 150px)
+- [ ] Add scroll for long comments
+- [ ] Clear preview on mouse leave
+- [ ] Clear preview on pan/zoom start
+- [ ] Test rapid mouse movement (no spam)
+
+### B4: Edit Modal
+
+- [ ] Create `NodeCommentEditor.tsx` component
+- [ ] Create `NodeCommentEditor.module.scss` styles
+- [ ] Implement draggable header
+- [ ] Implement textarea with auto-focus
+- [ ] Handle Save button click
+- [ ] Handle Cancel button click
+- [ ] Handle Cmd+Enter to save
+- [ ] Handle Escape to cancel
+- [ ] Show node name in header
+- [ ] Position modal near node initially
+- [ ] Prevent duplicate modals for same node
+
+### B5: Click Handler Integration
+
+- [ ] Add comment icon click detection
+- [ ] Open modal on icon click
+- [ ] Prevent node selection on icon click
+- [ ] Handle modal close callback
+- [ ] Update node display after comment change
+
+### B: Integration & Polish
+
+- [ ] End-to-end test: create, edit, delete comment
+- [ ] Test with very long comments
+- [ ] Test with special characters
+- [ ] Test undo/redo flow
+- [ ] Test save/load project
+- [ ] Test export behavior
+- [ ] Accessibility review (keyboard nav)
+
+---
+
+## Sub-Task C: Port Organization & Smart Connections
+
+### C1: Port Grouping - Data Model
+
+- [ ] Define PortGroup interface
+- [ ] Add portGroups to node type schema
+- [ ] Create port group configuration for HTTP node
+- [ ] Create port group configuration for Object node
+- [ ] Create port group configuration for Function node
+- [ ] Create auto-grouping logic for unconfigured nodes
+- [ ] Store group expand state in view
+
+### C1: Port Grouping - Rendering
+
+- [ ] Modify measure() to account for groups
+- [ ] Implement group header drawing
+- [ ] Implement expand/collapse chevron
+- [ ] Draw ports within expanded groups
+- [ ] Skip ports in collapsed groups
+- [ ] Update connection positioning for grouped ports
+- [ ] Handle click on group header
+
+### C1: Port Grouping - Testing
+
+- [ ] Test grouped node rendering
+- [ ] Test collapse/expand toggle
+- [ ] Test connections to grouped ports
+- [ ] Test node without groups (unchanged)
+- [ ] Test dynamic ports (wildcard matching)
+- [ ] Verify no regression on existing projects
+
+### C2: Port Type Icons
+
+- [ ] Design icon set (signal, string, number, boolean, object, array, color, any)
+- [ ] Create icon paths/characters in `portIcons.ts`
+- [ ] Integrate icon drawing into port rendering
+- [ ] Size icons appropriately (10-12px)
+- [ ] Match icon color to port type
+- [ ] Test visibility at minimum zoom
+- [ ] Ensure icons don't interfere with labels
+
+### C3: Connection Preview on Hover
+
+- [ ] Add highlightedPort state to NodeGraphEditor
+- [ ] Detect port hover in mouse event handling
+- [ ] Implement `getPortCompatibility()` method
+- [ ] Highlight compatible ports (glow effect)
+- [ ] Dim incompatible ports (reduce opacity)
+- [ ] Draw preview line from source to cursor
+- [ ] Clear highlight on mouse leave
+- [ ] Test with various type combinations
+- [ ] Performance test with many visible nodes
+
+### C: Integration & Polish
+
+- [ ] Full interaction test
+- [ ] Performance profiling
+- [ ] Edge case testing
+- [ ] Documentation for port group configuration
+
+---
+
+## Final Verification
+
+- [ ] All three sub-tasks complete
+- [ ] No console errors
+- [ ] No TypeScript errors
+- [ ] Performance acceptable
+- [ ] Existing projects load correctly
+- [ ] All node types render correctly
+- [ ] Copy/paste works
+- [ ] Undo/redo works
+- [ ] Save/load works
+- [ ] Export works
+- [ ] Screenshots captured for changelog
+- [ ] CHANGELOG.md updated
+- [ ] LEARNINGS.md updated with discoveries
+
+---
+
+## Sign-off
+
+| Sub-Task             | Completed | Date | Notes |
+| -------------------- | --------- | ---- | ----- |
+| A: Visual Polish     | ☐         | -    | -     |
+| B: Node Comments     | ☐         | -    | -     |
+| C: Port Organization | ☐         | -    | -     |
+| Final Integration    | ☐         | -    | -     |
diff --git a/dev-docs/tasks/phase-3-editor-ux-overhaul/TASK-000-styles-overhaul/TASK-000I-node-graph-visual-improvements/NOTES.md b/dev-docs/tasks/phase-3-editor-ux-overhaul/TASK-000-styles-overhaul/TASK-000I-node-graph-visual-improvements/NOTES.md
new file mode 100644
index 0000000..bd92e49
--- /dev/null
+++ b/dev-docs/tasks/phase-3-editor-ux-overhaul/TASK-000-styles-overhaul/TASK-000I-node-graph-visual-improvements/NOTES.md
@@ -0,0 +1,306 @@
+# TASK-000I Working Notes
+
+## Key Code Locations
+
+### Node Rendering
+
+```
+packages/noodl-editor/src/editor/src/views/nodegrapheditor/NodeGraphEditorNode.ts
+
+Key methods:
+- paint() - Main render function (~line 200-400)
+- drawPlugs() - Port indicator rendering
+- measure() - Calculate node dimensions
+- handleMouseEvent() - Click/hover handling
+```
+
+### Colors
+
+```
+packages/noodl-core-ui/src/styles/custom-properties/colors.css
+
+Node colors section (~line 30-60):
+- --theme-color-node-data-*
+- --theme-color-node-visual-*
+- --theme-color-node-logic-*
+- --theme-color-node-custom-*
+- --theme-color-node-component-*
+```
+
+### Node Model
+
+```
+packages/noodl-editor/src/editor/src/models/nodegraphmodel/NodeGraphNode.ts
+
+- metadata object already exists
+- Add comment storage here
+```
+
+### Node Type Definitions
+
+```
+packages/noodl-editor/src/editor/src/models/nodelibrary/
+
+- Port groups would be defined in node type registration
+```
+
+---
+
+## Canvas API Notes
+
+### roundRect Support
+
+- Native `ctx.roundRect()` available in modern browsers
+- Fallback for older browsers:
+
+```javascript
+function roundRect(ctx, x, y, w, h, r) {
+  ctx.beginPath();
+  ctx.moveTo(x + r, y);
+  ctx.lineTo(x + w - r, y);
+  ctx.arcTo(x + w, y, x + w, y + r, r);
+  ctx.lineTo(x + w, y + h - r);
+  ctx.arcTo(x + w, y + h, x + w - r, y + h, r);
+  ctx.lineTo(x + r, y + h);
+  ctx.arcTo(x, y + h, x, y + h - r, r);
+  ctx.lineTo(x, y + r);
+  ctx.arcTo(x, y, x + r, y, r);
+  ctx.closePath();
+}
+```
+
+### Text Measurement
+
+```javascript
+const width = ctx.measureText(text).width;
+```
+
+### Hit Testing
+
+Currently done manually by checking bounds - no need to change pattern.
+
+---
+
+## Color Palette Ideas
+
+### Current (approximate from inspection)
+
+```css
+/* Data nodes - current olive green */
+--base-color-node-green-700: #4a5d23;
+--base-color-node-green-600: #5c7029;
+
+/* Visual nodes - current muted blue */
+--base-color-node-blue-700: #2d4a6d;
+--base-color-node-blue-600: #3a5f8a;
+
+/* Logic nodes - current grey */
+--base-color-node-grey-700: #3d3d3d;
+--base-color-node-grey-600: #4a4a4a;
+
+/* Custom nodes - current pink/magenta */
+--base-color-node-pink-700: #7d3a5d;
+--base-color-node-pink-600: #9a4872;
+```
+
+### Proposed Direction
+
+```css
+/* Data nodes - richer emerald */
+--base-color-node-green-700: #166534;
+--base-color-node-green-600: #15803d;
+
+/* Visual nodes - cleaner slate */
+--base-color-node-blue-700: #334155;
+--base-color-node-blue-600: #475569;
+
+/* Logic nodes - warmer charcoal */
+--base-color-node-grey-700: #3f3f46;
+--base-color-node-grey-600: #52525b;
+
+/* Custom nodes - refined rose */
+--base-color-node-pink-700: #9f1239;
+--base-color-node-pink-600: #be123c;
+```
+
+_Need to test contrast ratios and get visual feedback_
+
+---
+
+## Port Type Icons
+
+### Character-based approach (simpler)
+
+```typescript
+const PORT_TYPE_ICONS = {
+  signal: '⚡', // or custom glyph
+  string: 'T',
+  number: '#',
+  boolean: '◐',
+  object: '{}',
+  array: '[]',
+  color: '●',
+  any: '◇'
+};
+```
+
+### SVG path approach (more control)
+
+```typescript
+const PORT_TYPE_PATHS = {
+  signal: 'M4 0 L8 4 L4 8 L0 4 Z' // lightning bolt
+  // ... etc
+};
+```
+
+_Need to evaluate which looks better at 10-12px_
+
+---
+
+## Port Grouping Logic
+
+### Auto-grouping heuristics
+
+```typescript
+function autoGroupPorts(ports: Port[]): PortGroup[] {
+  const signals = ports.filter((p) => isSignalType(p.type));
+  const dataInputs = ports.filter((p) => p.direction === 'input' && !isSignalType(p.type));
+  const dataOutputs = ports.filter((p) => p.direction === 'output' && !isSignalType(p.type));
+
+  const groups: PortGroup[] = [];
+
+  if (signals.length > 0) {
+    groups.push({ name: 'Events', ports: signals, expanded: true });
+  }
+  if (dataInputs.length > 0) {
+    groups.push({ name: 'Inputs', ports: dataInputs, expanded: true });
+  }
+  if (dataOutputs.length > 0) {
+    groups.push({ name: 'Outputs', ports: dataOutputs, expanded: true });
+  }
+
+  return groups;
+}
+
+function isSignalType(type: string): boolean {
+  return type === 'signal' || type === '*'; // Check actual type names
+}
+```
+
+### Explicit group configuration example (HTTP node)
+
+```typescript
+{
+  portGroups: [
+    {
+      name: 'Request',
+      ports: ['url', 'method', 'body', 'headers-*'],
+      defaultExpanded: true
+    },
+    {
+      name: 'Response',
+      ports: ['status', 'response', 'responseHeaders'],
+      defaultExpanded: true
+    },
+    {
+      name: 'Control',
+      ports: ['send', 'success', 'failure', 'error'],
+      defaultExpanded: true
+    }
+  ];
+}
+```
+
+---
+
+## Connection Compatibility
+
+### Existing type checking
+
+```typescript
+// Check NodeLibrary for existing type compatibility logic
+NodeLibrary.instance.canConnect(sourceType, targetType);
+```
+
+### Visual feedback states
+
+1. **Source port** - Normal rendering (this is what user is hovering)
+2. **Compatible** - Brighter, subtle glow, maybe pulse animation
+3. **Incompatible** - Dimmed to 50% opacity, greyed connection point
+
+---
+
+## Comment Modal Positioning
+
+### Algorithm
+
+```typescript
+function calculateModalPosition(node: NodeGraphEditorNode): { x: number; y: number } {
+  const nodeScreenPos = canvasToScreen(node.global.x, node.global.y);
+  const nodeWidth = node.nodeSize.width * currentScale;
+  const nodeHeight = node.nodeSize.height * currentScale;
+
+  // Position to the right of the node
+  let x = nodeScreenPos.x + nodeWidth + 20;
+  let y = nodeScreenPos.y;
+
+  // Check if off-screen right, move to left
+  if (x + MODAL_WIDTH > window.innerWidth) {
+    x = nodeScreenPos.x - MODAL_WIDTH - 20;
+  }
+
+  // Check if off-screen bottom
+  if (y + MODAL_HEIGHT > window.innerHeight) {
+    y = window.innerHeight - MODAL_HEIGHT - 20;
+  }
+
+  return { x, y };
+}
+```
+
+---
+
+## Learnings to Add to LEARNINGS.md
+
+_Add these after implementation:_
+
+- [ ] Canvas roundRect browser support findings
+- [ ] Performance impact of rounded corners
+- [ ] Comment storage in metadata - any gotchas
+- [ ] Port grouping measurement calculations
+- [ ] Connection preview performance considerations
+
+---
+
+## Questions to Resolve
+
+1. ~~Should rounded corners apply to title bar only or whole node?~~
+
+   - Decision: Whole node with consistent radius
+
+2. What happens to comments when node is copied to different project?
+
+   - Need to test metadata handling in import/export
+
+3. Should port groups be user-customizable or only defined in node types?
+
+   - Start with node type definitions, user customization is future enhancement
+
+4. How to handle groups for Component nodes (user-defined ports)?
+   - Auto-group based on port direction (input/output)
+
+---
+
+## Reference Screenshots
+
+_Add reference screenshots here during implementation for comparison_
+
+### Design References
+
+- [ ] Modern node-based tools (Unreal Blueprints, Blender Geometry Nodes)
+- [ ] Other low-code tools for comparison
+
+### OpenNoodl Current State
+
+- [ ] Capture before screenshots
+- [ ] Note specific problem areas
diff --git a/dev-docs/tasks/phase-3-editor-ux-overhaul/TASK-000-styles-overhaul/TASK-000I-node-graph-visual-improvements/README.md b/dev-docs/tasks/phase-3-editor-ux-overhaul/TASK-000-styles-overhaul/TASK-000I-node-graph-visual-improvements/README.md
new file mode 100644
index 0000000..36eacf5
--- /dev/null
+++ b/dev-docs/tasks/phase-3-editor-ux-overhaul/TASK-000-styles-overhaul/TASK-000I-node-graph-visual-improvements/README.md
@@ -0,0 +1,786 @@
+# TASK-000I: Node Graph Visual Improvements
+
+## Overview
+
+Modernize the visual appearance of the node graph canvas, add a node comments system, and improve port label handling. This is a high-impact visual refresh that maintains backward compatibility while significantly improving the user experience for complex node graphs.
+
+**Phase:** 3 (Visual Improvements)  
+**Priority:** High  
+**Estimated Time:** 35-50 hours total  
+**Risk Level:** Low-Medium
+
+---
+
+## Background
+
+The node graph is the heart of OpenNoodl's visual programming experience. While functionally solid, the current visual design shows its age:
+
+- Nodes have sharp corners and flat colors that feel dated
+- No way to attach documentation/comments to individual nodes
+- Port labels overflow on nodes with many connections
+- Dense nodes (Object, State, Function) become hard to read
+
+This task addresses these pain points through three sub-tasks that can be implemented incrementally.
+
+### Current Architecture
+
+The node graph uses a **hybrid rendering approach**:
+
+1. **HTML5 Canvas** (`NodeGraphEditorNode.ts`) - Renders:
+
+   - Node backgrounds via `ctx.fillRect()`
+   - Borders via `ctx.rect()` and `ctx.strokeRect()`
+   - Port indicators (dots/arrows) via `ctx.arc()` and triangle paths
+   - Connection lines via bezier curves
+   - Text labels via `ctx.fillText()`
+
+2. **DOM Layer** (`domElementContainer`) - Renders:
+
+   - Comment layer (existing, React-based)
+   - Some overlays and tooltips
+
+3. **Color System** - Node colors come from:
+   - `NodeLibrary.instance.colorSchemeForNodeType()`
+   - Maps to CSS variables in `colors.css`
+   - Already abstracted - we can update colors without touching Canvas code
+
+### Key Files
+
+```
+packages/noodl-editor/src/editor/src/views/
+├── nodegrapheditor.ts                    # Main editor, paint loop
+├── nodegrapheditor/
+│   ├── NodeGraphEditorNode.ts            # Node rendering (PRIMARY TARGET)
+│   ├── NodeGraphEditorConnection.ts      # Connection line rendering
+│   └── ...
+├── commentlayer.ts                       # Existing comment system
+
+packages/noodl-core-ui/src/styles/custom-properties/
+├── colors.css                            # Design tokens (color updates)
+
+packages/noodl-editor/src/editor/src/models/
+├── nodegraphmodel/NodeGraphNode.ts       # Node data model (metadata storage)
+├── nodelibrary/                          # Node type definitions, port groups
+```
+
+---
+
+## Sub-Tasks
+
+### Sub-Task A: Visual Polish (8-12 hours)
+
+Modernize node appearance without changing functionality.
+
+### Sub-Task B: Node Comments System (12-18 hours)
+
+Add ability to attach documentation to individual nodes.
+
+### Sub-Task C: Port Organization & Smart Connections (15-20 hours)
+
+Improve port label handling and add connection preview on hover.
+
+---
+
+## Sub-Task A: Visual Polish
+
+### Scope
+
+1. **Rounded corners** on all node rectangles
+2. **Updated color palette** following design system
+3. **Refined connection points** (port dots/arrows)
+4. **Port label truncation** with ellipsis for overflow
+
+### Implementation
+
+#### A1: Rounded Corners (2-3 hours)
+
+**Current code** in `NodeGraphEditorNode.ts`:
+
+```typescript
+// Background
+ctx.fillRect(x, y, this.nodeSize.width, this.nodeSize.height);
+
+// Border
+ctx.rect(x, y, this.nodeSize.width, this.nodeSize.height);
+```
+
+**New approach** - Create helper function:
+
+```typescript
+function roundRect(ctx: CanvasRenderingContext2D, x: number, y: number, width: number, height: number, radius: number) {
+  ctx.beginPath();
+  ctx.roundRect(x, y, width, height, radius); // Native Canvas API
+  ctx.closePath();
+}
+```
+
+**Apply to:**
+
+- Node background fill
+- Node border stroke
+- Selection highlight
+- Error/annotation borders
+- Title bar area (top corners only, or clip)
+
+**Radius recommendation:** 6-8px for nodes, 4px for smaller elements
+
+#### A2: Color Palette Update (2-3 hours)
+
+Update CSS variables in `colors.css` to use more modern, saturated colors while maintaining the existing semantic meanings:
+
+| Node Type          | Current      | Proposed Direction               |
+| ------------------ | ------------ | -------------------------------- |
+| Data (green)       | Olive/muted  | Richer emerald green             |
+| Visual (blue)      | Muted blue   | Cleaner slate blue               |
+| Logic (grey)       | Flat grey    | Warmer charcoal with subtle tint |
+| Custom (pink)      | Magenta-pink | Refined rose/coral               |
+| Component (purple) | Muted purple | Cleaner violet                   |
+
+**Also update:**
+
+- `--theme-color-signal` (connection lines)
+- `--theme-color-data` (connection lines)
+- Background contrast between header and body
+
+**Constraint:** Keep changes within design system tokens, ensure sufficient contrast.
+
+#### A3: Connection Point Styling (2-3 hours)
+
+Current port indicators are simple:
+
+- **Dots** (`ctx.arc`) for data sources
+- **Triangles** (manual path) for signals/targets
+
+**Improvements:**
+
+- Slightly larger hit areas (currently 4px radius)
+- Subtle inner highlight or ring effect
+- Smoother anti-aliasing
+- Consider pill-shaped indicators for "connected" state
+
+**Files:** `NodeGraphEditorNode.ts` - `drawPlugs()` function
+
+#### A4: Port Label Truncation (2-3 hours)
+
+**Problem:** Long port names overflow the node boundary.
+
+**Solution:**
+
+```typescript
+function truncateText(ctx: CanvasRenderingContext2D, text: string, maxWidth: number): string {
+  const ellipsis = '…';
+  let truncated = text;
+
+  while (ctx.measureText(truncated + ellipsis).width > maxWidth && truncated.length > 0) {
+    truncated = truncated.slice(0, -1);
+  }
+
+  return truncated.length < text.length ? truncated + ellipsis : text;
+}
+```
+
+**Apply in** `drawPlugs()` before `ctx.fillText()`.
+
+**Tooltip:** Full port name should show on hover (existing tooltip system).
+
+### Success Criteria - Sub-Task A
+
+- [ ] All nodes render with rounded corners (radius configurable)
+- [ ] Color palette updated, passes contrast checks
+- [ ] Connection points are visually refined
+- [ ] Long port labels truncate with ellipsis
+- [ ] Full port name visible on hover
+- [ ] No visual regressions in existing projects
+- [ ] Performance unchanged (canvas render time)
+
+---
+
+## Sub-Task B: Node Comments System
+
+### Scope
+
+Allow users to attach plain-text comments to any node, with:
+
+- Small indicator icon when comment exists
+- Hover preview (debounced to avoid bombardment)
+- Click to open edit modal
+- Comments persist with project
+
+### Design Decisions
+
+**Storage:** `node.metadata.comment: string`
+
+- Already have `metadata` object on NodeGraphNode
+- Persists with project JSON
+- No schema changes needed
+
+**UI Pattern:** Icon + Hover Preview + Modal
+
+- Comment icon in title bar (only shows if comment exists OR on hover)
+- Hover over icon shows preview tooltip (300ms delay)
+- Click opens sticky modal for editing
+- Modal can be dragged, stays open while working
+
+**Why not inline expansion?**
+
+- Would affect node measurement/layout calculations
+- Creates cascade effects on connections
+- More invasive to existing code
+
+### Implementation
+
+#### B1: Data Layer (1-2 hours)
+
+**Add to `NodeGraphNode.ts`:**
+
+```typescript
+// In metadata interface
+interface NodeMetadata {
+  // ... existing fields
+  comment?: string;
+}
+
+// Helper methods
+getComment(): string | undefined {
+  return this.metadata?.comment;
+}
+
+setComment(comment: string | undefined, args?: { undo?: boolean }) {
+  if (!this.metadata) this.metadata = {};
+
+  const oldComment = this.metadata.comment;
+  this.metadata.comment = comment || undefined; // Remove if empty
+
+  this.notifyListeners('commentChanged', { comment });
+
+  if (args?.undo) {
+    UndoQueue.instance.push({
+      label: 'Edit comment',
+      do: () => this.setComment(comment),
+      undo: () => this.setComment(oldComment)
+    });
+  }
+}
+
+hasComment(): boolean {
+  return !!this.metadata?.comment?.trim();
+}
+```
+
+#### B2: Comment Icon Rendering (2-3 hours)
+
+**In `NodeGraphEditorNode.ts` paint function:**
+
+```typescript
+// After drawing title, before drawing ports
+if (this.model.hasComment() || this.isHovered) {
+  this.drawCommentIcon(ctx, x, y, titlebarHeight);
+}
+
+private drawCommentIcon(
+  ctx: CanvasRenderingContext2D,
+  x: number, y: number,
+  titlebarHeight: number
+) {
+  const iconX = x + this.nodeSize.width - 24; // Right side of title
+  const iconY = y + titlebarHeight / 2;
+  const hasComment = this.model.hasComment();
+
+  ctx.save();
+  ctx.globalAlpha = hasComment ? 1 : 0.4;
+  ctx.fillStyle = hasComment ? '#ffffff' : nc.text;
+
+  // Draw speech bubble icon (simple path or loaded SVG)
+  // ... icon drawing code
+
+  ctx.restore();
+
+  // Store hit area for click detection
+  this.commentIconBounds = { x: iconX - 8, y: iconY - 8, width: 16, height: 16 };
+}
+```
+
+#### B3: Hover Preview (3-4 hours)
+
+**Requirements:**
+
+- 300ms delay before showing (avoid bombardment on pan/scroll)
+- Cancel if mouse leaves before delay
+- Position near node but not obscuring it
+- Max width ~250px, max height ~150px with scroll
+
+**Implementation approach:**
+
+- Track mouse position in `NodeGraphEditorNode.handleMouseEvent`
+- Use `setTimeout` with cleanup for debounce
+- Render preview using existing `PopupLayer.showTooltip()` or custom
+
+```typescript
+// In handleMouseEvent, on 'move-in' to comment icon area:
+this.commentPreviewTimer = setTimeout(() => {
+  if (this.model.hasComment()) {
+    PopupLayer.instance.showTooltip({
+      content: this.model.getComment(),
+      position: { x: iconX, y: iconY + 20 },
+      maxWidth: 250
+    });
+  }
+}, 300);
+
+// On 'move-out':
+clearTimeout(this.commentPreviewTimer);
+PopupLayer.instance.hideTooltip();
+```
+
+#### B4: Edit Modal (4-6 hours)
+
+**Create new component:** `NodeCommentEditor.tsx`
+
+```typescript
+interface NodeCommentEditorProps {
+  node: NodeGraphNode;
+  initialPosition: { x: number; y: number };
+  onClose: () => void;
+}
+
+export function NodeCommentEditor({ node, initialPosition, onClose }: NodeCommentEditorProps) {
+  const [comment, setComment] = useState(node.getComment() || '');
+  const [position, setPosition] = useState(initialPosition);
+
+  const handleSave = () => {
+    node.setComment(comment.trim() || undefined, { undo: true });
+    onClose();
+  };
+
+  return (
+    <Draggable position={position} onDrag={setPosition}>
+      <div className={styles.CommentEditor}>
+        <div className={styles.Header}>
+          <span>Comment: {node.label}</span>
+          <button onClick={onClose}>×</button>
+        </div>
+        <textarea
+          value={comment}
+          onChange={(e) => setComment(e.target.value)}
+          placeholder="Add a comment to document this node..."
+          autoFocus
+        />
+        <div className={styles.Footer}>
+          <button onClick={handleSave}>Save</button>
+          <button onClick={onClose}>Cancel</button>
+        </div>
+      </div>
+    </Draggable>
+  );
+}
+```
+
+**Styling:**
+
+- Dark theme matching editor
+- ~300px wide, resizable
+- Draggable header
+- Save on Cmd+Enter
+
+**Integration:**
+
+- Open via `PopupLayer` or dedicated overlay
+- Track open editors to prevent duplicates
+- Close on Escape
+
+#### B5: Click Handler Integration (2-3 hours)
+
+**In `NodeGraphEditorNode.handleMouseEvent`:**
+
+```typescript
+case 'up':
+  if (this.isClickInCommentIcon(evt)) {
+    this.owner.openCommentEditor(this);
+    return; // Don't process as node selection
+  }
+  // ... existing click handling
+```
+
+**In `NodeGraphEditor`:**
+
+```typescript
+openCommentEditor(node: NodeGraphEditorNode) {
+  const screenPos = this.canvasToScreen(node.global.x, node.global.y);
+
+  PopupLayer.instance.showPopup({
+    content: NodeCommentEditor,
+    props: {
+      node: node.model,
+      initialPosition: { x: screenPos.x + node.nodeSize.width + 20, y: screenPos.y }
+    },
+    modal: false, // Allow interaction with canvas
+    closeOnOutsideClick: false
+  });
+}
+```
+
+### Success Criteria - Sub-Task B
+
+- [ ] Comments stored in node.metadata.comment
+- [ ] Icon visible on nodes with comments
+- [ ] Icon appears on hover for nodes without comments
+- [ ] Hover preview shows after 300ms delay
+- [ ] No preview bombardment when scrolling/panning
+- [ ] Click opens editable modal
+- [ ] Modal is draggable, stays open
+- [ ] Save with Cmd+Enter, cancel with Escape
+- [ ] Undo/redo works for comment changes
+- [ ] Comments persist when project saved/loaded
+- [ ] Comments included in copy/paste of nodes
+- [ ] Comments visible in exported project (or gracefully ignored)
+
+---
+
+## Sub-Task C: Port Organization & Smart Connections
+
+### Scope
+
+1. **Port grouping system** for nodes with many ports
+2. **Type icons** for ports (classy, minimal)
+3. **Connection preview on hover** - highlight compatible ports
+
+### Implementation
+
+#### C1: Port Grouping System (6-8 hours)
+
+**The challenge:** How do we define which ports belong to which group?
+
+**Proposed solution:** Define groups in node type definitions.
+
+**In node type registration:**
+
+```typescript
+{
+  name: 'net.noodl.httpnode',
+  displayName: 'HTTP Request',
+  // ... existing config
+
+  portGroups: [
+    {
+      name: 'Request',
+      ports: ['url', 'method', 'body', 'headers-*'],  // Wildcard for dynamic ports
+      defaultExpanded: true
+    },
+    {
+      name: 'Response',
+      ports: ['status', 'response', 'headers'],
+      defaultExpanded: true
+    },
+    {
+      name: 'Events',
+      ports: ['send', 'success', 'failure'],
+      defaultExpanded: true
+    }
+  ]
+}
+```
+
+**For nodes without explicit groups:** Auto-group by:
+
+- Signal ports (Run, Do, Done, Success, Failure)
+- Data inputs
+- Data outputs
+
+**Rendering changes in `NodeGraphEditorNode.ts`:**
+
+```typescript
+interface PortGroup {
+  name: string;
+  ports: PlugInfo[];
+  expanded: boolean;
+  y: number; // Calculated position
+}
+
+private portGroups: PortGroup[] = [];
+
+measure() {
+  // Build groups from node type config or auto-detect
+  this.portGroups = this.buildPortGroups();
+
+  // Calculate height based on expanded groups
+  let height = this.titlebarHeight();
+  for (const group of this.portGroups) {
+    height += GROUP_HEADER_HEIGHT;
+    if (group.expanded) {
+      height += group.ports.length * NodeGraphEditorNode.propertyConnectionHeight;
+    }
+  }
+
+  this.nodeSize.height = height;
+  // ...
+}
+
+private drawPortGroups(ctx: CanvasRenderingContext2D) {
+  let y = this.titlebarHeight();
+
+  for (const group of this.portGroups) {
+    // Draw group header with expand/collapse arrow
+    this.drawGroupHeader(ctx, group, y);
+    y += GROUP_HEADER_HEIGHT;
+
+    if (group.expanded) {
+      for (const port of group.ports) {
+        this.drawPort(ctx, port, y);
+        y += NodeGraphEditorNode.propertyConnectionHeight;
+      }
+    }
+  }
+}
+```
+
+**Group header click handling:**
+
+- Click toggles expanded state
+- State stored in view (not model) - doesn't persist
+
+**Fallback:** Nodes without groups render exactly as before (flat list).
+
+#### C2: Port Type Icons (4-6 hours)
+
+**Design principle:** Minimal, monochrome, recognizable at small sizes.
+
+**Icon set (12x12px or smaller):**
+| Type | Icon | Description |
+|------|------|-------------|
+| Signal | `⚡` or lightning bolt | Trigger/event |
+| String | `T` or `""` | Text data |
+| Number | `#` | Numeric data |
+| Boolean | `◐` | True/false (half-filled circle) |
+| Object | `{ }` | Object/record |
+| Array | `[ ]` | List/collection |
+| Color | `◉` | Filled circle (could show actual color) |
+| Any | `◇` | Diamond (accepts anything) |
+
+**Implementation:**
+
+- Create SVG icons, convert to Canvas-drawable paths
+- Or use a minimal icon font
+- Draw before/instead of colored dot
+
+```typescript
+private drawPortIcon(
+  ctx: CanvasRenderingContext2D,
+  type: string,
+  x: number, y: number,
+  connected: boolean
+) {
+  const icon = PORT_TYPE_ICONS[type] || PORT_TYPE_ICONS.any;
+
+  ctx.save();
+  ctx.fillStyle = connected ? connectionColor : '#666';
+  ctx.font = '10px Inter-Regular';
+  ctx.fillText(icon.char, x, y);
+  ctx.restore();
+}
+```
+
+**Alternative:** Small inline SVG paths drawn with Canvas path commands.
+
+#### C3: Connection Preview on Hover (5-6 hours)
+
+**Behavior:**
+
+1. User hovers over an output port
+2. All compatible input ports on other nodes highlight
+3. Incompatible ports dim or show "incompatible" indicator
+4. Works in reverse (hover input, show compatible outputs)
+
+**Implementation:**
+
+```typescript
+// In NodeGraphEditor
+private highlightedPort: { node: NodeGraphEditorNode; port: string; side: 'input' | 'output' } | null = null;
+
+setHighlightedPort(node: NodeGraphEditorNode, portName: string, side: 'input' | 'output') {
+  this.highlightedPort = { node, port: portName, side };
+  this.repaint();
+}
+
+clearHighlightedPort() {
+  this.highlightedPort = null;
+  this.repaint();
+}
+
+// In paint loop, for each node's ports:
+if (this.highlightedPort) {
+  const compatibility = this.getPortCompatibility(
+    this.highlightedPort,
+    currentNode,
+    currentPort
+  );
+
+  if (compatibility === 'compatible') {
+    // Draw with highlight glow
+  } else if (compatibility === 'incompatible') {
+    // Draw dimmed
+  }
+  // 'source' = this is the hovered port, draw normal
+}
+
+getPortCompatibility(source, targetNode, targetPort): 'compatible' | 'incompatible' | 'source' {
+  if (source.node === targetNode && source.port === targetPort) {
+    return 'source';
+  }
+
+  // Can't connect to same node
+  if (source.node === targetNode) {
+    return 'incompatible';
+  }
+
+  // Check type compatibility
+  const sourceType = source.node.model.getPort(source.port)?.type;
+  const targetType = targetNode.model.getPort(targetPort)?.type;
+
+  return NodeLibrary.instance.canConnect(sourceType, targetType)
+    ? 'compatible'
+    : 'incompatible';
+}
+```
+
+**Visual treatment:**
+
+- Compatible: Subtle pulse/glow animation, brighter color
+- Incompatible: 50% opacity, greyed out
+- Draw connection preview line from source to mouse cursor
+
+### Success Criteria - Sub-Task C
+
+- [ ] Port groups configurable in node type definitions
+- [ ] Auto-grouping fallback for unconfigured nodes
+- [ ] Groups collapsible with click
+- [ ] Group state doesn't affect existing projects
+- [ ] Port type icons render clearly at small sizes
+- [ ] Icons follow design system (not emoji-style)
+- [ ] Hovering output port highlights compatible inputs
+- [ ] Hovering input port highlights compatible outputs
+- [ ] Incompatible ports visually dimmed
+- [ ] Preview works during connection drag
+- [ ] Performance acceptable with many nodes visible
+
+---
+
+## Files to Create
+
+```
+packages/noodl-editor/src/editor/src/views/
+├── nodegrapheditor/
+│   ├── NodeCommentEditor.tsx           # Comment edit modal
+│   ├── NodeCommentEditor.module.scss   # Styles
+│   ├── canvasHelpers.ts                # roundRect, truncateText utilities
+│   └── portIcons.ts                    # SVG paths for port type icons
+```
+
+## Files to Modify
+
+```
+packages/noodl-editor/src/editor/src/views/
+├── nodegrapheditor.ts                  # Connection preview logic
+├── nodegrapheditor/
+│   ├── NodeGraphEditorNode.ts          # PRIMARY: All rendering changes
+│   └── NodeGraphEditorConnection.ts    # Minor: Updated colors
+
+packages/noodl-editor/src/editor/src/models/
+├── nodegraphmodel/NodeGraphNode.ts     # Comment storage methods
+
+packages/noodl-core-ui/src/styles/custom-properties/
+├── colors.css                          # Updated palette
+
+packages/noodl-editor/src/editor/src/models/
+├── nodelibrary/index.ts                # Port group definitions
+```
+
+---
+
+## Testing Checklist
+
+### Visual Polish
+
+- [ ] Rounded corners render correctly at all zoom levels
+- [ ] Colors match design system, sufficient contrast
+- [ ] Connection points visible and clickable
+- [ ] Truncated labels show tooltip on hover
+- [ ] Selection/error states still visible with new styling
+
+### Node Comments
+
+- [ ] Create comment on node without existing comment
+- [ ] Edit existing comment
+- [ ] Delete comment (clear text)
+- [ ] Undo/redo comment changes
+- [ ] Comment persists after save/reload
+- [ ] Comment included when copying node
+- [ ] Hover preview appears after delay
+- [ ] No preview spam when panning quickly
+- [ ] Modal draggable and stays open
+- [ ] Multiple comment modals can be open
+
+### Port Organization
+
+- [ ] Grouped ports render correctly
+- [ ] Ungrouped nodes unchanged
+- [ ] Collapse/expand works
+- [ ] Node height adjusts correctly
+- [ ] Connections still work with grouped ports
+- [ ] Port icons render at all zoom levels
+- [ ] Connection preview highlights correct ports
+- [ ] Performance acceptable with 50+ visible nodes
+
+### Regression Testing
+
+- [ ] Open existing complex project
+- [ ] All nodes render correctly
+- [ ] All connections intact
+- [ ] Copy/paste works
+- [ ] Undo/redo works
+- [ ] No console errors
+
+---
+
+## Risks & Mitigations
+
+| Risk                                        | Likelihood | Impact | Mitigation                                        |
+| ------------------------------------------- | ---------- | ------ | ------------------------------------------------- |
+| Performance regression with rounded corners | Low        | Medium | Profile canvas render time, optimize path caching |
+| Port grouping breaks connection logic       | Medium     | High   | Extensive testing, feature flag for rollback      |
+| Comment data loss on export                 | Low        | High   | Verify metadata included in all export paths      |
+| Hover preview annoying                      | Medium     | Low    | Configurable delay, easy to disable               |
+| Color changes controversial                 | Medium     | Low    | Document old colors, provide theme option         |
+
+---
+
+## Dependencies
+
+**Blocked by:** None
+
+**Blocks:** None (standalone visual improvements)
+
+**Related:**
+
+- Phase 3 design system work (colors should align)
+- Future node editor enhancements
+
+---
+
+## Future Enhancements (Out of Scope)
+
+- Markdown support in comments
+- Comment search/filter
+- Comment export to documentation
+- Custom node colors per-instance
+- Animated connections
+- Minimap improvements
+- Node grouping/frames (separate feature)
+
+---
+
+## References
+
+- Current node rendering: `NodeGraphEditorNode.ts` paint() method
+- Color system: `colors.css` and `NodeLibrary.colorSchemeForNodeType()`
+- Existing comment layer: `commentlayer.ts` (for patterns, not reuse)
+- Canvas roundRect API: https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/roundRect
diff --git a/dev-docs/tasks/phase-3-editor-ux-overhaul/TASK-000-styles-overhaul/TASK-000I-node-graph-visual-improvements/TASK-000I-A-visual-polish.md b/dev-docs/tasks/phase-3-editor-ux-overhaul/TASK-000-styles-overhaul/TASK-000I-node-graph-visual-improvements/TASK-000I-A-visual-polish.md
new file mode 100644
index 0000000..83253f4
--- /dev/null
+++ b/dev-docs/tasks/phase-3-editor-ux-overhaul/TASK-000-styles-overhaul/TASK-000I-node-graph-visual-improvements/TASK-000I-A-visual-polish.md
@@ -0,0 +1,472 @@
+# TASK-000I-A: Node Graph Visual Polish
+
+**Parent Task:** TASK-009I Node Graph Visual Improvements  
+**Estimated Time:** 8-12 hours  
+**Risk Level:** Low  
+**Dependencies:** None
+
+---
+
+## Objective
+
+Modernize the visual appearance of nodes on the canvas without changing functionality. This is a purely cosmetic update that improves the perceived quality and modernity of the editor.
+
+---
+
+## Scope
+
+1. **Rounded corners** on all node rectangles
+2. **Updated color palette** following design system
+3. **Refined connection points** (port dots/arrows)
+4. **Port label truncation** with ellipsis for overflow
+
+### Out of Scope
+
+- Node sizing changes
+- Layout algorithm changes
+- New functionality
+- Port grouping (Sub-Task C)
+
+---
+
+## Implementation Phases
+
+### Phase A1: Rounded Corners (2-3 hours)
+
+#### Current Code
+
+In `NodeGraphEditorNode.ts` paint() method:
+
+```typescript
+// Background - sharp corners
+ctx.fillStyle = nc.header;
+ctx.fillRect(x, y, this.nodeSize.width, this.nodeSize.height);
+
+// Border - sharp corners
+ctx.rect(x, y, this.nodeSize.width, this.nodeSize.height);
+ctx.stroke();
+```
+
+#### New Approach
+
+**Create helper file** `canvasHelpers.ts`:
+
+```typescript
+/**
+ * Draw a rounded rectangle path
+ * Uses native roundRect if available, falls back to arcTo
+ */
+export function roundRect(
+  ctx: CanvasRenderingContext2D,
+  x: number,
+  y: number,
+  width: number,
+  height: number,
+  radius: number | { tl: number; tr: number; br: number; bl: number }
+): void {
+  const r = typeof radius === 'number' ? { tl: radius, tr: radius, br: radius, bl: radius } : radius;
+
+  ctx.beginPath();
+  ctx.moveTo(x + r.tl, y);
+  ctx.lineTo(x + width - r.tr, y);
+  ctx.arcTo(x + width, y, x + width, y + r.tr, r.tr);
+  ctx.lineTo(x + width, y + height - r.br);
+  ctx.arcTo(x + width, y + height, x + width - r.br, y + height, r.br);
+  ctx.lineTo(x + r.bl, y + height);
+  ctx.arcTo(x, y + height, x, y + height - r.bl, r.bl);
+  ctx.lineTo(x, y + r.tl);
+  ctx.arcTo(x, y, x + r.tl, y, r.tl);
+  ctx.closePath();
+}
+
+/**
+ * Fill a rounded rectangle
+ */
+export function fillRoundRect(
+  ctx: CanvasRenderingContext2D,
+  x: number,
+  y: number,
+  width: number,
+  height: number,
+  radius: number
+): void {
+  roundRect(ctx, x, y, width, height, radius);
+  ctx.fill();
+}
+
+/**
+ * Stroke a rounded rectangle
+ */
+export function strokeRoundRect(
+  ctx: CanvasRenderingContext2D,
+  x: number,
+  y: number,
+  width: number,
+  height: number,
+  radius: number
+): void {
+  roundRect(ctx, x, y, width, height, radius);
+  ctx.stroke();
+}
+```
+
+#### Changes to NodeGraphEditorNode.ts
+
+```typescript
+import { fillRoundRect, strokeRoundRect } from './canvasHelpers';
+
+// Constants
+const NODE_CORNER_RADIUS = 6;
+
+// In paint() method:
+
+// Background - replace fillRect
+ctx.fillStyle = nc.header;
+fillRoundRect(ctx, x, y, this.nodeSize.width, this.nodeSize.height, NODE_CORNER_RADIUS);
+
+// Body area - need to clip to rounded shape
+ctx.save();
+roundRect(ctx, x, y, this.nodeSize.width, this.nodeSize.height, NODE_CORNER_RADIUS);
+ctx.clip();
+ctx.fillStyle = nc.base;
+ctx.fillRect(x, y + titlebarHeight, this.nodeSize.width, this.nodeSize.height - titlebarHeight);
+ctx.restore();
+
+// Selection border
+if (this.selected || this.borderHighlighted) {
+  ctx.strokeStyle = '#ffffff';
+  ctx.lineWidth = 2;
+  strokeRoundRect(ctx, x, y, this.nodeSize.width, this.nodeSize.height, NODE_CORNER_RADIUS);
+}
+
+// Error border
+if (!health.healthy) {
+  ctx.setLineDash([5]);
+  ctx.strokeStyle = '#F57569';
+  strokeRoundRect(ctx, x - 1, y - 1, this.nodeSize.width + 2, this.nodeSize.height + 2, NODE_CORNER_RADIUS + 1);
+  ctx.setLineDash([]);
+}
+```
+
+#### Locations to Update
+
+1. **Node background** (~line 220)
+2. **Node body fill** (~line 230)
+3. **Highlight overlay** (~line 240)
+4. **Selection border** (~line 290)
+5. **Error/unhealthy border** (~line 280)
+6. **Annotation borders** (~line 300)
+
+#### Testing
+
+- [ ] Nodes render with rounded corners at 100% zoom
+- [ ] Corners visible at 50% zoom
+- [ ] Corners not distorted at 150% zoom
+- [ ] Selection highlight follows rounded shape
+- [ ] Error dashed border follows rounded shape
+- [ ] No visual artifacts at corner intersections
+
+---
+
+### Phase A2: Color Palette Update (2-3 hours)
+
+#### File to Modify
+
+`packages/noodl-core-ui/src/styles/custom-properties/colors.css`
+
+#### Current vs Proposed
+
+Document current values first, then update:
+
+```css
+/* ===== NODE COLORS ===== */
+
+/* Data nodes - Green */
+/* Current: muted olive */
+/* Proposed: richer emerald */
+--base-color-node-green-900: #052e16;
+--base-color-node-green-700: #166534;
+--base-color-node-green-600: #16a34a;
+--base-color-node-green-500: #22c55e;
+
+/* Visual nodes - Blue */
+/* Current: muted blue */
+/* Proposed: cleaner slate */
+--base-color-node-blue-900: #0f172a;
+--base-color-node-blue-700: #334155;
+--base-color-node-blue-600: #475569;
+--base-color-node-blue-500: #64748b;
+--base-color-node-blue-400: #94a3b8;
+--base-color-node-blue-300: #cbd5e1;
+--base-color-node-blue-200: #e2e8f0;
+
+/* Logic nodes - Grey */
+/* Current: flat grey */
+/* Proposed: warmer zinc */
+--base-color-node-grey-900: #18181b;
+--base-color-node-grey-700: #3f3f46;
+--base-color-node-grey-600: #52525b;
+
+/* Custom nodes - Pink */
+/* Current: magenta */
+/* Proposed: refined rose */
+--base-color-node-pink-900: #4c0519;
+--base-color-node-pink-700: #be123c;
+--base-color-node-pink-600: #e11d48;
+
+/* Component nodes - Purple */
+/* Current: muted purple */
+/* Proposed: cleaner violet */
+--base-color-node-purple-900: #2e1065;
+--base-color-node-purple-700: #6d28d9;
+--base-color-node-purple-600: #7c3aed;
+```
+
+#### Process
+
+1. **Document current** - Screenshot and hex values
+2. **Design new palette** - Use design system principles
+3. **Update CSS variables** - One category at a time
+4. **Test contrast** - WCAG AA minimum (4.5:1 for text)
+5. **Visual review** - Check all node types
+
+#### Contrast Checking
+
+Use browser dev tools or online checker:
+
+- Header text on header background
+- Port labels on body background
+- Selection highlight visibility
+
+#### Testing
+
+- [ ] Data nodes (green) - legible, modern
+- [ ] Visual nodes (blue) - legible, modern
+- [ ] Logic nodes (grey) - legible, modern
+- [ ] Custom nodes (pink) - legible, modern
+- [ ] Component nodes (purple) - legible, modern
+- [ ] All text passes contrast check
+- [ ] Colors distinguish node types clearly
+
+---
+
+### Phase A3: Connection Point Styling (2-3 hours)
+
+#### Current Implementation
+
+In `NodeGraphEditorNode.ts` drawPlugs():
+
+```typescript
+function dot(side, color) {
+  ctx.fillStyle = color;
+  ctx.beginPath();
+  ctx.arc(x + (side === 'left' ? 0 : _this.nodeSize.width), ty, 4, 0, 2 * Math.PI, false);
+  ctx.fill();
+}
+
+function arrow(side, color) {
+  const dx = side === 'left' ? 4 : -4;
+  const cx = x + (side === 'left' ? 0 : _this.nodeSize.width);
+  ctx.fillStyle = color;
+  ctx.beginPath();
+  ctx.moveTo(cx - dx, ty - 4);
+  ctx.lineTo(cx + dx, ty);
+  ctx.lineTo(cx - dx, ty + 4);
+  ctx.fill();
+}
+```
+
+#### Improvements
+
+```typescript
+const PORT_RADIUS = 5; // Increased from 4
+const PORT_INNER_RADIUS = 2;
+
+function drawPort(side: 'left' | 'right', type: 'dot' | 'arrow', color: string, connected: boolean) {
+  const cx = x + (side === 'left' ? 0 : _this.nodeSize.width);
+
+  ctx.save();
+
+  if (type === 'dot') {
+    // Outer circle
+    ctx.fillStyle = color;
+    ctx.beginPath();
+    ctx.arc(cx, ty, PORT_RADIUS, 0, 2 * Math.PI);
+    ctx.fill();
+
+    // Inner highlight (connected state)
+    if (connected) {
+      ctx.fillStyle = 'rgba(255, 255, 255, 0.3)';
+      ctx.beginPath();
+      ctx.arc(cx, ty, PORT_INNER_RADIUS, 0, 2 * Math.PI);
+      ctx.fill();
+    }
+  } else {
+    // Arrow (signal)
+    const dx = side === 'left' ? PORT_RADIUS : -PORT_RADIUS;
+    ctx.fillStyle = color;
+    ctx.beginPath();
+    ctx.moveTo(cx - dx, ty - PORT_RADIUS);
+    ctx.lineTo(cx + dx, ty);
+    ctx.lineTo(cx - dx, ty + PORT_RADIUS);
+    ctx.closePath();
+    ctx.fill();
+  }
+
+  ctx.restore();
+}
+```
+
+#### Testing
+
+- [ ] Port dots larger and easier to click
+- [ ] Connected ports have visual distinction
+- [ ] Arrows properly sized
+- [ ] Hit detection still works
+- [ ] Dragging connections works
+- [ ] Hover states visible
+
+---
+
+### Phase A4: Port Label Truncation (2-3 hours)
+
+#### Problem
+
+Long port names overflow the node boundary, appearing outside the node rectangle.
+
+#### Solution
+
+**Add to canvasHelpers.ts:**
+
+```typescript
+/**
+ * Truncate text to fit within maxWidth, adding ellipsis if needed
+ */
+export function truncateText(ctx: CanvasRenderingContext2D, text: string, maxWidth: number): string {
+  if (ctx.measureText(text).width <= maxWidth) {
+    return text;
+  }
+
+  const ellipsis = '…';
+  let truncated = text;
+
+  while (truncated.length > 0) {
+    truncated = truncated.slice(0, -1);
+    if (ctx.measureText(truncated + ellipsis).width <= maxWidth) {
+      return truncated + ellipsis;
+    }
+  }
+
+  return ellipsis;
+}
+```
+
+#### Integration in drawPlugs()
+
+```typescript
+// Calculate available width for label
+const labelMaxWidth =
+  side === 'left'
+    ? _this.nodeSize.width / 2 - horizontalSpacing - PORT_RADIUS
+    : _this.nodeSize.width / 2 - horizontalSpacing - PORT_RADIUS;
+
+// Truncate if needed
+const displayName = truncateText(ctx, p.displayName || p.property, labelMaxWidth);
+ctx.fillText(displayName, tx, ty);
+
+// Store full name for tooltip
+p.fullDisplayName = p.displayName || p.property;
+```
+
+#### Tooltip Integration
+
+Verify existing tooltip system shows full port name on hover. If not working:
+
+```typescript
+// In handleMouseEvent, on port hover:
+if (p.fullDisplayName !== displayName) {
+  PopupLayer.instance.showTooltip({
+    content: p.fullDisplayName,
+    position: { x: mouseX, y: mouseY }
+  });
+}
+```
+
+#### Testing
+
+- [ ] Long labels truncate with ellipsis
+- [ ] Short labels unchanged
+- [ ] Truncation respects node width
+- [ ] Tooltip shows full name on hover
+- [ ] Left and right aligned labels both work
+- [ ] No text overflow outside node bounds
+
+---
+
+## Files to Create
+
+```
+packages/noodl-editor/src/editor/src/views/nodegrapheditor/
+└── canvasHelpers.ts    # Utility functions
+```
+
+## Files to Modify
+
+```
+packages/noodl-editor/src/editor/src/views/nodegrapheditor/
+└── NodeGraphEditorNode.ts    # Main rendering changes
+
+packages/noodl-core-ui/src/styles/custom-properties/
+└── colors.css                # Color palette updates
+```
+
+---
+
+## Testing Checklist
+
+### Visual Verification
+
+- [ ] Open existing project with many node types
+- [ ] All nodes render with rounded corners
+- [ ] Colors updated and consistent
+- [ ] Port indicators refined
+- [ ] Labels truncate properly
+
+### Functional Verification
+
+- [ ] Node selection works
+- [ ] Connection dragging works
+- [ ] Copy/paste works
+- [ ] Undo/redo works
+- [ ] Zoom in/out renders correctly
+
+### Performance
+
+- [ ] No noticeable slowdown
+- [ ] Smooth panning with 50+ nodes
+- [ ] Profile render time if concerned
+
+---
+
+## Success Criteria
+
+- [ ] All nodes have rounded corners (6px radius)
+- [ ] Color palette modernized
+- [ ] Port indicators larger and cleaner
+- [ ] Long labels truncate with ellipsis
+- [ ] Full port name visible on hover
+- [ ] No visual regressions
+- [ ] No functional regressions
+- [ ] Performance unchanged
+
+---
+
+## Rollback Plan
+
+If issues arise:
+
+1. Revert `NodeGraphEditorNode.ts` changes
+2. Revert `colors.css` changes
+3. Delete `canvasHelpers.ts`
+
+All changes are isolated to rendering code with no data model changes.
diff --git a/dev-docs/tasks/phase-3-editor-ux-overhaul/TASK-000-styles-overhaul/TASK-000I-node-graph-visual-improvements/TASK-000I-B-node-comments.md b/dev-docs/tasks/phase-3-editor-ux-overhaul/TASK-000-styles-overhaul/TASK-000I-node-graph-visual-improvements/TASK-000I-B-node-comments.md
new file mode 100644
index 0000000..5d5a250
--- /dev/null
+++ b/dev-docs/tasks/phase-3-editor-ux-overhaul/TASK-000-styles-overhaul/TASK-000I-node-graph-visual-improvements/TASK-000I-B-node-comments.md
@@ -0,0 +1,786 @@
+# TASK-009I-B: Node Comments System
+
+**Parent Task:** TASK-000I Node Graph Visual Improvements  
+**Estimated Time:** 12-18 hours  
+**Risk Level:** Medium  
+**Dependencies:** None (can be done in parallel with A)
+
+---
+
+## Objective
+
+Allow users to attach plain-text documentation to individual nodes, making it easier to understand and maintain complex node graphs, especially when picking up someone else's project.
+
+---
+
+## Scope
+
+1. **Data storage** - Comments stored in node metadata
+2. **Visual indicator** - Icon shows when node has comment
+3. **Hover preview** - Quick preview with debounce (no spam)
+4. **Edit modal** - Draggable editor for writing comments
+5. **Persistence** - Comments save with project
+
+### Out of Scope
+
+- Markdown formatting
+- Rich text
+- Comment threading/replies
+- Search across comments
+- Character limits
+
+---
+
+## Design Decisions
+
+| Decision         | Choice                  | Rationale                                            |
+| ---------------- | ----------------------- | ---------------------------------------------------- |
+| Storage location | `node.metadata.comment` | Existing structure, persists automatically           |
+| Preview trigger  | Hover with 300ms delay  | Balance between accessible and not annoying          |
+| Edit trigger     | Click on icon           | Explicit action, won't interfere with node selection |
+| Modal behavior   | Draggable, stays open   | User can see context while editing                   |
+| Text format      | Plain text, no limit    | Simple, no parsing overhead                          |
+
+---
+
+## Implementation Phases
+
+### Phase B1: Data Layer (1-2 hours)
+
+#### File: `NodeGraphNode.ts`
+
+**Add to metadata interface** (if typed):
+
+```typescript
+interface NodeMetadata {
+  // ... existing fields
+  comment?: string;
+  colorOverride?: string;
+  typeLabelOverride?: string;
+}
+```
+
+**Add helper methods:**
+
+```typescript
+/**
+ * Get the comment attached to this node
+ */
+getComment(): string | undefined {
+  return this.metadata?.comment;
+}
+
+/**
+ * Check if node has a non-empty comment
+ */
+hasComment(): boolean {
+  return !!this.metadata?.comment?.trim();
+}
+
+/**
+ * Set or clear the comment on this node
+ * @param comment - The comment text, or undefined/empty to clear
+ * @param args - Options including undo support
+ */
+setComment(comment: string | undefined, args?: { undo?: boolean; label?: string }): void {
+  const oldComment = this.metadata?.comment;
+  const newComment = comment?.trim() || undefined;
+
+  // No change
+  if (oldComment === newComment) return;
+
+  // Initialize metadata if needed
+  if (!this.metadata) {
+    this.metadata = {};
+  }
+
+  // Set or delete
+  if (newComment) {
+    this.metadata.comment = newComment;
+  } else {
+    delete this.metadata.comment;
+  }
+
+  // Notify listeners
+  this.notifyListeners('metadataChanged', { key: 'comment', data: newComment });
+
+  // Undo support
+  if (args?.undo) {
+    const _this = this;
+    const undo = typeof args.undo === 'object' ? args.undo : UndoQueue.instance;
+
+    undo.push({
+      label: args.label || 'Edit comment',
+      do: () => _this.setComment(newComment),
+      undo: () => _this.setComment(oldComment)
+    });
+  }
+}
+```
+
+#### Verify Persistence
+
+Comments should automatically persist because:
+
+1. `metadata` is included in `toJSON()`
+2. `metadata` is restored in constructor/fromJSON
+
+**Test by:**
+
+1. Add comment to node
+2. Save project
+3. Close and reopen
+4. Verify comment still exists
+
+#### Verify Copy/Paste
+
+When nodes are copied, metadata should be included.
+
+**Check in** `NodeGraphEditor.ts` or `NodeGraphModel.ts`:
+
+- `copySelected()`
+- `getNodeSetFromClipboard()`
+- `insertNodeSet()`
+
+---
+
+### Phase B2: Comment Icon Rendering (2-3 hours)
+
+#### Icon Design
+
+Simple speech bubble icon, rendered via Canvas path:
+
+```typescript
+// In NodeGraphEditorNode.ts or separate file
+
+const COMMENT_ICON_SIZE = 14;
+
+function drawCommentIcon(
+  ctx: CanvasRenderingContext2D,
+  x: number,
+  y: number,
+  filled: boolean,
+  alpha: number = 1
+): void {
+  ctx.save();
+  ctx.globalAlpha = alpha;
+
+  // Speech bubble path (14x14)
+  ctx.beginPath();
+  ctx.moveTo(x + 2, y + 2);
+  ctx.lineTo(x + 12, y + 2);
+  ctx.quadraticCurveTo(x + 14, y + 2, x + 14, y + 4);
+  ctx.lineTo(x + 14, y + 9);
+  ctx.quadraticCurveTo(x + 14, y + 11, x + 12, y + 11);
+  ctx.lineTo(x + 6, y + 11);
+  ctx.lineTo(x + 3, y + 14);
+  ctx.lineTo(x + 3, y + 11);
+  ctx.lineTo(x + 2, y + 11);
+  ctx.quadraticCurveTo(x, y + 11, x, y + 9);
+  ctx.lineTo(x, y + 4);
+  ctx.quadraticCurveTo(x, y + 2, x + 2, y + 2);
+  ctx.closePath();
+
+  if (filled) {
+    ctx.fillStyle = '#ffffff';
+    ctx.fill();
+  } else {
+    ctx.strokeStyle = '#ffffff';
+    ctx.lineWidth = 1.5;
+    ctx.stroke();
+  }
+
+  ctx.restore();
+}
+```
+
+#### Integration in paint()
+
+```typescript
+// After drawing title, in paint() method
+
+// Comment icon position - right side of title bar
+const commentIconX = x + this.nodeSize.width - COMMENT_ICON_SIZE - 8;
+const commentIconY = y + 6;
+
+// Store bounds for hit detection
+this.commentIconBounds = {
+  x: commentIconX - 4,
+  y: commentIconY - 4,
+  width: COMMENT_ICON_SIZE + 8,
+  height: COMMENT_ICON_SIZE + 8
+};
+
+// Draw icon
+const hasComment = this.model.hasComment();
+const isHoveringIcon = this.isHoveringCommentIcon;
+
+if (hasComment) {
+  // Always show filled icon if comment exists
+  drawCommentIcon(ctx, commentIconX, commentIconY, true, 1);
+} else if (isHoveringIcon || this.owner.isHighlighted(this)) {
+  // Show outline icon on hover
+  drawCommentIcon(ctx, commentIconX, commentIconY, false, 0.5);
+}
+```
+
+#### Hit Detection
+
+Add bounds checking in `handleMouseEvent`:
+
+```typescript
+private isPointInCommentIcon(x: number, y: number): boolean {
+  if (!this.commentIconBounds) return false;
+
+  const b = this.commentIconBounds;
+  return x >= b.x && x <= b.x + b.width && y >= b.y && y <= b.y + b.height;
+}
+```
+
+---
+
+### Phase B3: Hover Preview (3-4 hours)
+
+#### Requirements
+
+- 300ms delay before showing
+- Cancel if mouse leaves before delay
+- Clear on pan/zoom
+- Max dimensions with scroll for long comments
+- Position near icon, not obscuring node
+
+#### State Management
+
+```typescript
+// In NodeGraphEditorNode.ts
+
+private commentPreviewTimer: NodeJS.Timeout | null = null;
+private isHoveringCommentIcon: boolean = false;
+
+private showCommentPreview(): void {
+  if (!this.model.hasComment()) return;
+
+  const comment = this.model.getComment();
+  const screenPos = this.owner.canvasToScreen(
+    this.global.x + this.nodeSize.width,
+    this.global.y
+  );
+
+  PopupLayer.instance.showTooltip({
+    content: this.createPreviewContent(comment),
+    position: { x: screenPos.x + 10, y: screenPos.y },
+    maxWidth: 250,
+    maxHeight: 150
+  });
+}
+
+private createPreviewContent(comment: string): HTMLElement {
+  const div = document.createElement('div');
+  div.className = 'node-comment-preview';
+  div.style.cssText = `
+    max-height: 130px;
+    overflow-y: auto;
+    white-space: pre-wrap;
+    word-break: break-word;
+    font-size: 12px;
+    line-height: 1.4;
+  `;
+  div.textContent = comment;
+  return div;
+}
+
+private hideCommentPreview(): void {
+  PopupLayer.instance.hideTooltip();
+}
+
+private cancelCommentPreviewTimer(): void {
+  if (this.commentPreviewTimer) {
+    clearTimeout(this.commentPreviewTimer);
+    this.commentPreviewTimer = null;
+  }
+}
+```
+
+#### Mouse Event Handling
+
+```typescript
+// In handleMouseEvent()
+
+case 'move':
+  const inCommentIcon = this.isPointInCommentIcon(localX, localY);
+
+  if (inCommentIcon && !this.isHoveringCommentIcon) {
+    // Entered comment icon area
+    this.isHoveringCommentIcon = true;
+    this.owner.repaint();
+
+    // Start preview timer
+    if (this.model.hasComment()) {
+      this.cancelCommentPreviewTimer();
+      this.commentPreviewTimer = setTimeout(() => {
+        this.showCommentPreview();
+      }, 300);
+    }
+  } else if (!inCommentIcon && this.isHoveringCommentIcon) {
+    // Left comment icon area
+    this.isHoveringCommentIcon = false;
+    this.cancelCommentPreviewTimer();
+    this.hideCommentPreview();
+    this.owner.repaint();
+  }
+  break;
+
+case 'move-out':
+  // Clear all hover states
+  this.isHoveringCommentIcon = false;
+  this.cancelCommentPreviewTimer();
+  this.hideCommentPreview();
+  break;
+```
+
+#### Clear on Pan/Zoom
+
+In `NodeGraphEditor.ts`, when pan/zoom starts:
+
+```typescript
+// In mouse wheel handler or pan start
+this.forEachNode((node) => {
+  node.cancelCommentPreviewTimer?.();
+  node.hideCommentPreview?.();
+});
+```
+
+---
+
+### Phase B4: Edit Modal (4-6 hours)
+
+#### Create Component
+
+**File:** `views/nodegrapheditor/NodeCommentEditor.tsx`
+
+```tsx
+import React, { useState, useEffect, useRef, useCallback } from 'react';
+
+import { NodeGraphNode } from '@noodl-models/nodegraphmodel';
+
+import styles from './NodeCommentEditor.module.scss';
+
+export interface NodeCommentEditorProps {
+  node: NodeGraphNode;
+  initialPosition: { x: number; y: number };
+  onClose: () => void;
+}
+
+export function NodeCommentEditor({ node, initialPosition, onClose }: NodeCommentEditorProps) {
+  const [comment, setComment] = useState(node.getComment() || '');
+  const [position, setPosition] = useState(initialPosition);
+  const [isDragging, setIsDragging] = useState(false);
+  const [dragOffset, setDragOffset] = useState({ x: 0, y: 0 });
+  const textareaRef = useRef<HTMLTextAreaElement>(null);
+
+  // Auto-focus textarea
+  useEffect(() => {
+    textareaRef.current?.focus();
+    textareaRef.current?.select();
+  }, []);
+
+  // Handle save
+  const handleSave = useCallback(() => {
+    node.setComment(comment, { undo: true, label: 'Edit node comment' });
+    onClose();
+  }, [node, comment, onClose]);
+
+  // Handle cancel
+  const handleCancel = useCallback(() => {
+    onClose();
+  }, [onClose]);
+
+  // Keyboard shortcuts
+  const handleKeyDown = useCallback(
+    (e: React.KeyboardEvent) => {
+      if (e.key === 'Escape') {
+        handleCancel();
+      } else if (e.key === 'Enter' && (e.metaKey || e.ctrlKey)) {
+        handleSave();
+      }
+    },
+    [handleCancel, handleSave]
+  );
+
+  // Dragging handlers
+  const handleDragStart = useCallback(
+    (e: React.MouseEvent) => {
+      if ((e.target as HTMLElement).closest('textarea, button')) return;
+
+      setIsDragging(true);
+      setDragOffset({
+        x: e.clientX - position.x,
+        y: e.clientY - position.y
+      });
+    },
+    [position]
+  );
+
+  useEffect(() => {
+    if (!isDragging) return;
+
+    const handleMouseMove = (e: MouseEvent) => {
+      setPosition({
+        x: e.clientX - dragOffset.x,
+        y: e.clientY - dragOffset.y
+      });
+    };
+
+    const handleMouseUp = () => {
+      setIsDragging(false);
+    };
+
+    document.addEventListener('mousemove', handleMouseMove);
+    document.addEventListener('mouseup', handleMouseUp);
+
+    return () => {
+      document.removeEventListener('mousemove', handleMouseMove);
+      document.removeEventListener('mouseup', handleMouseUp);
+    };
+  }, [isDragging, dragOffset]);
+
+  return (
+    <div className={styles.CommentEditor} style={{ left: position.x, top: position.y }} onKeyDown={handleKeyDown}>
+      <div className={styles.Header} onMouseDown={handleDragStart}>
+        <span className={styles.Title}>Comment: {node.label}</span>
+        <button className={styles.CloseButton} onClick={handleCancel} title="Close (Escape)">
+          ×
+        </button>
+      </div>
+
+      <textarea
+        ref={textareaRef}
+        className={styles.TextArea}
+        value={comment}
+        onChange={(e) => setComment(e.target.value)}
+        placeholder="Add a comment to document this node..."
+      />
+
+      <div className={styles.Footer}>
+        <span className={styles.Hint}>{navigator.platform.includes('Mac') ? '⌘' : 'Ctrl'}+Enter to save</span>
+        <div className={styles.Buttons}>
+          <button className={styles.CancelButton} onClick={handleCancel}>
+            Cancel
+          </button>
+          <button className={styles.SaveButton} onClick={handleSave}>
+            Save
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}
+```
+
+#### Styles
+
+**File:** `views/nodegrapheditor/NodeCommentEditor.module.scss`
+
+```scss
+.CommentEditor {
+  position: fixed;
+  width: 320px;
+  background: var(--theme-color-bg-2);
+  border: 1px solid var(--theme-color-border-default);
+  border-radius: 8px;
+  box-shadow: 0 8px 32px rgba(0, 0, 0, 0.4);
+  z-index: 10000;
+  display: flex;
+  flex-direction: column;
+}
+
+.Header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 10px 12px;
+  background: var(--theme-color-bg-3);
+  border-bottom: 1px solid var(--theme-color-border-default);
+  border-radius: 8px 8px 0 0;
+  cursor: move;
+  user-select: none;
+}
+
+.Title {
+  font-size: 13px;
+  font-weight: 500;
+  color: var(--theme-color-fg-default);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.CloseButton {
+  background: none;
+  border: none;
+  color: var(--theme-color-fg-default-shy);
+  font-size: 18px;
+  cursor: pointer;
+  padding: 0 4px;
+  line-height: 1;
+
+  &:hover {
+    color: var(--theme-color-fg-default);
+  }
+}
+
+.TextArea {
+  flex: 1;
+  min-height: 120px;
+  max-height: 300px;
+  margin: 12px;
+  padding: 10px;
+  background: var(--theme-color-bg-1);
+  border: 1px solid var(--theme-color-border-default);
+  border-radius: 4px;
+  color: var(--theme-color-fg-default);
+  font-family: inherit;
+  font-size: 13px;
+  line-height: 1.5;
+  resize: vertical;
+
+  &::placeholder {
+    color: var(--theme-color-fg-default-shy);
+  }
+
+  &:focus {
+    outline: none;
+    border-color: var(--theme-color-primary);
+  }
+}
+
+.Footer {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 10px 12px;
+  border-top: 1px solid var(--theme-color-border-default);
+}
+
+.Hint {
+  font-size: 11px;
+  color: var(--theme-color-fg-default-shy);
+}
+
+.Buttons {
+  display: flex;
+  gap: 8px;
+}
+
+.CancelButton,
+.SaveButton {
+  padding: 6px 14px;
+  border-radius: 4px;
+  font-size: 12px;
+  font-weight: 500;
+  cursor: pointer;
+  transition: background-color 0.15s;
+}
+
+.CancelButton {
+  background: var(--theme-color-bg-3);
+  border: 1px solid var(--theme-color-border-default);
+  color: var(--theme-color-fg-default);
+
+  &:hover {
+    background: var(--theme-color-bg-4);
+  }
+}
+
+.SaveButton {
+  background: var(--theme-color-primary);
+  border: none;
+  color: var(--theme-color-on-primary);
+
+  &:hover {
+    background: var(--theme-color-primary-highlight);
+  }
+}
+```
+
+---
+
+### Phase B5: Click Handler Integration (2-3 hours)
+
+#### Open Modal on Click
+
+In `NodeGraphEditorNode.ts` handleMouseEvent():
+
+```typescript
+case 'up':
+  // Check comment icon click FIRST
+  if (this.isPointInCommentIcon(localX, localY)) {
+    this.owner.openCommentEditor(this);
+    return; // Don't process as node selection
+  }
+
+  // ... existing click handling
+```
+
+#### NodeGraphEditor Integration
+
+In `NodeGraphEditor.ts`:
+
+```typescript
+import { NodeCommentEditor } from './nodegrapheditor/NodeCommentEditor';
+
+// Track open editors to prevent duplicates
+private openCommentEditors: Map<string, () => void> = new Map();
+
+openCommentEditor(node: NodeGraphEditorNode): void {
+  const nodeId = node.model.id;
+
+  // Check if already open
+  if (this.openCommentEditors.has(nodeId)) {
+    return; // Already open
+  }
+
+  // Calculate initial position
+  const screenPos = this.canvasToScreen(node.global.x, node.global.y);
+  const initialX = Math.min(
+    screenPos.x + node.nodeSize.width * this.getPanAndScale().scale + 20,
+    window.innerWidth - 340
+  );
+  const initialY = Math.min(
+    screenPos.y,
+    window.innerHeight - 250
+  );
+
+  // Create close handler
+  const closeEditor = () => {
+    this.openCommentEditors.delete(nodeId);
+    PopupLayer.instance.hidePopup(popupId);
+    this.repaint(); // Update comment icon state
+  };
+
+  // Show modal
+  const popupId = PopupLayer.instance.showPopup({
+    content: NodeCommentEditor,
+    props: {
+      node: node.model,
+      initialPosition: { x: initialX, y: initialY },
+      onClose: closeEditor
+    },
+    modal: false,
+    closeOnOutsideClick: false,
+    closeOnEscape: false // We handle Escape in component
+  });
+
+  this.openCommentEditors.set(nodeId, closeEditor);
+}
+
+// Helper method
+canvasToScreen(canvasX: number, canvasY: number): { x: number; y: number } {
+  const panAndScale = this.getPanAndScale();
+  return {
+    x: (canvasX + panAndScale.x) * panAndScale.scale,
+    y: (canvasY + panAndScale.y) * panAndScale.scale
+  };
+}
+```
+
+---
+
+## Files to Create
+
+```
+packages/noodl-editor/src/editor/src/views/nodegrapheditor/
+├── NodeCommentEditor.tsx
+└── NodeCommentEditor.module.scss
+```
+
+## Files to Modify
+
+```
+packages/noodl-editor/src/editor/src/models/nodegraphmodel/
+└── NodeGraphNode.ts              # Add comment methods
+
+packages/noodl-editor/src/editor/src/views/nodegrapheditor/
+└── NodeGraphEditorNode.ts        # Icon rendering, hover, click
+
+packages/noodl-editor/src/editor/src/views/
+└── nodegrapheditor.ts            # openCommentEditor integration
+```
+
+---
+
+## Testing Checklist
+
+### Data Layer
+
+- [ ] getComment() returns undefined for new node
+- [ ] setComment() stores comment
+- [ ] hasComment() returns true when comment exists
+- [ ] setComment('') clears comment
+- [ ] Comment persists after save/reload
+- [ ] Comment copied when node copied
+- [ ] Undo restores previous comment
+- [ ] Redo re-applies comment
+
+### Icon Rendering
+
+- [ ] Icon shows (filled) on nodes with comments
+- [ ] Icon shows (outline) on hover for nodes without comments
+- [ ] Icon positioned correctly in title bar
+- [ ] Icon visible at various zoom levels
+- [ ] Icon doesn't overlap with node label
+
+### Hover Preview
+
+- [ ] Preview shows after 300ms hover
+- [ ] Preview doesn't show immediately (no spam)
+- [ ] Preview clears when mouse leaves
+- [ ] Preview clears on pan/zoom
+- [ ] Long comments scroll in preview
+- [ ] Preview positioned near icon, not obscuring node
+
+### Edit Modal
+
+- [ ] Opens on icon click
+- [ ] Shows current comment
+- [ ] Textarea auto-focused
+- [ ] Can edit comment text
+- [ ] Save button saves and closes
+- [ ] Cancel button discards and closes
+- [ ] Cmd+Enter saves
+- [ ] Escape cancels
+- [ ] Modal is draggable
+- [ ] Can have multiple modals open (different nodes)
+- [ ] Cannot open duplicate modal for same node
+
+### Integration
+
+- [ ] Clicking icon doesn't select node
+- [ ] Can still select node by clicking elsewhere
+- [ ] Comment updates reflected after save
+- [ ] Node repainted after comment change
+
+---
+
+## Success Criteria
+
+- [ ] Comments stored in node.metadata.comment
+- [ ] Filled icon visible on nodes with comments
+- [ ] Outline icon on hover for nodes without comments
+- [ ] Hover preview after 300ms, no spam on pan/scroll
+- [ ] Click opens draggable edit modal
+- [ ] Cmd+Enter to save, Escape to cancel
+- [ ] Undo/redo works for comment changes
+- [ ] Comments persist in project save/load
+- [ ] Comments included in copy/paste
+
+---
+
+## Rollback Plan
+
+1. Revert `NodeGraphNode.ts` comment methods
+2. Revert `NodeGraphEditorNode.ts` icon/hover code
+3. Revert `nodegrapheditor.ts` openCommentEditor
+4. Delete `NodeCommentEditor.tsx` and `.scss`
+
+Data layer changes are additive - existing projects won't break even if code is partially reverted.
diff --git a/dev-docs/tasks/phase-3-editor-ux-overhaul/TASK-000-styles-overhaul/TASK-000I-node-graph-visual-improvements/TASK-000I-C-port-organization.md b/dev-docs/tasks/phase-3-editor-ux-overhaul/TASK-000-styles-overhaul/TASK-000I-node-graph-visual-improvements/TASK-000I-C-port-organization.md
new file mode 100644
index 0000000..ee9e3d8
--- /dev/null
+++ b/dev-docs/tasks/phase-3-editor-ux-overhaul/TASK-000-styles-overhaul/TASK-000I-node-graph-visual-improvements/TASK-000I-C-port-organization.md
@@ -0,0 +1,858 @@
+# TASK-009I-C: Port Organization & Smart Connections
+
+**Parent Task:** TASK-000I Node Graph Visual Improvements  
+**Estimated Time:** 15-20 hours  
+**Risk Level:** Medium  
+**Dependencies:** Sub-Task A (visual polish) recommended first
+
+---
+
+## Objective
+
+Improve the usability of nodes with many ports through visual organization, type indicators, and smart connection previews that highlight compatible ports.
+
+---
+
+## Scope
+
+1. **Port grouping system** - Collapsible groups for nodes with many ports
+2. **Port type icons** - Small, classy icons indicating data types
+3. **Connection preview on hover** - Highlight compatible ports when hovering
+
+### Out of Scope
+
+- Two-column port layout
+- Hiding unused ports
+- User-customizable groups (node type defines groups)
+- Animated connections
+
+---
+
+## Target Nodes
+
+These nodes have the most ports and will benefit most:
+
+| Node Type                  | Typical Port Count | Pain Point                |
+| -------------------------- | ------------------ | ------------------------- |
+| Object                     | 10-30+             | Dynamic properties        |
+| States                     | 5-20+              | State transitions         |
+| Function/Script            | Variable           | User-defined I/O          |
+| Component I/O              | Variable           | Exposed ports             |
+| HTTP Request               | 15+                | Headers, params, response |
+| Visual nodes (Group, etc.) | 20+                | Style properties          |
+
+---
+
+## Implementation Phases
+
+### Phase C1: Port Grouping System (6-8 hours)
+
+#### Design: Group Configuration
+
+Groups can be defined in two ways:
+
+**1. Explicit configuration in node type definition:**
+
+```typescript
+// In node type registration
+{
+  name: 'net.noodl.httpnode',
+  displayName: 'HTTP Request',
+
+  portGroups: [
+    {
+      name: 'Request',
+      ports: ['url', 'method', 'body'],
+      dynamicPorts: 'header-*',  // Wildcard for dynamic ports
+      defaultExpanded: true
+    },
+    {
+      name: 'Query Parameters',
+      ports: ['queryParams'],
+      dynamicPorts: 'param-*',
+      defaultExpanded: false
+    },
+    {
+      name: 'Response',
+      ports: ['status', 'response', 'responseHeaders', 'error'],
+      defaultExpanded: true
+    },
+    {
+      name: 'Control',
+      ports: ['send', 'success', 'failure'],
+      defaultExpanded: true
+    }
+  ]
+}
+```
+
+**2. Auto-grouping fallback:**
+
+```typescript
+// For nodes without explicit groups
+function autoGroupPorts(node: NodeGraphEditorNode): PortGroup[] {
+  const ports = node.getAllPorts();
+
+  const inputs = ports.filter((p) => p.direction === 'input' && p.type !== 'signal');
+  const outputs = ports.filter((p) => p.direction === 'output' && p.type !== 'signal');
+  const signals = ports.filter((p) => p.type === 'signal');
+
+  const groups: PortGroup[] = [];
+
+  // Only create groups if node has many ports
+  const GROUPING_THRESHOLD = 8;
+  if (ports.length < GROUPING_THRESHOLD) {
+    return []; // No grouping, render flat
+  }
+
+  if (signals.length > 0) {
+    groups.push({
+      name: 'Events',
+      ports: signals,
+      expanded: true,
+      isAutoGenerated: true
+    });
+  }
+
+  if (inputs.length > 0) {
+    groups.push({
+      name: 'Inputs',
+      ports: inputs,
+      expanded: true,
+      isAutoGenerated: true
+    });
+  }
+
+  if (outputs.length > 0) {
+    groups.push({
+      name: 'Outputs',
+      ports: outputs,
+      expanded: true,
+      isAutoGenerated: true
+    });
+  }
+
+  return groups;
+}
+```
+
+#### Data Structures
+
+**File:** `views/nodegrapheditor/portGrouping.ts`
+
+```typescript
+export interface PortGroupDefinition {
+  name: string;
+  ports: string[]; // Explicit port names
+  dynamicPorts?: string; // Wildcard pattern like 'header-*'
+  defaultExpanded?: boolean;
+}
+
+export interface PortGroup {
+  name: string;
+  ports: PlugInfo[];
+  expanded: boolean;
+  isAutoGenerated: boolean;
+  yPosition?: number; // Calculated during layout
+}
+
+export const GROUP_HEADER_HEIGHT = 24;
+export const GROUP_INDENT = 8;
+
+/**
+ * Build port groups for a node
+ */
+export function buildPortGroups(node: NodeGraphEditorNode, plugs: PlugInfo[]): PortGroup[] {
+  const typeDefinition = node.model.type;
+
+  // Check for explicit group configuration
+  if (typeDefinition.portGroups && typeDefinition.portGroups.length > 0) {
+    return buildExplicitGroups(typeDefinition.portGroups, plugs);
+  }
+
+  // Fall back to auto-grouping
+  return autoGroupPorts(plugs);
+}
+
+function buildExplicitGroups(definitions: PortGroupDefinition[], plugs: PlugInfo[]): PortGroup[] {
+  const groups: PortGroup[] = [];
+  const assignedPorts = new Set<string>();
+
+  for (const def of definitions) {
+    const groupPorts: PlugInfo[] = [];
+
+    // Match explicit port names
+    for (const portName of def.ports) {
+      const plug = plugs.find((p) => p.property === portName);
+      if (plug) {
+        groupPorts.push(plug);
+        assignedPorts.add(portName);
+      }
+    }
+
+    // Match dynamic ports via wildcard
+    if (def.dynamicPorts) {
+      const pattern = def.dynamicPorts.replace('*', '(.*)');
+      const regex = new RegExp(`^${pattern}$`);
+
+      for (const plug of plugs) {
+        if (!assignedPorts.has(plug.property) && regex.test(plug.property)) {
+          groupPorts.push(plug);
+          assignedPorts.add(plug.property);
+        }
+      }
+    }
+
+    if (groupPorts.length > 0) {
+      groups.push({
+        name: def.name,
+        ports: groupPorts,
+        expanded: def.defaultExpanded !== false,
+        isAutoGenerated: false
+      });
+    }
+  }
+
+  // Add ungrouped ports to "Other" group
+  const ungrouped = plugs.filter((p) => !assignedPorts.has(p.property));
+  if (ungrouped.length > 0) {
+    groups.push({
+      name: 'Other',
+      ports: ungrouped,
+      expanded: true,
+      isAutoGenerated: true
+    });
+  }
+
+  return groups;
+}
+```
+
+#### Rendering Changes
+
+**In `NodeGraphEditorNode.ts`:**
+
+```typescript
+import { buildPortGroups, PortGroup, GROUP_HEADER_HEIGHT } from './portGrouping';
+
+// Add to class
+private portGroups: PortGroup[] = [];
+private groupExpandState: Map<string, boolean> = new Map();
+
+// Modify measure() method
+measure() {
+  // ... existing size calculations
+
+  // Build port groups
+  this.portGroups = buildPortGroups(this, this.plugs);
+
+  // Apply saved expand states
+  for (const group of this.portGroups) {
+    const savedState = this.groupExpandState.get(group.name);
+    if (savedState !== undefined) {
+      group.expanded = savedState;
+    }
+  }
+
+  // Calculate height
+  if (this.portGroups.length > 0) {
+    let height = this.titlebarHeight();
+
+    for (const group of this.portGroups) {
+      height += GROUP_HEADER_HEIGHT;
+      if (group.expanded) {
+        height += group.ports.length * NodeGraphEditorNode.propertyConnectionHeight;
+      }
+    }
+
+    this.nodeSize.height = Math.max(height, NodeGraphEditorNode.size.height);
+  }
+
+  // ... rest of measure
+}
+
+// Add group header drawing
+private drawGroupHeader(
+  ctx: CanvasRenderingContext2D,
+  group: PortGroup,
+  x: number,
+  y: number
+): void {
+  const headerY = y;
+
+  // Background
+  ctx.fillStyle = 'rgba(0, 0, 0, 0.15)';
+  ctx.fillRect(x, headerY, this.nodeSize.width, GROUP_HEADER_HEIGHT);
+
+  // Chevron
+  ctx.save();
+  ctx.fillStyle = 'rgba(255, 255, 255, 0.6)';
+  ctx.font = '10px Inter-Regular';
+  ctx.textBaseline = 'middle';
+
+  const chevron = group.expanded ? '▼' : '▶';
+  ctx.fillText(chevron, x + 8, headerY + GROUP_HEADER_HEIGHT / 2);
+
+  // Group name
+  ctx.fillStyle = 'rgba(255, 255, 255, 0.8)';
+  ctx.font = '11px Inter-Medium';
+  ctx.fillText(group.name, x + 22, headerY + GROUP_HEADER_HEIGHT / 2);
+
+  // Port count
+  ctx.fillStyle = 'rgba(255, 255, 255, 0.4)';
+  ctx.font = '10px Inter-Regular';
+  ctx.fillText(`(${group.ports.length})`, x + 22 + ctx.measureText(group.name).width + 6, headerY + GROUP_HEADER_HEIGHT / 2);
+
+  ctx.restore();
+
+  // Store hit area for click detection
+  group.headerBounds = {
+    x: x,
+    y: headerY,
+    width: this.nodeSize.width,
+    height: GROUP_HEADER_HEIGHT
+  };
+}
+
+// Modify drawPlugs or create new drawGroupedPlugs
+private drawGroupedPorts(ctx: CanvasRenderingContext2D, x: number, startY: number): void {
+  let y = startY;
+
+  for (const group of this.portGroups) {
+    // Draw header
+    this.drawGroupHeader(ctx, group, x, y);
+    y += GROUP_HEADER_HEIGHT;
+    group.yPosition = y;
+
+    // Draw ports if expanded
+    if (group.expanded) {
+      for (const plug of group.ports) {
+        this.drawPort(ctx, plug, x, y);
+        y += NodeGraphEditorNode.propertyConnectionHeight;
+      }
+    }
+  }
+}
+```
+
+#### Click Handling for Expand/Collapse
+
+```typescript
+// In handleMouseEvent
+case 'up':
+  // Check group header clicks
+  for (const group of this.portGroups) {
+    if (group.headerBounds && this.isPointInBounds(localX, localY, group.headerBounds)) {
+      this.toggleGroupExpanded(group);
+      return;
+    }
+  }
+  // ... rest of click handling
+
+private toggleGroupExpanded(group: PortGroup): void {
+  group.expanded = !group.expanded;
+  this.groupExpandState.set(group.name, group.expanded);
+
+  // Remeasure and repaint
+  this.measuredSize = null;
+  this.owner.relayout();
+  this.owner.repaint();
+}
+```
+
+---
+
+### Phase C2: Port Type Icons (4-6 hours)
+
+#### Icon Design
+
+Small, monochrome icons that indicate data type at a glance.
+
+**File:** `views/nodegrapheditor/portIcons.ts`
+
+```typescript
+export type PortType =
+  | 'signal'
+  | 'string'
+  | 'number'
+  | 'boolean'
+  | 'object'
+  | 'array'
+  | 'color'
+  | 'any'
+  | 'component'
+  | 'enum';
+
+export interface PortIcon {
+  char?: string; // Single character fallback
+  path?: Path2D; // Canvas path for precise control
+}
+
+// Simple character-based icons (reliable, easy)
+export const PORT_ICONS: Record<PortType, PortIcon> = {
+  signal: { char: '⚡' }, // Lightning bolt
+  string: { char: 'T' }, // Text
+  number: { char: '#' }, // Number sign
+  boolean: { char: '◐' }, // Half circle
+  object: { char: '{ }' }, // Braces (might need path)
+  array: { char: '[ ]' }, // Brackets
+  color: { char: '●' }, // Filled circle
+  any: { char: '◇' }, // Diamond
+  component: { char: '◈' }, // Diamond with dot
+  enum: { char: '≡' } // Menu/list
+};
+
+// Size constants
+export const PORT_ICON_SIZE = 10;
+export const PORT_ICON_PADDING = 4;
+
+/**
+ * Map Noodl internal type names to our icon types
+ */
+export function getPortIconType(type: string | undefined): PortType {
+  if (!type) return 'any';
+
+  const typeMap: Record<string, PortType> = {
+    signal: 'signal',
+    '*': 'signal',
+    string: 'string',
+    number: 'number',
+    boolean: 'boolean',
+    object: 'object',
+    array: 'array',
+    color: 'color',
+    component: 'component',
+    enum: 'enum'
+  };
+
+  return typeMap[type.toLowerCase()] || 'any';
+}
+
+/**
+ * Draw a port type icon
+ */
+export function drawPortIcon(ctx: CanvasRenderingContext2D, type: PortType, x: number, y: number, color: string): void {
+  const icon = PORT_ICONS[type];
+
+  ctx.save();
+  ctx.fillStyle = color;
+  ctx.font = `${PORT_ICON_SIZE}px Inter-Regular`;
+  ctx.textAlign = 'center';
+  ctx.textBaseline = 'middle';
+  ctx.fillText(icon.char || '?', x, y);
+  ctx.restore();
+}
+```
+
+#### Integration
+
+```typescript
+// In drawPort() or drawPlugs()
+
+// After drawing the connection dot/arrow, add type icon
+const portType = getPortIconType(plug.type);
+const iconX =
+  side === 'left'
+    ? x + PORT_RADIUS + PORT_ICON_PADDING + PORT_ICON_SIZE / 2
+    : x + this.nodeSize.width - PORT_RADIUS - PORT_ICON_PADDING - PORT_ICON_SIZE / 2;
+
+drawPortIcon(ctx, portType, iconX, ty, 'rgba(255, 255, 255, 0.5)');
+
+// Adjust label position to account for icon
+const labelX = side === 'left' ? iconX + PORT_ICON_SIZE / 2 + 4 : iconX - PORT_ICON_SIZE / 2 - 4;
+```
+
+#### Alternative: SVG Path Icons
+
+For more precise control:
+
+```typescript
+// Create paths once
+const signalPath = new Path2D('M4 0 L8 4 L6 4 L6 8 L2 8 L2 4 L0 4 Z');
+
+export function drawPortIconPath(
+  ctx: CanvasRenderingContext2D,
+  type: PortType,
+  x: number,
+  y: number,
+  color: string,
+  scale: number = 1
+): void {
+  const path = PORT_ICON_PATHS[type];
+  if (!path) return;
+
+  ctx.save();
+  ctx.fillStyle = color;
+  ctx.translate(x - 4 * scale, y - 4 * scale);
+  ctx.scale(scale, scale);
+  ctx.fill(path);
+  ctx.restore();
+}
+```
+
+---
+
+### Phase C3: Connection Preview on Hover (5-6 hours)
+
+#### Behavior Specification
+
+1. User hovers over a port (input or output)
+2. System identifies all compatible ports on other nodes
+3. Compatible ports are highlighted (brighter, glow effect)
+4. Incompatible ports are dimmed (reduced opacity)
+5. Preview clears when mouse leaves port area
+
+#### State Management
+
+**In `NodeGraphEditor.ts`:**
+
+```typescript
+// Add state
+private highlightedPort: {
+  node: NodeGraphEditorNode;
+  plug: PlugInfo;
+  isOutput: boolean;
+} | null = null;
+
+// Methods
+setHighlightedPort(
+  node: NodeGraphEditorNode,
+  plug: PlugInfo,
+  isOutput: boolean
+): void {
+  this.highlightedPort = { node, plug, isOutput };
+  this.repaint();
+}
+
+clearHighlightedPort(): void {
+  if (this.highlightedPort) {
+    this.highlightedPort = null;
+    this.repaint();
+  }
+}
+
+/**
+ * Check if a port is compatible with the currently highlighted port
+ */
+getPortCompatibility(
+  targetNode: NodeGraphEditorNode,
+  targetPlug: PlugInfo,
+  targetIsOutput: boolean
+): 'source' | 'compatible' | 'incompatible' | 'neutral' {
+  if (!this.highlightedPort) return 'neutral';
+
+  const source = this.highlightedPort;
+
+  // Same port = source
+  if (source.node === targetNode && source.plug.property === targetPlug.property) {
+    return 'source';
+  }
+
+  // Same node = incompatible (can't connect to self)
+  if (source.node === targetNode) {
+    return 'incompatible';
+  }
+
+  // Same direction = incompatible (output to output, input to input)
+  if (source.isOutput === targetIsOutput) {
+    return 'incompatible';
+  }
+
+  // Check type compatibility
+  const sourceType = source.plug.type || '*';
+  const targetType = targetPlug.type || '*';
+
+  // Use existing type compatibility logic
+  const compatible = this.checkTypeCompatibility(sourceType, targetType);
+
+  return compatible ? 'compatible' : 'incompatible';
+}
+
+private checkTypeCompatibility(sourceType: string, targetType: string): boolean {
+  // Signals connect to signals
+  if (sourceType === '*' || sourceType === 'signal') {
+    return targetType === '*' || targetType === 'signal';
+  }
+
+  // Any type (*) is compatible with anything
+  if (sourceType === '*' || targetType === '*') {
+    return true;
+  }
+
+  // Same type
+  if (sourceType === targetType) {
+    return true;
+  }
+
+  // Number compatible with string (coercion)
+  if ((sourceType === 'number' && targetType === 'string') ||
+      (sourceType === 'string' && targetType === 'number')) {
+    return true;
+  }
+
+  // Could add more rules based on NodeLibrary
+  return false;
+}
+```
+
+#### Visual Rendering
+
+**In `NodeGraphEditorNode.ts` drawPort():**
+
+```typescript
+private drawPort(
+  ctx: CanvasRenderingContext2D,
+  plug: PlugInfo,
+  x: number,
+  y: number,
+  isOutput: boolean
+): void {
+  // Get compatibility state
+  const compatibility = this.owner.getPortCompatibility(this, plug, isOutput);
+
+  // Determine visual style
+  let alpha = 1;
+  let glowColor: string | null = null;
+
+  switch (compatibility) {
+    case 'source':
+      // This is the hovered port - normal rendering
+      break;
+
+    case 'compatible':
+      // Highlight compatible ports
+      glowColor = 'rgba(100, 200, 255, 0.6)';
+      break;
+
+    case 'incompatible':
+      // Dim incompatible ports
+      alpha = 0.3;
+      break;
+
+    case 'neutral':
+      // No highlighting active
+      break;
+  }
+
+  ctx.save();
+  ctx.globalAlpha = alpha;
+
+  // Draw glow for compatible ports
+  if (glowColor) {
+    ctx.shadowColor = glowColor;
+    ctx.shadowBlur = 8;
+  }
+
+  // ... existing port drawing code
+
+  ctx.restore();
+}
+```
+
+#### Mouse Event Handling
+
+**In `NodeGraphEditorNode.ts` handleMouseEvent():**
+
+```typescript
+case 'move':
+  // Check if hovering a port
+  const hoveredPlug = this.getPlugAtPosition(localX, localY);
+
+  if (hoveredPlug) {
+    const isOutput = hoveredPlug.side === 'right';
+    this.owner.setHighlightedPort(this, hoveredPlug.plug, isOutput);
+  } else if (this.owner.highlightedPort?.node === this) {
+    // Was hovering our port, now not - clear
+    this.owner.clearHighlightedPort();
+  }
+  break;
+
+case 'move-out':
+  // Clear if we were the source
+  if (this.owner.highlightedPort?.node === this) {
+    this.owner.clearHighlightedPort();
+  }
+  break;
+
+// Helper method
+private getPlugAtPosition(x: number, y: number): { plug: PlugInfo; side: 'left' | 'right' } | null {
+  const portRadius = 8; // Hit area
+
+  for (const plug of this.plugs) {
+    // Left side ports
+    if (plug.leftCons?.length || plug.leftIcon) {
+      const px = 0;
+      const py = plug.yPosition; // Need to track this during layout
+
+      if (Math.abs(x - px) < portRadius && Math.abs(y - py) < portRadius) {
+        return { plug, side: 'left' };
+      }
+    }
+
+    // Right side ports
+    if (plug.rightCons?.length || plug.rightIcon) {
+      const px = this.nodeSize.width;
+      const py = plug.yPosition;
+
+      if (Math.abs(x - px) < portRadius && Math.abs(y - py) < portRadius) {
+        return { plug, side: 'right' };
+      }
+    }
+  }
+
+  return null;
+}
+```
+
+#### Performance Consideration
+
+With many nodes visible, checking compatibility for every port on every paint could be slow.
+
+**Optimization:**
+
+```typescript
+// Cache compatibility results when highlight changes
+private compatibilityCache: Map<string, 'compatible' | 'incompatible'> = new Map();
+
+setHighlightedPort(...) {
+  this.highlightedPort = { node, plug, isOutput };
+  this.rebuildCompatibilityCache();
+  this.repaint();
+}
+
+private rebuildCompatibilityCache(): void {
+  this.compatibilityCache.clear();
+
+  if (!this.highlightedPort) return;
+
+  // Pre-calculate for all visible nodes
+  this.forEachNode(node => {
+    for (const plug of node.plugs) {
+      const key = `${node.model.id}:${plug.property}`;
+      const compat = this.calculateCompatibility(node, plug);
+      this.compatibilityCache.set(key, compat);
+    }
+  });
+}
+
+getPortCompatibility(node, plug, isOutput): string {
+  if (!this.highlightedPort) return 'neutral';
+
+  const key = `${node.model.id}:${plug.property}`;
+  return this.compatibilityCache.get(key) || 'neutral';
+}
+```
+
+---
+
+## Files to Create
+
+```
+packages/noodl-editor/src/editor/src/views/nodegrapheditor/
+├── portGrouping.ts     # Group logic and interfaces
+└── portIcons.ts        # Type icon definitions
+```
+
+## Files to Modify
+
+```
+packages/noodl-editor/src/editor/src/views/nodegrapheditor/
+└── NodeGraphEditorNode.ts    # Grouped rendering, icons, hover
+
+packages/noodl-editor/src/editor/src/views/
+└── nodegrapheditor.ts        # Highlight state management
+
+packages/noodl-editor/src/editor/src/models/nodelibrary/
+└── [node definitions]        # Add portGroups config (optional)
+```
+
+---
+
+## Testing Checklist
+
+### Port Grouping
+
+- [ ] Nodes with explicit groups render correctly
+- [ ] Nodes without groups use auto-grouping (if >8 ports)
+- [ ] Nodes with few ports render flat (no groups)
+- [ ] Group headers display name and count
+- [ ] Click expands/collapses group
+- [ ] Collapsed group hides ports
+- [ ] Node height adjusts with collapse
+- [ ] Connections still work with grouped ports
+- [ ] Group state doesn't persist (intentional)
+
+### Port Type Icons
+
+- [ ] Icons render for all port types
+- [ ] Icons visible at 100% zoom
+- [ ] Icons visible at 50% zoom
+- [ ] Icons don't overlap labels
+- [ ] Color matches port state
+- [ ] Icons for unknown types fallback to 'any'
+
+### Connection Preview
+
+- [ ] Hovering output highlights compatible inputs
+- [ ] Hovering input highlights compatible outputs
+- [ ] Same node ports dimmed
+- [ ] Same direction ports dimmed
+- [ ] Type-incompatible ports dimmed
+- [ ] Highlight clears when mouse leaves
+- [ ] Highlight clears on pan/zoom
+- [ ] Performance acceptable with 50+ nodes
+
+### Integration
+
+- [ ] Grouping + icons work together
+- [ ] Grouping + connection preview work together
+- [ ] No regression on ungrouped nodes
+- [ ] Copy/paste works with grouped nodes
+
+---
+
+## Success Criteria
+
+- [ ] Port groups configurable per node type
+- [ ] Auto-grouping fallback for unconfigured nodes
+- [ ] Groups collapsible with visual feedback
+- [ ] Port type icons clear and minimal
+- [ ] Connection preview highlights compatible ports
+- [ ] Incompatible ports visually dimmed
+- [ ] Performance acceptable
+- [ ] No regression on existing functionality
+
+---
+
+## Rollback Plan
+
+**Port grouping:**
+
+- Revert `NodeGraphEditorNode.ts` measure/draw changes
+- Delete `portGrouping.ts`
+- Nodes will render flat (original behavior)
+
+**Type icons:**
+
+- Delete `portIcons.ts`
+- Remove icon drawing from port render
+- Ports will show dots/arrows only (original behavior)
+
+**Connection preview:**
+
+- Remove highlight state from `nodegrapheditor.ts`
+- Remove compatibility rendering from node
+- No visual change on hover (original behavior)
+
+All features are independent and can be rolled back separately.
+
+---
+
+## Future Enhancements (Out of Scope)
+
+- User-customizable port groups
+- Persistent group expand state per project
+- Search/filter ports within node
+- Port group templates (reusable across node types)
+- Connection line preview during hover
+- Animated highlight effects
diff --git a/packages/noodl-core-ui/src/components/inputs/LegacyIconButton/LegacyIconButton.tsx b/packages/noodl-core-ui/src/components/inputs/LegacyIconButton/LegacyIconButton.tsx
index eb6d863..ccf0398 100644
--- a/packages/noodl-core-ui/src/components/inputs/LegacyIconButton/LegacyIconButton.tsx
+++ b/packages/noodl-core-ui/src/components/inputs/LegacyIconButton/LegacyIconButton.tsx
@@ -1,49 +1,31 @@
-import classNames from 'classnames';
-import React, {
-  CSSProperties,
-  MouseEvent,
-  MouseEventHandler,
-  SyntheticEvent,
-} from 'react';
-import css from './LegacyIconButton.module.scss';
-
-export enum LegacyIconButtonIcon {
-  VerticalDots = 'vertical-dots',
-  Close = 'close',
-  CloseDark = 'close-dark',
-  CaretDown = 'caret-down',
-  Generate = 'generate',
-}
-
-export interface LegacyIconButtonProps {
-  icon: LegacyIconButtonIcon;
-  isRotated180?: boolean;
-  onClick?: MouseEventHandler<HTMLButtonElement>;
-  style?: CSSProperties;
-  testId?: string;
-}
-
-export function LegacyIconButton({
-  icon,
-  isRotated180,
-  style,
-  onClick,
-  testId,
-}: LegacyIconButtonProps) {
-  return (
-    <button
-      className={css['Root']}
-      onClick={onClick}
-      style={style}
-      data-test={testId}
-    >
-      <img
-        className={classNames([
-          css['Icon'],
-          isRotated180 && css['is-rotated-180'],
-        ])}
-        src={`../assets/icons/icon-button/${icon}.svg`}
-      />
-    </button>
-  );
-}
+import classNames from 'classnames';
+import React, { CSSProperties, MouseEvent, MouseEventHandler, SyntheticEvent } from 'react';
+
+import css from './LegacyIconButton.module.scss';
+
+export enum LegacyIconButtonIcon {
+  VerticalDots = 'vertical-dots',
+  Close = 'close',
+  CloseDark = 'close-dark',
+  CaretDown = 'caret-down',
+  Generate = 'generate'
+}
+
+export interface LegacyIconButtonProps {
+  icon: LegacyIconButtonIcon;
+  isRotated180?: boolean;
+  onClick?: MouseEventHandler<HTMLButtonElement>;
+  style?: CSSProperties;
+  testId?: string;
+}
+
+export function LegacyIconButton({ icon, isRotated180, style, onClick, testId }: LegacyIconButtonProps) {
+  return (
+    <button className={css['Root']} onClick={onClick} style={style} data-test={testId}>
+      <img
+        className={classNames([css['Icon'], isRotated180 && css['is-rotated-180']])}
+        src={`/assets/icons/icon-button/${icon}.svg`}
+      />
+    </button>
+  );
+}
diff --git a/packages/noodl-core-ui/src/components/inputs/TextInput/TextInput.module.scss b/packages/noodl-core-ui/src/components/inputs/TextInput/TextInput.module.scss
index 0ed9f05..e806765 100644
--- a/packages/noodl-core-ui/src/components/inputs/TextInput/TextInput.module.scss
+++ b/packages/noodl-core-ui/src/components/inputs/TextInput/TextInput.module.scss
@@ -103,12 +103,12 @@
   left: 0;
   visibility: hidden;
   height: 0;
-  overflow: overlay;
+  overflow: hidden;
   white-space: pre;
 }
 
 .InputWrapper {
-  overflow-x: overlay;
+  overflow-x: hidden;
   flex-grow: 1;
   padding-top: 1px;
 }
diff --git a/packages/noodl-core-ui/src/components/inputs/ToggleSwitch/ToggleSwitch.module.scss b/packages/noodl-core-ui/src/components/inputs/ToggleSwitch/ToggleSwitch.module.scss
index 0dd0365..6297576 100644
--- a/packages/noodl-core-ui/src/components/inputs/ToggleSwitch/ToggleSwitch.module.scss
+++ b/packages/noodl-core-ui/src/components/inputs/ToggleSwitch/ToggleSwitch.module.scss
@@ -1,38 +1,38 @@
-.Root {
-}
-
-.Track {
-  box-sizing: border-box;
-  height: 24px;
-  width: 42px;
-  border-radius: 12px;
-  background-color: var(--theme-color-bg-1);
-  cursor: pointer;
-  display: flex;
-  align-items: center;
-  padding: 3px;
-  margin-left: 8px;
-  margin-right: 8px;
-}
-
-.Indicator {
-  width: 18px;
-  height: 18px;
-  border-radius: 50%;
-  background-color: var(--theme-color-bg-3);
-  transition: transform var(--speed-quick) var(--easing-base),
-    background-color var(--speed-quick) var(--easing-base);
-
-  &.is-checked {
-    transform: translateX(100%);
-  }
-
-  &.is-always-active-color,
-  &.is-checked {
-    background-color: var(--theme-color-secondary-bright);
-  }
-}
-
-.Input {
-  display: none;
-}
+.Root {
+}
+
+.Track {
+  box-sizing: border-box;
+  height: 24px;
+  width: 42px;
+  border-radius: 12px;
+  background-color: var(--theme-color-bg-3);
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  padding: 3px;
+  margin-left: 8px;
+  margin-right: 8px;
+  border: 1px solid var(--theme-color-border-default);
+}
+
+.Indicator {
+  width: 18px;
+  height: 18px;
+  border-radius: 50%;
+  background-color: var(--theme-color-bg-3);
+  transition: transform var(--speed-quick) var(--easing-base), background-color var(--speed-quick) var(--easing-base);
+
+  &.is-checked {
+    transform: translateX(100%);
+  }
+
+  &.is-always-active-color,
+  &.is-checked {
+    background-color: var(--theme-color-secondary-bright);
+  }
+}
+
+.Input {
+  display: none;
+}
diff --git a/packages/noodl-core-ui/src/components/popups/MenuDialog/MenuDialog.module.scss b/packages/noodl-core-ui/src/components/popups/MenuDialog/MenuDialog.module.scss
index 21d87fe..05bf827 100644
--- a/packages/noodl-core-ui/src/components/popups/MenuDialog/MenuDialog.module.scss
+++ b/packages/noodl-core-ui/src/components/popups/MenuDialog/MenuDialog.module.scss
@@ -1,97 +1,105 @@
-.Root {
-  padding: 4px;
-  max-height: 400px;
-  overflow: hidden overlay;
-
-  &.is-width-small {
-    width: 140px;
-  }
-
-  &.is-width-default {
-    width: 200px;
-  }
-
-  &.is-width-medium {
-    width: 250px;
-  }
-
-  &.is-width-large {
-    width: 400px;
-  }
-}
-
-.Item {
-  padding: 8px;
-  cursor: pointer;
-  border-radius: 1px;
-  transition: background-color var(--speed-turbo) var(--easing-base);
-
-  &.is-highlighted:not(.is-disabled) {
-    background-color: var(--theme-color-secondary-highlight);
-
-    h2 {
-      color: var(--theme-color-on-secondary);
-    }
-  }
-
-  &.is-danger {
-    .Icon path {
-      fill: var(--theme-color-danger) !important;
-    }
-  }
-
-  &.is-disabled {
-    .Icon path {
-      fill: var(--theme-color-fg-muted);
-    }
-
-    .Label span {
-      color: var(--theme-color-fg-muted);
-    }
-  }
-
-  &:not(.has-component):not(.is-highlighted):not(.is-disabled):hover {
-    background-color: var(--theme-color-bg-3);
-
-    .Label span {
-      color: var(--theme-color-fg-highlight);
-    }
-
-    &.is-danger .Label span {
-      color: var(--theme-color-danger);
-    }
-  }
-}
-
-.Label {
-  display: flex;
-  align-items: center;
-
-  &.has-bottom-spacing {
-    padding-bottom: 8px;
-  }
-}
-
-.Icon {
-  margin: -4px 8px -4px 0;
-
-  path {
-    fill: var(--theme-color-fg-default-contrast);
-
-    .Item:not(.has-component):not(.is-disabled):hover & {
-      fill: var(--theme-color-fg-highlight);
-    }
-  }
-}
-
-.Divider {
-  width: calc(100% + 8px);
-  height: 1px;
-  background-color: var(--theme-color-bg-3);
-  margin: 4px -4px;
-}
-
-.EndSlot {
-  display: flex;
-  align-items: center;
-}
+.Root {
+  padding: 4px;
+  max-height: 400px;
+  overflow: hidden overlay;
+
+  &.is-width-small {
+    width: 140px;
+  }
+
+  &.is-width-default {
+    width: 200px;
+  }
+
+  &.is-width-medium {
+    width: 250px;
+  }
+
+  &.is-width-large {
+    width: 400px;
+  }
+}
+
+.Item {
+  padding: 8px;
+  cursor: pointer;
+  border-radius: 1px;
+  transition: background-color var(--speed-turbo) var(--easing-base);
+
+  &.is-highlighted:not(.is-disabled) {
+    background-color: var(--theme-color-primary);
+
+    h2 {
+      color: var(--theme-color-on-primary);
+    }
+
+    .Label span {
+      color: var(--theme-color-on-primary);
+    }
+
+    .Icon path {
+      fill: var(--theme-color-on-primary);
+    }
+  }
+
+  &.is-danger {
+    .Icon path {
+      fill: var(--theme-color-danger) !important;
+    }
+  }
+
+  &.is-disabled {
+    .Icon path {
+      fill: var(--theme-color-fg-muted);
+    }
+
+    .Label span {
+      color: var(--theme-color-fg-muted);
+    }
+  }
+
+  &:not(.has-component):not(.is-highlighted):not(.is-disabled):hover {
+    background-color: var(--theme-color-bg-3);
+
+    .Label span {
+      color: var(--theme-color-fg-highlight);
+    }
+
+    &.is-danger .Label span {
+      color: var(--theme-color-danger);
+    }
+  }
+}
+
+.Label {
+  display: flex;
+  align-items: center;
+
+  &.has-bottom-spacing {
+    padding-bottom: 8px;
+  }
+}
+
+.Icon {
+  margin: -4px 8px -4px 0;
+
+  path {
+    fill: var(--theme-color-fg-default-contrast);
+
+    .Item:not(.has-component):not(.is-disabled):hover & {
+      fill: var(--theme-color-fg-highlight);
+    }
+  }
+}
+
+.Divider {
+  width: calc(100% + 8px);
+  height: 1px;
+  background-color: var(--theme-color-bg-3);
+  margin: 4px -4px;
+}
+
+.EndSlot {
+  display: flex;
+  align-items: center;
+}
diff --git a/packages/noodl-core-ui/src/preview/launcher/Launcher/Launcher.tsx b/packages/noodl-core-ui/src/preview/launcher/Launcher/Launcher.tsx
index a5ea5bf..bcd569b 100644
--- a/packages/noodl-core-ui/src/preview/launcher/Launcher/Launcher.tsx
+++ b/packages/noodl-core-ui/src/preview/launcher/Launcher/Launcher.tsx
@@ -199,6 +199,16 @@ export function Launcher({
     }
   });
 
+  // Folder selection state with localStorage persistence
+  const [selectedFolderId, setSelectedFolderId] = useState<string | null>(() => {
+    try {
+      const stored = localStorage.getItem('launcher:selectedFolderId');
+      return stored === 'null' ? null : stored;
+    } catch {
+      return null; // Default to "All Projects"
+    }
+  });
+
   // Persist view mode changes
   useEffect(() => {
     try {
@@ -219,6 +229,15 @@ export function Launcher({
     }
   }, [useMockData, projects]);
 
+  // Persist folder selection
+  useEffect(() => {
+    try {
+      localStorage.setItem('launcher:selectedFolderId', selectedFolderId === null ? 'null' : selectedFolderId);
+    } catch (error) {
+      console.warn('Failed to persist folder selection:', error);
+    }
+  }, [selectedFolderId]);
+
   // Determine which projects to use and if toggle should be available
   const hasRealProjects = Boolean(projects && projects.length > 0);
   const activeProjects = useMockData ? MOCK_PROJECTS : projects || MOCK_PROJECTS;
@@ -264,6 +283,8 @@ export function Launcher({
         setUseMockData,
         projects: activeProjects,
         hasRealProjects,
+        selectedFolderId,
+        setSelectedFolderId,
         onCreateProject,
         onOpenProject,
         onLaunchProject,
diff --git a/packages/noodl-core-ui/src/preview/launcher/Launcher/LauncherContext.tsx b/packages/noodl-core-ui/src/preview/launcher/Launcher/LauncherContext.tsx
index 2a98b99..b67f290 100644
--- a/packages/noodl-core-ui/src/preview/launcher/Launcher/LauncherContext.tsx
+++ b/packages/noodl-core-ui/src/preview/launcher/Launcher/LauncherContext.tsx
@@ -26,6 +26,10 @@ export interface LauncherContextValue {
   projects: LauncherProjectData[];
   hasRealProjects: boolean; // Indicates if real projects were provided to Launcher
 
+  // Folder organization
+  selectedFolderId: string | null;
+  setSelectedFolderId: (folderId: string | null) => void;
+
   // Project management callbacks
   onCreateProject?: () => void;
   onOpenProject?: () => void;
diff --git a/packages/noodl-core-ui/src/preview/launcher/Launcher/components/FolderTree/FolderTree.module.scss b/packages/noodl-core-ui/src/preview/launcher/Launcher/components/FolderTree/FolderTree.module.scss
new file mode 100644
index 0000000..2d674cb
--- /dev/null
+++ b/packages/noodl-core-ui/src/preview/launcher/Launcher/components/FolderTree/FolderTree.module.scss
@@ -0,0 +1,200 @@
+/**
+ * FolderTree Styles
+ */
+
+.Root {
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-2);
+  padding: var(--spacing-2);
+  height: 100%;
+}
+
+.VirtualFolders {
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-1);
+}
+
+.Divider {
+  height: 1px;
+  background-color: var(--theme-color-border-default);
+  margin: var(--spacing-2) 0;
+}
+
+.UserFolders {
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-1);
+  flex: 1;
+  overflow-y: auto;
+}
+
+.RenameInput {
+  padding: var(--spacing-1) var(--spacing-2);
+}
+
+.RenameInputField {
+  width: 100%;
+  padding: var(--spacing-2);
+  background-color: var(--theme-color-bg-2);
+  border: 1px solid var(--theme-color-border-default);
+  border-radius: var(--radius-default);
+  color: var(--theme-color-fg-default);
+  font-size: var(--theme-font-size-default);
+  outline: none;
+
+  &:focus {
+    border-color: var(--theme-color-primary);
+  }
+}
+
+.NewFolderButton {
+  display: flex;
+  align-items: center;
+  gap: var(--spacing-2);
+  padding: var(--spacing-2) var(--spacing-3);
+  margin-bottom: var(--spacing-4);
+  background: none;
+  border: 1px dashed var(--theme-color-border-default);
+  border-radius: var(--radius-default);
+  color: var(--theme-color-fg-default-shy);
+  cursor: pointer;
+  transition: all 0.15s ease;
+  font-size: var(--theme-font-size-default);
+
+  &:hover {
+    background-color: var(--theme-color-bg-3);
+    border-color: var(--theme-color-border-highlight);
+    color: var(--theme-color-fg-default);
+  }
+
+  &:active {
+    background-color: var(--theme-color-bg-4);
+  }
+}
+
+.NewFolderIcon {
+  display: flex;
+  flex-shrink: 0;
+}
+
+.NewFolderLabel {
+  flex: 1;
+  text-align: left;
+}
+
+.CreateFolderInput {
+  padding: var(--spacing-1) var(--spacing-2);
+}
+
+.CreateFolderInputField {
+  width: 100%;
+  padding: var(--spacing-2);
+  background-color: var(--theme-color-bg-2);
+  border: 1px solid var(--theme-color-primary);
+  border-radius: var(--radius-default);
+  color: var(--theme-color-fg-default);
+  font-size: var(--theme-font-size-default);
+  outline: none;
+
+  &::placeholder {
+    color: var(--theme-color-fg-default-shy);
+  }
+}
+
+/* Delete Confirmation Dialog */
+.DeleteConfirmation {
+  position: fixed;
+  top: 0;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  z-index: 1000;
+}
+
+.DeleteConfirmationBackdrop {
+  position: absolute;
+  top: 0;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  background-color: rgba(0, 0, 0, 0.5);
+}
+
+.DeleteConfirmationDialog {
+  position: relative;
+  background-color: var(--theme-color-bg-2);
+  border: 1px solid var(--theme-color-border-default);
+  border-radius: var(--radius-lg);
+  padding: var(--spacing-6);
+  min-width: 400px;
+  max-width: 500px;
+  box-shadow: 0 8px 32px rgba(0, 0, 0, 0.3);
+  z-index: 1001;
+}
+
+.DeleteConfirmationTitle {
+  font-size: 20px;
+  font-weight: 600;
+  color: var(--theme-color-fg-default);
+  margin: 0 0 var(--spacing-3) 0;
+  line-height: 1.3;
+}
+
+.DeleteConfirmationMessage {
+  font-size: var(--theme-font-size-default);
+  color: var(--theme-color-fg-default);
+  margin-bottom: var(--spacing-6);
+  line-height: 1.5;
+}
+
+.DeleteConfirmationButtons {
+  display: flex;
+  gap: var(--spacing-3);
+  justify-content: flex-end;
+}
+
+.DeleteConfirmationCancelButton {
+  padding: var(--spacing-2) var(--spacing-4);
+  background-color: var(--theme-color-bg-3);
+  border: 1px solid var(--theme-color-border-default);
+  border-radius: var(--radius-default);
+  color: var(--theme-color-fg-default);
+  font-size: var(--theme-font-size-default);
+  cursor: pointer;
+  transition: all 0.15s ease;
+
+  &:hover {
+    background-color: var(--theme-color-bg-4);
+    border-color: var(--theme-color-border-highlight);
+  }
+
+  &:active {
+    transform: scale(0.98);
+  }
+}
+
+.DeleteConfirmationDeleteButton {
+  padding: var(--spacing-2) var(--spacing-4);
+  background-color: var(--theme-color-danger);
+  border: 1px solid var(--theme-color-danger);
+  border-radius: var(--radius-default);
+  color: white;
+  font-size: var(--theme-font-size-default);
+  font-weight: var(--theme-font-weight-medium);
+  cursor: pointer;
+  transition: all 0.15s ease;
+
+  &:hover {
+    background-color: var(--theme-color-danger-hover);
+    border-color: var(--theme-color-danger-hover);
+  }
+
+  &:active {
+    transform: scale(0.98);
+  }
+}
diff --git a/packages/noodl-core-ui/src/preview/launcher/Launcher/components/FolderTree/FolderTree.tsx b/packages/noodl-core-ui/src/preview/launcher/Launcher/components/FolderTree/FolderTree.tsx
new file mode 100644
index 0000000..ad77b07
--- /dev/null
+++ b/packages/noodl-core-ui/src/preview/launcher/Launcher/components/FolderTree/FolderTree.tsx
@@ -0,0 +1,276 @@
+/**
+ * FolderTree - Project organization folder tree
+ *
+ * Displays virtual folders (All Projects, Uncategorized) and user-created folders
+ * with expand/collapse functionality and folder management actions.
+ *
+ * @module noodl-core-ui/preview/launcher
+ */
+
+import React, { useState } from 'react';
+
+import { Icon, IconName, IconSize } from '@noodl-core-ui/components/common/Icon';
+import { FolderTreeItem } from '@noodl-core-ui/preview/launcher/Launcher/components/FolderTreeItem';
+import { Folder, useProjectOrganization } from '@noodl-core-ui/preview/launcher/Launcher/hooks/useProjectOrganization';
+
+import css from './FolderTree.module.scss';
+
+export interface FolderTreeProps {
+  /** Currently selected folder ID (null for "All Projects", 'uncategorized' for uncategorized) */
+  selectedFolderId: string | null;
+  /** Called when a folder is selected */
+  onFolderSelect: (folderId: string | null) => void;
+  /** Total number of projects */
+  totalProjectCount: number;
+  /** Number of projects without a folder */
+  uncategorizedProjectCount: number;
+}
+
+/**
+ * FolderTree displays the project organization structure:
+ * - Virtual folders ("All Projects", "Uncategorized")
+ * - User-created folders with expand/collapse
+ * - "+ New Folder" button
+ */
+export function FolderTree({
+  selectedFolderId,
+  onFolderSelect,
+  totalProjectCount,
+  uncategorizedProjectCount
+}: FolderTreeProps) {
+  const { folders, createFolder, renameFolder, deleteFolder, getProjectCountInFolder } = useProjectOrganization();
+
+  // Track expanded folders (folder IDs that are expanded)
+  const [expandedFolderIds, setExpandedFolderIds] = useState<Set<string>>(new Set());
+
+  // Track folder being renamed
+  const [renamingFolderId, setRenamingFolderId] = useState<string | null>(null);
+  const [renameValue, setRenameValue] = useState('');
+
+  // Track new folder creation
+  const [isCreatingFolder, setIsCreatingFolder] = useState(false);
+  const [newFolderName, setNewFolderName] = useState('');
+
+  // Track folder deletion confirmation
+  const [deletingFolder, setDeletingFolder] = useState<Folder | null>(null);
+
+  const toggleExpand = (folderId: string) => {
+    setExpandedFolderIds((prev) => {
+      const next = new Set(prev);
+      if (next.has(folderId)) {
+        next.delete(folderId);
+      } else {
+        next.add(folderId);
+      }
+      return next;
+    });
+  };
+
+  const handleCreateFolder = () => {
+    setIsCreatingFolder(true);
+    setNewFolderName('');
+  };
+
+  const handleCreateFolderSubmit = () => {
+    if (newFolderName.trim()) {
+      createFolder(newFolderName.trim());
+    }
+    setIsCreatingFolder(false);
+    setNewFolderName('');
+  };
+
+  const handleCreateFolderCancel = () => {
+    setIsCreatingFolder(false);
+    setNewFolderName('');
+  };
+
+  const handleRenameFolder = (folder: Folder) => {
+    setRenamingFolderId(folder.id);
+    setRenameValue(folder.name);
+  };
+
+  const handleRenameSubmit = (folderId: string) => {
+    if (renameValue.trim()) {
+      renameFolder(folderId, renameValue.trim());
+    }
+    setRenamingFolderId(null);
+    setRenameValue('');
+  };
+
+  const handleRenameCancel = () => {
+    setRenamingFolderId(null);
+    setRenameValue('');
+  };
+
+  const handleDeleteFolder = (folder: Folder) => {
+    setDeletingFolder(folder);
+  };
+
+  const handleDeleteFolderConfirm = () => {
+    if (deletingFolder) {
+      deleteFolder(deletingFolder.id);
+      // If deleted folder was selected, reset to "All Projects"
+      if (selectedFolderId === deletingFolder.id) {
+        onFolderSelect(null);
+      }
+      setDeletingFolder(null);
+    }
+  };
+
+  const handleDeleteFolderCancel = () => {
+    setDeletingFolder(null);
+  };
+
+  // Organize folders into root and nested
+  const rootFolders = folders.filter((f) => f.parentId === null);
+  const getFolderChildren = (parentId: string) => {
+    return folders.filter((f) => f.parentId === parentId);
+  };
+
+  return (
+    <div className={css['Root']}>
+      {/* Virtual Folders */}
+      <div className={css['VirtualFolders']}>
+        {/* All Projects */}
+        <FolderTreeItem
+          folder={{ id: 'all', name: 'All Projects', parentId: null, order: 0, createdAt: '' }}
+          projectCount={totalProjectCount}
+          isSelected={selectedFolderId === null}
+          onClick={() => onFolderSelect(null)}
+        />
+
+        {/* Uncategorized */}
+        <FolderTreeItem
+          folder={{
+            id: 'uncategorized',
+            name: 'Uncategorized',
+            parentId: null,
+            order: 1,
+            createdAt: ''
+          }}
+          projectCount={uncategorizedProjectCount}
+          isSelected={selectedFolderId === 'uncategorized'}
+          onClick={() => onFolderSelect('uncategorized')}
+        />
+      </div>
+
+      {/* Divider */}
+      {rootFolders.length > 0 && <div className={css['Divider']} />}
+
+      {/* User Folders */}
+      <div className={css['UserFolders']}>
+        {rootFolders.map((folder) => {
+          const children = getFolderChildren(folder.id);
+          const isExpanded = expandedFolderIds.has(folder.id);
+          const projectCount = getProjectCountInFolder(folder.id);
+
+          return (
+            <div key={folder.id}>
+              {renamingFolderId === folder.id ? (
+                <div className={css['RenameInput']}>
+                  <input
+                    type="text"
+                    value={renameValue}
+                    onChange={(e) => setRenameValue(e.target.value)}
+                    onKeyDown={(e) => {
+                      if (e.key === 'Enter') {
+                        handleRenameSubmit(folder.id);
+                      } else if (e.key === 'Escape') {
+                        handleRenameCancel();
+                      }
+                    }}
+                    onBlur={() => handleRenameSubmit(folder.id)}
+                    autoFocus
+                    className={css['RenameInputField']}
+                  />
+                </div>
+              ) : (
+                <FolderTreeItem
+                  folder={folder}
+                  projectCount={projectCount}
+                  isSelected={selectedFolderId === folder.id}
+                  hasChildren={children.length > 0}
+                  isExpanded={isExpanded}
+                  onClick={() => onFolderSelect(folder.id)}
+                  onToggleExpand={() => toggleExpand(folder.id)}
+                  onRename={() => handleRenameFolder(folder)}
+                  onDelete={() => handleDeleteFolder(folder)}
+                />
+              )}
+
+              {/* Render children if expanded */}
+              {isExpanded &&
+                children.map((childFolder) => {
+                  const childProjectCount = getProjectCountInFolder(childFolder.id);
+                  return (
+                    <FolderTreeItem
+                      key={childFolder.id}
+                      folder={childFolder}
+                      projectCount={childProjectCount}
+                      isSelected={selectedFolderId === childFolder.id}
+                      level={1}
+                      onClick={() => onFolderSelect(childFolder.id)}
+                      onRename={() => handleRenameFolder(childFolder)}
+                      onDelete={() => handleDeleteFolder(childFolder)}
+                    />
+                  );
+                })}
+            </div>
+          );
+        })}
+      </div>
+
+      {/* New Folder Button */}
+      {isCreatingFolder ? (
+        <div className={css['CreateFolderInput']}>
+          <input
+            type="text"
+            value={newFolderName}
+            onChange={(e) => setNewFolderName(e.target.value)}
+            onKeyDown={(e) => {
+              if (e.key === 'Enter') {
+                handleCreateFolderSubmit();
+              } else if (e.key === 'Escape') {
+                handleCreateFolderCancel();
+              }
+            }}
+            onBlur={handleCreateFolderSubmit}
+            placeholder="Folder name..."
+            autoFocus
+            className={css['CreateFolderInputField']}
+          />
+        </div>
+      ) : (
+        <button className={css['NewFolderButton']} onClick={handleCreateFolder}>
+          <Icon icon={IconName.Plus} size={IconSize.Small} UNSAFE_className={css['NewFolderIcon']} />
+          <span className={css['NewFolderLabel']}>New Folder</span>
+        </button>
+      )}
+
+      {/* Delete Confirmation Overlay */}
+      {deletingFolder && (
+        <div className={css['DeleteConfirmation']}>
+          <div className={css['DeleteConfirmationBackdrop']} onClick={handleDeleteFolderCancel} />
+          <div className={css['DeleteConfirmationDialog']}>
+            <div className={css['DeleteConfirmationTitle']}>Delete Folder</div>
+            <div className={css['DeleteConfirmationMessage']}>
+              {getProjectCountInFolder(deletingFolder.id) > 0
+                ? `Delete "${deletingFolder.name}"? ${getProjectCountInFolder(
+                    deletingFolder.id
+                  )} project(s) will be moved to Uncategorized.`
+                : `Delete "${deletingFolder.name}"?`}
+            </div>
+            <div className={css['DeleteConfirmationButtons']}>
+              <button className={css['DeleteConfirmationCancelButton']} onClick={handleDeleteFolderCancel}>
+                Cancel
+              </button>
+              <button className={css['DeleteConfirmationDeleteButton']} onClick={handleDeleteFolderConfirm}>
+                Delete
+              </button>
+            </div>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}
diff --git a/packages/noodl-core-ui/src/preview/launcher/Launcher/components/FolderTree/index.ts b/packages/noodl-core-ui/src/preview/launcher/Launcher/components/FolderTree/index.ts
new file mode 100644
index 0000000..8b0000e
--- /dev/null
+++ b/packages/noodl-core-ui/src/preview/launcher/Launcher/components/FolderTree/index.ts
@@ -0,0 +1,2 @@
+export { FolderTree } from './FolderTree';
+export type { FolderTreeProps } from './FolderTree';
diff --git a/packages/noodl-core-ui/src/preview/launcher/Launcher/components/FolderTreeItem/FolderTreeItem.module.scss b/packages/noodl-core-ui/src/preview/launcher/Launcher/components/FolderTreeItem/FolderTreeItem.module.scss
new file mode 100644
index 0000000..b75a8ab
--- /dev/null
+++ b/packages/noodl-core-ui/src/preview/launcher/Launcher/components/FolderTreeItem/FolderTreeItem.module.scss
@@ -0,0 +1,87 @@
+/**
+ * FolderTreeItem Styles
+ */
+
+.Root {
+  display: flex;
+  align-items: center;
+  gap: var(--spacing-2);
+  padding: var(--spacing-1-5) var(--spacing-2);
+  border-radius: var(--radius-default);
+  cursor: pointer;
+  transition: background-color 0.15s ease;
+  min-height: 32px;
+  user-select: none;
+
+  &:hover {
+    background-color: var(--theme-color-bg-3);
+  }
+
+  &--selected {
+    background-color: var(--theme-color-bg-4);
+
+    &:hover {
+      background-color: var(--theme-color-bg-4);
+    }
+  }
+}
+
+.Chevron {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 0;
+  background: none;
+  border: none;
+  cursor: pointer;
+  color: var(--theme-color-fg-default-shy);
+  transition: color 0.15s ease;
+  flex-shrink: 0;
+
+  &:hover {
+    color: var(--theme-color-fg-default);
+  }
+}
+
+.ChevronIcon {
+  display: flex;
+}
+
+.FolderIcon {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  color: var(--theme-color-fg-default-shy);
+  flex-shrink: 0;
+}
+
+.Icon {
+  display: flex;
+}
+
+.FolderName {
+  flex: 1;
+  min-width: 0; /* Allow text truncation */
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.Badge {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 0 var(--spacing-1-5);
+  background-color: var(--theme-color-bg-3);
+  border-radius: var(--radius-full);
+  min-width: 20px;
+  height: 18px;
+  flex-shrink: 0;
+}
+
+.ContextMenuTrigger {
+  display: flex;
+  align-items: center;
+  margin-left: auto;
+  flex-shrink: 0;
+}
diff --git a/packages/noodl-core-ui/src/preview/launcher/Launcher/components/FolderTreeItem/FolderTreeItem.tsx b/packages/noodl-core-ui/src/preview/launcher/Launcher/components/FolderTreeItem/FolderTreeItem.tsx
new file mode 100644
index 0000000..18868e4
--- /dev/null
+++ b/packages/noodl-core-ui/src/preview/launcher/Launcher/components/FolderTreeItem/FolderTreeItem.tsx
@@ -0,0 +1,148 @@
+/**
+ * FolderTreeItem - Individual folder row in the folder tree
+ *
+ * Displays a folder with icon, name, project count badge, and context menu.
+ * Supports nested folders with expand/collapse chevron.
+ *
+ * @module noodl-core-ui/preview/launcher
+ */
+
+import classNames from 'classnames';
+import React, { useState } from 'react';
+
+import { Icon, IconName, IconSize } from '@noodl-core-ui/components/common/Icon';
+import { ContextMenu, ContextMenuProps } from '@noodl-core-ui/components/popups/ContextMenu';
+import { Label, LabelSize } from '@noodl-core-ui/components/typography/Label';
+import { TextType } from '@noodl-core-ui/components/typography/Text';
+import { Folder } from '@noodl-core-ui/preview/launcher/Launcher/hooks/useProjectOrganization';
+
+import css from './FolderTreeItem.module.scss';
+
+export interface FolderTreeItemProps {
+  folder: Folder;
+  /** Project count in this folder */
+  projectCount: number;
+  /** Whether this folder is currently selected for filtering */
+  isSelected?: boolean;
+  /** Whether this folder has nested children */
+  hasChildren?: boolean;
+  /** Whether children are expanded (only relevant if hasChildren is true) */
+  isExpanded?: boolean;
+  /** Indentation level for nested folders (0 = root) */
+  level?: number;
+  /** Called when folder is clicked for filtering */
+  onClick?: () => void;
+  /** Called when expand/collapse chevron is clicked */
+  onToggleExpand?: () => void;
+  /** Called when rename is requested */
+  onRename?: () => void;
+  /** Called when delete is requested */
+  onDelete?: () => void;
+}
+
+/**
+ * FolderTreeItem displays a single folder in the tree with:
+ * - Folder icon (open/closed based on expansion)
+ * - Folder name
+ * - Project count badge
+ * - Context menu for rename/delete
+ * - Expand/collapse chevron for nested folders
+ */
+export function FolderTreeItem({
+  folder,
+  projectCount,
+  isSelected = false,
+  hasChildren = false,
+  isExpanded = false,
+  level = 0,
+  onClick,
+  onToggleExpand,
+  onRename,
+  onDelete
+}: FolderTreeItemProps) {
+  const [isHovered, setIsHovered] = useState(false);
+
+  const handleChevronClick = (e: React.MouseEvent) => {
+    e.stopPropagation();
+    onToggleExpand?.();
+  };
+
+  const contextMenuItems: ContextMenuProps['menuItems'] = [
+    {
+      label: 'Rename folder',
+      icon: IconName.PencilLine,
+      onClick: () => onRename?.()
+    },
+    'divider',
+    {
+      label: 'Delete folder',
+      icon: IconName.Trash,
+      onClick: () => onDelete?.(),
+      isDangerous: true
+    }
+  ];
+
+  const paddingLeft = 8 + level * 16; // Base padding + indent per level
+
+  return (
+    <div
+      className={classNames(css['Root'], {
+        [css['Root--selected']]: isSelected,
+        [css['Root--hasChildren']]: hasChildren
+      })}
+      style={{ paddingLeft: `${paddingLeft}px` }}
+      onClick={onClick}
+      onMouseEnter={() => setIsHovered(true)}
+      onMouseLeave={() => setIsHovered(false)}
+    >
+      {/* Expand/Collapse Chevron */}
+      {hasChildren && (
+        <button
+          className={css['Chevron']}
+          onClick={handleChevronClick}
+          aria-label={isExpanded ? 'Collapse folder' : 'Expand folder'}
+        >
+          <Icon
+            icon={isExpanded ? IconName.CaretDown : IconName.CaretRight}
+            size={IconSize.Small}
+            UNSAFE_className={css['ChevronIcon']}
+          />
+        </button>
+      )}
+
+      {/* Folder Icon */}
+      <div className={css['FolderIcon']}>
+        <Icon
+          icon={isExpanded ? IconName.FolderOpen : IconName.FolderClosed}
+          size={IconSize.Default}
+          UNSAFE_className={css['Icon']}
+        />
+      </div>
+
+      {/* Folder Name */}
+      <Label
+        size={LabelSize.Default}
+        variant={isSelected ? TextType.Default : TextType.Shy}
+        UNSAFE_className={css['FolderName']}
+      >
+        {folder.name}
+      </Label>
+
+      {/* Project Count Badge */}
+      {projectCount > 0 && (
+        <span className={css['Badge']}>
+          <Label size={LabelSize.Small} variant={TextType.Shy}>
+            {String(projectCount)}
+          </Label>
+        </span>
+      )}
+
+      {/* Context Menu */}
+      {isHovered && (
+        <div className={css['ContextMenuTrigger']} onClick={(e) => e.stopPropagation()}>
+          <ContextMenu menuItems={contextMenuItems} />
+        </div>
+      )}
+    </div>
+  );
+}
diff --git a/packages/noodl-core-ui/src/preview/launcher/Launcher/components/FolderTreeItem/index.ts b/packages/noodl-core-ui/src/preview/launcher/Launcher/components/FolderTreeItem/index.ts
new file mode 100644
index 0000000..e7403e2
--- /dev/null
+++ b/packages/noodl-core-ui/src/preview/launcher/Launcher/components/FolderTreeItem/index.ts
@@ -0,0 +1,2 @@
+export { FolderTreeItem } from './FolderTreeItem';
+export type { FolderTreeItemProps } from './FolderTreeItem';
diff --git a/packages/noodl-core-ui/src/preview/launcher/Launcher/components/LauncherProjectCard/LauncherProjectCard.tsx b/packages/noodl-core-ui/src/preview/launcher/Launcher/components/LauncherProjectCard/LauncherProjectCard.tsx
index cfcda84..9e2dbb7 100644
--- a/packages/noodl-core-ui/src/preview/launcher/Launcher/components/LauncherProjectCard/LauncherProjectCard.tsx
+++ b/packages/noodl-core-ui/src/preview/launcher/Launcher/components/LauncherProjectCard/LauncherProjectCard.tsx
@@ -19,6 +19,8 @@ import { Title, TitleSize } from '@noodl-core-ui/components/typography/Title';
 import { UserBadgeProps, UserBadgeSize } from '@noodl-core-ui/components/user/UserBadge';
 import { UserBadgeList } from '@noodl-core-ui/components/user/UserBadgeList';
 
+import { useProjectOrganization } from '../../hooks/useProjectOrganization';
+import { TagPill, TagPillSize } from '../TagPill';
 import css from './LauncherProjectCard.module.scss';
 
 // FIXME: Use the timeSince function from the editor package when this is moved there
@@ -73,26 +75,31 @@ export interface LauncherProjectData {
 
 export interface LauncherProjectCardProps extends LauncherProjectData {
   contextMenuItems: ContextMenuProps[];
+  onClick?: () => void;
 }
 
 export function LauncherProjectCard({
   id,
   title,
   cloudSyncMeta,
+  localPath,
   lastOpened,
   pullAmount,
   pushAmount,
   uncommittedChangesAmount,
   imageSrc,
   contextMenuItems,
-  contributors
+  contributors,
+  onClick
 }: LauncherProjectCardProps) {
+  const { tags, getProjectMeta } = useProjectOrganization();
+
+  // Get project tags
+  const projectMeta = getProjectMeta(localPath);
+  const projectTags = projectMeta ? tags.filter((tag) => projectMeta.tagIds.includes(tag.id)) : [];
+
   return (
-    <Card
-      background={CardBackground.Bg2}
-      hoverBackground={CardBackground.Bg3}
-      onClick={() => alert('FIXME: open project')}
-    >
+    <Card background={CardBackground.Bg2} hoverBackground={CardBackground.Bg3} onClick={onClick}>
       <Stack direction="row">
         <div className={css.Image} style={{ backgroundImage: `url(${imageSrc})` }} />
 
@@ -102,6 +109,16 @@ export function LauncherProjectCard({
               <Title hasBottomSpacing size={TitleSize.Medium}>
                 {title}
               </Title>
+
+              {/* Tags */}
+              {projectTags.length > 0 && (
+                <HStack hasSpacing={2} UNSAFE_style={{ marginBottom: 'var(--spacing-2)', flexWrap: 'wrap' }}>
+                  {projectTags.map((tag) => (
+                    <TagPill key={tag.id} tag={tag} size={TagPillSize.Small} />
+                  ))}
+                </HStack>
+              )}
+
               <Label variant={TextType.Shy}>Last opened {timeSince(new Date(lastOpened))} ago</Label>
             </div>
 
diff --git a/packages/noodl-core-ui/src/preview/launcher/Launcher/components/TagPill/TagPill.module.scss b/packages/noodl-core-ui/src/preview/launcher/Launcher/components/TagPill/TagPill.module.scss
new file mode 100644
index 0000000..fce6ff1
--- /dev/null
+++ b/packages/noodl-core-ui/src/preview/launcher/Launcher/components/TagPill/TagPill.module.scss
@@ -0,0 +1,80 @@
+/**
+ * TagPill Styles
+ *
+ * Small colored pill displaying a tag name.
+ * Uses tag.color for background, white text for readability.
+ */
+
+.Root {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--spacing-2);
+  border-radius: 12px;
+  transition: opacity 0.15s ease;
+  user-select: none;
+  flex-shrink: 0;
+
+  &.Clickable {
+    cursor: pointer;
+
+    &:hover {
+      opacity: 0.85;
+    }
+
+    &:active {
+      opacity: 0.7;
+    }
+
+    &:focus-visible {
+      outline: 2px solid var(--theme-color-primary);
+      outline-offset: 2px;
+    }
+  }
+}
+
+/* Size Variants */
+.Size-small {
+  padding: 2px 8px;
+  min-height: 20px;
+}
+
+.Size-medium {
+  padding: 4px 10px;
+  min-height: 24px;
+}
+
+/* Label */
+.Label {
+  color: #ffffff;
+  font-weight: 500;
+  line-height: 1;
+  white-space: nowrap;
+}
+
+/* Remove Button */
+.RemoveButton {
+  all: unset;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  padding: 0;
+  margin-left: 2px;
+  cursor: pointer;
+  color: #ffffff;
+  opacity: 0.7;
+  transition: opacity 0.15s ease;
+  border-radius: 4px;
+
+  &:hover {
+    opacity: 1;
+  }
+
+  &:active {
+    opacity: 0.6;
+  }
+
+  &:focus-visible {
+    outline: 1px solid #ffffff;
+    outline-offset: 1px;
+  }
+}
diff --git a/packages/noodl-core-ui/src/preview/launcher/Launcher/components/TagPill/TagPill.tsx b/packages/noodl-core-ui/src/preview/launcher/Launcher/components/TagPill/TagPill.tsx
new file mode 100644
index 0000000..dd06dd3
--- /dev/null
+++ b/packages/noodl-core-ui/src/preview/launcher/Launcher/components/TagPill/TagPill.tsx
@@ -0,0 +1,91 @@
+/**
+ * TagPill Component
+ *
+ * Displays a tag as a small colored pill/badge.
+ * Used to show project tags in cards and lists.
+ */
+
+import React from 'react';
+
+import { Icon, IconName, IconSize } from '@noodl-core-ui/components/common/Icon';
+import { Label, LabelSize } from '@noodl-core-ui/components/typography/Label';
+
+import { Tag } from '../../hooks/useProjectOrganization';
+import css from './TagPill.module.scss';
+
+export enum TagPillSize {
+  Small = 'small',
+  Medium = 'medium'
+}
+
+export interface TagPillProps {
+  /** The tag data to display */
+  tag: Tag;
+  /** Size variant */
+  size?: TagPillSize;
+  /** Whether to show remove button */
+  removable?: boolean;
+  /** Callback when remove button is clicked */
+  onRemove?: () => void;
+  /** Callback when pill is clicked */
+  onClick?: () => void;
+  /** Custom className */
+  className?: string;
+}
+
+/**
+ * TagPill - Displays a tag as a colored pill badge
+ *
+ * @example
+ * ```tsx
+ * <TagPill
+ *   tag={{ id: '1', name: 'Frontend', color: '#3B82F6' }}
+ *   size={TagPillSize.Small}
+ * />
+ * ```
+ */
+export function TagPill({
+  tag,
+  size = TagPillSize.Medium,
+  removable = false,
+  onRemove,
+  onClick,
+  className
+}: TagPillProps) {
+  const handleRemoveClick = (e: React.MouseEvent) => {
+    e.stopPropagation();
+    onRemove?.();
+  };
+
+  const handlePillClick = (e: React.MouseEvent) => {
+    if (onClick) {
+      e.stopPropagation();
+      onClick();
+    }
+  };
+
+  return (
+    <div
+      className={`${css.Root} ${css[`Size-${size}`]} ${onClick ? css.Clickable : ''} ${className || ''}`}
+      style={{ backgroundColor: tag.color }}
+      onClick={handlePillClick}
+      role={onClick ? 'button' : undefined}
+      tabIndex={onClick ? 0 : undefined}
+    >
+      <Label size={size === TagPillSize.Small ? LabelSize.Small : LabelSize.Default} UNSAFE_className={css.Label}>
+        {tag.name}
+      </Label>
+
+      {removable && (
+        <button
+          className={css.RemoveButton}
+          onClick={handleRemoveClick}
+          aria-label={`Remove ${tag.name} tag`}
+          type="button"
+        >
+          <Icon icon={IconName.Close} size={size === TagPillSize.Small ? IconSize.Tiny : IconSize.Small} />
+        </button>
+      )}
+    </div>
+  );
+}
diff --git a/packages/noodl-core-ui/src/preview/launcher/Launcher/components/TagPill/index.ts b/packages/noodl-core-ui/src/preview/launcher/Launcher/components/TagPill/index.ts
new file mode 100644
index 0000000..42df8da
--- /dev/null
+++ b/packages/noodl-core-ui/src/preview/launcher/Launcher/components/TagPill/index.ts
@@ -0,0 +1,2 @@
+export { TagPill, TagPillSize } from './TagPill';
+export type { TagPillProps } from './TagPill';
diff --git a/packages/noodl-core-ui/src/preview/launcher/Launcher/components/TagSelector/TagSelector.module.scss b/packages/noodl-core-ui/src/preview/launcher/Launcher/components/TagSelector/TagSelector.module.scss
new file mode 100644
index 0000000..9609962
--- /dev/null
+++ b/packages/noodl-core-ui/src/preview/launcher/Launcher/components/TagSelector/TagSelector.module.scss
@@ -0,0 +1,35 @@
+/**
+ * TagSelector Styles
+ *
+ * UI for selecting/managing tags for a project.
+ */
+
+.Root {
+  padding: var(--spacing-4);
+  min-width: 240px;
+  max-width: 320px;
+}
+
+/* Tag Item (Checkbox + Pill) */
+.TagItem {
+  display: flex;
+  align-items: center;
+  gap: var(--spacing-2);
+  padding: var(--spacing-2);
+  border-radius: 4px;
+  cursor: pointer;
+  transition: background-color 0.15s ease;
+
+  &:hover {
+    background-color: var(--theme-color-bg-3);
+  }
+}
+
+/* Checkbox */
+.Checkbox {
+  width: 16px;
+  height: 16px;
+  margin: 0;
+  cursor: pointer;
+  accent-color: var(--theme-color-primary);
+}
diff --git a/packages/noodl-core-ui/src/preview/launcher/Launcher/components/TagSelector/TagSelector.tsx b/packages/noodl-core-ui/src/preview/launcher/Launcher/components/TagSelector/TagSelector.tsx
new file mode 100644
index 0000000..2c441d5
--- /dev/null
+++ b/packages/noodl-core-ui/src/preview/launcher/Launcher/components/TagSelector/TagSelector.tsx
@@ -0,0 +1,142 @@
+/**
+ * TagSelector Component
+ *
+ * Allows users to assign/remove tags from a project.
+ * Displays all available tags with checkboxes and option to create new tags.
+ */
+
+import React, { useState } from 'react';
+
+import { Icon, IconName, IconSize } from '@noodl-core-ui/components/common/Icon';
+import { PrimaryButton, PrimaryButtonSize, PrimaryButtonVariant } from '@noodl-core-ui/components/inputs/PrimaryButton';
+import { TextInput, TextInputVariant } from '@noodl-core-ui/components/inputs/TextInput';
+import { Box } from '@noodl-core-ui/components/layout/Box';
+import { HStack, VStack } from '@noodl-core-ui/components/layout/Stack';
+import { Label, LabelSize } from '@noodl-core-ui/components/typography/Label';
+import { TextType } from '@noodl-core-ui/components/typography/Text';
+
+import { Tag, useProjectOrganization } from '../../hooks/useProjectOrganization';
+import { TagPill, TagPillSize } from '../TagPill';
+import css from './TagSelector.module.scss';
+
+export interface TagSelectorProps {
+  /** Project path to manage tags for */
+  projectPath: string;
+  /** Callback when tags are changed */
+  onTagsChanged?: () => void;
+}
+
+/**
+ * TagSelector - UI for assigning/removing tags from a project
+ *
+ * Shows all available tags with checkboxes, and allows creating new tags inline.
+ */
+export function TagSelector({ projectPath, onTagsChanged }: TagSelectorProps) {
+  const { tags, getProjectMeta, addTagToProject, removeTagFromProject, createTag } = useProjectOrganization();
+
+  const [isCreatingTag, setIsCreatingTag] = useState(false);
+  const [newTagName, setNewTagName] = useState('');
+
+  // Get current project tags
+  const projectMeta = getProjectMeta(projectPath);
+  const assignedTagIds = projectMeta?.tagIds || [];
+
+  const handleToggleTag = (tagId: string) => {
+    if (assignedTagIds.includes(tagId)) {
+      removeTagFromProject(projectPath, tagId);
+    } else {
+      addTagToProject(projectPath, tagId);
+    }
+    onTagsChanged?.();
+  };
+
+  const handleCreateTag = () => {
+    if (!newTagName.trim()) return;
+
+    const newTag = createTag(newTagName.trim());
+    addTagToProject(projectPath, newTag.id);
+    setNewTagName('');
+    setIsCreatingTag(false);
+    onTagsChanged?.();
+  };
+
+  const handleCancelCreate = () => {
+    setNewTagName('');
+    setIsCreatingTag(false);
+  };
+
+  return (
+    <div className={css.Root}>
+      {/* Tag list */}
+      {tags.length > 0 ? (
+        <VStack hasSpacing={2}>
+          {tags.map((tag) => {
+            const isAssigned = assignedTagIds.includes(tag.id);
+            return (
+              <label key={tag.id} className={css.TagItem}>
+                <input
+                  type="checkbox"
+                  checked={isAssigned}
+                  onChange={() => handleToggleTag(tag.id)}
+                  className={css.Checkbox}
+                />
+                <TagPill tag={tag} size={TagPillSize.Small} />
+              </label>
+            );
+          })}
+        </VStack>
+      ) : (
+        <Label variant={TextType.Shy} size={LabelSize.Small}>
+          No tags yet. Create one below.
+        </Label>
+      )}
+
+      {/* Create new tag */}
+      <Box hasTopSpacing={4}>
+        {!isCreatingTag ? (
+          <PrimaryButton
+            label="Create new tag"
+            icon={IconName.Plus}
+            size={PrimaryButtonSize.Small}
+            variant={PrimaryButtonVariant.Muted}
+            onClick={() => setIsCreatingTag(true)}
+            UNSAFE_style={{ width: '100%' }}
+          />
+        ) : (
+          <VStack hasSpacing={2}>
+            <TextInput
+              value={newTagName}
+              onChange={(e) => setNewTagName(e.target.value)}
+              placeholder="Tag name..."
+              variant={TextInputVariant.Default}
+              isAutoFocus
+              onKeyDown={(e) => {
+                if (e.key === 'Enter') {
+                  handleCreateTag();
+                } else if (e.key === 'Escape') {
+                  handleCancelCreate();
+                }
+              }}
+            />
+            <HStack hasSpacing={2}>
+              <PrimaryButton
+                label="Create"
+                size={PrimaryButtonSize.Small}
+                onClick={handleCreateTag}
+                isDisabled={!newTagName.trim()}
+                UNSAFE_style={{ flex: 1 }}
+              />
+              <PrimaryButton
+                label="Cancel"
+                size={PrimaryButtonSize.Small}
+                variant={PrimaryButtonVariant.Muted}
+                onClick={handleCancelCreate}
+                UNSAFE_style={{ flex: 1 }}
+              />
+            </HStack>
+          </VStack>
+        )}
+      </Box>
+    </div>
+  );
+}
diff --git a/packages/noodl-core-ui/src/preview/launcher/Launcher/components/TagSelector/index.ts b/packages/noodl-core-ui/src/preview/launcher/Launcher/components/TagSelector/index.ts
new file mode 100644
index 0000000..9bb08df
--- /dev/null
+++ b/packages/noodl-core-ui/src/preview/launcher/Launcher/components/TagSelector/index.ts
@@ -0,0 +1,2 @@
+export { TagSelector } from './TagSelector';
+export type { TagSelectorProps } from './TagSelector';
diff --git a/packages/noodl-core-ui/src/preview/launcher/Launcher/hooks/useProjectOrganization.ts b/packages/noodl-core-ui/src/preview/launcher/Launcher/hooks/useProjectOrganization.ts
new file mode 100644
index 0000000..59a43e3
--- /dev/null
+++ b/packages/noodl-core-ui/src/preview/launcher/Launcher/hooks/useProjectOrganization.ts
@@ -0,0 +1,354 @@
+/**
+ * useProjectOrganization
+ *
+ * React hook for managing project organization (folders and tags).
+ * Interfaces with ProjectOrganizationService from noodl-editor.
+ */
+
+import { useEffect, useMemo, useState } from 'react';
+
+// Import types and service from noodl-editor
+// Note: This assumes the service is available in the editor context
+// We'll need to expose it through the window or context
+declare global {
+  interface Window {
+    ProjectOrganizationService?: any;
+  }
+}
+
+export interface Folder {
+  id: string;
+  name: string;
+  parentId: string | null;
+  order: number;
+  createdAt: string;
+}
+
+export interface Tag {
+  id: string;
+  name: string;
+  color: string;
+  createdAt: string;
+}
+
+export interface ProjectMeta {
+  folderId: string | null;
+  tagIds: string[];
+  customName?: string;
+  notes?: string;
+}
+
+export interface UseProjectOrganizationReturn {
+  // Data
+  folders: Folder[];
+  tags: Tag[];
+
+  // Folder operations
+  createFolder: (name: string, parentId?: string | null) => Folder;
+  renameFolder: (id: string, name: string) => void;
+  deleteFolder: (id: string) => void;
+  getProjectCountInFolder: (folderId: string | null) => number;
+
+  // Tag operations
+  createTag: (name: string, color?: string) => Tag;
+  renameTag: (id: string, name: string) => void;
+  changeTagColor: (id: string, color: string) => void;
+  deleteTag: (id: string) => void;
+
+  // Project organization
+  moveProjectToFolder: (projectPath: string, folderId: string | null) => void;
+  addTagToProject: (projectPath: string, tagId: string) => void;
+  removeTagFromProject: (projectPath: string, tagId: string) => void;
+  getProjectMeta: (projectPath: string) => ProjectMeta | null;
+  getProjectsInFolder: (folderId: string | null) => string[];
+  getProjectsWithTag: (tagId: string) => string[];
+}
+
+/**
+ * Hook to manage project organization through folders and tags.
+ *
+ * Note: Currently uses localStorage directly as a fallback.
+ * In production, this should interface with ProjectOrganizationService
+ * from the Electron main process.
+ */
+export function useProjectOrganization(): UseProjectOrganizationReturn {
+  const [folders, setFolders] = useState<Folder[]>([]);
+  const [tags, setTags] = useState<Tag[]>([]);
+  const [, setUpdateTrigger] = useState(0);
+
+  // Memoize service to prevent infinite loop - service must be stable across renders
+  const service = useMemo(() => {
+    // TODO: In production, get this from window context or inject it
+    // For now, we'll implement a minimal localStorage version
+    return createLocalStorageService();
+  }, []); // Empty deps - create service once
+
+  // Subscribe to service events and load initial data
+  useEffect(() => {
+    // Initial load
+    setFolders(service.getFolders());
+    setTags(service.getTags());
+
+    // Subscribe to changes
+    const handleDataChange = () => {
+      setFolders(service.getFolders());
+      setTags(service.getTags());
+      setUpdateTrigger((prev) => prev + 1);
+    };
+
+    service.on('dataChanged', handleDataChange);
+
+    // Cleanup
+    return () => {
+      service.off('dataChanged', handleDataChange);
+    };
+  }, [service]);
+
+  return {
+    // Data
+    folders,
+    tags,
+
+    // Folder operations
+    createFolder: (name, parentId) => service.createFolder(name, parentId),
+    renameFolder: (id, name) => service.renameFolder(id, name),
+    deleteFolder: (id) => service.deleteFolder(id),
+    getProjectCountInFolder: (folderId) => service.getProjectCountInFolder(folderId),
+
+    // Tag operations
+    createTag: (name, color) => service.createTag(name, color),
+    renameTag: (id, name) => service.renameTag(id, name),
+    changeTagColor: (id, color) => service.changeTagColor(id, color),
+    deleteTag: (id) => service.deleteTag(id),
+
+    // Project organization
+    moveProjectToFolder: (projectPath, folderId) => service.moveProjectToFolder(projectPath, folderId),
+    addTagToProject: (projectPath, tagId) => service.addTagToProject(projectPath, tagId),
+    removeTagFromProject: (projectPath, tagId) => service.removeTagFromProject(projectPath, tagId),
+    getProjectMeta: (projectPath) => service.getProjectMeta(projectPath),
+    getProjectsInFolder: (folderId) => service.getProjectsInFolder(folderId),
+    getProjectsWithTag: (tagId) => service.getProjectsWithTag(tagId)
+  };
+}
+
+// ============================================================================
+// Minimal localStorage-based service for noodl-core-ui
+// This allows the hook to work in Storybook and standalone contexts
+// ============================================================================
+
+class EventEmitter {
+  private listeners: Map<string, Array<(data: any) => void>> = new Map();
+
+  on(event: string, callback: (data: any) => void) {
+    if (!this.listeners.has(event)) {
+      this.listeners.set(event, []);
+    }
+    this.listeners.get(event)!.push(callback);
+  }
+
+  off(event: string, callback?: (data: any) => void) {
+    if (!callback) {
+      this.listeners.delete(event);
+      return;
+    }
+    const callbacks = this.listeners.get(event);
+    if (callbacks) {
+      const index = callbacks.indexOf(callback);
+      if (index > -1) {
+        callbacks.splice(index, 1);
+      }
+    }
+  }
+
+  emit(event: string, data?: any) {
+    const callbacks = this.listeners.get(event);
+    if (callbacks) {
+      callbacks.forEach((callback) => callback(data));
+    }
+  }
+}
+
+function createLocalStorageService() {
+  const emitter = new EventEmitter();
+  const storageKey = 'projectOrganization';
+
+  interface StorageData {
+    version: 1;
+    folders: Folder[];
+    tags: Tag[];
+    projectMeta: Record<string, ProjectMeta>;
+  }
+
+  const loadData = (): StorageData => {
+    try {
+      const stored = localStorage.getItem(storageKey);
+      if (stored) {
+        return JSON.parse(stored);
+      }
+    } catch (error) {
+      console.error('[useProjectOrganization] Failed to load data:', error);
+    }
+    return {
+      version: 1,
+      folders: [],
+      tags: [],
+      projectMeta: {}
+    };
+  };
+
+  let data = loadData();
+
+  const saveData = () => {
+    try {
+      localStorage.setItem(storageKey, JSON.stringify(data));
+      emitter.emit('dataChanged', data);
+    } catch (error) {
+      console.error('[useProjectOrganization] Failed to save data:', error);
+    }
+  };
+
+  const generateId = (prefix: string) => {
+    return `${prefix}-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+  };
+
+  const TAG_COLORS = [
+    '#EF4444',
+    '#F97316',
+    '#EAB308',
+    '#22C55E',
+    '#06B6D4',
+    '#3B82F6',
+    '#8B5CF6',
+    '#EC4899',
+    '#6B7280'
+  ];
+
+  const getNextTagColor = () => {
+    const usedColors = data.tags.map((t) => t.color);
+    const availableColors = TAG_COLORS.filter((c) => !usedColors.includes(c));
+    return availableColors.length > 0 ? availableColors[0] : TAG_COLORS[0];
+  };
+
+  return {
+    // Event methods
+    on: emitter.on.bind(emitter),
+    off: emitter.off.bind(emitter),
+    emit: emitter.emit.bind(emitter),
+
+    // Data methods
+    getFolders: () => [...data.folders].sort((a, b) => a.order - b.order),
+    getTags: () => [...data.tags],
+
+    createFolder: (name: string, parentId?: string | null): Folder => {
+      const folder: Folder = {
+        id: generateId('folder'),
+        name,
+        parentId: parentId || null,
+        order: data.folders.length,
+        createdAt: new Date().toISOString()
+      };
+      data.folders.push(folder);
+      saveData();
+      return folder;
+    },
+
+    renameFolder: (id: string, name: string) => {
+      const folder = data.folders.find((f) => f.id === id);
+      if (folder) {
+        folder.name = name;
+        saveData();
+      }
+    },
+
+    deleteFolder: (id: string) => {
+      data.folders = data.folders.filter((f) => f.id !== id && f.parentId !== id);
+      Object.keys(data.projectMeta).forEach((projectPath) => {
+        if (data.projectMeta[projectPath].folderId === id) {
+          data.projectMeta[projectPath].folderId = null;
+        }
+      });
+      saveData();
+    },
+
+    getProjectCountInFolder: (folderId: string | null): number => {
+      return Object.values(data.projectMeta).filter((meta) => meta.folderId === folderId).length;
+    },
+
+    createTag: (name: string, color?: string): Tag => {
+      const tag: Tag = {
+        id: generateId('tag'),
+        name,
+        color: color || getNextTagColor(),
+        createdAt: new Date().toISOString()
+      };
+      data.tags.push(tag);
+      saveData();
+      return tag;
+    },
+
+    renameTag: (id: string, name: string) => {
+      const tag = data.tags.find((t) => t.id === id);
+      if (tag) {
+        tag.name = name;
+        saveData();
+      }
+    },
+
+    changeTagColor: (id: string, color: string) => {
+      const tag = data.tags.find((t) => t.id === id);
+      if (tag) {
+        tag.color = color;
+        saveData();
+      }
+    },
+
+    deleteTag: (id: string) => {
+      data.tags = data.tags.filter((t) => t.id !== id);
+      Object.keys(data.projectMeta).forEach((projectPath) => {
+        data.projectMeta[projectPath].tagIds = data.projectMeta[projectPath].tagIds.filter((tagId) => tagId !== id);
+      });
+      saveData();
+    },
+
+    moveProjectToFolder: (projectPath: string, folderId: string | null) => {
+      if (!data.projectMeta[projectPath]) {
+        data.projectMeta[projectPath] = { folderId: null, tagIds: [] };
+      }
+      data.projectMeta[projectPath].folderId = folderId;
+      saveData();
+    },
+
+    addTagToProject: (projectPath: string, tagId: string) => {
+      if (!data.projectMeta[projectPath]) {
+        data.projectMeta[projectPath] = { folderId: null, tagIds: [] };
+      }
+      const meta = data.projectMeta[projectPath];
+      if (!meta.tagIds.includes(tagId)) {
+        meta.tagIds.push(tagId);
+        saveData();
+      }
+    },
+
+    removeTagFromProject: (projectPath: string, tagId: string) => {
+      const meta = data.projectMeta[projectPath];
+      if (meta) {
+        meta.tagIds = meta.tagIds.filter((id) => id !== tagId);
+        saveData();
+      }
+    },
+
+    getProjectMeta: (projectPath: string): ProjectMeta | null => {
+      return data.projectMeta[projectPath] || null;
+    },
+
+    getProjectsInFolder: (folderId: string | null): string[] => {
+      return Object.keys(data.projectMeta).filter((projectPath) => data.projectMeta[projectPath].folderId === folderId);
+    },
+
+    getProjectsWithTag: (tagId: string): string[] => {
+      return Object.keys(data.projectMeta).filter((projectPath) =>
+        data.projectMeta[projectPath].tagIds.includes(tagId)
+      );
+    }
+  };
+}
diff --git a/packages/noodl-core-ui/src/preview/launcher/Launcher/views/Projects.tsx b/packages/noodl-core-ui/src/preview/launcher/Launcher/views/Projects.tsx
index 603a553..98a6aa8 100644
--- a/packages/noodl-core-ui/src/preview/launcher/Launcher/views/Projects.tsx
+++ b/packages/noodl-core-ui/src/preview/launcher/Launcher/views/Projects.tsx
@@ -1,4 +1,4 @@
-import React, { useRef, useState } from 'react';
+import React, { useMemo, useRef, useState } from 'react';
 
 import { Icon, IconName } from '@noodl-core-ui/components/common/Icon';
 import { PrimaryButton, PrimaryButtonSize, PrimaryButtonVariant } from '@noodl-core-ui/components/inputs/PrimaryButton';
@@ -9,6 +9,7 @@ import { Columns } from '@noodl-core-ui/components/layout/Columns';
 import { HStack } from '@noodl-core-ui/components/layout/Stack';
 import { Label, LabelSize } from '@noodl-core-ui/components/typography/Label';
 import { TextType } from '@noodl-core-ui/components/typography/Text';
+import { FolderTree } from '@noodl-core-ui/preview/launcher/Launcher/components/FolderTree';
 import { LauncherPage } from '@noodl-core-ui/preview/launcher/Launcher/components/LauncherPage';
 import {
   CloudSyncType,
@@ -23,6 +24,7 @@ import { ProjectList } from '@noodl-core-ui/preview/launcher/Launcher/components
 import { ProjectSettingsModal } from '@noodl-core-ui/preview/launcher/Launcher/components/ProjectSettingsModal';
 import { ViewModeToggle } from '@noodl-core-ui/preview/launcher/Launcher/components/ViewModeToggle';
 import { useProjectList } from '@noodl-core-ui/preview/launcher/Launcher/hooks/useProjectList';
+import { useProjectOrganization } from '@noodl-core-ui/preview/launcher/Launcher/hooks/useProjectOrganization';
 import { MOCK_PROJECTS } from '@noodl-core-ui/preview/launcher/Launcher/Launcher';
 import { useLauncherContext, ViewMode } from '@noodl-core-ui/preview/launcher/Launcher/LauncherContext';
 
@@ -33,6 +35,8 @@ export function Projects({}: ProjectsViewProps) {
     viewMode,
     setViewMode,
     projects: allProjects,
+    selectedFolderId,
+    setSelectedFolderId,
     onCreateProject,
     onOpenProject,
     onLaunchProject,
@@ -40,8 +44,38 @@ export function Projects({}: ProjectsViewProps) {
     onDeleteProject
   } = useLauncherContext();
 
+  const { getProjectMeta, getProjectsInFolder, folders, moveProjectToFolder } = useProjectOrganization();
+
   const [selectedProjectId, setSelectedProjectId] = useState(null);
-  const uniqueTypes = [...new Set(allProjects.map((item) => item.cloudSyncMeta.type))];
+  const [movingProject, setMovingProject] = useState<LauncherProjectData | null>(null);
+
+  // Filter projects based on selected folder
+  const filteredByFolder = useMemo(() => {
+    if (selectedFolderId === null) {
+      // "All Projects" - show everything
+      return allProjects;
+    } else if (selectedFolderId === 'uncategorized') {
+      // "Uncategorized" - show projects without a folder
+      return allProjects.filter((project) => {
+        const meta = getProjectMeta(project.localPath);
+        return !meta || meta.folderId === null;
+      });
+    } else {
+      // Specific folder - show projects in that folder
+      const projectPathsInFolder = getProjectsInFolder(selectedFolderId);
+      return allProjects.filter((project) => projectPathsInFolder.includes(project.localPath));
+    }
+  }, [allProjects, selectedFolderId, getProjectMeta, getProjectsInFolder]);
+
+  // Calculate counts for folder tree
+  const uncategorizedCount = useMemo(() => {
+    return allProjects.filter((project) => {
+      const meta = getProjectMeta(project.localPath);
+      return !meta || meta.folderId === null;
+    }).length;
+  }, [allProjects, getProjectMeta]);
+
+  const uniqueTypes = [...new Set(filteredByFolder.map((item) => item.cloudSyncMeta.type))];
   const visibleTypesDropdownItems: SelectOption[] = [
     { label: 'All projects', value: 'all' },
     ...uniqueTypes.map((type) => ({ label: `Only ${type.toLowerCase()} projects`, value: type }))
@@ -54,7 +88,7 @@ export function Projects({}: ProjectsViewProps) {
     searchTerm,
     setSearchTerm
   } = useLauncherSearchBar({
-    allItems: allProjects,
+    allItems: filteredByFolder,
     filterDropdownItems: visibleTypesDropdownItems,
     propertyNameToFilter: 'cloudSyncMeta.type'
   });
@@ -74,6 +108,21 @@ export function Projects({}: ProjectsViewProps) {
     setSelectedProjectId(null);
   }
 
+  function onMoveToFolder(project: LauncherProjectData) {
+    setMovingProject(project);
+  }
+
+  function onCloseFolderPicker() {
+    setMovingProject(null);
+  }
+
+  function handleMoveToFolder(folderId: string | null) {
+    if (movingProject) {
+      moveProjectToFolder(movingProject.localPath, folderId);
+      setMovingProject(null);
+    }
+  }
+
   function onImportProjectClick() {
     onOpenProject?.();
   }
@@ -83,103 +132,256 @@ export function Projects({}: ProjectsViewProps) {
   }
 
   return (
-    <LauncherPage
-      title="Recent Projects"
-      headerSlot={
-        <HStack hasSpacing>
-          <PrimaryButton
-            label="Open project"
-            size={PrimaryButtonSize.Small}
-            variant={PrimaryButtonVariant.Muted}
-            onClick={onImportProjectClick}
-          />
-          <PrimaryButton label="Create new project" size={PrimaryButtonSize.Small} onClick={onNewProjectClick} />
-        </HStack>
-      }
-    >
-      <ProjectSettingsModal
-        isVisible={selectedProjectId !== null}
-        onClose={onCloseProjectSettings}
-        projectData={projects.find((project) => project.id === selectedProjectId)}
-      />
-
-      <HStack hasSpacing={4} UNSAFE_style={{ justifyContent: 'space-between', alignItems: 'center' }}>
-        <LauncherSearchBar
-          searchTerm={searchTerm}
-          setSearchTerm={setSearchTerm}
-          filterValue={filterValue}
-          setFilterValue={setFilterValue}
-          filterDropdownItems={visibleTypesDropdownItems}
+    <div style={{ display: 'flex', height: '100%', overflow: 'hidden' }}>
+      {/* Folder Tree Sidebar */}
+      <div style={{ width: '240px', borderRight: '1px solid var(--theme-color-border-default)', flexShrink: 0 }}>
+        <FolderTree
+          selectedFolderId={selectedFolderId}
+          onFolderSelect={setSelectedFolderId}
+          totalProjectCount={allProjects.length}
+          uncategorizedProjectCount={uncategorizedCount}
         />
-        <ViewModeToggle mode={viewMode} onChange={setViewMode} />
-      </HStack>
+      </div>
 
-      <Box hasTopSpacing={4}>
-        {viewMode === ViewMode.List ? (
-          <ProjectList
-            projects={sortedProjects}
-            sortField={sortField}
-            sortDirection={sortDirection}
-            onSort={setSorting}
-            onProjectClick={(project) => onLaunchProject?.(project.id)}
-            onOpenFolder={(project) => onOpenProjectFolder?.(project.id)}
-            onSettings={(project) => onOpenProjectSettings(project.id)}
-            onDelete={(project) => onDeleteProject?.(project.id)}
+      {/* Main Content */}
+      <div style={{ flex: 1, overflow: 'auto' }}>
+        <LauncherPage
+          title="Recent Projects"
+          headerSlot={
+            <HStack hasSpacing>
+              <PrimaryButton
+                label="Open project"
+                size={PrimaryButtonSize.Small}
+                variant={PrimaryButtonVariant.Muted}
+                onClick={onImportProjectClick}
+              />
+              <PrimaryButton label="Create new project" size={PrimaryButtonSize.Small} onClick={onNewProjectClick} />
+            </HStack>
+          }
+        >
+          <ProjectSettingsModal
+            isVisible={selectedProjectId !== null}
+            onClose={onCloseProjectSettings}
+            projectData={projects.find((project) => project.id === selectedProjectId)}
           />
-        ) : (
-          <>
-            {/* TODO: make project list legend and grid reusable */}
-            <Box hasBottomSpacing={4}>
-              <HStack hasSpacing>
-                <div style={{ width: 100 }} />
-                <div style={{ width: '100%' }}>
-                  <Columns layoutString={'1 1 1'}>
-                    <Label variant={TextType.Shy} size={LabelSize.Small}>
-                      Name
-                    </Label>
-                    <Label variant={TextType.Shy} size={LabelSize.Small}>
-                      Version control
-                    </Label>
-                    <Label variant={TextType.Shy} size={LabelSize.Small}>
-                      Contributors
-                    </Label>
-                  </Columns>
-                </div>
-              </HStack>
-            </Box>
-            <Columns layoutString="1" hasXGap hasYGap>
-              {projects.map((project) => (
-                <LauncherProjectCard
-                  key={project.id}
-                  {...project}
-                  contextMenuItems={[
-                    {
-                      label: 'Launch project',
-                      onClick: () => onLaunchProject?.(project.id)
-                    },
-                    {
-                      label: 'Open project folder',
-                      onClick: () => onOpenProjectFolder?.(project.id)
-                    },
-                    {
-                      label: 'Open project settings',
-                      onClick: () => onOpenProjectSettings(project.id)
-                    },
 
-                    'divider',
-                    {
-                      label: 'Delete project',
-                      onClick: () => onDeleteProject?.(project.id),
-                      icon: IconName.Trash,
-                      isDangerous: true
-                    }
-                  ]}
-                />
-              ))}
-            </Columns>
-          </>
-        )}
-      </Box>
-    </LauncherPage>
+          <HStack hasSpacing={4} UNSAFE_style={{ justifyContent: 'space-between', alignItems: 'center' }}>
+            <LauncherSearchBar
+              searchTerm={searchTerm}
+              setSearchTerm={setSearchTerm}
+              filterValue={filterValue}
+              setFilterValue={setFilterValue}
+              filterDropdownItems={visibleTypesDropdownItems}
+            />
+            <ViewModeToggle mode={viewMode} onChange={setViewMode} />
+          </HStack>
+
+          <Box hasTopSpacing={4}>
+            {viewMode === ViewMode.List ? (
+              <ProjectList
+                projects={sortedProjects}
+                sortField={sortField}
+                sortDirection={sortDirection}
+                onSort={setSorting}
+                onProjectClick={(project) => onLaunchProject?.(project.id)}
+                onOpenFolder={(project) => onOpenProjectFolder?.(project.id)}
+                onSettings={(project) => onOpenProjectSettings(project.id)}
+                onDelete={(project) => onDeleteProject?.(project.id)}
+              />
+            ) : (
+              <>
+                {/* TODO: make project list legend and grid reusable */}
+                <Box hasBottomSpacing={4}>
+                  <HStack hasSpacing>
+                    <div style={{ width: 100 }} />
+                    <div style={{ width: '100%' }}>
+                      <Columns layoutString={'1 1 1'}>
+                        <Label variant={TextType.Shy} size={LabelSize.Small}>
+                          Name
+                        </Label>
+                        <Label variant={TextType.Shy} size={LabelSize.Small}>
+                          Version control
+                        </Label>
+                        <Label variant={TextType.Shy} size={LabelSize.Small}>
+                          Contributors
+                        </Label>
+                      </Columns>
+                    </div>
+                  </HStack>
+                </Box>
+                <Columns layoutString="1" hasXGap hasYGap>
+                  {projects.map((project) => (
+                    <LauncherProjectCard
+                      key={project.id}
+                      {...project}
+                      onClick={() => onLaunchProject?.(project.id)}
+                      contextMenuItems={[
+                        {
+                          label: 'Launch project',
+                          onClick: () => onLaunchProject?.(project.id)
+                        },
+                        {
+                          label: 'Open project folder',
+                          onClick: () => onOpenProjectFolder?.(project.id)
+                        },
+                        {
+                          label: 'Move to folder...',
+                          onClick: () => onMoveToFolder(project)
+                        },
+                        {
+                          label: 'Open project settings',
+                          onClick: () => onOpenProjectSettings(project.id)
+                        },
+
+                        'divider',
+                        {
+                          label: 'Delete project',
+                          onClick: () => onDeleteProject?.(project.id),
+                          icon: IconName.Trash,
+                          isDangerous: true
+                        }
+                      ]}
+                    />
+                  ))}
+                </Columns>
+              </>
+            )}
+          </Box>
+
+          {/* Folder Picker Modal */}
+          {movingProject && (
+            <div
+              style={{
+                position: 'fixed',
+                top: 0,
+                left: 0,
+                right: 0,
+                bottom: 0,
+                display: 'flex',
+                alignItems: 'center',
+                justifyContent: 'center',
+                zIndex: 1000
+              }}
+            >
+              <div
+                style={{
+                  position: 'absolute',
+                  top: 0,
+                  left: 0,
+                  right: 0,
+                  bottom: 0,
+                  backgroundColor: 'rgba(0, 0, 0, 0.5)'
+                }}
+                onClick={onCloseFolderPicker}
+              />
+              <div
+                style={{
+                  position: 'relative',
+                  backgroundColor: 'var(--theme-color-bg-2)',
+                  border: '1px solid var(--theme-color-border-default)',
+                  borderRadius: 'var(--radius-lg)',
+                  padding: 'var(--spacing-6)',
+                  minWidth: '400px',
+                  maxWidth: '500px',
+                  boxShadow: '0 8px 32px rgba(0, 0, 0, 0.3)',
+                  zIndex: 1001
+                }}
+              >
+                <h3
+                  style={{
+                    fontSize: '20px',
+                    fontWeight: 600,
+                    color: 'var(--theme-color-fg-default)',
+                    margin: '0 0 var(--spacing-3) 0',
+                    lineHeight: 1.3
+                  }}
+                >
+                  Move "{movingProject.title}" to folder
+                </h3>
+                <div
+                  style={{
+                    marginBottom: 'var(--spacing-6)',
+                    maxHeight: '300px',
+                    overflowY: 'auto'
+                  }}
+                >
+                  <button
+                    onClick={() => handleMoveToFolder(null)}
+                    style={{
+                      width: '100%',
+                      textAlign: 'left',
+                      padding: 'var(--spacing-2) var(--spacing-3)',
+                      marginBottom: 'var(--spacing-1)',
+                      backgroundColor: 'var(--theme-color-bg-3)',
+                      border: '1px solid var(--theme-color-border-default)',
+                      borderRadius: 'var(--radius-default)',
+                      color: 'var(--theme-color-fg-default)',
+                      cursor: 'pointer',
+                      transition: 'all 0.15s ease'
+                    }}
+                    onMouseEnter={(e) => {
+                      e.currentTarget.style.backgroundColor = 'var(--theme-color-bg-4)';
+                    }}
+                    onMouseLeave={(e) => {
+                      e.currentTarget.style.backgroundColor = 'var(--theme-color-bg-3)';
+                    }}
+                  >
+                    Uncategorized
+                  </button>
+                  {folders.map((folder) => (
+                    <button
+                      key={folder.id}
+                      onClick={() => handleMoveToFolder(folder.id)}
+                      style={{
+                        width: '100%',
+                        textAlign: 'left',
+                        padding: 'var(--spacing-2) var(--spacing-3)',
+                        marginBottom: 'var(--spacing-1)',
+                        backgroundColor: 'var(--theme-color-bg-3)',
+                        border: '1px solid var(--theme-color-border-default)',
+                        borderRadius: 'var(--radius-default)',
+                        color: 'var(--theme-color-fg-default)',
+                        cursor: 'pointer',
+                        transition: 'all 0.15s ease'
+                      }}
+                      onMouseEnter={(e) => {
+                        e.currentTarget.style.backgroundColor = 'var(--theme-color-bg-4)';
+                      }}
+                      onMouseLeave={(e) => {
+                        e.currentTarget.style.backgroundColor = 'var(--theme-color-bg-3)';
+                      }}
+                    >
+                      {folder.name}
+                    </button>
+                  ))}
+                </div>
+                <div style={{ display: 'flex', justifyContent: 'flex-end' }}>
+                  <button
+                    onClick={onCloseFolderPicker}
+                    style={{
+                      padding: 'var(--spacing-2) var(--spacing-4)',
+                      backgroundColor: 'var(--theme-color-bg-3)',
+                      border: '1px solid var(--theme-color-border-default)',
+                      borderRadius: 'var(--radius-default)',
+                      color: 'var(--theme-color-fg-default)',
+                      cursor: 'pointer',
+                      transition: 'all 0.15s ease'
+                    }}
+                    onMouseEnter={(e) => {
+                      e.currentTarget.style.backgroundColor = 'var(--theme-color-bg-4)';
+                    }}
+                    onMouseLeave={(e) => {
+                      e.currentTarget.style.backgroundColor = 'var(--theme-color-bg-3)';
+                    }}
+                  >
+                    Cancel
+                  </button>
+                </div>
+              </div>
+            </div>
+          )}
+        </LauncherPage>
+      </div>
+    </div>
   );
 }
diff --git a/packages/noodl-editor/src/editor/src/pages/ProjectsPage/ProjectsPage.tsx b/packages/noodl-editor/src/editor/src/pages/ProjectsPage/ProjectsPage.tsx
index a5525f2..fc22084 100644
--- a/packages/noodl-editor/src/editor/src/pages/ProjectsPage/ProjectsPage.tsx
+++ b/packages/noodl-editor/src/editor/src/pages/ProjectsPage/ProjectsPage.tsx
@@ -6,25 +6,67 @@
  */
 
 import { ipcRenderer, shell } from 'electron';
-import React, { useCallback, useEffect } from 'react';
+import React, { useCallback, useEffect, useState } from 'react';
 import { filesystem } from '@noodl/platform';
 
+import {
+  CloudSyncType,
+  LauncherProjectData
+} from '@noodl-core-ui/preview/launcher/Launcher/components/LauncherProjectCard';
 import { Launcher } from '@noodl-core-ui/preview/launcher/Launcher/Launcher';
 
+import { useEventListener } from '../../hooks/useEventListener';
 import { IRouteProps } from '../../pages/AppRoute';
-import { LocalProjectsModel } from '../../utils/LocalProjectsModel';
+import { LocalProjectsModel, ProjectItem } from '../../utils/LocalProjectsModel';
 import { ToastLayer } from '../../views/ToastLayer/ToastLayer';
 
 export interface ProjectsPageProps extends IRouteProps {
   from: TSFixme;
 }
 
+/**
+ * Map LocalProjectsModel ProjectItem to LauncherProjectData format
+ */
+function mapProjectToLauncherData(project: ProjectItem): LauncherProjectData {
+  return {
+    id: project.id,
+    title: project.name || 'Untitled',
+    localPath: project.retainedProjectDirectory,
+    lastOpened: new Date(project.latestAccessed).toISOString(),
+    imageSrc: project.thumbURI || 'data:image/svg+xml,%3Csvg xmlns="http://www.w3.org/2000/svg"%3E%3C/svg%3E',
+    cloudSyncMeta: {
+      type: CloudSyncType.None // TODO: Detect git repos in future
+    }
+    // Git-related fields will be populated in future tasks
+  };
+}
+
 export function ProjectsPage(props: ProjectsPageProps) {
+  // Real projects from LocalProjectsModel
+  const [realProjects, setRealProjects] = useState<LauncherProjectData[]>([]);
+
+  // Fetch projects on mount
   useEffect(() => {
     // Switch main window size to editor size
     ipcRenderer.send('main-window-resize', { size: 'editor', center: true });
+
+    // Initial load
+    const loadProjects = async () => {
+      await LocalProjectsModel.instance.fetch();
+      const projects = LocalProjectsModel.instance.getProjects();
+      setRealProjects(projects.map(mapProjectToLauncherData));
+    };
+
+    loadProjects();
   }, []);
 
+  // Subscribe to project list changes
+  useEventListener(LocalProjectsModel.instance, 'myProjectsChanged', () => {
+    console.log('🔔 Projects list changed, updating dashboard');
+    const projects = LocalProjectsModel.instance.getProjects();
+    setRealProjects(projects.map(mapProjectToLauncherData));
+  });
+
   const handleCreateProject = useCallback(async () => {
     try {
       const direntry = await filesystem.openDialog({
@@ -196,6 +238,7 @@ export function ProjectsPage(props: ProjectsPageProps) {
 
   return (
     <Launcher
+      projects={realProjects}
       onCreateProject={handleCreateProject}
       onOpenProject={handleOpenProject}
       onLaunchProject={handleLaunchProject}
diff --git a/packages/noodl-editor/src/editor/src/services/ProjectOrganizationService.ts b/packages/noodl-editor/src/editor/src/services/ProjectOrganizationService.ts
new file mode 100644
index 0000000..b95dc0c
--- /dev/null
+++ b/packages/noodl-editor/src/editor/src/services/ProjectOrganizationService.ts
@@ -0,0 +1,340 @@
+/**
+ * ProjectOrganizationService
+ *
+ * Manages project organization through folders and tags.
+ * Data is stored client-side in electron-store and keyed by project path.
+ */
+
+import { EventDispatcher } from '../../../shared/utils/EventDispatcher';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface Folder {
+  id: string;
+  name: string;
+  parentId: string | null; // null = root level
+  order: number;
+  createdAt: string;
+}
+
+export interface Tag {
+  id: string;
+  name: string;
+  color: string; // hex color
+  createdAt: string;
+}
+
+export interface ProjectMeta {
+  folderId: string | null;
+  tagIds: string[];
+  customName?: string;
+  notes?: string;
+}
+
+export interface ProjectOrganizationData {
+  version: 1;
+  folders: Folder[];
+  tags: Tag[];
+  projectMeta: Record<string, ProjectMeta>; // keyed by project path
+}
+
+// Tag color palette
+export const TAG_COLORS = [
+  '#EF4444', // Red
+  '#F97316', // Orange
+  '#EAB308', // Yellow
+  '#22C55E', // Green
+  '#06B6D4', // Cyan
+  '#3B82F6', // Blue
+  '#8B5CF6', // Purple
+  '#EC4899', // Pink
+  '#6B7280' // Gray
+];
+
+// ============================================================================
+// Service
+// ============================================================================
+
+export class ProjectOrganizationService extends EventDispatcher {
+  private static _instance: ProjectOrganizationService;
+  private data: ProjectOrganizationData;
+  private storageKey = 'projectOrganization';
+
+  private constructor() {
+    super();
+    this.data = this.loadData();
+  }
+
+  static get instance(): ProjectOrganizationService {
+    if (!ProjectOrganizationService._instance) {
+      ProjectOrganizationService._instance = new ProjectOrganizationService();
+    }
+    return ProjectOrganizationService._instance;
+  }
+
+  // ============================================================================
+  // Storage
+  // ============================================================================
+
+  private loadData(): ProjectOrganizationData {
+    try {
+      const stored = localStorage.getItem(this.storageKey);
+      if (stored) {
+        return JSON.parse(stored);
+      }
+    } catch (error) {
+      console.error('[ProjectOrganizationService] Failed to load data:', error);
+    }
+
+    // Return default empty structure
+    return {
+      version: 1,
+      folders: [],
+      tags: [],
+      projectMeta: {}
+    };
+  }
+
+  private saveData(): void {
+    try {
+      localStorage.setItem(this.storageKey, JSON.stringify(this.data));
+      this.notifyListeners('dataChanged', this.data);
+    } catch (error) {
+      console.error('[ProjectOrganizationService] Failed to save data:', error);
+    }
+  }
+
+  // ============================================================================
+  // Folder Operations
+  // ============================================================================
+
+  createFolder(name: string, parentId?: string | null): Folder {
+    const folder: Folder = {
+      id: this.generateId('folder'),
+      name,
+      parentId: parentId || null,
+      order: this.data.folders.length,
+      createdAt: new Date().toISOString()
+    };
+
+    this.data.folders.push(folder);
+    this.saveData();
+    this.notifyListeners('folderCreated', folder);
+
+    return folder;
+  }
+
+  renameFolder(id: string, name: string): void {
+    const folder = this.data.folders.find((f) => f.id === id);
+    if (!folder) {
+      console.warn('[ProjectOrganizationService] Folder not found:', id);
+      return;
+    }
+
+    folder.name = name;
+    this.saveData();
+    this.notifyListeners('folderRenamed', { id, name });
+  }
+
+  deleteFolder(id: string): void {
+    // Remove folder
+    this.data.folders = this.data.folders.filter((f) => f.id !== id);
+
+    // Remove child folders
+    this.data.folders = this.data.folders.filter((f) => f.parentId !== id);
+
+    // Move projects in deleted folder to uncategorized
+    Object.keys(this.data.projectMeta).forEach((projectPath) => {
+      if (this.data.projectMeta[projectPath].folderId === id) {
+        this.data.projectMeta[projectPath].folderId = null;
+      }
+    });
+
+    this.saveData();
+    this.notifyListeners('folderDeleted', id);
+  }
+
+  reorderFolder(id: string, newOrder: number): void {
+    const folder = this.data.folders.find((f) => f.id === id);
+    if (!folder) return;
+
+    folder.order = newOrder;
+    this.saveData();
+    this.notifyListeners('folderReordered', { id, order: newOrder });
+  }
+
+  getFolders(): Folder[] {
+    return [...this.data.folders].sort((a, b) => a.order - b.order);
+  }
+
+  getFolder(id: string): Folder | undefined {
+    return this.data.folders.find((f) => f.id === id);
+  }
+
+  // ============================================================================
+  // Tag Operations
+  // ============================================================================
+
+  createTag(name: string, color?: string): Tag {
+    const tag: Tag = {
+      id: this.generateId('tag'),
+      name,
+      color: color || this.getNextTagColor(),
+      createdAt: new Date().toISOString()
+    };
+
+    this.data.tags.push(tag);
+    this.saveData();
+    this.notifyListeners('tagCreated', tag);
+
+    return tag;
+  }
+
+  renameTag(id: string, name: string): void {
+    const tag = this.data.tags.find((t) => t.id === id);
+    if (!tag) {
+      console.warn('[ProjectOrganizationService] Tag not found:', id);
+      return;
+    }
+
+    tag.name = name;
+    this.saveData();
+    this.notifyListeners('tagRenamed', { id, name });
+  }
+
+  changeTagColor(id: string, color: string): void {
+    const tag = this.data.tags.find((t) => t.id === id);
+    if (!tag) return;
+
+    tag.color = color;
+    this.saveData();
+    this.notifyListeners('tagColorChanged', { id, color });
+  }
+
+  deleteTag(id: string): void {
+    // Remove tag
+    this.data.tags = this.data.tags.filter((t) => t.id !== id);
+
+    // Remove tag from all projects
+    Object.keys(this.data.projectMeta).forEach((projectPath) => {
+      const meta = this.data.projectMeta[projectPath];
+      meta.tagIds = meta.tagIds.filter((tagId) => tagId !== id);
+    });
+
+    this.saveData();
+    this.notifyListeners('tagDeleted', id);
+  }
+
+  getTags(): Tag[] {
+    return [...this.data.tags];
+  }
+
+  getTag(id: string): Tag | undefined {
+    return this.data.tags.find((t) => t.id === id);
+  }
+
+  private getNextTagColor(): string {
+    const usedColors = this.data.tags.map((t) => t.color);
+    const availableColors = TAG_COLORS.filter((c) => !usedColors.includes(c));
+    return availableColors.length > 0 ? availableColors[0] : TAG_COLORS[0];
+  }
+
+  // ============================================================================
+  // Project Organization
+  // ============================================================================
+
+  moveProjectToFolder(projectPath: string, folderId: string | null): void {
+    if (!this.data.projectMeta[projectPath]) {
+      this.data.projectMeta[projectPath] = {
+        folderId: null,
+        tagIds: []
+      };
+    }
+
+    this.data.projectMeta[projectPath].folderId = folderId;
+    this.saveData();
+    this.notifyListeners('projectMoved', { projectPath, folderId });
+  }
+
+  addTagToProject(projectPath: string, tagId: string): void {
+    if (!this.data.projectMeta[projectPath]) {
+      this.data.projectMeta[projectPath] = {
+        folderId: null,
+        tagIds: []
+      };
+    }
+
+    const meta = this.data.projectMeta[projectPath];
+    if (!meta.tagIds.includes(tagId)) {
+      meta.tagIds.push(tagId);
+      this.saveData();
+      this.notifyListeners('projectTagAdded', { projectPath, tagId });
+    }
+  }
+
+  removeTagFromProject(projectPath: string, tagId: string): void {
+    const meta = this.data.projectMeta[projectPath];
+    if (!meta) return;
+
+    meta.tagIds = meta.tagIds.filter((id) => id !== tagId);
+    this.saveData();
+    this.notifyListeners('projectTagRemoved', { projectPath, tagId });
+  }
+
+  getProjectMeta(projectPath: string): ProjectMeta | null {
+    return this.data.projectMeta[projectPath] || null;
+  }
+
+  // ============================================================================
+  // Queries
+  // ============================================================================
+
+  getProjectsInFolder(folderId: string | null): string[] {
+    return Object.keys(this.data.projectMeta).filter((projectPath) => {
+      const meta = this.data.projectMeta[projectPath];
+      return meta.folderId === folderId;
+    });
+  }
+
+  getProjectsWithTag(tagId: string): string[] {
+    return Object.keys(this.data.projectMeta).filter((projectPath) => {
+      const meta = this.data.projectMeta[projectPath];
+      return meta.tagIds.includes(tagId);
+    });
+  }
+
+  getProjectCountInFolder(folderId: string | null): number {
+    return this.getProjectsInFolder(folderId).length;
+  }
+
+  // ============================================================================
+  // Utilities
+  // ============================================================================
+
+  private generateId(prefix: string): string {
+    return `${prefix}-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+  }
+
+  // For debugging
+  exportData(): ProjectOrganizationData {
+    return JSON.parse(JSON.stringify(this.data));
+  }
+
+  importData(data: ProjectOrganizationData): void {
+    this.data = data;
+    this.saveData();
+  }
+
+  clearAll(): void {
+    this.data = {
+      version: 1,
+      folders: [],
+      tags: [],
+      projectMeta: {}
+    };
+    this.saveData();
+    this.notifyListeners('dataCleared', null);
+  }
+}
diff --git a/packages/noodl-editor/src/editor/src/styles/componentspanel.css b/packages/noodl-editor/src/editor/src/styles/componentspanel.css
index f98f6eb..ba27238 100644
--- a/packages/noodl-editor/src/editor/src/styles/componentspanel.css
+++ b/packages/noodl-editor/src/editor/src/styles/componentspanel.css
@@ -219,13 +219,13 @@ TODO: review this icon
 
 .components-panel-item-selected {
   line-height: 36px;
-  background-color: var(--theme-color-secondary);
-  color: var(--theme-color-on-secondary);
+  background-color: var(--theme-color-bg-4);
+  color: var(--theme-color-fg-highlight);
   opacity: 1;
 }
 
 .components-panel-item-selected .caret-icon-container {
-  background-color: var(--theme-color-secondary);
+  background-color: var(--theme-color-bg-4);
 }
 
 .components-panel-item-selected .components-panel-item-selected {
@@ -234,13 +234,13 @@ TODO: review this icon
 
 .components-panel-item-selected:hover,
 .components-panel-item-selected:hover .caret-icon-container {
-  background-color: var(--theme-color-secondary-highlight);
+  background-color: var(--theme-color-bg-5);
 }
 
 .components-panel-item-selected .components-panel-edit-button:hover,
 .components-panel-item-selected .components-panel-item-dropdown:hover {
-  background-color: var(--theme-color-secondary);
-  color: var(--theme-color-on-secondary);
+  background-color: var(--theme-color-bg-3);
+  color: var(--theme-color-fg-highlight);
 }
 
 .is-folder-component:hover .components-panel-folder-label {
diff --git a/packages/noodl-editor/src/editor/src/styles/popuplayer.css b/packages/noodl-editor/src/editor/src/styles/popuplayer.css
index e0e7364..909153f 100644
--- a/packages/noodl-editor/src/editor/src/styles/popuplayer.css
+++ b/packages/noodl-editor/src/editor/src/styles/popuplayer.css
@@ -122,9 +122,10 @@
   width: 0;
   position: absolute;
   pointer-events: none;
-  border-bottom-color: var(--theme-color-bg-5);
+  border-bottom-color: var(--theme-color-bg-4);
   border-width: 10px;
   margin-left: -10px;
+  transform: translateX(0);
 }
 
 .popup-layer-popout-arrow.right {
diff --git a/packages/noodl-editor/src/editor/src/views/EditorTopbar/EditorTopbar.module.scss b/packages/noodl-editor/src/editor/src/views/EditorTopbar/EditorTopbar.module.scss
index baa8b83..cfab4b9 100644
--- a/packages/noodl-editor/src/editor/src/views/EditorTopbar/EditorTopbar.module.scss
+++ b/packages/noodl-editor/src/editor/src/views/EditorTopbar/EditorTopbar.module.scss
@@ -1,111 +1,112 @@
-.Root {
-  container-name: editortopbar;
-  height: 36px;
-  background-color: var(--theme-color-bg-2);
-  border-bottom: 2px solid var(--theme-color-bg-1);
-  display: flex;
-  align-items: stretch;
-  justify-content: space-between;
-}
-
-.LeftSide,
-.RightSide {
-  display: flex;
-  align-items: stretch;
-
-  // please use these general selectors with great caution
-  > div {
-    display: flex;
-    align-items: center;
-  }
-}
-
-.LeftSide {
-  flex-grow: 1;
-}
-
-.is-padded-s {
-  padding: 0 4px;
-}
-
-.is-padded {
-  padding: 0 8px;
-}
-
-.is-padded-l {
-  padding: 0 16px;
-}
-
-.LeftSide {
-  > div:not(:last-child) {
-    border-right: 1px solid var(--theme-color-bg-1);
-  }
-}
-
-.RightSide {
-  > div:not(:first-child) {
-    border-left: 1px solid var(--theme-color-bg-1);
-  }
-}
-
-.UrlBarWrapper {
-  flex-grow: 1;
-  min-width: 150px;
-  max-width: 500px;
-  margin-right: -1px;
-}
-
-.UrlBarTextInput {
-  width: 100%;
-
-  svg {
-    cursor: pointer;
-
-    &:hover {
-      path {
-        fill: var(--theme-color-fg-highlight);
-      }
-    }
-  }
-}
-
-.TooltipPositioner {
-  height: 32px;
-  padding-bottom: 1px;
-  display: flex !important;
-  flex-direction: column;
-  justify-content: center;
-}
-
-.TopbarSelect {
-  display: flex;
-  align-items: center;
-  cursor: pointer;
-
-  * {
-    color: var(--theme-color-fg-default);
-    fill: var(--theme-color-fg-default);
-  }
-
-  &:hover * {
-    color: var(--theme-color-fg-highlight);
-    fill: var(--theme-color-fg-highlight);
-  }
-}
-
-.ZoomSelect {
-  padding-right: 4px;
-  padding-left: 8px;
-}
-
-.DesignPreviewModeButton {
-  cursor: pointer;
-  pointer-events: all;
-}
-
-.DeployButton {
-  .Root.is-small & {
-    padding: 0 4px 0 8px;
-    min-width: 0;
-  }
-}
+.Root {
+  container-name: editortopbar;
+  height: 36px;
+  background-color: var(--theme-color-bg-2);
+  border-bottom: 2px solid var(--theme-color-bg-1);
+  display: flex;
+  align-items: stretch;
+  justify-content: space-between;
+}
+
+.LeftSide,
+.RightSide {
+  display: flex;
+  align-items: stretch;
+
+  // please use these general selectors with great caution
+  > div {
+    display: flex;
+    align-items: center;
+  }
+}
+
+.LeftSide {
+  flex-grow: 1;
+}
+
+.is-padded-s {
+  padding: 0 4px;
+}
+
+.is-padded {
+  padding: 0 8px;
+}
+
+.is-padded-l {
+  padding: 0 16px;
+}
+
+.LeftSide {
+  > div:not(:last-child) {
+    border-right: 1px solid var(--theme-color-bg-1);
+  }
+}
+
+.RightSide {
+  > div:not(:first-child) {
+    border-left: 1px solid var(--theme-color-bg-1);
+  }
+}
+
+.UrlBarWrapper {
+  flex-grow: 1;
+  min-width: 150px;
+  max-width: 500px;
+  margin-right: -1px;
+}
+
+.UrlBarTextInput {
+  width: 100%;
+
+  svg {
+    cursor: pointer;
+
+    &:hover {
+      path {
+        fill: var(--theme-color-fg-highlight);
+      }
+    }
+  }
+}
+
+.TooltipPositioner {
+  height: 32px;
+  padding-bottom: 1px;
+  display: flex !important;
+  flex-direction: column;
+  justify-content: center;
+}
+
+.TopbarSelect {
+  display: flex;
+  align-items: center;
+  cursor: pointer;
+
+  * {
+    color: var(--theme-color-fg-highlight);
+    fill: var(--theme-color-fg-highlight);
+  }
+
+  &:hover * {
+    color: var(--theme-color-fg-highlight);
+    fill: var(--theme-color-fg-highlight);
+    opacity: 0.8;
+  }
+}
+
+.ZoomSelect {
+  padding-right: 4px;
+  padding-left: 8px;
+}
+
+.DesignPreviewModeButton {
+  cursor: pointer;
+  pointer-events: all;
+}
+
+.DeployButton {
+  .Root.is-small & {
+    padding: 0 4px 0 8px;
+    min-width: 0;
+  }
+}
diff --git a/packages/noodl-editor/src/editor/src/views/NodeGraphComponentTrail/NodeGraphComponentTrail.module.scss b/packages/noodl-editor/src/editor/src/views/NodeGraphComponentTrail/NodeGraphComponentTrail.module.scss
index 2eecc0c..fc3851b 100644
--- a/packages/noodl-editor/src/editor/src/views/NodeGraphComponentTrail/NodeGraphComponentTrail.module.scss
+++ b/packages/noodl-editor/src/editor/src/views/NodeGraphComponentTrail/NodeGraphComponentTrail.module.scss
@@ -76,7 +76,7 @@
   }
 
   &.is-current {
-    background-color: var(--theme-color-secondary);
+    background-color: var(--theme-color-bg-4);
     position: relative;
     z-index: 1;
   }
diff --git a/packages/noodl-editor/src/editor/src/views/NodePicker/components/NodePickerCategory/NodePickerCategory.tsx b/packages/noodl-editor/src/editor/src/views/NodePicker/components/NodePickerCategory/NodePickerCategory.tsx
index bd568cf..bea1055 100644
--- a/packages/noodl-editor/src/editor/src/views/NodePicker/components/NodePickerCategory/NodePickerCategory.tsx
+++ b/packages/noodl-editor/src/editor/src/views/NodePicker/components/NodePickerCategory/NodePickerCategory.tsx
@@ -1,12 +1,14 @@
+import { CustomPropertyAnimation, useCustomPropertyValue } from '@noodl-hooks/useCustomPropertyValue';
 import classNames from 'classnames';
 import React, { ReactNode, useEffect, useState } from 'react';
+
 import { NodeType } from '@noodl-constants/NodeType';
+
 import { Collapsible } from '@noodl-core-ui/components/layout/Collapsible';
+import { Text, TextSize, TextType } from '@noodl-core-ui/components/typography/Text';
+import { Title, TitleSize, TitleVariant } from '@noodl-core-ui/components/typography/Title';
 
 import css from './NodePickerCategory.module.scss';
-import { CustomPropertyAnimation, useCustomPropertyValue } from '@noodl-hooks/useCustomPropertyValue';
-import { Title, TitleSize, TitleVariant } from '@noodl-core-ui/components/typography/Title';
-import { Text, TextSize, TextType } from '@noodl-core-ui/components/typography/Text';
 
 interface NodePickerCategoryProps {
   title: string;
@@ -86,7 +88,7 @@ export default function NodePickerCategory({
             css['Arrow'],
             isCollapsedState ? css['Arrow--is-collapsed'] : css['Arrow--is-not-collapsed']
           ])}
-          src="../assets/icons/editor/right_arrow_22.svg"
+          src="/assets/icons/editor/right_arrow_22.svg"
         />
       </header>
 
diff --git a/packages/noodl-editor/src/editor/src/views/NodePicker/tabs/NodeLibrary/NodeLibrary.tsx b/packages/noodl-editor/src/editor/src/views/NodePicker/tabs/NodeLibrary/NodeLibrary.tsx
index cba28e7..74dc0de 100644
--- a/packages/noodl-editor/src/editor/src/views/NodePicker/tabs/NodeLibrary/NodeLibrary.tsx
+++ b/packages/noodl-editor/src/editor/src/views/NodePicker/tabs/NodeLibrary/NodeLibrary.tsx
@@ -180,7 +180,7 @@ export function NodeLibrary({ model, parentModel, pos, attachToRoot, runtimeType
                     createNewComment(model, pos);
                     e.stopPropagation();
                   }}
-                  icon={<img src="../assets/icons/comment.svg" />}
+                  icon={<img src="/assets/icons/comment.svg" />}
                 />
               </NodePickerSection>
             ) : null}
diff --git a/packages/noodl-editor/src/editor/src/views/lessons/LessonLayerView.css b/packages/noodl-editor/src/editor/src/views/lessons/LessonLayerView.css
index 07e50ba..2307f77 100644
--- a/packages/noodl-editor/src/editor/src/views/lessons/LessonLayerView.css
+++ b/packages/noodl-editor/src/editor/src/views/lessons/LessonLayerView.css
@@ -48,8 +48,8 @@
 }
 
 .lesson-item.selected {
-  background-color: var(--theme-color-fg-highlight);
-  color: var(--theme-color-secondary-dim);
+  background-color: var(--theme-color-bg-4);
+  color: var(--theme-color-fg-highlight);
   opacity: 1;
   transition: background-color 200ms, opacity 200ms;
 }
@@ -128,9 +128,9 @@
 }
 
 .lesson-item-popup {
-  background-color: var(--theme-color-secondary);
+  background-color: var(--theme-color-bg-3);
   width: 512px;
-  color: white;
+  color: var(--theme-color-fg-highlight);
   padding: 8px;
 }
 
diff --git a/packages/noodl-editor/src/editor/src/views/panels/search-panel/search-panel.module.scss b/packages/noodl-editor/src/editor/src/views/panels/search-panel/search-panel.module.scss
index 40043b6..6468438 100644
--- a/packages/noodl-editor/src/editor/src/views/panels/search-panel/search-panel.module.scss
+++ b/packages/noodl-editor/src/editor/src/views/panels/search-panel/search-panel.module.scss
@@ -17,10 +17,10 @@
   }
 
   &.is-active {
-    background-color: var(--theme-color-secondary);
+    background-color: var(--theme-color-bg-4);
 
     &:hover {
-      background-color: var(--theme-color-secondary-highlight);
+      background-color: var(--theme-color-bg-5);
     }
   }
 }
@@ -33,4 +33,4 @@
 
 .SearchResults {
   overflow: hidden overlay;
-}
\ No newline at end of file
+}