margin-docs/docs/architecture.md

Architecture

Tauri 2, React 19, Vite, TypeScript and zustand on the front, Rust behind. Same stack as margin and margin-calendar, which means the build and bundle setup, the token layer and the TipTap editor core carry over from margin rather than being invented again, while the zustand and CSS conventions carry over from margin-calendar, the newer and more disciplined of the two scaffolds.

The split is strict. Rust owns the filesystem: reading and writing documents, walking and watching the tree, the SQLite index, moving files to the trash, and atomic writes. TypeScript owns everything above that: the markdown bridge that turns file bytes into an editable document and back, the WYSIWYG editor itself, and all rendering. Rust never parses markdown and TypeScript never touches the filesystem directly; everything between the two crosses through the dto.rs/ipc.ts contract described below.

The markdown bridge

The bridge is built on remark-parse and remark-stringify through unified, not on @tiptap/markdown, TipTap's own markdown extension. Two things rule that out. @tiptap/markdown is built on marked, which has no frontmatter support, and frontmatter here is not optional: it has to be parsed, hidden from the editor, and written back unchanged on every save. More fundamentally, a marked AST does not carry source positions, while every node remark-parse produces carries a position with byte offsets into the original file. That offset is the whole trick the rest of this document depends on: when a piece of syntax has no model in the editor, the bridge does not reconstruct its text from a generic AST node, it slices the exact bytes out of the original source between position.start.offset and position.end.offset and carries that slice forward untouched. Writing back byte identical is a property of the source string, not of the printer, and only an AST that remembers where it came from can hand that string back.

Where a hand wrapped line lives

Most markdown in the world is hard wrapped: a paragraph is several lines in the file and one paragraph on screen, and the author chose where those lines end. That choice is theirs and this editor does not get to reflow it, so a soft line break survives the round trip as a real newline in the paragraph's text rather than being folded into a space.

Keeping it takes three declarations that have to agree, and it is worth naming all three because each one on its own looks like an optimisation somebody could remove. src/markdown/parse.ts puts the newline in the text. prose.css draws a paragraph pre-wrap so it is on screen where the author put it. src/model/schema.ts declares the paragraph whitespace: "pre", and that is the one that was missing: two libraries read that field and both of them rewrite the paragraph without it. prosemirror-view reads it to decide how to parse the editor's own DOM back after a keystroke, and at the default every soft wrap in the paragraph being typed into came back as a hard break, so one character typed into a hand wrapped file put a backslash at the end of every line in that paragraph. prosemirror-transform asks the same field before it joins two blocks, so Backspace between two hand wrapped paragraphs rewrote the wraps in both.

The heading needs all three for the same reason and was declared with none of them, which is the same bug wearing the one hat markdown lets an author wrap by hand. A setext heading is two lines of text over an underline, and mdast writes a break inside one as a backslash, so a character typed into a two line heading put a backslash in the user's words exactly as it used to in a paragraph. The first save cannot rescue it either, because a heading that has been wrapped has no ATX spelling to be normalised into, so it stays setext and every later keystroke re-arms the bug. The field goes on at every level rather than only the two that have an underline: the deeper four cannot be wrapped in the file, but they can hold a line ending written 
, and at the default a keystroke turned that into a break the writer then swallowed as a space.

The paragraph's parse rule says the opposite on purpose, and a rule's own answer outranks the node's. Whitespace is significant in a paragraph this editor rendered, and meaningless in a <p> off somebody else's web page, where the line endings are that page's source indentation and keeping them would put breaks and runs of spaces through the middle of a pasted sentence.

Only a running editor can prove any of this: the fault is between the keystroke and the serializer, and the serializer never saw it. tests/bytes.spec.ts is where that proof lives.

Callouts, toggles and unknown syntax

On disk a callout is a GitHub alert: a blockquote whose first line reads [!NOTE], [!WARNING], [!IMPORTANT], [!TIP] or [!CAUTION]. remark-parse hands back an ordinary blockquote node for these, so a visitor walks the tree afterward, recognises the marker in the first child, tags the node with its variant and strips the marker before the editor ever sees it. Serialization reverses exactly that: re-emit the blockquote and put the marker back as its first line.

A toggle is <details> and <summary>, and remark does not parse HTML blocks into a tree at all; it hands them back as opaque html nodes carrying raw text. The bridge looks for a matching details/summary pair in that raw text, and where it finds one it lifts the summary and the body into a toggle node the editor can open and close like a native control. A details block that does not match that exact shape, nested oddly, missing a summary, carrying attributes the editor has no model for, is left exactly as it was found. Everything else the parser cannot classify, an HTML block that is not a details/summary pair, a construct remark itself does not model, a piece of syntax nobody has written a visitor for yet, becomes a raw node under the rule in conventions.md: the literal source slice, editable as monospace text, written back unchanged. Nothing is ever silently reformatted or dropped.

Tables, maths and the rest of what the bridge learned to model

The first pass over the bridge modelled prose and left everything structural as a raw node. A GFM table, a $$ math block and a <details> toggle were all bytes the editor showed and refused to touch. Modelling them is what turns those blocks from something the editor carries into something it edits, and every one of them was built as the exact inverse of the writer that puts it back: the first mdast row becomes header cells and the delimiter row's per column alignment is copied on to every cell of that column, because markdown has no way to say that one cell is centred and the rest of its column is not. That inverse relationship is the whole test: a construct is modelled only where parsing it and writing it back is the identity, and the parser refuses everything else.

The refusals are the interesting half and they are all the same shape. A table row with more cells than its header has no column to put them in, so there is no answer between dropping the cells and inventing a column, and the block stays raw. A toggle whose summary does not survive being unescaped and escaped again character for character stays raw. A math fence that runs to the end of the file unclosed stays raw, because writing it back would invent the closing delimiter. So does a carriage return anywhere inside any of the three, since remark reads a lone \r as a line ending and the writer never puts one back. In every case the file keeps its exact bytes and the user gets an editable monospace block instead of a rich one, which is the trade this project has always made.

Modelling a table does cost one thing, and it is on the record rather than hidden. The house style writes a table with its cells padded out to the width of the column, and a table written compact by hand is repadded by the save that settles the file. Nothing else about it moves, no cell content changes, and the second save is byte identical, which is the same one time normalisation the house style has always applied to a setext heading or a tilde fence. The alternative would be a source attribute on the table node holding the author's spelling, and that cannot work: the schema is frozen, and the editor rebuilds every node from JSON when it installs a document, so the node the writer sees is never the node the parser made. roundtrip.test.ts names the two corpus files this affects and asserts, cell by cell, that the padding is the only thing that changed.

What the writer proves before it writes

mdast writes the tree, so escaping, fence lengths and list indentation are decided by the library that read the file rather than by string concatenation. What mdast cannot decide is whether this reader will hand the block back as the block the document holds, and several spellings turn on exactly that. A url the file wrote bare should stay bare, not become [https://x](https://x) and put a diff in front of somebody who edited a different paragraph. A code span or an equation the file wrapped across two lines should keep its line ending rather than have it swapped for a space. A <summary> should keep the line endings the file gave it. None of those is safe on the strength of a regular expression here, because GFM's literal autolink grammar has more corners than one, and every corner that was got wrong cost a destination.

So the writer proves rather than assumes, and it proves the same way every time: write the block out, read it back with the pair the app opens files with, and compare. There are two ladders. The outer one is about the block, and it has three rungs, from writing every line ending where the document puts it, through handing the spans back to mdast, to writing the two a text node cannot hold as 
 and 
. The inner one is about a url and also has three, shortest first: the url on its own, <url>, then [url](url), which has no grammar left to get wrong. The last rung of the outer ladder is written whether it verifies or not, because a document holding something markdown cannot spell still has to be saved and the one thing that must not happen is a file that gains bytes on every save for the rest of its life.

The comparison is against the ProseMirror node, not against the mdast tree the block was built from, and that is the whole point of it. The two trees disagree in ways that mean nothing: remark reads an item's spread off the blank lines inside it while the writer sets it from the list, and a parser extension hangs its own fields on the nodes it made. Every one of those differences is a comparison that fails on a block that is perfectly fine, and each one was a rung of this ladder quietly switched off. The document is the thing that has to survive, so the document is what is compared.

The comparison itself is by name, not by object. The block the writer built and the block it reads back are bound to two different Schema instances over one set of specs, so every NodeType and every MarkType in one is a different object from its twin in the other, and Node.eq, which compares them by identity, answered "different" for every block it was ever given. That was the whole ladder switched off at the top rung, and src/document.ts has the same comparison for the same reason.

Two questions about a file are not questions about any block in it, and each has a check of its own because the ladder cannot see either. The seam between two blocks is one: a blank line closes every construct markdown has except a list, which carries on over one and swallows the block below, so a list written next to preserved source is proved apart and respelled, with a wider item indent or the other bullet, until it is.

A rule inside a list item is the same question asked from the other side, and it is the one place the house style has to give way rather than the seam. --- is the house spelling and it is a setext underline wherever a paragraph is still open above it, which inside a tight item is the only place the line under the item's text can be. Reading that as "these two blocks cannot be written a line apart" is correct about --- and wrong about the rule, so the writer spread the whole list to make room, and a tight list came back loose with its items wrapped in paragraphs they did not have. *** is the same rule in the one spelling that does interrupt a paragraph, the writer already reaches for it when a rule lands on the first byte of a file, and a tight item now gets it. A loose item keeps ---, because the blank line in front of it has already closed the paragraph.

Those respellings cover every raw block a file can hand over, because a file's own raw block starts in the first three columns and column four is indented code. An edited one can be anything, and for some of them no spelling exists at all: four spaces typed into a raw block below a list makes bytes that no seam can hold, since they read back as a code block wherever they are put. So the seam has a last resort. When a list beside a raw block has no spelling left, the raw block is written from the bytes the file gave it and the edit does not reach disk that save. That is the one place this editor knowingly drops something the user typed, and it is the right way round: the alternative measured on the same file swallowed the list into the raw block and then moved bytes around inside somebody's html on the save after. A raw block with no list beside it is written exactly as it always was.

Dropping it is the decision; dropping it in silence was the bug. The writer had no way to say it had happened, so the save path marked the buffer clean over bytes the edit was not in: the file stopped changing, the unsaved dot went out, and the only trace was the edit still sitting on screen. The writer now reports the refusal on the way past, the dirty flag has that as a second input beside the tree comparison, and the toast says which block and why the file won. The flag stands for exactly as long as those bytes are the file's, so a later lap of the debounce over the same unsavable block says nothing more, and it is deliberately kept out of the question the debounce asks, since a refused edit is not a difference another write could fix and re-arming for it would be a loop.

Where the body starts is the other: --- on the first line of a file is not a rule, it is the opening delimiter of frontmatter, and everything down to the next one stops being markdown. That check is asked only of a body whose first three characters could open a delimiter, and only when the body really is at the first byte of the file. A body with frontmatter coming in front of it was never in danger, and running the defence there did the damage it exists to prevent, because the blank line it pushes the body down by is handed back as part of the frontmatter and written again on the next save. serializeMarkdown is the one thing that knows whether a prefix is coming, so it is what tells the body writer.

One inline shape has no spelling either, and the writer settles it rather than the editor. A hard break is a line ending inside a block, and there is no line left for one to start at the end of a block, so a break with nothing under it is written as nothing. It used to be written as a backslash on a line of its own, which reads back as a literal backslash in the user's words: a character they never typed. That answer is in the serializer and nowhere else on purpose, because the trailing break has more than one way in. Shift+Enter at the end of a paragraph is the obvious one, and is still allowed, since it is a line somebody is halfway through typing and the next character makes it a real break. Deleting the text out from under a break that was legal where it was put is the other, and no keystroke guard sees that one at all. The editor refuses only the level 1 and 2 heading, where a trailing break also takes the setext underline with it, and that refusal is about the marker, not about the backslash.

Reading costs about eight times what writing does, and this editor saves half a second after the user stops typing, so neither ladder runs on a block that has nothing in it to get wrong. A block reaches the outer one only when it holds a line ending somewhere markdown has no way to write one, or bytes mdast did not choose, and it reaches the inner one only when it holds a url that could be written short. On the real corpus and on a 200 KB document of ordinary prose that is no blocks at all: a save is 24 ms and no reparse happens. The shape that pays is a document with a bare url in every paragraph, which costs two trips through the parser per block. Measured in Chromium on three large real files, a save is 26 ms for the 179 KB yt-dlp README, 56 ms for the 266 KB opentelemetry-js changelog and 91 ms for the 251 KB node changelog, each byte identical on the second save.

The block lanes

A node's shape is in the frozen schema and is turned into a TipTap extension mechanically. What a node does, its ProseMirror plugins, its node views, its keymap and its input rules, is not derivable from a shape and does not belong on a generated extension, so each of the five blocks with real behaviour is one extension in one file, listed once in a registry that the extension list spreads without knowing what is in it. Tables, syntax highlighting, maths, mermaid and toggles are then five files that can be worked on at once, each exporting its extension and whatever commands the editor handle delegates to when a toolbar button is pressed.

The toggle is the one whose behaviour is mostly outside ProseMirror. It is a real <details>, and its summary row is chrome rather than content: the row is declared not editable, the title inside it is declared editable again, and every keystroke in that island is turned into an ordinary transaction that writes the summary attribute. Native disclosure is cancelled and open is written by a command for the same reason, since both of those are bytes in the file and a browser flipping an attribute behind the document's back is a title or a state the next save has to guess at. Cancelling the click is not the whole of it either: a disclosure is a control, so the browser works one from the keyboard too and sends the row a click for every space typed anywhere inside it, which was every other space in a title flipping the toggle and writing open to disk. The flip asks for a pointer press, or for the row itself holding the keyboard, and takes nothing else as consent.

Being chrome has a second consequence that reaches further than the node. A caret in the title is not in the document at all, so ProseMirror's selection stays wherever it last was, and a toolbar button pressed while a title is being typed runs its command against a paragraph the user is not looking at. Rather than give the title a selection, which makes Horizontal rule and Insert image replace or split the toggle, the file refuses: a transaction that changes the document is thrown out while a title holds the caret, bar the two the title's own surface makes, and the caret is put back in the title on the frame after TipTap's own focus lands. The toolbar draws itself disabled for the same condition, read off the page rather than off a transaction, because clicking into a title dispatches none.

And a toggle only ever sits among the document's own children, because that is the only place the bridge pairs one. A <details> inside a quote or a list item goes to disk as a <details> inside that container and comes back as a single raw block: the bytes survive, and both constructs stop being editable. So a transaction that puts a toggle below the top level is refused, and the ranges it is asked about are widened to the whole top level block first, since a wrap rewrites only the two markers it puts either side and the thing it moved a level down is in the gap between them.

The order in that registry is load bearing rather than alphabetical. ProseMirror resolves a node view first plugin wins by node name and gives a node view constructor no way to decline, and a mermaid diagram is not a node of its own but a code block whose language happens to be mermaid. So mermaid owns the code block node view outright and draws an ordinary fence for every other language, while the highlighter contributes decorations only, which is what it wanted anyway: highlighting is inherently a decoration and never a transaction that touches the text.

Two rules cut across all five. A command that has nothing to act on where the cursor is returns false and does nothing, which is what a button pressed in the wrong place should do. And anything that puts a node in the document asks first whether a node can go there at all: a table cell holds inline content and is isolating, and ProseMirror asked to insert a block into one will split the table around it and leave a row with no cells behind, which is a table the writer turns into three blank lines. A fence and a raw block are the same question from the other side, since both hold bytes that are the user's and an insert cuts them in half.

That guard is src/editor/fits.ts, and it now answers two questions rather than one, because the first one turned out to be half the problem.

The first is about a node: can this thing go here. fits answers for one position and is the rule itself. placeable asks it for a whole selection, which is the question a command actually has: a selection has two ends, and a rectangle of table cells dragged out has neither of them anywhere a caret would be, so it is refused outright whatever the type. An inline formula fits a cell perfectly happily, which is right for a caret and catastrophic for a drag, and that gap is how one insert emptied six cells of somebody's table. place is the guard and the insert in one call, so a command written through it has no insert in it to forget to guard.

The second is about a command: may this edit happen here at all. Nothing asked that for two milestones, and a block conversion is where it showed: setNode asks whether the new type fits and never asks what the old block was, so the Heading tool rewrote a raw block's own bytes as escaped markdown, and the Paragraph item, which TipTap answers by lifting once the block is already a paragraph, deleted the callout around the caret along with its label. change is that half. It refuses over a raw block outright, and otherwise it builds the transaction without dispatching it, looks at what it did, and throws it away when a callout or a toggle that was there is gone, or when a finished line break has landed somewhere the file swallows. Answering on the finished transaction rather than on the command is the point: there is no list here of which commands lift, so a command that starts lifting in a later TipTap is refused on the day it does. Its one exemption is the button that names the wrapper, since the Toggle button pressed inside a toggle is meant to remove it. markable and breakable are the same shape for the Link tool and for Shift+Enter.

Four things reach these guards from outside the toolbar. A pasted image asks before the bytes are sent to be written, so a paste that cannot land leaves nothing in the assets folder, and again after the write returns, because the caret is the user's during a round trip to disk; the Insert image tool asks the same question through canInsertImage, since it has to write the picture before it has a path to insert. A plain text paste is not refused anywhere, since text goes everywhere, but where paragraphs would tear the block open it arrives as text instead, and a drop of blocks where blocks do not fit is refused outright. And "--- " typed at the start of a line is the one typing rule that inserts a node beside the caret rather than wrapping or retyping the block the caret is in, so it is the one typing rule that has to ask; the others are operations ProseMirror declines on its own.

src/editor/fits.test.ts is what holds all of that together, and it enumerates rather than lists. It asks the running editor for its entry points: every method on the editor handle, off createCommands; every method on the find handle, off createFind; every chord, read off every extension's addKeyboardShortcuts the way the extension manager reads them; every ProseMirror prop, read off every extension's plugins; and every prop the component puts straight on the view, off createEditorProps. That last channel is neither an extension nor a handle and was invisible to the enumeration until it was lifted out of the component, which is exactly the shape of gap this file exists for. Each entry declares a family and each hostile context answers for every family, so a new family forces a column and a new context forces a row, both at compile time. Three checks then apply to every cell whatever its row says: the number of raw blocks is unchanged, no callout or toggle is lost by anything not asked to lose one, and no toggle ends up below the top level.

Nothing in that file calls a handler. Every entry point goes through EditorView.prototype.someProp, borrowed off prosemirror-view rather than modelled here, because the walk it does is the question: the props the component put on the view, then the direct plugins, then the state's plugins in order, first answer that is not false. Calling a guard by name and asserting what it answers proves nothing about whether the running program asks it, and four guards in this project's history were shipped with a green test of exactly that shape. What the unit suite still cannot do is construct a view at all, because vitest runs in node with no DOM, so the event object and the parsed slice are built by hand there. tests/clipboard.spec.ts is the other half: a real EditorView in Chromium, a real mouse drag across a rectangle of cells, a real Cmd+V off the system clipboard, and assertions only about what is on screen afterwards. It is the only place in the repository where the whole chain from a key to a byte is real.

Where a guard sits in the plugin list is part of the guard. ProseMirror offers an event to the plugins in order and takes the first answer that is not false, and prosemirror-tables installs a paste handler that claims every paste made while a rectangle of cells is up, replacing the content of every cell in the rectangle with whatever the slice holds. It sat at index nine and this app's clipboard plugin sat at fifteen, so for two rounds the app's paste guard was written, documented, unit tested and asked about nothing. One word on the clipboard replaced six cells; an image, which carries no HTML for ProseMirror to parse and so arrives as the empty slice, emptied them. The clipboard extension now declares a priority above every other extension in the tree, which puts it at the head of the list whatever order the extension file lists things in, and being first is asserted rather than believed: src/editor/fits.test.ts reads the built plugin list, computes the index of every plugin claiming a paste or a drop, and fails if anything is in front. A guard is also worth nothing when the gesture it is watching for produces no event to answer, and that is the sibling of the ordering fault rather than a different kind of mistake. Typing over a rectangle of cells is refused through handleTextInput, which prosemirror-view offers only for a character the browser was about to insert. An IME produces none: the browser writes the composition into the DOM itself and prosemirror-view reads the result back, and on the way there its own compositionstart replaces the rectangle with whatever a DOM range spanning cells makes, because prosemirror-tables hands back a cell selection only while a mouse drag is still down. What follows is either that range collapsed on to the whole content of one cell and replaced, or a text selection left spanning cell boundaries and replaced across them, which joins the cells and rows away and hands the writer a table whose rows disagree in width. Neither reaches the guard, and the second never reaches it by construction, since a change crossing a textblock is dispatched without the offer being made. Claiming the event does not help, because a composition cannot be cancelled and returning true only stops ProseMirror's own bookkeeping. What is decidable is where the composition lands, so the rectangle is collapsed to a caret at the end of its anchor cell before one can start, and false is returned so the library's own handler still runs against that caret. Being first also means standing aside deliberately, for the one paste the library does better: cells copied out of a table and pasted into one, recognised with prosemirror-tables' own predicate rather than a reimplementation of it. Emptying cells is a real thing to want and it is Backspace.

There is no table op for the header row for a related reason. GFM has exactly one header row, it is the first one, and there is no spelling for a table without one, so a toggle would offer an edit the file cannot hold and the next open would silently take back. The same rule is why a new formula is created holding a placeholder rather than nothing: an empty formula is $$$$ on disk, which reads back as four characters of text, so a box the editor draws and the file cannot hold is a box that disappears on the next save.

Not every change to the document is a change to the file, and the block layer is where that first became true. Dragging a column edge writes a width on to every cell in the column, which is a real ProseMirror transaction and marks the buffer dirty, and GFM has nowhere at all to put a column width. Sniffing for that particular transaction would be fragile, so the question is asked of two trees instead: a walk comparing type, text, marks, child count and attributes, skipping the handful of attributes the serializer never reads. It short circuits on identity, which is every subtree a transaction did not visit, so it costs nothing per keystroke. The allowlist is deliberately short and each entry has its reason written beside it, because an attribute wrongly called insignificant is a user edit that never gets saved.

Types are compared by name and marks by name and attributes, never by object, and that is not a shortcut. The two trees this walk is handed are never built on the same schema: the disk side comes off the bridge, which parses against the frozen schema, and the live side is bound to the schema TipTap generates from those same specs and which the editor rebinds every opened document on to. Two instances over one set of specs means every type object in one differs from its twin in the other, so a.type !== b.type and Mark.sameSet were both true of every pair this function had ever been given, and everything behind them, the attribute allowlist included, was unreachable. Name is also the right thing to compare rather than a way around that: the serializer dispatches on node.type.name and mark.type.name and reads nothing else off a type.

Which two trees is the part that had to be got right twice. Asking whether this keystroke changed anything since the last one makes dirty a count of transactions rather than a fact about the file: the answer can only ever go up, so an edit and its undo inside one debounce still wrote, and on a hand written file the save path's own byte comparison cannot catch it, since that file's serialized bytes differ from its own bytes from the moment it opens. So src/document.ts keeps diskDoc beside diskText, the tree whose serialization is the bytes currently on disk, and differsFromDisk asks the question of that rather than of the previous keystroke. The two move together through one function, so they cannot drift into one guard sending a write and the other holding it back. Behind that the save path still serializes and compares the result against the bytes it last saw on disk, which catches an edit that really did happen and really did come out identical. Between them they are what stops a gesture that moved a line on screen, or a typo typed and taken back, from putting a whole file diff in somebody's git status.

Mermaid, and what is not in the main bundle

Mermaid is about 700kB before its per diagram chunks, which are several megabytes between them, and almost no document has a diagram in it. It is imported dynamically the first time a diagram is actually drawn, not when one is merely present with the caret inside it, so the library is a chunk of its own and the main bundle contains none of it. Rendering is asynchronous, so the node view draws the fence first and swaps the SVG in when it arrives, and it does that without dispatching a transaction: nothing mermaid does reaches the document, and a diagram that fails to parse stays as the code the user typed with the parser's complaint beside it. Nothing it needs is fetched over the network, which matters because the app runs under a strict CSP with no connect-src for anything but the Tauri IPC. KaTeX is the opposite trade and is bundled outright, since a formula is small, common, and has to render synchronously; its fonts are emitted as files rather than inlined, because the CSP's font-src is self and refuses the data: URI a small enough font would otherwise become.

The dto.rs and ipc.ts contract

Rust and TypeScript meet at exactly one seam: src-tauri/src/dto.rs, a set of #[serde(rename_all = "camelCase")] structs, and its hand-written mirror src/ipc.ts. Both sides are built against that shape rather than against each other, which is what lets the filesystem layer and the markdown bridge be built independently of one another: the tree, the read and write commands and the index queries only need their DTO agreed, not implemented, before anything above them is built against a stand-in of the same shape. The file is frozen by convention: a command's Rust body can change freely, but adding, renaming or retyping a field is a decision made once, in both files, in the same change.

The dev IPC mock

pnpm dev runs the Vite dev server on its own, with no Tauri process behind it and no window.__TAURI_INTERNALS__ for @tauri-apps/api to find. src/ipc.ts checks for that bridge and, when it is absent, swaps in a mock implementation of the same command surface backed by an in-memory fixture, rather than throwing or leaving the screen blank. That is what lets the Playwright suite in tests/ (pnpm test:ui) drive the real editor, the real store and the real components in plain Chromium without a compiled Rust binary anywhere in the loop, and it is also what makes iterating on the editor fast day to day: no Rust recompile between changes. The mock is exactly as wide as dto.rs, never wider, so a command the mock cannot answer is a command that has not been added to the contract yet, not a gap in the mock to be patched around.

That fixture is also how a test reads what a save actually wrote. tests/disk.ts puts the shim and the fixture behind one import, and tests/bytes.spec.ts uses it to type one character into a running editor and then ask the file what happened. Every data loss bug this project has had lived between the keystroke and the serializer, where a unit test that builds a document by hand cannot see it, so that suite is deliberately about bytes and deliberately short: one test per way the app has been caught rewriting something nobody touched.

The corpus under src/markdown/corpus/ is globbed by folder rather than by a list of folder names, so a fixture written for one test is inside every sweep the moment it is added. That is the whole reason a sweep is worth having, and naming folders meant the twenty hardest files in the corpus sat outside four of the gates that were supposed to cover them.

The SQLite index

SQLite through rusqlite with the bundled feature, so there is no system SQLite dependency, and with FTS5 compiled in as a side effect of that same feature rather than a separate cargo flag. The database lives in the app data directory, never inside any folder the user opened, and it is derived state rather than a source of truth: every row is rebuilt from the markdown files on disk, so deleting it costs nothing but the time to walk the open roots again. It is kept current by the same notify/notify-debouncer-full watcher the tree uses, debounced because a git checkout or another editor's save fires a burst of filesystem events for what is really one change. The index answers three things a plain file tree cannot: quick open by filename and path on Cmd+P, full text search across every open root on Cmd+Shift+F, and the backlinks section appended to a document, a reverse lookup of every relative markdown link elsewhere that resolves to the file currently open.

Derived state that only rebuilds at launch has to survive the session, and the worker behind it was written as though it could not fail. It ran a bare loop over its queue, so one panic ended indexing for as long as the app stayed open: the receiver dropped, every later send was discarded by a .ok() that never looked, and search, quick open and backlinks went on answering from a frozen snapshot with nothing on screen to say so. There was a reachable way to reach it, too, since a document is free to contain the control character the search snippets are marked with, and a line holding one and nothing else made the snippet slice start after it ended. The panic fired inside the search command, which holds the connection across its whole row loop, so it poisoned the mutex and took the worker with it. The loop now catches a panic, clears the poison, says so in the index status and takes the next job, and it drains its queue before acting on it rather than one message at a time, because the watcher's report that the kernel dropped events is a full walk of the root and hundreds of those can pile up behind a long build. The drain keeps the last word about each path and never reorders, which is the rule the debouncer already applies inside one batch.

The watcher had the same shape of gap about its own root. Detecting that the open folder had gone rode on an event arriving for something inside it, because notify does not ask FSEvents to watch the path to the root and discards anything above it, so renaming or deleting a parent directory was never noticed at all and the watch was left holding a stream on a path that no longer existed. A watchdog beside each watch stats the root on the debounce tick instead, which is one call and does not depend on any event being delivered by any backend.

The link rewrite sweep is the one consumer that deliberately does not share the walk. The tree and the index honour .gitignore because a sidebar full of build output and a search box full of vendored READMEs are both worse than those files being hidden, and the invariant that a file the tree hides is a file no search result can open is worth keeping for both. The sweep is not display, it writes to the user's files, and a .gitignore is a statement about version control rather than about whether something is a document: a relative link inside an ignored draft is one the user still follows, and leaving it pointing at a path this app is the one that moved is a break nobody finds until they follow it. So it gets its own walk with the git sources off and everything else on, the four always skipped folders included, and it is bounded by a document count it reports rather than by a depth it would have to hide.

Order of work

The filesystem layer and the markdown bridge are the two things everything else depends on, and neither is proven by the other, so the first milestone is Rust: roots, the tree, atomic read and write, the watcher and trash, built from the start against a frozen dto.rs and ipc.ts, with the dev IPC mock standing in for it on the TypeScript side. The second is the bridge itself: parsing, the raw-node slicing that makes the round trip byte identical, frontmatter separation and serialization, proven with round-trip tests before a single line of editor UI exists, because a round-trip bug is obvious in a plain text diff and invisible once it is glued to a rich text view. The third is the WYSIWYG editor: TipTap wired to the bridge, the sticky bottom toolbar, callouts, toggles and image paste into assets/. The fourth is the SQLite index: the schema, the watcher-driven indexer, quick open, full text search and backlinks. The fifth is the rest of the shell: multiple roots open at once, the tree showing every file including the greyed-out ones that open in the system default app, and settings and the updater.