chore: commit pending workspace changes
This commit is contained in:
Hiren Kangad
@@ -0,0 +1,544 @@
|
||||
# RefBoard Product Expansion Plan — 2026-03-12
|
||||
|
||||
## Goal
|
||||
|
||||
Turn RefBoard from a collaborative media board into a stronger visual workspace that combines:
|
||||
|
||||
- PureRef-style media handling
|
||||
- Figma-style review and comments
|
||||
- Milanote-style notes and structure
|
||||
- Kosmik-style mixed-media research and retrieval
|
||||
|
||||
This plan is written for iterative implementation with code review after each slice.
|
||||
|
||||
---
|
||||
|
||||
## Working Model
|
||||
|
||||
### Roles
|
||||
|
||||
- **Builder session**: implements one scoped slice at a time
|
||||
- **Reviewer session**: reviews code for correctness, regressions, UX consistency, and plan adherence
|
||||
|
||||
### Delivery rules
|
||||
|
||||
- Ship in thin vertical slices, not broad unfinished scaffolding
|
||||
- Preserve existing board stability and current media workflows
|
||||
- Avoid overloading the current `text` element with unrelated behavior
|
||||
- Add first-class object types where semantics differ
|
||||
- Prefer migration-safe schema and scene-format extensions
|
||||
|
||||
### Definition of done for each slice
|
||||
|
||||
- Data model is explicit
|
||||
- UI behavior is testable manually
|
||||
- Socket sync behavior is defined
|
||||
- Save/load survives reload
|
||||
- Permissions are enforced
|
||||
- Existing image/video flows still work
|
||||
|
||||
---
|
||||
|
||||
## Current State Summary
|
||||
|
||||
### Already present
|
||||
|
||||
- Infinite canvas with images, GIFs, videos, drawings, text, frames/groups
|
||||
- Real-time sync
|
||||
- Upload pipeline with image/video support
|
||||
- Thread/comment backend and frontend groundwork
|
||||
- Votes groundwork
|
||||
- Mattermost import
|
||||
|
||||
### Main gaps
|
||||
|
||||
- Comments need to reach a polished Figma-like UX
|
||||
- No sticky notes / note cards
|
||||
- No PDF media type
|
||||
- No markdown/doc object
|
||||
- Current `text` object is too primitive for notes/docs
|
||||
- No strong retrieval layer for mixed media
|
||||
- No Milanote-style structural/workflow objects
|
||||
|
||||
---
|
||||
|
||||
## Product Principles
|
||||
|
||||
1. **Labels are not documents**
|
||||
Keep lightweight canvas text for labels and annotations.
|
||||
|
||||
2. **Every content type needs its own semantics**
|
||||
`text`, `sticky`, `pdf`, `markdown`, `comment`, and `task` should not collapse into one generic object.
|
||||
|
||||
3. **Canvas should stay visually fast**
|
||||
Large or dense content must degrade gracefully with zoom and viewport distance.
|
||||
|
||||
4. **Review is a first-class layer**
|
||||
Comments, pins, resolution state, and jump-to-context should feel native, not bolted on.
|
||||
|
||||
5. **Mixed media must be searchable**
|
||||
PDF text, markdown text, note text, filenames, and comments should converge in one retrieval model.
|
||||
|
||||
---
|
||||
|
||||
## Object Model Direction
|
||||
|
||||
### Keep
|
||||
|
||||
- `image`
|
||||
- `video`
|
||||
- `drawing`
|
||||
- `text` for lightweight labels
|
||||
- `group` / frame
|
||||
|
||||
### Add next
|
||||
|
||||
- `sticky` — visual note card
|
||||
- `pdf` — document or page-based asset object
|
||||
- `markdown` — rich document card with preview
|
||||
|
||||
### Add later
|
||||
|
||||
- `web` — URL/article/embed card
|
||||
- `task` — checklist/work item card
|
||||
- `connector` — relationship line
|
||||
- `column` or stronger structure container if needed beyond frames
|
||||
|
||||
---
|
||||
|
||||
## Zoom Behavior Rules
|
||||
|
||||
### `text`
|
||||
|
||||
- World-space label
|
||||
- Scales naturally with zoom
|
||||
- Best for captions and annotations
|
||||
|
||||
### `sticky`
|
||||
|
||||
- Canvas object with card chrome
|
||||
- Text remains readable longer than plain labels
|
||||
- Use clamped on-screen font sizing or simplified preview when zoomed out
|
||||
|
||||
### `markdown`
|
||||
|
||||
- Card preview on canvas
|
||||
- Full reading/editing in side panel or modal inspector
|
||||
- Do not render entire long documents at tiny zoom levels
|
||||
|
||||
### `comment`
|
||||
|
||||
- Review UI overlay behavior, not a regular scene text object
|
||||
|
||||
---
|
||||
|
||||
## Priority Plan
|
||||
|
||||
## Phase 1 — Review Layer Completion
|
||||
|
||||
### Objective
|
||||
|
||||
Finish comments into a reliable Figma-style review workflow before adding more content types.
|
||||
|
||||
### Scope
|
||||
|
||||
- Object-level comments
|
||||
- Point/region-pinned comments
|
||||
- Thread list + detail panel polish
|
||||
- Resolve/reopen flow
|
||||
- Unread state
|
||||
- Jump-to-object
|
||||
- Better pin visibility and interactions
|
||||
- Notification/toast behavior for incoming comments
|
||||
- Permissions for comment vs edit vs view
|
||||
|
||||
### Key tasks
|
||||
|
||||
1. Audit existing comments/votes code paths and close gaps
|
||||
2. Stabilize socket event flows and sender behavior
|
||||
3. Ensure orphan handling for deleted objects is sane
|
||||
4. Add unread/new indicators and active-thread focus behavior
|
||||
5. Tighten panel UX and pin hit-testing
|
||||
|
||||
### Acceptance criteria
|
||||
|
||||
- User can comment on an object and on a specific point
|
||||
- Another user sees updates live without reload
|
||||
- Threads can be resolved and reopened
|
||||
- Deleted objects do not break thread history
|
||||
- Jump-to-object is reliable
|
||||
- Review flow feels coherent on a live board
|
||||
|
||||
### Reviewer focus
|
||||
|
||||
- Event duplication
|
||||
- Board permission leaks
|
||||
- Orphaned thread correctness
|
||||
- Socket race conditions
|
||||
- UI regressions in editor layout
|
||||
|
||||
---
|
||||
|
||||
## Phase 2 — Sticky Notes
|
||||
|
||||
### Objective
|
||||
|
||||
Add Milanote-style note cards without damaging the current label text tool.
|
||||
|
||||
### Scope
|
||||
|
||||
- New `sticky` scene object
|
||||
- Preset colors/themes
|
||||
- Title/body or single-body variant
|
||||
- Resize behavior
|
||||
- Duplicate/copy-paste
|
||||
- Inline editing
|
||||
- Selection, layering, grouping
|
||||
|
||||
### Data model
|
||||
|
||||
Suggested fields:
|
||||
|
||||
```ts
|
||||
type StickyObject = {
|
||||
id: string;
|
||||
type: 'sticky';
|
||||
x: number; y: number; w: number; h: number;
|
||||
sx: number; sy: number; angle: number; z: number;
|
||||
opacity: number; locked: boolean; visible: boolean; name: string;
|
||||
title?: string;
|
||||
text: string;
|
||||
theme: string;
|
||||
fontSize: number;
|
||||
};
|
||||
```
|
||||
|
||||
### Key tasks
|
||||
|
||||
1. Extend scene schema and serialization
|
||||
2. Add Pixi renderer for note card
|
||||
3. Add editing UX
|
||||
4. Add toolbar action and shortcuts
|
||||
5. Validate transform, selection, save/load, sync
|
||||
|
||||
### Acceptance criteria
|
||||
|
||||
- Sticky can be created in one action
|
||||
- It looks like a note card, not raw canvas text
|
||||
- It persists and syncs correctly
|
||||
- It remains readable enough across zoom levels
|
||||
|
||||
### Reviewer focus
|
||||
|
||||
- Scene-format backward compatibility
|
||||
- Hitbox and transform correctness
|
||||
- Editing UX under zoom
|
||||
- Performance with many notes
|
||||
|
||||
---
|
||||
|
||||
## Phase 3 — PDF Support
|
||||
|
||||
### Objective
|
||||
|
||||
Make PDFs a first-class media type with strong review utility.
|
||||
|
||||
### Scope
|
||||
|
||||
- Upload PDF files
|
||||
- Backend page rasterization
|
||||
- PDF metadata storage
|
||||
- Page thumbnails / previews
|
||||
- Place full doc card or individual pages on canvas
|
||||
- Comment on page/region
|
||||
- Basic PDF text extraction for search preparation
|
||||
|
||||
### Product choice
|
||||
|
||||
Start with **page-based ingestion**, not an embedded fully interactive PDF viewer on the canvas.
|
||||
|
||||
Reason:
|
||||
|
||||
- simpler scene model
|
||||
- easier comments
|
||||
- better performance predictability
|
||||
- closer to board workflows
|
||||
|
||||
### Backend tasks
|
||||
|
||||
1. Accept `application/pdf`
|
||||
2. Generate page previews
|
||||
3. Store doc metadata: page count, dimensions, extracted text status
|
||||
4. Add asset routing for preview pages
|
||||
|
||||
### Frontend tasks
|
||||
|
||||
1. Add PDF upload handling
|
||||
2. Add PDF card/import dialog
|
||||
3. Support dragging pages onto canvas as scene objects
|
||||
4. Allow comments pinned to page content
|
||||
|
||||
### Acceptance criteria
|
||||
|
||||
- User uploads a PDF successfully
|
||||
- User can place page previews on canvas
|
||||
- PDF pages persist and sync like other assets
|
||||
- Comments can be attached to a page object
|
||||
|
||||
### Reviewer focus
|
||||
|
||||
- Processing failures and user feedback
|
||||
- Storage layout and cleanup
|
||||
- Large PDF performance
|
||||
- Whether page objects and source document records stay consistent
|
||||
|
||||
---
|
||||
|
||||
## Phase 4 — Text System Overhaul
|
||||
|
||||
### Objective
|
||||
|
||||
Fix the current text element so it remains strong for labels while not pretending to be a note/doc system.
|
||||
|
||||
### Scope
|
||||
|
||||
- Better text box layout and wrapping
|
||||
- Alignment
|
||||
- Curated font set
|
||||
- Background/padding for label chips if needed
|
||||
- Improved resize semantics
|
||||
- Better zoom behavior
|
||||
|
||||
### Explicit non-goal
|
||||
|
||||
Do not turn `text` into markdown or sticky notes.
|
||||
|
||||
### Acceptance criteria
|
||||
|
||||
- Text boxes wrap predictably
|
||||
- Editing overlay aligns correctly under zoom and rotation
|
||||
- Font options are intentional, not random browser defaults
|
||||
- Labels remain lightweight
|
||||
|
||||
### Reviewer focus
|
||||
|
||||
- Text measurement drift
|
||||
- Serialization of layout fields
|
||||
- Rotation/edit overlay bugs
|
||||
- Cross-browser behavior
|
||||
|
||||
---
|
||||
|
||||
## Phase 5 — Markdown Cards
|
||||
|
||||
### Objective
|
||||
|
||||
Add richer document-like content while keeping the canvas uncluttered.
|
||||
|
||||
### Scope
|
||||
|
||||
- New `markdown` object
|
||||
- Canvas preview card with title/excerpt
|
||||
- Source edit mode
|
||||
- Render mode
|
||||
- Links, lists, headings, code blocks
|
||||
- Open-full-doc side panel
|
||||
|
||||
### Product rule
|
||||
|
||||
Canvas shows a compact preview, not the entire markdown body at all zoom levels.
|
||||
|
||||
### Suggested fields
|
||||
|
||||
```ts
|
||||
type MarkdownObject = {
|
||||
id: string;
|
||||
type: 'markdown';
|
||||
x: number; y: number; w: number; h: number;
|
||||
sx: number; sy: number; angle: number; z: number;
|
||||
opacity: number; locked: boolean; visible: boolean; name: string;
|
||||
title: string;
|
||||
markdown: string;
|
||||
previewMode: 'card' | 'expanded';
|
||||
};
|
||||
```
|
||||
|
||||
### Acceptance criteria
|
||||
|
||||
- Markdown card can be created and edited
|
||||
- Canvas preview is readable and compact
|
||||
- Full content opens in panel/modal
|
||||
- Save/load/sync works without corruption
|
||||
|
||||
### Reviewer focus
|
||||
|
||||
- Unsafe markdown rendering
|
||||
- Performance of live render
|
||||
- Whether the object should stay on-canvas or move to inspector sooner
|
||||
|
||||
---
|
||||
|
||||
## Phase 6 — Search and Retrieval
|
||||
|
||||
### Objective
|
||||
|
||||
Make mixed-media boards retrievable, not just visually navigable.
|
||||
|
||||
### Scope
|
||||
|
||||
- Search across board titles, filenames, notes, markdown, comments
|
||||
- PDF extracted text indexing
|
||||
- Later OCR for images
|
||||
- Filter by object type, author, tag, updated time
|
||||
|
||||
### Acceptance criteria
|
||||
|
||||
- A user can search content inside a board and find the right object
|
||||
- Results can jump to canvas context
|
||||
- Search does not require full reload of large boards
|
||||
|
||||
### Reviewer focus
|
||||
|
||||
- Query performance
|
||||
- Index strategy
|
||||
- Search result relevance vs complexity
|
||||
|
||||
---
|
||||
|
||||
## Phase 7 — Structure and Workflow
|
||||
|
||||
### Objective
|
||||
|
||||
Bring in selected Milanote-style organization features after the content core is solid.
|
||||
|
||||
### Scope
|
||||
|
||||
- Better frames/sections
|
||||
- Optional columns/stacks
|
||||
- Connectors
|
||||
- Task/checklist cards
|
||||
- Better share roles: view, comment, edit
|
||||
- Presentation / clean-share mode
|
||||
- Export improvements
|
||||
|
||||
### Important constraint
|
||||
|
||||
Do not add task/workflow objects until notes, docs, and comments are already stable.
|
||||
|
||||
### Reviewer focus
|
||||
|
||||
- Product sprawl
|
||||
- Interaction conflicts with selection/grouping
|
||||
- Share-mode permission correctness
|
||||
|
||||
---
|
||||
|
||||
## Cross-Cutting Technical Work
|
||||
|
||||
### Scene format versioning
|
||||
|
||||
- Extend scene schema conservatively
|
||||
- Keep old boards loadable
|
||||
- Add migration helpers where needed
|
||||
|
||||
### Upload pipeline
|
||||
|
||||
- Add clear status feedback for every media type
|
||||
- Unify queued/processing/ready/failed states
|
||||
|
||||
### Performance
|
||||
|
||||
- Avoid rendering full-detail content when zoomed out
|
||||
- Ensure many notes/pages/comments do not tank frame rate
|
||||
|
||||
### Permissions
|
||||
|
||||
- Formalize role behavior:
|
||||
- `viewer`
|
||||
- `commenter`
|
||||
- `editor`
|
||||
- `owner`
|
||||
|
||||
### Export
|
||||
|
||||
- Board export to image
|
||||
- Board export to PDF
|
||||
- Selection export
|
||||
|
||||
---
|
||||
|
||||
## Recommended Implementation Order
|
||||
|
||||
1. Finish review/comments UX
|
||||
2. Add sticky notes
|
||||
3. Add PDF ingestion and page placement
|
||||
4. Overhaul plain text behavior
|
||||
5. Add markdown cards
|
||||
6. Add search and PDF text indexing
|
||||
7. Add structural/workflow features
|
||||
|
||||
---
|
||||
|
||||
## Suggested PR / Review Slices
|
||||
|
||||
### Slice A
|
||||
|
||||
- Review/comments gap audit and polish
|
||||
|
||||
### Slice B
|
||||
|
||||
- `sticky` scene object end-to-end
|
||||
|
||||
### Slice C
|
||||
|
||||
- PDF backend ingestion and metadata
|
||||
|
||||
### Slice D
|
||||
|
||||
- PDF page placement UI
|
||||
|
||||
### Slice E
|
||||
|
||||
- Text box overhaul
|
||||
|
||||
### Slice F
|
||||
|
||||
- Markdown card object
|
||||
|
||||
### Slice G
|
||||
|
||||
- Search and retrieval
|
||||
|
||||
Each slice should be reviewable independently and should not mix unrelated feature families.
|
||||
|
||||
---
|
||||
|
||||
## Risks
|
||||
|
||||
- Overloading the canvas with too many object semantics too early
|
||||
- Regressing existing image/video performance
|
||||
- Mixing review UI and content UI in confusing ways
|
||||
- Turning text into a catch-all object
|
||||
- Adding PDF support without strong processing/error handling
|
||||
|
||||
---
|
||||
|
||||
## Reviewer Checklist
|
||||
|
||||
- Is the slice aligned with the current phase?
|
||||
- Does it preserve current board behavior?
|
||||
- Is the object schema explicit and future-safe?
|
||||
- Are save/load/sync semantics correct?
|
||||
- Are permissions and roles enforced?
|
||||
- Does the UI feel coherent at different zoom levels?
|
||||
- Is there a simpler implementation that preserves the same product outcome?
|
||||
|
||||
---
|
||||
|
||||
## Next Action
|
||||
|
||||
Start with **Slice A / Phase 1**:
|
||||
|
||||
- review the current comments implementation
|
||||
- enumerate gaps against the desired review workflow
|
||||
- close the highest-value UX and correctness issues before adding new content types
|
||||
Reference in New Issue
Block a user