notescraft/specs/obsidian-basics/spec.md

Obsidian basics: the everyday features NotesCraft still lacks

Problem

NotesCraft covers most of Obsidian's core, but an audit (2026-10-19, specs/obsidian-basics/audit.md) found everyday features that a user of Obsidian reaches for within the first hour and does not find: find and replace in a note, back and forward navigation, hover previews of links, split panes, footnotes, folding, auto-pairing of brackets, sorting the file explorer, replacing across the vault and more. Evidence: the audit table and owner testing.

Goal

A daily Obsidian user can do their ordinary editing, navigating and searching in NotesCraft without missing a core feature that Obsidian ships without plugins.

Non-Goals

• Sync, Publish, Web Clipper, Slides, Audio recorder, Bases, community-plugin store, CSS snippets (deferred in SPEC 6.1, by design).
• Mobile layouts for the new features beyond what the existing screens already do.
• Pop-out windows and workspaces (separate specs; they need multi-viewport work).

User Stories

• As a writer, I want find and replace in the open note, so that I can fix repeated text without leaving the editor.
• As a reader, I want back and forward through my navigation history, so that I can return from a link.
• As a reader, I want a preview when I hover a link, so that I can peek at a note without opening it.
• As a writer, I want footnotes to render and jump, so that references read like in Obsidian.
• As a writer, I want brackets and quotes to pair as I type and headings and lists to fold, so that editing is quick.
• As a vault owner, I want to sort the explorer by name, modified or created time, drag files to move them, and replace text across the vault with a review, so that I can organise and clean up.
• As a power user, I want side-by-side panes, pinned tabs and draggable tab order, so that I can work with several notes.

Acceptance Criteria

Each item is a task in tasks.md; the Given/When/Then of every task is its "Done when". Summary:

• Find and replace in the open note (Cmd-F / Cmd-H), plain and regex, case and whole-word switches, replace one and all as one undo step.
• Back and forward navigation (Cmd-[ and Cmd-]) over notes, remembering scroll and caret.
• Hovering an internal link for 400 ms shows a read-only preview card of the target (heading and block targets show that part).
• Footnote references [^1] and inline ^[text] render as superscripts that jump to and from the definition.
• Typing an opening bracket or quote inserts its pair; typing the closer steps over it; Backspace removes an empty pair.
• Headings and list items fold and unfold by click in the rendered view; fold state is kept per note while it is open.
• The explorer sorts by name, modified time or created time, ascending or descending, remembered across restarts.
• Dragging a file or folder onto a folder in the explorer moves it through note.rename and updates links.
• Search has section:, block:, task: operators and a match-case switch; /regex/ queries work.
• Search and replace across the vault: a dry run lists changes per file, accepted ones are applied as one edit per file (same review as batch format).
• The quick switcher finds headings and blocks (note#heading, note^block).
• Tabs can be pinned and reordered by drag.
• Settings: default view mode for new tabs, font size, readable line length, line numbers, strict line breaks, default location for new notes, link format (wikilink or markdown, shortest or relative path), deleted files (trash or permanent).
• Context menu: Open in default app, Copy Obsidian URL; an Outgoing links pane next to Backlinks; Open random note command; unique note creator command.
• Split panes: the editor area holds two panes side by side or stacked, each with its own tabs.
• Embedded PDF pages and audio/video files render or play inline.
• Spellcheck (needs an owner decision on a dictionary).

Constraints

• Stack: Rust only, egui. Logic below the UI layer as pure code with tests; UI draws.
• Never crash; hostile input bounded; every write through craft-atomic; strings through the i18n tables.
• New third-party crates need owner approval: regex search (a regex dependency or reuse of the approved grep-regex), spellcheck (a dictionary crate), PDF rendering, audio and video decoding.
• Performance: find, hover preview and fold toggles respond within one frame on a 5,000-line note.

Open Questions

• Regex search: approve the regex crate for the index crate, or reuse grep-regex through a thin adapter?
• Spellcheck: new dependency (for example a Hunspell-compatible crate) or an in-house word list with edit distance?
• PDF and video embeds: which decoders are acceptable (the app has no video stack today)?
• Split panes: is a two-pane limit enough for v1?