Under the hood

`@outl/shared`: the wire DTOs and the `invoke()` wrappers

@outl/shared: the wire DTOs and the invoke() wrappers

Every type the Rust backend serialises and every typed command wrapper a client calls, with the Rust source each one mirrors.

Moved out of crates/outl-frontend-shared/CLAUDE.md, which is loaded into the model’s context on every session in that crate. The catalog is reference: you look an entry up before writing a helper, you do not read it top to bottom. The decision rule for what may enter the library stayed in that file.

The surface is three pages, so grep all of them at once: grep -n 'symbol' docs/frontend-shared-*.md.

PageWhat it lists
frontend-shared-views.mdComponents and the view pieces both clients render
frontend-shared-wire.mdThe DTOs the Rust backend serialises, and the typed invoke() wrappers
frontend-shared-logic.mdPure helpers: paste, autocomplete, outline walks, journal math, caret navigation
ConceptEntryMirrors (Rust)
formatNextFire(iso, now?) → "now" / "in 20min" / "in 3h" / "tomorrow 09:00" / "Dec 15, 10:00", and groupReminders(list, now?) → Today / Tomorrow / This week / Later / Done (empty buckets dropped). Both GUI clients render the same column and the same section headers; two implementations drift on the edge cases (exactly 60 minutes, midnight rollover, a finished rule) long before anyone notices@outl/shared/api/commandsNo Rust mirror — presentation only. The instants themselves come from outl_actions::reminders::next_fire_at, which is the single owner of when a reminder fires. Never re-derive a schedule in TS
RemindFields + parseRemindRule / formatRemindRule — a remind:: rule flattened into what a form binds to (anchor, clock, repeat, stop, cap), and the two commands that read and write the rule text around it. Declared in commands-reminders.ts beside its wrappers, the api/paste.ts arrangement, and re-exported from api/types.ts so the import path stays one. Neither the grammar nor the schedule is in TypeScript: the pair is outl_md::remind’s parse_remind / format_remind across the bridge, called twice per picker session rather than per keystroke, and a field set the grammar cannot express comes back as a rejection rather than a corrected rule. It exists because mobile’s “Remind me…” was a window.prompt for the grammar (#572); a picker without this pair would have meant a second reading of the rule language in a webview@outl/shared/api/commands + @outl/shared/api/typesoutl_tauri_shared::commands::reminders::RemindFieldsDto over outl_md::remind
Reminder / ReminderSettings DTOs. Times are ISO-8601 local strings with no zone suffix, deliberately: the backend resolved them in the user’s configured timezone (outl_actions::clock), and re-deriving a local time from an epoch in JS reintroduces exactly the bug that module exists to fix@outl/shared/api/typesoutl_tauri_shared::commands::reminders::{ReminderDto, ReminderSettingsDto}
backlinkRowOp(pageId, id, op) / createBacklinkSibling(pageId, id, side) + BacklinkRowOp / BacklinkSide — the nine non-text gestures on a backlink row, aimed at the citing block’s own page. Never the block.rs twin (toggleTodo, deleteBlock, indentBlock, createBlock, …): those act on the page the user is looking at and may therefore tolerate a stale block id, which a backlink’s routinely is — createBlock by appending at that page’s end, six by reporting a raw ActionError (a ULID), and moveBlockUp / moveBlockDown / indentBlock by answering success while doing nothing. A rejection is a message to show, never a Retry to pin, and its wording is outl_actions::refusal’s@outl/shared/api/commands (declared in api/backlinks.ts)outl_tauri_shared::commands::backlink_edit; both enums pinned in that crate’s wire_enums.rs
renamePage(page, newName) / mergePages(source, target) + RenamePageReply (renamed or a typed exists, never an error: nothing was written and the caller may offer a merge), MergePagesReply, the two reports and PropertyConflictView. Its own file for the ratchet reason trash.ts has. renameOrMerge(page, newName, confirmMerge) is the flow both clients run (rename; when the name is taken ask confirmMerge(existing) and merge on accept; a refusal writes nothing), mergeInto is the merge after a confirmation already happened, and mergeConfirmMessage / nameTakenMessage / renameSummary / mergeSummary own the wording so neither client words it. A merge is never reached without a confirmation and the UI has no undo for it. Nothing here decides what a merge does: that is outl_actions::merge_pages@outl/shared/api/page-merge + @outl/shared/pagesoutl_tauri_shared rename_page / merge_pages over outl_actions::{rename_page, merge_pages}
TrashEntry / RestoreTrashResult DTOs + listTrash / restoreTrashEntry. Its own file because commands.ts and types.ts are at their size ratchet, same reason as trust.ts. Nothing here decides what can be restored: refusal is outl_actions::trash::refusal_for’s own sentence per row, and restoreTrashEntry rejects with the identical string when the verdict changed under the listing — so a caller handles the rejection and re-lists rather than trusting the row it rendered@outl/shared/api/trashoutl_tauri_shared::commands::trash
PasteReply (view, host_text?, host_caret?) — reply of pasteMarkdown / pastePlain; host_caret is a codepoint offset@outl/shared/api/types (declared in api/paste.ts)outl_tauri_shared::state::PasteReply
TableView / ColumnAlign (DTO of BlockNode.table) — a table with every cell pre-tokenized, rectangular: aligns, header and every row carry one entry per column, padded by the backend, so a renderer emits <tr>s without counting. ColumnAlign has four members; reading "none" as left-aligned is the client’s choice, not knowing about "center" is a silently mis-rendered table@outl/shared/api/typesoutl_md::TableView / outl_md::ColumnAlign
ParseWarning / ParseWarningKind (DTO of PageView.warnings). ParseWarningKind has six members, in two families: unrecognized_block_marker (a line outside the outl dialect, kept verbatim) and five remind_* members (a remind:: rule the scheduler could not take at face value: the block is fine, the rule is malformed). The five shipped with the reminder parser, mirrored here only after outl-tauri-shared/tests/wire_enums.rs gained the ability to fail on a missing enum variant; a ParseWarning is therefore not always “a line outside the dialect”, and copy that says so is wrong for every remind_* kind@outl/shared/api/typesoutl_md::ParseWarning / ParseWarningKind
MdAheadOfLog (path, lines, sample) — DTO of PageView.md_ahead_of_log; PageView.md_ahead_of_log_checked rides alongside it and says whether this reply ran the check (only the open commands do), i.e. whether an absent notice means “healthy” or “unknown”@outl/shared/api/typesoutl_tauri_shared::state::MdAheadOfLog
DroppedEdit (block, kept_as?, message) — DTO of PageView.dropped_edit: the block the user was typing in had left the tree, so the keystroke did not land there. The backend keeps the text at the end of the page when it still can (kept_as) and admits it could not when the page went too. message is the only wording — the backend wrote it, and a client that phrases this itself is a second copy of the fact. Neither client renders it yet: the two files that would (OutlineView.tsx, Journal.tsx) sit exactly at their size baseline and are each being split by separate work, so the render is owed by those tasks. The field and its pin exist now so the reply is not lying about what happened (#473)@outl/shared/api/typesoutl_tauri_shared::state::DroppedEdit
PeerDto (node_id, alias, added_at) / PeerStatusDto (node_id, alias, online, rtt_ms)@outl/shared/api/typesRust PeerDto / PeerStatusDto in both clients’ commands/peers.rs
SyncProgress — tagged union by phase (connecting / snapshot / asset / received-ops / pushed-ops / synced / failed), every variant carries peer (short node id); snapshot + asset also carry byte received / total (progress bar)@outl/shared/api/typesoutl_actions::SyncProgress (#[serde(tag = "phase", rename_all = "kebab-case")])
DTOs (PageMeta, OutlineNode, BlockNode, Backlink — incl. ancestors: BacklinkCrumb[], the citing block’s root-first ancestor breadcrumb, page root excluded, empty at root level — InlineToken, PageView — incl. backlinks_order: BacklinksOrder, CreateBlockReply, WorkspaceSummary, …)@outl/shared/api/typesthe corresponding serde-serialised Rust structs
BacklinkCrumb { id, text, tokens } — one breadcrumb entry: the ancestor’s body with no TODO/DONE prefix, plus its inline tokens, since no client runs a tokenizer. <CrumbTrail /> renders it; text is what a title= tooltip reads. FocusCrumb is a near-twin and carries no tokens@outl/shared/api/typesoutl_actions::BacklinkCrumb
ResolvedBlock { handle, text, page_slug, status, children } — a block resolved from its ref handle; reply value of resolveEmbeds. ((…)) refs render text; !((…)) embeds render text + the children subtree. Declared in api/embeds.ts beside its wrapper, re-exported from api/types@outl/shared/api/typesRust EmbedContent
PageEmbedContent { slug, title, blocks } + resolvePageEmbeds(names) — the page embed ![[page]] (issue #190), the page-level twin of resolveEmbeds: a read-only expansion of the whole target page’s outline, capped at the same depth. Keyed by the name as written in the token, not by slug, because that is what the renderer holds; a name resolving to no page is absent from the map, exactly like an unresolvable ((blk-…)) handle. Lives beside ResolvedBlock in api/embeds.ts on purpose — the two are twins and a split between them is how one starts answering a question the other does not@outl/shared/api/types + @outl/shared/api/commandsoutl_tauri_shared::commands::exec::PageEmbedContent
BacklinksOrder ("newest" | "oldest")@outl/shared/api/typesoutl_config::BacklinksOrder
PageBacklinks (fields mirror the Rust struct) — reply of pageBacklinks(slug) / setBacklinksOrder(...); backlinks are fetched lazily, decoupled from PageView, so the O(blocks) scan never blocks first paint@outl/shared/api/typesoutl_tauri_shared::state::BacklinksReply
Plugin DTOs (PluginCommand, PluginToolbarButton, PluginRunReply, PluginSyncHooksReply, PluginTransformer, PluginTransformResult) + wrappers (pluginList, pluginRun, pluginSyncHooks, pluginToolbar, pluginTransformers, pluginTransform) — both clients register the identical plugin_* commands (thin shims over PluginService), so the wire shapes + wrappers live here once. The desktop-only chord surface (PluginKeybinding / pluginKeybindings) stays in outl-desktop/src/lib/api.ts (mobile has no keybindings)@outl/shared/api/types + @outl/shared/api/commandseach client’s src-tauri/src/commands/plugin.rs DTOs
invoke<T>() wrappers (navigation: listPages, searchPages, searchPersons, searchEmojis → EmojiHit[] (powers the :shortcode: autocomplete in every client; backed by outl_md::emoji::search so TUI / mobile / desktop rank identically), searchBlocks → BlockHit[] (powers the ((…)) block-ref autocomplete; backed by outl_md::WorkspaceIndex::search_block_text; caller inserts each hit’s handle wrapped in ((…)), never the display text), openTodayJournal, openJournalFor, openPageBySlug, openRef, previousDay, nextDay, todaySlug, dateTitle, resolveRef, workspaceStats; mutation: createBlock → CreateBlockReply (returns { view, new_id } so the client puts the new block straight into edit mode without diffing the outline), splitBlock(pageId, id, charOffset) → CreateBlockReply (splits a block at the caret — the text up to charOffset stays, the rest moves into a new sibling below, returned as new_id; charOffset is a codepoint offset, convert the textarea’s UTF-16 selectionStart with utf16OffsetToCharOffset first; mirrors outl_actions::split_block, backs the Enter-mid-text gesture on desktop + mobile, issue #184), editBlock, editBacklinkBlock(pageId, id, text) (the same edit through a backlink row, where pageId is the backlink’s source page; a second wrapper because the two differ in how they recover — editBlock keeps the text by appending it at the end of the page, which is right for the page you are reading and wrong for one you are not, so this one rejects a stale block id and a source page that has stopped syncing instead. A rejection is therefore a message to show, never a Retry to pin: nothing was written. The resolved PageView describes the source page, so apply it only when that page is the one on screen), toggleTodo, deleteBlock, indentBlock, outdentBlock, moveBlockUp, moveBlockDown, reloadWorkspace, pasteMarkdown, pastePlain(pageId, blockId, caret, text) (invokes paste_plain_at — paste without formatting: raw text as a single block, no normalisation or paragraph splitting), copyMarkdown (serialises a block selection + subtrees as clean outl markdown for the OS clipboard — the copy-out inverse of pasteMarkdown), setBlockCollapsed, deletePage(slug) → Promise<PageView> (delegates to the shared delete_page command; returns today’s-journal PageView so every caller navigates away from the deleted slug identically — desktop hover ×, desktop DeletePage action handler, and mobile long-press all call this one wrapper), pageBacklinks(slug) → Promise<PageBacklinks> (the lazy backlinks fetch every client fires after the outline paints — backlinks moved off PageView because backlinks_for_page is an O(blocks) scan that blocked the first journal paint; PageView.backlinks now always comes back empty, mirroring the TUI’s lazy/cached panel), setBacklinksOrder(order, slug) → Promise<PageBacklinks> (delegates to set_backlinks_order; persists [display] backlinks_order and returns the re-sorted PageBacklinks — the desktop InlineBacklinks and mobile BacklinksSection header buttons both call this one wrapper, issue #142); block clipboard / pin (RFC 0254 phase 4b): cutBlock(pageId, id) → Promise<CutBlockReply> (renders the block + subtree to markdown, moves it to trash, and returns both — the markdown feeds the same block-clipboard signal pasteBlockAfter reads, so cut-then-paste round-trips without reintroducing a second clipboard shape), copyBlockRef(id) → Promise<string> (the block’s ((blk-XXXXXX)) ref handle, issue #18 — reads the handle the workspace index already assigned rather than deriving one, so a collision-expanded handle can’t disagree), togglePin(pageId) → Promise<PageView> (flips pinned:: true; refuses journal pages); execution: runCodeBlock → RunCodeBlockReply (refreshed PageView + stdout/stderr/exit so the caller swaps the outline in one round-trip); peers/pairing: peerList → PeerDto[], peerRemove(id) → bool (prefix match), peerStatus(withPending?) → PeerStatusDto[] (reachability is an in-memory read of the transport’s own dials; withPending defaults to false because pending_ops is the only field that counts the op log, and only the Sync panel renders it — root CLAUDE.md invariant 15), peerPairHost(alias?) → string (ticket; completion surfaces via the backend peer-paired event — desktop’s Rust command is being aligned to the mobile ticket-return shape), peerPairJoin(ticket, alias?) → PeerDto, syncNow() → void (force an immediate iroh sync pass against every peer — pull-to-refresh / Refresh; no-op when iroh isn’t wired), resolvePageLabels(nodeIds) → Promise<string[]> (batch-resolves block ids to their distinct page/journal slugs; the createSyncProgress feed’s only round-trip, best-effort — an id not yet materialized on this device is skipped); external links: openExternalUrl(href) (opens http(s)/mailto in the system browser via tauri-plugin-opener; rejects other schemes — the host must register the opener plugin + grant opener:allow-open-url); assets: openAsset(url) → Promise<void> (opens an assets/… uploaded file in the OS default app via the open_asset command — outl does not render it; rejects when the asset hasn’t synced to this device yet), readAssetDataUrl(url) → Promise<string> (resolves an assets/… link to a data:<mime>;base64,… URL the webview loads inline via the read_asset_data_url command — the image-render path; size-capped backend-side, rejects when the asset hasn’t synced yet), attachAsset(sourcePath, pageId, afterBlockId?) → Promise<PageView> (imports a file via the attach_asset command — content-addressed copy into <root>/assets/, size-capped — and attaches its markdown link as a new block after afterBlockId or at the page end; both clients drive it from a @tauri-apps/plugin-dialog file picker), and importAssetFile(sourcePath) → Promise<ImportedAsset> (imports via import_asset_file — same content-addressed copy, but creates no block; returns { rel_path, display_name, is_image, markdown } so the caller splices markdown straight into the drop target — the drag-and-drop path, see below))@outl/shared/api/commandsthe matching Tauri command in each client’s src-tauri/src/lib.rs (openExternalUrl wraps the @tauri-apps/plugin-opener JS API, not a custom command)
openExternalFile(sourcePath) → Promise<PageView> — the OS “Open With → outl” import (open_external_file). Lands the file as a page under the open-in/ title namespace; a path already imported navigates to the page it produced rather than importing a second copy. Every policy question (namespace, the source:: re-open rule, the extension / size / UTF-8 refusals) belongs to outl_actions::open_with — this is a wrapper, nothing more. Only the desktop has an OS association that delivers a path today (Capability::OpenExternalFile)@outl/shared/api/commandsoutl_tauri_shared::commands::open_with::open_external_file
ImportedAsset (rel_path, display_name, is_image, markdown) — reply of importAssetFile, mirror of outl_actions::ImportedAsset@outl/shared/api/commandsoutl_actions::ImportedAsset