Files
Marcos Paulo 15d7f5e873 feat: editor blocks and lint, vault knowledge, calendar plugin, macOS menu
- notescraft-lint (rules, safe fixes, learned style) and notescraft-blocks (block model and edits); engine lint.* and block.* commands with CLI and MCP parity
- Lint tab, underlines, slash menu with preview in Source and Visual, block grip and menu, Settings > Editor and lint, Vim block keys
- Visual view: tables, note embeds, %% comments, wrapping property chips
- Vault knowledge (Related tab, assistant sources, Settings) and calendar plugin
- Sidebar top padding fixed, dot grid follows PaperCraft spacing, right-card tabs no longer cover the collapse button

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-18 12:36:00 -03:00

8.5 KiB

Editor blocks, component slash menu and note lint

Problem

The slash menu inserts plain markdown and shows only a flat list (SPEC item 21). Inserted components (tables, callouts, diagrams, calendars, whiteboards) have no way to be previewed before insertion, to be moved as blocks or to be edited in place in the Visual view. Notes also pick up small mistakes that nobody sees until later: a link to a note that does not exist, a heading level that jumps, mixed list markers, double spaces, a frontmatter block that is not closed. Today the only checks are the unresolved-links list and doctor in the CLI. Users who write a lot (the owner's daily notes and roadmaps) fix these by hand or not at all. Evidence: owner request in the 2026-10-17 session after reviewing the openknowledge editor (slash menu with components, WYSIWYG blocks, lint with fixes); designs exist in PaperCraft (project NotesCraft, page "Editor").

Goal

A user can insert, preview, move and edit blocks from / and a grip handle, and every note shows its problems with a one-click fix that never changes meaning without asking, all on the device and without AI.

Non-Goals

  • Replacing the Markdown file format. Blocks are plain markdown; a note stays readable in any editor.
  • AI-written fixes. Learning is statistics over the user's own notes, local only.
  • Real-time collaboration or a block database (no Notion-style block ids written into files).
  • Spell-check in the first release (see Open Questions).
  • A native mobile build; the new screens must lay out at 390 pt (design: "Mobile / Slash sheet and lint").
  • Lint of attachments, canvas, whiteboard or diagram files.

User Stories

  • As a writer, I want / to show components with a preview and filter as I type, so that I insert the right block first time.
  • As a writer, I want a grip beside each block to move, duplicate, turn into another type or delete it, so that I restructure a note without selecting text.
  • As a writer, I want a floating toolbar on selected text, so that formatting needs no shortcut I forgot.
  • As a careful writer, I want problems underlined with a one-click fix, so that notes stay clean.
  • As an owner of a large vault, I want lint to follow the style my notes already use, so that it does not argue with my habits.
  • As a scripter, I want lint.check and lint.fix as commands with JSON output, so that CI and the assistant can use them.

Acceptance Criteria

Slash menu and blocks (design: "Slash menu", "Blocks and WYSIWYG")

  • Given / at the start of a line or after a space, when typing a filter, then entries are grouped (Basic, Components, Insert), ranked by fuzzy match, and the highlighted entry shows a preview pane; Up/Down move, Enter or Tab inserts, Escape closes.
  • Given a component entry (table, callout, calendar, diagram, whiteboard, template), when inserted, then the note receives valid markdown or an embed and the caret lands in the first editable place; undo removes it in one step.
  • Given the slash menu inside a code fence, when / is typed, then it does not open.
  • Given a plugin registers a command with the slash flag, when the menu opens, then its entry appears in the Insert group.
  • Given Visual view, when the pointer rests on or the caret is in a block, then a grip shows at its left; dragging the grip or pressing the move-up or move-down command moves the whole block (paragraph, list item with children, table, callout, code fence) and undo restores it in one step.
  • Given the grip menu, when "Turn into" is chosen, then the block changes type keeping its text (paragraph to heading, quote, task, callout and back).
  • Given text selected in Visual view, when the selection settles, then a floating toolbar offers bold, italic, strike, code, link and highlight; each toggles the markdown marks and shows its active state.
  • Given Vim mode on, when in Normal mode, then the block commands are reachable by keys (]] and [[ move between blocks, gb opens the block menu).

Lint (design: "Lint and fixes", "Settings / Editor and lint")

  • Given the right card, when it renders, then its tabs are Backlinks, Related, Lint, Outline, Assistant (active tab shows icon and label, others the icon only); the Lint tab lists this note's issues with their fixes, "Fix all safe" and the learned-style switches, and it never replaces the existing tabs.
  • Given a note, when lint.check {path} runs, then it returns issues {rule, severity, range, message, fix?} sorted by position; fixes carry safe: true only when they cannot change meaning (spacing, list markers, heading level, closing a frontmatter fence).
  • Given the rules heading-increment, list-marker consistency, double and trailing spaces, blank line around headings, fences and lists, unclosed or duplicate frontmatter keys, duplicate headings, unresolved wikilinks, and (optional) spelling, when each is violated, then exactly the matching issue is reported and a clean note reports none.
  • Given an unresolved link [[Releas notes]], when a close title exists (edit distance within a threshold, same folder preferred), then the issue offers "Replace with Release notes" and "Create note"; a link fix is never marked safe and never applied by Fix all.
  • Given issues, when the user clicks a fix, then one undoable edit is applied; when "Fix all safe" runs, then every safe fix is applied back to front as a single undo step and overlapping edits are skipped, not merged.
  • Given "Learn my style" is on, when at least 20 notes use a style (list marker, heading style, date format) in more than 80% of cases, then that style becomes the preferred one, the rule text says so ("Your vault uses - in 94% of notes"), and the vote is recomputed incrementally on edits.
  • Given a suggestion dismissed with Ignore, when the same note is checked again, then it does not return; dismissals are stored per vault in .notescraft/lint-state.json and can be cleared in Settings.
  • Given a 1 MB note, when typing, then lint runs on the edited region and the visible viewport only, off the UI thread, and typing never waits for it (p99 keystroke latency unchanged within 2 ms).
  • Given hostile input (binary text, 100k headings, invalid UTF-8 ranges, unclosed fences), when checked or fixed, then nothing panics and a fix whose range no longer matches the text is refused with Error::Stale.
  • Given the commands lint.check, lint.fix, lint.fix_all_safe, lint.rules, lint.dismiss, lint.state, when invoked as an engine command, from the CLI with --json and as MCP tools, then all three return the same result; the assistant gate treats checks as reads and fixes as writes (pending changes).
  • Given Settings > Editor, when opened, then the toggles, severity pills and learning controls from the design appear and persist as editor.blocks.* and session.lint.*.
  • Given every new user-visible string, when cargo xtask i18n runs, then it passes.

Constraints

  • Stack: Rust only, egui. Lint is a pure crate notescraft-lint at L2 (depends on markdown and index only; no IO). Block parsing builds on notescraft-markdown scanning; the editor crate stays free of egui.
  • Everything is an engine command (SPEC 10). Private state only under .notescraft/ through the atomic writer; the learned style table is derived and rebuilt on open.
  • Performance: lint of a 100 KB note under 10 ms; full-vault style vote of 10,000 notes under 2 s off the UI thread; slash filter under 1 ms per keystroke.
  • Security and privacy: nothing leaves the device; no network.
  • Never crash: no unwrap or panics; every range is checked against the current text before an edit.
  • Design: follow the PaperCraft pages named above. Before implementing a screen run get_design_spec (target egui) on its artboard and run verify_code on the result. Spacing 4/8 pt, rows at least 40 pt (44 pt in compact), tokens from the active theme.
  • Third-party dependencies: none. Spell-check needs owner approval if it uses a crate.

Open Questions

  1. ASSUMED default: spelling stays off by default and ships after the owner chooses between a dictionary crate and an in-house checker built from the vault's own words; the rule slot exists now.
  2. ASSUMED default: lint underlines show only in Visual view and the Source view's current line; the status bar shows the issue count in both.
  3. ASSUMED default: block ids are never written to files; blocks are found by parsing.
  4. ASSUMED default: Fix all safe on save is off by default.
  5. ASSUMED default: the grip menu in the first release has Turn into, Duplicate, Delete; Copy link to block follows later.