# Annotations & Voting System — Design

## Goal

Add thread-centric comments (object-level and region-pinned) and per-object upvoting to refboard, turning it into a collaborative feedback tool for game dev art review and mood board curation.

## Core Decisions

| Decision | Choice |
|----------|--------|
| Comment anchoring | Both object-level and region-pinned (anchor_type + nullable pinX/pinY) |
| Pin coordinates | Relative 0-1 range (survives transforms naturally) |
| Structure | Thread-centric: one pin = one thread, flat replies inside |
| Reply depth | Flat (v1) — root comment + flat replies, no nested threading |
| Thread status | Enum: open, resolved, archived (with resolved_by, resolved_at) |
| Voting | Simple upvote per object, one vote per user, toggle on/off |
| Real-time sync | Everything live via socket events, server-authoritative |
| Socket broadcast | Include sender — canonical event is the single codepath for all clients |
| Canvas UX | Pin markers + side panel + Review Mode (soft, not modal) |
| Object delete | Soft orphan — comments hidden from canvas, visible in panel |
| Object duplicate | Comments do not copy |
| Object ID stability | Scene object UUIDs must remain stable across saves, sync, and reloads |

## Critical Assumption

`object_id` in threads/votes references scene object UUIDs inside `canvas_state`. These IDs **must remain stable** across saves, sync, and board reloads. This is already the case in the current SceneManager (objects get UUIDs at creation, preserved through all operations), but it is a hard dependency for this feature.

---

## Data Model

### `comment_threads` table

Thread is the anchor — one pin = one thread. Carries the spatial/object binding.

```sql
CREATE TABLE IF NOT EXISTS comment_threads (
  id TEXT PRIMARY KEY,
  board_id TEXT NOT NULL REFERENCES boards(id) ON DELETE CASCADE,
  object_id TEXT NOT NULL,              -- scene object UUID (stable across saves)
  anchor_type TEXT NOT NULL DEFAULT 'object',  -- 'object' | 'point' (future: 'rect')
  pin_x REAL,                           -- null for anchor_type='object', 0-1 for 'point'
  pin_y REAL,
  status TEXT NOT NULL DEFAULT 'open',  -- 'open' | 'resolved' | 'archived'
  resolved_by TEXT REFERENCES users(id),
  resolved_at TEXT,
  comment_count INTEGER NOT NULL DEFAULT 1,  -- denormalized, includes root comment
  last_commented_at TEXT,                    -- denormalized, updated on each reply
  last_commented_by TEXT,                    -- denormalized, user_id of last commenter
  created_by TEXT NOT NULL REFERENCES users(id),
  created_at TEXT NOT NULL DEFAULT (datetime('now')),
  updated_at TEXT NOT NULL DEFAULT (datetime('now'))
);

CREATE INDEX IF NOT EXISTS idx_threads_board ON comment_threads(board_id);
CREATE INDEX IF NOT EXISTS idx_threads_object ON comment_threads(board_id, object_id);
```

### `comments` table

Flat replies inside threads. No anchor fields — positioning belongs to the thread.
No parent_id in v1 — all replies are flat, ordered by created_at.

```sql
CREATE TABLE IF NOT EXISTS comments (
  id TEXT PRIMARY KEY,
  thread_id TEXT NOT NULL REFERENCES comment_threads(id) ON DELETE CASCADE,
  user_id TEXT NOT NULL REFERENCES users(id),
  author_name TEXT NOT NULL,            -- snapshot at creation time
  author_color TEXT,                    -- user color snapshot for avatar
  content TEXT NOT NULL,
  edited_at TEXT,                       -- set on edit, null if never edited
  created_at TEXT NOT NULL DEFAULT (datetime('now'))
);

CREATE INDEX IF NOT EXISTS idx_comments_thread ON comments(thread_id);
```

### `object_votes` table

```sql
CREATE TABLE IF NOT EXISTS object_votes (
  board_id TEXT NOT NULL REFERENCES boards(id) ON DELETE CASCADE,
  object_id TEXT NOT NULL,
  user_id TEXT NOT NULL REFERENCES users(id),
  created_at TEXT NOT NULL DEFAULT (datetime('now')),
  PRIMARY KEY (board_id, object_id, user_id)
);

CREATE INDEX IF NOT EXISTS idx_votes_object ON object_votes(board_id, object_id);
```

### Object lifecycle

**Transform**: Pins derive position from object bounds each frame. Relative coords (0-1) survive move/scale/rotate automatically.

**Delete**: Don't hard-delete threads. Threads whose object_id no longer exists in canvas_state are "orphaned" — hidden from canvas pins but visible in panel under a "Deleted items" section. Review history matters.

**Duplicate**: Comments do not copy with the object. Clean slate for the duplicate.

---

## API Endpoints

### Threads & Comments

```
GET    /api/boards/:boardId/threads                          — all threads + comments for board
POST   /api/boards/:boardId/threads                          — create thread + first comment
                                                               { object_id, anchor_type, pin_x?, pin_y?, content }
PATCH  /api/boards/:boardId/threads/:threadId                — update status { status: 'open'|'resolved'|'archived' }
DELETE /api/boards/:boardId/threads/:threadId                 — delete thread + all comments

POST   /api/boards/:boardId/threads/:threadId/comments       — add reply { content }
PUT    /api/boards/:boardId/threads/:threadId/comments/:id   — edit own comment { content }
DELETE /api/boards/:boardId/threads/:threadId/comments/:id   — delete own comment
```

### Votes

```
GET    /api/boards/:boardId/votes                            — all votes for board
POST   /api/boards/:boardId/votes                            — toggle vote { object_id }
```

### Permissions

- **Public (unauthenticated)**: read-only — can view threads and vote counts, cannot comment or vote
- **Viewer** (collection member): read threads, add threads/comments, vote
- **Editor**: all viewer + resolve/archive threads
- **Owner**: all editor + delete any thread/comment

Public boards expose feedback as read-only. Participating in the review loop requires authentication and collection membership.

---

## Socket Events

Server-authoritative: client sends REST request → server writes DB → server broadcasts canonical event to **all clients in the room including sender**. The REST response returns minimal confirmation (id, timestamp); the socket event is the single codepath that updates local state for everyone.

| Event | Payload |
|-------|---------|
| `thread:add` | `{ boardId, thread, comment }` |
| `thread:status` | `{ boardId, threadId, status, resolvedBy, resolvedAt }` |
| `thread:delete` | `{ boardId, threadId }` |
| `comment:add` | `{ boardId, threadId, comment }` |
| `comment:update` | `{ boardId, threadId, commentId, content, editedAt }` |
| `comment:delete` | `{ boardId, threadId, commentId }` |
| `vote:toggle` | `{ boardId, objectId, userId, active }` |

All broadcast to `board:${boardId}` room.

---

## Canvas UX — Pin Markers

### Pin appearance
- Small circle (16-20px at 1x zoom, scale-independent)
- Unresolved: red fill with white thread count
- Resolved: gray fill, dimmed (hidden by default, toggle to show)
- Region pins: positioned at `(obj.x + pinX * obj.w, obj.y + pinY * obj.h)` in world space
- Object-level pins: top-right corner of object bounding box
- Do NOT render comment text on canvas — pins are minimal dots only

### Vote badge
- Small upvote arrow + count pill at bottom-right of object
- Only visible when count > 0 or in Review Mode

### Interaction
- Click pin → opens panel scrolled to that thread
- Hover pin → tooltip: author + first line of content
- Pins and vote badges visible in **Review Mode**

---

## Review Mode

Soft toggle in toolbar — not a separate locked mode. When enabled:

- Comment pins and vote badges become visible on canvas
- Editing still works — selection, move, resize all functional
- A "Place comment" subtool activates pin placement (crosshair cursor, click on object to place)
- Panel auto-opens to feedback view
- Exiting the subtool returns to normal select behavior

When disabled:

- Pins and badges hidden — clean canvas for arranging/editing
- Panel can still be opened manually but defaults to layer view

This keeps Review Mode useful without trapping users in a separate workflow.

---

## Panel UX — Feedback Panel

### Layout
- Right-side panel, 280px wide, same pattern as LayerPanel
- Toggled via toolbar button (comment icon) or auto-opens in Review Mode
- Tabs or toggle to switch between Layer view and Feedback view

### Filters (top of panel)
- Unresolved only (default on)
- Mine only
- Selected object
- Most voted

### Sort options
- Newest activity
- Unresolved first
- By vote count

### Views

**1. Overview (no selection)**
- List of objects with active threads, grouped by object
- Each row: object name, unresolved thread count badge, vote count + vote button
- "Top voted" section at top for lightweight poll results
- "Deleted items" collapsible section at bottom for orphaned threads

**2. Object detail (object selected or pin clicked)**
- Object name + vote button + count at top
- List of threads for that object
- Each thread: pin indicator (object/point), author, timestamp, first comment preview, reply count, status badge
- Click to expand

**3. Thread expanded**
- Root comment + flat replies in chronological order
- Reply input at bottom
- Resolve/archive button (editor+)
- "Edited" label on modified comments
- Delete button on own comments
- "Jump to object" button — pans/zooms viewport to center on the target object

---

## Frontend State

### Loaded on board open
- `GET /api/boards/:boardId/threads` → `Map<string, Thread>` with nested comments
- `GET /api/boards/:boardId/votes` → `Map<string, Set<string>>` (objectId → userIds)

### Socket updates (single codepath for all clients including sender)
- `thread:add` → insert thread + comment, add pin to overlay
- `thread:status` → update status + resolved_by/at, re-render pin
- `thread:delete` → remove thread, remove pin
- `comment:add` → append to thread's comment list
- `comment:update` → update comment content + edited_at
- `comment:delete` → remove from thread's comment list
- `vote:toggle` → add/remove userId from vote set, update badge

### Pin overlay
- Separate PixiJS Container on viewport (above objects, below selection handles)
- Re-derives positions from object world bounds on viewport change
- Only rendered when Review Mode is active

---

## Implementation Order

Ship comments first, then votes, then review mode polish.

### Phase 1: Comments (core value)
1. Backend: DB schema (comment_threads, comments tables + indexes)
2. Backend: REST endpoints for threads and comments
3. Backend: Socket event relay in board-room.js
4. Frontend: State management (load on board open, socket handlers)
5. Frontend: Feedback panel (overview, object detail, thread views)

### Phase 2: Canvas Pins
6. Frontend: Review Mode toggle in toolbar
7. Frontend: Pin overlay rendering (PixiJS container)
8. Frontend: Pin placement subtool (click-to-place region pins)
9. Frontend: Jump-to-object from thread

### Phase 3: Voting
10. Backend: object_votes table + REST endpoints + socket events
11. Frontend: Vote button in panel + badge on canvas
12. Frontend: "Top voted" section in panel overview

### Phase 4: Polish
13. Frontend: Orphan detection (deleted objects, show in panel)
14. Frontend: Filters and sort options in panel
15. Frontend: "Edited" labels, timestamps, author snapshots