Under the hood

`@outl/shared`: what the clients render

@outl/shared: what the clients render

Every component and view piece in the shared library, 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)
<MarkdownInline /> (refs/tags fire onRefClick/onTagClick; external [label](url) links fire the optional onLinkClick(href) — when wired, the link is a keyboard-operable button (role/tabindex/Enter+Space); when omitted it’s a plain inert <span>, no fake button. ((blk-X)) block-refs resolve their text from the embeds map when present — Roam-style inline reference, TODO/DONE marker prefixed — and fall back to the neutral handle chip when orphan; !((blk-X)) embeds still render the single-line ↳ text; ![alt](href) image tokens render an inline <img> for image extensions (a local assets/… asset resolved to a data: URL via readAssetDataUrl; a remote src used directly, but only when isSafeHttpUrl passes so a file:/data:/javascript: href from synced/imported markdown is refused and shown as a chip instead of hit as an image src) and a clickable file chip for pdf / other kinds that fires onLinkClick(href) so the client opens it in the OS viewer; blockAssets decides whether an asset may take a block of its own: it defaults to variant !== "inline", so compact inline contexts (backlinks, embedded subtrees, breadcrumbs) render every asset as an inline-sized chip instead of a block image, issue #203, and the desktop’s main BlockRow opts back in with variant="inline" blockAssets, issue #322)@outl/shared/markdownoutput of outl_md::tokenize_owned
<MarkdownTable table variant? onEdit? /> — a block whose whole text is a markdown table, as an HTML <table>. Per-column alignment from table.aligns ("none" renders left; the on-disk delimiter is what preserves the distinction), cells through <MarkdownInline /> so a [[ref]] / **bold** inside one renders as it does anywhere else, and an overflow-x-auto wrapper so a wide grid scrolls inside the block instead of stretching the outline. onEdit drops the host into its raw-markdown editor on tap — there are no cell editors, by design (#329); omitting it leaves the grid inert for read-only contexts. No parsing here: the backend decided the cells@outl/shared/markdownoutput of outl_md::tokenize_table (BlockNode.table)
<EmbeddedSubtree nodes= embeds? pageEmbeds? depth? /> — read-only render of transcluded rows, marked by one continuous rail down the left of the region (accent at 25%, drawn only by the outermost call) and stepped at the product’s own 22px per level. TODO/DONE markers, nested refs/embeds via embeds, nested ![[page]] titles via pageEmbeds, depth-capped at 4. Both kinds of embed expand through it — a !((blk-X)) block embed’s children and a ![[page]] page embed’s top-level blocks — because they are the same promise (“these rows live somewhere else”) and a second component would let the two drift. Display-only, no onClick/edit/nav — the client wires the expansion under the carrying block. MAX_DEPTH here is one of three copies of the cap (the TUI’s EMBED_MAX_DEPTH, the backend’s EMBED_SUBTREE_MAX_DEPTH); do not add a fourth@outl/shared/markdownsemantics mirror outl-tui’s emit_embedded_children (view/embed.rs) and the cap is shared; the glyph is not, deliberately — see outl-frontend-shared/CLAUDE.md → The transclusion rail
EmbedMap (Record<handle, ResolvedBlock>) — resolved refs/embeds keyed by handle, consumed by <MarkdownInline embeds= /> and <EmbeddedSubtree embeds= />@outl/shared/markdownreply shape of resolveEmbeds
PageEmbedMap (Record<name, PageEmbedContent>) + <PageEmbedTitle name content? onOpenPage? /> — the ![[page]] twin. Keyed by the name as written in the token, never by slug: the renderer holds token.value and nothing else. An absent key covers both “no such page” and “the resolve has not answered yet”, and both render the literal ![[name]] — a page embed is never blank, because the user wrote that name. The resolved line carries the same dim ↳ the TUI’s chip and the expanded rows below it do, so all three clients say “this content lives elsewhere” the same way. Following it goes through the same onRefClick a [[ref]] uses (a page embed is a page reference, so a second handler would be a second answer to one question). Both states are a plain inline <span>: they swap after the first paint inside the block the user may be typing in, so an atomic inline box (inline-flex, an icon, block) would change the carrying line’s height when a resolve lands and push every row below the caret — the component’s own doc owns that reasoning, and PageEmbed.test.tsx pins the shape@outl/shared/markdownreply shape of resolvePageEmbeds; token outl_md::InlineToken::PageEmbed
<CrumbTrail crumbs=… /> + crumbTrailText(crumbs) — a backlink’s ancestor breadcrumb. The barrel carries only those two; CRUMB_SEPARATOR and the TrailCrumb prop type stay module-level, imported from ./CrumbTrail by the test alone (the lock.ts rule). Rendered, not drawn as source: a crumb carries its own tokens, so a trail reads #alinhamento buser/team/vendas internet 0800 email instead of the markup around those names — the one line on the panel saying where a reference lives was the one line written in markup, with a URL eating a row that truncates to a single line. Dimmed is the caller’s styling rule and composes with the token colours underneath; the component is inert (no onRefClick / onTagClick / onLinkClick), because the backlink row already has one destination and two tap targets in one line overlap on a phone. variant="inline" also keeps blockAssets false, so an image in an ancestor is a chip. crumbTrailText is the plain reading a title= tooltip can hold. The prop is structural ({ text, tokens }), mirroring sameCrumbTrail, which is generic over { id } for the same reason@outl/shared/markdownoutl_actions::BacklinkCrumb; the TUI’s view::backlinks::render_crumb_trail is the terminal twin, and CRUMB_SEPARATOR is the › all three draw
splitQuote, isQuote, QUOTE_PREFIX, stripQuoteFromTokens@outl/shared/markdown (re-exported)outl_actions::quote::{split_quote, is_quote, QUOTE_PREFIX}
<QuoteWrap />, isBlockQuoted@outl/shared/markdownWraps a quoted block’s body in blockquote chrome (left border + faint tint), while each client keeps its outline bullet outside. Each client passes its theme tokens via baseClass + chromeClass props (Tailwind string literals for JIT discovery).
isAssetLink(url) — true when a [label](url) link points at a workspace asset (assets/…, ./assets/…, /assets/…; any :// scheme rejected). Every client’s handleLinkClick routes an asset link to openAsset (OS default app) and everything else to openExternalUrl@outl/shared/linksmirror of outl_md::asset::is_asset_link
isImagePath(href) → boolean (extension classifier — strips ?/#, matches the last .-segment; drives whether <MarkdownInline />’s image token renders an <img> or a click-to-open file chip) + assetFileName(href) (last non-empty path segment, for the chip label) + isSafeHttpUrl(href) → boolean (http/https only; gates whether a remote image href is loaded directly as <img src> or refused to a chip, since the href comes from synced/imported markdown)@outl/shared/linksisImagePath mirrors IMAGE_EXTENSIONS in crates/outl-md/src/wikilink.rs (is_image_target) — keep the extension list in sync
paletteResults({ query, pages, blocks, actions, limits? }) → { items, hidden }, sectionOf, DEFAULT_LIMITS (8 pages / 5 tasks / 6 blocks / 5 actions), COMMAND_PREFIX, BLOCK_QUERY_MIN, PaletteItem<C>, PaletteActionRow<C>. What a search box lists and in what order: pages, then tasks (via taskState), then blocks (from 2 characters), then actions matched on label plus keywords; a leading > narrows to actions; hidden counts what each limit dropped. Chord-aware action rows (paletteActions) stay in outl-desktop because the phone has no chords@outl/shared/palettenone (presentation ordering only; pages and block hits come from search_pages / search_blocks)
<BlockProperties /> — a block’s or page’s key:: value properties as one attribute line under the text, and attributeFields(properties, limit) as the pure policy under it. A pill is a tag — a flat label you tap to filter — so drawing a field as one promised an action the tap did not perform, and two different things read as the same thing. This is the shape every mobile app gives an item’s fields (Things, Linear, Apple Reminders, GitHub mobile): key in fg_dimmer, value in fg_dim, · between, one line, truncated. Colour is spent only on a field that acts on the user — LIVE_KEYS is {remind} today, and the criterion is interruption, not importance, which is why auto-run executes code and still renders quiet. A live field sorts first (the backend sorts alphabetically, so remind fell outside the capped line), shows its value without the key (the icon says what it is), and takes an SVG from @outl/shared/icons rather than the ⏰ the TUI draws, because DESIGN.md keeps emoji out of GUI chrome. Past limit fields the rest is +N more. There is no inline editor: the whole line is one tap target that calls onOpen, and editing lives in the client’s properties sheet, where a row that looks like a form row opens a form. propertyChips is still the filter underneath — isInternalKey hides outl’s own model state (id, from-template, collapsed) everywhere, and isImportStamp(key, value) hides an importer’s leftovers from a render only, so a property editor still lists one and can delete it. The type scale rides rowClass, never a class on the inner <button>: mobile’s styles.css carries an unlayered button, input, textarea { font-size: inherit }, which outranks every @layer utilities rule. One deliberate token divergence, recorded in docs/theming.md: the value uses fg_dim, not the dedicated property_value_fg, which the brand sets to accent_soft so the TUI paints every value lavender@outl/shared/markdownisImportStamp mirrors outl_actions::property::is_import_stamp; the glyph table still mirrors outl-tui’s property_glyph — a const can’t cross the Rust/TS boundary, so each pair is edited together
bootMark(mark) / BOOT_MARKS / waitWorkspaceReady(timeoutMs?) / BOOT_STYLE_KEY + cacheBootStyle / cachedBootStyle — the launch itself. bootMark is fire and forget and never awaited: a measurement that can delay the thing it measures is worse than no measurement, and its rejection is swallowed so a client built before the command existed does not print one per launch. first_content also releases the backend’s deferred boot work, so it is the one mark a client must not skip. waitWorkspaceReady resolving false means not yet and is not a failure; a rejection is. The style cache is what the inline <head> script replays before the first pixel@outl/shared/bootoutl_tauri_shared::commands::boot (BOOT_MARKS is a declared mirror, pinned by that crate’s tests/boot_marks.rs — a &[&str] has no serialized shape, so wire_mirrors.rs cannot hold it)
onPagePreview(handler) / <PreviewOutline outline= /> — the page-first boot’s client half. The backend reads today’s journal .md and its sidecar before it opens the op log (0.6-1.3 ms on a real 730k-op workspace, against 163 ms of snapshot boot plus the index load) and emits it; this is what a client paints instead of a spinner or a skeleton. <PreviewOutline /> is a second outline renderer with no interaction in it at all, and that is the design: the clients’ real outlines are not separable from editing, and threading a “nothing works yet” flag through every mutation callback is wrong in exactly one direction. A renderer with nothing to make editable cannot drift into being editable, which is why the payload is a plain PageView and carries no “do not edit me” flag: a flag is a second, weaker statement of the same thing, and one a client can ignore@outl/shared/bootoutl_tauri_shared::page_preview’s page-preview event
paletteDeclarations(palette) → the <html> inline declarations a palette installs, as a CSS string. Pure, and it is the boot cache: the inline <head> script assigns this exact string, which is what paints the user’s own palette on the first frame instead of the brand default. Built explicitly rather than read back off root.style.cssText, which would also capture a client’s own <html> values (--outl-notice-offset) and replay a stale copy of them next launch. applyPaletteToRoot applies it, merges it over whatever the theme does not own, and is the only writer of the cache — beside the only writer of the tokens, so the two cannot disagree@outl/shared/themethe Palette the backend’s get_theme resolves
<ParseWarningsBanner /> + @outl/shared/warnings/styles CSS@outl/shared/warningsTUI view::warnings_banner (visual parity, neutral chrome). Clients must @import "@outl/shared/warnings/styles" from their root stylesheet — without it the banner renders with unstyled neutral classes and looks invisible against the page.
<PageAheadOfLogBanner info= client= /> + aheadOfLogNotice(info, client) + RECONCILE_COMMAND. Rendered above the outline when PageView.md_ahead_of_log is present: the page has stopped syncing because its .md holds lines the op log never recorded, so outl refuses to overwrite the file (root CLAUDE.md invariant 8). aheadOfLogNotice is the pure copy owner and is what’s unit-tested — the wording is the deliverable here, not the markup, and it must say the same thing on both clients. client changes exactly one sentence: the desktop user gets the command to run in the workspace folder, the mobile user gets “open this workspace on your computer”, because iOS ships no outl binary and a button that can’t work would be worse than saying so. Not dismissable — the condition doesn’t clear on its own. Each client keeps the notice across mutation replies (which never carry it) and drops it on the first reply with md_ahead_of_log_checked and no notice, so the banner can’t outlive the reconcile that fixed the page@outl/shared/warnings (+ @outl/shared/warnings/styles CSS)outl_tauri_shared::state::MdAheadOfLog, produced by helpers::reproject_stale_md; the recovery is outl reconcile --ahead-of-log
<PairingQR ticket=… /> (renders a pairing ticket as a scannable QR; owns its own async encoding via ticketToSvg, no invoke inside — host passes the ticket from peerPairHost()) + <PeerList peers=… statusByNodeId? onRemove? /> (pure list of paired devices with online/offline/unknown status dot + optional remove button; all data + callbacks via props, no invoke) + ticketToSvg (pure ticket → SVG string, wraps the qrcode npm dep) + peersOnline(statuses) (pure: true when any peer has online === true; accepts the PeerStatusDto[] from peerStatus() or the desktop’s Map<node_id, …>; both clients derive the sync dot from it identically)@outl/shared/peers (+ @outl/shared/peers/styles CSS baseline)the outl_peer_* commands in each client’s commands/peers.rs (wrappers in @outl/shared/api/commands; outl_sync_iroh::PeerEntry/PeerStatus)
syncState({ syncing, peers, deviceOnline? }) → "checking" | "online" | "offline" | "syncing", plus syncStateLabel (the sentence), syncStateColor (the palette token), SYNC_STATES, peersAfterFailedProbe(previous) and <SyncDot state= /> (the dot / spinner itself). The one owner of what a sync indicator shows, on every client. peersOnline was shared and the state built on it was not, so the desktop and mobile each derived their own and had already drifted on the case nobody looks at: the desktop started at null (a dim “checking” dot) and mobile at false, so a phone reported “offline” over a probe that had not answered yet, and a failed probe meant “read offline” on one client and “keep the last value” on the other (#575). peers: null is the absence of a measurement and [] is one, which is why they are not collapsed. The dot announces the state and the client’s button announces the action — <SyncDot> is an aria-live region (iOS WKWebView renders no title= tooltip at all, so a colour-blind user would otherwise get a grey dot and nothing else), so a wrapping control that also names the state is read out twice on every change@outl/shared/peersthe reachability comes from peer_status over outl_sync_iroh’s peer_health(), which records both directions: the dials this device made and the inbound exchanges it confirmed
createSyncProgress() → SyncProgressState { current, feed, clear } (subscribes to the sync-progress Tauri event, resolves received-ops block ids to page/journal slugs via resolvePageLabels) + <SyncProgressView current= feed= peers= /> (pure: phase pill + snapshot-% bar / live ops count + “device → page” activity feed; no invoke inside, host wires createSyncProgress() and passes the signals down) + SyncFeedEntry / SyncProgressState types. Both DevicesSheet (mobile) and SyncPanel (desktop) render this one implementation on the pairing screen@outl/shared/peers (+ @outl/shared/peers/styles CSS baseline)outl_actions::SyncProgress, bridged to the sync-progress event by outl-tauri-shared::iroh_sync::start_with_reload_bridge
CRASH_REPORTS_SETTING (title + body for the Privacy section’s crash-reporting toggle, RFC 0377) + CRASH_REPORTS_NOTICE (body + dismiss label for the first-run strip, rendered by <CrashReportsNotice /> in @outl/shared/polish) + getTelemetryEnabled / setTelemetryEnabled. Reporting is on by default, so the copy is the disclosure the opt-out rests on, and the same claim goes to Apple and Google — a client that phrases it itself is how one of those becomes false. onboarding.test.ts asserts on the promises (notes are never sent; the named exclusions), never the sentences, and polish/parity.test.ts pins that neither client inlines them. The two bodies are not interchangeable: Settings answers on demand and carries the full field list, the strip arrives uninvited and has to read in a glance, so it points at Settings instead of repeating it (a test keeps it the shorter of the two). The wrappers are their own file because commands.ts sits at its size ratchet, same reason as trust.ts; both commands carry a bare bool, so there is no wire DTO to pin@outl/shared/onboarding + @outl/shared/api/telemetryoutl_tauri_shared::commands::telemetry; the flag is outl_config’s [telemetry] enabled
First-run onboarding copy (STORAGE_STEP, SYNC_STEP, FINISH_CTA) — plain as const data, no invoke / no JSX; the only piece of onboarding that’s identical between clients (the honest, no-account “where do your notes live” + “sync is peer-to-peer, one device is fine” wording). The chrome is client-specific (mobile: full-screen bottom-sheet-styled Onboarding.tsx + haptics; desktop: Onboarding.tsx wrapping <WorkspacePicker /> + <SyncPanel />).@outl/shared/onboardingno Rust mirror — UI copy. The storage facts it tracks live in outl-mobile/src-tauri/workspace_picker.rs / outl-desktop workspace commands
Mobile keyboard-toolbar logic — ToolbarAction catalog + TOOLBAR_META (label + symbol/text style) + DEFAULT_ORDER + PINNED_FIRST/PINNED_LAST + MIDDLE_ORDER (the catalog minus the pinned slots — everything that reorders the bar permutes exactly this set, so both MFU and the lock read it instead of re-deriving the filter), plus the MFU ordering (orderedMiddleActions(counts) pure; recordToStore/readCountsFromStore/orderedMiddleFromStore/clearCountsInStore over localStorage under outl.toolbar.mfu.v1). The action string ids are the wire contract the iOS native bar ships via window.__outlToolbar(action); kept byte-identical to OutlKit/Toolbar/ToolbarAction.swift (rename on both sides in one commit). Rendering (icons, capsule, keyboard docking) is client chrome, NOT here@outl/shared/toolbarport of OutlKit/Toolbar/{ToolbarAction,ToolbarMFU}.swift (the iOS native bar keeps its Swift copy because it renders before the webview)
Toolbar order lock — the user’s opt-out from MFU reordering (#271). The barrel exports only what a client calls: resolveMiddleFromStore() (lay the row out), lockOrderInStore / unlockOrderInStore / isOrderLocked. The pure internals (reconcileLockedOrder, parseLockedOrder, resolveMiddleOrder, LOCK_STORAGE_KEY) stay module-level exports that only the tests import from ./lock. A lock stores an order, not a boolean: counting keeps running while locked, so a flag alone would let the row jump on the next unlock or tiebreak change. reconcileLockedOrder is what keeps a snapshot honest as the catalog moves — unknown ids and the pinned slots dropped, actions the snapshot never saw appended at the end (appended, not inserted, because the user locked the row to stop things moving). Stored under outl.toolbar.lock.v1@outl/shared/toolbarOutlKit/Toolbar/ToolbarLock.swift. Neither this nor the MFU counts is a per-bar store: the settings sheet that writes them is web on iOS too, so localStorage is the single home and OutlToolbar.swift reads it (and the counts) out of the webview via evaluateJavaScript, through OutlKit.ToolbarStore. Both LOCK_STORAGE_KEY and MFU_STORAGE_KEY are pinned on both sides — keys.test.ts here, ToolbarStoreTests in Swift
<PageGlyph icon? kind? /> + the chrome line icons (SearchIcon, CalendarIcon, …) — PageGlyph is the one owner of a page’s icon: its own icon:: when set, else the calendar (journal) or page line icon. SVGs stroke in currentColor, so they take the palette token of the text beside them; no emoji in chrome@outl/shared/iconsno Rust mirror; icon:: is read from PageMeta.icon
Polish: createFocusMode / focusMode() (device-local focus mode, mirrored as data-outl-focus on <html>, persisted in localStorage), createSettle(busy, ms?) (true for one beat after busy goes true to false: drives the sync dot pulse and the unfold slide, never fires on first paint), firstRunTips(client) + <FirstRunTips /> + isBlankOutline (the 30-second tour on empty and blank pages; dismissal is per device), <CrashReportsNotice /> (the crash-reporting strip, RFC 0377 §6 surface 1 — the only disclosure that arrives uninvited, so reporting being on by default rests on it; mounted at each client’s shell (AppShell.tsx / App.tsx), not above the outline, because it is about the app and not about the page, and fixed + pointer-events: none on the wrapper so it cannot take focus or swallow a click; its words come from CRASH_REPORTS_NOTICE and it never gates the reporter), dismissedOnce(key) / dismissOnce(key) (the one “show it once, then remember” pair over localStorage, keyed per surface — TIPS_KEY, CRASH_NOTICE_KEY, CHROME_TOUR_KEY (a client’s walkthrough of its own chrome, whose rows stay in that client because they name its own controls — the mechanism is shared, the copy is not); a failed write means show it once more, never throw), contrastRatio (WCAG; polish.test.ts pins body fg at 4.5:1 on all ten presets). Styles in @outl/shared/polish/styles: every animation is opacity/transform only, under 200ms (the settle pulse is 420ms, once), and off under prefers-reduced-motion. Focus mode fades chrome marked outl-focus-hide to 0.18 instead of hiding it, because touch has no hover and the way out lives in that chrome@outl/shared/polishno Rust mirror; view state never leaves the device (UX.md principle 5)
<DiagramFence /> + chooseFence + diagramsMode / setDiagramsMode. Fence priority is one function: plugin transformer, then Pele for a mermaid fence when editor.diagrams is pele, else highlighted source. Pele loads through import("pele/lazy") so it is its own chunk. Styles: @outl/shared/diagram/styles, which maps --pele-* onto --color-outl-*. Clients must import that stylesheet.@outl/shared/diagram[editor] diagrams in outl-config (DiagramsMode)