feat(v1.4.0.0): /make-pdf — markdown to publication-quality PDFs (#1086)

* feat(browse): full $B pdf flag contract + tab-scoped load-html/js/pdf Grow $B pdf from a 2-line wrapper (hard-coded A4) into a real PDF engine frontend so make-pdf can shell out to it without duplicating Playwright: - pdf: --format, --width/--height, --margins, --margin-*, --header-template, --footer-template, --page-numbers, --tagged, --outline, --print-background, --prefer-css-page-size, --toc. Mutex rules enforced. --from-file <json> dodges Windows argv limits (8191 char CreateProcess cap). - load-html: add --from-file <json> mode for large inline HTML. Size + magic byte checks still apply to the inline content, not the payload file path. - newtab: add --json returning {"tabId":N,"url":...} for programmatic use. - cli: extract --tab-id flag and route as body.tabId to the HTTP layer so parallel callers can target specific tabs without racing on the active tab (makes make-pdf's per-render tab isolation possible). - --toc: non-fatal 3s wait for window.__pagedjsAfterFired. Paged.js ships later; v1 renders TOC statically via the markdown renderer. Codex round 2 flagged these P0 issues during plan review. All resolved. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(resolvers): add MAKE_PDF_SETUP + makePdfDir host paths Skill templates can now embed {{MAKE_PDF_SETUP}} to resolve $P to the make-pdf binary via the same discovery order as $B / $D: env override (MAKE_PDF_BIN), local skill root, global install, or PATH. Mirrors the pattern established by generateBrowseSetup() and generateDesignSetup() in scripts/resolvers/design.ts. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(make-pdf): new /make-pdf skill + orchestrator binary Turn markdown into publication-quality PDFs. $P generate input.md out.pdf produces a PDF with 1in margins, intelligent page breaks, page numbers, running header, CONFIDENTIAL footer, and curly quotes/em dashes — all on Helvetica so copy-paste extraction works ("S ai li ng" bug avoided). Architecture (per Codex round 2): markdown → render.ts (marked + sanitize + smartypants) → orchestrator → $B newtab --json → $B load-html --tab-id → $B js (poll Paged.js) → $B pdf --tab-id → $B closetab browseClient.ts shells out to the compiled browse CLI rather than duplicating Playwright. --tab-id isolation per render means parallel $P generate calls don't race on the active tab. try/finally tab cleanup survives Paged.js timeouts, browser crashes, and output-path failures. Features in v1: --cover left-aligned cover page (eyebrow + title + hairline rule) --toc clickable static TOC (Paged.js page numbers deferred) --watermark <text> diagonal DRAFT/CONFIDENTIAL layer --no-chapter-breaks opt out of H1-starts-new-page --page-numbers "N of M" footer (default on) --tagged --outline accessible PDF + bookmark outline (default on) --allow-network opt in to external image loading (default off for privacy) --quiet --verbose stderr control Design decisions locked from the /plan-design-review pass: - Helvetica everywhere (Chromium emits single-word Tj operators for system fonts; bundled webfonts emit per-glyph and break extraction). - Left-aligned body, flush-left paragraphs, no text-indent, 12pt gap. - Cover shares 1in margins with body pages; no flexbox-center, no inset padding. - The reference HTMLs at .context/designs/*.html are the implementation source of truth for print-css.ts. Tests (56 unit + 1 E2E combined-features gate): - smartypants: code/URL-safe, verified against 10 fixtures - sanitizer: strips <script>/<iframe>/on*/javascript: URLs - render: HTML assembly, CJK fallback, cover/TOC/chapter wrap - print-css: all @page rules, margin variants, watermark - pdftotext: normalize()+copyPasteGate() cross-OS tolerance - browseClient: binary resolution + typed error propagation - combined-features gate (P0): 2-chapter fixture with smartypants + hyphens + ligatures + bold/italic + inline code + lists + blockquote passes through PDF → pdftotext → expected.txt diff Deferred to Phase 4 (future PR): Paged.js vendored for accurate TOC page numbers, highlight.js for syntax highlighting, drop caps, pull quotes, two-column, CMYK, watermark visual-diff acceptance. Plan: .context/ceo-plans/2026-04-19-perfect-pdf-generator.md References: .context/designs/make-pdf-*.html Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * chore(build): wire make-pdf into build/test/setup/bin + add marked dep - package.json: compile make-pdf/dist/pdf as part of bun run build; add "make-pdf" to bin entry; include make-pdf/test/ in the free test pass; add marked@18.0.2 as a dep (markdown parser, ~40KB). - setup: add make-pdf/dist/pdf to the Apple Silicon codesign loop. - .gitignore: add make-pdf/dist/ (matches browse/dist/ and design/dist/). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * ci(make-pdf): matrix copy-paste gate on Ubuntu + macOS Runs the combined-features P0 gate on pull requests that touch make-pdf/ or browse's PDF surface. Installs poppler (macOS) / poppler-utils (Ubuntu) per OS. Windows deferred to tolerant mode (Xpdf / Poppler-Windows extraction variance not yet calibrated against the normalized comparator — Codex round 2 #18). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(skills): regenerate SKILL.md for make-pdf addition + browse pdf flags bun run gen:skill-docs picks up: - the new /make-pdf skill (make-pdf/SKILL.md) - updated browse command descriptions for 'pdf', 'load-html', 'newtab' reflecting the new flag contract and --from-file mode Source of truth stays the .tmpl files + COMMAND_DESCRIPTIONS; these are regenerated artifacts. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(tests): repair stale test expectations + emit _EXPLAIN_LEVEL / _QUESTION_TUNING from preamble Three pre-existing test failures on main were blocking /ship: - test/skill-validation.test.ts "Step 3.4 test coverage audit" expected the literal strings "CODE PATH COVERAGE" and "USER FLOW COVERAGE" which were removed when the Step 7 coverage diagram was compressed. Updated assertions to check the stable `Code paths:` / `User flows:` labels that still ship. - test/skill-validation.test.ts "ship step numbering" allowed-substeps list didn't include 15.0 (WIP squash) and 15.1 (bisectable commits) which were added for continuous checkpoint mode. Extended the allowlist. - test/writing-style-resolver.test.ts and test/plan-tune.test.ts expected `_EXPLAIN_LEVEL` and `_QUESTION_TUNING` bash variables in the preamble but generate-preamble-bash.ts had been refactored and those lines were dropped. Without them, downstream skills can't read `explain_level` or `question_tuning` config at runtime — terse mode and /plan-tune features were silently broken. Added the two bash echo blocks back to generatePreambleBash and refreshed the golden-file fixtures to match. All three preamble-related golden baselines (claude/codex/factory) are synchronized with the new output. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * chore: bump version and changelog (v1.4.0.0) New /make-pdf skill + $P binary. Turn any markdown file into a publication-quality PDF. Default output is a 1in-margin Helvetica letter with page numbers in the footer. `--cover` adds a left-aligned cover page, `--toc` generates a clickable table of contents, `--watermark DRAFT` overlays a diagonal watermark. Copy-paste extraction from the PDF produces clean words, not "S a i l i n g" spaced out letter by letter. CI gate (macOS + Ubuntu) runs a combined- features fixture through pdftotext on every PR. make-pdf shells out to browse rather than duplicating Playwright. $B pdf grew into a real PDF engine with full flag contract (--format, --margins, --header-template, --footer-template, --page-numbers, --tagged, --outline, --toc, --tab-id, --from-file). $B load-html and $B js gained --tab-id. $B newtab --json returns structured output. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(changelog): rewrite v1.4.0.0 headline — positive voice, no VC framing The original headline led with "a PDF you wouldn't be embarrassed to send to a VC": double-negative voice and audience-too-narrow. /make-pdf works for essays, letters, memos, reports, proposals, and briefs. Framing the whole release around founders-to-investors misses the wider audience. New headline: "Turn any markdown file into a PDF that looks finished." New tagline: "This one reads like a real essay or a real letter." Positive voice. Broader aperture. Same energy. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-18 02:22:04 +08:00 · 2026-04-20 13:20:30 +08:00
parent 22a4451e0e
commit d0782c4c4d
74 changed files with 4456 additions and 37 deletions
--- a/make-pdf/src/print-css.ts
+++ b/make-pdf/src/print-css.ts
@@ -0,0 +1,350 @@
+/**
+ * Print stylesheet generator.
+ *
+ * Source of truth: .context/designs/make-pdf-print-reference.html and siblings.
+ * Mirror those CSS rules here. The HTML references were approved via
+ * /plan-design-review with explicit design decisions locked in the plan:
+ *
+ *   - Helvetica only (system font, no bundled webfonts — dodges the
+ *     per-glyph Tj bug that breaks copy-paste extraction).
+ *   - All paragraphs flush-left. No first-line indent, no justify, no
+ *     p+p indent. text-align: left everywhere. 12pt margin-bottom.
+ *   - Cover page has the same 1in margins as every other page. No flexbox
+ *     center, no inset padding, no vertical centering. Distinction comes
+ *     from eyebrow + larger title + hairline rule, not from centering.
+ *   - `@page :first` suppresses running header/footer but does NOT override
+ *     the 1in margin.
+ *   - No <link>, no external CSS/fonts — everything inlined.
+ *   - CJK fallback: Helvetica, Arial, Hiragino Kaku Gothic ProN, Noto Sans
+ *     CJK JP, Microsoft YaHei, sans-serif.
+ */
+
+export interface PrintCssOptions {
+  // Document structure
+  cover?: boolean;
+  toc?: boolean;
+  noChapterBreaks?: boolean;
+
+  // Branding
+  watermark?: string;
+  confidential?: boolean;
+
+  // Header (running title, top of page)
+  runningHeader?: string;
+
+  // Page size (in CSS `@page size:` terms)
+  pageSize?: "letter" | "a4" | "legal" | "tabloid";
+
+  // Margins (default 1in)
+  margins?: string;
+}
+
+/**
+ * Produce a CSS block (no <style> wrapper) for inline injection.
+ */
+export function printCss(opts: PrintCssOptions = {}): string {
+  const size = opts.pageSize ?? "letter";
+  const margin = opts.margins ?? "1in";
+  const hasWatermark = typeof opts.watermark === "string" && opts.watermark.length > 0;
+
+  return [
+    pageRules(size, margin, opts),
+    rootTypography(),
+    coverRules(opts.cover === true),
+    tocRules(opts.toc === true),
+    chapterRules(opts.noChapterBreaks === true),
+    blockRules(),
+    inlineRules(),
+    codeRules(),
+    quoteRules(),
+    figureRules(),
+    tableRules(),
+    listRules(),
+    footnoteRules(),
+    hasWatermark ? watermarkRules() : "",
+    breakAvoidRules(),
+  ].filter(Boolean).join("\n\n");
+}
+
+function pageRules(size: string, margin: string, opts: PrintCssOptions): string {
+  const runningHeader = escapeCssString(opts.runningHeader ?? "");
+  const showConfidential = opts.confidential !== false;
+
+  return [
+    `@page {`,
+    `  size: ${size};`,
+    `  margin: ${margin};`,
+    runningHeader
+      ? `  @top-center { content: "${runningHeader}"; font-family: Helvetica, Arial, sans-serif; font-size: 9pt; color: #666; }`
+      : ``,
+    `  @bottom-center { content: counter(page) " of " counter(pages); font-family: Helvetica, Arial, sans-serif; font-size: 9pt; color: #666; }`,
+    showConfidential
+      ? `  @bottom-right { content: "CONFIDENTIAL"; font-family: Helvetica, Arial, sans-serif; font-size: 8pt; color: #aaa; letter-spacing: 0.05em; }`
+      : ``,
+    `}`,
+    ``,
+    // Cover page: suppress running header/footer but keep margins.
+    `@page :first {`,
+    `  @top-center { content: none; }`,
+    `  @bottom-center { content: none; }`,
+    `  @bottom-right { content: none; }`,
+    `}`,
+  ].filter(line => line !== "").join("\n");
+}
+
+function rootTypography(): string {
+  return [
+    `html { lang: en; }`,
+    `body {`,
+    `  font-family: Helvetica, Arial, "Hiragino Kaku Gothic ProN", "Noto Sans CJK JP", "Microsoft YaHei", sans-serif;`,
+    `  font-size: 11pt;`,
+    `  line-height: 1.5;`,
+    `  color: #111;`,
+    `  background: white;`,
+    `  hyphens: auto;`,
+    `  font-variant-ligatures: common-ligatures;`,
+    `  font-kerning: normal;`,
+    `  text-rendering: geometricPrecision;`,
+    `  margin: 0;`,
+    `  padding: 0;`,
+    `}`,
+  ].join("\n");
+}
+
+function coverRules(enabled: boolean): string {
+  if (!enabled) return "";
+  return [
+    `.cover {`,
+    `  page: first;`,
+    `  page-break-after: always;`,
+    `  break-after: page;`,
+    `  text-align: left;`,
+    `}`,
+    `.cover .eyebrow {`,
+    `  font-size: 9pt;`,
+    `  letter-spacing: 0.2em;`,
+    `  text-transform: uppercase;`,
+    `  color: #666;`,
+    `  margin: 0 0 36pt;`,
+    `}`,
+    `.cover h1.cover-title {`,
+    `  font-size: 32pt;`,
+    `  line-height: 1.15;`,
+    `  font-weight: 700;`,
+    `  letter-spacing: -0.01em;`,
+    `  margin: 0 0 18pt;`,
+    `  max-width: 5.5in;`,
+    `  text-align: left;`,
+    `}`,
+    `.cover .cover-subtitle {`,
+    `  font-size: 14pt;`,
+    `  line-height: 1.4;`,
+    `  font-weight: 400;`,
+    `  color: #333;`,
+    `  margin: 0 0 36pt;`,
+    `  max-width: 5in;`,
+    `  text-align: left;`,
+    `}`,
+    `.cover hr.rule {`,
+    `  width: 2.5in;`,
+    `  height: 0;`,
+    `  border: 0;`,
+    `  border-top: 1px solid #111;`,
+    `  margin: 0 0 18pt 0;`,
+    `}`,
+    `.cover .cover-meta { font-size: 10pt; line-height: 1.6; color: #333; text-align: left; }`,
+    `.cover .cover-meta strong { font-weight: 700; }`,
+  ].join("\n");
+}
+
+function tocRules(enabled: boolean): string {
+  if (!enabled) return "";
+  return [
+    `.toc { page-break-after: always; break-after: page; }`,
+    `.toc h2 {`,
+    `  font-size: 13pt;`,
+    `  text-transform: uppercase;`,
+    `  letter-spacing: 0.15em;`,
+    `  color: #666;`,
+    `  font-weight: 600;`,
+    `  margin: 0 0 0.5in;`,
+    `}`,
+    `.toc ol {`,
+    `  list-style: none;`,
+    `  padding: 0;`,
+    `  margin: 0;`,
+    `}`,
+    `.toc li {`,
+    `  display: flex;`,
+    `  align-items: baseline;`,
+    `  gap: 0.25in;`,
+    `  font-size: 11pt;`,
+    `  line-height: 2;`,
+    `  padding: 4pt 0;`,
+    `}`,
+    `.toc li .toc-title { flex: 0 0 auto; }`,
+    `.toc li .toc-dots { flex: 1 1 auto; border-bottom: 1px dotted #aaa; margin: 0 6pt; transform: translateY(-4pt); }`,
+    `.toc li .toc-page { flex: 0 0 auto; color: #666; font-variant-numeric: tabular-nums; }`,
+    `.toc li.level-2 { padding-left: 0.35in; font-size: 10pt; }`,
+    `.toc li a { color: inherit; text-decoration: none; }`,
+  ].join("\n");
+}
+
+function chapterRules(noChapterBreaks: boolean): string {
+  const breakRule = noChapterBreaks
+    ? `/* chapter breaks disabled */`
+    : [
+        `.chapter { break-before: page; page-break-before: always; }`,
+        `.chapter:first-of-type { break-before: auto; page-break-before: auto; }`,
+      ].join("\n");
+  return [
+    breakRule,
+    `h1 {`,
+    `  font-size: 22pt;`,
+    `  line-height: 1.2;`,
+    `  font-weight: 700;`,
+    `  letter-spacing: -0.01em;`,
+    `  margin: 0 0 0.25in;`,
+    `  break-after: avoid;`,
+    `  page-break-after: avoid;`,
+    `}`,
+    `h2 { font-size: 15pt; line-height: 1.3; font-weight: 700; margin: 24pt 0 6pt; break-after: avoid; page-break-after: avoid; }`,
+    `h3 { font-size: 12pt; line-height: 1.4; font-weight: 700; text-transform: uppercase; letter-spacing: 0.08em; color: #333; margin: 18pt 0 4pt; break-after: avoid; page-break-after: avoid; }`,
+    `h4 { font-size: 11pt; font-weight: 700; margin: 12pt 0 4pt; break-after: avoid; page-break-after: avoid; }`,
+  ].join("\n");
+}
+
+function blockRules(): string {
+  // Flush-left paragraphs, no indent, 12pt gap. No justify.
+  // Rule from the plan's "Body paragraph rule (post-review fix)".
+  return [
+    `p {`,
+    `  margin: 0 0 12pt;`,
+    `  text-align: left;`,
+    `  widows: 3;`,
+    `  orphans: 3;`,
+    `}`,
+    `p:first-child { margin-top: 0; }`,
+    `p.lead { font-size: 13pt; line-height: 1.45; color: #222; margin: 0 0 18pt; }`,
+  ].join("\n");
+}
+
+function inlineRules(): string {
+  return [
+    `a {`,
+    `  color: #0055cc;`,
+    `  text-decoration: underline;`,
+    `  text-decoration-thickness: 0.5pt;`,
+    `  text-underline-offset: 1.5pt;`,
+    `}`,
+    `strong { font-weight: 700; }`,
+    `em { font-style: italic; }`,
+  ].join("\n");
+}
+
+function codeRules(): string {
+  return [
+    `code {`,
+    `  font-family: "SF Mono", Menlo, Consolas, monospace;`,
+    `  font-size: 9.5pt;`,
+    `  background: #f4f4f4;`,
+    `  padding: 1pt 3pt;`,
+    `  border-radius: 2pt;`,
+    `  border: 0.5pt solid #e4e4e4;`,
+    `}`,
+    `pre {`,
+    `  font-family: "SF Mono", Menlo, Consolas, monospace;`,
+    `  font-size: 9pt;`,
+    `  line-height: 1.4;`,
+    `  background: #f7f7f5;`,
+    `  padding: 10pt 12pt;`,
+    `  border: 0.5pt solid #e0e0e0;`,
+    `  border-radius: 3pt;`,
+    `  margin: 12pt 0;`,
+    `  overflow: hidden;`,
+    `  white-space: pre-wrap;`,
+    `}`,
+    `pre code { background: none; border: 0; padding: 0; font-size: inherit; }`,
+    // highlight.js minimal palette (kept neutral, prints well)
+    `.hljs-keyword { color: #8b0000; font-weight: 500; }`,
+    `.hljs-string { color: #0d6608; }`,
+    `.hljs-comment { color: #888; font-style: italic; }`,
+    `.hljs-function, .hljs-title { color: #0044aa; }`,
+    `.hljs-number { color: #a64d00; }`,
+  ].join("\n");
+}
+
+function quoteRules(): string {
+  return [
+    `blockquote {`,
+    `  margin: 12pt 0;`,
+    `  padding: 0 0 0 18pt;`,
+    `  border-left: 2pt solid #111;`,
+    `  color: #333;`,
+    `  font-size: 11pt;`,
+    `  line-height: 1.5;`,
+    `}`,
+    `blockquote p { margin-bottom: 6pt; text-align: left; }`,
+    `blockquote cite { display: block; margin-top: 6pt; font-style: normal; font-size: 9.5pt; color: #666; letter-spacing: 0.02em; }`,
+    `blockquote cite::before { content: "— "; }`,
+  ].join("\n");
+}
+
+function figureRules(): string {
+  return [
+    `figure { margin: 12pt 0; }`,
+    `figure img { display: block; max-width: 100%; height: auto; }`,
+    `figcaption { font-size: 9pt; color: #666; margin-top: 6pt; font-style: italic; }`,
+  ].join("\n");
+}
+
+function tableRules(): string {
+  return [
+    `table { width: 100%; border-collapse: collapse; margin: 12pt 0; font-size: 10pt; }`,
+    `th, td { border-bottom: 0.5pt solid #ccc; padding: 5pt 8pt; text-align: left; vertical-align: top; }`,
+    `th { font-weight: 700; border-bottom: 1pt solid #111; background: transparent; }`,
+  ].join("\n");
+}
+
+function listRules(): string {
+  return [
+    `ul, ol { margin: 0 0 12pt 0; padding-left: 20pt; }`,
+    `li { margin-bottom: 3pt; line-height: 1.45; }`,
+    `li > ul, li > ol { margin-top: 3pt; margin-bottom: 0; }`,
+  ].join("\n");
+}
+
+function footnoteRules(): string {
+  return [
+    `.footnote-ref { font-size: 0.75em; vertical-align: super; line-height: 0; text-decoration: none; color: #0055cc; }`,
+    `.footnotes { margin-top: 24pt; padding-top: 12pt; border-top: 0.5pt solid #ccc; font-size: 9.5pt; line-height: 1.4; }`,
+    `.footnotes ol { padding-left: 18pt; }`,
+  ].join("\n");
+}
+
+function watermarkRules(): string {
+  return [
+    `.watermark {`,
+    `  position: fixed;`,
+    `  top: 50%;`,
+    `  left: 50%;`,
+    `  transform: translate(-50%, -50%) rotate(-30deg);`,
+    `  font-size: 140pt;`,
+    `  font-weight: 700;`,
+    `  color: rgba(200, 0, 0, 0.06);`,
+    `  letter-spacing: 0.08em;`,
+    `  pointer-events: none;`,
+    `  z-index: 9999;`,
+    `  user-select: none;`,
+    `  white-space: nowrap;`,
+    `}`,
+  ].join("\n");
+}
+
+function breakAvoidRules(): string {
+  return `blockquote, pre, code, table, figure, li, .keep-together { break-inside: avoid; page-break-inside: avoid; }`;
+}
+
+function escapeCssString(s: string): string {
+  return s.replace(/\\/g, "\\\\").replace(/"/g, "\\\"");
+}