Notes

Plinken includes a block-based note editor for writing session notes, lyrics, production plans, or any text alongside your project. Notes use Y.js CRDTs for real-time collaborative editing across team members in a Space.

Opening Notes

Action	Description
Notebook Panel	Toggle the note list sidebar
Note Editor	Opens when you select or create a note

Note Model

Each note has:

Property	Type	Description
`id`	string	Unique UUID
`title`	string	Extracted from the first line of content
`created_by`	string	Creator’s user ID
`created_at`	i64	Creation timestamp (ms since epoch)
`modified_at`	i64	Last modification timestamp (ms since epoch)

Block-Based Content

Note content is stored as an array of blocks (similar to Notion). Each block has:

Property	Type	Description
`id`	string	Unique block ID (e.g., `blk_7fa`)
`type`	BlockType	Block kind — see table below
`props`	BlockProps	Additional properties (heading level, checked state, etc.)
`text`	string	Text content
`children`	Block[]	Nested child blocks

Block Types

Type	Markdown	Rendered As
Paragraph	plain text	Normal text
Heading	`# H1`, `## H2`, `### H3`	Heading (level 1–3)
BulletList	`- item` or `* item`	Bullet point (•)
NumberedList	`1. item`	Numbered item
Todo	`- [ ] task` or `- [x] task`	Checkbox (☐ / ☑)
Quote	`> text`	Blockquote (│)
Divider	`---`	Horizontal rule
Code	```lang	Code block with optional language

Block Properties

Property	Type	Used By
`level`	u8 (1–3)	Heading
`checked`	bool	Todo
`number`	u32	NumberedList
`language`	string	Code

Markdown Shortcuts

Type markdown patterns and they’re automatically converted to blocks:

You Type	Converts To
`# Title`	Heading 1
`## Subtitle`	Heading 2
`### Section`	Heading 3
`- Item`	Bullet list
`* Item`	Bullet list
`1. Item`	Numbered list
`- [ ] Task`	Unchecked todo
`- [x] Task`	Checked todo
`> Quote`	Blockquote
`---`	Divider
```	Code block

Creating & Managing Notes

Create a Note

Create a new note by calling the module’s create_note method:

-- From Lua scripts, use commands to interact
pl.log("Notes are managed through the UI")

Notes are created with:

A UUID v4 identifier
The current user’s ID as creator
Current timestamp for created/modified
Content initialized as a Y.Doc with the title text

Search & Filter

The notebook panel supports:

Feature	Description
Search	Filter notes by title text and content (case-insensitive)
Sort	Choose from four sort modes (see below)

Sort Modes

Mode	Label	Description
`ModifiedDesc`	Newest First	Most recently modified first (default)
`ModifiedAsc`	Oldest First	Least recently modified first
`TitleAsc`	A → Z	Alphabetical by title
`TitleDesc`	Z → A	Reverse alphabetical by title

Delete a Note

Deleting a note:

Removes the note metadata from the list
Destroys the Y.Doc instance
Clears the selection if the deleted note was selected
Queues a delete request to the server (in collaborative mode)

Collaborative Editing

Notes use Y.js (via the yrs Rust implementation) for conflict-free collaborative editing.

How It Works

Y.Doc per note — Each note has a Y.Doc containing a Y.Text field for content
Local edits → Generate Y.js updates → Queued as PendingDocUpdate → Sent to server
Remote edits → Server broadcasts Y.js updates → Applied locally via apply_remote_update
Sync — On first access, the full doc state is synced from the server

Pending Operations

The Notes module queues several types of operations for server communication:

Operation	Description
Updates	Y.Doc binary updates (content changes)
Sync Requests	Request full doc state for notes not yet loaded
Creates	New notes to be created on the server
Title Updates	Title changes to broadcast to collaborators
Deletes	Notes to be deleted on the server

Title Sync

Titles are derived from the first line of note content. When you edit a note:

The title in the metadata is updated
A pending_title_update is queued for server broadcast
Remote title updates arrive via update_note_title and refresh the local display

Storage

Aspect	Details
Persistence	Local SQLite database
Content format	Y.Doc binary state (base64 for transport)
Sync	Y.js CRDT updates over WebSocket (in Spaces)
Module ID	`notes`

Modified Time Display

Notes show relative timestamps in the list:

Time Difference	Display
< 60 seconds	”Just now”
< 1 hour	”5m ago”
< 1 day	”3h ago”
< 1 week	”2d ago”
≥ 1 week	”Mar 15” (date format)