Repository navigation
Description
Markdown viewer: copy, source/preview toggle, and in-place editing
Summary
The markdown surface is currently a one-way, read-only render target: content
goes in via CLI/pipe/file-picker, gets converted to sanitized HTML, and that's it.
There is no way to get the text back out (other than mouse-selecting rendered
HTML, which loses markdown syntax), no way to look at the raw source, and no way
to fix a typo in the file you're reading.
That makes the viewer good for consuming agent output (its original purpose,
issue #54) but useless for the far more common loop: agent writes a plan/spec →
user reads it in the pane → user wants to copy it into a ticket, quote one line
into chat, or tweak two sentences and save.
It also means the surface forgets where the content came from: the full path is
dropped at every entry point, so the pane can't tell you which file you're
reading, can't hand the path to the terminal next door, and can't save back to it.
This issue proposes four features, in priority order:
| # | Feature | Priority | Rough size |
|---|---|---|---|
| F0 | Path-aware surfaces — a markdown surface knows, shows, and can hand out the path of the file it came from | must have | small |
| F1 | Copy Markdown — copy the raw markdown source to the clipboard (all, a selection, or a code block) — and the file path | must have | small |
| F2 | Toggle Text/Markdown view — switch the pane between rendered preview and raw, line-selectable source | must have | small |
| F3 | Edit & Save — edit the source in place and write it back to the backing file | nice to have | medium |
F0–F2 are pure-renderer changes (F0 needs one field plumbed through existing
producers) with no new IPC and no new trust surface. F3 introduces the first
write path to the filesystem from the markdown surface and needs a deliberate
security design (see Security).
Current state
Rendering
src/renderer/components/Markdown/MarkdownPane.tsx:12-51 is the whole component
(51 lines). It:
marked.parse(content)with{ gfm: true, breaks: true }DOMPurify.sanitize(...)withFORBID_TAGS: ['style','form','input','button','textarea','select']- dumps the result through
dangerouslySetInnerHTMLinto.markdown-pane__content - intercepts clicks on
<a>and routes them to the wmux browser panel
No toolbar, no state, no modes. The raw content prop is available in the
component but never shown to the user.
Where content comes from
| Entry point | Code | Sets file name? | Sets file path? |
|---|---|---|---|
wmux markdown set <id> --content <text> |
src/cli/wmux.ts:241-247 → markdown.set_content (src/main/v2-bridge.ts:88-90) |
no | no |
wmux markdown set <id> --file <path> |
src/cli/wmux.ts:248-251 → markdown.load_file (src/main/index.ts:608-637) |
yes (basename) | no |
wmux markdown <file> (one-shot) |
src/cli/wmux.ts:256-262 — creates the surface, then markdown.load_file |
yes (basename) | no |
| Command palette → "Open Markdown File…" | src/renderer/components/CommandPalette/CommandPalette.tsx:86-108 → markdown:open-file IPC (src/main/ipc-handlers.ts:331-366) |
yes (derived in renderer) | no (main returns filePath, renderer throws it away at line 100-101) |
Ctrl+Shift+M (openMarkdownPanel) |
src/renderer/hooks/useKeyboardShortcuts.ts:322 |
n/a (empty surface) | n/a |
All of them funnel into setMarkdownContent(surfaceId, content, fileName?)
(src/renderer/store/surface-slice.ts:427-442), which patches the surface in the
split tree.
State model
SurfaceRef (src/shared/types.ts:14-36) carries:
markdownContent?: string; // raw markdown, persisted
markdownFileName?: string; // basename only — used as the tab labelTwo consequences that matter here:
- The full path is never stored.
markdownFileNameis a basename
(src/renderer/components/SplitPane/surface-label.ts:36), so today the
renderer literally cannot know what file to save back to. F3 requires adding
the path. - Content is persisted into the session snapshot.
src/renderer/App.tsx:666-692
serializes the entiresplitTreeon the 30 s autosave, somarkdownContent
(including, once F3 lands, unsaved edits) survives restarts. That's a feature
(crash safety) and a hazard (silent divergence from disk) — addressed below.
Available plumbing we can reuse
- Clipboard:
window.wmux.clipboard.writeText/readText(src/preload/index.ts:98-102).
Preferred overnavigator.clipboardin this codebase — see the comments at
src/renderer/hooks/useTerminal.ts:620-636(no user-gesture requirement, and
correct handling of non-UTF-8 Windows clipboard payloads). - Read guards already centralized twice (extension whitelist + 5 MB cap):
src/main/index.ts:616-628andsrc/main/ipc-handlers.ts:336-359. - A toolbar-button precedent with matching CSS tokens:
diff-pane__refresh-btn
(src/renderer/components/Diff/DiffPane.tsx:242-248,src/renderer/styles/diff.css:92-110). - Shortcut registry:
ShortcutActionunion +DEFAULT_SHORTCUTS
(src/renderer/store/settings-slice.ts:160-161, 216-217). - i18n: three dicts (
en/fr/zh) insrc/renderer/i18n/core.ts:24, 99, 165.
Use cases
UC-1 — Copy an agent's plan into a ticket. Claude writes PLAN.md, wmux
renders it. The user wants the markdown (headings, bullets, code fences) in
Jira/Linear/GitHub. Selecting the rendered HTML yields plain text with the syntax
stripped and code blocks mangled. Today the only workaround is cat PLAN.md in a
terminal pane and copying from xterm.
UC-2 — Quote one line into chat. The user wants a single bullet, or one line
of a fenced code block, verbatim. Rendered-HTML selection is unreliable
(soft-wrapped <li>, inline <code> padding) and there is no line granularity.
UC-3 — Verify what the agent actually wrote. Rendering hides syntax errors:
a broken table, an unclosed fence, a literal \n that should have been a newline
(a real class of bug for content arriving via markdown.set_content, which passes
through JSON.stringify in the bridge). The user needs to see the source to debug
the producer.
UC-4 — Fix a typo without leaving the pane. Reviewing a spec, spotting a
wrong word, and needing an editor pane / nvim in another tab to change three
characters is disproportionate friction. Read → edit → save should happen where
the reading happens.
UC-5 — Write a short note. Ctrl+Shift+M opens an empty markdown surface.
Today it stays empty forever (it can only be filled from outside). With F3 it
becomes a scratchpad, with "Save As" to materialize it.
UC-6 — Hand the path to something else. The user is reading docs/config.md
in the pane and wants to run nvim docs/config.md, git log -- docs/config.md,
or paste the path into a Claude prompt in the neighbouring terminal. Today the
pane shows only the basename on the tab; the path has to be reconstructed by
hand — and for a file opened via the palette's native dialog, the user may not
know where it lives at all.
UC-7 — Agent-and-human co-editing. An agent regenerates a doc on disk while
the user has it open. The pane should notice and offer to reload rather than
silently overwrite the agent's work on next save (see Conflict handling).
F0 — Path-aware markdown surfaces
Today a markdown surface is content-only; the path is dropped at every entry
point (see the table above). That's the root cause behind UC-6, it blocks F3
entirely, and it makes the "which file am I even looking at?" question
unanswerable for palette-opened files. Fixing it first makes the rest cheap.
Behaviour
- Every surface populated from a file carries its absolute path.
- The toolbar shows the path, not just the basename:
- relative to the workspace
cwdwhen the file is inside it
(ws.cwdis already on the workspace and persisted —src/renderer/App.tsx:682), ~/…-shortened when inside the home directory,- otherwise absolute; middle-ellipsized to fit, with the full path in the
titletooltip.
- relative to the workspace
- The tab tooltip gets the full path too (the label stays the basename —
src/renderer/components/SplitPane/surface-label.ts:36). - Copy file path / Copy relative path in the toolbar overflow menu (see F1).
- Reveal in File Explorer —
shell.showItemInFolder, and Open in default
app —shell.openPath. Both are main-process one-liners; gate them on a
path being present. (system.openExternalalready exists in the preload
surface; these are the filesystem-side equivalents.) - Surfaces with no backing path (
markdown.set_content,Ctrl+Shift+M) show
no path chip and disable the path-dependent actions. This must stay a
first-class state, not an error case — pushed agent content is the original use
case for the surface. - Drag and drop a file onto a markdown pane opens it there. The renderer can
already resolve a droppedFileto a real path via
window.wmux.shell.getPathForFile(src/preload/index.ts:103-108, added for
terminal drag-and-drop in issue Drag and Drop of Files does nothing #33), so this is a drop handler plus the same
guarded read the palette uses. - Reload from disk button, active whenever a path is present — useful before
F3 even exists, since agents rewrite files under the pane constantly.
Implementation
Add markdownFilePath to SurfaceRef (full definition in the F3 state block
below) and pass it from every producer:
| Producer | Change |
|---|---|
markdown.load_file (src/main/index.ts:632-634) |
pass filePath alongside the existing path.basename(filePath) |
markdown:open-file palette flow (CommandPalette.tsx:94-102) |
stop discarding res.filePath; forward it |
markdown.set_content (src/main/v2-bridge.ts:88-90) |
unchanged — no path by design |
setMarkdownContent grows an options object rather than a fourth positional
argument (see F3). Keep the existing "don't clobber on content-only updates"
guard (src/renderer/store/surface-slice.ts:434-436) and extend it to the path:
wmux markdown set <id> --content … against a file-backed surface must not
silently re-point or clear the path.
One decision to make explicit: pushing new content into a file-backed surface
means the buffer no longer matches disk. Treat it exactly like a user edit —
keep the path, mark the surface dirty (once F3 lands). Do not auto-write.
F1 — Copy Markdown
Behaviour
- Toolbar button Copy (clipboard icon) in the pane header. Copies the full
rawmarkdownContent— not the rendered text. - Transient confirmation: the button label/icon flips to "Copied" for ~1.2 s
(no toast infra needed). - Disabled when
contentis empty. - Bonus, cheap: per-code-block copy buttons. After the sanitized HTML is
mounted, walkpre > codenodes and inject a small copy button per block. This
is the single most-requested markdown-viewer affordance and reuses the same
handler. - In source view (F2), if a text selection exists, Copy copies the selection;
otherwise the whole document. In preview view it always copies the whole
document (line-level copy is what source view is for). - Copy file path and Copy relative path (relative to the workspace
cwd)
as separate entries in the toolbar overflow menu, greyed out when the surface
has no backing path. Copy-path is the fastest bridge from "reading this doc" to
"acting on it in the terminal next to it" (UC-6) and costs nothing once F0
stores the path.
Windows note: copy the path with backslashes as-is. wmux's own CLI and the
shells it spawns accept both separators, and normalizing to forward slashes
would break cmd.exe consumers.
Implementation sketch
const copy = useCallback(async (text: string) => {
if (!text) return;
await window.wmux?.clipboard?.writeText?.(text); // preload/index.ts:100
setCopied(true);
window.setTimeout(() => setCopied(false), 1200);
}, []);For the per-block buttons, prefer a delegated click handler on
.markdown-pane__content keyed off a data-md-copy attribute added in a
useEffect after render, over React portals — the HTML is injected via
dangerouslySetInnerHTML, so there are no React nodes to attach to. Note that
FORBID_TAGS includes button, so the injected buttons must be created after
sanitization (DOMPurify would strip them if they came from marked), which the
useEffect approach naturally does.
F2 — Toggle Text/Markdown view
Behaviour
- Two-state segmented control in the toolbar: Preview | Source (icon or
¶ / </>). - Source view renders the raw markdown in a monospace,
white-space: pre,
horizontally scrollable block using the terminal font stack
('Cascadia Mono', 'Consolas', monospace— same asmarkdown.css:47). - Line numbers in a non-selectable gutter (
user-select: none) so double-click /
drag selection yields clean lines without numbers. This is what makes UC-2 work. - Optional soft-wrap toggle for long paragraphs (default off — wrapping breaks
line-accurate selection). - Mode is per surface and persisted on
SurfaceRefas
markdownViewMode?: 'preview' | 'source'so it survives the remounts caused by
split-tree restructures (same rationale as the existingmarkdownContent
comment atsrc/shared/types.ts:29-31) and the session snapshot. - Shortcut:
Ctrl+Shift+E(currently unbound — verified against
DEFAULT_SHORTCUTS) as a newtoggleMarkdownSourceaction, active when the
focused pane's active surface is a markdown surface.
Why not a third "both" mode
Side-by-side preview+source is tempting but doubles the layout work and competes
with wmux's own splitting: a user who wants both can already split the pane and
open the file twice. Keep two modes; revisit later.
Implementation sketch
type ViewMode = 'preview' | 'source';
// source view
<pre className="markdown-pane__source">
{content.split('\n').map((line, i) => (
<div className="markdown-pane__source-line" key={i}>
<span className="markdown-pane__source-gutter">{i + 1}</span>
<span className="markdown-pane__source-text">{line || ' '}</span>
</div>
))}
</pre>Per-line <div>s are fine up to the 5 MB cap in practice, but a 5 MB file is
~100 k lines and will jank. Guard: above a SOURCE_VIRTUALIZE_THRESHOLD
(suggest 5 000 lines) fall back to a single <pre>{content}</pre> without a
gutter rather than pulling in a virtualization dependency (the project has
deliberately minimal deps — see package.json).
F3 — Edit and save
Behaviour
- Edit toggle (pencil) enters edit mode; edit mode is source view plus an
editable buffer. Only reachable from source view, so the mental model is
"Preview → Source → Editing". - Plain
<textarea>— no CodeMirror/Monaco. The project ships no editor
dependency and adds ~1–3 MB to the bundle for one. Atextareawith the
monospace stack,Tabinserting two spaces, and auto-continuation of-/
1./>list prefixes on Enter covers the "fix a typo, add a bullet" cases
this issue is actually about. Syntax highlighting is explicitly out of scope. - Live preview is not required while editing (that's the "both" mode we
deferred); leaving edit mode re-renders. - Dirty state:
markdownDirty?: booleanonSurfaceRef; the tab label gets a
•prefix (src/renderer/components/SplitPane/surface-label.ts:36). - Save (
Ctrl+Swhen the pane is focused, plus a toolbar button):- has a backing path → write in place
- no backing path (created by
Ctrl+Shift+Mormarkdown.set_content) → open
native Save As dialog, then write and adopt the returned path
- Revert (discard buffer, reload from disk) in the toolbar overflow menu.
- Closing a dirty surface: confirm before closing. Note
reopenClosedSurface
(src/renderer/hooks/useKeyboardShortcuts.ts:339) preserves closed surfaces, so
an accidental close is recoverable — the confirm is still worth it because
"recoverable via a shortcut you may not know" isn't good enough for user text.
State additions
// src/shared/types.ts — SurfaceRef
/** Absolute path of the file backing a markdown surface (F0). Shown in the
* toolbar, copyable, and required to save edits back to disk; absent for
* content pushed via markdown.set_content or an empty scratch surface. */
markdownFilePath?: string;
/** mtimeMs of the backing file as of the last successful load/save — used to
* detect out-of-band changes before overwriting. */
markdownFileMtime?: number;
/** View mode of a markdown surface (F2). */
markdownViewMode?: 'preview' | 'source';
/** Buffer differs from what's on disk (F3). */
markdownDirty?: boolean;setMarkdownContent (src/renderer/store/surface-slice.ts:427-442) grows a
filePath/mtime parameter — or, cleaner, is refactored to take an options
object so the next addition doesn't add a fifth positional argument:
setMarkdownContent(surfaceId, content, { fileName, filePath, mtimeMs, dirty }?)Every producer must be updated to pass the path:
src/main/index.ts:632-634 (the load_file bridge call),
src/main/ipc-handlers.ts:362 already returns filePath — the palette caller at
src/renderer/components/CommandPalette/CommandPalette.tsx:94-102 just needs to
forward it.
New write channel
// src/shared/types.ts → IPC_CHANNELS
MARKDOWN_SAVE_FILE: 'markdown:save-file', // write in place
MARKDOWN_SAVE_AS: 'markdown:save-as', // native dialog + write// src/preload/index.ts (next to markdown.openFile, line 185-189)
markdown: {
openFile: () => ipcRenderer.invoke(IPC_CHANNELS.MARKDOWN_OPEN_FILE),
saveFile: (filePath: string, content: string, expectedMtimeMs?: number) =>
ipcRenderer.invoke(IPC_CHANNELS.MARKDOWN_SAVE_FILE, filePath, content, expectedMtimeMs),
saveAs: (content: string, suggestedName?: string) =>
ipcRenderer.invoke(IPC_CHANNELS.MARKDOWN_SAVE_AS, content, suggestedName),
}Main-process handler requirements (src/main/ipc-handlers.ts):
- Extension whitelist and 5 MB cap on the content being written, mirroring
the read guards. FactorALLOWED_MD_EXT/MAX_MD_BYTESout of
src/main/index.ts:616,624andsrc/main/ipc-handlers.ts:336-337into a
shared module (e.g.src/main/markdown-file.ts) instead of a third copy. - Path must be in the grant set (see below).
- Reject if the target is a symlink or not a regular file
(fs.lstatSync(...).isSymbolicLink()), so a save can't be redirected through
a link planted by whatever produced the markdown. - Optimistic-concurrency check: if
expectedMtimeMsis provided and the
file's currentmtimeMsdiffers, return
{ conflict: true, currentMtimeMs }and write nothing. - Atomic write: write
<file>.wmux-tmp-<random>in the same directory, then
fs.renameSyncover the target. A half-written spec is worse than an
unsaved one. - Return
{ ok: true, mtimeMs }so the renderer can refresh
markdownFileMtimeand clearmarkdownDirty.
Security
This is the first renderer→disk write in this surface, and the markdown content
itself is explicitly treated as untrusted (see the comment at
MarkdownPane.tsx:21-24, and the markdown.load_file hardening note in
src/shared/instance.ts:33). Two rules:
- Never let the write target be an arbitrary renderer-supplied path. The main
process keeps a per-webContentsgrant set of paths that the user or an
authenticated pipe client opened this session — populated in
MARKDOWN_OPEN_FILE(ipc-handlers.ts:350), in themarkdown.load_file
handler (index.ts:611), and byMARKDOWN_SAVE_ASon dialog confirmation. A
MARKDOWN_SAVE_FILEfor a path not in that set is rejected. This keeps the
blast radius of a renderer-side bug (e.g. prototype pollution via injected
markdown) to "files the user already opened", not~/.ssh/authorized_keys. - Extension whitelist applies on write too, so a grant can't be laundered
into writing.ps1/.cmd/.bat. Combined with the whitelist on read,
the reachable set stays.md/.markdown/.mdx/.txt/.text/.rst.
Worth noting explicitly: markdown.load_file is already token-gated on the pipe
(src/shared/instance.ts:28-37); no new pipe method is required for F3 — saving
is renderer-initiated only. Do not add a markdown.save_file pipe method in
this issue; agents already have unrestricted Write, and it would widen the pipe
surface for no gain.
Conflict handling
| Situation | Behaviour |
|---|---|
| Disk unchanged since load, buffer dirty | save in place |
| Disk changed, buffer clean | show a "changed on disk — Reload" banner in the toolbar (no auto-reload; the user may be mid-read) |
| Disk changed, buffer dirty | save is blocked; banner offers Overwrite / Reload and lose my edits / Save As copy |
| No backing path | Save As |
Disk-change detection: a lightweight fs.watch on the backing file, or an
mtime re-stat on pane focus. Prefer the mtime-on-focus check for v1 — it
needs no watcher lifecycle management and covers the realistic case ("agent
rewrote the file while I was in another pane"). A watcher can come later if
live-reload-while-visible is wanted.
Session-restore caveat: because unsaved buffers are persisted in the autosave
snapshot (src/renderer/App.tsx:666-692), a restored dirty surface must re-stat
its file and, if the mtime moved, come up with the conflict banner already
showing rather than silently holding a stale buffer.
UI layout
The toolbar has to be added carefully: .markdown-pane currently owns both the
scroll container and the padding (src/renderer/styles/markdown.css:1-11), so a
naive header would scroll away with the content.
┌──────────────────────────────────────────────────────────────┐
│ docs/PLAN.md ⧉ [Preview|Source] [Edit] [Copy] [⋯] │ ← sticky, ~32px
├──────────────────────────────────────────────────────────────┤
│ ↑ path chip: click = copy path, ⧉ = reveal in explorer │
│ ⋯ = Copy path / Copy relative path / Reload / Reveal / │
│ Open in default app / Revert │
├──────────────────────────────────────────────────────────────┤
│ │
│ rendered markdown / source / textarea (scrolls) │
│ │
└──────────────────────────────────────────────────────────────┘
Required restructure:
.markdown-pane { display: flex; flex-direction: column; overflow: hidden; padding: 0; }
.markdown-pane__toolbar { flex: 0 0 auto; /* diff-pane__sidebar-header tokens */ }
.markdown-pane__body { flex: 1 1 auto; overflow: auto; padding: 24px 32px; }Style the toolbar with the theme variables already used by the diff pane
(--ui-bg-2, --ui-text-primary, rgba(var(--ui-overlay-rgb), 0.1) for hover)
rather than the hard-coded hex values that the rest of markdown.css uses — the
existing hardcoded colors are a separate pre-existing wart, not something to
propagate.
Toolbar should auto-hide its labels below a narrow pane width (icon-only), since
markdown surfaces are frequently in a quarter-width pane.
Also worth fixing while we're in here
- GFM task-list checkboxes are silently stripped.
FORBID_TAGSincludes
'input'(MarkdownPane.tsx:28), so- [ ] itemrenders as a bare bullet —
andmarkdown.css:117-120styles a checkbox that can never exist. Either allow
input[type=checkbox][disabled]explicitly, or render☐/☑glyphs. (Making
checkboxes interactive is an editing feature and belongs with F3, gated on a
backing file.) markdown.set_contentcan't set a file name, so every CLI-pushed surface is
labelled "Markdown". A--titleflag onwmux markdown set(src/cli/wmux.ts:241-247)
would make multiple agent-pushed docs distinguishable.- No way to read content back out via CLI.
wmux markdown get <id>(mirroring
read-screen) would let an agent verify what it pushed, and is trivially built
on amarkdown.get_contentbridge entry next to
src/main/v2-bridge.ts:88-90.
Implementation risk: global shortcuts vs. the editor
isSafeToIntercept (src/renderer/hooks/useKeyboardShortcuts.ts:30-52) has no
guard for editable focus targets — it reasons only about modifier combos, on the
assumption that the only keyboard consumer is xterm. Once a <textarea> exists in
a pane, every Ctrl+Shift+<letter> binding fires while the user is typing, and
document-level preventDefault at line 367 will swallow keys the textarea
should have received.
Add an early bail:
const t = e.target as HTMLElement | null;
if (t && (t.tagName === 'INPUT' || t.tagName === 'TEXTAREA' || t.isContentEditable)) {
// let the editor have it, except for explicitly global combos
if (!isGlobalOverride(e)) return;
}This also fixes latent misbehaviour in existing inputs (settings fields, tab
rename) and should probably land as its own small commit before F3.
Ctrl+S specifically: it is not currently in DEFAULT_SHORTCUTS and bare-Ctrl
combos are deliberately not intercepted globally (line 31-51, so the terminal
keeps XOFF). Handle it locally in the markdown pane via a component-level
keydown listener, not by adding a global action.
Testing
Unit (Vitest, tests/unit/):
markdown-view.test.ts— mode toggle reducer, dirty tracking, list-prefix
auto-continuation,SOURCE_VIRTUALIZE_THRESHOLDfallback.markdown-file.test.ts(new shared main-process module) — extension whitelist
on write, size cap, symlink rejection, grant-set enforcement, mtime conflict
detection, atomic-rename behaviour, and that a rejected write leaves the
original file byte-identical.- Extend
surface-slicecoverage for the newsetMarkdownContentoptions object,
including "content-only setters must not clobbermarkdownFilePath" (the same
class of bug the existingfileNameguard at line 434-436 exists to prevent). markdown-path.test.ts— display-path derivation: insidecwd→ relative,
inside home →~/…, elsewhere → absolute, UNC paths (\\server\share\…) not
mangled, and the middle-ellipsis never dropping the basename.
Manual:
wmux markdown docs/config.md→ Copy → paste in a terminal → syntax intact.
1b. Same surface → path chip showsdocs/config.md; Copy path → paste → absolute
path with backslashes; Reveal in Explorer selects the file. Then open a file
from outside the workspace via the palette → chip shows~/…or absolute.
1c.wmux markdown set <id> --content "x"against that surface → path is kept,
not cleared or re-pointed.
1d. Drag a.mdfile from Explorer onto the pane → it opens, path chip updates.- Toggle to Source → double-click one line → paste → exactly that line.
- Edit a word,
Ctrl+S,git diff→ only that word changed, file still ends
with a single trailing newline, CRLF/LF unchanged. Ctrl+Shift+M→ type →Ctrl+S→ Save As dialog → file created.- Open a file,
echo x >> filefrom a terminal pane, refocus the markdown pane
→ conflict banner appears; Save is blocked. - Restart wmux with a dirty buffer → content restored, conflict state correct.
- Try to save a surface whose content came from
markdown.set_contentwith a
hand-forged path in the store → rejected by the grant set.
Suggested sequencing
- PR 1 — editable-focus guard in
isSafeToIntercept(small, independent, fixes
existing latent bugs). - PR 2 — F0: plumb
markdownFilePaththrough every producer, path chip in a
new toolbar shell, copy-path / reveal / open-in-default-app / reload,
drag-and-drop onto the pane, full path in the tab tooltip. - PR 3 — F1 + F2:
markdownViewModeonSurfaceRef, Copy (document,
selection, per-code-block), source view with gutter,Ctrl+Shift+E, i18n keys
for en/fr/zh. No new IPC. Ships the two must-haves. - PR 3b — extract
src/main/markdown-file.tswith the shared read/write
guards (currently duplicated atmain/index.ts:616-628and
ipc-handlers.ts:336-359) and addmarkdownFileMtime. No user-visible
change — pure groundwork, easy to review. - PR 4 — F3: textarea editor, dirty state,
MARKDOWN_SAVE_FILE/
MARKDOWN_SAVE_ASwith grant set + atomic write, conflict banner,
close-confirm. - PR 5 (optional) — the "also worth fixing" items: task-list checkboxes,
--titleonmarkdown set,wmux markdown get.
Open questions
- Should
Ctrl+Shift+Mon a pane that already has a markdown surface focus it
instead of stacking a new one (the wayopenDiffPaneldedups at
useKeyboardShortcuts.ts:326-333)? Diff is a singleton; markdown arguably
isn't — but an empty duplicate scratchpad is rarely what's wanted. - Should edit mode be gated behind a setting (default off) so the read-only
guarantee is preserved for users who only ever consume agent output? - For a surface with no backing file, should Save As default into the workspace
cwd(ws.cwdis already persisted —src/renderer/App.tsx:682)?
Activity
feat(markdown): path-aware surfaces, copy, and source view (#116)
amirlehmam commentedon Jul 24, 2026
F0, F1 and F2 shipped in v0.34.0. F3 (edit & save) is deliberately still open — see below.
What landed
F0 — path-aware surfaces.
markdownFilePathis now plumbed through every producer that actually has a path (markdown.load_file, the command-palette picker), and the pane grew a toolbar that shows it: relative to the workspacecwdwhen the file is inside it,~-shortened under home, absolute otherwise, middle-ellipsized so the basename always survives. Comes with copy path / copy relative path, reveal in Explorer, open in default app, reload from disk, and drag-and-drop of a file onto the pane.markdown.set_contentstays pathless by design, and a content-only push against a file-backed surface no longer re-points or clears its path — that guard has a test.F1 — Copy. Toolbar button copies the raw markdown rather than the rendered text, plus per-code-block copy buttons. Those are injected after sanitization, because
FORBID_TAGSincludesbuttonand DOMPurify would otherwise strip them. In source view, a selection inside the pane wins over the whole document.F2 — Preview/Source toggle, persisted on the
SurfaceRefso it survives the remount a split-tree restructure causes. The gutter isuser-select: none, which is what makes UC-2 work. Past 5000 lines it falls back to a plain<pre>instead of pulling in a virtualization dependency.Ctrl+Shift+E→toggleMarkdownSource, as proposed. en/fr/zh strings for everything.Three things worth calling out
The editable-focus guard was the right call, and nastier than the issue makes it sound. The issue's suggested snippet bails on
tagName === 'TEXTAREA'— but xterm.js renders its focus target as<textarea class="xterm-helper-textarea">. Shipping that snippet as written would classify every focused terminal as an editor and silently disable the entire global shortcut set, which is the normal case, not an edge case. The guard now excludes anything inside.xtermbefore the tag check, and there's a test pinning exactly that. It landed with the rest rather than as its own PR, but it does fix the latent misbehaviour in the settings fields and the tab-rename box today.Task-list checkboxes are fixed via glyphs, not by relaxing the sanitizer. Allowing
input[type=checkbox][disabled]through DOMPurify would mean admitting<input>from untrusted markdown and relying on attribute filtering to keep the rest out. Amarkedrenderer override that emits ☐/☑ never emits the tag at all, so there's nothing to filter. The deadmarkdown.cssrule that styled the impossible checkbox is gone.Two bugs found while in here that weren't in the issue:
MarkdownPanewas calling the globalmarked.setOptions()during render — mutating parser state shared by every markdown pane in the window. It now uses its ownMarkedinstance.readMarkdownFileuseslstatand rejects symlinks. Without it, a link namednotes.mdpointing at a non-whitelisted target passes the extension check on its own name — which matters more now thatrevealandopen in default apptake a renderer-supplied path.src/main/markdown-file.tsnow holds the read guards that were duplicated betweenmain/index.tsandipc-handlers.ts(PR 3b in the sequencing), so the reachable file set is defined once.On F3
Not shipped, and I'd rather it stay its own change. It is the first renderer→disk write in this surface, and the grant-set / atomic-write / mtime-conflict design in this issue deserves to be reviewed on its own rather than buried under a toolbar refactor. The groundwork it needs is now in place: the shared guard module exists,
readMarkdownFilealready returnsmtimeMs, and the editable-focus guard that a<textarea>editor requires is done.Leaving this open to track F3. The three "also worth fixing" items (
--titleonmarkdown set,wmux markdown get) are also still open — task-list checkboxes are done.Open questions, answered
Ctrl+Shift+Mfocus an existing markdown surface instead of stacking? Not changed. Unlike diff, a second markdown surface is often legitimately wanted — but now that surfaces are path-aware, "focus the one already showing this file" is the better dedup key than "focus any markdown tab". Worth revisiting with F3.kevmtt commentedon Jul 24, 2026
@amirlehmam You and you agents are so fast! I though we discuss first, but I guess I provided enough information 😆
myersdb commentedon Jul 28, 2026
At least need to be able to copy text.
amirlehmam commentedon Jul 28, 2026
F3 shipped in v0.37.0 (4498cf1), along with the two remaining "also worth fixing" items. This closes the issue.
@myersdb — copy landed back in 0.34.0 (F1): the toolbar Copy button copies the raw markdown rather than the rendered text, and every fenced code block gets its own copy button. Source view also lets you select individual lines cleanly. If that isn't working for you, it's a separate bug and worth its own issue.
What landed
The editor. A plain
<textarea>, as the issue argued for — CodeMirror/Monaco would be 1–3 MB of bundle for a surface whose job is "fix a typo, add a bullet". Tab inserts two spaces instead of moving focus, and Enter continues-/1./>/- [ ]prefixes, ending the list on an empty item the way every editor does. Ordered lists increment. Those are the two absences that make a bare textarea feel broken for markdown; beyond them it's just a textarea, deliberately.Save.
Ctrl+S(handled locally in the pane, not as a global action — bare-Ctrl combos are deliberately not intercepted globally so the terminal keeps XOFF) plus a toolbar button. Backed by a path → writes in place. No path → Save As, which then adopts the path.Dirty state.
markdownDirtyon theSurfaceRef, a•on the tab, and a confirm before closing. That goes through the samerequestClose→pending→confirmsplit thatConfirmCloseDialogalready uses for workspaces, which keeps the property you'd want:wmux close-surfacefrom the CLI closes immediately and never blocks on a modal nobody is looking at.Conflicts via mtime re-stat on focus, as suggested. No watcher lifecycle, and it covers the real case — an agent rewrote the file while you were in another pane. Dirty buffer + changed disk blocks the save and offers Overwrite / Reload / Save-as-copy.
The two leftovers:
--titleonwmux markdown set(every pushed surface was labelled "Markdown"), andwmux markdown get <id>, which returns content, path and dirty state so an agent can verify what it actually pushed.Where I diverged from the issue, and why
The grant set is stricter than proposed —
MARKDOWN_READ_FILEdoes not grant. The issue lists the palette dialog,markdown.load_fileand Save As as grant sources, which I kept. ButMARKDOWN_READ_FILE(which backs reload-from-disk and drag-and-drop) takes a renderer-supplied path. If it minted grants, the renderer could mint its own, and the set would be decorative — it would stop nothing that the threat model is actually about.The cost is real and worth stating: a file you drag onto the pane saves through Save As the first time. That looked like a wart until I wrote it down the other way round — the dialog is the user confirming the destination, which is the same standard the palette flow already meets. So it's the mechanism working, not a gap in it. The path is granted after that, and subsequent saves are in place.
Task-list checkboxes stay non-interactive. The issue floats making them clickable under F3, gated on a backing file. Skipped: they're rendered as ☐/☑ glyphs specifically so
<input>never has to be admitted through DOMPurify, and making them interactive means either reversing that or round-tripping a click into a source edit. Neither is worth it for this issue. Worth its own if anyone wants it.Edit mode is not behind a setting (one of your open questions). The read-only guarantee is preserved by the fact that edit mode is opt-in per pane and nothing writes without an explicit Save — a preference would just be a second switch in front of the first.
Save As defaults into the workspace
cwd(your third open question) — yes, it does.Things the issue didn't call out
--titledoesn't make a surface file-backed. Labelling pushed content is a tab-label concern; the surface stays pathless, and Save still goes through Save As. Conflating the two would have been an easy way to makemarkdown set --titleaccidentally grant a write path.wmux markdown set <id> --content …against a file-backed surface leaves a•on the tab. That's intended — the buffer genuinely no longer matches disk..ps1.isSafeToIntercept's editable-focus guard — the prerequisite you sequenced as PR 1 — landed back in 0.34.0, including the.xtermexclusion that the issue's suggested snippet would have gotten wrong (xterm renders its focus target as<textarea class="xterm-helper-textarea">, so a naivetagName === 'TEXTAREA'bail disables every global shortcut whenever a terminal is focused). That groundwork is why the textarea could just drop in here.Thanks for the issue — the sequencing held up almost exactly as written, and having the security design argued out in advance is the reason F3 could ship as one reviewable change instead of a negotiation.
feat(markdown): edit and save in place (issue amirlehmam#116, F3)