paper2poster

paper2poster — paper_spec.md → HTML poster → PDF/PNG + editable PPTX

This skill is the rendering stage of a 3-skill pipeline. It assumes paper2assets has already produced the input <outdir>/. Given that outdir, it picks figures, renders an HTML poster, iteratively fills the layout to fit a fixed page (60×36in landscape or 33.1×46.8in A0 portrait), generates per-section narration audio, hands the HTML to the bundled html2pptx sub-skill (vendored at html2pptx/) for an editable .pptx, and exports PDF + PNG. The html2pptx handoff is a standard final step, not optional — one run yields poster.{html,pptx,pdf,png}, because users want the editable deck in the same pass and won't call html2pptx separately.

   <outdir>/                              (produced by paper2assets)
     manifest.json   assets/figures/   assets/logos/   assets/qr/   assets/meta/{paper_spec.md, text.txt, figures.json, metadata.json}
     │
     ▼  Step 1 — verify prerequisites
     ▼  Step 2: select figures from upstream semantics
     │         → assets/meta/figure_selection.json
     │           (Method / high-confidence optional Motivation / Result)
     ▼  Step 2.5 — optional per-figure visual box cut (asymmetric noise the
     │             paper2assets deterministic chain couldn't catch — most
     │             figures need no further work here)
     │
     ▼  Step 3 — compose (layout × style × header) + substitute  (references/compose_poster.py → poster.html)
     │         → <outdir>/poster.html (lean: 6 core sections, Necessary only)
     │
     ▼  Step 4 — iterative fill loop (check_poster.py slack + polish)
     │         → <outdir>/poster.html (every section FULL, every figure ≥90% on one axis)
     │
     ▼  Step 5 — generate_audio.py → <outdir>/assets/audio/<id>.mp3   (free Edge TTS, from <outdir>/assets/meta/narration.json)
     │         → the Listen buttons + Full Listen play these clips by id
     │
     ▼  Step 5.9 — fit_logos.py → pack the header institution logos to fill their zone
     │             (browser-measure + greedy shape-pack; baked into poster.html)
     │
     ▼  Step 6 — render_poster.py → <outdir>/poster.pdf + <outdir>/poster.png   (applies + bakes the expand into poster.html)
     │
     ▼  Step 7 — html2pptx skill → <outdir>/poster.pptx   (reads the baked poster.html; users want the editable pptx in one run)
     │         (render FIRST — bakes the expand into poster.html; html2pptx then reads it, isolated under assets/_pptx_build/)
     │         then check_poster.py verify-final
     │
     ▼  Step 7.5 — check_poster.py deliverables (MANDATORY final gate)
     │
     └─→  Step 8 — Report absolute paths (html + pptx + pdf + png)

The canvas is fixed per orientation (landscape 60×36in 5:3 / portrait A0 33.1×46.8in 0.708) in the templates; do not change it.

Mandatory finishing gates (NEVER ship outside these bands)

Two hard requirements gate the final poster. They are NOT warnings, NOT advisory, NOT "polish for next iteration" — a poster that violates either MUST be re-iterated before you call the task done:

1. Every card figure fills 90–100% of its section on at least one axis (width OR height). check_poster.py polish reports this as FIG/NARROW. A figure painting under 90% on both axes is a small stamp marooned in its card — a visible defect. Stated as one number: fillRatio = max(w_fig / w_section, h_fig / h_section) MUST land in [0.90, 1.00]. The fix order (cap tune → tighten the figure-section's prose → shorten the figcaption → rebalance the column) is in references/staged_fill.md. Do not exit the staged-fill loop with any figure below 90%.

2. Every section reads FULL (fullRatio 0.90–1.00). check_poster.py slack reports this. OVERFLOW (>1.10), SPILLAGE (1.00–1.10), SPARSE (0.70–0.90), and EMPTY (<0.70) are all unacceptable finishing states.

Both gates compose: an edit that fixes one but breaks the other must be rolled back. Loop until slack shows every section FULL AND polish reports zero FIG/NARROW warnings — then render PDF/PNG and run verify-final + deliverables.

When to consult which reference

Workflow

Parallel-safety (READ FIRST — never violate)

This skill is frequently run on MANY papers at once — a batch driver launches one claude -p session per paper, each with its own separate <outdir> (e.g. papers/foo_portrait/, papers/bar_portrait/, … running concurrently). Therefore:

• NEVER run ps, pkill, kill, killall, or otherwise inspect or terminate other processes. Any other claude / python / chromium / soffice processes you see belong to SIBLING poster jobs on DIFFERENT papers. They are NOT duplicates of you and NOT competing for your files. Killing them corrupts other papers' runs.
• Only ever read/write files inside YOUR given <outdir>. Never touch another paper's directory or the shared template/config dirs.
• If <outdir>/poster.html appears to have "changed unexpectedly" between a Read and an Edit, it changed because of YOUR OWN prior tool call (a Write, a substitution script you ran, a prior Edit) — NOT a competing process. Re-Read the file and continue. Do not investigate "who else is modifying it" — nobody else is.
• The shared template at <config>/skills/paper2poster/assets/*.html is READ-ONLY input — copy it into your <outdir>, never edit it in place.

Violating any of the above is the single most common cause of a fast-fail (~400s) where the agent rabbit-holes on phantom "process conflicts" instead of building the poster.

Step 0 — Cache check (do this FIRST, before any other work)

Rendering a poster runs Stage 2's iterative staged-fill loop (~15-30 min of Claude tokens) and overwrites <outdir>/poster.html — destroying any inline edits, manual figure swaps, or layout tweaks the user may have made. Before starting, check whether the deliverables already exist:

if [[ -f "$outdir/poster.html" \
      && -f "$outdir/poster.pdf" \
      && -f "$outdir/poster.png" ]]; then
  if python ~/.claude/skills/paper2poster/scripts/select_figures.py "$outdir" \
      && python ~/.claude/skills/paper2poster/scripts/check_poster.py \
          preflight "$outdir/poster.html"; then
    echo "[paper2poster] CACHED in $outdir: semantic preflight passed, reusing."
    echo "  poster.html  $(stat -c%s "$outdir/poster.html") bytes"
    echo "  poster.pdf   $(stat -c%s "$outdir/poster.pdf") bytes"
    echo "  poster.png   $(stat -c%s "$outdir/poster.png") bytes"
    [[ -f "$outdir/poster.pptx" ]] && echo "  poster.pptx  (html2pptx output present)"
    [[ -d "$outdir/assets/audio" ]] && echo "  assets/audio/       (narration present)"
    exit 0
  fi
  echo "[paper2poster] cached deliverables are semantically stale; upgrading " \
       "Paper2Assets and rebuilding instead of reusing them."
fi

If all three core deliverables are present, REPORT and STOP only when the selector and semantic preflight both pass. A legacy, partial, mixed-generation, or wrongly attributed cached poster must continue through Step 1, upgrade its Paper2Assets package, and be rendered again. Cached PDF/PNG existence alone is never proof that the Motivation image is correct.

Re-render ONLY when:

• the user changes the header template, including switching to/from an explicit no-institution header → recompose and re-export instead of reusing the cache
• one of poster.{html,pdf,png} is missing → resume from the appropriate step (poster.html missing → start from Step 2 fill loop; only poster.pdf / poster.png missing → just run Step 6 render)
• the user explicitly requests it ("rebuild the poster", "regenerate", "fresh render", "from scratch", "redo the layout"). In that case, delete <outdir>/poster.html first so the cache check doesn't fire.

Step 1 — Verify paper2assets prerequisites

No institution names/logos requested? Select the explicit unbranded header first: Landscape v6 (centered) / v7 (left), Portrait pv6 (centered) / pv7 (left). Read references/branding_free_headers.md. For these templates, skip the logo recovery below, preserve any shared logo assets, and still recover QR assets if needed. Their structure deliberately has no affiliation/logo slots; do not add them during substitution or fitting. This exception also applies to all later logo-fetching and affiliation instructions. The regular cache shortcut does not apply when the requested header differs from the cached poster.

Required argument: an <outdir>/ path produced by the paper2assets skill, or a path to a source *.pdf. Verify the required files exist before doing any work:

ls <outdir>/assets/meta/paper_spec.md <outdir>/assets/meta/text.txt <outdir>/assets/meta/figures.json <outdir>/assets/meta/metadata.json

If any of the four required files is missing, automatically invoke the paper2assets skill on the source PDF to produce/populate the <outdir>/, then continue. figures.json may legitimately be an empty list; the selector and preflight validate every non-empty record and its on-disk asset.

Optional files <outdir>/assets/logos/ and <outdir>/assets/qr/ may be absent — but DO NOT silently delete the logo/QR HTML blocks just because the directory is missing. Two common reasons the directory is missing are recoverable:

1. paper2assets's Step 6 was skipped, or
2. paper2assets's Step 6 was called with the wrong CLI flags (the --spec / --outdir <outdir>/assets/logos traps documented in paper2assets SKILL.md Step 6 caused most papers to land logos at <outdir>/assets/logos/logos/<slug>.png instead of <outdir>/assets/logos/<slug>.png).

Recovery procedure when <outdir>/assets/logos/ is missing or empty:

# A. Auto-fix the nested-dir bug if present
if [ -d <outdir>/assets/logos/logos ]; then
  mv <outdir>/assets/logos/logos/* <outdir>/assets/logos/ 2>/dev/null
  rmdir <outdir>/assets/logos/logos
fi

# B. Retry fetch_logos.py from this skill (it's a paper2assets script
#    but safe to call from paper2poster as a recovery step).
python ~/.claude/skills/paper2assets/scripts/fetch_logos.py \
    --from-spec <outdir>/assets/meta/paper_spec.md --outdir <outdir>

# C. Same for qr/ if missing
python ~/.claude/skills/paper2assets/scripts/make_qr.py \
    --from-metadata <outdir>/assets/meta/metadata.json --outdir <outdir>

Only AFTER the retry, if logos/ is still empty (institute names didn't resolve to any Wikipedia infobox — happens for "Anonymous Institution" submissions and obscure labs), then remove the unused <img class="logo"> elements from the poster HTML as a final fallback. Same for missing QR codes.

Step 2 — Pick figures

Run the deterministic semantic selector before composing or substituting the poster:

python scripts/select_figures.py <outdir>

It writes <outdir>/assets/meta/figure_selection.json. Treat that manifest as the single source of truth for the primary figure placeholders:

• selections.method.file -> {{METHOD_FIGURE}}
• selections.motivation.file -> {{TEASER_FIGURE}} when non-null
• selections.result.file -> {{SECONDARY_FIGURE}} or the primary figure in the Key Result section

Each non-null entry also carries the stable figure_id, caption, semantic confidence, and evidence. Do not replace a selected file with a different image based on visual guesswork. check_poster.py preflight independently recomputes the deterministic selection and hard-fails a stale manifest, a role mismatch, or Method/Motivation reuse.

The selector consumes the additive Paper2Assets semantic fields semantic_roles[] and section_relevance[]. Selection is deterministic and disjoint:

• Method figure requires method >= 0.55 and rejects empirically dominant or near-tied Result/Ablation/Qualitative galleries. This prevents captions that happen to say "our method" from displacing the actual system overview.
• Motivation figure is optional and high-confidence only. It requires motivation >= 0.62, rejects every candidate carrying method, result, or ablation >= 0.55, and is always disjoint from Method. If it is null, remove the entire Motivation <figure> block. Never fill that space with a Method or Result image.
• Result figure requires result or qualitative >= 0.55, rejects clearly Method-dominant diagrams, and is disjoint from Method and Motivation. Target >=2 figures per poster only when an eligible empirical figure exists. Do not pad a poster with a semantically unrelated image to reach the target.
• Figure-rich mode → 3-column layout. If the paper carries more than 3 high-signal figures (multiple result plots, a qualitative-samples gallery, architecture + component diagrams), select them all (soft cap ~6) instead of stopping at 2 — and render with the 3-column layout (--layout 3col, Step 3) whose wider columns hold bigger figures, the way most author-GT posters do. Distribute the figures across all three columns; the Method figure stays the anchor. Pick only genuinely informative figures — never pad to hit a count.

Legacy bundles must be upgraded. When figures.json has no complete figure_semantics.v2 producer contract, including partial/prototype semantic fields, the selector exits non-zero and preflight fails. Reuse the existing assets and run Paper2Assets build_package.py --skip-extract --paper-spec ..., then rerun the selector. Manual/raw-model figure selection is not an allowed fallback because it recreates the Motivation mismatch this gate prevents.

Cite each selected figure with its file path and verify it exists before relying on it.

Step 2.5 — Per-figure visual box cut (optional, for asymmetric noise the deterministic chain couldn't catch)

paper2assets already ran the deterministic cleanup pipeline (top-check → decaption → autotrim) on every figure. Most picked figures need no further work.

If a picked figure has asymmetric noise the deterministic chain couldn't catch — multi-figure-page bleed on a SIDE (a vertical strip of an adjacent panel), an obvious orphan caption line a tight decaption threshold missed, or a region of figure content you want excluded — do one visual box pass:

1. Read the figure with the Read tool.
2. Decide a tight pixel bbox (X0, Y0, X1, Y1).
3. Apply:

   python ~/.claude/skills/paper2assets/scripts/crop_figure.py box <outdir>/assets/figures/<file>.png --box X0 Y0 X1 Y1
   

   This writes a one-time <file>.png.bak (or preserves the existing one from paper2assets' earlier work) and updates figures.json.
4. Re-Read the result. Cap at 3 attempts per figure; restore from .bak with cp if you over-cut.

For most papers this step is a no-op — skip when the picked figures look clean after paper2assets' deterministic pipeline.

Step 3 — Render the HTML poster

Choose the orientation-aware composition axes, then COMPOSE.

Both orientations share four independent axes under assets/: layout × style × header × theme. Landscape adds a fifth, Scan-to-Read, while Portrait deliberately has no standalone scan axis:

• Structure: landscape assets/layouts/{full,half,3col}.html; portrait assets/layouts_portrait/{full,half}.html.
• Visual style: assets/styles/*.css; Landscape enables all 11 treatments, while Portrait excludes underline and double-rule and enables the remaining 9.
• Titlebar: landscape assets/headers/{v1,v2,v3,v4,v5,v6,v7}.html; portrait assets/headers_portrait/{pv1,pv2,pv3,pv4,pv5,pv6,pv7}.html. The *6 / *7 variants are opt-in, without institution names/logos.
• Color/theme: 9 bundles from references/apply_theme.py, shared by both orientations.
• Scan-to-Read: landscape only, from assets/scan/*.html.

references/compose_poster.py injects the chosen style at {{STYLE_CSS}}, the chosen header at {{HEADER}}, the landscape-only scan block at {{SCAN_SECTION}}, and the resolved theme into the chosen layout. It writes ONE self-contained poster.html, so check_poster.py / render_poster.py / the staged-fill loop work unchanged without an N×M×K×J explosion of monolithic templates.

Portrait is now composed (--orientation portrait, assets/layouts_portrait/{full,half}.html) with the STYLE + COLOR + HEADER axes: 9 eligible styles, 9 themes including mono, and 5 A0 title formats pv1–pv5 on the light-default header. underline and double-rule are Landscape-only because their horizontal rules create misleading section divisions in narrow Portrait columns. Portrait has no standalone Scan-to-Read section or --scan axis, but it does have a composed header and its header-owned QR slots. Portrait sections must use the content-pattern widgets (references/content_patterns.md) with the same ≥5-distinct-semantic-families discipline as landscape. The narrow A0 columns make it easier to collapse to plain bullets/tables, so Portrait needs the widget palette more.

Axis 0 — orientation:

1. landscape (default) — ICML / NeurIPS / CVPR standard 60×36 in, 5:3 aspect. 4-column outer grid. Always use landscape unless the user has explicitly opted into portrait.
2. portrait — ACL / NAACL / AAAI 2025 standard A0 portrait, 33.1×46.8 in, 0.708 aspect. The half layout uses a 2-column body; the full layout uses four stacked content bands. Use ONLY when the pipeline sets POSTER_ORIENTATION=portrait. Do NOT auto-detect orientation from the Method figure aspect ratio — figure shape drives the layout axis (full vs half) WITHIN an orientation, not the orientation itself. A tall Method figure in landscape goes in a half template's single column; it does not flip the whole poster to portrait.

If POSTER_ORIENTATION is unset (or set to landscape), use landscape templates. Period.

Axis 1 — layout (driven by Method figure shape):

1. full (landscape --layout full; portrait layouts_portrait/full.html) — use when the Method figure is horizontally wide: in landscape AR ≥ 2.5, in portrait AR ≥ 1.2. Also use when {column=full} in figures.json. In landscape, this picks a 4-col outer grid with the middle two columns merged into a .mid-wide block. In portrait, this picks four stacked content bands: Problem | Motivation; the full-width .method-hero; Key Results | Ablation | Headline Numbers at 1.5fr 1fr 1fr; and a full-width Takeaway.

   Portrait pseudo-section for bullets fill: the hero band's LEFT bullets cell is wrapped in <div class="section method-text" data-section="method-text">…</div> — a visually-transparent pseudo-section that participates in the staged-fill loop. slack.py measures its fill ratio as bullets_content_h / row_h. When the figure stretches the row taller than the bullets need, the verdict surfaces method-text SPARSE and the LLM expands bullets until the cell fills. This is why the AR threshold can stay loose at 1.2 instead of the safer 1.8 — the pseudo-section absorbs medium-aspect-figure whitespace automatically.

2. half (landscape --layout half; portrait layouts_portrait/half.html) — default within the orientation. Use when Method figure AR is moderate or tall AND {column=half} in figures.json, OR when Method figure is **Figure:** none. In landscape, Method is a half-width card in 1 of 4 cols. In portrait, Method is a card in 1 of 2 cols.

Read the Method figure's width and height from figures.json, compute AR = width / height, then:

• Landscape: full if AR ≥ 2.5 OR {column=full}, else half.
• Portrait: full if AR ≥ 1.2 OR {column=full}, else half. (The hero band's bullets cell is a pseudo-section that auto-fills via the staged-fill loop; medium-aspect figures are safe.)

Figure-rich override (landscape — takes precedence over full/half). If Step 2 selected more than 3 figures, use the 3-column layout (--layout 3col) regardless of the Method figure's AR — its 3 wide equal columns (1fr 1fr 1fr) hold bigger, more numerous figures, matching the dominant author-GT layout. The Method figure card stays prominent in the middle column; the other figures distribute across columns. Via composition, 3col now combines with any style and any header (the old "solid-only" limit is gone). The full/half choice above applies only when the poster carries ≤ 3 figures.

Method-driven override (OPT-IN — only when the user explicitly asks for a "method-driven" poster). Use --layout methoddriven. The Method owns the wide middle block (.mid-wide, the merged centre columns): a large priority Method figure on top, then the method split into solid rounded subsection cards (.section.msub, data-section="method-1"…"method-N") that organize its sub-parts; the benchmark-style filler cards are dropped (side columns carry Problem/Motivation left, Key-Results/Headline/Takeaway right). This is opt-in — --layout random never selects it, and every other layout/style is unchanged. Rules:

• Subsection headings in both methoddriven and methoddriven4 use outlined square A, B, C, D… badges (.msub-h .n). Keep numeric steps inside cards separate; do not turn heading badges back into filled numbered circles. When adding/reordering cards, continue the letters in reading order while preserving data-section="method-1"…"method-N" for measurement and Reel interactions.
• Colour = multi-accent by default: same hue as the theme --accent, different depth per card (.msub.d1…d4, theme-derived — tracks the 9-theme axis). Opt into distinct hues by adding class mhue to <body>.
• The Method figure is the priority — it fills the column WIDTH (so a wide banner clears the 90% figure-fill gate on width; NO exemption needed) and is bounded only by a generous, fill-loop-tunable height guard --method-fig-max (default 42cqh). Raise/lower --method-fig-max to trade figure size against card room. The <figcaption> flows below.
• The subsection cards adapt to the figure — the fill loop chooses the arrangement per-paper (no fixed 2×2). .msubs is a span-composable grid; tag individual cards + order them to compose the layout:
  • .msub.wide → full-width long row (first card = top row, last card = bottom row)
  • .msub.tall → tall card spanning 2 rows (the two normal cards flow the other column)
  • add cols-3 to .msubs → a 3-up equal-column row
  • Examples: tall+2 (one .tall + two normal); row-top/bottom+2 (a leading/trailing .wide + two normal); 2×2 (four normal); 3-up (.cols-3 + three normal). Add/remove cards freely.
• Fit the cards into the room the figure left. Run the pack pre-check; measure every .msub with slack (each must read FULL 0.90–1.00). If cards are SPARSE/OVERFLOW or unbalanced, re-pick the arrangement (add/remove a .wide/.tall, change card count, switch to .cols-3) or nudge --method-fig-max, rather than only padding prose. In any multi-card row, balance the cards' content or the shorter one trails blank (polish Gate C / CARD-TRAILING).

Axis 2 — style (POSTER_STYLE, default randomize):

The first three are full themes (they retheme the header + page background); styles 4–11 are block-only card treatments that ride the solid theme (accent header, flat white logo chips) and just change the section-card look.

1. solid — the classic look: solid-filled accent titlebar (accent bg, white text), section h2 = colored accent text with a thin underline. Sections are quiet warm cards with a top accent stripe.
2. framed — the editorial look: outlined rounded titlebar frame (white bg, accent border + accent title), section h2 = solid accent-filled banner edge-to-edge; white section cards with a neutral thin frame.
3. simple — the minimal white look: white header + a single thin rule beneath it, near-black plain headings, frameless section cards separated only by a hairline top rule.
4. left-bar — thick accent rail down the card's left edge; plain accent heading.
5. elevated — floating white card with a soft deep shadow, rounded corners.
6. neo-brutal — hard black border + offset accent drop-shadow; uppercase headings.
7. tag — heading rendered as an inline accent pill.
8. underline — bold accent rule hugging the heading.
9. tinted — faint accent-tinted card background.
10. double-rule — centered heading between two thin accent lines.
11. legend-frame — heavy accent border with the centered heading sitting on the top edge, breaking the border (fieldset/legend look).

Default style policy: --style defaults to random, so compose_poster.py picks deterministically from the orientation's eligible catalog. Landscape randomizes across all 11 styles. Portrait randomizes across 9 and rejects explicit underline or double-rule requests. Override an eligible style via POSTER_STYLE=<name> or --style <name>. Do NOT ask the model to "pick a random style"; use the composer's random mode. The block-only styles ride the solid header theme. Portrait also composes 9 themes and 5 A0 title formats (pv1–pv5, assets/headers_portrait/), all on the light-default header. The Portrait formats now differ structurally: pv1 balanced Venue+QR | centered title | institutions; pv2 full-width centered masthead over a Venue+QR | institutions navigation strip; pv3 left-top-aligned title | institutions | Venue+QR, keeping institutional identity beside the paper information; pv4 is pv1's centered mirror, institutions | centered title | Venue+QR; pv5 mirrors pv3 as Venue+QR | institutions | right-top-aligned title. In pv2/pv3/pv5, one vertical rule separates the utility menu from institution marks while the two regions remain independently measurable by fit_logos.py.

Axis 5 — color/theme (POSTER_THEME, default random): 9 academic accent bundles (blue · teal · green · burgundy · purple · rust · slate · plum · mono) — the palette the paper's gallery recolor used. Each swaps {--accent, --accent-soft} (and the audio --play-highlight-blue); the result-register --callout (crimson) stays fixed across all themes. With the light-default header (--tb-bg: var(--accent-soft), dark title) each theme paints a pale-tint header + colored <h2> text/underlines on white cards — the light look, not a dark filled band. --theme random samples one theme deterministically from the seed, replacing the old "model hand-edits :root" step. Defined once in references/apply_theme.py (THEMES); shared by landscape and portrait (both via compose_poster.py).

Axis 3 — header (POSTER_HEADER, default randomize):

Explicit no-institution templates: v6 / v7 (Landscape), pv6 / pv7 (Portrait) omit both institution names and all header logos by construction. Choose centered (*6) or left-aligned (*7); both retain author names, venue text and the orientation's normal QR behavior. Fill {{AUTHORS_PLAIN}} rather than the affiliation-marked {{AUTHORS}}. They are excluded from random pools. See references/branding_free_headers.md for the complete contract.

1. v1 — venue (left) · title (center) · institution logos (right). Symmetric 3-zone band.
2. v2 — mirror of v1: institution logos (left) · title (center) · venue (right).
3. v3 — title centered full-width with a single equal-height logo strip below (conference mark + institutions).
4. v4 — title (left) · venue + institution logos stacked (right). A common GT layout.
5. v5 — classic: venue text badge (left) · title (center) · institution logos + Paper/Code QR tiles (right). The one header that carries the QR in the titlebar. Opt-in only (POSTER_HEADER=v5) — when chosen, suppress the standalone scan-to-read section (set both {{QR_*}} empty) so the QR is not duplicated.

v1–v4 each render the conference logo when assets/logos/_venue.png exists (Step 6 fetch_conf_logo.py), else a text venue/year fallback in the same chip; v5 uses a text venue badge by design. All work for 2–6 institutions (empty LOGO_n slots auto-hide). Logos are sized to fill their zone (single venue logo + a 2-row institution grid), and the logo chips theme to the chosen style via --tb-chip-bg / --tb-chip-shadow: solid → flat white chip (no shadow) on the accent band; framed → flat white chip on the white card; simple → transparent chip (no frame), logos sit directly on the white header. Default: pass --header random — compose_poster.py picks one DETERMINISTICALLY from the configured seed from all five (v1–v5); v5 fills its own titlebar QR via {{HDR_QR_*}} (see the QR contract). Override via POSTER_HEADER={v1|v2|v3|v4|v5}.

Default font policy: the poster body defaults to Arial, and --font-latin may select any of the 8 Mac/Windows PowerPoint-safe family names: Calibri | Aptos | Cambria | Arial | "Times New Roman" | Verdana | Georgia | "Trebuchet MS". These proprietary OS fonts are not reliably installed on the Linux renderer or every HTML client. Before browser geometry is measured, check_poster.py / render_poster.py freeze browser rendering to a compact, self-contained open-licensed subset under assets/fonts/, while html2pptx continues emitting the requested native family into .pptx. Arial uses bundled Arimo Regular/Bold because Arimo is metrically compatible with Arial; the other selections preserve an open DejaVu or Noto face from the renderer's actual fallback category. A fresh Arial poster, an old Arial/DejaVu fidelity block, or a local-first Arimo block is migrated to packaged-first Arimo through a directional media gate: media identity must stay fixed, every research figure must satisfy the absolute 90% minimum after migration, and no axis may newly exceed 101%. After that one repair, the Arimo layout becomes the strict source baseline for durable HTML, PDF, PNG, and Reel checks. The optional POSTER_FONT env var carries the same choice, but the default lives in the templates. To use Inter, flip --font-latin back to Inter, … and run the html2pptx Inter embed step so the .pptx ships the font; the 4 Inter @font-face blocks stay defined in every template for exactly this override.

Composition catalog (landscape and portrait):

compose_poster.py validates each choice and, on a bad name, aborts listing the available options. The old monolithic poster_*_{solid,framed}.html / poster_portrait_*.html templates have been retired — compose_poster.py (layout × style × header × scan × color, --orientation portrait for A0) is the only path; the source now lives entirely in assets/{layouts,layouts_portrait,styles,headers,headers_portrait,scan}/.

Generate poster.html WITHOUT ever emitting its full contents through your output channel — hard requirement. The template is ~100 KB (≈ 30–40k tokens); writing it inline with the Write tool overflows the per-turn output-token cap (CLAUDE_CODE_MAX_OUTPUT_TOKENS, default 32000) and kills the run — and the measured-fill loop would re-pay that cost every round. Generate it indirectly so the bulk template never passes through your output:

1. Compose the template (disk-to-disk, zero output tokens — do NOT Write it):

   # landscape — assemble layout × style × header into ONE self-contained poster.html
   python references/compose_poster.py \
     --layout <full|half|3col> --style random --header random \
     --scan <single|dual> --theme random \
     --out <outdir>/poster.html
   # portrait — composed too (STYLE + COLOR + HEADER axes; 5 A0 title formats pv1-pv5,
   # no scan section): reads assets/layouts_portrait/ + assets/headers_portrait/
   python references/compose_poster.py --orientation portrait \
     --layout <full|half> --style random --header random --theme random \
     --out <outdir>/poster.html
   

   compose_poster.py resolves the STRUCTURAL hooks ({{STYLE_CSS}}, {{HEADER}}, and landscape-only {{SCAN_SECTION}}) AND the COLOR axis (rewrites the :root accent vars to the resolved theme); every CONTENT {{...}} placeholder survives for the next step. --scan: pass the GROUP keyword dual only when make_qr.py emitted TWO QR slots (two genuinely distinct URLs survived de-duplication), else single — compose deterministically picks a fitting variant within the group (so a 2-QR layout never lands on a 1-link paper, whose paper/project/code URLs collapse to one QR); --scan random or an explicit variant name also work. Portrait ignores this axis because it has no standalone scan section, while its pv1–pv5 header still composes normally. QR-count guard (belt-and-suspenders): if you pass a single-QR context (single, or an explicit hero/contact/banner) but metadata.json actually carries two QR files on disk, compose_poster.py auto-upgrades to the dual group so the second (project/code) QR is never silently dropped — still pass dual explicitly when a code QR resolved. --theme: default random picks one of 9 academic themes DETERMINISTICALLY from the seed — do NOT hand-edit :root colors; override a specific one with --theme <name> or POSTER_THEME. --header: default random (landscape v1-v5 / portrait pv1-pv5). --math: the math-typesetting engine, default katex (thinner glyphs, posterskill-like) — the ONE place to switch is MATH_ENGINE_DEFAULT in compose_poster.py, or per-run --math mathjax / POSTER_MATH=mathjax. Both engines are bundled offline (assets/katex/, assets/mathjax/) and intercepted by the renderer + html2pptx (whose math pass is engine-agnostic), so flipping it needs no template/pptx change. Injected at the {{MATH_HEAD}} hook in every layout (landscape + portrait).

   Deterministic selection and 30+ paper batches. For an ordinary run, the random axes use --seed when supplied, then POSTER_SEED, otherwise the resolved absolute --out path. Resolving the path is important: separate paper outdirs no longer collapse to the same seed merely because each command says --out poster.html. For a large batch, pass consecutive zero-based --variant-index values and one shared --variant-seed; the sampler deterministically orders the joint random-axis combination space without replacement while keeping each axis marginally balanced. Landscape covers all 11 styles in 11 posters; Portrait covers its 9 eligible styles in 9 posters; 5 posters cover all 5 portrait headers; and 9 cover all 9 themes. Keep layout driven by the Method figure, or pass --layout random only when layout itself should join the balanced sampling:

   python references/compose_poster.py --orientation portrait \
     --layout full --style random --header random --theme random \
     --variant-index 17 --variant-seed portrait-wave-20260810 \
     --selection-out <outdir>/selection.json \
     --out <outdir>/poster.html
   

   Every composed HTML also embeds the resolved composition as JSON in <script id="paper2poster-composition" type="application/json"> and stamps the main axes as <body data-poster-...> attributes. --selection-out writes the same auditable selection to a separate JSON file for gallery and sampling tests.

2. Substitute placeholders with the Edit tool, one {{...}} token (or one section block) at a time — each Edit emits only the small placeholder plus your paper-specific content, never the surrounding template. Never reconstruct and Write the whole file.

Equivalent Opus-style alternative when you have many substitutions: copy the ready skeleton at references/build_poster.py (it carries the real placeholder names, a depth-aware optional-section drop for the lean render, and a leftover-{{...}} check), fill its SUBS dict with this paper's content, and run it on the composed poster.html — the template is read from disk at runtime and never enters your output. Either path is fine; the invariant is identical: the full HTML must never appear in a tool call's output (this is the single most common cause of a smaller model aborting on a large poster).

Read references/template_substitution.md now — it carries the full placeholder map, the code-driven theme color (1-of-9, applied by compose / apply_theme.py — do NOT hand-edit :root), per-section accent palette, vertical-sizing convention (in Portrait Half, exactly one grow on the bottom-most section of each column), and the lean initial render policy: only Necessary of the six core sections; all three optional sections (Contribution, Dataset / Benchmark, Ablation Study) and every Additional paragraph are deliberately withheld at this stage.

Decoupled-header + QR placeholder contract. Landscape v6/v7 follow the same body-scan rules as v1–v4. Portrait pv1–pv5 expose {{LOGO_1}}…{{LOGO_4}} plus header QR placeholders; pv6/pv7 expose only the QR placeholders, with no logo or affiliation slots. All Portrait headers omit the standalone Scan-to-Read section and scan axis. Fill portrait QR slots only when the referenced QR file exists. The composed headers replace the old titlebar, so the placeholder set changed:

• Venue: landscape v1–v4 use {{VENUE_NAME}} + {{VENUE_YEAR}} and an optional {{VENUE_LOGO}}. Set VENUE_LOGO to assets/logos/_venue.png only if that file exists, else ""; when empty, the header paints the venue/year text in the conference chip. The legacy {{VENUE}} token is retired. Landscape v5 and Portrait pv1–pv5 intentionally keep {{VENUE_LINK}} and {{VENUE_TAG}} for their compact text badge.
• Institution logos (branded headers only): landscape exposes {{LOGO_1}}…{{LOGO_6}}; portrait exposes {{LOGO_1}}…{{LOGO_4}}. Fill each present institution's path; set every unused slot to "" (empty/unfilled chips auto-hide).
• QR placement depends ONLY on the header — the QR appears in exactly ONE place, and NEVER in the Title Section except for v5:
  • Headers v1 / v2 / v3 / v4 / v6 / v7 → the Title Section carries NO QR (these headers have no QR slot at all). ALWAYS fill the standalone Scan to Read .section (data-section="scan-to-read", right after Takeaway) via {{QR_PAPER}} / {{QR_CODE}}, and set the header's {{HDR_QR_PAPER}} / {{HDR_QR_CODE}} to "". Institution count is irrelevant — the old "≤ 2 institutions → header QR" rule is RETIRED; the QR never joins the logo row. The section's internal layout is the --scan axis (Step 3): pass --scan dual when a code QR resolves, else --scan single, so a two-QR layout never lands on a one-QR paper. Beyond {{QR_PAPER}}/{{QR_CODE}}, the picked variant may also expose the display-URL placeholders {{URL_PAPER}} / {{URL_CODE}} / {{URL_PROJECT}} (short URL text from metadata.json, e.g. arxiv.org/abs/2106.09711) and {{CONTACT}} — fill whatever exists and leave the rest ""; every one auto-hides when empty. Exception — --layout 3col: the standalone Scan-to-Read section is suppressed in the 3col layout (its 1/3-width column is too wide for the section's small content and reads as empty), so a 3col poster intentionally carries NO QR. When you compose with --layout 3col, leave {{QR_PAPER}} / {{QR_CODE}} (and the other scan content placeholders) empty — they would render into a hidden section anyway.
  • Header v5 (classic) is the ONLY header with a titlebar QR — with v5, ALWAYS fill {{HDR_QR_PAPER}} / {{HDR_QR_CODE}} and leave the section {{QR_*}} empty, so the QR shows once (in the v5 header) and the scan-to-read section auto-hides.
  • Render-time guarantee (CSS — belt-and-suspenders, you do NOT rely on the build filling the right one): every layout hides .section[data-section="scan-to-read"] whenever the titlebar carries a FILLED QR (body:has(.titlebar img.qr-img[filled]) , body:has(.titlebar .qr-tile .chip.qr img[filled]) -> [data-section="scan-to-read"]{display:none}). So even if BOTH the header QR and the section QR get filled, the standalone Scan-to-Read section is suppressed at render time and the QR can never appear twice.
  • Every QR placeholder auto-hides when empty or when its assets/qr/*.png is absent — set a path only if the file exists.
• Logo autotrim: fetch_logos.py / fetch_conf_logo.py now rasterize (SVG→PNG) and crop the transparent/near-white border so chips hug the mark — automatic, best-effort, no action needed here.

After substitution, apply the visual polish layer — read references/visual_polish.md for typography, color, the inline-emphasis vocabulary (<strong> / .hi / .num), stat grid, figure cap, callout and arch components, and print hygiene (the canvas locks per orientation: landscape 60×36in / cqw / aspect-ratio: 5 / 3; portrait 33.1×46.8in / cqw / aspect-ratio: 33.1 / 46.8 — never edit).

Read references/content_patterns.md now and BREAK UP THE WALL-OF-TEXT. This is not optional reference material — it is a hard requirement for visual quality. The catalog contains 12 semantic widget families: callout-primary, callout-soft, callout-bar, key-stat, stat-strip, vs-compare, numbered-steps, chips, highlight-table, equation, timeline, and banner. The four timeline renderings count as one family. These patterns exist because plain <p> + <ul> across eligible sections makes the poster read as undifferentiated text. Rules:

• Every eligible section body MUST contain at least ONE pattern widget. Gate H exempts only structural title/titlebar cards, scan cards, the Portrait Full method-text pseudo-section, Headline Numbers cards that already contain .headline-hero, and genuinely figure-only cards. Plain <p> + <ul> alone in any other visible card is a failure.
• Across the full poster, use at least 5 DISTINCT semantic families. A poster that uses .p-callout-soft 9 times still reads as monotonous. Timeline variants do not count separately. Vary the family across sections so adjacent sections look visually different.
• Author at most 2 widgets per section (a visual-quality rule; Gate H does not machine-enforce this cap), so one card does not turn into a stack of competing callouts.
• Match widget to content shape: pick from the catalog's "Shape of content it suits" column — key-stat for sections dominated by one number, vs-compare for Theirs/Ours sections, numbered-steps for pipelines, chips for taxonomy/dataset/baseline lists, etc.

The figure/logo/QR assets live under <outdir>/assets/{figures,logos,qr}/ (placed there by paper2assets), and poster.html references them with src="assets/figures/…", src="assets/logos/…", src="assets/qr/…". The path/file values in figures.json, fetch_logos.py, and make_qr.py manifests already carry the assets/ prefix, so dropping them verbatim into src makes the relative paths resolve from the poster's own location without further action.

Step 4 — Iterative fill to exactly fit the page

First, the column-pack pre-check (one calculation, before any fill round). Run python3 scripts/check_poster.py pack <outdir>/poster.html. It flags any column whose figure floors + minimum text already exceed the column height — a negative-slack column is INFEASIBLE, and the fill loop would oscillate there for ~20 rounds (the single biggest time-sink measured: one opus run burned ~15 min on one such column). Re-pack a flagged column before filling — move a text section or the figure to a looser/wider column, or (if TOTAL slack is negative) drop/shrink a figure or cut text — and enter the loop only when every column's slack ≥ 0. Details: references/staged_fill.md → "Column-pack pre-check".

The lean initial render usually leaves some sections under-filled. Grow content with an iterative loop until every section reads FULL (fullRatio 90–100% of the card height, padding included). Each pass: first run check_poster.py autofit <outdir>/poster.html — it deterministically closes the continuous-lever gaps a machine can size exactly (every .grow-card row-gap gap AND the scan-to-read QR height, using the needPx the report already computes, bounded by the column budget) and prints the residual sections that still need YOUR content/figure edits — then measure with check_poster.py slack --with-polish, read the per-section verdicts, pick the one or two modification methods best matched to the current defects, apply them, then re-measure to review and keep-or-rollback. There is no fixed order of methods — the measurement tells you what's wrong and you choose the remedy. Each off-band verdict suggests its remedy:

• EMPTY (<70%) → add Additional text or add the optional section for that column.
• SPARSE (70–90%) → polish to enhance the existing prose (pad with material from the spec's Additional) so the card fills.
• SPILLAGE (100–110%) → polish to reduce content (tighten prose so it fits in fewer lines).
• OVERFLOW (>110%) → remove Additional text or remove the optional section to claw back vertical space.

When two methods are independent (different columns) you may apply both in one pass; when they touch the same column, apply one at a time so a rollback decision stays unambiguous. When several methods could fill the same gap, prefer the highest-value content (real numbers, the Method figure, named contributions) over filler prose.

Machine-checked exit gate. The loop is done only when this command exits 0:

python ~/.claude/skills/paper2poster/scripts/check_poster.py slack \
    <outdir>/poster.html --with-polish --strict

--with-polish runs the fill gate (slack) and the visual-polish gate (FIG/NARROW etc.) on one rendered page — a single browser launch instead of two — and under --strict both must pass, so this one command replaces the old separate slack + polish calls. Do not stop iterating while it exits non-zero. --strict is the same measurement you read each pass, but with a hard exit code — there is no "acceptable SPARSE" or "figure too tight to fix" escape. Keep applying the modification methods (and, for a stubborn figure, the column-width nudge / vertical-room methods in references/staged_fill.md) until the gate passes.

Converge fast, and bound the loop (critical for smaller models). The slack report gives each off-band section a precise needPx delta — e.g. key-result SPARSE grow +50px [+18..+83]. Edit by that number with a continuous CSS lever (margin-bottom / .col gap / figure max-height), don't guess with whole text lines and overshoot the 0.05-wide FULL band. Track recent measurements and switch levers the instant a section ping-pongs SPARSE↔SPILLAGE. And the loop is bounded: if both gates aren't green after ~12 rounds / ~20 min, render the best-measured state, mark the stage DEGRADED with the residual off-band section ids, and move on — never grind indefinitely. This is script-enforced: slack counts consecutive non-converged measurements in <poster_dir>/assets/meta/.fill_budget.json and exits 3 with a CIRCUIT BREAKER banner once it passes --max-iterations (default 80) — an on-disk cap that survives context compaction, so a lost round-count can't make you grind. A converged measurement clears the count, and a call that produced no geometry at all (nav timeout, MathJax settle failure) doesn't count against it. Treat exit 3 as a hard stop (render best state, mark DEGRADED). The exit gate stays strict; only the iteration count is capped. Full rules: the "Convergence protocol" at the top of references/staged_fill.md.

When the .grow section is persistently EMPTY or SPARSE even after exhausting its own Additional/optional content, don't keep stretching that one section — instead refine the content of the other (non-grow) sections in the same column: lift their Additional paragraphs into the rendered card, promote bullets from concise to expanded form, or fold in a paper-specific custom section. The .grow section then absorbs the residual slack naturally instead of inflating a single card with filler.

When a column is at budget (slackRatio ≈ 0) but lopsided — one card SPARSE while its siblings read FULL, so neither adding nor removing content works — use the rebalance-adjacent-sections method: relocate a reserved, on-topic line from a FULL sibling into the SPARSE card (a net-zero swap that shifts the column's height budget without changing its total). This only moves content that genuinely belongs to the destination section.

Read references/staged_fill.md now — it carries the check_poster.py slack command, the JSON report shape, the measure→select→apply→review loop, the flat catalog of modification methods, and the shave-back order.

Run preflight first (check_poster.py preflight) to catch LaTeX residue / raw < in math / missing images before measuring. For semantic Paper2Assets bundles this is also the mandatory figure attribution gate: it fails when the Motivation, Method, or Result image disagrees with assets/meta/figure_selection.json, when Motivation is below confidence or has a Method/Result/Ablation veto role, or when Method and Motivation reuse one figure. Legacy or partial bundles fail until Paper2Assets upgrades their semantic metadata.

Debug aid. When the fill loop misbehaves — slackRatio says one thing, your eyes see another — write check_poster.py slack --json-out <outdir>/assets/meta/poster_debug.json output, open poster.html in a browser, and press d. Every column/section/figure gets outlined; badges show actual rendered height alongside the estimator's prediction and the delta.

Step 5 — Synthesize narration audio for the Listen buttons

paper2assets produced the narration script (<outdir>/assets/meta/narration.json); paper2poster turns it into the mp3s the Listen buttons play — paper2poster is where TTS happens (paper2assets does NOT):

python ~/.claude/skills/paper2poster/scripts/generate_audio.py \
    <outdir>/assets/meta/narration.json --outdir <outdir>/assets/audio

• Backend = free Edge TTS by default — Microsoft Edge online voices via the edge-tts package: no API key, no config file, just network. Default voice en-US-AndrewNeural; narration.json carries "provider": "edge". Override per run with --provider azure (needs ~/.azure/speech.json + AZURE_API_KEY) or --voice <name>. See references/audio_narration.md.
• Graceful skip: if edge-tts isn't installed or the network is down, the script exits with a clear message and writes nothing — the poster's HTML/PDF still render, only the Listen buttons stay silent. Surface that message; don't fabricate audio.
• Keep PLAYLIST in sync: the template's PLAYLIST (and the per-section data-section ids) must match the clip ids in <outdir>/assets/audio/. The Listen buttons + Full Listen play assets/audio/<id>.mp3 by id; an id with no file flashes the highlight and falls silent. So if you drop a section at render time (e.g. dataset-benchmark) or inject a custom one, keep PLAYLIST in sync with the audio files present. If <outdir>/assets/audio/ is absent entirely, the buttons gracefully no-op and the poster still works visually.

Step 5.9 — Pack the header logos to fill their zone (fit_logos.py)

After the fill loop converges, BEFORE rendering, pack the header's institution logos so they FILL their zone regardless of count or shape:

python references/fit_logos.py --poster <outdir>/poster.html

fit_logos.py opens the poster headless at true canvas scale, measures each logo zone (.logo-grid / .logo-block), greedily searches row partitions to MAXIMISE the single uniform height shared by EVERY institution logo (they enlarge together — never some big, some small); logos are reorderable. Institution-resource safety: automatic completion reads only approved entries from assets/logos/logos.json; it never globs every image in assets/logos/. Current entries carry approved: true + decision: "approved"; legacy logos[] entries without those fields remain compatible because older manifests stored accepted resources only. Explicitly rejected entries and orphan images (such as campus photos or cover art) are excluded even if they remain on disk or in stale HTML. When logos.json is absent, fitting fails closed for discovery: it packs only institution sources already explicit in poster.html and adds nothing from disk. The separately-owned venue resource remains independent of this allowlist: the fitter wires assets/logos/_venue.png into the conference chip (.chip.conf) when it exists, so the :has(img) CSS fires and the venue year-text auto-hides — it never duplicates the mark. It also pulls any QR out of the titlebar and re-homes it in the standalone Scan-to-Read section for landscape v1–v4 headers (re-creating that section after Takeaway if an older render dropped it); landscape v5 and all Portrait headers keep their titlebar QR. It rewrites the zone into rows — baked into poster.html disk-to-disk (it never emits the full HTML through your output channel). Every logo renders at the SAME height, as large as the zone allows (one logo fills it; many balance into rows of equal-height marks). The widest mark and the short header band cap that uniform height, so there is no fixed fill target — the packer maximises the shared height. render_poster.py (Step 6) now auto-runs fit_logos.py for you right before it renders (it was routinely skipped when manual), so the exported PDF/PNG always has packed logos; you may still run it standalone to preview.

Step 6 — Render the poster to PDF + PNG (FIRST — applies + bakes the expand)

python ~/.claude/skills/paper2poster/scripts/render_poster.py <outdir>/poster.html

Run this before Step 7 (html2pptx) so the expand is baked into poster.html before html2pptx reads it — the editable poster.pptx then matches the PDF/PNG instead of shipping the pre-expand layout. The script reads @page { size: <W> <H> } from the HTML, mirrors the bundled Inter webfonts into <outdir>/assets/fonts/, freezes any selected OS-font stack to its licensed portable browser face, opens Chromium with print emulation, waits for MathJax to settle, applies the render-time expand, bakes that expand back into poster.html, then writes <outdir>/poster.pdf and <outdir>/poster.png (0.35× scale by default). The poster HTML and assets/fonts/ therefore stay self-contained for sharing across platforms.

Render-time "expand" (automatic, on by default). Right before writing the PDF/PNG, render_poster.py takes one read-only snapshot of the natural poster, then provisionally grows the row-gaps between each under-filled card's inner rows toward POSTER_EXPAND_THRESHOLD (default 0.98). This makes a poster that converged at the 0.90 FULL gate read as visually full — no trailing whitespace — without re-grinding the fill loop to a tighter, ~2× slower gate. Every proposal stops at its bottom-padding ceiling and is immediately reverted if it changes the card's column/container height. Figure/image cards may participate, but their rules are not trusted from the live DOM: the renderer bakes the provisional rules into poster.html, reloads the actual file, and retains a rule only when its cascade still wins, every original section/parent rectangle and visible media box stays fixed, media source/intrinsic/painted dimensions stay fixed, and every tracked figure still fills ≥90% of its section on at least one axis without overflow. A failure removes every provisional rule in that parent scope, rewrites the block, reloads, and repeats to a fixed point; settle/validation failures remove all optional rules. The final rule set must then survive one extra identical-file reload before capture. Only that validated durable page is used for the editable HTML, its D overlay, PDF/PNG, and downstream html2pptx, so all views share the same layout. The bake is one idempotent <style id="poster-expand-baked"> block written only after Step 4, so the staged-fill loop still measures the natural top-aligned layout and its 0.90 FULL gate stays correct.

The surviving rules must also pass a brand-new BrowserContext open, not only warm reloads. Legacy recurring geometry fitters are guarded in the delivered HTML so they measure the unscaled fixed canvas and restore the exact viewer transform; after the cold-open page settles, script execution is frozen before PDF/PNG capture so a late timer cannot create a live-only export.

Two tuning knobs (env vars) — the only layout dials you normally touch:

The pairing is deliberate: 0.90 converges the layout fast, then 0.98 makes the final deliverable read full at render time for free. Both are read from the environment, so a one-off run can override either without editing code.

Useful flags (defaults usually fine):

• --thumb-scale 0.5 for a larger thumbnail, 0.2 for smaller.
• --mathjax-timeout-ms 15000 if the poster has heavy LaTeX.

This is a SOFT path. A blocked CDN, MathJax fetch failure, or slow web font produces a stderr warning and a PDF that may show raw $...$ instead of typeset math. Surface warnings verbatim, but do not re-run the script in response — fix upstream.

Prerequisites: playwright + Chromium. If the script exits with ImportError, run the install commands it prints and re-run.

After rendering, run the final dimension gate:

python ~/.claude/skills/paper2poster/scripts/check_poster.py verify-final \
    <outdir>/poster.pdf --from-html <outdir>/poster.html

A FAIL means the upstream HTML or render_poster.py invocation is wrong (e.g., @page was edited out). Surface the error and stop — re-running without fixing the HTML produces the same failure.

Step 7 — Convert poster.html → poster.pptx (html2pptx — STANDARD final handoff)

Users almost always want the editable PowerPoint in the same run — do NOT treat this as optional or wait for a separate request. Once Step 6 has rendered and baked the expand into poster.html, hand it to the bundled html2pptx sub-skill (vendored inside this skill at html2pptx/; no longer a separate git submodule). From a Claude session, say:

"Use the html2pptx skill to convert <outdir>/poster.html into <outdir>/poster.pptx. The default poster font is Arial, pre-installed on Mac + Windows PowerPoint, so no font embedding is needed — skip the embed step. ONLY if this poster was rendered with the optional Inter override, also run the html2pptx Inter embed (its own scripts/font_embedder.py) so the .pptx ships the font."

The skill extracts the DOM via Playwright, builds a native .pptx (editable text + native shapes + images, NOT a PNG-in-slide), renders a soffice sanity PNG, and runs a Claude-vision fidelity audit (on by default). Run it with --outdir <outdir>/assets/_pptx_build/ so every html2pptx artifact (DOM json, sanity PNGs, the soffice render) stays under assets/, then promote the deck to the deliverable top level: cp <outdir>/assets/_pptx_build/poster.pptx <outdir>/poster.pptx. Final deliverable: <outdir>/poster.pptx (bundle root); build artifacts isolated under <outdir>/assets/_pptx_build/. Because it reads the already-baked poster.html from Step 6, the pptx carries the same expanded layout as the PDF/PNG.

Ordering. html2pptx runs after Step 6's render+bake so it reads the expanded poster.html. Its soffice sanity render writes into <outdir>/assets/_pptx_build/, so it never clobbers the bundle-root poster.pdf / poster.png (which is what made this safe to run last).

Non-fatal. If html2pptx genuinely cannot run (e.g. soffice or a Python dep missing), record a clear WARNING and CONTINUE to Step 7.5 — a pptx failure must never block the core poster.{html,pdf,png}. Report the warning explicitly; never drop the pptx silently.

Step 7.5 — Final deliverable check (MANDATORY before declaring done)

python ~/.claude/skills/paper2poster/scripts/check_poster.py deliverables <outdir>

Deterministic gate, not advisory. It exits 0 only when all four core artifacts exist in <outdir> and meet minimum size thresholds:

• paper_spec.md (from paper2assets)
• poster.html (from Step 3–4)
• poster.pdf (from Step 6)
• poster.png (from Step 6)

If exit is non-zero, the command prints which files are missing and the exact command to produce them — run those, then re-run this check. Loop until exit 0. Then confirm poster.pptx (Step 7) is also present; if html2pptx warned out, say so in the report instead of silently dropping it.

FAILURE MODE this gate catches — models routinely exit after Step 4's fill loop passes its slack/polish hard gates and skip the render steps entirely, rationalizing "all gates passed = task done." This is wrong: the fill loop only verifies the HTML; it does NOT produce or verify the PPTX/PDF/PNG. The same Claude model, on the same paper, will sometimes run Steps 6–7 and sometimes skip them — there is no warning sign you can rely on internally. Do not declare done without running this check.

Step 8 — Report

Tell the user the absolute paths of all artifacts:

• <outdir>/assets/meta/paper_spec.md (from paper2assets)
• <outdir>/poster.html
• <outdir>/poster.pptx (editable PowerPoint, from Step 7 — note it explicitly if html2pptx warned out)
• <outdir>/poster.pdf
• <outdir>/poster.png
• <outdir>/assets/audio/ (generated here by Step 5's generate_audio.py from narration.json; absent if edge-tts/network unavailable — Listen buttons then no-op)

Do not dump file contents into the chat — the spec and HTML are long, and the PPTX/PDF/PNG are binaries. For the PNG, inline-display if the chat surface supports image attachments. Mention that the user can open poster.html directly in a browser; the poster auto-fits the browser window (no scrolling needed). Press s for fullscreen, a to toggle Listen buttons, d to toggle a debug overlay.

The full chain is paper2assets → paper2poster (which now ends by producing the editable .pptx via the bundled html2pptx); each skill is still invokable on its own from a Claude session against the previous stage's <outdir>/.

Tools

scripts/
├── check_poster.py      ← CLI: slack / preflight / polish / verify-final / deliverables
├── select_figures.py    ← figures.json semantics → deterministic figure_selection.json
├── render_poster.py     ← CLI: print-emulated PDF + scaled PNG thumbnail (mirrors bundled fonts)
├── generate_audio.py    ← CLI: narration.json → assets/audio/<id>.mp3 (free Edge TTS default; --provider azure)
└── utils/               ← internal modules (canvas parser, Playwright + settle, etc.)

check_poster.py slack and render_poster.py both read @page { size: W H } from the input HTML — the templates set this — so the canvas size doesn't need to be passed on the command line.

Note: figure-cropping tools (crop_figure.py, extract_pdf.py, fetch_logos.py, make_qr.py) live in the paper2assets skill. If you need a one-off visual box re-crop on a figure paper2assets' deterministic chain couldn't handle, invoke them via ~/.claude/skills/paper2assets/scripts/ (see Step 2.5).

Templates

All templates live in assets/. They share placeholder tokens, audio markup, keybinding scripts, design tokens; only the canvas size + column grid differ across orientation/layout. Step 3 routes between them by orientation trigger (POSTER_ORIENTATION=portrait → portrait; else landscape — DO NOT auto-detect orientation from figure AR) and then Method-figure shape (landscape: AR ≥ 2.5 OR {column=full} → full, else half; portrait: AR ≥ 1.2 OR {column=full} → full, else half).

Landscape (60×36in, 5:3):

• layouts/half.html — 4-column grid for half-width Method figures. Default landscape layout; Method is a half-width card alongside the other sections.
• layouts/full.html — 4-column outer grid with the middle two columns merged into .mid-wide for wide / full-width Method figures (AR ≥ 2.5 OR {column=full}). The .mid-wide block spans grid columns 2–3 and stacks Method (full mid-width, with the wide-figure floor enforcing ≥ 75% of available width) above a 2-col .mid-sub carrying Dataset + Key Result.

Portrait (33.1×46.8in A0, 0.708):

• layouts_portrait/half.html — 2-column grid for tall / moderate-AR Method figures. Default portrait layout; LEFT col carries Problem / Motivation / Method (with figure); RIGHT col carries Dataset / Key Results / Ablation / Headline Numbers / Takeaway. Each column has exactly one .grow, always on its bottom section: Method on the left and Takeaway on the right.
• layouts_portrait/full.html — four-content-band magazine sandwich layout for wide Method figures (AR ≥ 1.2 OR {column=full}). Reading order: titlebar → Band 1 (Problem | Motivation, 2-col equal) → Band 2 (.method-hero centerpiece, full-width: vertical-rotated SIDE-TITLE on left + bullets + wide-figure on right — magazine editorial style) → Band 3 (Key Results 1.5fr | Ablation 1fr | Headline Numbers 1fr, asymmetric 3-col data band) → Band 4 (Takeaway full-width punchline). The Method centerpiece sits in the visual middle, not at the top — this matches poster narrative convention (Problem/Motivation set up the WHY, then Method delivers the HOW, then Results/Numbers pay off, then Takeaway lands the WIN). The bottom 3-col band is intentionally unbalanced (1.5/1/1) so the data display reads as hierarchy, not parallelism. Takeaway gets the full canvas width — the eye lands on it as the closing word. The bullets cell inside the method-hero is wrapped in a pseudo-section (<div class="section method-text" data-section="method-text">) that's invisible to viewers but measured by slack.py — when the figure stretches the row taller than the bullets need, the staged-fill loop sees method-text SPARSE and the LLM expands bullets until the cell fills, unbinding the "narrow bullets cell next to tall figure → whitespace" trap. Optional sections (Contribution, Dataset/Benchmark) are NOT in the default layout — see the inline-commented recipe at the bottom of the template body to paste them in only when the paper genuinely needs them.

If you add a template: keep it venue-neutral, preserve the {{...}} placeholder vocabulary, preserve data-section attributes and PLAYLIST markup, and keep the canvas / cqw / aspect-ratio lock intact for that orientation.

Bundled in assets/fonts/: Inter Regular / SemiBold / Bold / ExtraBold in both .woff2 (web) and .ttf (pptx-embedding) formats — the HTML templates' @font-face rules use the relative fonts/Inter-*.woff2 path, and render_poster.py mirrors them into each <outdir>/fonts/ so the deliverable is self-contained.

Content guidelines

• Section semantics:
  • Problem — the concrete gap or failure mode the paper addresses.
  • Motivation — why this matters now; what's broken about prior approaches.
  • Contribution — the paper's explicit contributions (usually the bulleted "we contribute" list from the intro): the new artifact, dataset, algorithm, theorem, or insight.
  • Method — how the proposed approach works (the technical realization of the contribution).
  • Key equation / Formulation — the paper's core formula(s): the objective, loss, governing equation, or the one expression that defines the method. Include at least one key equation on every poster that has meaningful math (most ML / theory papers do), rendered with the equation widget (MathJax typesets $…$ / $$…$$). The model chooses placement — fold it into Method, or give it its own compact Formulation card when the math is central. Pull the LaTeX from paper_spec.md (Method's Key equation subfield, produced by paper2assets) / text.txt; never fabricate. Skip only for genuinely formula-free papers (pure systems / empirical).
  • Dataset / Benchmark — the datasets, splits, scale, and any new benchmark the paper introduces. If the paper just consumes standard public benchmarks without elaboration, this section is optional. If the paper introduces a dataset or benchmark, treat it as a first-class contribution.
  • Key Result — the headline experimental finding and qualitative takeaway.
  • Ablation Study — which components/design choices matter, quantified. Top 1–3 rows (hard cap 3). If the paper has no ablation, state so and omit numbers.
  • Headline Numbers — the 1–4 standout quantitative results. The numbers themselves are the visual; no figure. MUST render as the template's hero+supporting layout — a <div class="headline-hero"> containing .hero-val + .hero-label + .hero-note AND a <div class="supporting"> row holding at minimum 2 .stat-mini tiles (each with .val + .lbl). Bullets here OR a solo hero without supporting tiles = poster failure mode (caught by polish gates HEADLINE/HERO and HEADLINE/SUPPORTING).
  • Takeaway — the one-sentence "so what".
• Tables vs figures: tables (from captions.json) are not eligible as Method figures (only PNGs in figures/). Their numbers flow into Headline Numbers and Key Result necessary text.
• Every kept figure carries a one-line caption. A <figure> (Method, Motivation, or any secondary figure injected during fill) must always have a non-empty <figcaption> drawn from captions.json — a bare, unlabeled figure is a defect (check_poster.py preflight warns on empty captions). If a figure has no caption source, either write a short factual one-liner from the paper text or drop the figure; never ship it caption-less.
• Prefer 3+ column tables. A two-column Method | Metric table stretched to the section width reads sparse (wide empty gutter). When the paper reports more than one metric, give the table a column per metric so it holds more and fills its width. See content_patterns.md P12.
• No fabrication. Every number, claim, and figure caption must trace to text.txt (produced by paper2assets) or figures.json. When uncertain, prefer omission to invention.

Edge cases

Key rules

• Never invent numbers. Pull from text.txt (paper2assets' output). Every stat, delta, and table cell must trace back to the spec.
• Never emit the full poster.html through your output channel. It's ~100 KB; a full-file Write (or any inline emission of the whole template) overflows the per-turn output-token cap (CLAUDE_CODE_MAX_OUTPUT_TOKENS, default 32000) and aborts the run — the single most common way a smaller model fails on a large poster. Generate it indirectly (shell cp the template + surgical Edits for placeholders, or a build_poster.py generator — see Step 3), and keep every fill-loop change a partial Edit, never a full rewrite.
• Never re-Read the whole poster.html during the fill loop (INPUT-context twin of the rule above). At ~100 KB, re-reading it each round floods a smaller model's context window → auto-compaction → lost fill state → the loop thrashes and never converges. Work from the slack report — it now prints an EDIT TARGETS block with the verbatim source of every off-band section, so lift your Edit old_string straight from there and never re-read the whole file. See staged_fill.md rule 6.
• Lean render first, measured fill second. Don't guess at fit during placeholder substitution. Render the core sections' Necessary only — Problem, Motivation, Method (with the key equation), Key Result, Headline Numbers, Takeaway — then let check_poster.py slack decide what to add. Contribution is dropped by default (keep only when the paper's headline novelty IS its contribution list). Ablation Study, Dataset / Benchmark, and a filler Takeaway are deprioritized — render only when they carry real first-class content (Dataset only when the paper introduces one; Ablation only with real ablation rows). The fill loop reaches for the key equation, real numbers, the Method figure, and secondary/qualitative figures before Ablation, Dataset, or padded prose — and before resurrecting Contribution.
• Target ≥2 figures per poster. Method alone leaves the right-side empirical story as a prose-and-numbers wall. Step 2 picks a secondary figure whenever the paper has one — the eye needs at least one empirical visual beyond the Method diagram. 1-figure posters are acceptable only when no remaining figure carries real signal (rare).
• Include the key equation. Every poster for a paper with meaningful math MUST show at least one key equation/formula (objective, loss, or governing expression) via the equation widget — integrated into Method or as a compact Formulation card. Rendering zero equations for an equation-driven paper is a quality failure (the single most common gap vs author GT). Pull the LaTeX from the spec / text.txt; never invent symbols.
• No contentless section. A section that would render with no real content is omitted, not shown empty — never ship a heading over a placeholder or a lone "N/A". This is the flip side of the FULL fill gate: deprioritized sections (Ablation, a filler Takeaway, Dataset when not introduced) are dropped rather than padded. Every kept section must carry genuine, paper-specific content.
• Strict per-section fit gate. Stop the staged-fill loop only when every section is FULL (fullRatio 0.90–1.00) and every card figure fills 90–100% of its box on at least one axis (polish reports zero FIG/NARROW). There is no per-column SPARSE allowance — a SPARSE card is not done, it is a card you have not finished filling.
• Fill-loop pass ≠ task done. Passing the slack/polish gates means the HTML is well-laid-out — it does NOT mean the deliverables are produced. Step 6 (PDF/PNG render) and Step 7 (html2pptx) are separate steps and are routinely skipped by models who mistake "fill loop converged" for "task done." The check_poster.py deliverables gate in Step 7.5 is non-negotiable: run it before reporting, loop until exit 0.
• .grow cards are gated, not exempted. A .grow card stretched by flexbox to absorb leftover column space can read as FULL in old tooling yet still show a visible band of trailing whitespace. Apply the same fullRatio gate to it — fill it (Additional / extra bullet) or shift content from its non-grow siblings instead of leaving the whitespace.
• Multi-tile content uniformity (RECURRING DEFECT — read carefully). Whenever a section emits a horizontal row of small stat / number tiles, every tile in the row MUST share the same visual shape — same line count for the big number, same line count for the label. Mismatched heights look broken: one tile's value sits high while its neighbor sits low, or the labels show a 2-line / 3-line zig-zag baseline. Applies broadly — not just .headline-hero .supporting .stat-mini tiles, but also .p-stat-strip cells, any ad-hoc number-card row in Motivation / Method / Key Results, and any future tile widget.
  • The template now structurally backstops this: .headline-hero .supporting uses align-items: flex-start (all .val numbers top-align so they always sit at the same height regardless of label height) and .stat-mini .lbl carries min-height: 2.4em (every label reserves 2 lines, so a 1-line and a 2-line label occupy identical vertical space). This means a label that wraps can no longer shove its value up out of line. But the CSS only reserves the slot — you must still keep every label ≤ 2 lines or a 3-line label overflows the reserved 2-line slot and the row breaks again. Do NOT rely on the CSS as an excuse to write uneven labels.
  • Big numbers: either ALL tiles fit on one line OR ALL tiles wrap to two. Never mix 1-line and 2-line within the same row. Fix by shortening the longest tile's value (e.g. −84% FLOPs Δ → −84%), or by rephrasing short tiles to wrap too — usually the first option.
  • Labels: keep all tiles in a row to the SAME line count, ≤ 2 lines each (the reserved slot is exactly 2 lines). Target either all-1-line (short tokens: pts, params, mAP) or all-2-line, never a mix that reads as a zig-zag. If one label naturally goes to 3 lines while siblings stay at 2, shorten the long one (drop adjectives, prefer abbreviations, use unit shortcuts like M / B, acc for accuracy) — do NOT pad the shorter ones.
  • Check before declaring done. Visually scan every multi-tile row in the rendered poster. If values are at different y-positions or labels show a stair-step baseline, the row fails uniformity — fix the content before signing off.
• Do not edit the canvas lock. The 60×36in / cqw / aspect-ratio: 5 / 3 rules in both templates are what makes the browser preview, print PDF, and PNG thumbnail look like the same layout at different magnifications.
• paper2assets owns the figure-cleanup pipeline (top-check → decaption → autotrim). Don't re-run the deterministic chain here — it's already done. Step 2.5's visual box cut is for residual asymmetric noise only.