@1agh/maude 0.15.0 → 0.17.1

package/plugins/design/dev-server/exporters/_browser-bundles.ts

@@ -0,0 +1,89 @@
+// Lazy IIFE bundling of ESM libraries that need to run inside `page.evaluate`.
+//
+// `dom-to-svg` and `dom-to-pptx` ship as Node ESM only — they can't be
+// `<script>`-loaded into a browser context as-is. Bun.build turns them into
+// single-file IIFE bundles cached under the OS temp dir so the playwright
+// shims can `addScriptTag({ path })` without re-bundling per request.
+
+import { existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+interface CachedBundle {
+  path: string;
+  ready: Promise<string>;
+}
+
+const bundles = new Map<string, CachedBundle>();
+
+async function buildIife(entry: string, globalName: string, cachePath: string): Promise<string> {
+  if (existsSync(cachePath)) return cachePath;
+  // Bun.build doesn't expose IIFE directly — wrap a generated ESM bundle with
+  // a tiny shim that exposes its exports as a window global.
+  const built = await Bun.build({
+    entrypoints: [entry],
+    target: 'browser',
+    format: 'esm',
+    minify: true,
+  });
+  if (!built.success) {
+    throw new Error(`bundle ${entry} failed: ${built.logs.map((l) => l.message).join('; ')}`);
+  }
+  const firstOutput = built.outputs[0];
+  if (!firstOutput) throw new Error(`bundle ${entry} produced no outputs`);
+  const esm = await firstOutput.text();
+  // ESM → IIFE wrapper: evaluate the module as a Function body, then attach
+  // its exports to `window[globalName]`. We can't use top-level `import`
+  // inside a Function, so we transform `export {` to assignments via regex
+  // — the Bun-emitted bundle is consistent (`export { a as foo, b as bar };`).
+  const exportsMatch = esm.match(/export\s*\{([^}]+)\}\s*;?\s*$/);
+  let body = esm;
+  let exportsBlock = '';
+  if (exportsMatch) {
+    body = esm.slice(0, exportsMatch.index);
+    const captured = exportsMatch[1] ?? '';
+    const entries = captured
+      .split(',')
+      .map((s) => s.trim())
+      .filter(Boolean)
+      .map((s) => {
+        // `localName as exportedName` | bare `name`
+        const m = s.match(/^(.+?)\s+as\s+(.+)$/);
+        if (m?.[1] && m[2]) return { local: m[1].trim(), exported: m[2].trim() };
+        return { local: s, exported: s };
+      });
+    exportsBlock = entries
+      .map(
+        (e) =>
+          `globalThis[${JSON.stringify(globalName)}][${JSON.stringify(e.exported)}] = ${e.local};`
+      )
+      .join('\n');
+  }
+  const iife = `(function(){
+  globalThis[${JSON.stringify(globalName)}] = globalThis[${JSON.stringify(globalName)}] || {};
+  ${body}
+  ${exportsBlock}
+})();`;
+  await Bun.write(cachePath, iife);
+  return cachePath;
+}
+
+/**
+ * Returns the path to an IIFE bundle for the given npm package, attaching its
+ * exports under `window[globalName]`. Caches under the OS temp dir so a long-
+ * running dev server pays the build cost once.
+ */
+export function getBrowserBundle(packageName: string, globalName: string): Promise<string> {
+  const key = `${packageName}::${globalName}`;
+  const existing = bundles.get(key);
+  if (existing) return existing.ready;
+
+  const entry = require.resolve(packageName);
+  const cachePath = path.join(
+    tmpdir(),
+    `maude-${packageName.replace(/[^a-z0-9]/gi, '_')}-${globalName}.iife.js`
+  );
+  const ready = buildIife(entry, globalName, cachePath);
+  bundles.set(key, { path: cachePath, ready });
+  return ready;
+}

package/plugins/design/dev-server/exporters/canva-handoff-prompt.ts

@@ -0,0 +1,74 @@
+// Phase 6.5 T6c — `.canva-handoff.md` artifact builder.
+//
+// Emits a self-contained markdown file with three sections:
+//   1. Human-readable summary (artboard count, fidelity caveats)
+//   2. Drag-drop instructions for the universal Canva web path
+//   3. Fenced text-block prompt ready for the user's Canva MCP / agentic tool
+//
+// The prompt block is the load-bearing piece — anyone with a Canva MCP
+// configured in Claude Code / Cursor / equivalent can paste it and let the
+// MCP handle auth + import. Maude never touches credentials.
+
+export interface HandoffSummary {
+  /** Filename of the .pptx that ships next to this markdown (e.g. `home.pptx`). */
+  pptxFilename: string;
+  /** Absolute path to the .pptx after the user unzips. Resolved at render time. */
+  absolutePath: string;
+  /** Canvas slug — used as the Canva design title and as the prompt's anchor. */
+  canvasSlug: string;
+  /** Total artboard count (= PPTX slide count = expected Canva page count). */
+  artboardCount: number;
+  /** Optional list of artboard titles, in render order. */
+  artboardTitles?: string[];
+}
+
+const CAVEATS = `
+- **Fonts:** if your Canva Brand Kit doesn't include the source fonts, Canva substitutes its defaults. Text remains editable.
+- **Gradients:** CSS gradients translate to native PPT gradients. Multi-stop fidelity is approximate.
+- **Shadows, blend modes:** advanced effects rasterize on import.
+- **Layouts:** flex / grid get flattened to absolute coordinates at export-time viewport (1440 × declared artboard height).
+`.trim();
+
+export function buildHandoffMarkdown(s: HandoffSummary): string {
+  const plural = s.artboardCount === 1 ? 'artboard' : 'artboards';
+  const titles = s.artboardTitles?.length
+    ? s.artboardTitles.map((t, i) => `${i + 1}. ${t}`).join('\n')
+    : `${s.artboardCount} ${plural}`;
+
+  return `# Canva handoff — ${s.canvasSlug}
+
+Editable handoff bundle exported from Maude. The companion file \`${s.pptxFilename}\` is a native PowerPoint document — Canva imports it as editable text, shapes, and images, **not** a flat raster.
+
+## What's inside
+
+- **${s.artboardCount}** artboard${s.artboardCount === 1 ? '' : 's'} → ${s.artboardCount} Canva page${s.artboardCount === 1 ? '' : 's'} on import.
+${titles}
+
+## Option A — drag-drop (works on any Canva tier)
+
+1. Open https://www.canva.com in your browser.
+2. Drag \`${s.pptxFilename}\` from this folder into the Canva home screen, or use **Create a design → Upload media → Import file**.
+3. Canva opens the imported design. Text, shapes, and images are individually selectable and editable.
+
+## Option B — automate via your Canva MCP
+
+If you have a Canva MCP server configured in Claude Code / Cursor / Goose / any agentic tool, paste the prompt below into a fresh chat:
+
+\`\`\`text
+Use my Canva MCP to import the PowerPoint file at the path below into a new Canva design titled "${s.canvasSlug}". Preserve text editability, shape fills and strokes, image swappability, and the artboard-to-page mapping (one PPTX slide = one Canva page). After the import job completes, return the Canva design URL.
+
+File path: ${s.absolutePath}
+Slides expected: ${s.artboardCount}
+\`\`\`
+
+Maude doesn't see your Canva credentials — your MCP handles auth and the import call itself.
+
+## Fidelity caveats
+
+${CAVEATS}
+
+---
+
+Generated by [Maude](https://github.com/1aGh/maude).
+`;
+}

package/plugins/design/dev-server/exporters/canva.ts

@@ -0,0 +1,126 @@
+// Phase 6.5 T6c — Canva handoff adapter.
+//
+// Wraps T6b's PPTX bytes with a sibling `.canva-handoff.md` artifact and
+// ZIPs both into a single bundle. The user unzips, then either drag-drops
+// the PPTX into Canva web (universal path) or feeds the markdown prompt
+// to their own Canva MCP (one-click handoff for users who've configured
+// one). Maude never touches Canva credentials — see DDR.
+//
+// `--canva=raster` legacy bundle (T6d) is the opt-out for users who want a
+// flat reference image set instead of the editable handoff. Routed via
+// `options.mode = 'raster'`.
+
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+import JSZip from 'jszip';
+
+import { buildHandoffMarkdown } from './canva-handoff-prompt.ts';
+import type { ExportContext, ExportOptions, ExportResult } from './index.ts';
+import { run as runPng } from './png.ts';
+import { run as runPptx } from './pptx.ts';
+import type { Target } from './scope.ts';
+
+async function buildRasterBundle(
+  elementTargets: Array<Extract<Target, { kind: 'element' }>>,
+  options: ExportOptions,
+  ctx: ExportContext
+): Promise<ExportResult> {
+  // T6d — legacy PNG+CSV+README handoff. Reuses the PNG adapter for capture
+  // then assembles a ZIP with a manifest CSV + a README pointing the user
+  // at the raster files as reference imagery (no editable Canva path).
+  const pngResult = await runPng(elementTargets, options, ctx);
+  const zip = new JSZip();
+  const rows: string[] = ['index,filename,canvas_slug'];
+
+  if (pngResult.contentType === 'image/png') {
+    zip.file(pngResult.filename, pngResult.body);
+    rows.push(`1,${pngResult.filename},${elementTargets[0]?.canvasSlug ?? 'export'}`);
+  } else if (pngResult.contentType === 'application/zip' && pngResult.body.byteLength) {
+    const inner = await JSZip.loadAsync(pngResult.body);
+    let i = 0;
+    for (const fname of Object.keys(inner.files)) {
+      const file = inner.file(fname);
+      if (!file) continue;
+      const bytes = await file.async('uint8array');
+      zip.file(fname, bytes);
+      i += 1;
+      rows.push(`${i},${fname},${elementTargets[0]?.canvasSlug ?? 'export'}`);
+    }
+  }
+
+  const baseSlug = elementTargets[0]?.canvasSlug ?? 'export';
+  zip.file('manifest.csv', rows.join('\n'));
+  zip.file(
+    'README.md',
+    '# Canva raster bundle\n\n' +
+      'Legacy reference-only handoff. PNGs in this folder are NOT editable in Canva — they import as flat images.\n\n' +
+      'For an **editable** Canva design (text, shapes, images), re-export without `--canva=raster` to get the PPTX + MCP-prompt bundle instead.\n'
+  );
+  const zipBytes = await zip.generateAsync({ type: 'uint8array', compression: 'DEFLATE' });
+  return {
+    filename: `${baseSlug}.canva-raster.zip`,
+    contentType: 'application/zip',
+    body: zipBytes,
+  };
+}
+
+export async function run(
+  targets: Target[],
+  options: ExportOptions,
+  ctx: ExportContext
+): Promise<ExportResult> {
+  if (!targets.length) {
+    return {
+      filename: 'export.canva.zip',
+      contentType: 'application/zip',
+      body: new Uint8Array(0),
+    };
+  }
+  const elementTargets = targets.filter(
+    (t): t is Extract<Target, { kind: 'element' }> => t.kind === 'element'
+  );
+  if (!elementTargets.length) {
+    throw new Error('canva adapter requires element targets (got file-tree)');
+  }
+
+  if (options.mode === 'raster') {
+    return buildRasterBundle(elementTargets, options, ctx);
+  }
+
+  // Editable handoff — delegate to the pptx adapter (which now runs
+  // dom-to-pptx) for the payload, then wrap with handoff markdown. We pass
+  // the full targets through so multi-artboard canvases produce one slide
+  // per artboard inside the pptx.
+  const pptxResult = await runPptx(elementTargets, options, ctx);
+  const pptxBytes = pptxResult.body;
+
+  const baseSlug = elementTargets[0]?.canvasSlug ?? 'export';
+  const pptxName = `${baseSlug}.pptx`;
+  // dom-to-pptx doesn't surface artboard count from outside; we infer it
+  // from the target's multi-ness. For single-artboard exports the count is
+  // 1; for canvas-as-separate we report "all artboards" plainly — Canva
+  // splits them on import regardless of what we claim here.
+  const artboardCount = elementTargets[0]?.multi ? -1 : 1;
+  const markdown = buildHandoffMarkdown({
+    pptxFilename: pptxName,
+    absolutePath: path.join('<your-unzip-location>', pptxName),
+    canvasSlug: baseSlug,
+    artboardCount: artboardCount > 0 ? artboardCount : 1,
+  });
+
+  const zip = new JSZip();
+  zip.file(pptxName, pptxBytes);
+  zip.file(`${baseSlug}.canva-handoff.md`, markdown);
+  const zipBytes = await zip.generateAsync({ type: 'uint8array', compression: 'DEFLATE' });
+
+  return {
+    filename: `${baseSlug}.canva.zip`,
+    contentType: 'application/zip',
+    body: zipBytes,
+  };
+}
+
+// Suppress unused-import for `tmpdir` — kept for future raster-bundle
+// branches that may need a temp dir.
+void tmpdir;

package/plugins/design/dev-server/exporters/html.ts

@@ -0,0 +1,103 @@
+// Phase 6.5 T5 — HTML adapter (standalone bundler).
+//
+// Renders the target through Playwright, emits a self-contained `index.html`
+// with all stylesheets inlined (fonts + remote images still referenced by
+// origin — full asset inlining is a follow-up). Output is always a ZIP per
+// plan T5 ("Always zipped (multi-file)"), even for a single artboard,
+// because the consuming workflow typically wants one bundle per export.
+
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+import JSZip from 'jszip';
+
+import {
+  type ExportContext,
+  type ExportOptions,
+  type ExportResult,
+  canvasShellUrl,
+} from './index.ts';
+import type { Target } from './scope.ts';
+
+const HTML_PLAYWRIGHT = path.join(import.meta.dir, '..', 'bin', '_html-playwright.mjs');
+
+async function captureHtml(
+  target: Extract<Target, { kind: 'element' }>,
+  ctx: ExportContext,
+  outDir: string,
+  timeoutSec: number
+): Promise<string[]> {
+  const args = [
+    HTML_PLAYWRIGHT,
+    '--url',
+    canvasShellUrl(ctx, target.file),
+    '--selector',
+    target.cssPath,
+    '--timeout',
+    String(timeoutSec),
+  ];
+  if (target.multi) {
+    args.push('--multi', '1', '--out-dir', outDir);
+  } else {
+    args.push('--widen-to-artboard', '1', '--out', path.join(outDir, `${target.canvasSlug}.html`));
+  }
+  const proc = Bun.spawn(['node', ...args], {
+    cwd: path.dirname(HTML_PLAYWRIGHT),
+    stdout: 'pipe',
+    stderr: 'pipe',
+  });
+  const [stdout, stderr] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+  ]);
+  const code = await proc.exited;
+  if (code !== 0) {
+    throw new Error(`_html-playwright exited ${code}: ${stderr.trim() || stdout.trim()}`);
+  }
+  return stdout
+    .split('\n')
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+export async function run(
+  targets: Target[],
+  options: ExportOptions,
+  ctx: ExportContext
+): Promise<ExportResult> {
+  if (!targets.length) {
+    return { filename: 'export.zip', contentType: 'application/zip', body: new Uint8Array(0) };
+  }
+  const elementTargets = targets.filter(
+    (t): t is Extract<Target, { kind: 'element' }> => t.kind === 'element'
+  );
+  if (!elementTargets.length) {
+    throw new Error('html adapter requires element targets (got file-tree)');
+  }
+  const timeoutSec = (options.timeoutSec as number | undefined) ?? 8;
+  const tmp = mkdtempSync(path.join(tmpdir(), 'maude-html-'));
+  try {
+    const written: string[] = [];
+    for (const t of elementTargets) {
+      const paths = await captureHtml(t, ctx, tmp, timeoutSec);
+      written.push(...paths);
+    }
+    if (!written.length) {
+      return { filename: 'export.zip', contentType: 'application/zip', body: new Uint8Array(0) };
+    }
+    const zip = new JSZip();
+    for (const p of written) {
+      zip.file(path.basename(p), new Uint8Array(readFileSync(p)));
+    }
+    const zipBytes = await zip.generateAsync({ type: 'uint8array', compression: 'DEFLATE' });
+    const baseSlug = elementTargets[0]?.canvasSlug ?? 'export';
+    return {
+      filename: `${baseSlug}.html.zip`,
+      contentType: 'application/zip',
+      body: zipBytes,
+    };
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+}

package/plugins/design/dev-server/exporters/index.ts

@@ -0,0 +1,135 @@
+// Phase 6.5 T1 — adapter registry + dispatch.
+//
+// Each format adapter exports a single `run(targets, options, ctx) → Result`
+// function. This module owns the (format → adapter) lookup and the shared
+// `Result` envelope. Stub adapters live in `./{png,pdf,svg,html,pptx,canva,zip}.ts`
+// and currently return zero-byte payloads with valid MIME types — T2…T7
+// replace them with real renderers.
+
+import path from 'node:path';
+
+import * as canva from './canva.ts';
+import * as html from './html.ts';
+import * as pdf from './pdf.ts';
+import * as png from './png.ts';
+import * as pptx from './pptx.ts';
+import { type ResolveScopeArgs, type Scope, type Target, resolveScope } from './scope.ts';
+import * as svg from './svg.ts';
+import * as zip from './zip.ts';
+
+export type Format = 'png' | 'pdf' | 'svg' | 'html' | 'pptx' | 'canva' | 'zip';
+
+export const FORMATS: readonly Format[] = ['png', 'pdf', 'svg', 'html', 'pptx', 'canva', 'zip'];
+
+/** Options bag forwarded to the adapter. Format-specific keys are validated by each adapter. */
+export type ExportOptions = Record<string, unknown>;
+
+export interface ExportContext {
+  /** Absolute design root (e.g. /abs/.design). */
+  designRoot: string;
+  /** Absolute repo root. */
+  repoRoot: string;
+  /** Dev-server origin including port (`http://localhost:NNNN`) — adapters that render via Playwright resolve canvas URLs against this. */
+  serverOrigin: string;
+  /**
+   * designRoot-relative path to the tokens CSS file (e.g. `system/colors_and_type.css`).
+   * Threaded into the `?tokens=` query param on the canvas-shell URL so the
+   * standalone shell actually loads the project's design tokens — without it
+   * `var(--bg-0)` resolves to nothing and renders blank.
+   */
+  tokensCssRel?: string;
+  /** designRoot-relative path to a shared components CSS file (optional). */
+  componentsCssRel?: string;
+}
+
+export interface ExportResult {
+  /** Final filename (no path). E.g. `mockup.pdf` or `mockup.zip`. */
+  filename: string;
+  /** MIME type for the Content-Disposition / Content-Type header. */
+  contentType: string;
+  /** Payload bytes. T1 stubs return zero-byte placeholders. */
+  body: Uint8Array;
+}
+
+export interface Adapter {
+  run(targets: Target[], options: ExportOptions, ctx: ExportContext): Promise<ExportResult>;
+}
+
+const REGISTRY: Record<Format, Adapter> = {
+  png,
+  pdf,
+  svg,
+  html,
+  pptx,
+  canva,
+  zip,
+};
+
+export function getAdapter(format: Format): Adapter | null {
+  return REGISTRY[format] ?? null;
+}
+
+export function isFormat(s: unknown): s is Format {
+  return typeof s === 'string' && (FORMATS as readonly string[]).includes(s);
+}
+
+export function isScope(s: unknown): s is Scope {
+  return s === 'selection' || s === 'artboard' || s === 'canvas-as-separate' || s === 'project-raw';
+}
+
+/**
+ * One-shot dispatch — resolve scope, look up adapter, run it. The HTTP layer
+ * is a thin shell over this so CLI/slash can call the same path without
+ * re-implementing the orchestration.
+ */
+export async function runExport(args: {
+  format: Format;
+  scope: Scope;
+  options: ExportOptions;
+  resolve: Omit<ResolveScopeArgs, 'scope'>;
+  ctx: ExportContext;
+}): Promise<ExportResult> {
+  const targets = await resolveScope({ ...args.resolve, scope: args.scope });
+  const adapter = getAdapter(args.format);
+  if (!adapter) {
+    throw new Error(`unknown format: ${args.format}`);
+  }
+  return adapter.run(targets, args.options, args.ctx);
+}
+
+export { resolveScope };
+export type { Scope, Target };
+
+/**
+ * Build the `_canvas-shell.html?canvas=…&tokens=…&components=…` URL the
+ * playwright shims navigate to. Three normalisations the shell expects:
+ *
+ *   1. `canvas=` is a **designRoot-relative** path (`ui/Foo.tsx`), NOT a
+ *      repo-relative one (`.design/ui/Foo.tsx`). Without the strip the shell
+ *      builds `/.design/.design/ui/Foo.tsx` and 404s.
+ *   2. `tokens=` is the designRoot-relative path to the project's tokens CSS.
+ *      The shell only loads `<link id="canvas-tokens">` when this is set —
+ *      missing it means every `var(--bg-0)` etc. resolves to undefined and
+ *      the rendered DOM looks blank in screenshots.
+ *   3. `components=` (optional) — designRoot-relative path to a shared
+ *      components CSS file. Same shell behaviour as tokens.
+ *
+ * `_active.json.active` leaks the prefixed form straight through; this helper
+ * is the single normalization point. `ctx.tokensCssRel` is supplied by the
+ * HTTP handler from `cfg.tokensCssRel`.
+ */
+export function canvasShellUrl(ctx: ExportContext, file: string): string {
+  const designRel = path.basename(ctx.designRoot);
+  const stripPrefix = `${designRel}/`;
+  const rel = file.startsWith(stripPrefix) ? file.slice(stripPrefix.length) : file;
+  const params = new URLSearchParams();
+  params.set('canvas', rel);
+  if (ctx.tokensCssRel) params.set('tokens', ctx.tokensCssRel);
+  if (ctx.componentsCssRel) params.set('components', ctx.componentsCssRel);
+  // Suppress dev-server overlays (tool palette, mini-map, halos, pins, snap
+  // guides, annotation chrome) so the export captures only the artboard
+  // content. The shell's tiny <style id="canvas-hide-chrome"> rule flips
+  // active when this is set.
+  params.set('hide-chrome', '1');
+  return `${ctx.serverOrigin}/_canvas-shell.html?${params.toString()}`;
+}

package/plugins/design/dev-server/exporters/pdf.ts

@@ -0,0 +1,109 @@
+// Phase 6.5 T3 — PDF adapter (Playwright page.pdf, vector-faithful).
+//
+// Uses Chromium's print-to-PDF pipeline so the output is a TRUE vector PDF —
+// selectable text, web fonts embedded, SVG primitives kept as paths. The old
+// pdf-lib-over-PNG approach (which the user correctly complained was raster)
+// is gone; this adapter is now ~50 lines because Chromium does the work.
+//
+// Multi-target rendering: one PDF per target via the playwright shim, then
+// pdf-lib concatenates pages into a single document.
+
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+import { PDFDocument } from 'pdf-lib';
+
+import {
+  type ExportContext,
+  type ExportOptions,
+  type ExportResult,
+  canvasShellUrl,
+} from './index.ts';
+import type { Target } from './scope.ts';
+
+const PDF_PLAYWRIGHT = path.join(import.meta.dir, '..', 'bin', '_pdf-playwright.mjs');
+
+async function capturePdf(
+  target: Extract<Target, { kind: 'element' }>,
+  ctx: ExportContext,
+  outDir: string,
+  timeoutSec: number
+): Promise<string[]> {
+  const args = [
+    PDF_PLAYWRIGHT,
+    '--url',
+    canvasShellUrl(ctx, target.file),
+    '--selector',
+    target.cssPath,
+    '--timeout',
+    String(timeoutSec),
+  ];
+  if (target.multi) args.push('--multi', '1', '--out-dir', outDir);
+  else args.push('--out', path.join(outDir, `${target.canvasSlug}.pdf`));
+
+  const proc = Bun.spawn(['node', ...args], {
+    cwd: path.dirname(PDF_PLAYWRIGHT),
+    stdout: 'pipe',
+    stderr: 'pipe',
+  });
+  const [stdout, stderr] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+  ]);
+  const code = await proc.exited;
+  if (code !== 0) {
+    throw new Error(`_pdf-playwright exited ${code}: ${stderr.trim() || stdout.trim()}`);
+  }
+  return stdout
+    .split('\n')
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+export async function run(
+  targets: Target[],
+  options: ExportOptions,
+  ctx: ExportContext
+): Promise<ExportResult> {
+  if (!targets.length) {
+    return { filename: 'export.pdf', contentType: 'application/pdf', body: new Uint8Array(0) };
+  }
+  const elementTargets = targets.filter(
+    (t): t is Extract<Target, { kind: 'element' }> => t.kind === 'element'
+  );
+  if (!elementTargets.length) {
+    throw new Error('pdf adapter requires element targets (got file-tree)');
+  }
+  const timeoutSec = (options.timeoutSec as number | undefined) ?? 12;
+  const tmp = mkdtempSync(path.join(tmpdir(), 'maude-pdf-'));
+  try {
+    const written: string[] = [];
+    for (const t of elementTargets) {
+      const paths = await capturePdf(t, ctx, tmp, timeoutSec);
+      written.push(...paths);
+    }
+    if (!written.length) {
+      return { filename: 'export.pdf', contentType: 'application/pdf', body: new Uint8Array(0) };
+    }
+    if (written.length === 1) {
+      const bytes = new Uint8Array(readFileSync(written[0]));
+      const baseSlug = elementTargets[0]?.canvasSlug ?? 'export';
+      return { filename: `${baseSlug}.pdf`, contentType: 'application/pdf', body: bytes };
+    }
+    // Multi-target → concatenate via pdf-lib `copyPages`. The vector
+    // primitives produced by Chromium copy through losslessly — we never
+    // re-render or rasterize.
+    const out = await PDFDocument.create();
+    for (const p of written) {
+      const src = await PDFDocument.load(new Uint8Array(readFileSync(p)));
+      const pages = await out.copyPages(src, src.getPageIndices());
+      for (const page of pages) out.addPage(page);
+    }
+    const bytes = await out.save();
+    const baseSlug = elementTargets[0]?.canvasSlug ?? 'export';
+    return { filename: `${baseSlug}.pdf`, contentType: 'application/pdf', body: bytes };
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+}