feat(notes): add wiki-style internal links for notes and snippets (#721)

* feat(notes): add internal links parser and cache

* feat(core): add internal link entity lookup and deeplinks

* feat(notes): add internal link editor UI

* fix(notes): defer internal link popup positioning

* fix(notes): align internal link overlays and chips

* fix(api): type internal link entity responses

* feat(notes): add obsidian-style internal links

* fix(notes): handle modifier click navigation

* fix(notes): stabilize internal link interactions

* fix(notes): require modifier key for internal link preview

Preview popover now only appears on Cmd+hover (macOS) or Ctrl+hover
(Win/Linux) instead of plain hover. Supports both hover-then-press
and press-then-hover via document-level key listeners.

* fix(notes): prevent hideMarkup from hiding internal link brackets

The hideMarkup extension was hiding inner brackets of [[Target]] when
the cursor entered from the left, causing a two-step reveal instead
of showing all brackets at once.

* fix(notes): eliminate flicker when navigating to snippets via internal links

Deep link navigation to code space caused flickering because Library.vue's
initApp() raced with openSnippetDeepLink(), briefly showing the previous
selection before the target. Now openSnippetDeepLink() sets
pendingCodeNavigation and isAppLoading before the route change, Library.vue
skips its init when pending, and deep link handles all data loading with
a fallback to default initCodeSpace() on error.

* fix(notes): prevent preview popover from appearing at top-left corner

After navigating to a snippet and returning to notes, the preview
could render at (0,0) because hoveredLink retained a reference to a
detached DOM element. Now destroy() always clears hoveredLink, and
showPreview() checks target.isConnected before reading position.

* feat: add internal link navigation history

* fix: constrain header input with history controls

* fix: reduce internal link preview text size

* fix: use app scrollbar in link preview

* docs: add notes internal links guide

* fix: avoid notes flicker on history back navigation

* fix: reduce internal link preview typography

* feat: refine internal link chip colors

* docs: update image

Author: antonreshetov

docs/website/.vitepress/config.mts

@@ -122,6 +122,7 @@ export default defineConfig({
             { text: 'Library', link: '/documentation/notes/library' },
             { text: 'Folders', link: '/documentation/notes/folders' },
             { text: 'Tags', link: '/documentation/notes/tags' },
+            { text: 'Internal Links', link: '/documentation/notes/internal-links' },
             { text: 'Mermaid', link: '/documentation/notes/mermaid' },
             { text: 'Mindmap', link: '/documentation/notes/mindmap' },
             { text: 'Presentation', link: '/documentation/notes/presentation' },

docs/website/documentation/notes/index.md

@@ -43,11 +43,13 @@ The editor is built on CodeMirror 6 and includes:
 - Smart list indentation with automatic ordered list renumbering
 - Tab / Shift-Tab indentation
 - Table navigation between cells
+- Internal links to notes and snippets
 - Mermaid diagram support
 - Image embedding
 - Callout blocks
 
 For visual diagrams in notes, see [Mermaid](/documentation/notes/mermaid).
+For wiki-style links between notes and snippets, see [Internal Links](/documentation/notes/internal-links).
 
 ## Editor Preferences
 

docs/website/documentation/notes/internal-links.md

@@ -0,0 +1,80 @@
+---
+title: Internal Links
+description: "Link notes and snippets together inside massCode Notes with wiki-style links, hover previews, and back-forward navigation."
+---
+
+# Internal Links
+
+<AppVersion text=">=5.1.0" />
+
+Internal Links let you connect notes and snippets with wiki-style links directly inside Notes. Use them to build lightweight documentation, link reference snippets from prose, and move through related material without leaving massCode.
+
+<img :src="withBase('/notes-internal-links.png')">
+
+## Link Syntax
+
+Use double brackets around the target name:
+
+```md
+[[API authentication]]
+[[Fetch helper]]
+```
+
+You can also provide custom visible text with an alias:
+
+```md
+[[API authentication|auth flow]]
+[[Fetch helper|request snippet]]
+```
+
+massCode resolves internal links by item name. A target can be either a note or a snippet.
+
+## Creating Links
+
+Start typing `[[` in the Notes editor to open the internal links picker.
+
+- The picker searches both notes and snippets.
+- Results show the item name and its current location.
+- Press <kbd>Enter</kbd> to insert the active result.
+- Use the arrow keys to move through the list.
+
+The inserted link keeps the readable wiki-link format in your markdown.
+
+## Opening Links
+
+Hold <kbd>Cmd</kbd> on macOS or <kbd>Ctrl</kbd> on Windows or Linux, then click the link.
+
+- If the target is a note, massCode opens it in Notes.
+- If the target is a snippet, massCode switches to Code and opens the snippet there.
+
+Broken links stay visible, but they appear dimmed and struck through so you can spot missing targets.
+
+## Preview
+
+Hover an internal link while holding <kbd>Cmd</kbd> on macOS or <kbd>Ctrl</kbd> on Windows or Linux to open a preview popup.
+
+- Note links show a text excerpt.
+- Snippet links show the first snippet fragment.
+
+This helps you confirm the target before you navigate away from the current note.
+
+## Navigation History
+
+When you follow internal links, massCode keeps a small link navigation history for that session.
+
+- Use the back and forward buttons in the editor header to move through link-based navigation.
+- Use <kbd>Cmd+[</kbd> / <kbd>Cmd+]</kbd> on macOS or <kbd>Ctrl+[</kbd> / <kbd>Ctrl+]</kbd> on Windows or Linux.
+- The same actions are also available from the **History** menu.
+
+The history is specific to internal-link navigation. If you manually select another note or snippet from the list, that temporary link history is cleared.
+
+## When to Use Internal Links
+
+- Link architecture notes to implementation snippets
+- Connect meeting notes to reference code
+- Build personal knowledge-base pages that jump between notes and snippets
+- Keep long-form docs in Notes while linking reusable code examples from Code
+
+<script setup>
+import { withBase } from 'vitepress'
+</script>

docs/website/public/notes-internal-links.png

@@ -3,3 +3,7 @@ import { t } from 'elysia'
 export const commonAddResponse = t.Object({
   id: t.Union([t.Number(), t.BigInt()]),
 })
+
+export const commonMessageResponse = t.Object({
+  message: t.String(),
+})

src/main/api/dto/common/response.ts

@@ -52,6 +52,7 @@ export const notesDTO = new Elysia().model({
   notesAdd,
   notesContentUpdate,
   notesCountsResponse,
+  noteItemResponse: noteItem,
   notesResponse,
   notesQuery: t.Object({
     ...commonQuery.properties,
@@ -67,3 +68,4 @@ export const notesDTO = new Elysia().model({
 export type NotesAdd = typeof notesAdd.static
 export type NotesResponse = typeof notesResponse.static
 export type NotesCountsResponse = typeof notesCountsResponse.static
+export type NoteItemResponse = typeof noteItem.static

src/main/api/dto/notes.ts

@@ -66,6 +66,7 @@ const snippetsCountsResponse = t.Object({
 export const snippetsDTO = new Elysia().model({
   snippetContentsAdd,
   snippetContentsUpdate,
+  snippetItemResponse: snippetItem,
   snippetsAdd,
   snippetsUpdate,
   snippetsCountsResponse,
@@ -83,3 +84,4 @@ export const snippetsDTO = new Elysia().model({
 export type SnippetsAdd = typeof snippetsAdd.static
 export type SnippetsResponse = typeof snippetsResponse.static
 export type SnippetsCountsResponse = typeof snippetsCountsResponse.static
+export type SnippetItemResponse = typeof snippetItem.static

src/main/api/dto/snippets.ts

@@ -1,7 +1,10 @@
-import type { NotesResponse } from '../dto/notes'
+import type { NoteItemResponse, NotesResponse } from '../dto/notes'
 import Elysia from 'elysia'
 import { useNotesStorage } from '../../storage'
-import { commonAddResponse } from '../dto/common/response'
+import {
+  commonAddResponse,
+  commonMessageResponse,
+} from '../dto/common/response'
 import { notesDTO } from '../dto/notes'
 
 const app = new Elysia({ prefix: '/notes' })
@@ -89,6 +92,28 @@ app
       },
     },
   )
+  .get(
+    '/:id',
+    ({ params, status }) => {
+      const storage = useNotesStorage()
+      const note = storage.notes.getNoteById(Number(params.id))
+
+      if (!note) {
+        return status(404, { message: 'Note not found' })
+      }
+
+      return note as NoteItemResponse
+    },
+    {
+      response: {
+        200: 'noteItemResponse',
+        404: commonMessageResponse,
+      },
+      detail: {
+        tags: ['Notes'],
+      },
+    },
+  )
   .post(
     '/',
     ({ body, status }) => {

src/main/api/routes/notes.ts

@@ -1,7 +1,14 @@
-import type { SnippetsCountsResponse, SnippetsResponse } from '../dto/snippets'
+import type {
+  SnippetItemResponse,
+  SnippetsCountsResponse,
+  SnippetsResponse,
+} from '../dto/snippets'
 import Elysia from 'elysia'
 import { useStorage } from '../../storage'
-import { commonAddResponse } from '../dto/common/response'
+import {
+  commonAddResponse,
+  commonMessageResponse,
+} from '../dto/common/response'
 import { snippetsDTO } from '../dto/snippets'
 
 const app = new Elysia({ prefix: '/snippets' })
@@ -91,6 +98,28 @@ app
       },
     },
   )
+  .get(
+    '/:id',
+    ({ params, status }) => {
+      const storage = useStorage()
+      const snippet = storage.snippets.getSnippetById(Number(params.id))
+
+      if (!snippet) {
+        return status(404, { message: 'Snippet not found' })
+      }
+
+      return snippet as SnippetItemResponse
+    },
+    {
+      response: {
+        200: 'snippetItemResponse',
+        404: commonMessageResponse,
+      },
+      detail: {
+        tags: ['Snippets'],
+      },
+    },
+  )
   // Создание сниппета
   .post(
     '/',

src/main/api/routes/snippets.ts

@@ -135,12 +135,27 @@
       "toHtml": "Export to HTML"
     },
     "copy": {
-      "snippetLink": "Copy Snippet Link"
+      "snippetLink": "Copy Snippet Link",
+      "noteLink": "Copy Note Link"
     },
     "select": {
       "directory": "Select Directory"
     }
   },
+  "internalLinks": {
+    "picker": {
+      "searchPlaceholder": "Search snippets and notes...",
+      "emptyResults": "No results",
+      "groups": {
+        "snippets": "Snippets",
+        "notes": "Notes"
+      }
+    },
+    "missing": {
+      "snippet": "Snippet not found",
+      "note": "Note not found"
+    }
+  },
   "placeholder": {
     "emptyTagList": "Add tags to snippets to see them here",
     "emptyNotesTagList": "Add tags to notes to see them here",