Files
Marcos Paulo 5e8020aa38
ci / ci (macos-latest) (push) Has been cancelled
ci / ci (ubuntu-latest) (push) Has been cancelled
ci / ci (windows-latest) (push) Has been cancelled
feat: Obsidian basics, editor previews, graph rework, query blocks, stacked tabs, pop-out windows
Editor previews (colour swatches, arrows, embeds), the 18 obsidian-basics tasks (find and replace
with regex, back/forward, auto-pair, footnotes, folding, search operators, split view, PDF/audio/
video embeds, spelling, drag and drop, pinned tabs, settings) and round 2: ```query blocks, stacked
tabs, pop-out windows, tasks ticked inside embeds, text around an embed, embeds that follow edits,
block menu shortcut. New crates: notescraft-regex (linear-time engine) and notescraft-syntax.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-19 11:21:19 -03:00

6.6 KiB

Fast open and large-vault explorer

Problem

Opening a folder indexes every file on the UI thread before the first frame, so a large folder freezes the window for a long time. A user opened the project folder by mistake and waited with no feedback and no way to cancel. Once open, the explorer draws every visible row each frame and offers no help to find a place in a very large tree (only note search). Evidence: owner test on a 10,000-note folder; the open-time scan is synchronous and the explorer is not virtualized.

Goal

A vault of 5,000 or more notes opens to a usable window (explorer, file names, open note) in about a second, stays responsive while it finishes reading in the background, and is easy to navigate.

Non-Goals

  • Changing the search ranking, query language or backlink rules.
  • A persistent database or any server component.
  • Full-text search across non-note file types.
  • Changing the vault folder format or reserved folders.
  • Spell-check, sync, or community plugins.

User Stories

  • As a user with a huge vault, I want the window to appear immediately, so that I can start working while the rest loads.
  • As a user, I want search to work before indexing finishes, so that I am never blocked.
  • As a user, I want to see indexing progress and be able to pause it, so that I know what is still loading.
  • As a user, I want a warning when I open a very large or non-vault folder, so that I do not open one by accident.
  • As a user, I want the explorer to stay smooth while I scroll fast or drag the scrollbar, so that big folders are usable.
  • As a user, I want collapse all, reveal active note, folder note counts, a filter box and pinned folders, so that I can find places in a big tree.
  • As a returning user, I want the second open of the same vault to be near-instant, so that restarts are cheap.

Acceptance Criteria

Design: PaperCraft page "Large vaults and code", artboards "Explorer / Large vault" and "Dialog / Large folder warning".

  • Given a vault of 5,000 notes, when it is opened, then the explorer and the file names appear within 1 second on the reference machine, before any note content has been parsed.
  • Given indexing is running, when the user types in note search, then results appear without waiting for indexing, using content scanned from disk on demand.
  • Given a content search is running, when the user changes the query or closes the panel, then the old scan stops and no stale results appear.
  • Given indexing is running, when the user views the sidebar, then a status card shows "Indexing n / N" with a progress bar and a pause control, and a chip shows the percentage in the note header.
  • Given indexing is running, when the user opens backlinks, tags or graph, then they show a loading state and fill in as notes are read, without blocking the window.
  • Given a note is open, when indexing starts, then that note and recently modified notes are read first.
  • Given indexing is paused, when the user presses resume or reopens the vault, then reading continues without re-reading unchanged notes.
  • Given a vault was opened before and no file changed, when it is opened again, then unchanged notes are not re-parsed (keyed by path, size and modified time) and the backlinks are available within 1 second.
  • Given a file changed on disk since the last open, when the vault opens, then only that file is re-read.
  • Given the selected folder holds more than 5,000 files, or has no vault marker folder, when the user opens it, then a dialog shows the path, file and note counts and the note that a state folder will be added, with Cancel and Open anyway.
  • Given the user presses Cancel in that dialog, when it closes, then nothing is written to the folder and the previous vault stays open.
  • Given a tree of 50,000 rows, when the explorer is drawn, then only the visible rows plus about ten rows before and after are laid out, and frame time stays under 16 ms on the reference machine.
  • Given the user scrolls with the wheel quickly, when new rows enter view, then no blank rows are visible.
  • Given the user drags the scrollbar thumb, when it moves, then the visible rows match the thumb position on the same frame.
  • Given the explorer is shown, when the user presses collapse all, then every folder collapses except the path to the active note, which stays visible.
  • Given reveal active note is on, when the active note changes, then the explorer expands its folders and scrolls it into view.
  • Given a folder row, when it is drawn, then it shows the count of notes inside it.
  • Given the user scrolls inside a deep folder, when its row has left the viewport, then a sticky breadcrumb shows the folder path and clicking a segment scrolls to that folder.
  • Given the user types in the filter box, when text changes, then the tree narrows to matching names and their parent folders, and clearing it restores the previous collapse state.
  • Given the user pins a folder, when the explorer is shown, then it appears in a Pinned section above the tree and survives a restart.
  • Given an unreadable or non-UTF-8 file, when indexing reaches it, then it is skipped with a diagnostic and indexing continues.
  • Given any of these paths, when they run, then no code path panics (no unwrap, expect or unchecked indexing on file-derived data).

Constraints

  • Stack: Rust only, egui and eframe. Layering rules stay enforced: no UI types below the UI layer.
  • Performance: window with names in 1 s for 5,000 notes; frame time under 16 ms with 50,000 explorer rows; memory for the explorer bounded by the visible rows plus overscan.
  • Security: hostile file names and sizes; cap allocations and recursion; never write to reserved vault folders except through the existing private-write path; every disk write goes through the shared atomic-write crate.
  • Compat: macOS, Windows and Linux; the grep-style content scan must not depend on a system binary. New dependencies for this feature (the ripgrep library crates for walking and searching, approved by the owner) are the only additions.
  • Cache: the index cache lives in the vault's own state folder, so it travels with the vault; a missing, corrupt or version-mismatched cache is discarded and rebuilt, never an error.
  • Strings: all user-visible text goes through the translation tables.
  • Design: uses existing design tokens and components; row height 32 pt, 4 pt spacing scale.

Open Questions

None. Decisions: the large-folder warning applies at 5,000 files regardless of vault markers; indexing pause is manual only; the explorer actions are engine commands with no default key binding; the performance reference is the owner's Mac with a release build and the 10,000-note test vault.