preview: gaps blocking ucdavis/win's preview.yml migration (TinyTeX/multi-format render, post-render hooks)

[d-morrison]

While migrating ucdavis/win to gha's reusable workflows (ucdavis/win#74), its bespoke preview.yml could not migrate to the preview/preview-deploy/cleanup-pr-previews family. Feature-by-feature diff (per CLAUDE.md's migration guidance) found these gaps:

1. No TinyTeX / PDF support. preview.yml (reusable) has no tinytex input, unlike quarto-publish.yml. win renders PDF and DOCX outputs per chapter in its preview.
2. No post-render hook. win runs several post-render steps between render and deploy: changed-chapter detection, HTML change highlighting (with a re-render after injecting preview metadata), DOCX tracked-changes generation, and a home-page banner (all repo-local .github/scripts/*.py). A generic "run this script after render, before the artifact upload" input (or documented extension point) would let win keep these while using the shared build/deploy plumbing.
3. Label-driven behavior. win toggles highlighting off via a no-preview-highlights PR label and re-deploys on labeled/unlabeled events; the reusable preview family would need the label context forwarded (or at least not stripped) for that to keep working.

Per the migration rule, win's preview.yml migration is deferred (not hand-duplicated or feature-dropped) until these are closed or explicitly wontfixed.

[d-morrison]

Triage note from a backlog sweep (2026-08-29). Item 1's premise needs correcting, and the correction makes it smaller rather than larger.

"No TinyTeX / PDF support" is not quite right: preview/action.yml:90 does pass tinytex: to quarto-dev/quarto-actions/setup, but gates it on a hard-coded PR label rather than an input:

        # Install TinyTeX in the same setup only when a PDF render is requested;
        # composite actions can't vary `with:` conditionally, so gate it on the
        # label expression rather than running a second setup step.
        tinytex: ${{ contains(github.event.pull_request.labels.*.name, 'preview:pdf') }}

So the actual gap is narrower and more precisely stated as two things:

1. No tinytex input. preview/action.yml's inputs are path, r-version, apt-packages, use-renv, r-packages, install-package, setup-chrome, submodules, render-profile, output-dir, fail-on-render-warning, forbid-log-patterns — no tinytex, unlike quarto-publish.yml, which has one and threads it through (quarto-publish.yml:41-44, :154). A consumer that always renders PDF has to label every PR.
2. No formats input. quarto-publish.yml has one; preview does not. win renders PDF and DOCX per chapter, so the multi-format half of item 1 is a separate missing input from the TinyTeX half.

The natural fix for (1) keeps the label working rather than replacing it — OR the new input with the existing label expression, so no consumer relying on preview:pdf breaks.

Suggested split. Per this repo's own rule about issues carrying independent subissues (and the Closes #N hazard — a PR fixing only the inputs would silently close the post-render-hook and label-forwarding work too), the three numbered items want to be child issues:

• 1a: preview — add a tinytex input, ORed with the existing preview:pdf label.
• 1b: preview — add a formats input, mirroring quarto-publish.yml.
• 2: preview — a post-render extension point. Design-bearing; the "generic run-a-script-between-render-and-upload" shape needs a decision about what it is allowed to touch.
• 3: preview — forward PR label context and re-deploy on labeled/unlabeled.

1a and 1b are mechanical and could land together. 2 and 3 are design questions that shouldn't ride along with them.

I did not open a PR for any of these — flagging the corrected scope first, since item 1 as filed reads like a bigger gap than it is, and the split is a maintainer call.

---

Posted by Claude Code (AI agent) --- not written by a human.

---

Generated by Claude Code

[d-morrison]

Decision on item 2 (post-render extension point): option (c) — document the partial-migration path

Owner's call, taken just now. Recording it here with the reasoning, and with a correction to this issue's own framing that a scoping pass turned up.

Item 1's premise is false as filed

This issue says preview has "no TinyTeX / PDF support". It has had label-gated pdf/docx/revealjs render steps and a label-gated tinytex: since the family's first commit:

$ git log -S"Render docx" --reverse origin/main -- preview/action.yml
3de2c97 2026-06-20  Add reusable PR-preview/publish workflow family (#34)

This issue was filed 2026-07-16 — 26 days later. Confirmed live at preview/action.yml:90 (tinytex: gated on preview:pdf), :144, :177-202 (the three label-gated render steps) and :204-211 (Render html, unconditional --to html).

So the real gaps are narrower than the title suggests, and item 3's "label context is stripped" is also partly false — preview/action.yml:90,144,152,178,187,196 all read github.event.pull_request.labels.*.name and work, because a reusable workflow inherits the caller's event context.

Why (c) for the post-render hook

ucdavis/win's sequence is seven steps (win/.github/workflows/preview.yml:72-113): a change-detection script writing to $GITHUB_ENV, a metadata injector gated on that variable, a second full quarto render, a pip install python-docx, then three more scripts. A single post-render-script: input cannot express that without win consolidating into one entry-point script that shells out to quarto render and pip install itself — which moves work onto the consumer and loses the per-step if: readability.

(b) — splitting preview into render-only and stage/upload composites — is the flexible answer and the largest change. preview/action.yml:263-279 stages and uploads unconditionally, so nothing can interpose today, and it is the only option touching the fork/trust boundary this workflow's own header calls load-bearing.

(c) works because the artifact contract is already small and already documented: preview-deploy.yml:84-95 reads exactly meta/pr-number.txt, meta/action.txt, and site/. A consumer with post-render steps can keep a bespoke build half and still adopt preview-deploy.yml + cleanup-pr-previews.yml — getting the deploy, preview-URL and cleanup machinery without needing an extension point at all.

(a) remains available if a second consumer ever wants it. One consumer with an unusually elaborate sequence is not enough evidence to design an extension point around.

(c) is not "do nothing"

It has a deliverable: document the partial-adoption path and the artifact contract, so a consumer can find it without reading preview-deploy.yml's source. Tracked as a child issue below rather than left as a decision nobody acts on.

Splitting this issue

Filing the remaining work as children, because Closes #256 on any one of them would close all three items — GitHub cannot partially close an issue, and the residual work would be silently gone while the closed issue read as evidence it was handled. That is the hazard this repo's own issue-first fragment records for ai-config#847.

Children follow in the next comments. This issue stays open as the parent until they land.

---

Posted by Claude Code (AI agent) --- not written by a human.

---

Generated by Claude Code

[d-morrison]

Correction: the (c) decision above is superseded — gha will adopt win's post-render steps as capabilities

The owner challenged the option set rather than picking within it, and was right to. Recording the reversal here rather than editing the previous comment, so the reasoning stays checkable.

What was wrong with the framing, not just the answer

This issue calls item 2 a "post-render extension point". The scoping pass inherited that phrasing, and my options (a), (b) and (c) all inherited it in turn — a hook, a composite split, or documenting a workaround. Every one of them presupposed win's post-render steps stay in win as opaque consumer code. The option set was complete within a frame that was itself the mistake, which is why it read as exhaustive.

Nobody in that chain asked the prior question: are those steps themselves worth having?

They are, and it is not close

Read rather than inferred from filenames (ucdavis/win, .github/scripts/):

script	what it does	size
highlight-html-changes.py	diffs the PR's rendered HTML against the published gh-pages version and injects highlighting — a visual diff of rendered prose	16 KB
create-docx-tracked-changes.py	diffs PR DOCX against published DOCX, emits Word tracked changes	8.6 KB
add-home-banner.py	preview home banner linking to changed chapters	3.7 KB
detect-changed-chapters.py	shared substrate: which chapters changed vs deployed	7 KB

None of it is win-specific. They operate on rendered HTML/DOCX and gh-pages, which every Quarto book, manuscript and website repo here has. The DOCX one is the feature that lets a non-technical co-author review a PR's prose as Word tracked changes — squarely this lab's workflow. grep -ril "tracked.changes\|highlight.*change\|changed.chapter\|redline" over this repo returns nothing, so gha offers no equivalent today.

Adoption is cheaper than it looks, and is not copy-paste

• Dependencies are light: stdlib (difflib, re, html), git, and python-docx for one script. No pandoc.
• Licensing is not an obstacle: ucdavis/win's LICENSE reads COPYRIGHT HOLDER: d-morrison.
• But the code does not meet this repo's bar: 9 check=False and 6 broad except blocks across the four, which is precisely what shared/principles/fail-fast.md forbids. Porting means a rewrite pass plus tests to this repo's standard.

Why this dominates every option I offered

It dissolves the problem instead of accommodating it. If gha performs the valuable post-render work itself, win needs no extension point at all — its seven-step sequence becomes preview with a few inputs turned on. No hook to design, no composite split, no fork/trust-boundary change, and the capability lands for every other Quarto repo at the same time.

Consequences for the children

• preview: document the partial-adoption path for consumers with post-render steps #757 (document the partial-adoption path) stays open but is no longer the unblocker and drops in priority. The artifact contract is still worth documenting; it is no longer what lets win migrate.
• preview: add tinytex and formats inputs (label gating is the only way to reach PDF/multi-format today) #758 and preview: label handling is asymmetric — adding a label skips the build, removing one runs it #759 are unaffected — they are about preview's inputs and label handling, independent of this.
• Three new children follow for the adoption itself.

---

Posted by Claude Code (AI agent) --- not written by a human.

---

Generated by Claude Code