Diff View

Diff View compares the file in the active frame with another text file. The compare flow is built around note content first: it starts with nearby notes as preview cards, then widens the search only when you need a broader scope.

Opening Diff View

• Keyboard shortcut - press Mod+Shift+D from a file-backed frame.

• Command Palette - search "Check diff" (Mod+K).

The command is shown only when the active frame has a real file path, such as a Note Tray note or an External File Editor tab. Opening the command launches the compare picker and, after you choose a target, splits a Diff View frame to the right.

Compare Launcher

The launcher opens as a modal titled around the current file, then presents up to four scope tiers. Each tier keeps the same filter input and candidate focus model.

The first two tiers are browse-first: candidates render as cards with the note number or filename, heading, excerpt, and recent modified date. This makes numbered Markdown notes identifiable by their content instead of by 1.md, 2.md, and so on.

Filtering

Typing in the launcher filters the active scope immediately:

• This tray, Workspace, and Other apps match against the heading, excerpt, note number or filename, and basename.

• Mac searches file names through Spotlight. It is an escape hatch for arbitrary files, not a content search.

Only text candidates are loaded for the content-aware tiers: .md, .markdown, and .txt. The active file is excluded, duplicate canonical paths are removed, and blank files are skipped.

Scope Escalation

When a scope has no useful match, the empty state offers the next wider search:

• From This tray, search the whole workspace.

• From Workspace, search Other apps when available, otherwise search this Mac when the Mac tier is available.

• From Other apps, search this Mac when available.

• From Mac, use Browse with Finder.

You can also click the numbered scope buttons directly. Only available scopes are shown, so the visible buttons may be fewer than four.

Other Apps

The Other apps tier lists known zudo-text app/workspace pairs from this machine. Each app starts as a teaser row; click it to load that app's note-tray candidates. Loaded apps then show their note directories with sticky headers, and the launcher filter narrows only the loaded content.

This tier is hidden on iOS.

Mac Search

The Mac tier uses Spotlight to search file names anywhere Spotlight can see. It is intentionally different from the content-aware tiers: use it when the target is outside zudo-text's managed note trays or when you know the file name.

The Mac tier is hidden when either condition is true:

• Spotlight search is unavailable on the current platform.

• Settings -> General -> Use Spotlight for file/directory search is unchecked (disableSpotlightSearch is enabled).

The launcher still opens when the Mac tier is hidden. This tray and Workspace remain available.

Live Preview

On wide desktop viewports, the launcher shows a live unified diff preview beside the candidate list. Moving focus to a candidate prepares a preview against the current file and shows +N -N stats in the preview header.

On narrow windows and mobile viewports, the preview pane is omitted. The candidate list fills the dialog, and selecting a candidate opens the full Diff View frame.

Detail Frame

After you select a target, Diff View opens as a frame component with its own toolbar.

The toolbar shows:

• Identity chips for the left and right files. Numbered notes use #N; both chips include heading text and the containing directory when available.

• Sibling steppers around the right-side chip when the right file is a numbered sibling. Use the left/right buttons to compare against the previous or next numbered note in that same directory.

• Swap sides to exchange the left and right files.

• Change... to reopen the compare launcher and replace the right-side target in the same frame.

• Stats as +N -N for the current diff.

Diff orientation follows the app convention: the left side is the current file ("mine") and the right side is the target. Swapping sides reverses that orientation.

Layout

Use the frame layout switcher in the frame chrome to choose the Diff View layout:

The selected layout is part of the Diff View frame state.

iOS Behavior

On iOS, the compare launcher still opens and the local content scopes remain available. The Mac tier is hidden because Spotlight file search is macOS-only, and Other apps is hidden because cross-app workspace discovery is not available there.

Starting an empty comparison

An empty Diff View explains the comparison and offers Choose files to compare…. The action selects the first workspace file when none is configured, then uses the existing comparison picker for the second. The request carries the intended frame id. Manual opens the history guide.