Claude's answers, rendered: Markdown, math, charts and diagrams drawn in the Claude Code terminal. Independent project, not affiliated with Anthropic.
TypeScript claude-code-mod
// Typst on the host: finding it, measuring the fonts, and compiling an
// answer's segments to PNG pages (with a retry in safe mode).
import type { EngineInterface } from 'claude-code'
import { COMPILE_TIMEOUT_MS, MAX_IMAGE_ROWS, NO_NETWORK, TOUCH_FLUSH_MS, TYPST_FALLBACKS } from './settings'
import { DEFAULT_METRICS, fauxBoldOf, S, type Cell, type FontMetrics, type Job, type LeanFonts, type Metrics, type Page, type Result } from './state'
import { firstLine, imagePathOf, localImages, plainOf, seamsOf, splitInTwo, splitSegments } from './markdown'
import { segmentBudget } from './terminal'
import { fontFit, placeFirstLine, sizing } from './draw'
import { DEFAULT_GRID, gridOf } from './grid'
import { HEADERS_SH, perlFor } from './host'
import { logDebug } from './log'
import { positionsOf, type Mark, type Positions } from './copy'
import { hasBoldFace, leanFontsFor } from './fonts'
import { flipFile } from './flip'
import { delay, getenv, exists, ls, cat, write, exec, spawn } from './api'
// The typst command and its environment. Network off (see NO_NETWORK) and a
// package cache of our own, so only the vendored packages load, and the
// fonts of S.fontPaths (Ghostty's own font). `fonts`:
// the lean font folder (fonts.ts) in place of all system fonts. `run`: the
// root that STAGE_SH made, so the answer's code reads no other file.
export function typstCall(o: {
typst: string
root: string
run: string
cache: string
ppi: number
inputs: Readonly<Record<string, string | number>>
out: string
fonts?: string
}): { argv: string[]; env: Record<string, string> } {
const argv = [
o.typst, 'compile',
'--root', o.run,
'--package-path', `${o.root}/render/packages`,
...fontArgs(o.fonts),
'--format', 'png',
'--diagnostic-format', 'short',
'--ppi', o.ppi.toFixed(4),
...Object.entries(o.inputs).flatMap(([k, v]) => ['--input', `${k}=${v}`]),
templateIn(o.run, o.root),
o.out,
]
return { argv, env: noNetworkEnv(o.cache) }
}
// ---- The root of a compile: only the files the mod puts there -------------
// md.typ evals the answer's ```typst blocks (and math), and Typst lets code
// read any file under its root. So a compile and a probe of answer text run
// with a root of their own: a new private folder in the key folder, with
// each file the template needs at its own path (so the inputs and doc.json
// keep their paths). STAGE_SH makes it, from $1 the folder, $2 the plugin
// root, $3 the doc JSON's path (its text on stdin), $4 the theme folder and
// then the allowed images (all paths as rootPathOf gives them):
// - render/: md.typ copied (Typst wants its main file inside the root) and
// links to the rest of the plugin's render folder;
// - the doc JSON, a file of its own (a compile of the same key at the same
// time has its own folder);
// - a link to the theme folder (a built-in one is in render/ already);
// - a link to each image (and each image its SVG links to) that is a file
// with an image name, also after its links (so a link named .png to
// another file is not one). An image under a linked folder is there
// already, and no folder is made through a link.
// Typst follows the links; any other path is not found, and `..` can not
// leave the root.
export const STAGE_SH = [
'umask 077',
'r=$1 p=$2 d=$3 t=$4',
'shift 4',
'mkdir "$r" && mkdir -p "$r$p/render" "$r${d%/*}" || exit 1',
'ln -s "$p"/render/* "$r$p/render/" && rm "$r$p/render/md.typ" && cp "$p/render/md.typ" "$r$p/render/md.typ" && cat > "$r$d" || exit 1',
'case $t in',
' "$p/render/"*) ;;',
' /?*) if [ -d "$t" ] && [ ! -e "$r$t" ]; then mkdir -p "$r${t%/*}" && ln -s "$t" "$r$t" || exit 1; fi ;;',
'esac',
'for f; do',
' case $f in',
' *//*|*/./*|*/../*|*/.|*/..|"$p/render/"*|"$t/"*) continue ;;',
' /?*) ;;',
' *) continue ;;',
' esac',
' g=$f n=0',
' while [ -L "$g" ] && [ $n -lt 40 ]; do',
' l=$(readlink "$g") || break',
' case $l in /*) g=$l ;; *) g=${g%/*}/$l ;; esac',
' n=$((n + 1))',
' done',
' [ -L "$g" ] && continue',
' case $(printf %s "${g##*/}" | tr A-Z a-z) in',
' *.png|*.jpg|*.jpeg|*.gif|*.svg|*.webp) [ -f "$g" ] && [ ! -e "$r$f" ] && mkdir -p "$r${f%/*}" && ln -s "$g" "$r$f" ;;',
' esac',
'done',
'exit 0',
].join('\n')
// A path as Typst reads it in its root: `.`, `..` and empty parts resolved
// by name; null when `..` goes above the root.
export function rootPathOf(path: string): string | null {
const parts: string[] = []
for (const part of path.split('/')) {
if (part === '' || part === '.') continue
if (part !== '..') parts.push(part)
else if (parts.pop() === undefined) return null
}
return `/${parts.join('/')}`
}
// The template's main file in a run folder.
export const templateIn = (run: string, root: string) => `${run}${rootPathOf(root) ?? ''}/render/md.typ`
// The doc JSON the template reads: the base folder, the segments and the
// allow-list of images (path and full path of each, existingImages), and
// the seams (the gaps at the breaks) when there is more than one segment.
export type Doc = { base: string; segments: readonly string[]; images: readonly string[]; seams?: ([string, string] | null)[] }
// The doc of a compile (and of its probe: the same seams).
export const docOf = (base: string, segments: readonly string[], images: readonly string[]): Doc =>
({ base, segments, images, ...(segments.length > 1 ? { seams: seamsOf(segments) } : {}) })
// The full paths of a doc's allowed images (the odd entries), as in the root.
export const imageFullsOf = (images: readonly string[]) =>
images.filter((_, i) => i % 2 === 1).map(rootPathOf).filter((p): p is string => !!p)
// The arguments of STAGE_SH for a run folder: the images by their full
// paths (and the images their SVGs link to), each once.
export function stageArgs(run: string, root: string, docPath: string, themeDir: string, images: readonly string[], linked: readonly string[] = []): string[] {
return [run, rootPathOf(root) ?? '', rootPathOf(docPath) ?? '', rootPathOf(themeDir) ?? '', ...new Set([...imageFullsOf(images), ...linked])]
}
const IMAGE_NAME = /\.(png|jpe?g|gif|svg|webp)$/i
// The images an SVG at `full` links to by a relative path (Typst loads them
// from the SVG's folder in the root; it refuses absolute ones), as paths in
// the root.
export function svgLinksOf(svg: string, full: string): string[] {
const dir = full.replace(/\/[^/]*$/, '')
const found: string[] = []
for (const m of svg.matchAll(/\bhref\s*=\s*(["'])([^"']*)\1/g)) {
const href = m[2]!.trim()
if (!href || href.startsWith('#') || href.startsWith('/') || /^[a-z][a-z0-9+.-]*:/i.test(href)) continue
const path = rootPathOf(`${dir}/${href}`)
if (path && IMAGE_NAME.test(path)) found.push(path)
}
return found
}
// The images the allowed SVGs of `images` link to.
async function svgLinks($: EngineInterface, images: readonly string[]): Promise<string[]> {
const found: string[] = []
for (const full of new Set(imageFullsOf(images).filter(p => /\.svg$/i.test(p)))) {
const svg = await cat($, full).catch(() => '')
if (typeof svg === 'string') found.push(...svgLinksOf(svg, full))
}
return found
}
let runs = 0
// A new run folder's name in key folder `dir` (unique in this load, and
// random across loads and sessions).
const runFolderIn = (dir: string) => `${dir}/r-${(++runs).toString(36)}${Math.random().toString(36).slice(2, 10)}`
// Runs `use` with a root of its own for `doc` (STAGE_SH), then removes it.
// When the root can not be made, `use` still runs: Typst then finds no
// template there and fails (never a wider root); the folder is left to the
// 2-day sweep (it may be another run's, when its name was taken).
export async function inRoot<T>($: EngineInterface, job: Job, dir: string, doc: Doc, use: (run: string) => Promise<T>): Promise<T> {
const run = runFolderIn(dir)
const args = stageArgs(run, job.env.root, `${dir}/doc.json`, job.themeDir, doc.images, await svgLinks($, doc.images))
const made = await exec($, ['sh', '-c', STAGE_SH, 'sh', ...args], { stdin: JSON.stringify(doc), timeoutMs: 10000 }).catch(() => null)
if (made?.exitCode !== 0) await logDebug($, job.env.cache, `the root ${run} could not be made: ${made?.stderr ?? 'sh did not run'}`)
try {
return await use(run)
} finally {
if (made?.exitCode === 0) void Promise.resolve(exec($, ['rm', '-rf', run], { timeoutMs: 10000 })).catch(() => undefined)
}
}
// The arguments that load only the fonts of a lean folder (and Typst's own).
export const fontArgs = (fonts?: string) => (fonts ? ['--ignore-system-fonts', '--font-path', fonts] : [])
// The typst command that makes a PNG of a JPEG, WebP or SVG (render/convert.typ)
// that fits `box` (in pixels), never larger than its own pixel size: at 72
// ppi, 1 pt is 1 pixel. For a PDF, `page` is the page (it fits the box,
// larger too), and the errors are in the human format: only it has the
// hint with the page count of a page that does not exist. It runs no
// answer code, so it keeps the root at / (it only reads the file).
export function convertCall(o: {
typst: string
root: string
cache: string
file: string
box: { width: number; height: number }
out: string
page?: number
}): { argv: string[]; env: Record<string, string> } {
const argv = [
o.typst, 'compile',
'--root', '/',
'--format', 'png',
'--diagnostic-format', o.page ? 'human' : 'short',
'--ppi', '72',
'--input', `f=${o.file}`,
'--input', `maxw=${o.box.width}`,
'--input', `maxh=${o.box.height}`,
...(o.page ? ['--input', `page=${o.page}`] : []),
`${o.root}/render/convert.typ`,
o.out,
]
return { argv, env: noNetworkEnv(o.cache) }
}
// A pasted image's preview made to fill `box` pixels (the cells it is drawn
// in) exactly (render/fill.typ), in the root `run` that FILL_SH made: the
// pasted file is /image.png there, and Typst reads no other file.
export function fillCall(o: { typst: string; run: string; cache: string; box: { width: number; height: number }; fit?: 'cover' | 'contain'; out: string }): {
argv: string[]
env: Record<string, string>
} {
const argv = [
o.typst, 'compile',
'--root', o.run,
'--format', 'png',
'--diagnostic-format', 'short',
'--ppi', '72',
'--input', 'f=/image.png',
'--input', `maxw=${o.box.width}`,
'--input', `maxh=${o.box.height}`,
...(o.fit === 'contain' ? ['--input', 'fit=contain'] : []),
`${o.run}/fill.typ`,
o.out,
]
return { argv, env: noNetworkEnv(o.cache) }
}
// The root of a fill: a new private folder ($1) with fill.typ copied from
// the plugin root ($2) (Typst wants its main file inside the root) and a
// link image.png to the pasted file ($3), which must be a .png file, not a
// link. A copy or link that fails removes the new folder.
export const FILL_SH = [
'umask 077',
'r=$1 p=$2 f=$3',
'case $f in /*.png) ;; *) exit 1 ;; esac',
'[ -f "$f" ] && [ ! -L "$f" ] || exit 1',
'mkdir "$r" || exit 1',
'cp "$p/render/fill.typ" "$r/fill.typ" && ln -s "$f" "$r/image.png" || { rm -rf "$r"; exit 1; }',
].join('\n')
export function noNetworkEnv(cache: string): Record<string, string> {
return {
HTTPS_PROXY: NO_NETWORK,
HTTP_PROXY: NO_NETWORK,
ALL_PROXY: NO_NETWORK,
https_proxy: NO_NETWORK,
http_proxy: NO_NETWORK,
all_proxy: NO_NETWORK,
NO_PROXY: '',
no_proxy: '',
TYPST_PACKAGE_CACHE_PATH: `${cache}/pkg-cache`,
// The user's own folders stay (':' is the separator on macOS and Linux).
...fontPathsEnv(cache),
}
}
// TYPST_FONT_PATHS with no empty entries (Typst stops at one); a folder that
// is not there when the user's value has only empty entries.
function fontPathsEnv(cache: string): { TYPST_FONT_PATHS?: string } {
const paths = [...S.userFontPaths.split(':'), S.fontPaths].filter(Boolean).join(':')
return paths ? { TYPST_FONT_PATHS: paths } : S.userFontPaths ? { TYPST_FONT_PATHS: `${cache}/no-fonts` } : {}
}
// Width and height from a PNG's first 24 bytes (signature, then IHDR).
export function pngSize(bytes: readonly number[]): { width: number; height: number } | null {
const sig = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]
if (bytes.length < 24 || sig.some((v, i) => bytes[i] !== v)) return null
const at = (i: number) => ((bytes[i]! << 24) | (bytes[i + 1]! << 16) | (bytes[i + 2]! << 8) | bytes[i + 3]!) >>> 0
const width = at(16)
const height = at(20)
return width && height ? { width, height } : null
}
// `od -An -v -tx1` output for several files, each followed by a line `@`.
export function parseOd(stdout: string): number[][] {
return stdout
.split(/^@$/m)
.slice(0, -1)
.map(part => part.split(/\s+/).filter(Boolean).map(hex => Number.parseInt(hex, 16)))
}
// Any failed compile is tried once more with `safe=1`: the template then
// shows typst fences and math as code and images as alt boxes, which is how
// a bad typst block or an unknown LaTeX command still draws.
export function shouldRetrySafe(exitCode: number): boolean {
return exitCode !== 0
}
export async function findTypst($: EngineInterface): Promise<string | null> {
for (const flag of ['-lc', '-c']) {
const got = await exec($, ['sh', flag, 'command -v typst'], { timeoutMs: 5000 }).catch(() => null)
const path = got?.exitCode === 0 ? firstLine(got.stdout) : ''
if (path.startsWith('/')) return path
}
const home = (await getenv($, 'HOME').catch(() => undefined)) ?? ''
for (const each of TYPST_FALLBACKS) {
if (each.startsWith('~/') && !home) continue
const path = each.startsWith('~/') ? `${home}${each.slice(1)}` : each
if (await exists($, path).catch(() => false)) return path
}
return null
}
// The argv that measures the fonts: the active theme's body and code fonts
// (theme.typ reads theme.json, which needs `--root /`).
export const measureCall = (typst: string, root: string, family: string, themeDir: string) => [
typst, 'eval', 'query(<m>).first().value', '--in', `${root}/render/measure.typ`, '--root', '/',
'--input', `term-font=${family}`, '--input', `theme-dir=${themeDir}`,
]
// The theme's font lists of a measure, when they are lists of names.
export function leanFontsOf(v: unknown): LeanFonts | undefined {
const f = v as Partial<LeanFonts> | null | undefined
const names = (x: unknown): x is string[] => Array.isArray(x) && x.every(n => typeof n === 'string')
return f && names(f.body) && names(f.code) && typeof f.plain === 'boolean' ? { body: f.body, code: f.code, plain: f.plain } : undefined
}
// The fonts' metrics from render/measure.typ; the macOS defaults when that
// fails. With the font list (in the same time): whether the terminal's font
// has a bold face.
export async function measureFonts($: EngineInterface, typst: string, root: string, cache: string, family: string, themeDir: string): Promise<Metrics> {
const argv = measureCall(typst, root, family, themeDir)
const env = noNetworkEnv(cache)
const [got, listed] = await Promise.all([
exec($, argv, { timeoutMs: 10000, env }).catch(() => null),
family ? exec($, [typst, 'fonts', '--variants'], { timeoutMs: 10000, env }).catch(() => null) : null,
])
try {
const m = JSON.parse(got?.stdout ?? '') as Metrics
const ok = (x: FontMetrics | null | undefined) => !!x && x.adv > 0 && x.xh > 0 && x.avg > 0
const fonts = leanFontsOf(m.fonts)
const bold = listed?.exitCode === 0 ? hasBoldFace(listed.stdout, family) : null
if (ok(m.menlo) && ok(m.body)) {
return { term: ok(m.term) ? m.term : null, menlo: m.menlo, body: m.body, grid: gridOf(m.grid) ?? DEFAULT_GRID, ...(fonts ? { fonts } : {}), ...(bold === null ? {} : { termBold: bold }) }
}
} catch {}
return DEFAULT_METRICS
}
export { logDebug } from './log'
// The images that exist, for the template's allow-list: it draws any other
// as its alt, so one bad path doesn't fail the page.
export async function existingImages($: EngineInterface, segments: readonly string[], base: string): Promise<string[]> {
const found: string[] = []
for (const path of new Set(segments.flatMap(localImages))) {
const full = imagePathOf(path, base)
if (await exists($, full).catch(() => false)) found.push(path, full)
}
return found
}
// The template's inputs for the room of a drawing (pt): the room height, and
// the design's page width and room height.
export function roomInputs(room: Job['room']): Record<string, number> {
if (!room) return {}
const pt = (v: number) => Math.round(v * 100) / 100
return { height: pt(room.heightPt), 'design-w': pt(room.design.widthPt), 'design-h': pt(room.design.heightPt) }
}
// The rows a page of `height` pixels takes in cells of `cell` (the template
// pads each page to whole rows, so this rounds).
export const pageRowsOf = (height: number, cell: Cell) => Math.max(1, Math.round(height / cell.height))
// A kept pages.json as a Result; null when it is not one (an older format).
export function resultOf(text: string): Result | null {
try {
const r = JSON.parse(text) as Result
const isPage = (p: Page) => !!p && typeof p.file === 'string' && p.columns > 0 && p.rows > 0
return Array.isArray(r.pages) && r.pages.length > 0 && r.pages.every(isPage) ? r : null
} catch {
return null
}
}
// Paths in use (key folders, design files): their mtime is set to now, so
// the cleanups go by use. touchLater only notes the path (no process in a
// render path); one `touch -c` runs per TOUCH_FLUSH_MS for at most
// TOUCH_BATCH paths, the rest wait for the next run.
export const TOUCH_BATCH = 200
const TOUCH_KEPT = 4096
// The paths not touched yet (empty after each flush; answer.ts keeps the
// keys touched in this load, so a redraw does not note them again).
const toTouch = new Set<string>()
let touchTimer: { cancel: () => void } | null = null
export function touchLater($: EngineInterface, path: string) {
if (toTouch.size >= TOUCH_KEPT && !toTouch.has(path)) return
toTouch.add(path)
if (touchTimer) return
touchTimer = delay($, TOUCH_FLUSH_MS, () => {
touchTimer = null
const paths = [...toTouch].slice(0, TOUCH_BATCH)
for (const each of paths) toTouch.delete(each)
if (paths.length) void Promise.resolve(exec($, ['touch', '-c', ...paths], { timeoutMs: 5000 })).catch(() => undefined)
if (toTouch.size) touchLater($, toTouch.values().next().value!)
})
}
// Clears the paths not touched yet and the timer (for tests).
export function forgetTouches() {
touchTimer?.cancel()
touchTimer = null
toTouch.clear()
}
// A command with a PID line first: `sh` writes its own PID, then becomes
// the command (exec keeps the PID), so `kill <pid>` stops the command.
export const wrapPid = (argv: readonly string[]): string[] => ['sh', '-c', 'echo $$; exec "$@"', 'sh', ...argv]
// How a run ended: `isCancelled` when `signal` stopped it (its output does
// not count).
export type Ran = { exitCode: number; stdout: string; stderr: string; isCancelled?: boolean }
// Runs `argv` through wrapPid with $.process.spawn: its stdout (less the PID
// line) and stderr, and its exit code (1 when a signal ended it). `signal`
// and the timeout (`timeoutMs`, on $.clock) kill it by its PID; a timeout
// ends with exit 1 and stderr `timed out`.
export async function runKillable(
$: EngineInterface,
argv: readonly string[],
o: { env?: Record<string, string>; signal?: AbortSignal; timeoutMs: number },
): Promise<Ran> {
if (o.signal?.aborted) return { exitCode: 1, stdout: '', stderr: 'cancelled', isCancelled: true }
let pid = ''
let head = ''
let stdout = ''
let stderr = ''
let why: 'cancel' | 'timeout' | null = null
let isKillSent = false
const killNow = () => {
if (!why || !pid || isKillSent) return
isKillSent = true
void Promise.resolve(exec($, ['kill', pid], { timeoutMs: 5000 })).catch(() => undefined)
}
const stop = (reason: 'cancel' | 'timeout') => {
if (why) return
why = reason
killNow()
}
const onAbort = () => stop('cancel')
o.signal?.addEventListener('abort', onAbort, { once: true })
const timer = delay($, o.timeoutMs, () => stop('timeout'))
let code: number | null = 1
try {
const child = spawn($, { argv: wrapPid(argv), ...(o.env ? { env: o.env } : {}) })
for (;;) {
const got = await child.next()
if (got.done) {
code = got.value?.code ?? 1
break
}
const { stream, text } = got.value
if (stream === 'stderr') stderr += text
else if (pid) stdout += text
else {
head += text
const at = head.indexOf('\n')
if (at >= 0) {
pid = head.slice(0, at).trim()
stdout += head.slice(at + 1)
head = ''
if (!/^\d+$/.test(pid)) pid = ''
killNow()
}
}
}
} catch (err: unknown) {
stderr += `${stderr ? '\n' : ''}typst did not run: ${String(err)}`
code = 1
} finally {
timer.cancel()
o.signal?.removeEventListener('abort', onAbort)
}
// A cancel that came after typst ended (before its end was read) drops a
// whole result too: the key compiles again (rare, and accepted).
if (why === 'cancel') return { exitCode: 1, stdout, stderr, isCancelled: true }
if (why === 'timeout') return { exitCode: 1, stdout, stderr: 'timed out' }
return { exitCode: code, stdout, stderr }
}
// The first page's top margin and bullet row of a job's text.
function firstLinePlace(job: Job, segments: readonly string[]) {
const fit = fontFit(job.env.metrics, job.size)
const { rowPt } = sizing(job.columns, job.cell, fit.columnPt)
const metrics = job.env.metrics.grid ?? DEFAULT_GRID
const grid = job.grid ? { metrics, code: fit.code } : undefined
return placeFirstLine(segments[0] ?? '', rowPt, grid, metrics)
}
// The template's inputs for a job and its ppi (the PNG compile and the
// probe share them). With the row grid, `grid` is 1 and `top` 0.
export function typstInputs(job: Job, segments: readonly string[], dir: string, isSafe: boolean) {
const fit = fontFit(job.env.metrics, job.size)
const { widthPt, ppi, rowPt } = sizing(job.columns, job.cell, fit.columnPt)
const { topPt } = firstLinePlace(job, segments)
const inputs: Record<string, string | number> = {
theme: job.theme,
width: widthPt,
top: topPt,
row: Math.round(rowPt * 10000) / 10000,
...(job.grid ? { grid: 1 } : {}),
code: fit.code,
...(job.env.termFont ? { 'term-font': job.env.termFont } : {}),
...(fauxBoldOf(job.env.metrics) ? { 'term-bold': 0 } : {}),
'theme-dir': job.themeDir,
doc: `${dir}/doc.json`,
...roomInputs(job.room),
...(isSafe ? { safe: 1 } : {}),
}
return { inputs, ppi }
}
// The lean font folder for a job's segments ('' none: all fonts), noted as in use.
async function leanFor($: EngineInterface, job: Job, segments: readonly string[]): Promise<string> {
const fonts = await leanFontsFor($, job.env, segments, noNetworkEnv(job.env.cache)).catch(() => '')
if (fonts) touchLater($, fonts)
return fonts
}
// Runs a typst command with the lean fonts, else with all fonts. A lean
// run that fails (not one that was cancelled or timed out) runs once more
// with all fonts, so the lean set never makes a failure of its own.
async function runFonts($: EngineInterface, job: Job, fonts: string, run: (fonts?: string) => Promise<Ran>): Promise<Ran> {
if (!fonts) return run()
const ran = await run(fonts)
if (ran.exitCode === 0 || ran.isCancelled || ran.stderr === 'timed out') return ran
await logDebug($, job.env.cache, `typst for ${job.key} with the lean fonts failed (now with all fonts):\n${ran.stderr}`)
return run()
}
export async function runTypst($: EngineInterface, job: Job, doc: Doc, dir: string, tag: string, isSafe: boolean, signal?: AbortSignal): Promise<Ran> {
const { inputs, ppi } = typstInputs(job, doc.segments, dir, isSafe)
const fonts = await leanFor($, job, doc.segments)
return inRoot($, job, dir, doc, run => runFonts($, job, fonts, fonts => {
const { argv, env: vars } = typstCall({ typst: job.env.typst!, root: job.env.root, run, cache: job.env.cache, ppi, inputs, out: `${dir}/${tag}-{0p}.png`, ...(fonts ? { fonts } : {}) })
return runKillable($, argv, { env: vars, timeoutMs: COMPILE_TIMEOUT_MS, ...(signal ? { signal } : {}) })
}))
}
// ---- The probe: where the words are ---------------------------------------
// `typst query` of the template's <mdpos> marks with probe=1: the PNG
// compile's own inputs (and `page`), root (a run folder of its own), package
// path, fonts and env (no ppi, format or out).
export function probeCall(o: { typst: string; root: string; run: string; cache: string; inputs: Readonly<Record<string, string | number>>; fonts?: string }): { argv: string[]; env: Record<string, string> } {
const argv = [
o.typst, 'query',
'--root', o.run,
'--package-path', `${o.root}/render/packages`,
...fontArgs(o.fonts),
'--diagnostic-format', 'short',
...Object.entries({ ...o.inputs, probe: 1 }).flatMap(([k, v]) => ['--input', `${k}=${v}`]),
templateIn(o.run, o.root),
'<mdpos>',
'--field', 'value',
]
return { argv, env: noNetworkEnv(o.cache) }
}
// A drawn page's file says how it was compiled: `b` and `d` (the split
// retry) are the safe mode's tags (`f` before them: stored for flip mode).
export const isSafePage = (file: string) => /\/f?[bd]-\d+\.png$/.test(file)
// The word positions of page `page` (0-based) of a key folder: the probe
// of that page only (page=<n>), with the inputs of the PNG compile, built
// from the Job that drew it and the segments in its doc.json. Null when it
// fails, or when doc.json does not hold one segment per page drawn (a split
// retry that failed keeps the pages of the first compile).
export async function probePage(
$: EngineInterface, job: Job, dir: string, o: { page: number; pages: number; isSafe: boolean },
): Promise<Positions | null> {
let kept: Partial<Doc> | null = null
try {
kept = JSON.parse((await cat($, `${dir}/doc.json`)) as string) as Partial<Doc>
} catch {
return null
}
const segments = kept?.segments
if (!Array.isArray(segments) || segments.length !== o.pages || !job.env.typst) return null
const typst = job.env.typst
const images = Array.isArray(kept!.images) ? kept!.images.filter((p): p is string => typeof p === 'string') : []
const doc = docOf(typeof kept!.base === 'string' ? kept!.base : '', segments, images)
const { inputs, ppi } = typstInputs(job, segments, dir, o.isSafe)
const fonts = await leanFor($, job, segments)
const ran = await inRoot($, job, dir, doc, run => runFonts($, job, fonts, fonts => {
const { argv, env } = probeCall({ typst, root: job.env.root, run, cache: job.env.cache, inputs: { ...inputs, page: o.page + 1 }, ...(fonts ? { fonts } : {}) })
return runKillable($, argv, { env, timeoutMs: COMPILE_TIMEOUT_MS })
}))
if (ran.exitCode !== 0) {
await logDebug($, job.env.cache, `probe ${dir} page ${o.page + 1} failed:\n${ran.stderr}`)
return null
}
try {
return positionsOf(JSON.parse(ran.stdout) as Mark[], ppi)
} catch {
return null
}
}
// The pages of one run: its PNGs (by tag) in order, with their sizes and
// the box each takes. Null when there are none or a size can not be read.
async function pagesOfRun($: EngineInterface, job: Job, dir: string, tag: string, segments: readonly string[]): Promise<Page[] | null> {
const files = (await ls($, dir))
.filter(f => f.kind === 'file' && f.name.startsWith(`${tag}-`) && f.name.endsWith('.png'))
.map(f => f.name)
.sort((x, y) => Number(x.replace(/\D/g, '')) - Number(y.replace(/\D/g, '')))
.map(name => `${dir}/${name}`)
if (!files.length) return null
const heads = await exec($, ['sh', '-c', HEADERS_SH, 'sh', ...files])
const sizes = parseOd(heads.stdout).map(pngSize)
if (sizes.length !== files.length || sizes.some(s => !s)) {
await logDebug($, job.env.cache, `compile ${job.key}: could not read PNG sizes`)
return null
}
return files.map((file, i) => ({
file, ...sizes[i]!, alt: plainOf(segments[i] ?? job.text), columns: job.columns, rows: pageRowsOf(sizes[i]!.height, job.cell),
}))
}
// Compiles a job's text to its pages (kept in its key folder). `signal`
// stops it: a run killed by it, or a retry not begun, is 'cancelled' (not a
// result: nothing is kept).
export async function compile($: EngineInterface, job: Job, signal?: AbortSignal): Promise<Result | 'failed' | 'cancelled'> {
const dir = `${job.env.cache}/${job.key}`
const kept = await cat($, `${dir}/pages.json`).catch(() => null)
const keptResult = kept ? resultOf(kept) : null
if (keptResult) {
touchLater($, dir)
return keptResult
}
if (signal?.aborted) return 'cancelled'
const { rowPt } = sizing(job.columns, job.cell, fontFit(job.env.metrics, job.size).columnPt)
// The room height of a drawing in rows (less the pt rounding); unknown
// without a room (the default applies).
const roomRows = job.room ? Math.ceil(job.room.heightPt / rowPt - 0.01) : undefined
let segments = splitSegments(job.text, job.columns, segmentBudget(job.env, job.columns, job.cell), job.size, roomRows)
const base = job.base ?? job.env.cwd
const images = await existingImages($, segments, base)
const doc = docOf(base, segments, images)
await write($, `${dir}/doc.json`, JSON.stringify(doc))
let tag = 'a'
let isSafe = false
let ran = await runTypst($, job, doc, dir, tag, false, signal)
let note: string | undefined
if (ran.isCancelled) return 'cancelled'
if (ran.exitCode !== 0) {
if (signal?.aborted) return 'cancelled'
await logDebug($, job.env.cache, `compile ${job.key} failed:\n${ran.stderr}`)
if (!shouldRetrySafe(ran.exitCode)) return 'failed'
note = firstLine(ran.stderr.split('\n').find(l => /error:/i.test(l)) ?? ran.stderr).replace(/^.*error:\s*/i, '')
tag = 'b'
isSafe = true
ran = await runTypst($, job, doc, dir, tag, true, signal)
if (ran.isCancelled) return 'cancelled'
if (ran.exitCode !== 0) {
await logDebug($, job.env.cache, `compile ${job.key} with safe=1 failed:\n${ran.stderr}`)
return 'failed'
}
}
let pages = await pagesOfRun($, job, dir, tag, segments)
if (!pages) return 'failed'
// A page taller than an Image can be (the row estimate was short): its
// segment is cut in two and the whole text compiled once more. If that
// fails, the first pages stay (drawn at most MAX_IMAGE_ROWS tall).
if (pages.some(p => p.rows > MAX_IMAGE_ROWS)) {
const cut = segments.flatMap((seg, i) => (pages![i]!.rows > MAX_IMAGE_ROWS ? splitInTwo(seg, job.columns, job.size, roomRows) : [seg]))
if (cut.length > segments.length) {
if (signal?.aborted) return 'cancelled'
const cutDoc = docOf(base, cut, images)
await write($, `${dir}/doc.json`, JSON.stringify(cutDoc))
const again = await runTypst($, job, cutDoc, dir, isSafe ? 'd' : 'c', isSafe, signal)
if (again.isCancelled) return 'cancelled'
const split = again.exitCode === 0 ? await pagesOfRun($, job, dir, isSafe ? 'd' : 'c', cut) : null
if (split) {
pages = split
segments = cut
} else await logDebug($, job.env.cache, `compile ${job.key}: the split retry failed:\n${again.stderr}`)
}
pages = pages.map(p => ({ ...p, rows: Math.min(MAX_IMAGE_ROWS, p.rows) }))
}
// Flip mode: each page stored for herdr in iTerm2 (fa-1.png from a-1.png); a page that can not be stored fails the compile (the text shows).
if (job.flip) {
const flipped = await flipPages($, job, pages, signal)
if (typeof flipped === 'string') return flipped
pages = flipped
}
const { bulletRow } = firstLinePlace(job, segments)
const result: Result = { pages, bulletRow, ...(note ? { note } : {}) }
await write($, `${dir}/pages.json`, JSON.stringify(result))
return result
}
// The pages of a compile stored for flip mode (flip.ts: rows × B pixels
// tall, the bands reversed), each as a file of its own (`f` before its
// name: a flip of a flipped page would undo it), with the height its rows map to (flipSteps).
async function flipPages($: EngineInterface, job: Job, pages: readonly Page[], signal?: AbortSignal): Promise<Page[] | 'failed' | 'cancelled'> {
const flipped: Page[] = []
for (const p of pages) {
const out = p.file.replace(/\/([^/]*)$/, '/f$1')
const made = await flipFile($, { src: p.file, out, rows: p.rows, isPage: true, perl: perlFor(job.env.isMac), ...(signal ? { signal } : {}) })
if (signal?.aborted) return 'cancelled'
if (!made) {
await logDebug($, job.env.cache, `compile ${job.key}: could not store ${p.file} for herdr in iTerm2`)
return 'failed'
}
flipped.push({ ...p, file: out, height: made.height, flip: true })
}
return flipped
}