@lincyaw/addon-publish 0.0.0-stage → 1.0.0-rc.2

package/src/client/offline.ts

@@ -0,0 +1,29 @@
+import { OFFLINE_REQUESTS } from '@lincyaw/kernel'
+
+export interface OfflineRuntimes {
+  bytes: number
+  saved: boolean
+}
+
+async function ask<T>(type: string, timeoutMs: number): Promise<T | undefined> {
+  if (typeof navigator === 'undefined' || !navigator.serviceWorker) return undefined
+  const worker = navigator.serviceWorker.controller ?? (await navigator.serviceWorker.getRegistration())?.active
+  if (!worker) return undefined
+  return new Promise((resolve) => {
+    const channel = new MessageChannel()
+    const timer = setTimeout(() => resolve(undefined), timeoutMs)
+    channel.port1.onmessage = ({ data }: MessageEvent<T>) => {
+      clearTimeout(timer)
+      resolve(data)
+    }
+    worker.postMessage({ type }, [channel.port2])
+  })
+}
+
+export function offlineRuntimes(): Promise<OfflineRuntimes | undefined> {
+  return ask<OfflineRuntimes>(OFFLINE_REQUESTS.runtimes, 3000)
+}
+
+export async function saveOffline(): Promise<boolean> {
+  return Boolean((await ask<{ ok: boolean }>(OFFLINE_REQUESTS.save, 600_000))?.ok)
+}

package/src/client/plugin.ts

@@ -0,0 +1,34 @@
+import { currentLocale, TOOLBAR } from '@lincyaw/host'
+import type { PluginDefinition, Unsubscribe } from '@lincyaw/kernel'
+import { createElement } from 'react'
+import { version } from '../../package.json'
+import PmContrastToggle from '../../components/PmContrastToggle.tsx'
+import PmSaveOffline from '../../components/PmSaveOffline.tsx'
+import { MESSAGES, PUBLISH_ID } from '../domain/index.ts'
+import { initHighContrast } from './contrast.ts'
+import './contrast.css'
+
+const ToolbarToggle = () => createElement(PmContrastToggle, { compact: true })
+
+let unregister: Unsubscribe[] = []
+
+export const publishPlugin: PluginDefinition = {
+  manifest: { id: PUBLISH_ID, name: { 'zh-CN': '发布', en: 'Publishing' }, version, kernel: '^1.0.0', requires: [{ token: TOOLBAR, optional: true }] },
+  setup(ctx) {
+    initHighContrast()
+    const toolbar = ctx.tryGet(TOOLBAR)
+    const t = MESSAGES[currentLocale()]
+    unregister = toolbar
+      ? [
+          toolbar.register({ id: PUBLISH_ID, title: t.highContrast, component: ToolbarToggle, order: 20 }),
+          toolbar.register({ id: `${PUBLISH_ID}.offline`, title: t.savedOffline, component: PmSaveOffline, order: 21 }),
+        ]
+      : []
+  },
+  dispose() {
+    unregister.forEach(off => off())
+    unregister = []
+  },
+}
+
+export default publishPlugin

package/src/domain/assets.ts

@@ -0,0 +1,27 @@
+export const ASSETS_DIR = '.presmium/assets'
+
+export const MEDIA_EXTENSIONS = ['svg', 'png', 'jpg', 'jpeg', 'gif', 'webp', 'avif', 'ico', 'bmp', 'woff', 'woff2', 'ttf', 'otf', 'mp4', 'webm', 'ogg', 'mp3', 'wav', 'm4a', 'pdf']
+
+const TYPES: Record<string, string> = {
+  'image/svg+xml': 'svg',
+  'image/png': 'png',
+  'image/jpeg': 'jpg',
+  'image/gif': 'gif',
+  'image/webp': 'webp',
+  'image/avif': 'avif',
+  'image/x-icon': 'ico',
+  'image/vnd.microsoft.icon': 'ico',
+}
+
+export function assetExtension(url: string, contentType: string | null): string | undefined {
+  const path = (() => {
+    try {
+      return new URL(url).pathname
+    } catch {
+      return ''
+    }
+  })()
+  const ext = /\.([a-z\d]+)$/i.exec(path)?.[1]?.toLowerCase()
+  if (ext && MEDIA_EXTENSIONS.includes(ext)) return ext
+  return TYPES[(contentType ?? '').split(';')[0]!.trim().toLowerCase()]
+}

package/src/domain/config.ts

@@ -0,0 +1,14 @@
+import { isRecord } from '@lincyaw/kernel'
+
+export const PUBLISH_ID = 'presmium.publish'
+
+export interface PublishOptions {
+  offline: boolean
+}
+
+export function toPublishOptions(headmatter: unknown): PublishOptions {
+  const presmium = isRecord(headmatter) ? headmatter.presmium : undefined
+  const own = isRecord(presmium) ? presmium[PUBLISH_ID] : undefined
+  return { offline: !(isRecord(own) && own.offline === false) }
+}
+

package/src/domain/export.ts

@@ -0,0 +1,15 @@
+export function exportedSlides(count: number, range?: ReadonlySet<number>): number[] {
+  return Array.from({ length: count }, (_, i) => i + 1).filter(slide => !range || range.has(slide))
+}
+
+export function parseRange(range: string | undefined): Set<number> | undefined {
+  if (range === undefined) return undefined
+  const slides = new Set<number>()
+  for (const part of range.split(',').map(p => p.trim()).filter(Boolean)) {
+    const match = /^(\d+)(?:-(\d+))?$/.exec(part)
+    if (!match) throw new Error(`invalid range "${range}"`)
+    const from = Number(match[1])
+    for (let n = from; n <= Number(match[2] ?? from); n++) slides.add(n)
+  }
+  return slides
+}

package/src/domain/index.ts

@@ -0,0 +1,10 @@
+export { ASSETS_DIR, assetExtension, MEDIA_EXTENSIONS } from './assets.ts'
+export { PUBLISH_ID, toPublishOptions } from './config.ts'
+export type { PublishOptions } from './config.ts'
+export { exportedSlides, parseRange } from './export.ts'
+export { linkLine, normalizeUrl, slideLinks } from './links.ts'
+export type { DeclaredLink } from './links.ts'
+export { MESSAGES } from './messages.ts'
+export type { PublishMessages } from './messages.ts'
+export { diffReport, pageStatus, pairPages, parsePageFile, parseWebFile, reportMarkdown } from './visual-diff.ts'
+export type { DiffSide, PageRef, PageStatus, VisualDiff, VisualDiffReport } from './visual-diff.ts'

package/src/domain/links.ts

@@ -0,0 +1,70 @@
+import type { IRBlock, IRDocument, MdastNode, SourcePos } from '@lincyaw/kernel'
+
+export interface DeclaredLink {
+  url: string
+  slide: number
+  source: SourcePos
+}
+
+const ATTRIBUTE = /\s(?:href|to|[\w-]*link|[\w-]*url)\s*=\s*(["'])(https?:\/\/[^"']+)\1/gi
+const JSON_KEY = /"(?:href|to|[\w-]*link|[\w-]*url)"\s*:\s*"(https?:\/\/[^"\\\s]+)"/gi
+const LINK_KEY = /^(?:href|to|.*link|.*url)$/i
+
+function mdastLinks(node: MdastNode, found: string[]): void {
+  if ((node.type === 'link' || node.type === 'definition') && typeof node.url === 'string') found.push(node.url)
+  if (node.type === 'html' && typeof node.value === 'string') {
+    const html = node.value.replaceAll('"', '"')
+    found.push(...[...html.matchAll(ATTRIBUTE)].map(m => m[2]!), ...[...html.matchAll(JSON_KEY)].map(m => m[1]!))
+  }
+  node.children?.forEach(child => mdastLinks(child, found))
+}
+
+function propLinks(value: unknown, found: string[], key = ''): void {
+  if (typeof value === 'string' && LINK_KEY.test(key)) found.push(value)
+  else if (Array.isArray(value)) value.forEach(item => propLinks(item, found, key))
+  else if (typeof value === 'object' && value !== null) Object.entries(value).forEach(([k, v]) => propLinks(v, found, k))
+}
+
+function blockLinks(block: IRBlock): string[] {
+  const found: string[] = []
+  const { node } = block
+  if (node.type === 'markdown') mdastLinks(node.mdast, found)
+  else if (node.type === 'code' && node.origin?.permalink) found.push(node.origin.permalink)
+  else if (node.type === 'component') {
+    propLinks(node.props, found)
+    for (const child of node.children ?? []) found.push(...blockLinks(child))
+  }
+  return found
+}
+
+export function slideLinks(doc: IRDocument, range?: Set<number>): DeclaredLink[] {
+  const links = new Map<string, DeclaredLink>()
+  for (const section of doc.sections) {
+    const hints = section.hints.slides ?? {}
+    if (hints.hide || hints.disabled || (range && !range.has(section.index))) continue
+    for (const block of section.blocks.filter(b => b.role === 'visual')) {
+      for (const raw of blockLinks(block)) {
+        const url = /^https?:\/\//i.test(raw) ? normalizeUrl(raw.replaceAll('&amp;', '&')) : undefined
+        if (url && !links.has(url)) links.set(url, { url, slide: section.index, source: block.source })
+      }
+    }
+  }
+  return [...links.values()]
+}
+
+export function linkLine(lines: string[], url: string, from: number, to = lines.length + 1): number | undefined {
+  const forms = [url, url.replace(/\/$/, ''), url.replaceAll('&', '&amp;')].map(form => form.replace(/[.*+?^$()|[\]{}\\]/g, '\\$&'))
+  const written = new RegExp(`(?:${forms.join('|')})(?=$|[\\s"'<>)\\]])`)
+  for (let i = Math.max(from, 1); i < Math.min(to, lines.length + 1); i++) {
+    if (written.test(lines[i - 1]!)) return i
+  }
+  return undefined
+}
+
+export function normalizeUrl(url: string): string | undefined {
+  try {
+    return new URL(url).href
+  } catch {
+    return undefined
+  }
+}

package/src/domain/messages.ts

@@ -0,0 +1,23 @@
+import type { Locale } from '@lincyaw/kernel'
+
+const zhCN = {
+  highContrast: '高对比度',
+  highContrastState: (on: boolean) => `高对比度：${on ? '开' : '关'}`,
+  saveOffline: (megabytes: number) => `保存以离线使用（${megabytes} MB）`,
+  savingOffline: '正在保存以离线使用…',
+  savedOffline: '已保存，可离线使用',
+  saveOfflineFailed: '无法保存以离线使用。请联网后重试。',
+}
+
+export type PublishMessages = typeof zhCN
+
+const en: PublishMessages = {
+  highContrast: 'High contrast',
+  highContrastState: on => `High contrast: ${on ? 'on' : 'off'}`,
+  saveOffline: megabytes => `Save for Offline Use (${megabytes} MB)`,
+  savingOffline: 'Saving for offline use…',
+  savedOffline: 'Saved for offline use',
+  saveOfflineFailed: 'Couldn’t save for offline use. Please try again when online.',
+}
+
+export const MESSAGES: Record<Locale, PublishMessages> = { 'zh-CN': zhCN, en }

package/src/domain/visual-diff.ts

@@ -0,0 +1,81 @@
+export interface PageRef {
+  id: string
+  slide: number
+  step: number
+}
+
+export type PageStatus = 'same' | 'changed' | 'added' | 'removed'
+
+export interface VisualDiff extends PageRef {
+  status: PageStatus
+  ratio: number
+  diffPixels: number
+}
+
+export interface DiffSide {
+  ref: string
+  commit: string
+}
+
+export interface VisualDiffReport {
+  a: DiffSide
+  b: DiffSide
+  threshold: number
+  pages: VisualDiff[]
+  listed: VisualDiff[]
+}
+
+export function parsePageFile(name: string): PageRef | undefined {
+  const match = /^(\d+)(?:-(\d+))?\.png$/.exec(name)
+  if (!match) return undefined
+  return { id: name.slice(0, -4), slide: Number(match[1]), step: match[2] === undefined ? 0 : Number(match[2]) - 1 }
+}
+
+export function parseWebFile(name: string, sections: ReadonlyMap<string, number>): PageRef | undefined {
+  if (!name.endsWith('.png')) return undefined
+  const stem = name.slice(0, -4)
+  const present = /^present-(.+)$/.exec(stem)?.[1]
+  return { id: `web/${stem}`, slide: present === undefined ? 0 : sections.get(present) ?? 0, step: 0 }
+}
+
+export function pairPages(a: string[], b: string[], parse: (name: string) => PageRef | undefined = parsePageFile): { page: PageRef, a?: string, b?: string }[] {
+  const pages = new Map<string, { page: PageRef, a?: string, b?: string }>()
+  for (const [side, files] of [['a', a], ['b', b]] as const) {
+    for (const file of files) {
+      const page = parse(file)
+      if (page) pages.set(page.id, { page, ...pages.get(page.id), [side]: file })
+    }
+  }
+  return [...pages.values()].sort((x, y) => x.page.slide - y.page.slide || x.page.step - y.page.step || x.page.id.localeCompare(y.page.id))
+}
+
+export function pageStatus(ratio: number, threshold: number, a: boolean, b: boolean): PageStatus {
+  if (!a) return 'added'
+  if (!b) return 'removed'
+  return ratio > threshold ? 'changed' : 'same'
+}
+
+export function diffReport(a: DiffSide, b: DiffSide, threshold: number, pages: VisualDiff[]): VisualDiffReport {
+  return { a, b, threshold, pages, listed: pages.filter(page => page.status !== 'same') }
+}
+
+const percent = (ratio: number) => `${(ratio * 100).toFixed(2)}%`
+
+export function reportMarkdown(report: VisualDiffReport): string {
+  const side = (s: DiffSide) => `\`${s.ref}\` (${s.commit.slice(0, 12)})`
+  const lines = [
+    `# Visual diff: ${side(report.a)} → ${side(report.b)}`,
+    '',
+    `${report.listed.length} of ${report.pages.length} pages differ (threshold ${percent(report.threshold)}).`,
+  ]
+  if (report.listed.length > 0) {
+    lines.push('', '| Page | Slide | Step | Status | Differing pixels |', '|---|---|---|---|---|')
+    for (const p of report.listed) lines.push(`| ${p.id} | ${p.slide} | ${p.step} | ${p.status} | ${percent(p.ratio)} |`)
+    for (const p of report.listed) {
+      lines.push('', `## ${p.id}`, '')
+      const images = [p.status !== 'added' && `![a](a/${p.id}.png)`, p.status !== 'removed' && `![b](b/${p.id}.png)`, p.status === 'changed' && `![diff](diff/${p.id}.png)`]
+      lines.push(images.filter(Boolean).join(' '))
+    }
+  }
+  return `${lines.join('\n')}\n`
+}

package/src/node/assets.ts

@@ -0,0 +1,78 @@
+import { createHash } from 'node:crypto'
+import { existsSync } from 'node:fs'
+import { mkdir, readdir, rm, writeFile } from 'node:fs/promises'
+import { basename, dirname, join, relative, sep } from 'node:path'
+import { docBlocks, errorMessage, nodeMdast } from '@lincyaw/kernel'
+import type { IRBlock, IRPass, MdastNode } from '@lincyaw/kernel'
+import { ASSETS_DIR, assetExtension, PUBLISH_ID, toPublishOptions } from '../domain/index.ts'
+
+const DOWNLOAD_TIMEOUT_MS = 15_000
+
+const DOWNLOAD = /^[\da-f]{16}\.[a-z\d]+$/
+
+const failed = new Map<string, string>()
+
+function images(node: MdastNode, found: MdastNode[] = []): MdastNode[] {
+  if (node.type === 'image' && typeof node.url === 'string') found.push(node)
+  node.children?.forEach(child => images(child, found))
+  return found
+}
+
+async function localCopy(url: string, dir: string, existing: readonly string[]): Promise<string> {
+  const name = createHash('sha256').update(url).digest('hex').slice(0, 16)
+  const found = existing.find(file => file.startsWith(`${name}.`))
+  if (found) return join(dir, found)
+  const before = failed.get(url)
+  if (before !== undefined) throw new Error(before)
+  try {
+    const response = await fetch(url, { signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS) })
+    if (!response.ok) throw new Error(`HTTP ${response.status}`)
+    const ext = assetExtension(url, response.headers.get('content-type'))
+    if (!ext) throw new Error(`not an image (${response.headers.get('content-type') ?? 'no content type'})`)
+    const file = join(dir, `${name}.${ext}`)
+    await mkdir(dir, { recursive: true })
+    await writeFile(file, Buffer.from(await response.arrayBuffer()))
+    return file
+  } catch (error) {
+    failed.set(url, errorMessage(error))
+    throw error
+  }
+}
+
+export const remoteAssetsPass: IRPass = {
+  name: 'presmium.publish.remote-assets',
+  order: 100,
+  async run(doc, ctx) {
+    if (!toPublishOptions({ presmium: doc.config.presmium }).offline) return
+    const dir = join(ctx.deckDir, ASSETS_DIR)
+    const remote: { node: MdastNode, block: IRBlock }[] = []
+    for (const { block } of docBlocks(doc)) {
+      for (const node of nodeMdast(block.node).flatMap(mdast => images(mdast))) {
+        if (/^https?:\/\//i.test(node.url as string)) remote.push({ node, block })
+      }
+    }
+    const existing = existsSync(dir) ? await readdir(dir) : []
+    const urls = [...new Set(remote.map(({ node }) => node.url as string))]
+    const copies = new Map(urls.map((url, i) => [url, i]))
+    const settled = await Promise.allSettled(urls.map(url => localCopy(url, dir, existing)))
+    const used = new Set<string>()
+    for (const { node, block } of remote) {
+      const url = node.url as string
+      const copy = settled[copies.get(url)!]!
+      if (copy.status === 'fulfilled') {
+        used.add(basename(copy.value))
+        node.url = relative(dirname(block.source.file), copy.value).split(sep).join('/')
+      } else {
+        ctx.report({
+          checkId: PUBLISH_ID,
+          severity: 'warning',
+          message: `remote image ${url} was not downloaded (${errorMessage(copy.reason)}); it needs network when presenting`,
+          source: { file: block.source.file, line: block.source.line },
+        })
+      }
+    }
+    for (const file of existing) {
+      if (DOWNLOAD.test(file) && !used.has(file)) await rm(join(dir, file), { force: true })
+    }
+  },
+}

package/src/node/cli.ts

@@ -0,0 +1,153 @@
+import { isAbsolute, join, relative } from 'node:path'
+import { parseArgs } from 'node:util'
+import type { ParseArgsConfig } from 'node:util'
+import { DECK_ENTRY } from '@lincyaw/compiler'
+import { errorMessage } from '@lincyaw/kernel'
+import { isDeck } from './deck.ts'
+import { EXPORT_TIMEOUT, exportDeck } from './export.ts'
+import { visualDiff } from './visual-diff.ts'
+
+const EXPORT_USAGE = `Usage: presmium-export [deckDir] [--format pdf|pptx|png] [--output <file.pdf | file.pptx | dir>] [--with-clicks] [--range <1,3-5>] [--dark] [--timeout <ms>] [--json]
+
+Builds the deck's slides and prints them in Chromium (playwright-chromium): to
+PDF (default), then checks that every link the slides show (Markdown links,
+href and *link/*url attributes, code permalinks) is still a link in the PDF,
+and exits 1 when a link was lost; to PowerPoint (a picture of each slide, its
+narration as the speaker notes, no links); or to PNG images, one per slide
+(per click step with --with-clicks), in the --output directory, where links
+cannot be checked. The print page must be ready within --timeout (default
+${EXPORT_TIMEOUT}); an export that lacks a page fails (exit 2).`
+
+const DIFF_USAGE = `Usage: presmium-diff <refA> <refB> [deckDir] [--out <dir>] [--threshold <ratio>] [--wait <ms>] [--install] [--json]
+
+Renders the deck of two commits in each of its forms: the slides (every slide
+and click step, exported as PNG) and the web form (every page in the document
+view and every section in the present view, captured with playwright-chromium).
+Compares the images pixel by pixel and writes report.md and report.json
+(default directory <deckDir>/.presmium/diff). Exits 1 when a page differs by
+more than the threshold (a ratio of pixels, default 0). --wait lets each web page
+settle before it is captured (default 500); a slides export that lacks a slide
+fails (exit 2). Both commits render with the host and addons
+installed for the deck; --install renders each commit with the dependencies of
+its own pnpm lockfile instead, e.g. to check a host or addon upgrade.`
+
+function shown(file: string): string {
+  const rel = relative(process.cwd(), file)
+  return rel === '' ? '.' : rel.startsWith('..') || isAbsolute(rel) ? file : rel
+}
+
+function parse<T extends ParseArgsConfig['options']>(argv: string[], options: T, usage: string) {
+  try {
+    return parseArgs({ args: argv, options: { ...options, json: { type: 'boolean' }, help: { type: 'boolean', short: 'h' } }, allowPositionals: true })
+  } catch (error) {
+    console.error(`${errorMessage(error)}\n\n${usage}`)
+    return undefined
+  }
+}
+
+function deckOrError(dir: string, usage: string): string | undefined {
+  if (isDeck(dir)) return dir
+  console.error(`no ${DECK_ENTRY} in ${dir}\n\n${usage}`)
+  return undefined
+}
+
+export async function exportMain(argv: string[]): Promise<number> {
+  const args = parse(argv, {
+    'format': { type: 'string' },
+    'output': { type: 'string', short: 'o' },
+    'with-clicks': { type: 'boolean', short: 'c' },
+    'range': { type: 'string' },
+    'dark': { type: 'boolean' },
+    'timeout': { type: 'string' },
+  }, EXPORT_USAGE)
+  if (!args) return 2
+  const { values, positionals } = args
+  if (values.help) {
+    console.log(EXPORT_USAGE)
+    return 0
+  }
+  const format = values.format ?? 'pdf'
+  if (positionals.length > 1 || (format !== 'pdf' && format !== 'png' && format !== 'pptx')) {
+    console.error(EXPORT_USAGE)
+    return 2
+  }
+  const timeout = values.timeout === undefined ? undefined : Number(values.timeout)
+  if (timeout !== undefined && !(timeout > 0)) {
+    console.error(`--timeout takes a number of milliseconds\n\n${EXPORT_USAGE}`)
+    return 2
+  }
+  const deckDir = deckOrError(positionals[0] ?? '.', EXPORT_USAGE)
+  if (!deckDir) return 2
+  try {
+    const result = await exportDeck({
+      deckDir,
+      format,
+      output: values.output as string | undefined,
+      withClicks: values['with-clicks'] as boolean | undefined,
+      range: values.range as string | undefined,
+      dark: values.dark as boolean | undefined,
+      timeout,
+    })
+    const lost = result.links.filter(link => link.pages.length === 0)
+    if (values.json) {
+      console.log(JSON.stringify({ ...result, lost: lost.length }, null, 2))
+    } else {
+      result.warnings.forEach(w => console.error(`warning: ${w}`))
+      if (format === 'png') {
+        console.log(`exported ${shown(result.output)} (${result.pages} images); links are not checked in images`)
+      } else if (format === 'pptx') {
+        console.log(`exported ${shown(result.output)} (${result.pages} slides, each a picture)`)
+      } else {
+        console.log(`exported ${shown(result.output)} (${result.pages} pages)`)
+        for (const link of lost) console.log(`${shown(link.source.file)}:${link.source.line}  link lost  ${link.url} (slide ${link.slide})`)
+        console.log(`${result.links.length - lost.length} of ${result.links.length} links kept`)
+      }
+    }
+    return lost.length > 0 ? 1 : 0
+  } catch (error) {
+    console.error(`presmium-export: ${errorMessage(error)}`)
+    return 2
+  }
+}
+
+export async function diffMain(argv: string[]): Promise<number> {
+  const args = parse(argv, {
+    out: { type: 'string', short: 'o' },
+    threshold: { type: 'string' },
+    wait: { type: 'string' },
+    install: { type: 'boolean' },
+  }, DIFF_USAGE)
+  if (!args) return 2
+  const { values, positionals } = args
+  if (values.help) {
+    console.log(DIFF_USAGE)
+    return 0
+  }
+  const threshold = values.threshold === undefined ? 0 : Number(values.threshold)
+  const wait = values.wait === undefined ? undefined : Number(values.wait)
+  if (!(threshold >= 0 && threshold <= 1) || (wait !== undefined && !(wait >= 0))) {
+    console.error(`--threshold must be a ratio between 0 and 1, --wait a number of milliseconds\n\n${DIFF_USAGE}`)
+    return 2
+  }
+  const [refA, refB, dir = '.', ...extra] = positionals
+  if (!refA || !refB || extra.length > 0) {
+    console.error(DIFF_USAGE)
+    return 2
+  }
+  const deckDir = deckOrError(dir, DIFF_USAGE)
+  if (!deckDir) return 2
+  try {
+    const { report, out, warnings } = await visualDiff({ refA, refB, deckDir, out: values.out as string | undefined, threshold, wait, install: values.install as boolean | undefined })
+    warnings.forEach(w => console.error(`warning: ${w}`))
+    if (values.json) {
+      console.log(JSON.stringify(report, null, 2))
+    } else {
+      for (const page of report.listed) console.log(`${page.id}  ${page.status}  ${(page.ratio * 100).toFixed(2)}%`)
+      console.log(`${report.listed.length} of ${report.pages.length} pages differ; report: ${shown(join(out, 'report.md'))}`)
+    }
+    return report.listed.length > 0 ? 1 : 0
+  } catch (error) {
+    console.error(`presmium-diff: ${errorMessage(error)}`)
+    return 2
+  }
+}

package/src/node/deck.ts

@@ -0,0 +1,14 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { DECK_ENTRY } from '@lincyaw/compiler'
+import type { Compilation } from '@lincyaw/compiler'
+
+export function isDeck(dir: string): boolean {
+  return existsSync(join(dir, DECK_ENTRY))
+}
+
+/** Whether the deck renders to form `id`: to every form when it names no renderer. */
+export function hasForm(compilation: Compilation, id: string): boolean {
+  const { renderers } = compilation.doc.config
+  return Object.keys(renderers).length === 0 || id in renderers
+}

package/src/node/export.ts

@@ -0,0 +1,109 @@
+import { cp, mkdir, readdir, readFile, rm } from 'node:fs/promises'
+import { join, resolve } from 'node:path'
+import { Compiler, exportDocument, viewFor } from '@lincyaw/compiler'
+import type { Compilation } from '@lincyaw/compiler'
+import { exportedSlides, linkLine, normalizeUrl, parseRange, slideLinks } from '../domain/index.ts'
+import type { DeclaredLink } from '../domain/index.ts'
+import { pdfLinks } from './pdf.ts'
+
+export const EXPORT_TIMEOUT = 120_000
+
+// The export's own directory below the deck's: the slides renderer's exporters write there.
+const WORK = '.presmium/export'
+const PAGE_IMAGE = /^\d+(?:-\d+)?\.png$/
+
+export interface ExportJob {
+  deckDir: string
+  format?: 'pdf' | 'png' | 'pptx'
+  output?: string
+  withClicks?: boolean
+  range?: string
+  dark?: boolean
+  timeout?: number
+  log?: (line: string) => void
+  signal?: AbortSignal
+}
+
+export interface ExportedLink {
+  url: string
+  slide: number
+  source: { file: string, line: number }
+  pages: number[]
+}
+
+export interface ExportResult {
+  format: 'pdf' | 'png' | 'pptx'
+  output: string
+  pages: number
+  links: ExportedLink[]
+  warnings: string[]
+}
+
+/** The pages an export of the slides has: a slide each, or each of its steps with `withClicks`. */
+function expectedPages(compilation: Compilation, range: Set<number> | undefined, withClicks: boolean): number {
+  const sections = viewFor(compilation.doc, 'slides').sections
+  return exportedSlides(sections.length, range).reduce((count, slide) => count + (withClicks ? sections[slide - 1]!.steps + 1 : 1), 0)
+}
+
+/** Exports the slides with the slides renderer's exporters (`pdf`, `png`, `pptx`) to `output`. */
+export async function exportSlides(compilation: Compilation, job: ExportJob & { format: 'pdf' | 'png' | 'pptx', output: string }): Promise<string[]> {
+  const range = parseRange(job.range)
+  const work = join(compilation.deckDir, WORK)
+  await rm(work, { recursive: true, force: true })
+  await mkdir(work, { recursive: true })
+  try {
+    const options = { steps: Boolean(job.withClicks), ...range ? { slides: [...range] } : {}, ...job.dark ? { dark: true } : {}, timeout: job.timeout ?? EXPORT_TIMEOUT }
+    const { files } = await exportDocument(compilation, job.format, { outDir: work, options, ...job.log ? { log: job.log } : {}, ...job.signal ? { signal: job.signal } : {} })
+    if (job.format !== 'png') {
+      await cp(join(work, files[0]!), job.output)
+      return [job.output]
+    }
+    await mkdir(job.output, { recursive: true })
+    await Promise.all((await readdir(job.output)).filter(file => PAGE_IMAGE.test(file)).map(file => rm(join(job.output, file))))
+    await Promise.all(files.map(file => cp(join(work, file), join(job.output, file))))
+    return files
+  } finally {
+    await rm(work, { recursive: true, force: true })
+  }
+}
+
+export async function exportDeck(job: ExportJob): Promise<ExportResult> {
+  const format = job.format ?? 'pdf'
+  const compilation = await new Compiler(job.deckDir).compile()
+  const warnings = compilation.doc.diagnostics.filter(f => f.severity !== 'info').map(f => f.message)
+  const filename = compilation.doc.config.renderers.slides?.exportFilename
+  const name = job.output ? resolve(job.output) : resolve(compilation.deckDir, String(filename ?? 'slides-export'))
+  const output = format === 'png' || name.endsWith(`.${format}`) ? name : `${name}.${format}`
+  const range = parseRange(job.range)
+  const written = await exportSlides(compilation, { ...job, format, output })
+  const expected = expectedPages(compilation, range, Boolean(job.withClicks))
+
+  if (format === 'png') {
+    if (written.length !== expected) throw new Error(`the export wrote ${written.length} pictures for the ${expected} pages of the slides`)
+    return { format, output, pages: written.length, links: [], warnings }
+  }
+  // A PowerPoint file has a picture of each slide: no links to check.
+  if (format === 'pptx') return { format, output, pages: expected, links: [], warnings }
+  const pages = (await pdfLinks(output)).map(uris => new Set(uris.map(normalizeUrl)))
+  if (pages.length !== expected) throw new Error(`the PDF has ${pages.length} pages for the ${expected} pages of the slides`)
+  const links = await locateLinks(slideLinks(viewFor(compilation.doc, 'slides'), range))
+  return {
+    format,
+    output,
+    pages: pages.length,
+    links: links.map(link => ({ ...link, pages: pages.flatMap((uris, i) => (uris.has(link.url) ? [i + 1] : [])) })),
+    warnings,
+  }
+}
+
+async function locateLinks(links: DeclaredLink[]): Promise<Omit<ExportedLink, 'pages'>[]> {
+  const sources = new Map<string, Promise<string[]>>()
+  const linesOf = (file: string) => {
+    if (!sources.has(file)) sources.set(file, readFile(file, 'utf8').then(text => text.split(/\r?\n/), () => []))
+    return sources.get(file)!
+  }
+  return Promise.all(links.map(async ({ url, slide, source }) => {
+    const line = linkLine(await linesOf(source.file), url, source.line, (source.endLine ?? source.line) + 1) ?? source.line
+    return { url, slide, source: { file: source.file, line } }
+  }))
+}