feat: add Notes Space with unified architecture (#698)

* feat(notes): add CodeMirror 6 dependencies

* refactor(notes): make NotesEditor standalone with defineModel

* feat(spaces): add dev space with editor demo

* fix(notes): hide header mark with trailing space, show code marks on block focus

* feat(notes): add rounded corners and padding to fenced code blocks

* fix(notes): show marks only when cursor is between them, not on entire line

* chore(dev): expand demo markdown content with all supported elements

* fix(notes): use primary color for links instead of accent

* feat(notes): add tab/shift-tab indentation support

* feat(notes): add smart list indentation with ordered list renumbering

* docs: add Notes Space design spec

* docs: update Notes Space spec after review

Address review findings:
- Watcher integration: ignore __spaces__/notes/ in snippet sync
- Own getNotesPaths() function, separate from snippet getPaths()
- Own notesRuntimeRef singleton cache
- Storage contracts and useStorage() integration
- Notes-specific reserved names (not reusing snippet list)
- Separate content update endpoint (PATCH /notes/:id/content)
- Note serialization: frontmatter + raw body (no fragment parsing)
- Composables re-export from index.ts
- notesState as separate electron-store object

* docs: address final review findings in Notes Space spec

- Scope watcher ignore to __spaces__/notes/ only (not __spaces__/ broadly)
- Use separate useNotesStorage() accessor instead of extending StorageProvider
- Own writeNoteFolderMetadata() (FolderRecord has defaultLanguage, NoteFolderRecord doesn't)
- Reuse shared pendingStateWriteByPath for state debounce
- Note to add 'notes' case in refreshAfterStorageSync() switch

* docs: add Notes Space implementation plan

* feat(notes): add notes storage types and contracts

Add NotesPaths, NotesState, MarkdownNote, NotesRuntimeCache and other
runtime types. Add notes contracts (NoteRecord, NotesStorage,
NotesFoldersStorage, NoteTagsStorage, NotesStorageProvider) to the
shared contracts file.

* feat(notes): add notes constants, paths, and validation support

Add getNotesPaths(), notesRuntimeRef singleton, notes-specific path
constants. Add folder path utilities (buildNotesFolderPathMap,
findNotesFolderById, etc.). Extend validateEntryName to accept 'note'
kind.

* feat(notes): add notes state persistence with shared debounce

Add loadNotesState, saveNotesState, ensureNotesStateFile that reuse
the shared pendingStateWriteByPath maps from the snippet runtime.
State version starts at 1.

* feat(notes): add note file I/O, serialization, and folder metadata

Add serializeNote (YAML frontmatter + raw markdown body), readNoteFromFile,
writeNoteToFile, persistNote, loadNotes, findNoteById, listNoteMarkdownFiles.
Add notes folder metadata read/write without legacy migration or
defaultLanguage.

* feat(notes): add notes search index with trigram matching

Add buildNotesSearchIndex, getNoteIdsBySearchQuery, and
invalidateNotesSearchIndex using the same trigram + word token
algorithm as snippet search.

* feat(notes): add notes sync, runtime cache, and barrel export

Add syncNotesFoldersWithDisk, syncNotesRuntimeWithDisk,
getNotesRuntimeCache, resetNotesRuntimeCache for the notes storage
runtime. Add barrel export index.ts for the notes runtime module.

* fix(notes): add missing META_FILE_NAME re-export in notes constants

* feat(notes): add notes folders CRUD storage

* feat(notes): add notes CRUD storage

* feat(notes): add notes tags storage, provider index, and barrel export

* feat(notes): add useNotesStorage accessor and ignore notes in snippet watcher

* feat(notes): add API DTOs for notes, note-folders, note-tags

* feat(notes): add REST API routes for notes, note-folders, note-tags

* feat(notes): register notes space, routing, and i18n keys

* feat(notes): add notes composables (useNotes, useNoteFolders, useNoteTags, useNotesApp)

* feat(notes): add 3-column notes space layout

* feat(notes): add notes sidebar with library and folder tree

* feat(notes): add virtualized notes list with search and context menu

* feat(notes): add notes editor pane connecting CM6 to composable

* feat(notes): add notes case to storage sync handler

When external vault changes are detected (e.g. sync from another device),
the notes space now refreshes folders, notes, and tags data.

* fix(notes): replace (api as any) casts with typed API method calls

* fix(notes): fix api:generate script and regenerate API client with notes endpoints

* fix(notes): add response schema to notes GET endpoint for proper API typing

* fix(notes): add external drop handler to move notes into folders via drag-drop

* feat(notes): add editor header with note name input and action buttons slot

* fix(notes): re-create editor when switching notes via key binding

* fix(notes): invalidate search index on state save so search finds new/updated notes

* fix(notes): invalidate search index when note content is updated

* fix(notes): rewrite search to match code space pattern with substring fallback

- Add w: token fallback when trigrams yield no candidates (short words)
- Use intersectSets for proper candidate narrowing
- Final check uses searchText.includes(normalizedQuery) for substring match
- ensureNotesSearchIndex now returns cache for caller use

* fix(notes): return empty trigrams for words < 3 chars to match code space behavior

* fix(notes-search): support one-character queries

* fix(notes-search): harden runtime cache behavior

* fix(notes): close note-space parity gaps

* chore: merge branch 'main' into feat/notes-editor-cm6-clean

* fix(notes-ui): align tags panel placement with code space

* feat: add tag input

Author: antonreshetov

.gitignore

@@ -8,4 +8,5 @@ node_modules
 components.d.ts
 auto-imports.d.ts
 .github/*-instructions.md
-.env
+.env
+docs/superpowers

docs/spaces/markdown-runtime-reuse-playbook.md

@@ -0,0 +1,114 @@
+# Markdown Runtime Reuse Playbook
+
+A concise guide for adding new markdown-backed entities without duplicating infrastructure.
+
+---
+
+## 1. Required Shared Primitives
+
+When adding a new markdown entity, you **must** use the following from `runtime/shared/` instead of reimplementing them.
+
+### `shared/path.ts`
+
+| Export | Purpose |
+|--------|---------|
+| `toPosixPath` | Normalize OS paths to forward-slash form |
+| `depthOfRelativePath` | Count directory depth of a relative path |
+| `normalizeDirectoryPath` | Ensure trailing slash, posix-normalized |
+| `listMarkdownFiles` | Walk a directory and return `.md` file paths |
+
+### `shared/folderIndex.ts`
+
+| Export | Purpose |
+|--------|---------|
+| `buildFolderPathMap` | Build `folderId → path` lookup from folder list |
+| `buildPathToFolderIdMap` | Build `path → folderId` reverse lookup |
+| `findFolderByIdPure` | Find a folder in a list by ID (no side effects) |
+| `getFolderSiblings` | Return all folders sharing the same parent |
+| `getNextFolderOrder` | Compute the next `order` value within a sibling set |
+
+### `shared/searchIndex.ts`
+
+| Export | Purpose |
+|--------|---------|
+| `normalizeSearchValue` | Lowercase + trim a query string |
+| `splitSearchWords` | Tokenize a query into words |
+| `createWordTrigrams` | Generate trigram set for a word |
+| `buildSearchTokens` | Produce the full token set for an entity field |
+| `intersectSets` | Return the intersection of two `Set<string>` objects |
+
+### `shared/stateWriter.ts`
+
+| Export | Purpose |
+|--------|---------|
+| `scheduleStateFlush` | Debounce a pending write by path key |
+| `flushPendingStateWrites` | Immediately flush all pending writes (used on exit) |
+| `registerStateWriteHooks` | Register `process` exit/signal hooks once per entity |
+
+---
+
+## 2. File Structure for New Entities
+
+```
+entity/
+  runtime/
+    constants.ts     — entity-specific constants (e.g., file prefix, debounce ms), runtimeRef
+    types.ts         — entity-specific runtime types (internal, not API DTOs)
+    paths.ts         — thin wrappers over shared/folderIndex, with entity-scoped cache
+    search.ts        — entity search built on shared/searchIndex primitives
+    state.ts         — entity state persistence using shared/stateWriter
+    sync.ts          — disk sync logic (watch + reconcile)
+    index.ts         — barrel: re-export everything the routes need
+  storages/
+    notes.ts / items.ts — CRUD operations for leaf records
+    folders.ts          — folder CRUD + tree operations
+    tags.ts             — tag CRUD (if applicable)
+    index.ts            — factory function returning the full storage object
+```
+
+**Rules:**
+
+- `constants.ts` owns the single `runtimeRef` for this entity. Nothing else creates one.
+- `paths.ts` **wraps** `buildFolderPathMap` / `buildPathToFolderIdMap`; it does not reimplement them.
+- `state.ts` calls `registerStateWriteHooks` exactly once (guard with a module-level boolean).
+- `index.ts` in `storages/` exports one factory; route files call that factory, not individual modules.
+
+---
+
+## 3. Minimum Required Tests
+
+Every new entity must ship with the following test files before merging:
+
+| File | What it covers |
+|------|---------------|
+| `files.test.ts` | `listMarkdownFiles`, path helpers, directory walking edge cases |
+| `sync.test.ts` | Full sync cycle: write files to a temp vault, run sync, assert DB state |
+| `search.test.ts` | Token building, trigram matching, multi-word intersection |
+| `storages/*.test.ts` | CRUD contract: create, read, update, delete, conflict, not-found |
+
+Tests must use a real temp directory (not mocks) for sync and file-walker tests.
+
+---
+
+## 4. API Contract Checklist
+
+Before shipping a route, verify every case:
+
+| Scenario | Expected response |
+|----------|------------------|
+| PATCH with empty body | `{ invalidInput: true, notFound: false }` |
+| GET / PATCH / DELETE with missing ID | `{ notFound: true }` or throw `NotFoundError` |
+| Create/rename with a name that already exists in the same parent | `throwStorageError('NAME_CONFLICT')` |
+| Create with a `folderId` that does not exist | `throwStorageError('FOLDER_NOT_FOUND')` |
+
+---
+
+## 5. Anti-Patterns
+
+Avoid the following when adding a new entity:
+
+- **Copying helpers** — never copy `search`, `state`, or `path` helpers into the new entity's directory. Import from `shared/`.
+- **Premature abstraction** — do not introduce a new shared utility until it has a second real, distinct consumer.
+- **Silent fallback on bad input** — e.g., resolving an unknown `folderId` to `null` and continuing silently. Throw `FOLDER_NOT_FOUND` instead.
+- **Skipping exit hooks** — `registerStateWriteHooks` in `state.ts` must be called during entity initialization; omitting it causes data loss on unclean exit.
+- **Duplicating `runtimeRef`** — each entity owns exactly one `runtimeRef` declared in its `constants.ts`.

package.json

@@ -43,11 +43,19 @@
     "prepare": "simple-git-hooks && npm run rebuild"
   },
   "dependencies": {
+    "@codemirror/commands": "^6.10.3",
+    "@codemirror/lang-markdown": "^6.5.0",
+    "@codemirror/language": "^6.12.2",
+    "@codemirror/language-data": "^6.5.2",
+    "@codemirror/state": "^6.6.0",
+    "@codemirror/view": "^6.40.0",
     "@dagrejs/dagre": "^1.1.5",
     "@elysiajs/cors": "^1.2.0",
     "@elysiajs/node": "^1.4.2",
     "@elysiajs/swagger": "^1.3.1",
     "@faker-js/faker": "^10.1.0",
+    "@lezer/highlight": "^1.2.3",
+    "@lezer/markdown": "^1.6.3",
     "@sinclair/typebox": "^0.34.41",
     "@vue-flow/background": "^1.3.2",
     "@vue-flow/controls": "^1.1.3",
@@ -162,5 +170,6 @@
   },
   "volta": {
     "node": "20.16.0"
-  }
+  },
+  "packageManager": "pnpm@10.29.2+sha512.bef43fa759d91fd2da4b319a5a0d13ef7a45bb985a3d7342058470f9d2051a3ba8674e629672654686ef9443ad13a82da2beb9eeb3e0221c87b8154fff9d74b8"
 }