Skinoculars Assistant

Expert assistant for developing and maintaining Skinoculars, an interactive 3D skin anatomy visualization built with React and Three.js.

Project Context

Skinoculars renders a procedurally generated cross-section of human skin with explorable layers (epidermis, dermis, hypodermis) and anatomical structures (hair follicles, sweat glands, blood vessels, collagen). The application features disease profiles, guided tours, quizzes, and multi-language support.

Tech Stack

Development Workflow

Setup and Running

1. Install dependencies: `npm install`

2. Start dev server: `npm run dev` (opens http://localhost:3000)

3. Build for production: `npm run build`

4. Preview build: `npm run preview`

Architecture Guidelines

**Entry Points:**

**Core Components (`/components`):**

**Data Modules (root):**

Key Implementation Patterns

1. Procedural Anatomy Generation

The `SkinScene` component uses `buildAnatomy(params)` to procedurally generate 3D geometry based on `ModelParameters`. Disease profiles modify these parameters:

```typescript

const params = computeParameters(diseaseId);

const anatomy = buildAnatomy(params);

```

When implementing new anatomical structures:

2. State Management

`App.tsx` is the single source of truth for all UI state:

`SkinScene` receives this state as props and applies changes via `useEffect` hooks. Never store Three.js state in component state—apply props directly to scene objects.

3. Raycasting for Interaction

Click and hover detection uses Three.js raycasting. When creating interactive objects:

4. Localization

All user-facing content supports `LocalizedString` type:

```typescript

type LocalizedString = string | { en: string; es?: string; ar?: string };

```

Use the `getLocalizedString(value, lang)` helper to resolve localized content. When adding new content:

5. Clipping Plane

Slice view uses a horizontal `THREE.Plane` that clips all materials. When adding new geometry:

Common Tasks

Adding a New Anatomical Structure

1. Define geometry generation in `buildAnatomy()` in `SkinScene.tsx`

2. Add structure type to TypeScript types in `types.ts`

3. Set `userData.type` on mesh for raycasting

4. Add educational content to `constants.ts` (`STRUCTURE_CONTENT`)

5. Add visibility toggle in `Controls.tsx`

6. Update state management in `App.tsx`

Creating a Disease Profile

1. Add disease ID to `DiseaseID` type in `types.ts`

2. Create parameter overrides in `diseaseProfiles.ts`

3. Document affected parameters and visual changes

4. Test procedural generation with new parameters

Adding a Guided Tour

1. Define camera waypoints in `tours.ts`

2. Include structure highlights and narrative text

3. Support localization for all text content

4. Test camera animations and transitions

Implementing Quiz Questions

1. Add questions to `quiz.ts`

2. Link correct answers to specific structure IDs

3. Provide localized feedback messages

4. Ensure questions integrate with raycasting selection

Best Practices

1. **Keep procedural generation pure**: `buildAnatomy()` should be deterministic based on parameters

2. **Minimize Three.js state**: Derive scene state from React props, don't duplicate in component state

3. **Use TypeScript strictly**: Define types for all data structures, especially procedural parameters

4. **Optimize raycasting**: Limit raycaster checks to interactive objects only

5. **Support localization**: Always use `LocalizedString` type for user-facing text

6. **Document parameters**: Comment what each `ModelParameter` controls visually

7. **Test across zoom levels**: Ensure structures render correctly at macro/meso/micro scales

8. **Profile performance**: Use Chrome DevTools Performance tab for Three.js frame drops

File Organization

```

/

├── index.html # HTML shell with CDN imports

├── index.tsx # React mount

├── App.tsx # Main app state

├── components/

│ ├── SkinScene.tsx # Three.js scene

│ ├── Controls.tsx # UI controls

│ └── InfoPanel.tsx # Info display

├── types.ts # TypeScript definitions

├── constants.ts # Educational content

├── diseaseProfiles.ts # Disease presets

├── zoomLevels.ts # Camera poses

├── tours.ts # Guided tours

├── quiz.ts # Quiz questions

└── timelines.ts # Process animations

```

Troubleshooting

Resources