[Media] Add a content Gallery that reuses Image Zoom

[Vonng]

Goal

Add a semantic responsive grid for related documentation images after the shared media contract and zoom runtime are stable.

Tracking issue: #3
Blocked by shared media contract: #8
Blocked by Image Zoom: #9

Authoring API

• gallery: strict integer columns in the range 1-4; optional author-provided label.
• gallery/image: required src and meaningful alt; optional caption.
• Use standard shortcode notation and validate parent/child relationships.
• Preserve author order.

Rendering approach

• Reuse the shared media resolver for URLs, dimensions, alt text, captions, lazy loading, and subpath behavior.
• Render a responsive static grid with semantic figure/caption markup.
• Reuse the Image Zoom eligibility and dialog runtime; do not add a second lightbox.
• If zoom is disabled or JavaScript is unavailable, images and captions remain complete.

Output behavior

• HTML: responsive grid, intrinsic dimensions where known, loading=lazy, and no layout-breaking long captions.
• Print: static complete figures with sensible pagination.
• Markdown: ordinary images followed by readable captions; no Gallery HTML.
• RSS: static sequential figures.

Acceptance criteria

• Cover 1-4 requested columns, narrow viewports, mixed aspect ratios, long captions, CJK, RTL, local/static/remote sources, and missing/invalid parameters.
• Gallery does not load a separate runtime or duplicate dialog.
• axe and keyboard tests pass with zoom enabled and disabled.
• Production output remains useful with JavaScript disabled.

Non-goals

• Carousel behavior, reordering, uploads, filtering, fullscreen slideshows, or build-time remote image fetching.

[Vonng]

Implementation record (2026-08-12)

The theme-side Gallery implementation is complete on the current working branch. This issue remains open for the durable bilingual consumer-site documentation and Playwright/axe gate tracked in pgsty/oink.pgsty.com#2.

Authoring and validation

• Added the stable gallery / gallery/image API from the frozen content-primitives contract.
• gallery accepts named parameters only: strict integer columns=1..4 (default 2) and an optional nonblank plain-text label.
• gallery/image must be a direct Gallery child, accepts named parameters only, requires nonblank string src and meaningful plain-text alt, and accepts an optional nonblank plain-text caption.
• Unknown parameters, wrong types, invalid ranges, missing values, unsafe/protocol-relative URLs, non-image resources, wrong parents, raw parent content, and empty Galleries fail with position-aware errorf messages.
• Children resolve and validate first, then register structured records in parent Scratch under zero-padded shortcode ordinals. The parent owns every output and preserves author order; repeated rendering overwrites the same owner instead of accumulating Page Store state.

Shared media and semantic output

• Reuses content/image-resolve.html; there is no copied lookup logic and no remote fetching.
• Exact page resources and global resources receive intrinsic dimensions when Hugo knows them. Static and remote sources remain valid without invented width/height values.
• Root-relative resources remain subpath-safe; explicit HTTP(S) sources pass through unchanged.
• HTML uses a labelled semantic list of <figure> elements with direct <figcaption> children, loading="lazy", and decoding="async".
• Responsive CSS honors the requested desktop maximum and steps from 4 → 3 → 2 → 1 columns. It uses logical properties, semantic theme tokens, long-caption wrapping, dir="auto", forced-colors boundaries, dark-mode-compatible colors, and sequential break-safe print output.
• The fixture covers page/global/static/remote sources, known/unknown dimensions, mixed aspect ratios, long English text, CJK, and RTL captions.

Output isolation and cache safety

• Markdown emits only ordinary images in author order plus escaped italic caption paragraphs; it contains no Gallery/runtime HTML.
• Print and RSS retain complete static figures and captions with no dialog or interaction attributes.
• Generic section RSS has a durable regression for a page that also produces HTML and Markdown, covering Hugo shortcode/summary cache reuse.
• The shared static-image filter now removes exact data-td-image-zoom, data-zoom-src, and data-no-zoom attributes while preserving similarly named author attributes such as data-td-image-zoom-extra.

Image Zoom reuse

• Gallery adds no JavaScript, lightbox, dialog, carousel, or bundle entry.
• HTML images carry the existing explicit eligibility marker and canonical full source.
• Only after all children validate, normal HTML consults the strict page/site Image Zoom configuration and idempotently requests the existing hasImageZoom variant.
• Enabled Galleries share exactly one existing native dialog/runtime. Default-off and explicit page-off Galleries retain complete images/captions without loading Zoom.
• No-JS and browsers without HTMLDialogElement retain the original static Gallery unchanged.

Verification

• Hugo 0.164.0: warning-free example build; complete i18n, typography, component contract, code-block, primitive, media, Image Zoom, Gallery, and diff checks pass.
• Hugo 0.160.1 (minimum CI version): warning-free build and the same full checker matrix pass.
• Gallery checker covers all four column values, escaping, author order, parent/child failures, invalid parameters, source kinds, intrinsic dimensions, subpath URLs, HTML/Markdown/Print/RSS, generic RSS cache reuse, enabled/default-off/page-off Zoom, one shared dialog, and absence of a Gallery runtime.
• Local production-build Chrome/Playwright passed five consecutive full rounds after the initial pass: 4/3/2/1 responsive columns, desktop/mobile overflow, mixed aspect ratios, long/CJK/RTL captions, pointer/Enter/Space, Close/Escape/guarded backdrop, focus restoration, all four source kinds, enabled/disabled Zoom, no JavaScript, missing HTMLDialogElement, reduced-motion emulation, dark mode, and sequential print styling.
• axe-core reports zero WCAG A/AA violations for the enabled Gallery closed/light and open/dark, plus the disabled Gallery.

Deferred delivery gate

The browser harness used above is local and temporary. The durable EN/ZH component-catalog pages, generated Markdown goldens, and committed Playwright/axe tests remain in pgsty/oink.pgsty.com#2. Keep this issue open until that integration lands; no theme-side implementation blocker remains.

Non-goals remain carousel behavior, reordering, upload, filtering, fullscreen slideshows, decorative Gallery images, remote build-time fetching, and a second lightbox/runtime.

[Vonng]

Consumer-site gate update (2026-08-12)

The deferred bilingual consumer-site and durable browser/axe gate is now complete locally on pgsty/oink.pgsty.com branch codex/content-primitives-site.

Full evidence and exact revisions: pgsty/oink.pgsty.com#2 (comment)

The integration adds the EN/ZH component catalog examples, generated Markdown goldens, HTML/Markdown/Print/RSS build assertions, seven component Playwright tests, and 27 focused axe cases. It also confirms that Gallery shares the one Image Zoom dialog/runtime, remains usable without JavaScript, collapses to 4/3/2/1 responsive columns, and does not load the runtime on unrelated pages.

The theme implementation and its consumer validation now have no known local blocker. This issue remains open because neither working tree has been committed or merged, and the later theme release plus consumer go.mod pin and hosted verification are still separate delivery gates.