Omniscio

Peek viewer (look at a file without leaving what you were doing)

A slide-over panel that shows a file in place — text, code, images, video — so you can read or watch what an agent is talking about without opening an editor or losing your place. Covers opening one from a link or a path, finding text inside it, how it works on a phone, and how a path is resolved to the right copy of a file.

On this page

What it is

What it is — A side panel

A side panel (drawer on desktop, full-screen sheet on mobile) that previews a single file without leaving the chat. You open it by clicking a file path or image link that an agent printed in its message. Code files render with syntax highlighting; images render through the shared ImageCanvas (pinch-to-zoom on mobile, click-to-zoom on desktop); videos play in place.

For files whose extension maps to a renderable format, a Type toggle in the header flips between the raw source and a rendered preview. The peek viewer renders six formats through its shared PreviewRenderer: Markdown (.md / .mdx), SVG (.svg, sanitized markup), Mermaid diagrams (.mmd / .mermaid, lazy-loaded), LaTeX / KaTeX (.tex / .latex, sanitized HTML), and CSV / TSV tables (.csv / .tsv, the first 100 rows and 30 columns as plain text, saying when cut). Sound files (MP3, WAV, OGG, FLAC, M4A, AAC, Opus, up to 25 MB) open as a player that plays only when you press it, on the desktop app only. The toggle is hidden for any other extension. HTML is the deliberate exception: .html / .htm peeks render as raw code only, never through an iframe — the toggle is suppressed for them so the peek viewer's security posture is unchanged. (The sandboxed-iframe HTML render path lives in the separate File Explorer file viewer, not the peek overlay.)

Both heavy renderers load on demand, and neither may become a static import. KaTeX is ~280 KB and Mermaid ~1.6 MB, so PreviewRenderer reaches each with a dynamic import() only when a file of that format is actually previewed — a static top-level import would pull the whole library into the entry chunk for every user who never opens one. The Mermaid preview goes through the shared MermaidDiagram, which owns the dynamic import and runs the produced SVG through the same sanitizer.

A Mermaid preview shows a loading state, never the failure copy, while its first draw is in flight. PreviewRenderer passes the failure copy as MermaidDiagram's fallback and a shared Spinner as its loadingPlaceholder; MermaidDiagram reaches fallback only when a draw actually fails. Passing the failure copy alone made the peek viewer flash "Couldn't render this diagram preview." before the picture appeared.

PDFs are the other special case. A .pdf peek hands the whole body to Omniscio's built-in PDF viewer (paginated, zoom, selectable text, find, convert-to-text, Print — see media-link-open.md). A PDF has no raw view, so the header shows no Type toggle and no lines · chars · tokens line for it — those only make sense for text, and for a PDF they would describe its base64 encoding rather than the document. The header keeps the file name, path copy, Share / Send-to-agent and Close. PreviewRenderer still carries a pdf case that returns null: PDFs never reach it (the viewer takes the PDF branch itself), and the case exists only to keep the format switch exhaustive.

Video plays in the panel too. A .webm, .mp4, .m4v, .mov, .mkv, .avi or .ogv path opens a real player with play/pause, scrubbing, volume and fullscreen. It never autoplays and never starts with sound — you press play. The header keeps the file name, path copy, Share / Send-to-agent, Reveal and Close, and drops the Type toggle, the find bar and the lines · chars · tokens line, since a video has no text to search or count. On desktop the clip streams from disk through a peek-media:// link with no size limit — the player pulls only the bytes it needs and answers range requests, so scrubbing a long video jumps straight to that point instead of re-downloading it, and a multi-gigabyte file costs the app no more memory than a small one. On a phone the same clip streams over the /file route instead, which answers range requests the same way. A video on a remote computer keeps a 25 MB inline limit, because those bytes arrive over the connection rather than from a local file. A format the app's engine cannot decode — some .mov codecs, for instance — shows a clear message rather than a black box. Promises: the video preview contract.

The peek viewer also has sibling-image navigation. When you click an image link inside an agent message that contains multiple image links, those other images become "siblings" of the one you opened. You can flip through them in place — left/right arrow buttons flank the image, a small N / M counter sits at the bottom-center, and ArrowLeft / ArrowRight on the keyboard work too. On mobile you swipe left to advance and right to go back. Navigation wraps at edges, so the last image's "next" goes back to the first. When the agent message has only one image, the arrows, counter, and swipe handlers stay hidden entirely — the viewer behaves exactly like the pre-navigation peek viewer.

Where to find it

From a file link or path wherever it appears in the app — the peek opens as a slide-over on top of what you were already reading, so you close it and you are back. It opens in the window you clicked from, so a link in a popped-out session window, a project pop-out, the KMS window, the Writer window or a project-document window shows the file right there rather than nothing happening.

A link that is relative opens too, wherever you click it from a document rather than a session: it resolves the way markdown says it should, against the folder of the document that carries it — so [DECISIONS.md](DECISIONS.md) inside a project doc opens its neighbour, not something in the project root. And a link to a folder opens in the in-app file list only where that list exists (the main window); anywhere else it hands the folder to your computer's own file manager, which is where folder links already go for folders outside a project.

How it behaves

How to use it

  1. Open a chat session with an agent that produces file paths or image links in its replies (any provider).

  2. Click an image link in an agent message. The peek viewer slides in from the right (desktop) or up from the bottom (mobile) showing that image.

  3. If the same agent message has more image links, three things appear on top of the image:

    • Left chevron at the middle-left edge — previous image.
    • Right chevron at the middle-right edge — next image.
    • Position counter at the bottom-center, shaped like 2 / 5.

    The counter stays hidden when the message has only one image link.

  4. Navigate the siblings any of three ways:

    • Click the on-screen left / right chevron buttons.
    • Press ArrowLeft / ArrowRight on the keyboard. (No modifier — plain arrows. Holding Ctrl/Cmd/Alt/Shift falls through to OS / app shortcuts as normal.)
    • Swipe horizontally on the image area on mobile. Swipe left to advance to the next image, swipe right to go back. Vertical scrolls and pinch-to-zoom are unaffected.
  5. Wrap-around is automatic. The first image's "previous" jumps to the last; the last image's "next" jumps back to the first. There's no edge stop and no edge dimming — it's a circular ring.

  6. Close the viewer with the X button, the desktop backdrop click, the Android back gesture (mobile), or Escape on the keyboard. Sibling state is forgotten — opening a different image link starts a fresh sibling group.

What "sibling" means

A sibling is another image link in the same agent message bubble. The viewer walks the DOM up from the link you clicked to the nearest message-bubble container ([data-msg-summary]) and collects every other image link inside that bubble in document order. Image links in different messages are never siblings, even if they appear adjacent on screen. This matches what users intuitively expect: "show me the rest of the images this agent message mentioned."

Operator-uploaded images (the chips you attach in the composer) already had their own lightbox with its own arrow nav — that lightbox is unchanged. Sibling-image navigation lives only in the peek viewer that opens from agent-message links.

When navigation is suppressed

The arrow buttons, counter, keyboard handler, and swipe handler are all gated together so the viewer never gets caught in a half-state where one input works and another doesn't:

  • Single image. Hidden entirely (not greyed out / disabled). A one-image preview looks identical to the pre-Phase-7 peek viewer.
  • Editing the file. When you click the pencil icon to edit a text file's contents, arrow keys belong to the textarea (cursor movement). The keyboard handler yields. The arrow buttons + counter still show because images aren't editable, but in practice editing only applies to text files where there are no sibling controls anyway.
  • A confirmation dialog is open. If you have unsaved edits and hit "Discard?", the inner confirm dialog owns the keys until you answer.
  • Multi-touch / pinch. If you put a second finger down at the start of a touch, or add it mid-gesture, the swipe is aborted — pinch-to-zoom belongs to the ImageCanvas zoom engine, not nav. The next single-finger touch starts cleanly.
  • Zoomed in. While the image is zoomed past fit, sibling-swipe is suspended entirely — a one-finger drag pans the zoomed picture instead of flipping to the next image. ImageCanvas reports rest↔zoomed crossings via onZoomedChange, which clears swipeNavEnabled; it resets to fit (and re-enables swipe) on each key={filePath} remount.
  • Vertical drag dominance. A swipe must travel more than 50 pixels horizontally and more horizontally than vertically. A 50px-exact drag stays in the no-op band. This means scrolling the page on mobile (mostly vertical) doesn't accidentally flip images.
  • Modifier keys. Plain ArrowLeft / ArrowRight only. Ctrl+ArrowLeft, Shift+ArrowRight, etc. fall through to the OS / app — they're never intercepted.
  • Focus inside an <input>, <textarea>, or [contenteditable]. Arrow keys belong to the focused field for text editing; the peek handler yields.

Counter accessibility

The N / M counter at the bottom-center is wrapped in role="status" aria-live="polite" with aria-label="Image N of M". Screen readers will announce the new position when you flip to a sibling.

Find in the file (Ctrl+F)

When you're viewing a text or Markdown file (not an image or PDF), press Ctrl+F (Cmd+F on macOS) to open a browser-style find bar at the top-right of the content. Type to highlight every match with a "N of M" counter; Enter jumps to the next match and Shift+Enter to the previous one (or use the up/down chevrons), scrolling the active match into view. Esc or the ✕ closes the find bar and clears the highlights — and while it's open, Esc closes the find bar first, not the whole viewer.

Find works in both the raw view and the rendered Markdown preview, and it searches only the file that's currently open. It's a desktop feature (a phone has no Ctrl key) and is available while viewing, not while editing. When the peek viewer is open, its Ctrl+F takes priority — the Settings find bar never opens behind it. Under the hood it shares the same find engine as the Settings and in-session find, so highlighting and matching behave identically across the app.

Files from a session on another computer

When a session runs on another computer over SSH (picked with the Run chip — see ssh-remote.md), the paths its agent prints are paths on that computer. Clicking one opens that computer's file in the peek viewer, read-only:

  • What opens: text and code, Markdown, images and PDFs, with the same size limits as a file on this computer — long text is cut at 1 MB with the usual notice, and an image over 16 MB or a PDF over 25 MB is refused with a plain message.
  • Read-only: the header shows a small Remote · read-only tag, and there is no Edit, Publish, Export or Show in folder. Nothing is ever written to the remote computer.
  • A relative path (notes/plan.md) opens from the session's own folder on that computer.
  • Protected files never open: private keys, the .ssh and .gnupg folders, .env files, cloud-tool logins (AWS, Google Cloud, Azure, Kubernetes, Docker, DigitalOcean, the GitHub CLI), shell history, the system password and sudo files, live process data and Claude's own credentials and settings — also when a shortcut points at one. Any other file on that computer opens.
  • Folders, web pages and other files (an .html, a zip, an app) show "Only text, Markdown, images and PDFs open from a remote computer for now." rather than opening a same-named file on this computer.
  • Speed: each open makes one SSH connection, so it takes a few seconds when the computer is far away; the viewer shows it is loading. A computer that can't be reached shows a plain message within about half a minute.
  • It works from the phone too. Omniscio's own cloud sessions and Windows remote computers don't support it yet — the click says so.
  • It is a click in the app only — there is no command-line route for it, because an agent reads the files on its own computer directly.

Mobile loading + caching

On mobile / web (any browser context — no Electron preload) image bytes stream over the /file?path=...&token=... HTTP route on the Omniscio web server, not over the WebSocket IPC channel that desktop uses. Two things follow:

  • The spinner shows for the entire fetch. Until the underlying <img> reports complete, the peek body keeps isLoading = true. A semi-opaque LoadingPanel overlays the image area so you have continuous visual feedback during the download — multi-MB photos over a slow Tailscale link no longer look frozen. Once the image decodes, ImageCanvas fires its onLoadComplete callback and the store flips isLoading = false, which removes the spinner overlay. If the load fails (404, network drop, decode error), the same path fires onLoadError and you see the red error UI instead.
  • Sibling navigation reuses the browser cache. The /file route returns Cache-Control: private, max-age=300, must-revalidate plus a weak ETag (W/"<size>-<mtimeMs>") and a Last-Modified stamp. On every subsequent view the browser issues a conditional GET (If-None-Match or If-Modified-Since) and the server short-circuits to a bodyless 304 when the file hasn't changed. So flipping back-and-forth across siblings touches the network for headers only — the bytes come from the disk cache. First-pass nav still pays the network cost; the win is on the second visit per sibling and on every revisit during a single peek session.

If-None-Match takes precedence over If-Modified-Since (per RFC 7232 §6) when both headers arrive on the same request — so you don't need to worry about the two cache validators racing. The HTTP-date format only has 1-second resolution, so the server truncates mtimeMs to whole seconds before comparing it against If-Modified-Since to avoid spurious 200s on sub-second-modified files.

Stale-resolution guards prevent rapid sibling flicks from showing the wrong image: the store's openEpoch counter increments on every open and the IPC path discards in-flight resolutions whose epoch no longer matches; ImageCanvas's onLoad / onError callbacks pass the exact src they observed and the store ignores the call when state.content !== loadedSrc. So the previous image's late-firing onload after you've already navigated past it is a no-op — never a UI flicker.

Mobile text viewing + editing

On a phone the peek viewer is a full read-and-edit surface, not a read-only sheet:

  • Raw text wraps for prose. In Raw mode the file body wraps to the panel width (whitespace-pre-wrap + break-words) for markdown and plain text — any file with no detected highlight language — so long lines and long paths / URLs stay readable without sideways scrolling. This holds on both desktop and mobile. Code and data files (a detected highlight language other than markdown — .ts, .json, .yaml, .tex, …) keep horizontal scroll (overflow-x-auto) on desktop so indentation / alignment stays intact and you scroll to read, which the wider drawer affords; on a phone every file wraps (a small screen can't scroll sideways comfortably). The wrap-vs-scroll choice keys off the file's detected language (isMobile || !language || language === 'markdown'). The Type preview (Markdown / SVG / …) is unaffected; it already reflows.
  • Editing is available on mobile. The Edit pencil and the Save / Cancel controls show on phones, not just desktop. Saving goes through the same FILES_WRITE_ABSOLUTE path desktop uses, which already works over the mobile web route (e.g. a Tailscale tunnel). The editor textarea uses a 16px font on mobile (vs the denser desktop size) so iOS Safari doesn't auto-zoom the page when you tap into the field, and the pencil gets a larger tap target.
  • The Android back-gesture protects unsaved edits. Backing out of an in-progress edit with unsaved changes shows the same "Discard changes?" confirmation the X button and Escape use, instead of silently dropping the edit. The mobile back handler re-arms its history sentinel on "keep editing" so a later back still dismisses the viewer.

Editing stays gated to raw, non-truncated text files on every platform — a truncated file (>1 MB) stays view-only so a partial save can't overwrite the real file, and .html peeks stay raw-only for the iframe-security reason above.

Concurrent edits don't clobber each other. The two globally-editable docs (CLAUDE.md / MEMORY.md) are editable from desktop and a paired phone, so two surfaces can have the same file open at once. To stop one save from silently wiping the other's, the editor records the file's on-disk timestamp when it loads and echoes it back on Save; if the file changed on disk in between (the other surface saved first), the save is refused with "This file changed on disk since you opened it. Copy your edits, then reopen it to load the latest version." — your unsaved text stays in the editor so you can copy it and reopen the newest version. A first-ever save with no recorded timestamp still goes straight through.

Mobile crash recovery (stale-chunk reload)

FilePeekOverlay is React.lazy()-loaded — its module is fetched on first open. On a long-lived mobile tab, that fetch can fail after a desktop rebuild has replaced hashed chunk filenames: the tab is still running yesterday's entry chunk that references hash XYZ, but the server only has ABC now. Three layers cooperate so the user-facing tap "just works" without showing a loading state or perceived crash:

Layer 1 — boot-time chunk prefetch (primary)

Both bootstrap paths in App.tsx call prefetchFilePeekChunk() from mobile-prefetch.ts during requestIdleCallback (with setTimeout(200) fallback for Safari). This fire-and-forget dynamic import warms the FilePeekOverlay chunk before the user ever taps a link.

On a fresh tab where the chunk hashes still match the server, the prefetch hits the cache and the first tap is instant. On a stale tab where the chunk hashes have changed, the prefetch is exactly what trips vite:preloadError — but it trips at idle time (seconds into the page lifecycle, while the user is reading the inbox), which routes the reload through Layer 2 silently in the background. By the time the user actually taps a markdown link, the page has already reloaded and the fresh chunk is in cache.

This is the primary fix for the "tap → blank → reload" perceived crash. The user never sees a tap-then-reload sequence because the reload happens at boot, not at tap.

Layer 2 — preload-reload-guard (background recovery)

When vite:preloadError fires (from the boot-time prefetch OR from any other lazy boundary that runs before the prefetch warmed the chunk), the preload-reload-guard catches it and reloads the page once per page lifecycle so the fresh index.html picks up the new chunk hashes. The store also persists the click intent before any async work so a tap that does race the prefetch can be replayed after the reload — gated by three independent safeguards so a stale entry never spuriously re-opens a peek hours later. See "Write / Reload / Restore paths" below.

Layer 3 — visible Suspense fallback (edge-case safety net)

If the user somehow taps a markdown link before the prefetch resolves (extremely fast tap within the first ~200ms of boot, or before idle-callback fires), the React.lazy boundary briefly mounts FilePeekLoadingFallback.tsx — a panel-shaped placeholder matching the eventual viewer's shape: same right-slide drawer on desktop, same full-screen sheet on mobile, same close button, plus a spinner and the file name pulled from the store. Tapping a link registers within one frame, before the chunk fetch even starts.

The fallback uses only entry-chunk-resident dependencies (framer-motion, lucide-react, Zustand, useIsMobile) so adding it pulls nothing new into the startup bundle. Adding markdown-vendor weight here would defeat the lazy-load purpose. In practice the fallback is rarely visible because the prefetch wins the race, but it's the floor of the user experience when the prefetch hasn't finished yet.

Layer 2 internals — write / reload / restore

Write path (open)

useFilePeekStore.openFile(filePath, lineNumber, siblings) writes {filePath, lineNumber, siblings, ts} to sessionStorage under peek-intent synchronously, BEFORE the IPC await and BEFORE the React.lazy import boundary. (close clears the entry so a clean close doesn't trigger restore.) ts is the millisecond timestamp at write time — used by the TTL gate on restore.

Reload path (preload-reload-guard)

When vite:preloadError fires, the guard:

  1. Writes a last-preload-error breadcrumb ({url, message, timestamp}) — fired even when the guard suppresses the reload, so a SECOND chunk failure on the same lifecycle is still recorded.
  2. Checks the once-per-page chunk-reload cookie. If set, returns without reloading (loop cap).
  3. Otherwise: sets chunk-reload, sets peek-restore-armed=1, and calls location.reload(). The arm flag is set ONLY when reload actually fires — a suppressed second failure must NOT re-arm restoration.

The chunk-reload cookie is cleared in the next page's load listener so a later (post-success) chunk failure can reload again.

Restore path (boot, browser-only)

main.tsx calls restorePeekIntent() after installPreloadReloadGuard(). The function walks five gates, each self-clearing the state it consumes so nothing carries forward to the next lifecycle:

  1. Diagnostic breadcrumb — read+log+delete last-preload-error. console.warn('[peek-restore] preload error from previous lifecycle:', diag) so the next investigation can correlate the reload with the failed chunk URL. Cleared regardless of the rest of the gates.
  2. Arm flag — read+delete peek-restore-armed. Manual F5 / Cmd+R / tab-restore preserves sessionStorage but never sets the flag, so a manual refresh must NOT replay. The flag is read AND deleted before the intent gate so a stale flag from a browser quirk can't haunt the session.
  3. Intent entry — read+delete peek-intent. If absent, return. Anti-loop: delete BEFORE attempting replay so a chunk that persistently fails self-clears instead of restore-fail-restore-fail forever. The arm-flag enforcement (armed !== '1' → return) runs AFTER the intent delete so a manual F5 still one-shot-clears the stale intent rather than carrying it forward into a future reload-driven boot.
  4. Shape validation — filePath must be a non-empty string. Malformed entries are dropped silently.
  5. TTL — entries with ts older than 60 seconds are dropped. Defends against an arm flag that survives a quirky navigation flow we didn't anticipate.

Replay calls openFile(filePath, lineNumber, siblings) with a module-scoped suppressNextPersist flag set so the synchronous writePeekIntent inside doesn't re-write the entry we just deleted. The flag is single-shot — a subsequent user action (sibling nav, fresh open) writes a new intent normally.

The whole path is no-op in Electron (isElectron short-circuits both write and restore) — chunks load from disk on desktop and the failure mode does not exist.

Limitations and v1 notes

  • Sibling group is captured at click time. If the agent appends a new image to the message after you opened the peek viewer (rare but possible during streaming), the peek viewer won't see it — close and reopen to refresh.
  • No "open all in a gallery view" — sibling nav is in-place only. There's no contact-sheet UI.
  • Image links in code blocks aren't siblings. The walker scopes to the message bubble (data-msg-summary) but skips inert markdown that doesn't render as anchors. If an image path appears as fenced code text rather than an image link, it's not part of the sibling set.
  • A remote session's files are read-only — no editing, saving, publishing or exporting, and no sibling image navigation. Relative links and images inside a remote Markdown file do not resolve against its folder on that computer yet.
  • Remote files open only from user SSH remotes — not from Omniscio's cloud sessions or Windows remote computers.
  • No telemetry for sibling-nav input methods. Existing peek viewer events don't track input modality, so adding only sibling-nav events would be inconsistent. If we later add peek viewer telemetry generally, sibling-nav method (button / keyboard / swipe) is the natural attribute to include.

Last verified 2026-10-19