Research Notes
Relevant source files
The following files were used as context for generating this wiki page:
Research Notes provide a workspace for recording structured Markdown observations alongside source material. The system integrates a specialized editor, durable synchronization for offline-first workflows, and an automated recovery mechanism for unsaved drafts.
Sources: README.md, frontend/js/components/works.js:1016-1033
Editor and Interaction
PRKS uses EasyMDE to provide a Markdown editing experience. The editor integrates into the work detail view and supports semantic markup for linking research entities.
Feature Set
- Markdown Support: Provides standard Markdown formatting (bold, italic, lists, etc.).
- Research Linking: Supports
[[concept:Name]],[[argument:ID]], and[[pdf:annID]]markers for cross-referencing. - Autocomplete: Triggers suggestions for Work titles, Concepts, and PDF annotations when typing
[[. - Live Preview: Renders Markdown into sanitized HTML, resolving internal wiki links into navigable application routes.
Sources: frontend/js/components/works.js:1030-1085, frontend/js/components/works.js:630-650
Editor Lifecycle
The system initializes the editor through initEasyMDE during the work-detail mount sequence. It captures a resourceTicket to ensure the editor instance remains bound to the correct tab generation and Work ID.
Durable Synchronization
Research Notes use a local-first synchronization model. Edits are recorded as durable operations that persist in the browser even when the application is offline or the server is unreachable.
Save Pipeline
- Debounce: Keystrokes trigger a 2-second debounce timer (
saveNotesTimeout). - Draft Entry: The system creates a session entry in
prksWorkResearchDraftsto track the current text and edit generation. - Queueing: When the timer expires, the system enqueues a
SET_WORK_RESEARCH_NOTEoperation. - Conflict Handling: If the server reports a
REVISION_CONFLICTor if the aggregate is busy (scope_busy), the system retains the body asblockedand schedules a retry.
Sources: frontend/js/components/works.js:1145-1155, frontend/js/components/works.js:1196-1210, tests/e2e/test_work_notes_offline.py:101-118
Session States
| State | Description |
|---|---|
drafting | User is currently typing; changes are not yet queued. |
saving | An operation is currently being sent to the server. |
blocked | Save refused due to an in-flight operation (scope_busy); scheduled for retry. |
committed | Text successfully acknowledged by the server. |
error | Terminal failure in the save pipeline. |
Sources: frontend/js/components/works.js:46-65, frontend/js/components/works.js:1240-1246
Draft Recovery
The recovery system protects against data loss from tab closures, browser crashes, or storage failures. It uses a separate IndexedDB database (prks-editor-recovery-v1) to store drafts independently of the primary sync ledger.
Recovery Workflow
If a tab closes before a save is acknowledged, the next time you open that Work, the system evaluates the recovered draft:
- Auto-Restore: Applies the draft automatically if the server base is unchanged and no newer text exists.
- Review Dialog: If the note has changed on the server or another tab has newer text, the system provides a "Review" interface to compare and merge changes.
Sources: frontend-app/src/features/work/research-notes-recovery.ts:15-30, frontend/js/components/works.js:150-175, tests/e2e/test_work_notes_offline.py:270-285
Configuration and Constraints
The system enforces several technical limits to ensure performance and storage reliability.
| Parameter | Value | Description |
|---|---|---|
saveNotesTimeout | 2000 ms | Debounce interval before queueing a save. |
PRKS_RESEARCH_DRAFT_MAX_COMMITTED | 64 | Maximum number of acknowledged drafts retained in memory. |
PRKS_WIKI_HINT_MAX | 50 | Maximum results shown in autocomplete lists. |
PRKS_RESEARCH_NOTES_BUSY_RETRY_MAX_MS | 30000 ms | Maximum back-off interval for retrying blocked saves. |
Sources: frontend/js/components/works.js:1146, frontend/js/components/works.js:42, frontend/js/components/works.js:1161
Research Notes act as a central hub for knowledge synthesis within PRKS. By combining local-first durability with automatic draft recovery, the system ensures that user observations remain persistent and consistent across sessions.