dsh-typst-preview

Live Typst preview in the DeepSeek Harness Web UI's native right Sidebar — the same shape as the built-in Markdown preview: one tab per file, one toolbar switch between the rendered page and the source.

中文说明见 README.zh.md.

What you get

Open the right Sidebar → Files → click a .typ file, and it opens as a Sidebar tab with two faces:

• Preview — the page tinymist preview renders, driven over a WebSocket, so it follows the file on disk while you (or the agent) write it. The toolbar has reload, a colour mode cycle (original / follow system / inverted, remembered in localStorage) and open-in-new-tab.
• Source — the file's own text, syntax-highlighted from tinymist's own semantic tokens (headings, keywords, functions, strings, math, labels, comments, *strong* and _emphasis_ markup), with line numbers, copy and a Load more button for large files. The colours are the app's own code-block palette, so a .typ block looks the same here as in a Markdown code fence. If highlighting is unavailable — no tinymist, a file past the size cap, or highlight: false — the face falls back to the shared code renderer over the host's paged reader, exactly as it worked before.

Both faces stay mounted, so switching to Source and back does not tear down the preview server — it keeps compiling in the background. The preview document is mounted only for the tab you are looking at: one live preview page is a whole WebKit document with a compiled renderer and a socket, and keeping one per open tab is how a browser tab reaches multiple gigabytes. Returning to a tab reloads its page (~1 s), and it re-opens the preview first: the token the tab still holds may belong to an instance that was reaped while the tab was hidden, and asking for a dead token used to answer with an error page instead of the document.

.typ is claimed through the Sidebar's tab-type registry at priority: 'extension', which outranks the built-in plain-text fallback viewer. To send .typ back to the native text viewer instead, change priority in typstTabDefinition() (src/client/index.tsx) to 'fallback' and open the tab explicitly with openResource(address, { kind: 'typst-preview' }).

Requirements

• DSH >= 0.1.5-rc.1 — the plugin registers a tab type on the native right Sidebar (ctx.sidebarRightTabs) and mounts its body into the sidebar.right.pane.tab slot.
• tinymist — looked up on PATH, then in ~/.local/bin, /opt/homebrew/bin, /usr/local/bin and ~/.cargo/bin. Override the path with tinymistPath (below).
• The predecessor of this plugin (~/.dsh/plugins/dsh-typst-preview, mounted onto the dsh-better-sidebar file viewer) is not compatible with 0.1.5 and is superseded by this one.

Permissions, dependencies and failure bounds

Stated plainly, because this plugin drives an external compiler and DSH STORE (rightly) refuses to guess: it is a high-capability plugin, so the store lists it as user-reviewed — the market shows you what changed and you confirm it — rather than auto-approving it.

Capability	Exact bounds
Files	Reads the .typ files whose tabs you opened, and nothing else of yours. Never writes: the source face is read-only, and only the agent's own tools edit your files.
Network	No outbound traffic, no telemetry. Every request is either same-origin (/api/typst-preview/* on the app's own host) or loopback to a tinymist process this plugin started.
Commands	Spawns the local tinymist binary (preview, and lsp for source highlighting) with an explicit argv; no shell, no remote installs, no other executables. tinymistPath overrides which binary.
Credentials	None. No tokens, keys or cookies are read; the only environment use is resolving the tinymist path and the user's home directory.
Lifecycle	No preinstall/install/postinstall/prepare. Nothing runs at install or update time, which is also why lib/ is committed.

External dependency: tinymist must be on PATH (or given via tinymistPath); verified against v0.15.0-rc1.

When things are missing or fail: no tinymist means the Preview face shows the error and the Source face falls back to plain text; a file over highlightMaxBytes (4 MiB) loses highlighting but still reads; a crashed or killed preview is reaped and started again on demand; the fleet is capped (maxInstances, plus a hard ceiling of twice that) and both idle and orphaned children are reaped, so a lost child cannot outlive the tab that started it.

Declared compatibility: Node >=22, DSH >=0.1.5-rc.1 <0.2.0 (per-release record: 0.1.5-rc.1: compatible), profile web. The install/start/uninstall/rollback transcript on a disposable profile is in docs/profile-evidence.md; other DSH releases stay unknown there until the same run is done on them.

Install

dsh plugin --profile web add github:Limbo-137/dsh-typst-preview

Then restart dsh web (Ctrl-C in the terminal that runs it, start it again). This plugin has a host half that owns real tinymist processes and registers routes on the app's web server, so it cannot be hot-mounted; and a running instance only picks up changed host code on restart. (smart_restart needs systemd restartUnit and is a no-op on macOS.)

Build artifacts (lib/) are committed, so nothing is compiled at install time — the install is a checkout, not a build.

To do it by hand instead, the profile needs the package in both places:

// $DSH_HOME/profiles/web/package.json
"dependencies": { "dsh-typst-preview": "github:Limbo-137/dsh-typst-preview" },
"dsh": { "profile": { "bundles": [ /* … */ "dsh-typst-preview" ] } }

then pnpm install inside $DSH_HOME/profiles/web.

Configuration

Optional, on the plugin's row in the profile's cordis.patch.yml (or a home patch):

- id: typst-preview
  config:
    tinymistPath: tinymist          # default 'tinymist' (PATH lookup, then the fallback dirs)
    extraArgs: []                   # extra argv for `tinymist preview`, e.g. ['--font-path', '/path/to/fonts']
    maxInstances: 4                 # live preview processes, LRU-evicted, default 4
    readyTimeoutMs: 20000           # first page deadline, default 20s
    idleTimeoutMs: 1800000          # idle reaper, default 30min
    highlight: true                 # highlight the source face; false = the paged plain-text reader
    highlightLines: 800             # lines per highlighted page, default 800
    highlightMaxBytes: 4194304      # files above this stay plain, default 4 MiB
    highlightIdleTimeoutMs: 600000  # idle reaper for highlighting language servers, default 10min
    highlightMaxServers: 2          # highlighting language servers kept at once, one per project root

extraArgs is shared: they are passed to tinymist preview and to tinymist lsp alike, so a --font-path for a document that needs it applies to both faces.

Memory and process hygiene

A tinymist preview costs 200–600 MB, so this plugin treats every child as a resource that must stay reachable:

• One process per file. Two requests for the same file at the same moment (a remount, a second pane, a reload racing the first request) share one spawn. Without that, the loser of the race is overwritten in the instance map and no code path can ever kill it again.
• Every child is tracked separately from the reusable set, and close, the reaper and shutdown act on that superset — so a child that leaves the live set for any reason is still killable by token.
• LRU cap (maxInstances, default 4) evicts by killing, and a hard ceiling of twice that catches anything the cap misses.
• Two reapers: an idle one (default 30 min of no requests) and an orphan one that kills, after 60 s, any child no key claims any more — the safety net for a close request the browser never delivered. A preview with a live relay socket is never idle: "nobody is watching" cannot be inferred from request timestamps, because a page nobody recompiles makes no requests at all.
• Exit hook: a graceful host exit SIGKILLs whatever is still running, so a restart does not leave orphans behind.

GET /api/typst-preview/status reports both processes (every child) and instances (the reusable ones); the two disagreeing is the shape of a leak. scripts/leak-check.mjs asserts exactly that against the real process table.

How it works

Layer	Responsibility
src/index.ts (host)	Five routes: POST /api/typst-preview/open, POST …/close, POST …/source, GET …/status, the prefix proxy GET …/p/<token>/…, plus one exact upgrade route per instance, GET /api/typst-preview/ws/<token>. Same-origin fence: requests whose sec-fetch-site is cross-site, or whose Origin host differs from Host, are refused.
src/host/tinymist.ts	One preview process per (session × absolute path × colour mode). Ports are picked by binding 0 twice and releasing, so an instance never collides with tinymist's fixed default pair 23625/23626. The preview root is the nearest typst.toml, else the session workspace when it contains the file, else the file's directory. Readiness is polled before the tab reports success.
src/host/highlight.ts	Typst syntax highlighting from tinymist lsp. Its semanticTokens/full answer is decoded down to per-line runs of [start, end, classIndex, styleBits] over UTF-16 offsets, so the browser half paints spans without shipping a grammar. One language server per project root, each file cached by content hash, so turning a page costs no token request; position encoding is asserted to be UTF-16 rather than assumed, because the runs index JavaScript strings and UTF-8 offsets would slice CJK lines at the wrong characters. The static app highlighter cannot do this: its shiki instance bundles a fixed grammar table and Typst is not in it.
src/host/proxy.ts	HTTP passthrough with the prefix stripped (forcing accept-encoding: identity so the HTML rewrite is safe), plus exactly one edit to the served page: new URL("/", window.location.href) — the page's only absolute address — is rewritten to the instance's WebSocket route. The WebSocket handshake and every frame are relayed verbatim.
src/client/index.tsx (browser)	Registers the tab type on ctx.sidebarRightTabs and the body in the keyed sidebar.right.pane.tab seat. The source face asks POST …/source first and falls back to ctx.remote.workspaceFiles.read (the paged plain-text reader) with the shared code renderer when highlighting is unavailable, so the face always shows something. Token class names map onto the shell's own --shiki-* custom properties, so the colours are the app's code-block palette in both themes. Locale strings in English and Chinese.

Because both halves talk to tinymist through the DSH origin, the preview works over localhost, a LAN address, or a tunnel — there is no second port to expose.

One DSH detail worth knowing if you write against this: Remote methods such as workspaceFiles.read resolve to a result envelope ({ ok: true, value } / { ok: false, error }), not to the bare payload. The browser half unwraps it in its inject face and raises the failure as an exception.

Verification

Both scripts run against a real tinymist; nothing is mocked.

# Host half: apply() → a fake web server with the same exact/prefix/upgrade dispatch → real processes
node scripts/smoke.mjs
#   open starts an instance, the page is proxied, its WebSocket URL is rewritten,
#   the relay delivers real frames, a second open reuses the instance, the source
#   route answers with text plus token runs (and a page window, and a refusal),
#   close reaps it, an unknown page token answers a readable page rather than JSON,
#   and a cross-site request is refused — 20/20.

# Host half: the preview fleet against the OS process table
node scripts/leak-check.mjs
#   two simultaneous opens of one file share a token and one child; the LRU cap
#   kills what it evicts; a child removed from the instance map is still closable
#   and still counted; the reaper collects a stray but spares a preview that still
#   holds a socket; dispose leaves nothing alive — 15/15.

# Browser half: the built client bundle loaded the way the shell loads it, rendered
# with React's static renderer against a page the host really highlighted
node scripts/render-check.mjs
#   a real tinymist page becomes one row per line with line numbers, `#set` is a
#   keyword span, `*strong*` carries the style bit, the CJK comment is exact, and
#   every character of the file survives rendering — 8/8.

# Browser half: headless Chrome over CDP against a running DSH Web
printf '= Probe\nHello $x^2$\n' > /path/to/workspace/probe-typst.typ
node scripts/gui-check.mjs "http://127.0.0.1:3080/?token=…" probe-typst.typ
#   the client bundle loads, the right Sidebar opens, clicking the probe .typ lands in
#   this plugin's tab, the iframe points at the plugin's proxy path, the host serves the
#   rewritten page, the source face reads text, switching back keeps the iframe alive,
#   no typst-related console errors — 14/14.

gui-check.mjs prints diagnostics on failure (panel text, the read-only globalThis.__dshTypstDebug snapshot, and one direct open round-trip).

Known limits

• Read-only. The source face is a viewer, not an editor; edits come from the agent's write tools or an external editor, and the preview follows them.
• Sidebar tab state is in memory: a page refresh returns the Sidebar to its collapsed state (native Sidebar behaviour, not this plugin's).
• One tinymist process per open file, capped by maxInstances and LRU-evicted. Ports are allocated per instance rather than reusing the fixed 23625.
• --invert-colors=auto is tinymist's own interpretation; on a dark DSH theme, switch the toolbar to the inverted mode if auto does not match.
• Only .typ under dsh-resource://file/** (case-insensitive) is claimed. Files outside the workspace work too, through their absolute address.

License

MIT