@1agh/maude 0.45.1 → 0.46.0

package/apps/studio/dom-selection.ts

@@ -393,6 +393,26 @@ function styleMapsFor(el: Element | null): {
       if (ATTR_SKIP.test(a.name)) continue;
       attrs[a.name] = a.value;
     }
+    // Dogfood follow-up (print artboards) — ATTR_SKIP deliberately hides the
+    // engine's own `data-dc-*` plumbing from the generic "custom HTML
+    // attributes" panel, but for a whole-ARTBOARD selection those attributes
+    // ARE the payload: DCArtboard's readBackAttrs (canvas-lib.tsx) stamps
+    // data-dc-kind / data-dc-print / data-dc-fixed / data-dc-bg / … on the
+    // <article> precisely so the Inspector's ArtboardKnobs can pre-fill its
+    // Kind picker, paper preset, Hug/Fixed toggle, and Style fields. With
+    // the blanket skip, every one of those readbacks silently fell back to
+    // its default ('digital', screen presets, Hug, empty Bg) no matter what
+    // the artboard actually was — the root cause of the "Kind shows Digital
+    // on a print artboard" family of bugs. Allow data-dc-* through for the
+    // artboard element itself; ordinary elements keep the filter (their
+    // panel is CssKnobs, which never reads these).
+    if ((el as HTMLElement).hasAttribute('data-dc-screen')) {
+      for (const a of Array.from((el as HTMLElement).attributes)) {
+        if (a.name.startsWith('data-dc-') && a.name !== 'data-dcid') {
+          attrs[a.name] = a.value;
+        }
+      }
+    }
     // Stage M — parent's layout context (for the Fixed/Hug/Fill sizing control +
     // flex-child row gating). Read here because the shell can't reach the
     // cross-origin iframe to compute it after selection.

package/apps/studio/export-dialog.tsx

@@ -101,14 +101,38 @@ export type Scope = 'selection' | 'artboard' | 'canvas-as-separate' | 'project-r
 // ─── PNG size presets (item 1) ───────────────────────────────────────────────
 // Resolution multiplier applied as Chromium `deviceScaleFactor`. The native
 // artboard is 1440×900; 2× → 2880×1800. Default 2× because a single-scale PNG
-// was uselessly small. The shim clamps deviceScaleFactor ≤ 4.
-type PngScale = 1 | 2 | 3;
-const PNG_SCALES: ReadonlyArray<{ value: PngScale; label: string }> = [
-  { value: 1, label: '1× (native)' },
-  { value: 2, label: '2× (retina)' },
-  { value: 3, label: '3× (max)' },
+// was uselessly small. The shim clamps deviceScaleFactor ≤ 8.
+// feature-2-print-artboards T4/T6 — mirrors app.jsx's PNG_RESOLUTIONS (the
+// two dialogs must stay in sync — see this file's own header comment + the
+// plan's T6 gotcha). `kind:'scale'` sends `options.scale`, `kind:'dpi'`
+// sends `options.dpi` (exporters/png.ts resolveDeviceScale). Replaces the
+// old bare 1×/2×/3× PngScale picker — those three values are still
+// reachable, folded into this one richer list.
+type PngResolution = { id: string; label: string; kind: 'scale' | 'dpi'; value: number };
+const PNG_RESOLUTIONS: readonly PngResolution[] = [
+  { id: '1x', label: '1× (native)', kind: 'scale', value: 1 },
+  { id: '2x', label: '2× (retina)', kind: 'scale', value: 2 },
+  { id: '3x', label: '3× (max)', kind: 'scale', value: 3 },
+  { id: 'dpi150', label: '150 dpi', kind: 'dpi', value: 150 },
+  { id: 'dpi300', label: '300 dpi (print)', kind: 'dpi', value: 300 },
+  { id: 'dpi600', label: '600 dpi (high-res print)', kind: 'dpi', value: 600 },
 ];
-const DEFAULT_PNG_SCALE: PngScale = 2;
+const PNG_RESOLUTION_DEFAULT = '2x';
+
+// feature-2-print-artboards T5/T6 (dogfood follow-up) — mirrors app.jsx's
+// PDF_DPI_OPTIONS. The PDF page itself is always vector; this only sets the
+// capture density for RASTER content ON the artboard (a dropped photo, a
+// large-format piece authored at a fraction of its real physical size).
+// Default "Auto (1×)" is today's unchanged behavior — unlike PNG_RESOLUTIONS,
+// PDF has no legacy scale concept, so this is DPI-only.
+type PdfDpiOption = { id: string; label: string; value: number | undefined };
+const PDF_DPI_OPTIONS: readonly PdfDpiOption[] = [
+  { id: 'auto', label: 'Auto (1×)', value: undefined },
+  { id: 'dpi150', label: '150 dpi', value: 150 },
+  { id: 'dpi300', label: '300 dpi (print)', value: 300 },
+  { id: 'dpi600', label: '600 dpi (high-res print)', value: 600 },
+];
+const PDF_DPI_DEFAULT = 'auto';
 
 /**
  * The artboard under the viewport centre — the export dialog's notion of "the
@@ -456,20 +480,51 @@ const DialogShell = (() => {
     const { ref, openState, onClose, onSubmit, history, submitting, status } = props;
     const [format, setFormat] = useState<Format>('png');
     const [scope, setScope] = useState<Scope>('artboard');
-    const [pngScale, setPngScale] = useState<PngScale>(DEFAULT_PNG_SCALE);
+    const [pngResId, setPngResId] = useState<string>(PNG_RESOLUTION_DEFAULT);
+    // feature-2-print-artboards T5/T6 — PDF print options. Sent unconditionally
+    // on every PDF export; the server no-ops them for a non-print artboard
+    // (mirrors app.jsx's own ExportDialog — see that file's T6 comment).
+    const [pdfIncludeBleed, setPdfIncludeBleed] = useState(true);
+    const [pdfMarksOpen, setPdfMarksOpen] = useState(false);
+    const [pdfMarksCrop, setPdfMarksCrop] = useState(false);
+    const [pdfMarksRegistration, setPdfMarksRegistration] = useState(false);
+    const [pdfDpiId, setPdfDpiId] = useState<string>(PDF_DPI_DEFAULT);
     // Optional — the dialog can be mounted in tests without a provider.
     const selSet = useSelectionSetOptional();
 
     // Build the options bag at submit time: snapshot the live selection /
-    // active artboard (items 3 & 5) plus the PNG size (item 1).
+    // active artboard (items 3 & 5) plus the PNG size (item 1) / PDF print
+    // options (feature-2-print-artboards T5/T6).
     const handleSubmit = useCallback(() => {
       const options: Record<string, unknown> = {};
       const hints = captureScopeHints(selSet);
       if (hints.selection) options.selection = hints.selection;
       if (hints.artboardId) options.artboardId = hints.artboardId;
-      if (format === 'png') options.scale = pngScale;
+      if (format === 'png') {
+        const res = PNG_RESOLUTIONS.find((r) => r.id === pngResId) ?? PNG_RESOLUTIONS[1];
+        if (res.kind === 'dpi') options.dpi = res.value;
+        else options.scale = res.value;
+      }
+      if (format === 'pdf') {
+        options.pdfPrint = {
+          includeBleed: pdfIncludeBleed,
+          marks: { crop: pdfMarksCrop, registration: pdfMarksRegistration },
+        };
+        const pdfDpi = PDF_DPI_OPTIONS.find((d) => d.id === pdfDpiId)?.value;
+        if (pdfDpi !== undefined) options.dpi = pdfDpi;
+      }
       onSubmit(format, scope, options);
-    }, [selSet, format, scope, pngScale, onSubmit]);
+    }, [
+      selSet,
+      format,
+      scope,
+      pngResId,
+      pdfIncludeBleed,
+      pdfMarksCrop,
+      pdfMarksRegistration,
+      pdfDpiId,
+      onSubmit,
+    ]);
 
     useEffect(() => {
       if (!openState) return;
@@ -530,20 +585,85 @@ const DialogShell = (() => {
           </div>
           {format === 'png' && (
             <div>
-              <label htmlFor="dc-ed-png-scale">Size</label>
+              <label htmlFor="dc-ed-png-scale">Resolution</label>
               <select
                 id="dc-ed-png-scale"
-                value={pngScale}
-                onChange={(e) => setPngScale(Number(e.target.value) as PngScale)}
+                value={pngResId}
+                onChange={(e) => setPngResId(e.target.value)}
+              >
+                {PNG_RESOLUTIONS.map((r) => (
+                  <option key={r.id} value={r.id}>
+                    {r.label}
+                  </option>
+                ))}
+              </select>
+              <p className="dc-ed-desc">
+                Resolution multiplier or physical DPI for a print export. 2× ≈ 2880×1800 for a
+                1440×900 artboard.
+              </p>
+            </div>
+          )}
+          {format === 'pdf' && (
+            <div>
+              <label htmlFor="dc-ed-pdf-dpi">Image quality</label>
+              <select
+                id="dc-ed-pdf-dpi"
+                value={pdfDpiId}
+                onChange={(e) => setPdfDpiId(e.target.value)}
               >
-                {PNG_SCALES.map((s) => (
-                  <option key={s.value} value={s.value}>
-                    {s.label}
+                {PDF_DPI_OPTIONS.map((d) => (
+                  <option key={d.id} value={d.id}>
+                    {d.label}
                   </option>
                 ))}
               </select>
               <p className="dc-ed-desc">
-                Resolution multiplier. 2× ≈ 2880×1800 for a 1440×900 artboard.
+                The page stays vector; this only sets the capture density for raster content on it
+                (dropped photos, large-format art).
+              </p>
+              <label style={{ display: 'flex', alignItems: 'center', gap: 8, cursor: 'pointer' }}>
+                <input
+                  type="checkbox"
+                  checked={pdfIncludeBleed}
+                  onChange={(e) => setPdfIncludeBleed(e.target.checked)}
+                />
+                Include bleed
+              </label>
+              <button
+                type="button"
+                style={{ background: 'none', border: 0, padding: 0, cursor: 'pointer' }}
+                onClick={() => setPdfMarksOpen((v) => !v)}
+                aria-expanded={pdfMarksOpen}
+              >
+                {pdfMarksOpen ? '▾' : '▸'} Marks
+              </button>
+              {pdfMarksOpen && (
+                <div style={{ display: 'flex', flexDirection: 'column', gap: 6 }}>
+                  <label
+                    style={{ display: 'flex', alignItems: 'center', gap: 8, cursor: 'pointer' }}
+                  >
+                    <input
+                      type="checkbox"
+                      checked={pdfMarksCrop}
+                      onChange={(e) => setPdfMarksCrop(e.target.checked)}
+                    />
+                    Crop marks
+                  </label>
+                  <label
+                    style={{ display: 'flex', alignItems: 'center', gap: 8, cursor: 'pointer' }}
+                  >
+                    <input
+                      type="checkbox"
+                      checked={pdfMarksRegistration}
+                      onChange={(e) => setPdfMarksRegistration(e.target.checked)}
+                    />
+                    Registration marks
+                  </label>
+                </div>
+              )}
+              <p className="dc-ed-desc">
+                Bleed and marks apply to print (<code>kind=&quot;print&quot;</code>) artboards only.
+                {scope === 'canvas-as-separate' ? ' One PDF page per artboard.' : ''}
               </p>
             </div>
           )}

package/apps/studio/exporters/pdf.ts

@@ -7,12 +7,40 @@
 //
 // Multi-target rendering: one PDF per target via the playwright shim, then
 // pdf-lib concatenates pages into a single document.
+//
+// feature-2-print-artboards T5 — print-ready post-pass. When the caller asks
+// for it (`options.pdfPrint` and/or `options.pageFit`), every page gets
+// loaded into pdf-lib (single-page path now goes through pdf-lib too, not
+// just multi) and, per page:
+//   - a `kind="print"` artboard's rendered page gets its MediaBox enlarged
+//     (negative origin — content coordinates never move), BleedBox set to
+//     the full rendered page, TrimBox inset by the artboard's own bleed (read
+//     off its `print` JSX prop — never re-passed via options, so the
+//     exported boxes can never drift from what the artboard's OWN prop says),
+//     and vector crop/registration marks drawn outside TrimBox.
+//   - a non-print artboard honors `pageFit` (scale-to-paper via
+//     embedPage/drawPage) — finally implementing the long-dead
+//     `--option pageFit=a4` documented in export.md.
+// RGB PDF + correct boxes + vector marks + metadata — CMYK/PDF-X is
+// explicitly out of scope (Design Decision 4); this never claims PDF/X
+// compliance.
+//
+// `options.dpi` (dogfood follow-up to T4/T5) — the page itself is always
+// vector (text/shapes are never rasterized), but any raster content ON the
+// artboard (a dropped photo, a large-format piece authored at a fraction of
+// its real physical size — e.g. a billboard at 1:10 scale) embeds as a
+// bitmap whose pixel density is set by the CAPTURING context's
+// deviceScaleFactor. `resolveDeviceScale` (exporters/png.ts) is reused here
+// unchanged so `dpi` means the same physical resolution in both exporters.
 
 import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 
-import { PDFDocument } from 'pdf-lib';
+import { PDFDocument, type PDFPage, rgb } from 'pdf-lib';
+import { readArtboardPrintProp } from '../canvas-edit.ts';
+import { computeMarksGeometry, MARK_STROKE_PT, requiredSlugPt } from '../print/marks.ts';
+import { CSS_DPI, getPaperPreset, mmToPt, resolveBleedMm, trimSizeMm } from '../print/units.ts';
 import { exportShimPath, runShim } from './_runtime.ts';
 import {
   canvasShellUrl,
@@ -21,16 +49,42 @@ import {
   type ExportOptions,
   type ExportResult,
 } from './index.ts';
+import { clampDpi } from './png.ts';
 import type { Target } from './scope.ts';
 
 // DDR-045: resolve via DEV_SERVER_ROOT, never `import.meta.dir`. See _runtime.ts.
 const PDF_PLAYWRIGHT = exportShimPath('_pdf-playwright.mjs');
 
+/** `[data-dc-screen="<id>"]` → `<id>` — the exact cssPath shape scope.ts's
+ *  'artboard' resolver produces when it knows the artboard id (the common
+ *  case — see scope.ts hints.artboardId). Any other selector shape (a
+ *  descendant-widen fallback, `:first-of-type`) yields null — the post-pass
+ *  then simply skips print geometry for that page rather than guessing. */
+export function artboardIdFromCssPath(cssPath: string): string | null {
+  const m = /^\[data-dc-screen="([^"]+)"\]$/.exec(cssPath);
+  return m ? (m[1] as string) : null;
+}
+
+/** Resolve a client-supplied `sourceFile` (from `options.selection.file`, a
+ *  main-origin but caller-controlled string — see scope.ts's `readHints`)
+ *  against `repoRoot`, rejecting anything that escapes it — mirrors
+ *  `resolveCanvasAbs`'s containment check (api.ts) so this new read-path
+ *  doesn't skip the same-origin path-traversal guard the rest of the
+ *  codebase applies to disk reads. Returns null (skip print geometry for
+ *  that page) rather than throwing — a bad path here must not fail the export. */
+function resolveSourceFileUnderRoot(repoRoot: string, sourceFile: string): string | null {
+  const abs = path.resolve(repoRoot, sourceFile);
+  const resolvedRoot = path.resolve(repoRoot);
+  if (abs !== resolvedRoot && !abs.startsWith(`${resolvedRoot}${path.sep}`)) return null;
+  return abs;
+}
+
 async function capturePdf(
   target: Extract<Target, { kind: 'element' }>,
   ctx: ExportContext,
   outDir: string,
   timeoutSec: number,
+  deviceScale: number,
   hooks?: ExportHooks
 ): Promise<string[]> {
   const args = [
@@ -41,6 +95,8 @@ async function capturePdf(
     target.cssPath,
     '--timeout',
     String(timeoutSec),
+    '--scale',
+    String(deviceScale),
   ];
   if (target.multi) args.push('--multi', '1', '--out-dir', outDir);
   else {
@@ -58,6 +114,188 @@ async function capturePdf(
   });
 }
 
+export interface MarksOptions {
+  crop: boolean;
+  registration: boolean;
+  colorBars: boolean;
+  pageInfo: boolean;
+}
+
+export interface PdfPrintOptions {
+  /** Default true when the artboard's own bleedMm > 0 (Design Decision 5). */
+  includeBleed?: boolean;
+  marks: MarksOptions;
+}
+
+/**
+ * Validate + clamp `options.pdfPrint` — per exporters/index.ts's own
+ * contract, new print params enter through the free-form options bag and
+ * MUST be clamped/validated in-adapter (no schema gate exists upstream).
+ * Unknown/malformed shapes degrade to "print post-pass off" rather than
+ * throwing — a bad options bag should never break a plain export.
+ */
+export function parsePdfPrintOptions(raw: unknown): PdfPrintOptions | null {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
+  const o = raw as Record<string, unknown>;
+  const marksRaw =
+    o.marks && typeof o.marks === 'object' && !Array.isArray(o.marks)
+      ? (o.marks as Record<string, unknown>)
+      : {};
+  return {
+    includeBleed: typeof o.includeBleed === 'boolean' ? o.includeBleed : undefined,
+    marks: {
+      crop: marksRaw.crop === true,
+      registration: marksRaw.registration === true,
+      colorBars: marksRaw.colorBars === true,
+      pageInfo: marksRaw.pageInfo === true,
+    },
+  };
+}
+
+/** `options.pageFit` — a paper preset id for non-print artboards, or null. */
+export function parsePageFit(raw: unknown): string | null {
+  if (typeof raw !== 'string') return null;
+  return getPaperPreset(raw) ? raw : null;
+}
+
+/**
+ * PDF's own device-scale resolver — deliberately NOT `png.ts`'s
+ * `resolveDeviceScale`, which defaults an absent `dpi` to `clampScale(undefined)`
+ * = 2× (PNG's own "a 1× export was uselessly small" UX default). A vector PDF's
+ * text/shapes are already crisp at 1×; only embedded raster content benefits
+ * from a higher capture density, and only when the caller actually asks for
+ * it via `dpi` — defaulting every PDF export to 2× would silently double
+ * embedded-image weight/render time for the common "just export a PDF" case.
+ */
+export function resolvePdfDeviceScale(options: ExportOptions): number {
+  const dpi = clampDpi(options.dpi);
+  return dpi !== undefined ? dpi / CSS_DPI : 1;
+}
+
+/**
+ * Apply the print-ready post-pass to one page: enlarge MediaBox (negative
+ * origin, content untouched), set BleedBox/TrimBox, draw marks. `bleedMm`
+ * comes from the artboard's OWN `print` prop (read by the caller) — never a
+ * value re-derived here, so on-canvas guides (T3) and this export can never
+ * disagree about where the trim line is.
+ */
+export function applyPrintBoxesAndMarks(
+  page: PDFPage,
+  bleedMm: number,
+  printOpts: PdfPrintOptions
+): void {
+  const { width: pageWidthPt, height: pageHeightPt } = page.getSize();
+  const bleedPt = mmToPt(bleedMm);
+  const includeBleed = printOpts.includeBleed ?? bleedMm > 0;
+
+  // Bleed box IS the full rendered page (Design Decision 1 — the artboard
+  // authored its own width/height as trim + 2×bleed). Trim box insets by
+  // bleedPt on every side. When the caller opts OUT of bleed, both boxes
+  // collapse onto the trim rect (still a valid MediaBox ⊇ BleedBox ⊇ TrimBox
+  // nesting — degenerate but not violated) and the MediaBox itself starts
+  // there too, effectively cropping the bleed strip out of the visible area
+  // (PDF viewers/printers clip to MediaBox) without moving any content.
+  const trimX = bleedPt;
+  const trimY = bleedPt;
+  const trimW = Math.max(0, pageWidthPt - 2 * bleedPt);
+  const trimH = Math.max(0, pageHeightPt - 2 * bleedPt);
+  const baseBox = includeBleed
+    ? { x: 0, y: 0, w: pageWidthPt, h: pageHeightPt }
+    : { x: trimX, y: trimY, w: trimW, h: trimH };
+
+  const wantsMarks = printOpts.marks.crop || printOpts.marks.registration;
+  const slugPt = wantsMarks
+    ? requiredSlugPt({ crop: printOpts.marks.crop, registration: printOpts.marks.registration })
+    : 0;
+
+  page.setMediaBox(
+    baseBox.x - slugPt,
+    baseBox.y - slugPt,
+    baseBox.w + 2 * slugPt,
+    baseBox.h + 2 * slugPt
+  );
+  page.setBleedBox(
+    includeBleed ? 0 : trimX,
+    includeBleed ? 0 : trimY,
+    includeBleed ? pageWidthPt : trimW,
+    includeBleed ? pageHeightPt : trimH
+  );
+  page.setTrimBox(trimX, trimY, trimW, trimH);
+
+  if (wantsMarks) {
+    // Marks always reference the FULL render (bleed-box) coordinate frame —
+    // they show where the trim line is regardless of whether bleed itself is
+    // included in the visible MediaBox.
+    const geo = computeMarksGeometry({
+      pageWidthPt,
+      pageHeightPt,
+      bleedPt,
+      crop: printOpts.marks.crop,
+      registration: printOpts.marks.registration,
+    });
+    const black = rgb(0, 0, 0);
+    for (const seg of geo.cropMarks) {
+      page.drawLine({
+        start: { x: seg.x1, y: seg.y1 },
+        end: { x: seg.x2, y: seg.y2 },
+        thickness: MARK_STROKE_PT,
+        color: black,
+      });
+    }
+    for (const mark of geo.registrationMarks) {
+      page.drawCircle({
+        x: mark.circle.cx,
+        y: mark.circle.cy,
+        size: mark.circle.r,
+        borderColor: black,
+        borderWidth: MARK_STROKE_PT,
+      });
+      for (const seg of mark.crosshair) {
+        page.drawLine({
+          start: { x: seg.x1, y: seg.y1 },
+          end: { x: seg.x2, y: seg.y2 },
+          thickness: MARK_STROKE_PT,
+          color: black,
+        });
+      }
+    }
+  }
+}
+
+/**
+ * `pageFit` — scale-to-paper for a NON-print artboard (Design Decision 6's
+ * counterpart for the export.md `--option pageFit=a4` surface: PDF is
+ * always vector, so "DPI" never applies here). Embeds the rendered page as
+ * an XObject on a fresh page sized to the target paper, uniformly scaled +
+ * centered, and swaps it in at the same index.
+ */
+export async function applyPageFit(
+  doc: PDFDocument,
+  pageIndex: number,
+  paperId: string
+): Promise<void> {
+  const preset = getPaperPreset(paperId);
+  if (!preset) return;
+  const { widthMm, heightMm } = trimSizeMm(preset, 'portrait');
+  const widthPt = mmToPt(widthMm);
+  const heightPt = mmToPt(heightMm);
+  const original = doc.getPage(pageIndex);
+  const { width: origW, height: origH } = original.getSize();
+  if (origW <= 0 || origH <= 0) return;
+  const embedded = await doc.embedPage(original);
+  const scale = Math.min(widthPt / origW, heightPt / origH);
+  const drawW = origW * scale;
+  const drawH = origH * scale;
+  const newPage = doc.insertPage(pageIndex, [widthPt, heightPt]);
+  newPage.drawPage(embedded, {
+    x: (widthPt - drawW) / 2,
+    y: (heightPt - drawH) / 2,
+    width: drawW,
+    height: drawH,
+  });
+  doc.removePage(pageIndex + 1); // the original, now shifted one slot later
+}
+
 export async function run(
   targets: Target[],
   options: ExportOptions,
@@ -74,37 +312,113 @@ export async function run(
     throw new Error('pdf adapter requires element targets (got file-tree)');
   }
   const timeoutSec = (options.timeoutSec as number | undefined) ?? 12;
+  const printOpts = parsePdfPrintOptions(options.pdfPrint);
+  const pageFit = parsePageFit(options.pageFit);
+  // Dogfood follow-up — raster CONTENT on the artboard (a dropped photo, a
+  // large-format piece authored at a fraction of its physical size) needs a
+  // real deviceScaleFactor to embed at print density; the page itself stays
+  // vector regardless (see the file header comment). Default 1× (today's
+  // behavior) when `dpi` is absent.
+  const deviceScale = resolvePdfDeviceScale(options);
   const tmp = mkdtempSync(path.join(tmpdir(), 'maude-pdf-'));
   try {
-    const written: string[] = [];
+    // written[i] = { path, sourceFile (repo-relative canvas), artboardId }.
+    // artboardId is per-PAGE — a `--multi` capture writes one file per
+    // artboard, so this is populated per file, not per top-level Target.
+    const written: Array<{ path: string; sourceFile: string; artboardId: string | null }> = [];
     for (let i = 0; i < elementTargets.length; i += 1) {
-      const paths = await capturePdf(elementTargets[i], ctx, tmp, timeoutSec, hooks);
-      written.push(...paths);
-      // Outer-loop tick (N separate top-level Targets — rare). The granular
-      // "K of M artboards" signal for canvas-as-separate comes from the
-      // shim's own MAUDE_PROGRESS lines via spawnShim's onProgress inside
-      // capturePdf, above — both funnel into the same hooks.onProgress.
+      const target = elementTargets[i] as Extract<Target, { kind: 'element' }>;
+      const paths = await capturePdf(target, ctx, tmp, timeoutSec, deviceScale, hooks);
+      if (target.multi) {
+        // _pdf-playwright.mjs names multi output `${data-dc-screen}.pdf`.
+        for (const p of paths) {
+          written.push({
+            path: p,
+            sourceFile: target.file,
+            artboardId: path.basename(p, '.pdf'),
+          });
+        }
+      } else {
+        for (const p of paths) {
+          written.push({
+            path: p,
+            sourceFile: target.file,
+            artboardId: artboardIdFromCssPath(target.cssPath),
+          });
+        }
+      }
       hooks?.onProgress?.({ current: i + 1, total: elementTargets.length });
     }
     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';
+
+    const baseSlug = elementTargets[0]?.canvasSlug ?? 'export';
+    const needsPostPass = !!printOpts || !!pageFit;
+
+    // Fast path — no print/pageFit options given: pass Chromium's vector PDF
+    // straight through, exactly as before this feature (zero pdf-lib
+    // round-trip overhead for the common "just export a PDF" case).
+    if (!needsPostPass) {
+      const [only] = written;
+      if (written.length === 1 && only) {
+        const bytes = new Uint8Array(readFileSync(only.path));
+        return { filename: `${baseSlug}.pdf`, contentType: 'application/pdf', body: bytes };
+      }
+      const out = await PDFDocument.create();
+      for (const w of written) {
+        const src = await PDFDocument.load(new Uint8Array(readFileSync(w.path)));
+        const pages = await out.copyPages(src, src.getPageIndices());
+        for (const page of pages) out.addPage(page);
+      }
+      const bytes = await out.save();
       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.
+
+    // Post-pass path — every page goes through pdf-lib (single-page case now
+    // included, per T5's "extend the existing pdf-lib load to single-page
+    // too"), so boxes/marks/pageFit apply uniformly regardless of scope.
     const out = await PDFDocument.create();
-    for (const p of written) {
-      const src = await PDFDocument.load(new Uint8Array(readFileSync(p)));
+    // Cache canvas source text per file — a canvas-as-separate export reads
+    // the SAME source repeatedly (once per artboard) otherwise.
+    const sourceCache = new Map<string, string>();
+    for (const w of written) {
+      const src = await PDFDocument.load(new Uint8Array(readFileSync(w.path)));
       const pages = await out.copyPages(src, src.getPageIndices());
-      for (const page of pages) out.addPage(page);
+      for (const page of pages) {
+        const pageIndex = out.getPageCount();
+        out.addPage(page);
+        let printProp: Record<string, unknown> | null = null;
+        if (w.artboardId) {
+          const abs = resolveSourceFileUnderRoot(ctx.repoRoot, w.sourceFile);
+          if (abs) {
+            let text = sourceCache.get(abs);
+            if (text === undefined) {
+              try {
+                text = readFileSync(abs, 'utf8');
+              } catch {
+                text = '';
+              }
+              sourceCache.set(abs, text);
+            }
+            if (text) printProp = readArtboardPrintProp(abs, text, w.artboardId);
+          }
+        }
+        if (printProp && printOpts) {
+          const paper = typeof printProp.paper === 'string' ? printProp.paper : 'a4';
+          const bleedMmRaw = printProp.bleedMm;
+          const bleedMm = resolveBleedMm({
+            paper,
+            bleedMm: typeof bleedMmRaw === 'number' ? bleedMmRaw : undefined,
+          });
+          applyPrintBoxesAndMarks(page, bleedMm, printOpts);
+        } else if (!printProp && pageFit) {
+          // Non-print artboard + pageFit requested — scale-to-paper.
+          await applyPageFit(out, pageIndex, pageFit);
+        }
+      }
     }
     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 });