Web workspace

Web workspace

track web serves a local browser workspace for reading and navigating the vault. It is a thin frontend over the CLI: it renders note bodies, resolves [[...]] links into navigable, hover-previewable anchors, and draws the note graph.

Start, stop, and update the server

From Neovim, start the workspace with :Track web. Stop it with :Track webStop, then run :Track web again when you want to restart. Stopping does not restart automatically. Save any unsaved browser edits before stopping; the command does not save browser drafts.

Both commands accept an address, either as :Track webStop 127.0.0.1:8765 or :Track webStop --addr 127.0.0.1:8765. Without arguments, webStop targets the server started by this Neovim instance, using its launch address and environment even if you changed the plugin's web_addr setting afterward. With no active launcher job, it uses the current web_addr (default 127.0.0.1:8765) and current configuration. An explicit address selects that server.

The command uses the CLI's track web stop --addr ADDRESS and its PID record. It can also stop a managed server started outside Neovim when the address and cache configuration match. It reports an already stopped server without an error. If stopping fails, the launcher keeps its live job so you can retry; stopping a different address leaves that job alone. A missing PID record cannot identify an old listener, so the command does not kill a process merely because it uses the port.

Updating Track changes the installed binary, not an already running server. Stop the old server before opening the updated workspace. If Neovim itself still has the old plugin and bundled CLI loaded, exit and reopen Neovim after updating. From a shell, use track web stop --addr 127.0.0.1:8765, then start track web --addr 127.0.0.1:8765 with the updated CLI. See CLI.

Workspace navigation

The desktop sidebar is vertically centred in the full window. It stays below the tab strip as window size or text size changes. In a short window, scroll its navigation controls; Settings remains at the foot of the sidebar. At phone width or on a touch-only screen, the floating Track button replaces the sidebar.

What it offers

• Rendered Markdown reading with GFM tables, task lists, and Mermaid diagrams.
• Hover previews and persistent floating windows for linked notes and media.
• A local link graph you can open per-note or full-screen.
• Follow mode, so the web view tracks the note you are editing in Neovim.
• A Markdown viewer for reading local files or a folder without importing them into a vault.
• A configurable Home dashboard landing note, with recent-notes, journal, and pinned widgets.
• Calendar events with single-event registration, time zones, related notes, and recoverable trash; alongside today's, tomorrow's, and this week's dated Tasks.
• A metadata editor (the Meta dialog in the note actions menu): dedicated fields for the note's title, tags, description, cover image, and icon, plus a free-form block for Properties. Built-in fields get typed controls — the cover image can be uploaded straight from the browser into the vault assets — while props stays free-form YAML. The engine composes and validates the whole edit (the same rules as track meta --edit); the frontend never assembles YAML. Changing the title renames the note and rewrites its backlinks. The published static site has no editor.

Copy selected note lines

Select text in a vault note to open the copy popup in the live web workspace or Track.app. Copy range copies a path:start-end reference, Copy markdown copies the selected source lines, and Copy for Confluence copies formatted content for a rich-text editor. Source ranges cover whole Markdown blocks or list items, so selecting part of a paragraph copies its source lines.

Scrolling closes the popup rather than moving it with the text, including inside a floating note window. The text stays selected for ordinary keyboard copy. Select text again to reopen the popup. Published pages and the external Markdown viewer do not offer these source-line copy actions.

Recovering from a note load error

In the live web workspace and Track.app, a failed background refresh leaves the last loaded note and any unsaved edits visible. An error explains that the displayed version may be stale. Select Retry to fetch the note again without reloading the workspace or discarding the draft. A successful refresh does not save your edits; use Save when ready. If the note changed on disk, the existing conflict protection still applies.

If the note has not loaded yet, Retry tries again and Close tab closes that failed tab. On the configured home note, which is not an ordinary tab, Go to workspace leaves the error view so you can use the navigation rail. Closing a tab does not repair a server error: other notes may fail too until the server recovers. Keep unsaved work in the editor or copy it somewhere safe before reloading or quitting.

Graph hover previews

In the full graph, rest the pointer on a node to preview its note. Move into the popup to read or follow a link; leaving the node and popup closes the preview after a short grace period. Hovering another node releases the previous preview. Dragging or resizing a graph preview changes its position or size without keeping it open. Panning, zooming, or resetting the graph also releases the current node preview.

Choose Pin preview to keep a window, including across page changes; choose Open as page or click a graph node to navigate to its note. Unpinning a graph preview restores its hover lifetime. Ordinary note-link previews keep their existing behavior: dragging or resizing one keeps it open until navigation. A link inside a graph preview opens an independent note-link preview; closing its source popup does not close that newer window.

Voice input

Open Voice input in the live workspace, then press the microphone to start Japanese recognition (ja-JP). Press it again to stop. Interim words remain provisional; confirmed text is editable, with the existing copy, clear, search, and journal actions.

The macOS app defaults to macOS speech, using Apple's built-in Speech framework on macOS 14 and later. Recognition also offers the existing Browser speech backend when Web Speech is available. Your explicit choice is remembered in this app; the web client continues to use Browser speech and keeps a separate preference. Upgrading changes the native default without requiring a provider key or changing other settings.

Built-in does not mean offline-only: macOS speech may send audio to Apple servers. Availability and offline operation depend on the language, device, system configuration, and network. Track checks Japanese support and current availability at start; Apple can also impose service limits. The browser backend follows the browser's speech service and may also process audio remotely. Track never switches services automatically after an error. Choose another available backend explicitly if needed.

Only starting voice input requests Speech Recognition and Microphone permission. If denied, allow Track under System Settings → Privacy & Security → Speech Recognition / Microphone, then try again. Restricted permissions need administrator help. No usable microphone, unavailable Japanese recognition, audio input changes, and service errors stop recognition and display an explanation.

macOS speech stops capturing after 55 seconds to stay below Apple's approximately one-minute task limit. Start again to continue. Stop releases the microphone immediately and allows up to three seconds for a final transcript; if none arrives, unconfirmed words are discarded with an error. Leaving the voice view, reloading, closing the app, or changing backend cancels the session and discards its provisional words. Only the active session can update the transcript.

Published site navigation

The published static site's sidebar omits New (recently created notes) and Voice input. Both remain available in the live web workspace and desktop app. Published sites keep sidebar search, browsing history, the note hierarchy, and the full graph for reading and navigation.

Retired agent requests

The built-in Agent requests panel and its explain, research, and update actions have been retired. Existing notes and .track/requests/*.json history stay in place. With a loopback track web server, GET /api/requests and GET /api/requests/<id> still read that history; add ?vault=<name> for a registered vault. These endpoints cannot send, retry, save, or apply requests. Interrupted updates remain recorded as they were and are never resumed automatically. Existing machine agents: settings are accepted but inactive; no credentials are removed or revoked.

Use the CLI from Codex or Claude for explicit note searches and edits. The Markdown viewer can display saved Markdown from an agent session without importing it into the vault.

Read Markdown outside the vault

Choose Markdown viewer in the navigation rail to open /markdown. Open Markdown files selects local .md or .markdown files; Open folder includes nested documents and their local images. Browser-selected files stay read-only in browser memory, with no upload, import, or indexing. Follow links within the selected source, then return to your vault without losing that selection during the page session. A full reload requires selecting the source again.

From Neovim, save the current Markdown file and run :Track markdown to open it directly. This starts or reuses a compatible loopback workspace and briefly transfers a read-only snapshot of the containing folder. No note is imported or indexed. Save and repeat the command to refresh.

See Markdown viewer for local links, rendering limits, refreshing disk edits, and browser support. This viewer is a live-workspace feature and is not included in the published static site.

Media embeds and diagrams

In a vault note, a Markdown image link on its own line becomes a rich block embed — YouTube players, Twitter/X posts, PDFs, image URLs, Open Graph link cards, and text-file attachments (including Mermaid diagrams). Fenced code blocks are syntax highlighted (with a copy button) and a mermaid fence renders inline. See Embeds for the full list and syntax, and Charts for .viewspec.json chart embeds.

Relationship to the static export

The static site produced by track export-site is the published counterpart of this workspace: rendered content only, with no editor, search index, or heatmap top page. It reuses the same Markdown and Mermaid rendering so a published note reads the way it does here, while Linking notes explains how cross-note links are resolved against the published set.

Static apps

A vault can keep a browser app at apps/<name>/index.html. A link to /apps/<name>/ or apps/<name>/ opens it as a top-level HTML page on a separate listener, not as a note embed. A link from a note in a registered vault opens that vault's app; a direct app URL defaults to the workspace launch vault. The app listener uses the workspace port plus one, and startup fails if that adjacent port is unavailable. See Static apps for setup, multi-vault behavior, trust boundaries, and publishing. For HTML displayed inside a note, see Embeds.

Searching from the workspace

The workspace search box runs the same unscoped search as the CLI as you type: title and #tag matches appear first, followed by full-text matches from note bodies in a separate Full text group. Body matches are ranked by relevance and include code-block and CJK matches. Use track search --scope body when you want body-only results from the CLI; the workspace already combines both scopes. See Searching notes for the query rules it shares.

Find and navigation in the macOS app

Track.app uses Track's white t on a dark rounded square in Finder, the Dock, and the Cmd+Tab app switcher. This app icon stays the same when you change the workspace's light/dark theme. Build and open the .app bundle to see it; running the standalone executable is not an icon check.

In Track.app, Cmd+F opens a compact in-page Find panel below the tabs. Opening or closing it keeps the tab bar and reading viewport in place. Type a word or Japanese text from the rendered note: every match receives a soft highlight, and the current match uses the workspace's accent color. The counter shows the current match and total. Cmd+G or Enter moves to the next match; Shift+Cmd+G or Shift+Enter moves to the previous one, wrapping at either end and scrolling the current match into view. Escape or Done closes the panel and removes the highlights; clearing the query also removes them. Ordinary text selections and links remain intact.

Find is literal and case-insensitive, not a regular-expression search. It searches rendered text in the current reader, including text split by inline formatting and line breaks, and refreshes when you navigate or rendered content changes. Hidden text, editor drafts, embedded pages, images, and diagram canvases are excluded. The workspace search above searches across notes. On older WebKit versions without CSS Highlights (before Safari 17.2), Find retains its previous single-match selection behavior without the all-match counter.

Selecting a Contents heading moves within the current note without discarding edits or asking whether to leave. Moving away from an unchanged note also does not show an unsaved-edits warning. For edits to the note body, navigation that replaces the page (including Reload) still asks before discarding the draft. Cancel keeps the draft. Save first if you want to retain it; a failed save or a save still in progress does not count as saved. Uncommitted input from an input method is protected as well.

Window Close, Cmd+Q, and a macOS request to quit also check the current workspace. Unchanged or successfully saved notes and an empty tab strip close without an unsaved-edits warning. If a note has unsaved changes, choose Cancel to keep editing and Save before quitting, or Continue to discard them. Pending or failed saves and uncommitted input-method text remain protected. The app keeps the window open until its own local server has stopped.

In Track.app, Cmd+W (File → Close Tab) closes the current tab. Closing the last tab leaves the workspace open; press Cmd+Q (Quit Track) to exit the application. Unsaved note edits, pending saves, and input-method composition ask before closing a tab. Cancel keeps both the tab and its draft; unchanged and successfully saved notes close without a warning.

The mouse Back and Forward side buttons select the previous and next open tabs, including tabs in the overflow menu and Graph, Calendar, and Markdown viewer tabs. The ends wrap. Repeated presses follow the order at the start of the sequence even though the selected tab moves to the front. Clicking or opening/closing a tab starts a fresh order. Switching away from an unsaved note uses the same discard confirmation. These buttons switch tabs inside Track.app; the View → Back and View → Forward menu commands and trackpad history gestures retain their page navigation. Mouse software must send the standard side-button events (buttons 4 and 5), rather than remapping them to other shortcuts. Browser workspaces and published sites retain their existing controls.

For pages whose editing state Track cannot inspect, including static apps, voice input, focused embedded pages, and open dialogs, the app keeps its conservative warning. A failed or unresponsive state check also asks before discarding anything; it never treats a timeout as a successful save.

Reading keys in the macOS app

In Track.app, click ordinary text or an empty margin in a note's Preview view, or use normal keyboard focus navigation to reach the Note reading area. While that reading area has focus:

• j scrolls down and k scrolls up, three lines at a time. Holding either key keeps scrolling.
• Tab opens the next note tab; Shift+Tab opens the previous one. The ends wrap. Hidden note tabs in the overflow menu participate too; Graph, Calendar, and Markdown viewer tabs are skipped.
• Escape releases the reading keys. The next Tab or Shift+Tab moves keyboard focus normally, so links, controls, and the navigation rail remain reachable. Click the reading text or return focus to the reading area to enable the keys again.

Closing workspace search with Escape or choosing a result returns focus to the note Preview so you can keep scrolling without another click. Closing the native in-page Find bar with Escape or Done also resumes reading after removing its match highlights. An input, editable control, or open dialog that still owns focus keeps it; dismissing search opened from a text field returns to that field instead. Choosing a result resumes reading. Edit and Split mode do not acquire reading focus.

The first Tab uses the current tab-strip order. Continuing with Tab or Shift+Tab follows that same order even though the selected tab moves to the front of the strip. Clicking, leaving and returning focus, opening/closing a tab, or navigating another way starts a fresh order. Holding Tab does not rapidly switch tabs. With fewer than two note tabs, Tab keeps its normal focus behavior.

These keys apply only to note Preview mode in the macOS app. Edit and Split mode, text fields, editable content, links, buttons, embedded pages, search, open menus, dialogs, and input-method composition keep their existing keys. Selected text and its copy controls keep normal keyboard behavior; selecting text does not move focus. The native Find field keeps its text input and focus navigation. Ordinary browser workspaces and published sites are unchanged. A configured home note can be scrolled, but does not become an open note tab just by using these keys.

If a preview still contains unsaved edits, switching notes uses the existing discard confirmation; Cancel keeps the draft and current tab. Save first to retain the edits. Key customization through a configuration file is not available yet.

Editing draw.io diagrams

In Preview or Split, select Edit draw.io diagram above a drawio diagram, then Open online editor. This opens the official editor at https://embed.diagrams.net. It requires internet access and passes the selected diagram's XML to third-party code from diagrams.net. Track does not send the rest of the note. Do not open confidential diagrams in the online editor unless you accept that boundary. Reading diagrams still uses the bundled local viewer.

The open editor uses about 90% of the window's width and height and follows window resizing. In short windows, scroll the dialog to reach all controls. Drag shapes, connection endpoints, and edge waypoints in the editor to refine an architecture figure. Select Apply to draft, or Save inside the online editor, to return the full XML to the note. Track switches to Split so you can inspect the source and preview, then select Track's Save to persist it. Apply alone does not save the note. A failed or conflicting Track Save keeps the draft; resolve the disk conflict before saving again.

Cancel, Close, or Escape closes the diagram editor. After the online editor has opened, Track asks before discarding the session, including when no change has been reported yet. Leaving the note, closing its tab, reloading, or quitting also protects unapplied diagram edits. Canceling a discard confirmation keeps the editor open. Apply or cancel before opening another diagram. Use the visible buttons when an iframe consumes a keyboard shortcut.

Only complete, unindented backtick drawio fences in the current note are editable. Attachments (including .drawio.svg and .drawio.png), included notes, query results, external Markdown files, and published pages stay read-only. Editing note text uses the existing source editor. If the preview belongs to an older draft, its editing buttons disappear until it catches up. If a draft changes during diagram editing, Apply is rejected; cancel and reopen the diagram. Disk updates do not replace a draft while its diagram editor is open.

The editor receives and returns the entire XML document, including compressed pages and layers. The inline viewer displays only the first page. Returned XML must be valid draw.io XML, no larger than 4 MiB of text, and cannot contain a line that would close its surrounding Markdown fence. Loading or Apply timeouts leave the draft unchanged; check connectivity, cancel, and reopen. The online editor is provided by diagrams.net and may change independently of Track. Its iframe cannot open popups, navigate Track, download files, or save directly to the vault. Diagram media and editor resources may use the network. Track's Apply/Save flow needs no new account or service.