Generate & display image/PDF thumbnails for topic documents (put image_processing to use)

Background

The image_processing gem (Gemfile:13, ~> 1.14) is declared and locked (pulling in mini_magick + ruby-vips) but nothing in the app actually uses it — no Active Storage variants, previews, or representations anywhere in app/, app/views/, or config/. Topic documents are rendered as their original blobs only:

• app/views/topics/_topic.html.erb:17-38 — the Documents section shows a generic file icon + filename link + Download button for every document, regardless of type.
• app/helpers/topics_helper.rb — card_preview_media embeds the full-size original.

Rather than drop the gem, this issue puts it to work: generate small thumbnails for image and PDF documents and show them on the topic show page, falling back to the current icon for everything else.

This is a deliberately small, self-contained first slice. The nicer-but-heavier version (click-to-enlarge lightbox, eagerly generated variants) is captured under Future enhancements below and should be a separate follow-up.

Approach: lazy generation

Variants are generated lazily on first request (Active Storage's default) and cached. This is what keeps the task small:

• No background job — no async infrastructure to build.
• No backfill — lazy generation is the on-demand backfill. Existing documents get a thumbnail the first time someone views the topic; new ones the same way. Nothing is precomputed, so there's no "old documents lack a variant" gap and no migration/rake task.
• No conditional-on-present logic — we simply render representation(:thumb) for representable documents and fall back to the icon for the rest.

Proposed work

1. Wiring — declare a :thumb variant on the attachment

Resize to 256x256.

• Covers raster images directly. For PDFs, use the unified representation(:thumb) API, which routes images through variant and PDFs through preview (first page → image → resize).
• Confirm config.active_storage.variant_processor = :vips (default; ruby-vips is already locked, so no ImageMagick dependency needed for images).

2. UI — thumbnail on the topic show page

In app/views/topics/_topic.html.erb, in the per-document block (lines 18-37), render the thumbnail in place of the generic SVG icon for representable documents, wrapped in a plain link that opens the original inline (new tab). Keep the filename link, size, and Download button exactly as they are.

3. System dependencies

• Image variants: libvips (already implied by ruby-vips).
• PDF previews: poppler-utils (pdftoppm) or mupdf must be present in CI and the deploy/Docker images, or PDF thumbnails fail (and fall back to the icon).
• webp/avif/svg support depends on how libvips is built. Recommend excluding image/svg+xml from thumbnail generation (vector; rasterizing needs librsvg and adds little value) and verifying webp/avif on the target image before shipping.

Acceptance criteria

• An image document on a topic shows a thumbnail on the topic show page (generated on first view, cached after).
• A PDF document shows a first-page thumbnail.
• Clicking a thumbnail opens the original image/PDF inline in a new tab.
• Non-representable types (video/audio/other) and any document whose preview can't be generated fall back to the current generic icon — no errors.
• Required system dependencies (libvips, poppler/mupdf) are available in CI and deploy images.
• Tests cover: the :thumb variant is declared, the view renders a thumbnail for representable documents, and non-representable documents render the fallback icon.

Known tradeoffs (acceptable for a nonessential feature)

• First-view latency — the first person to view a topic with a large image/PDF waits while the thumbnail generates; cached thereafter.
• No proactive backfill — existing documents get thumbnails on first view rather than ahead of time. This is intentional.

Future enhancements (separate follow-up)

A nicer interaction, deferred to keep this task small. It can be added later with no backfill and no confusing UI change, because lazy generation makes any new variant available uniformly for all documents (old and new) the moment its consumer ships — so every thumbnail behaves the same, and the click target simply upgrades from "open in new tab" to "open lightbox":

• Add a :medium variant (e.g. resize_to_limit: [1200, 1200]) for display in a lightbox/modal, so clicking a thumbnail doesn't load the full-resolution original (documents can be up to 200 MB per the Topic size validation).
• Lightbox closes via backdrop and Esc; reuse an existing modal pattern if one exists.
• Optionally, eagerly generate variants via a background job on upload to remove first-view latency. (Note: going eager is the point at which a backfill question for old documents would reappear — staying lazy avoids it.)
• Unify TopicsHelper#card_preview_media to use representation(:thumb) for card/list previews instead of full-size originals.

Start with Gemfile:13, app/views/topics/_topic.html.erb:17-38, and app/helpers/topics_helper.rb, then locate the topic document attachment declaration and existing Active Storage configuration. Done means representable images and PDFs show cached 256x256 thumbnails linking to the original, while other or failed previews retain the generic icon; verify the required system dependencies and add coverage for the variant and fallback cases.