OpenNoodl/dev-docs/tasks/phase-3-editor-ux-overhaul/TASK-003-shared-component-system/COMP-overview.md

COMP Series: Shared Component System

Overview

The COMP series transforms Noodl's component sharing from manual zip file exchanges into a modern, Git-based collaborative ecosystem. Teams can share design systems via organization repositories, individuals can build personal component libraries, and improvements can flow back upstream via pull requests.

Target Environment

• Editor: React 19 version only
• Runtime: Not affected (components work in any runtime)
• Backwards Compatibility: Existing prefabs continue to work

Task Dependency Graph

COMP-001 (Prefab System Refactoring)
    │
    ├────────────────────────┬───────────────────────┐
    ↓                        ↓                       ↓
COMP-002 (Built-in)    COMP-003 (Export)      GIT-001 (OAuth)
    │                        │                       │
    ↓                        ↓                       │
    │                  COMP-004 (Org Components) ←───┘
    │                        │
    └────────────┬───────────┘
                 ↓
         COMP-005 (Version Control)
                 │
                 ↓
         COMP-006 (Forking & PR)

Task Summary

Task ID	Name	Est. Hours	Priority
COMP-001	Prefab System Refactoring	14-20	Critical
COMP-002	Built-in Prefabs	19-26	High
COMP-003	Component Export to Repository	19-25	High
COMP-004	Organization Components Repository	18-24	High
COMP-005	Component Import with Version Control	19-25	Medium
COMP-006	Component Forking & PR Workflow	28-35	Medium

Total Estimated: 117-155 hours

Implementation Order

Phase 1: Foundation (Weeks 1-2)

1. COMP-001 - Refactor prefab system for multiple sources

Phase 2: Local & Built-in (Weeks 3-4)

2. COMP-002 - Bundle essential prefabs with editor

Phase 3: Export & Organization (Weeks 5-7)

3. COMP-003 - Enable exporting to GitHub repositories
4. COMP-004 - Auto-detect and load organization repos

Phase 4: Version Control & Collaboration (Weeks 8-10)

5. COMP-005 - Track imports, detect updates
6. COMP-006 - Fork detection, PR workflow

Existing Infrastructure

ModuleLibraryModel

// Current implementation
class ModuleLibraryModel {
  modules: IModule[];    // External libraries
  prefabs: IModule[];    // Component bundles
  
  fetchModules(type: 'modules' | 'prefabs'): Promise<IModule[]>;
  installModule(path: string): Promise<void>;
  installPrefab(path: string): Promise<void>;
}

ProjectImporter

// Handles actual component import
class ProjectImporter {
  listComponentsAndDependencies(dir, callback);
  checkForCollisions(imports, callback);
  import(dir, imports, callback);
}

NodePicker

packages/noodl-editor/src/editor/src/views/NodePicker/
├── NodePicker.tsx           # Main component
├── NodePicker.context.tsx   # State management
├── tabs/
│   ├── NodeLibrary/         # Built-in nodes
│   ├── NodePickerSearchView/ # Prefabs & modules
│   └── ImportFromProject/   # Import from other project
└── components/
    └── ModuleCard/          # Prefab/module display card

Export Functionality

// exportProjectComponents.ts
export function exportProjectComponents() {
  // Shows export popup
  // User selects components
  // Creates zip file with dependencies
}

New Architecture

PrefabRegistry (COMP-001)

Central hub for all prefab sources:

class PrefabRegistry {
  private sources: Map<string, PrefabSource>;
  
  registerSource(source: PrefabSource): void;
  getAllPrefabs(): Promise<PrefabMetadata[]>;
  installPrefab(id: string): Promise<void>;
}

Source Types

Source	Priority	Description
BuiltInPrefabSource	100	Bundled with editor
OrganizationPrefabSource	80	Team component repos
PersonalPrefabSource	70	User's own repos
DocsPrefabSource	50	Community prefabs

Component Tracking (COMP-005)

interface ImportedComponent {
  componentId: string;
  source: ComponentSource;
  importedVersion: string;
  isFork: boolean;
  updateAvailable?: string;
  activePR?: PRInfo;
}

Repository Structure Convention

All component repositories follow this structure:

noodl-components/
├── index.json              # Repository manifest
├── README.md               # Documentation
├── LICENSE                 # License file
└── components/
    ├── component-name/
    │   ├── prefab.json     # Component metadata
    │   ├── component.ndjson # Component data
    │   ├── dependencies/   # Styles, variants
    │   └── assets/         # Images, fonts
    └── ...

Manifest Format (index.json)

{
  "name": "Acme Design System",
  "version": "2.1.0",
  "noodlVersion": ">=2.10.0",
  "components": [
    {
      "id": "acme-button",
      "name": "Acme Button",
      "version": "2.1.0",
      "path": "components/acme-button"
    }
  ]
}

Key User Flows

1. Team Member Imports Org Component

User opens NodePicker
    ↓
Sees "Acme Corp" section with org components
    ↓
Clicks "Clone" on AcmeButton
    ↓
Component imported, source tracked
    ↓
Later: notification "AcmeButton update available"

2. Developer Shares Component

User right-clicks component
    ↓
Selects "Export to Repository"
    ↓
Chooses personal repo or org repo
    ↓
Fills metadata (description, tags)
    ↓
Component committed and pushed

3. Developer Improves Org Component

User modifies imported AcmeButton
    ↓
System detects fork, shows badge
    ↓
User right-clicks → "Contribute Changes"
    ↓
PR created in org repo
    ↓
Team reviews and merges

Services to Create

Service	Purpose
PrefabRegistry	Central source management
ComponentTrackingService	Import/version tracking
ComponentExportService	Export to repositories
OrganizationService	Org detection & management
ComponentForkService	Fork detection & PR workflow

UI Components to Create

Component	Location	Purpose
ComponentSourceBadge	noodl-core-ui	Show source (Built-in, Org, etc.)
ForkBadge	noodl-core-ui	Show fork status
ExportToRepoModal	noodl-core-ui	Export workflow
ComponentUpdatesModal	noodl-core-ui	Update selection
ComponentDiffModal	noodl-core-ui	View changes
CreatePRModal	noodl-core-ui	PR creation
OrganizationSettings	noodl-core-ui	Org repo settings

Dependencies on Other Series

Required from GIT Series

• GIT-001 (GitHub OAuth) - Required for COMP-003, COMP-004

Enables for Future

• Community marketplace
• Component ratings/reviews
• Usage analytics

Testing Strategy

Unit Tests

• Source registration
• Metadata parsing
• Checksum calculation
• Version comparison

Integration Tests

• Full import flow
• Export to repo flow
• Update detection
• PR creation

Manual Testing

• Multiple organizations
• Large component libraries
• Offline scenarios
• Permission edge cases

Cline Usage Notes

Before Starting Each Task

1. Read task document completely
2. Review existing prefab system:
   • modulelibrarymodel.ts
   • projectimporter.js
   • NodePicker/ views
3. Understand export flow:
   • exportProjectComponents.ts

Key Gotchas

1. Singleton Pattern: ModuleLibraryModel.instance is used everywhere
2. Async Import: Import process is callback-based, not Promise
3. Collision Handling: Existing collision detection must be preserved
4. File Paths: Components use relative paths internally

Testing Prefabs

# Run editor tests
npm run test:editor

# Manual: Open NodePicker, try importing prefab

Success Criteria (Series Complete)

1. ✅ Multiple prefab sources supported
2. ✅ Built-in prefabs available offline
3. ✅ Components exportable to GitHub
4. ✅ Organization repos auto-detected
5. ✅ Import source/version tracked
6. ✅ Updates detected and installable
7. ✅ Forks can create PRs upstream

Future Work (Post-COMP)

The COMP series enables:

• Marketplace: Paid/free component marketplace
• Analytics: Usage tracking per component
• Ratings: Community ratings and reviews
• Templates: Project templates from components
• Subscriptions: Organization component subscriptions

Files in This Series

• COMP-001-prefab-system-refactoring.md
• COMP-002-builtin-prefabs.md
• COMP-003-component-export.md
• COMP-004-organization-components.md
• COMP-005-component-import-version-control.md
• COMP-006-forking-pr-workflow.md
• COMP-OVERVIEW.md (this file)