<!-- source-hash: ad455db496eef8ee2c54f68792ebfef2 -->
Defines the canonical wire-shape interfaces for roadmap items consumed by the chat roadmap card and the public `/api/roadmap` endpoint.

## Key Components

### `RoadmapItem`
Strongly-typed entity mirroring the `roadmap_items` projection produced by `transformTask()` in `clickup-sync-utils.ts`. Represents a single ClickUp task surfaced as a public roadmap entry.

| Field | Type | Description |
|---|---|---|
| `id` | `string` | Unique identifier |
| `status` / `statusColor` | `string` | Display status and its hex/named color |
| `icon` | `string \| null` | Optional icon URL |
| `figmaUrl` | `string \| null` | Linked Figma design |
| `screenshots` | `string[]` | Attached screenshot URLs |
| `targetVersion` | `string \| null` | Planned release version |
| `upvotes` / `downvotes` | `number` | Community voting counts |
| `quarter` | `string` | Planning quarter label |
| `clickupUrl` | `string` | Canonical ClickUp task URL |
| `customItemId` | `number \| null` | ClickUp task-type taxonomy ID (e.g. `1008`=Bug, `1009`=Request, `1010`=Feature) — drives type icons via `getTaskTypeIcon` |

### `RoadmapStaleness`
Tracks cache freshness for roadmap data synced from ClickUp.

| Field | Type | Description |
|---|---|---|
| `lastSyncedAt` | `string \| null` | ISO timestamp of last successful sync |
| `staleSinceMs` | `number` | Milliseconds elapsed since last sync |

## Usage Example

```typescript
import type { RoadmapItem, RoadmapStaleness } from '@/components/chat/types/entities/roadmap-item';

const item: RoadmapItem = {
  id: 'task_abc123',
  title: 'Dark mode support',
  description: 'Add system-level dark mode across all views',
  status: 'In Progress',
  statusColor: '#f5a623',
  icon: null,
  figmaUrl: 'https://figma.com/file/...',
  screenshots: [],
  targetVersion: 'v2.4.0',
  upvotes: 42,
  downvotes: 3,
  quarter: 'Q3 2025',
  clickupUrl: 'https://app.clickup.com/t/abc123',
  customItemId: 1010, // Feature
};

const staleness: RoadmapStaleness = {
  lastSyncedAt: '2025-07-01T12:00:00Z',
  staleSinceMs: 3600000, // 1 hour
};
```

> **Import note:** Always import from `@/components/chat/types/entities/roadmap-item` for the strongly-typed shape. The legacy `RoadmapItem` stub in `product-release/release-detail-page.tsx` is untyped (`{ id: string; [key: string]: unknown }`) and will be reconciled in a follow-up.