@1agh/maude 1.0.11 → 1.3.0

package/apps/studio/export-dialog.tsx

@@ -139,6 +139,38 @@ const PDF_DPI_OPTIONS: readonly PdfDpiOption[] = [
 ];
 const PDF_DPI_DEFAULT = 'auto';
 
+// issue #116 — how the export treats text. Mirrors app.jsx's PDF_TEXT_OPTIONS
+// (same mirror obligation as PDF_DPI_OPTIONS above).
+//
+// The list is FIXED regardless of whether Ghostscript is present on this
+// machine. Hiding "Convert to outlines" when gs is missing would need a new
+// capability route, and would answer the user's question ("can I send this to
+// a printer?") by making the answer invisible; a refusal that names the
+// one-line install is more honest and reaches them at the moment they care.
+type PdfTextOption = { id: 'keep' | 'embed' | 'outline'; label: string; description: string };
+const PDF_TEXT_OPTIONS: readonly PdfTextOption[] = [
+  {
+    id: 'keep',
+    label: 'Keep selectable (default)',
+    description:
+      'Text stays selectable and searchable. You are warned if a font came out unprintable.',
+  },
+  {
+    id: 'embed',
+    label: 'Verify fonts embedded',
+    description:
+      'Same file, but the export fails instead of shipping a font a print shop would reject.',
+  },
+  {
+    id: 'outline',
+    label: 'Convert to outlines (print-safe)',
+    description:
+      'Every glyph becomes a vector path — no fonts left to break. Text is no longer selectable ' +
+      'and the file can grow a lot. Needs Ghostscript installed locally; cloud workspaces have it.',
+  },
+];
+const PDF_TEXT_DEFAULT = 'keep';
+
 /**
  * The artboard under the viewport centre — the export dialog's notion of "the
  * active artboard" when nothing is selected. getBoundingClientRect is in
@@ -490,6 +522,7 @@ const DialogShell = (() => {
     const [pdfMarksCrop, setPdfMarksCrop] = useState(false);
     const [pdfMarksRegistration, setPdfMarksRegistration] = useState(false);
     const [pdfDpiId, setPdfDpiId] = useState<string>(PDF_DPI_DEFAULT);
+    const [pdfTextId, setPdfTextId] = useState<string>(PDF_TEXT_DEFAULT);
     // Optional — the dialog can be mounted in tests without a provider.
     const selSet = useSelectionSetOptional();
 
@@ -513,6 +546,10 @@ const DialogShell = (() => {
         };
         const pdfDpi = PDF_DPI_OPTIONS.find((d) => d.id === pdfDpiId)?.value;
         if (pdfDpi !== undefined) options.dpi = pdfDpi;
+        // Omitted for `keep` rather than sent explicitly: the adapter's default
+        // IS keep, so an untouched dialog produces the exact request body it
+        // did before this feature existed.
+        if (pdfTextId !== 'keep') options.text = pdfTextId;
       }
       onSubmit(format, scope, options);
     }, [
@@ -524,6 +561,7 @@ const DialogShell = (() => {
       pdfMarksCrop,
       pdfMarksRegistration,
       pdfDpiId,
+      pdfTextId,
       onSubmit,
     ]);
 
@@ -626,6 +664,22 @@ const DialogShell = (() => {
                 The page stays vector; this only sets the capture density for raster content on it
                 (dropped photos, large-format art).
               </p>
+              <label htmlFor="dc-ed-pdf-text">Text</label>
+              <select
+                id="dc-ed-pdf-text"
+                data-testid="export-pdf-text"
+                value={pdfTextId}
+                onChange={(e) => setPdfTextId(e.target.value)}
+              >
+                {PDF_TEXT_OPTIONS.map((t) => (
+                  <option key={t.id} value={t.id}>
+                    {t.label}
+                  </option>
+                ))}
+              </select>
+              <p className="dc-ed-desc">
+                {PDF_TEXT_OPTIONS.find((t) => t.id === pdfTextId)?.description}
+              </p>
               <label style={{ display: 'flex', alignItems: 'center', gap: 8, cursor: 'pointer' }}>
                 <input
                   type="checkbox"

package/apps/studio/exporters/degraded.ts

@@ -7,8 +7,8 @@
 // RCA `issue-mp4-audio-export-html5audio-silent-degrade`.
 
 /**
- * The file is real and the job is `done` — but it is NOT what was asked for,
- * and saying so is the whole point.
+ * The file is real and the job is `done` — but it is NOT clean, and saying so
+ * is the whole point.
  *
  * An mp4 export of a comp using `remotion`'s `<Audio>` (= `<Html5Audio>`, which
  * `@remotion/web-renderer` rejects outright) degrades to the video-only
@@ -17,10 +17,26 @@
  * for it, and the only trace was one `console.error` in the desktop app's
  * stderr — so the artifact and its ledger entry were indistinguishable from a
  * good export. This is what makes them distinguishable.
+ *
+ * Audio was the first instance of that shape, not the only one: issue #116 is
+ * the same failure in a different format. A PDF whose text came out as Type 3
+ * fonts is downloadable, opens fine, and looks right on screen — and a print
+ * shop's preflight rejects it. Both are "the file is real, the file is wrong",
+ * so both ride THIS channel rather than a parallel one: the job record, the
+ * history ledger, the WS emit, the pill and the completion toast are already
+ * wired to it, and a second notice type would have to re-earn all five.
+ *
+ * Every cause flag is optional — a degradation carries the one(s) that apply.
  */
 export interface ExportDegradation {
   /** The requested audio track is absent from the produced file. */
-  audioDropped: boolean;
+  audioDropped?: boolean;
+  /**
+   * Fonts a print shop's preflight will reject — Type 3 or genuinely
+   * non-embedded (issue #116). Names only, already stripped of their
+   * `AAAAAA+` subset prefixes; the count and the split live in `reason`.
+   */
+  fontsNotEmbedded?: string[];
   /** Human-readable cause, already newline-collapsed by the shim (DDR-054). */
   reason: string;
   /** One-line remedy — present only when the cause is a fixable authoring mistake. */

package/apps/studio/exporters/ghostscript.ts

@@ -0,0 +1,194 @@
+// Ghostscript — the `text: 'outline'` post-pass for PDF export (issue #116).
+//
+// Chromium emits Type 3 fonts for colour fonts and synthetic italics and has
+// no switch to stop it; `page.pdf()` has no outline mode; and pdf-lib cannot
+// convert a glyph to a path. Ghostscript's `-dNoOutputFonts` does exactly one
+// thing — replace every glyph with its vector outline — and it is the only
+// off-the-shelf tool that does. So this module shells out to it.
+//
+// WHY AN EXTERNAL BINARY, AND WHY IT IS NOT BUNDLED
+// ------------------------------------------------
+// Ghostscript is AGPL-3.0 and Maude is MIT. Exec'ing an unmodified `gs` the
+// user (or the image) installed is clean and ordinary; shipping it INSIDE the
+// signed `.app` would drag AGPL distribution obligations and third-party
+// notarization into the packaged product, on every platform, for one opt-in
+// export mode. So: `apps/render/Dockerfile` installs it, which makes the cloud
+// lane work with no user setup; the desktop app and the npm CLI resolve it off
+// PATH and fail LOUD when it is absent. Writing our own outliner was weighed
+// and rejected — see the DDR; the short version is that a DOM-side pass cannot
+// handle COLRv1 layering (the exact font that motivated the issue) and a
+// content-stream pass means emulating the whole PDF text-state machine.
+//
+// FAILURE POSTURE — DELIBERATELY THE OPPOSITE OF pptx.ts
+// -----------------------------------------------------
+// `pptx.ts` resolves an optional `svg2pptx` the same way and, when it is
+// missing, quietly falls back to a PNG deck. That is right there: the user
+// asked for slides and gets slides. It would be WRONG here. A user who asked
+// for outlines and silently receives a PDF with live Type 3 fonts has been
+// handed the precise artifact this feature exists to prevent, and will find
+// out from their printer. Missing `gs` is an error, never a fallback.
+
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+/**
+ * argv prefix for Ghostscript. `MAUDE_GHOSTSCRIPT` overrides (space-separated,
+ * so a wrapper or an absolute path both work); otherwise the usual binary
+ * names — `gs` everywhere, `gswin64c` on Windows (the console build; plain
+ * `gswin64` opens a GUI window and never returns).
+ *
+ * Resolved against the LIVE `process.env.PATH` rather than Bun's startup
+ * snapshot, matching `_runtime.ts`'s resolver: the desktop sidecar corrects
+ * PATH at spawn time (DDR-128), and a lookup against the stale snapshot would
+ * miss a `gs` that is genuinely reachable.
+ */
+export function ghostscriptArgv(): string[] | null {
+  const override = process.env.MAUDE_GHOSTSCRIPT?.trim();
+  if (override) return override.split(/\s+/);
+  const pathEnv = process.env.PATH;
+  const found = Bun.which('gs', { PATH: pathEnv }) ?? Bun.which('gswin64c', { PATH: pathEnv });
+  return found ? [found] : null;
+}
+
+export const GHOSTSCRIPT_MISSING_MESSAGE =
+  'Outlining text needs Ghostscript, which was not found on PATH. ' +
+  'Install it (macOS: `brew install ghostscript`, Debian/Ubuntu: `apt-get install ghostscript`, ' +
+  'Windows: `choco install ghostscript`), or set MAUDE_GHOSTSCRIPT to its path. ' +
+  'Exports run in a Maude workspace (cloud) already have it. ' +
+  'Without it, use text=embed to at least verify the fonts, or text=keep for today’s behaviour.';
+
+let _available: boolean | null = null;
+
+/** Is a usable Ghostscript reachable? Memoized — probed at most once per process. */
+export async function ghostscriptAvailable(): Promise<boolean> {
+  if (_available !== null) return _available;
+  const argv = ghostscriptArgv();
+  if (!argv) {
+    _available = false;
+    return false;
+  }
+  try {
+    const [bin, ...rest] = argv as [string, ...string[]];
+    const proc = Bun.spawn([bin, ...rest, '--version'], { stdout: 'pipe', stderr: 'pipe' });
+    _available = (await proc.exited) === 0;
+  } catch {
+    _available = false;
+  }
+  return _available;
+}
+
+/** Test seam — forget the memoized probe so a test can vary the environment. */
+export function resetGhostscriptProbe(): void {
+  _available = null;
+}
+
+/**
+ * The flag set, measured rather than assumed (plan Task 9).
+ *
+ * `-dNoOutputFonts` is the feature; everything else exists to stop Ghostscript
+ * from helpfully ruining the raster content on the way through. Measured on a
+ * three-page photo PDF (1600x1200 JPEG per page, `pdfimages -list` before and
+ * after):
+ *
+ *   | flags                                    | size    | image enc | px / ppi |
+ *   | pass-through ON  + forced Flate (this)   | 144 483 | jpeg      | identical |
+ *   | pass-through ON  only                    | 144 417 | jpeg      | identical |
+ *   | pass-through OFF + forced Flate          | 417 369 | flate     | identical |
+ *
+ * Two things that measurement settles:
+ *
+ *  1. **`-dPassThroughJPEGImages` is the flag that matters, and it is stated
+ *     explicitly on purpose.** It defaults to true, which is why the issue's
+ *     hand-run recipe did not corrupt anything — but the third row is what
+ *     happens the moment it does not win: every photo is decoded and re-encoded
+ *     as Flate, ~3x here and far worse on real photography (this is the
+ *     reported 16 MB -> 254 MB). Relying on a default for that is not a plan.
+ *  2. **The forced Flate filters stay anyway.** `AutoFilter*` defaults to true,
+ *     and for an image Ghostscript genuinely must re-encode (a Flate-encoded
+ *     source, which is what Chromium often produces) "auto" is free to choose
+ *     DCT — a LOSSY re-encode of lossless print artwork, silently. Pinning the
+ *     filter to Flate makes the only re-encode we can be handed a lossless one.
+ *
+ * `-dDownsample*=false` is the other half of the fidelity guarantee: without
+ * it Ghostscript resamples to its default target and quietly destroys print
+ * DPI. `-dSAFER` is default-on in gs >= 9.50 but passed explicitly — the input
+ * is user content.
+ */
+export const OUTLINE_FLAGS: readonly string[] = [
+  '-sDEVICE=pdfwrite',
+  '-dNoOutputFonts',
+  '-dCompatibilityLevel=1.7',
+  '-dPreserveMarkedContent=false',
+  '-dPassThroughJPEGImages=true',
+  '-dPassThroughJPXImages=true',
+  '-dAutoFilterColorImages=false',
+  '-dColorImageFilter=/FlateEncode',
+  '-dAutoFilterGrayImages=false',
+  '-dGrayImageFilter=/FlateEncode',
+  '-dDownsampleColorImages=false',
+  '-dDownsampleGrayImages=false',
+  '-dDownsampleMonoImages=false',
+  '-dBATCH',
+  '-dNOPAUSE',
+  '-dQUIET',
+  '-dSAFER',
+];
+
+export interface OutlineOptions {
+  /** Aborts the pass and kills Ghostscript. */
+  signal?: AbortSignal;
+  /** Wall-clock ceiling. Outlining a photo-heavy print job is genuinely slow. */
+  timeoutSec?: number;
+}
+
+/**
+ * Convert every glyph in `bytes` to vector outlines.
+ *
+ * Via temp files rather than stdin/stdout: `pdfwrite` seeks in its output, so
+ * it cannot write to a pipe, and feeding a large PDF through stdin buys
+ * nothing when the output has to land on disk regardless.
+ *
+ * Throws `GHOSTSCRIPT_MISSING_MESSAGE` when no `gs` resolves, and a message
+ * carrying Ghostscript's own stderr when it exits non-zero. It never returns
+ * the input unchanged — a caller that gets bytes back gets outlined bytes.
+ */
+export async function outlinePdf(
+  bytes: Uint8Array,
+  opts: OutlineOptions = {}
+): Promise<Uint8Array> {
+  const argv = ghostscriptArgv();
+  if (!argv || !(await ghostscriptAvailable())) throw new Error(GHOSTSCRIPT_MISSING_MESSAGE);
+
+  const dir = mkdtempSync(path.join(tmpdir(), 'maude-outline-'));
+  const inPath = path.join(dir, 'in.pdf');
+  const outPath = path.join(dir, 'out.pdf');
+  try {
+    await Bun.write(inPath, bytes);
+    const [bin, ...rest] = argv as [string, ...string[]];
+
+    // The caller's abort and our own timeout are one signal to the child, so a
+    // cancelled export and a hung Ghostscript are killed by the same path.
+    const timeoutSec = opts.timeoutSec ?? 600;
+    const signals = [AbortSignal.timeout(timeoutSec * 1000)];
+    if (opts.signal) signals.push(opts.signal);
+    const signal = AbortSignal.any(signals);
+
+    const proc = Bun.spawn([bin, ...rest, '-o', outPath, ...OUTLINE_FLAGS, inPath], {
+      stdout: 'pipe',
+      stderr: 'pipe',
+      signal,
+    });
+    const [code, stderr] = await Promise.all([proc.exited, new Response(proc.stderr).text()]);
+    if (code !== 0) {
+      if (opts.signal?.aborted) throw new Error('export cancelled');
+      const detail = stderr.trim().split('\n').slice(0, 4).join(' ').slice(0, 500);
+      throw new Error(
+        `Ghostscript failed to outline the PDF (exit ${code})${detail ? `: ${detail}` : ''}`
+      );
+    }
+    return new Uint8Array(readFileSync(outPath));
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}

package/apps/studio/exporters/pdf-fonts.ts

@@ -0,0 +1,261 @@
+// PDF font preflight — issue #116.
+//
+// Chromium's `page.pdf()` is vector-faithful for geometry but NOT for every
+// font: a COLRv1 colour font (`@font-palette-values`) and a SYNTHETIC italic
+// (CSS asks for `italic`, no real italic face is loaded) both come out as
+// **Type 3** fonts. A Type 3 font is not a font program at all — each glyph is
+// its own little content stream — so a print shop's preflight reports it as
+// "font not embedded", Acrobat/Illustrator render it broken, and DTP has to
+// re-substitute by hand. The export looked clean from every angle Maude could
+// see; the only way to find out was `pdffonts` on the delivered file, or the
+// printer refusing it.
+//
+// This module is the "see it" half. It walks the assembled document's font
+// dictionaries and classifies every font, with NO external tool and NO new
+// dependency — pdf-lib is already here, it just has no font-inspection API, so
+// we walk the object graph by hand. The classification drives both the
+// always-on notice (`text: 'keep'`) and the hard refusal (`text: 'embed'`);
+// `text: 'outline'` re-runs it after Ghostscript as a self-check.
+//
+// Deliberately pure (a `PDFDocument` in, an array out): no I/O, no spawn, no
+// clock — so it is unit-testable against hand-built fixtures the same way
+// `print/marks.ts` is.
+
+import {
+  PDFArray,
+  PDFDict,
+  type PDFDocument,
+  PDFName,
+  type PDFObject,
+  PDFRef,
+  PDFStream,
+} from 'pdf-lib';
+
+/**
+ * What a print shop's preflight will say about this font.
+ *
+ * `type3` is called out separately from `not-embedded` even though a printer
+ * rejects both, because the CAUSE and the remedy differ: a Type 3 font is
+ * Chromium telling us it had no other representation for these glyphs
+ * (outline it), while a genuinely non-embedded font is a font the document
+ * merely REFERENCES and expects the reader to have (embed or outline it).
+ */
+export type PdfFontKind = 'embedded' | 'type3' | 'not-embedded';
+
+export interface PdfFontInfo {
+  /** `/BaseFont` with the `AAAAAA+` subset prefix stripped, or a placeholder. */
+  name: string;
+  kind: PdfFontKind;
+  /** Raw `/Subtype` as written in the font dict (`Type0`, `TrueType`, `Type3`, ...). */
+  subtype: string;
+  /**
+   * This Type 3 font's base name ALSO appears in the document as a real
+   * embedded font — the signature of a synthetic italic (Chromium slants the
+   * upright face itself and emits the slanted glyphs as Type 3, while the
+   * unslanted runs still use the real embedded face). Worth surfacing
+   * separately because unlike a colour font this one is fixable at the source:
+   * load the real italic face and the Type 3 font disappears.
+   */
+  syntheticItalicSuspect: boolean;
+}
+
+/** `AAAAAA+Foo-Bold` -> `Foo-Bold`. A subset prefix is exactly six capitals. */
+export function stripSubsetPrefix(baseFont: string): string {
+  return baseFont.replace(/^[A-Z]{6}\+/, '');
+}
+
+/** Read a `/Name`-valued key as a plain string (`Type0`), or null. */
+function nameValue(dict: PDFDict, key: string): string | null {
+  const v = dict.lookup(PDFName.of(key));
+  return v instanceof PDFName ? v.decodeText() : null;
+}
+
+/**
+ * Does this FontDescriptor carry an actual font program?
+ *
+ * `/FontFile` (Type 1), `/FontFile2` (TrueType) and `/FontFile3` (CFF /
+ * OpenType) are the three spellings; any one present means the bytes are in
+ * the file. A descriptor with none — or no descriptor at all, which is how the
+ * standard 14 fonts appear — means the reader is expected to supply the font.
+ */
+function descriptorHasFontProgram(descriptor: PDFDict): boolean {
+  for (const key of ['FontFile', 'FontFile2', 'FontFile3']) {
+    const v = descriptor.lookup(PDFName.of(key));
+    if (v instanceof PDFStream) return true;
+  }
+  return false;
+}
+
+/**
+ * Classify ONE font dictionary.
+ *
+ * The `Type0` branch is the one that is easy to get wrong: a composite font's
+ * descriptor lives on its DESCENDANT, not on the parent dict, so reading
+ * `/FontDescriptor` off the parent finds nothing and would misreport every
+ * embedded CID font in the document as not-embedded — i.e. it would fire the
+ * warning on exactly the fonts that are fine.
+ */
+function classifyFontDict(font: PDFDict): PdfFontInfo | null {
+  const subtype = nameValue(font, 'Subtype');
+  if (!subtype) return null;
+
+  const baseFontRaw = nameValue(font, 'BaseFont');
+  // A Type 3 font is not required to have a /BaseFont at all. Chromium does set
+  // one, but a hand-authored or third-party PDF may not — name it after the
+  // subtype rather than dropping it from the report.
+  const name = baseFontRaw ? stripSubsetPrefix(baseFontRaw) : `(unnamed ${subtype})`;
+
+  if (subtype === 'Type3') {
+    return { name, kind: 'type3', subtype, syntheticItalicSuspect: false };
+  }
+
+  // Composite font — the real font program hangs off DescendantFonts[0].
+  let descriptorHost: PDFDict = font;
+  if (subtype === 'Type0') {
+    const descendants = font.lookup(PDFName.of('DescendantFonts'));
+    const first = descendants instanceof PDFArray ? descendants.lookup(0) : undefined;
+    if (first instanceof PDFDict) descriptorHost = first;
+  }
+
+  const descriptor = descriptorHost.lookup(PDFName.of('FontDescriptor'));
+  const embedded = descriptor instanceof PDFDict && descriptorHasFontProgram(descriptor);
+  return {
+    name,
+    kind: embedded ? 'embedded' : 'not-embedded',
+    subtype,
+    syntheticItalicSuspect: false,
+  };
+}
+
+/**
+ * Collect every font dict reachable from a resource dict, recursing through
+ * Form XObjects.
+ *
+ * The recursion is not theoretical here: `pdf.ts`'s `pageFit` path embeds the
+ * original page as a Form XObject and draws it on a fresh page, which moves
+ * every one of its fonts OUT of the page's own `/Font` resources and into the
+ * XObject's. A non-recursive walk would report "no fonts" for exactly the
+ * scale-to-paper exports that print shops receive.
+ *
+ * `seen` is keyed on ref numbers, so a shared resource dict (the common case —
+ * Chromium reuses one across pages) is walked once, and a cyclic
+ * XObject -> Resources -> XObject graph terminates instead of blowing the
+ * stack.
+ */
+function collectFontDicts(
+  resources: PDFObject | undefined,
+  out: PDFDict[],
+  seen: Set<string>
+): void {
+  if (!(resources instanceof PDFDict)) return;
+
+  const fonts = resources.lookup(PDFName.of('Font'));
+  if (fonts instanceof PDFDict) {
+    for (const key of fonts.keys()) {
+      const ref = fonts.get(key);
+      const id = ref instanceof PDFRef ? ref.toString() : null;
+      if (id) {
+        if (seen.has(id)) continue;
+        seen.add(id);
+      }
+      const font = fonts.lookup(key);
+      if (font instanceof PDFDict) out.push(font);
+    }
+  }
+
+  const xobjects = resources.lookup(PDFName.of('XObject'));
+  if (xobjects instanceof PDFDict) {
+    for (const key of xobjects.keys()) {
+      const ref = xobjects.get(key);
+      const id = ref instanceof PDFRef ? `xo:${ref.toString()}` : null;
+      if (id) {
+        if (seen.has(id)) continue;
+        seen.add(id);
+      }
+      const xo = xobjects.lookup(key);
+      if (xo instanceof PDFStream) {
+        collectFontDicts(xo.dict.lookup(PDFName.of('Resources')), out, seen);
+      }
+    }
+  }
+}
+
+/**
+ * Every distinct font in the document, classified.
+ *
+ * Deduped on `(name, kind)` rather than on dict identity: one font that
+ * Chromium split across pages is one line in a warning a human reads, not ten.
+ * The `(name, kind)` pair — rather than name alone — is deliberate, because the
+ * synthetic-italic case genuinely HAS the same base name twice with two
+ * different representations, and collapsing those would hide the very signal
+ * `syntheticItalicSuspect` exists to report.
+ */
+export function analyzePdfFonts(doc: PDFDocument): PdfFontInfo[] {
+  const dicts: PDFDict[] = [];
+  const seen = new Set<string>();
+  for (const page of doc.getPages()) {
+    // `Resources()`, NOT `lookup(PDFName.of('Resources'))`: `/Resources` is an
+    // INHERITABLE page attribute, and a producer is free to hang one shared
+    // dict off the Pages node instead of repeating it on every leaf. Reading
+    // the leaf directly then finds nothing and reports a document with fonts
+    // as having none — silently turning the whole preflight off for exactly
+    // the multi-page print exports it exists for.
+    collectFontDicts(page.node.Resources(), dicts, seen);
+  }
+
+  const byKey = new Map<string, PdfFontInfo>();
+  for (const dict of dicts) {
+    const info = classifyFontDict(dict);
+    if (!info) continue;
+    const key = `${info.name} ${info.kind}`;
+    if (!byKey.has(key)) byKey.set(key, info);
+  }
+
+  const all = [...byKey.values()];
+  const embeddedNames = new Set(all.filter((f) => f.kind === 'embedded').map((f) => f.name));
+  for (const info of all) {
+    if (info.kind === 'type3' && embeddedNames.has(info.name)) info.syntheticItalicSuspect = true;
+  }
+  return all;
+}
+
+/** The fonts a print shop's preflight will reject — Type 3 and non-embedded. */
+export function unprintableFonts(fonts: PdfFontInfo[]): PdfFontInfo[] {
+  return fonts.filter((f) => f.kind !== 'embedded');
+}
+
+/**
+ * The one-line problem statement + remedy for a set of bad fonts, shared by the
+ * `keep` notice and the `embed` refusal so the two can never drift into
+ * describing the same document differently.
+ */
+export function describeFontProblem(bad: PdfFontInfo[]): { reason: string; remedy: string } {
+  const type3 = bad.filter((f) => f.kind === 'type3');
+  const missing = bad.filter((f) => f.kind === 'not-embedded');
+  const parts: string[] = [];
+  if (type3.length) {
+    parts.push(
+      `${type3.length} font${type3.length === 1 ? '' : 's'} exported as Type 3 ` +
+        `(${type3.map((f) => f.name).join(', ')})`
+    );
+  }
+  if (missing.length) {
+    parts.push(
+      `${missing.length} font${missing.length === 1 ? '' : 's'} not embedded ` +
+        `(${missing.map((f) => f.name).join(', ')})`
+    );
+  }
+  const reason = `${parts.join('; ')} — a print shop's preflight will reject ${
+    bad.length === 1 ? 'it' : 'them'
+  }.`;
+
+  const suspects = bad.filter((f) => f.syntheticItalicSuspect);
+  const italicNote = suspects.length
+    ? ` ${suspects.map((f) => f.name).join(', ')} looks like a synthetic italic — ` +
+      'loading the real italic face fixes that one at the source.'
+    : '';
+  return {
+    reason,
+    remedy: `Re-export with text=outline to convert all text to curves.${italicNote}`,
+  };
+}