edisnote-mcp 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ayodeji Areago
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,95 @@
-# Temporary Holding Version
+# Edisnote for AI agents
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Let Claude Code, Cursor, and other AI tools see the notes and images you save
+with [Edisnote](https://chromewebstore.google.com/detail/edisnote/fbnlpkgckonpaekmbfohfobgabbigaan).
+
+Collect references in Chrome, then tell your agent "look at the two images I
+just added to my moodboard note". It sees the actual pictures, not just file
+names.
+
+- **`/edisnote`**, in the Claude desktop app or the terminal:
+
+  | Type | You get |
+  |---|---|
+  | `/edisnote` | your recent notes to pick from |
+  | `/edisnote moodboard` | that note: its text, source links and newest images |
+  | `/edisnote moodboard 2` | the 2 newest images in it |
+  | `/edisnote moodboard #3` | image 3 |
+  | `/edisnote recent` | what you just saved, from any note |
+
+- **Ask in plain words.** "Check my Edisnote references for the Apex signage"
+  works. The agent finds the note and opens the images itself.
+- **`@` your notes (terminal).** Type `@` in Claude Code in a terminal and your
+  notes show up next to your files.
+
+It only reads. It never changes, moves, or deletes your notes, and nothing
+leaves your computer except what your agent sends to its own AI model.
+
+## Before you start
+
+1. **Edisnote saves to a folder.** In the Edisnote panel, click **Sync off** in
+   the footer and pick a folder. `Documents\Notes` is the default this uses.
+2. **Node.js 20 or newer** ([nodejs.org](https://nodejs.org)).
+
+## Install
+
+```bash
+npx -y edisnote-mcp install
+```
+
+That adds it to Claude Code for every project, adds the `/edisnote` command, and prints the config for other
+apps. Start a new Claude Code session afterwards.
+
+If your notes are somewhere other than `Documents\Notes`:
+
+```bash
+npx -y edisnote-mcp install --dir "D:\My Notes"
+```
+
+To check what it can see:
+
+```bash
+npx -y edisnote-mcp check
+```
+
+### Other apps
+
+Add this to the app's MCP settings (Cursor: `~/.cursor/mcp.json`; Claude
+Desktop: Settings → Developer → Edit Config):
+
+```json
+{
+  "mcpServers": {
+    "edisnote": { "command": "npx", "args": ["-y", "edisnote-mcp"] }
+  }
+}
+```
+
+Add `"--dir", "D:\\My Notes"` to `args` if your folder is elsewhere.
+
+## What your agent gets
+
+| | |
+|---|---|
+| `list_notes` | Find a note. Searches titles, text and the links images came from. |
+| `read_note` | A note's text, sources and boards, a numbered list of its images, and the newest ones to look at. |
+| `view_images` | Specific images by number, or the newest few. |
+| `recent_images` | The newest images across every note. |
+
+Images are numbered in the order they appear in the note. For board images
+Edisnote records exactly when each one was added; for images in the note body,
+"newest" goes by when the file was last written, which is usually but not
+always when you added it.
+
+Images over about 3.7 MB, and formats AI models can't view (SVG, AVIF), are
+listed by file path instead of sent.
+
+## Remove it
+
+```bash
+claude mcp remove edisnote --scope user
+```
+
+## Develop
+
+No dependencies. `npm test` runs the suite with Node's built-in test runner.

package/bin/edisnote-mcp.js

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+/**
+ * edisnote-mcp            run the MCP server on stdio (what an agent launches)
+ * edisnote-mcp install    register it with Claude Code, print config for others
+ * edisnote-mcp check      show what the server can see, then exit
+ *
+ * Every form takes --dir <folder>; the default is Documents\Notes.
+ */
+
+import { watch, readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { serveStdio } from '../src/rpc.js';
+import { createHandlers, listFingerprint, NAME, VERSION } from '../src/server.js';
+import { chooseFolder, loadVault, defaultFolder } from '../src/vault.js';
+
+const SKILL_MARKER = 'edisnote-mcp skill';
+const argv = process.argv.slice(2);
+const command = argv[0] && !argv[0].startsWith('-') ? argv[0] : 'serve';
+const root = chooseFolder(argv);
+
+if (argv.includes('--version') || command === 'version') {
+  console.log(VERSION);
+} else if (command === 'serve') {
+  serve();
+} else if (command === 'check') {
+  await check();
+} else if (command === 'install') {
+  install();
+} else {
+  console.error(`Unknown command "${command}". Try: edisnote-mcp install | check | --version`);
+  process.exitCode = 1;
+}
+
+function serve() {
+  const { notify, closed } = serveStdio(createHandlers(root));
+
+  // New notes should show up in the @ list without restarting the agent. The
+  // extension writes two seconds after every keystroke, so the folder is busy;
+  // the fingerprint means a notification goes out only when the list itself
+  // (ids, titles, image counts) actually changed.
+  let last = null;
+  let timer = null;
+  listFingerprint(root).then((f) => (last = f));
+  const recheck = () => {
+    clearTimeout(timer);
+    timer = setTimeout(async () => {
+      const next = await listFingerprint(root).catch(() => last);
+      if (last !== null && next !== last) notify('notifications/resources/list_changed');
+      last = next;
+    }, 750);
+  };
+  let watcher = null;
+  try {
+    watcher = watch(root, { recursive: true }, recheck);
+    watcher.on('error', () => watcher?.close());
+  } catch {
+    // Folder missing or recursive watch unsupported: the list still refreshes
+    // whenever the client asks, it just isn't pushed.
+  }
+  closed.then(() => {
+    watcher?.close();
+    clearTimeout(timer);
+    process.exit(0);
+  });
+}
+
+async function check() {
+  const vault = await loadVault(root);
+  if (!vault.found) {
+    console.log(`No folder at ${root}.`);
+    console.log('Turn on folder sync in Edisnote (the "Sync off" chip), or pass --dir <folder>.');
+    process.exitCode = 1;
+    return;
+  }
+  const images = vault.notes.reduce((sum, n) => sum + n.embeds.filter((e) => !e.remote).length, 0);
+  console.log(`Edisnote folder: ${root}`);
+  console.log(`${vault.notes.length} notes, ${images} images embedded in them.`);
+  for (const note of vault.notes.slice(0, 5)) console.log(`  ${note.title}  (${note.id})`);
+  if (vault.notes.length > 5) console.log(`  …and ${vault.notes.length - 5} more`);
+}
+
+/**
+ * Registers the server with Claude Code at user scope, so it works in every
+ * project. Run through npx, it registers `npx -y edisnote-mcp` and so always
+ * gets the published version; run from a checkout, it registers that checkout.
+ */
+function install() {
+  const self = fileURLToPath(import.meta.url);
+  const viaNpx = /[\\/]_npx[\\/]/.test(self);
+  // Plain `node`, not process.execPath: the full path is usually
+  // C:\Program Files\..., and a space in the command is one more way for a
+  // config file or shell to split it in two.
+  const launch = viaNpx ? ['npx', '-y', 'edisnote-mcp'] : ['node', self];
+  const dirArgs = root !== defaultFolder() ? ['--dir', root] : [];
+  const full = [...launch, ...dirArgs];
+
+  console.log(`Edisnote MCP ${VERSION} — reading ${root}\n`);
+
+  const claude = runClaude(['mcp', 'add', '--scope', 'user', NAME, '--', ...full]);
+  if (claude.status === 0) {
+    console.log('Added to Claude Code for every project. Start a new session, then:');
+    console.log('  /edisnote                     pick one of your recent notes');
+    console.log('  /edisnote moodboard 2         the 2 newest images in that note');
+    console.log('  /edisnote recent              what you just saved, from any note');
+    console.log('  or just say "look at my Edisnote note on …"\n');
+  } else if (/already exists/i.test(`${claude.stdout}${claude.stderr}`)) {
+    console.log(`Claude Code already has a server called "${NAME}". To replace it:`);
+    console.log(`  claude mcp remove ${NAME} --scope user`);
+    console.log('  then run this again.\n');
+  } else {
+    console.log('Claude Code not found (or it refused). To add it by hand:');
+    console.log(`  claude mcp add --scope user ${NAME} -- ${full.map(quote).join(' ')}\n`);
+  }
+
+  installSkill();
+
+  const [cmd, ...args] = full;
+  console.log('For Cursor, Claude Desktop or any other MCP app, add this to its MCP config:');
+  console.log(JSON.stringify({ mcpServers: { [NAME]: { command: cmd, args } } }, null, 2));
+}
+
+/**
+ * The Claude desktop app's message box lists skills under `/` but not MCP
+ * prompts or resources, so without this the server is reachable there only by
+ * asking in words. The skill is the `/edisnote` command for the desktop app.
+ *
+ * A file at that path without our marker is someone's own skill, and an
+ * installer has no business replacing it.
+ */
+function installSkill() {
+  const source = fileURLToPath(new URL('../skill/SKILL.md', import.meta.url));
+  const dir = join(homedir(), '.claude', 'skills', 'edisnote');
+  const target = join(dir, 'SKILL.md');
+  const ours = readFileSync(source, 'utf8');
+  if (existsSync(target)) {
+    const current = readFileSync(target, 'utf8');
+    if (current === ours) return console.log('The /edisnote skill is already up to date.\n');
+    if (!current.includes(SKILL_MARKER)) {
+      console.log(`Left ${target} alone: it isn't one this installer wrote.\n`);
+      return;
+    }
+  }
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(target, ours);
+  console.log('Added the /edisnote skill. In the Claude desktop app, type /edisnote to pick a note.\n');
+}
+
+/**
+ * Runs the claude CLI without a shell first: through one, Node joins the args
+ * with spaces unescaped, and the first install registered "C:\Program" as the
+ * command. Only a Windows install that is a .cmd shim (npm's) needs the shell,
+ * and then every argument is quoted by hand.
+ */
+function runClaude(args) {
+  const direct = spawnSync('claude', args, { encoding: 'utf8' });
+  if (!direct.error || process.platform !== 'win32') return direct;
+  const line = ['claude', ...args].map((a) => (/[\s"&|<>^]/.test(a) ? `"${a.replace(/"/g, '""')}"` : a)).join(' ');
+  return spawnSync(line, { encoding: 'utf8', shell: true });
+}
+
+function quote(arg) {
+  return /\s/.test(arg) ? `"${arg}"` : arg;
+}

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "edisnote-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Let Claude Code, Cursor and other AI agents see the notes and images you save with Edisnote. Read-only, local, no dependencies.",
+  "type": "module",
+  "bin": {
+    "edisnote-mcp": "bin/edisnote-mcp.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "skill",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "keywords": [
+    "mcp",
+    "edisnote",
+    "claude",
+    "moodboard",
+    "references",
+    "obsidian"
+  ],
+  "author": "Ayodeji Areago",
+  "homepage": "https://github.com/ayareago/edisnote-mcp#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ayareago/edisnote-mcp.git"
+  },
+  "bugs": "https://github.com/ayareago/edisnote-mcp/issues",
+  "license": "MIT"
+}

package/skill/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: edisnote
+description: Look at the user's Edisnote notes and the images they saved in Chrome. Use when the user types /edisnote, mentions Edisnote, or says "my notes", "my references", "the images I saved", "what I just added", or names one of their notes.
+argument-hint: "[note] [N newest | #image] — or recent"
+allowed-tools: mcp__edisnote__list_notes mcp__edisnote__read_note mcp__edisnote__view_images mcp__edisnote__recent_images
+---
+
+<!-- edisnote-mcp skill: the installer may overwrite this file. -->
+
+The user collects references with Edisnote, a Chrome side-panel notepad. Every
+note is a Markdown file with images, and the `edisnote` MCP server reads them.
+Use its tools; don't search the disk yourself.
+
+What they asked for: `$ARGUMENTS`
+
+Work out which case this is, then act. Don't explain these steps to the user.
+
+1. **Nothing given** (the line above is empty): call `list_notes` with
+   `limit: 8`. Then ask which note with AskUserQuestion: header `Note`, the
+   **four most recently changed notes** as options, each label the note's title
+   (shortened to a few words if long), each description its image count and
+   when it changed. The automatic "Other" option lets them type any name. Then
+   read the chosen note as in case 3.
+
+2. **`recent`, `new`, `latest`, or "what I just saved", with no note named**:
+   call `recent_images`, with `count` if they gave a number.
+
+3. **A note name alone** (any part of the title works): call `read_note`.
+
+4. **A note plus one bare number**, e.g. `independence party 2`, or with
+   "newest/latest/last N": that is always the **newest N**, never image number
+   N. Call `view_images` with `newest: N`.
+
+5. **A note plus specific images**, written `#3`, `image 3`, `images 3 and 5`,
+   or a list like `3,5`: call `view_images` with `numbers`.
+
+If a tool says the name matches several notes, ask which one with
+AskUserQuestion, using those candidates as the options. Never guess.
+
+After the images arrive, describe what's in each one in a line or two:
+subject, colour, type, layout. Then stop, unless they asked for more. Keep the
+note in mind for the rest of the conversation, so that "the second one" or
+"what did I add after that" work without naming it again.
+
+If the `edisnote` tools aren't available at all, tell the user to run
+`npx -y edisnote-mcp install` in a terminal and then start a new session.

package/src/notes.js

@@ -0,0 +1,246 @@
+/**
+ * Pure parsing for an Edisnote folder: frontmatter, image embeds, board links,
+ * note lookup. No file system here — vault.js reads the bytes and hands them
+ * in, which is what lets the tests run on strings.
+ *
+ * The format being parsed is what the extension's markdown.js and vault.js
+ * write, plus whatever the user has since done to those files in Obsidian. So
+ * every parser here accepts both the Markdown form `![](path)` the extension
+ * writes and the wiki form `![[path|160]]` Obsidian writes.
+ */
+
+/** Formats a model can actually look at. Everything else is listed by path. */
+const VIEWABLE = new Map([
+  ['jpg', 'image/jpeg'],
+  ['jpeg', 'image/jpeg'],
+  ['png', 'image/png'],
+  ['gif', 'image/gif'],
+  ['webp', 'image/webp'],
+]);
+
+const IMAGE_EXTENSIONS = new Set([...VIEWABLE.keys(), 'svg', 'avif', 'bmp', 'heic', 'tif', 'tiff']);
+
+export function extensionOf(path) {
+  const match = /\.([A-Za-z0-9]+)$/.exec(path);
+  return match ? match[1].toLowerCase() : '';
+}
+
+export function isImagePath(path) {
+  return IMAGE_EXTENSIONS.has(extensionOf(path));
+}
+
+/** The MIME type to send an image inline with, or null when it can't be. */
+export function viewableMime(path) {
+  return VIEWABLE.get(extensionOf(path)) ?? null;
+}
+
+/**
+ * Splits a leading `---` block off the note. Only the subset of YAML that the
+ * extension writes, and that Obsidian's property editor writes back, is
+ * understood: scalars, quoted scalars, block lists and inline `[a, b]` lists.
+ * Anything stranger is kept as its raw string rather than guessed at.
+ *
+ * @returns {{data: Record<string, string|string[]>, body: string}}
+ */
+export function parseFrontmatter(text) {
+  const normalised = text.replace(/^/, '').replace(/\r\n?/g, '\n');
+  const match = /^---\n([\s\S]*?)\n---[ \t]*(?:\n|$)/.exec(normalised);
+  if (!match) return { data: {}, body: normalised };
+
+  const data = {};
+  let listKey = null;
+  for (const line of match[1].split('\n')) {
+    const item = /^\s+-\s*(.*)$/.exec(line);
+    if (item && listKey) {
+      data[listKey].push(unquote(item[1]));
+      continue;
+    }
+    const pair = /^([A-Za-z0-9_][\w -]*?)\s*:\s*(.*)$/.exec(line);
+    if (!pair) continue;
+    const [, key, raw] = pair;
+    if (raw === '') {
+      data[key] = [];
+      listKey = key;
+    } else if (/^\[.*\]$/.test(raw)) {
+      data[key] = raw.slice(1, -1).split(',').map((s) => unquote(s.trim())).filter(Boolean);
+      listKey = null;
+    } else {
+      data[key] = unquote(raw);
+      listKey = null;
+    }
+  }
+  return { data, body: normalised.slice(match[0].length) };
+}
+
+function unquote(value) {
+  const v = value.trim();
+  if (v.startsWith('"') && v.endsWith('"') && v.length >= 2) {
+    try {
+      return JSON.parse(v);
+    } catch {
+      return v.slice(1, -1);
+    }
+  }
+  if (v.startsWith("'") && v.endsWith("'") && v.length >= 2) {
+    return v.slice(1, -1).replace(/''/g, "'");
+  }
+  return v;
+}
+
+/** Images, in reading order. Group 1/2 = Markdown form, group 3 = wiki form. */
+const EMBED = /!\[[^\]]*\]\((?:<([^>]+)>|([^)\s]+))(?:\s+"[^"]*")?\)|!\[\[([^\]|#]+)(?:#[^\]|]*)?(?:\|[^\]]*)?\]\]/g;
+
+/**
+ * Every image embed in the body, in the order a reader meets them. Embeds of
+ * other things (notes, canvases, PDFs) are skipped; remote URLs are kept and
+ * flagged so they can be listed without being fetched.
+ *
+ * @returns {Array<{target: string, remote: boolean, wiki: boolean, start: number, end: number}>}
+ */
+export function findImageEmbeds(body) {
+  const found = [];
+  for (const match of body.matchAll(EMBED)) {
+    const wiki = match[3] !== undefined;
+    let target = (match[1] ?? match[2] ?? match[3]).trim();
+    if (!wiki) target = safeDecode(target);
+    const remote = /^https?:\/\//i.test(target);
+    if (!remote && !isImagePath(target)) continue;
+    found.push({ target, remote, wiki, start: match.index, end: match.index + match[0].length });
+  }
+  return found;
+}
+
+function safeDecode(value) {
+  try {
+    return decodeURI(value);
+  } catch {
+    return value;
+  }
+}
+
+/**
+ * The boards (collections) a note shows. The extension writes
+ * `[[collections/x.canvas|open canvas]]` above the gallery; an older version
+ * wrote `![[collections/x.canvas]]`. Both count, each board once.
+ */
+export function findBoardLinks(body) {
+  const boards = [];
+  for (const match of body.matchAll(/!?\[\[([^\]|#]+\.canvas)(?:\|[^\]]*)?\]\]/g)) {
+    const path = match[1].trim();
+    if (!boards.includes(path)) boards.push(path);
+  }
+  return boards;
+}
+
+/**
+ * Board images are named `col-<slug>-it_<base36 ms>_<random>.<ext>`: the item
+ * id is minted from Date.now() in collections.js, so the file name carries the
+ * exact moment the image was added. That is better evidence than any mtime.
+ */
+export function boardItemAddedAt(path) {
+  const match = /(?:^|\/)col-.+-it_([0-9a-z]+)_[0-9a-z]+\.[A-Za-z0-9]+$/.exec(path);
+  if (!match) return null;
+  const ms = parseInt(match[1], 36);
+  // Anything outside 2020–2100 is a coincidental match, not a timestamp.
+  return ms > 1577836800000 && ms < 4102444800000 ? ms : null;
+}
+
+/**
+ * Replaces each image embed with `[image N]` so the text Claude reads lines up
+ * with the numbers the image tools take, and drops board links, which are
+ * summarised separately. `numberFor` maps an embed's target to its number.
+ */
+export function readableBody(body, embeds, numberFor) {
+  let out = '';
+  let last = 0;
+  for (const embed of embeds) {
+    out += body.slice(last, embed.start);
+    const n = numberFor(embed.target);
+    out += embed.remote ? `[web image: ${embed.target}]` : n ? `[image ${n}]` : `[missing image: ${embed.target}]`;
+    last = embed.end;
+  }
+  out += body.slice(last);
+  return out
+    .replace(/\*\*[^*\n]+\*\*\s*·\s*\[\[[^\]]+\.canvas(?:\|[^\]]*)?\]\]/g, '')
+    .replace(/!?\[\[[^\]]+\.canvas(?:\|[^\]]*)?\]\]/g, '')
+    .replace(/[ \t]+\n/g, '\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+}
+
+/**
+ * Pulls what a model needs out of a JSON Canvas file: the image files in the
+ * order they sit on the board (top to bottom, then left to right) and the text
+ * cards. Edisnote's own link cards are text nodes, so links arrive here too.
+ */
+export function parseCanvas(json) {
+  let doc;
+  try {
+    doc = JSON.parse(json);
+  } catch {
+    return { files: [], texts: [] };
+  }
+  const nodes = Array.isArray(doc?.nodes) ? doc.nodes : [];
+  const placed = [...nodes].sort((a, b) => (a.y ?? 0) - (b.y ?? 0) || (a.x ?? 0) - (b.x ?? 0));
+  return {
+    files: placed.filter((n) => n.type === 'file' && typeof n.file === 'string' && isImagePath(n.file)).map((n) => n.file),
+    texts: placed.filter((n) => n.type === 'text' && typeof n.text === 'string' && n.text.trim()).map((n) => n.text.trim()),
+  };
+}
+
+export function normalise(value) {
+  return String(value ?? '')
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}]+/gu, ' ')
+    .trim();
+}
+
+/**
+ * Finds the note a person or a model meant. Exact id or title wins outright;
+ * otherwise every word of the query has to appear in the id or title. More
+ * than one hit is returned as candidates rather than silently picking one —
+ * looking at the wrong moodboard is worse than asking.
+ *
+ * @template {{id: string, title: string, mtime: number}} N
+ * @param {N[]} notes
+ * @returns {{note?: N, candidates: N[]}}
+ */
+export function resolveNote(notes, query) {
+  const q = normalise(query);
+  if (!q) return { candidates: [] };
+
+  const byRecency = (list) => [...list].sort((a, b) => b.mtime - a.mtime);
+  const exact = notes.filter((n) => normalise(n.id) === q || normalise(n.title) === q);
+  if (exact.length === 1) return { note: exact[0], candidates: [] };
+  if (exact.length > 1) return { candidates: byRecency(exact) };
+
+  const words = q.split(' ');
+  const hits = notes.filter((n) => {
+    const hay = `${normalise(n.id)} ${normalise(n.title)}`;
+    return words.every((w) => hay.includes(w));
+  });
+  if (hits.length === 1) return { note: hits[0], candidates: [] };
+  return { candidates: byRecency(hits) };
+}
+
+/** Case-insensitive search over title, id, body and sources, best first. */
+export function searchNotes(notes, query) {
+  const words = normalise(query).split(' ').filter(Boolean);
+  if (!words.length) return [];
+  const scored = [];
+  for (const note of notes) {
+    const head = `${normalise(note.title)} ${normalise(note.id)}`;
+    const rest = `${normalise(note.body)} ${normalise((note.sources ?? []).join(' '))}`;
+    let score = 0;
+    for (const w of words) {
+      if (head.includes(w)) score += 3;
+      else if (rest.includes(w)) score += 1;
+      else {
+        score = 0;
+        break;
+      }
+    }
+    if (score) scored.push({ note, score });
+  }
+  return scored.sort((a, b) => b.score - a.score || b.note.mtime - a.note.mtime).map((s) => s.note);
+}