@michaelyagi/shoji 0.1.0-alpha.6

package/dist/shoji.css

@@ -0,0 +1,690 @@
+/* DESIGN.md §4-autoplay — thin progress bar along the bottom edge, tracking
+   time-to-next-advance for timed (image) slides. Hidden during video slides,
+   where the video's own runtime — not a fixed interval — drives advancement. */
+.shoji-autoplay-progress {
+  position: absolute;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  height: 3px;
+  background: rgba(255, 255, 255, 0.15);
+  z-index: var(--shoji-z-toolbar);
+}
+
+.shoji-autoplay-progress[hidden] {
+  display: none;
+}
+
+.shoji-autoplay-progress-bar {
+  height: 100%;
+  width: 0%;
+  background: var(--shoji-progress);
+}
+/* DESIGN.md §5 — layout takes over the container entirely once enabled
+   (any host markup that was there at scan time is replaced by its own
+   generated tiles), so all of its structural styling lives here rather than
+   depending on host CSS. */
+
+.shoji-layout {
+  position: relative;
+}
+
+/* masonry & justified always give the container an explicit
+   `container.style.height` (index.ts) — never intrinsic/content-driven —
+   so CSS layout containment is safe here and doesn't collapse or misjudge
+   its size. A real, reported slowdown: opening/closing the lightbox reads
+   layout (getBoundingClientRect/offsetHeight — zoomTransition.ts's FLIP
+   technique) which forces the browser to flush *any* pending layout on the
+   page first, including this container's own (often large — hundreds of
+   individually absolutely-positioned tiles) subtree, even though none of
+   that subtree's layout ever changed. `contain: layout` tells the browser
+   this subtree's internal layout can't affect, and isn't affected by,
+   anything outside it, so that flush can skip descending into it. Not
+   applied to grid: its height is intrinsic (content-driven auto-sized
+   rows), which layout containment doesn't safely decouple the same way. */
+.shoji-layout--masonry,
+.shoji-layout--justified {
+  contain: layout style;
+}
+
+.shoji-layout-tile {
+  display: block;
+  cursor: pointer;
+}
+
+.shoji-layout-tile img {
+  display: block;
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+
+/* masonry & justified: both JS-positioned, absolutely placed, GPU-composited
+   moves only (transform), per CLAUDE.md — no top/left animation.
+   visibility: hidden until the JS layout pass actually sets a real
+   width/height/transform — masonry/justified skip that pass entirely
+   (index.ts's containerWidth <= 0 guard) if the container isn't sized yet
+   at construction, correcting only once the ResizeObserver's own
+   (asynchronous) initial notification fires. In that gap, an unstyled
+   tile falls back to CSS auto-sizing from its <img> child, which can be a
+   genuinely 0×0 or wildly wrong-shaped rect depending on image load
+   timing — clickable, but a click landing on it computes the zoom
+   transition's origin from that same bad rect, silently skipping the
+   animation (a 0×0 origin) or animating from the wrong place (a
+   wrong-shaped one). visibility: hidden (not display: none — keeps the
+   space-not-taking difference irrelevant here, but note it also removes
+   the tile from hit-testing, unlike opacity: 0) makes an unpositioned
+   tile un-clickable for that entire window instead — the JS layout
+   functions clear it back to visible the moment they actually set real
+   geometry. See DESIGN.md §2.3b. */
+.shoji-layout--masonry .shoji-layout-tile,
+.shoji-layout--justified .shoji-layout-tile {
+  position: absolute;
+  top: 0;
+  left: 0;
+  visibility: hidden;
+}
+
+.shoji-layout--masonry.shoji-layout--animate .shoji-layout-tile,
+.shoji-layout--justified.shoji-layout--animate .shoji-layout-tile {
+  transition: transform var(--shoji-duration) var(--shoji-easing);
+}
+
+/* grid: native CSS grid does the positioning, no JS math or transforms. */
+.shoji-layout--grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(var(--shoji-layout-column-width, 240px), 1fr));
+  gap: var(--shoji-layout-gutter, 8px);
+}
+
+.shoji-layout--grid .shoji-layout-tile {
+  aspect-ratio: var(--shoji-layout-tile-aspect, 1);
+}
+
+/* headings (groupBy) — grid: a real grid row of its own, native flow, no JS
+   positioning needed (a full-span item naturally starts a new row after
+   it). masonry/justified: JS-positioned same as tiles, since those modes
+   don't have a document-flow "row" to insert into. */
+.shoji-layout-heading {
+  margin: 0;
+}
+
+.shoji-layout--grid .shoji-layout-heading {
+  grid-column: 1 / -1;
+}
+
+.shoji-layout--masonry .shoji-layout-heading,
+.shoji-layout--justified .shoji-layout-heading {
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: 100%;
+}
+
+/* justified headings are compact, inline labels, not full-width blocking
+   elements (see the groupBy option's doc comment in index.ts) — sized to
+   their own content by default, and to their own JS-computed max-width
+   only when the content-fitting pass decides a label needs to wrap. This
+   overrides the shared width: 100% rule above by source order (equal
+   specificity), not by a stronger selector. */
+.shoji-layout--justified .shoji-layout-heading {
+  width: auto;
+  white-space: nowrap;
+}
+
+.shoji-layout--masonry.shoji-layout--animate .shoji-layout-heading,
+.shoji-layout--justified.shoji-layout--animate .shoji-layout-heading {
+  transition: transform var(--shoji-duration) var(--shoji-easing);
+}
+
+/* Font customization points, per CLAUDE.md ("all styling through --shoji-*
+   custom properties with sane defaults"). .shoji-layout-heading itself (the
+   plain-string/default heading, and the shared parent of title+subtitle)
+   deliberately keeps its browser-default <h2> font-size untouched rather
+   than gaining its own --shoji-layout-heading-font-size — overriding that
+   here to "inherit" would shrink it from the UA stylesheet's own (larger)
+   h2 default, a visible regression for anyone not using the structured
+   form. Host CSS targeting .shoji-layout-heading directly already fully
+   controls it.
+
+   The title/subtitle spans below intentionally do NOT size off that same
+   (oversized, unreset) h2 default — title and subtitle both get an
+   explicit shared default size instead (matching .shoji-counter's own
+   0.875rem elsewhere in core, for visual consistency), decoupled from
+   whatever the plain-string heading's own size happens to be. The label
+   (title) reads as muted/normal-weight, the value (subtitle) as bold/
+   full-color — e.g. "Taken" vs a bolded date — the inverse of an earlier
+   version of this default that bolded the label instead. */
+.shoji-layout-heading {
+  font-family: var(--shoji-layout-heading-font-family, inherit);
+}
+
+.shoji-layout-heading-title {
+  font-size: var(--shoji-layout-heading-title-font-size, 0.875rem);
+  font-weight: var(--shoji-layout-heading-title-font-weight, 400);
+  color: var(--shoji-layout-heading-title-color, #767676);
+  /* headingOverflow: 'fit''s ellipsis fallback (the one unavoidable case —
+     a single label wider than the container even alone) still needs
+     overflow-wrap: break-word so a single long unbroken token (a URL, a
+     hashtag) doesn't itself force the ellipsis box wider than intended. */
+  overflow-wrap: break-word;
+}
+
+.shoji-layout-heading-subtitle {
+  margin-left: 0.6em;
+  font-size: var(--shoji-layout-heading-subtitle-font-size, 0.875rem);
+  font-weight: var(--shoji-layout-heading-subtitle-font-weight, 700);
+  color: var(--shoji-layout-heading-subtitle-color, inherit);
+  overflow-wrap: break-word;
+}
+
+/* stickyHeadings — grid mode only; masonry/justified headings are already
+   absolutely positioned by JS, which sticky can't meaningfully layer onto
+   (see the option's own doc comment in index.ts). */
+.shoji-layout--grid .shoji-layout-heading--sticky {
+  position: sticky;
+  top: 0;
+  z-index: 1;
+}
+/* DESIGN.md §4-zoom — cursor affordances only; the transform itself is set
+   inline (per-slide, computed from gesture/button state, not a static
+   rule). Scoped to .shoji-zoom-enabled (added by the plugin itself, per
+   slide) rather than the bare .shoji-slide-img class — that class exists on
+   every slide image regardless of whether this plugin is even enabled for
+   a given gallery, and this CSS ships in the single-file bundle alongside
+   every other official plugin's, so an unscoped rule would leak a zoom-in
+   cursor onto galleries that never opted into this plugin at all. */
+.shoji-zoom-enabled {
+  cursor: zoom-in;
+}
+
+.shoji-zoom-enabled.shoji-zoomed {
+  cursor: grab;
+  /* Reported from real usage: a scaled-up image could show GPU tile-seam
+     lines through its own content while zoomed — the same rasterization
+     quirk as the toolbar's own (shoji.css), just from the image's frequent
+     scale() updates instead of a neighbor's. Scoped to only while actually
+     zoomed (not the whole time this plugin is enabled) — at scale 1 there's
+     no scale-up to tile-seam in the first place, so no reason to spend the
+     extra memory a promoted layer costs. */
+  will-change: transform;
+}
+
+.shoji-zoom-enabled.shoji-zoomed:active {
+  cursor: grabbing;
+}
+/**
+ * Core theme tokens (DESIGN.md §9). Dark is the default theme; `.shoji-light`
+ * overrides to light. No hardcoded colors/sizes elsewhere in JS or CSS —
+ * everything routes through these custom properties.
+ */
+:root {
+  /* .shoji-outer's own page-level z-index — relative to the rest of the
+     host page, not to anything inside the lightbox. Real pages routinely
+     put sticky navbars/sidebars/toast containers at 1000-9999, so this
+     needs real headroom, not the small internal scale below (which only
+     orders backdrop/slides/overlay/toolbar/toast *against each other*,
+     inside the stacking context .shoji-outer's own z-index establishes). */
+  --shoji-z-base: 9000;
+
+  --shoji-z-backdrop: 0;
+  --shoji-z-slides: 10;
+  --shoji-z-overlay: 20;
+  --shoji-z-toolbar: 30;
+  --shoji-z-toast: 40;
+
+  --shoji-color-bg: #0b0b0d;
+  --shoji-color-fg: #f5f5f5;
+  --shoji-color-accent: #4da3ff;
+  --shoji-color-backdrop: rgba(0, 0, 0, 0.92);
+  --shoji-color-toolbar-bg: rgba(20, 20, 22, 0.85);
+  --shoji-color-disabled: rgba(245, 245, 245, 0.35);
+
+  --shoji-focus-ring: 2px solid var(--shoji-color-accent);
+  --shoji-progress: var(--shoji-color-accent);
+
+  --shoji-spacing-sm: 0.5rem;
+  --shoji-spacing-md: 1rem;
+  --shoji-spacing-lg: 1.5rem;
+
+  --shoji-easing: cubic-bezier(0.4, 0, 0.2, 1);
+  --shoji-duration: 300ms;
+  /* Caps how tall the caption box can grow before it scrolls internally —
+     an unbounded caption on a long string would otherwise creep up over a
+     video slide's native control bar underneath it (bottom-left, same
+     corner), silently swallowing scrub/volume/fullscreen clicks with no
+     way to reach them. `min()` also bounds it on a short/wide dialog
+     (mobile landscape), where a `rem`-only cap could still eat most of
+     the available height. */
+  --shoji-caption-max-height: min(8rem, 30%);
+  /* Reserved space at the top of a provider embed (YouTube etc.) so its own
+     hover-revealed title bar never sits under Shoji's toolbar — matches the
+     toolbar's own rendered height (44px button + top/bottom padding).
+     Permanent, not tied to the toolbar's auto-hide state, so the video
+     never resizes as the toolbar fades in/out. HTML5 video has no top-of-
+     player UI at all, so it's untouched. */
+  --shoji-provider-video-top-inset: calc(44px + 2 * var(--shoji-spacing-sm));
+  /* DESIGN.md §2.4 — the gesture engine's own documented default easing for
+     drag-to-navigate/drag-to-close settle animations specifically (a snap
+     tuned for "released mid-motion," distinct from --shoji-easing's
+     open/close/zoom-transition curve). */
+  --shoji-momentum-easing: cubic-bezier(0.2, 0, 0, 1);
+
+  /* System-font stack: no webfont download, renders instantly, looks native
+     (San Francisco / Segoe UI / Roboto) on every platform. */
+  --shoji-font-family:
+    -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif,
+    'Apple Color Emoji', 'Segoe UI Emoji';
+}
+
+.shoji-light {
+  --shoji-color-bg: #fafafa;
+  --shoji-color-fg: #111111;
+  --shoji-color-backdrop: rgba(255, 255, 255, 0.96);
+  --shoji-color-toolbar-bg: rgba(255, 255, 255, 0.9);
+  --shoji-color-disabled: rgba(17, 17, 17, 0.35);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  :root {
+    --shoji-duration: 0ms;
+  }
+}
+
+/* Lightbox structure (DESIGN.md §2.3 slides, §2.6 dialog). Built lazily on first open(). */
+.shoji-outer {
+  display: none;
+  position: fixed;
+  inset: 0;
+  z-index: var(--shoji-z-base);
+}
+
+.shoji-outer.shoji-open {
+  display: block;
+}
+
+.shoji-backdrop {
+  position: absolute;
+  inset: 0;
+  z-index: var(--shoji-z-backdrop);
+  background: var(--shoji-color-backdrop);
+}
+
+.shoji-dialog {
+  position: relative;
+  z-index: var(--shoji-z-slides);
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+  color: var(--shoji-color-fg);
+  font-family: var(--shoji-font-family);
+  outline: none;
+  /* DESIGN.md §2.4 — the gesture engine owns horizontal/vertical drag on
+     this element; without this, touch browsers intercept the same gesture
+     for native scroll/pull-to-refresh/back-navigation before JS ever sees
+     enough movement to lock a direction. Buttons/video inside remain
+     interactive regardless (this is about implicit browser gesture
+     handling, not pointer-events). */
+  touch-action: none;
+}
+
+.shoji-toolbar {
+  position: absolute;
+  inset: 0 0 auto 0;
+  z-index: var(--shoji-z-toolbar);
+  display: flex;
+  justify-content: space-between;
+  padding: var(--shoji-spacing-sm);
+  pointer-events: none;
+  /* Reported from real usage: the Zoom plugin's frequent scale() updates on
+     the photo (a sibling, not a descendant) could show as GPU tile-seam
+     artifacts (thin lines) through the toolbar's own semi-transparent,
+     border-radius buttons — the same class of rendering quirk already noted
+     for progressive image decode. Promoting the toolbar to its own stable
+     compositing layer, decoupled from the photo's repaints, avoids it. */
+  will-change: transform;
+}
+
+/* DESIGN.md §3 — ctx.ui.toolbar(slot, ...) inserts plugin buttons into these;
+   pointer-events re-enabled per-slot (not per-button) so gaps between slots
+   stay click-through even once a slot has content. `flex-wrap: wrap` (not
+   `overflow-x: auto`) is deliberate: several plugins loaded together on a
+   narrow/mobile viewport can add up to more 44px buttons than the width
+   allows (CLAUDE.md's own touch-target size, non-negotiable), and this
+   project treats horizontal scroll as something to design around, not
+   reach for (see the layout plugin's masonry `orientation: 'horizontal'`,
+   which was rebuilt specifically to avoid it) — wrapping to a second row
+   keeps every button reachable by a tap with no sideways scroll gesture
+   anywhere in the lightbox chrome either. */
+.shoji-toolbar-slot {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--shoji-spacing-sm);
+  pointer-events: auto;
+  max-width: 45%;
+}
+
+.shoji-toolbar-left {
+  justify-content: flex-start;
+}
+
+.shoji-toolbar-right {
+  justify-content: flex-end;
+}
+
+.shoji-close,
+.shoji-nav,
+.shoji-toolbar-button {
+  appearance: none;
+  border: none;
+  padding: 0;
+  width: 44px;
+  height: 44px;
+  border-radius: 50%;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: rgba(0, 0, 0, 0.4);
+  color: var(--shoji-color-fg);
+  cursor: pointer;
+}
+
+.shoji-close:hover,
+.shoji-nav:hover,
+.shoji-toolbar-button:hover {
+  background: rgba(0, 0, 0, 0.6);
+}
+
+.shoji-close:focus-visible,
+.shoji-nav:focus-visible,
+.shoji-toolbar-button:focus-visible {
+  outline: var(--shoji-focus-ring);
+  outline-offset: 2px;
+}
+
+.shoji-nav {
+  position: absolute;
+  top: 50%;
+  transform: translateY(-50%);
+  z-index: var(--shoji-z-toolbar);
+}
+
+.shoji-nav-prev {
+  left: var(--shoji-spacing-md);
+}
+
+.shoji-nav-next {
+  right: var(--shoji-spacing-md);
+}
+
+.shoji-nav:disabled {
+  opacity: 0.3;
+  cursor: default;
+  pointer-events: none;
+}
+
+.shoji-close[hidden],
+.shoji-nav[hidden],
+.shoji-toolbar-button[hidden] {
+  display: none;
+}
+
+/* DESIGN.md §2.3 — while the active slide's own content is still loading,
+   feature/plugin toolbar buttons (zoom, rotate, fullscreen, autoplay, any
+   custom plugin's own button) dim and stop responding, since they'd
+   otherwise act on content about to be replaced. Deliberately scoped to
+   `.shoji-toolbar-button` only — `.shoji-close`/`.shoji-nav` are different
+   classes, so closing and navigating are never blocked by a slow image.
+   `pointer-events: none` here is the mouse half; Gallery.ts's matching
+   `tabIndex = -1` is the keyboard half (this alone wouldn't stop
+   Enter/Space activating an already-focused button). */
+.shoji-outer.shoji-slide-loading .shoji-toolbar-button {
+  opacity: 0.3;
+  cursor: default;
+  pointer-events: none;
+}
+
+.shoji-slides {
+  position: relative;
+  flex: 1;
+  overflow: hidden;
+}
+
+.shoji-slide {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  /* transform (translateX per pool offset) is set inline by SlideManager */
+}
+
+.shoji-slide-media {
+  /* Definite size (not max-width/max-height alone) so the img's own
+     percentage-based max-width/max-height below has something concrete to
+     resolve against — otherwise it sizes to the image's natural dimensions
+     instead of being contained, and object-fit: contain never engages. */
+  width: 100%;
+  height: 100%;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  /* Anchors .shoji-video-play-overlay's absolute positioning to this box
+     specifically, not implicitly to whichever positioned ancestor happens
+     to be next up (currently .shoji-slide, coincidentally the same size —
+     explicit here so that stays true even if that ever changes). */
+  position: relative;
+}
+
+.shoji-slide-img,
+.shoji-slide-video {
+  display: block;
+  max-width: 100%;
+  max-height: 100%;
+  object-fit: contain;
+}
+
+/* max-width/max-height above only ever *cap* size — a real photo is normally
+   bigger than the slide area, so that's correct. A low-res open() placeholder
+   (§2.3) is the opposite case: deliberately small, so it needs to be forced
+   up to fill the frame (blurry, on purpose) instead of rendering at its own
+   tiny natural size. object-fit: contain (inherited above) still letterboxes
+   it within that forced box, just per the thumbnail's own aspect ratio. */
+.shoji-slide-open-placeholder {
+  width: 100%;
+  height: 100%;
+}
+
+/* DESIGN.md §4-video — a provider's embed (an <iframe>, typically) has no
+   natural size Shoji can measure the way a decoded image/video does, so
+   this just fills whatever box it's given; supply item.width/height for a
+   correctly-shaped box (applyAspect() sets aspect-ratio on the slide-media
+   container itself from those), same as any other slide. */
+.shoji-slide-provider-video {
+  width: 100%;
+  height: 100%;
+  box-sizing: border-box;
+  padding-top: var(--shoji-provider-video-top-inset);
+}
+
+.shoji-slide-provider-video[hidden] {
+  display: none;
+}
+
+.shoji-slide-provider-video iframe {
+  display: block;
+  width: 100%;
+  height: 100%;
+  border: 0;
+}
+
+/* A paused video's own play affordance — native browser styling for this
+   varies too much to rely on alone (some show a big centered play icon,
+   some don't). Faint/translucent, same visual language as the toolbar's
+   own round icon buttons, just bigger — a primary, hard-to-miss affordance,
+   not a small chrome control. Deliberately not gated by any GalleryOptions
+   flag (purely presentational — hiding it changes nothing functionally,
+   the video is still clickable either way); a host not wanting it just
+   overrides this selector in their own CSS. */
+.shoji-video-play-overlay {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  transform: translate(-50%, -50%);
+  width: var(--shoji-video-overlay-size, 64px);
+  height: var(--shoji-video-overlay-size, 64px);
+  border-radius: 50%;
+  border: none;
+  padding: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: var(--shoji-video-overlay-bg, rgba(0, 0, 0, 0.4));
+  color: var(--shoji-video-overlay-color, var(--shoji-color-fg));
+  cursor: pointer;
+}
+
+.shoji-video-play-overlay[hidden] {
+  display: none;
+}
+
+/* DESIGN.md §2.5 — the temporary clone SlideTransition animates the
+   outgoing slide's content out on. Sits above the normal (unpositioned
+   z-index) pool slots by DOM order alone, but z-index is set explicitly
+   here rather than relied on implicitly, matching how every other overlay
+   layer in this file states its stacking intent up front. Not interactive
+   (it's a decorative clone mid-removal) and never receives its own size —
+   it fills `.shoji-slides` exactly like the real `.shoji-slide` it's a
+   snapshot of, so the cloned `.shoji-slide-media` inside it (already
+   `width/height: 100%`) lines up pixel-for-pixel with no extra CSS needed. */
+.shoji-slide-ghost {
+  position: absolute;
+  inset: 0;
+  z-index: 1;
+  pointer-events: none;
+}
+
+.shoji-slide-placeholder {
+  color: var(--shoji-color-disabled);
+}
+
+/* DESIGN.md §2.3 — shown in place of a slide's content while it's still
+   decoding/loading (outside the `preload` window, where nothing was ready
+   ahead of time). CSS-only rotation (no JS-driven layout, per CLAUDE.md);
+   disabled under prefers-reduced-motion the same as every other animation
+   here, rather than left spinning regardless. */
+.shoji-slide-spinner {
+  width: var(--shoji-spinner-size, 40px);
+  height: var(--shoji-spinner-size, 40px);
+  border-radius: 50%;
+  border: var(--shoji-spinner-thickness, 3px) solid var(--shoji-color-disabled);
+  border-top-color: var(--shoji-color-accent);
+  animation: shoji-spin 0.8s linear infinite;
+}
+
+@keyframes shoji-spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .shoji-slide-spinner {
+    animation: none;
+  }
+}
+
+/* A normal flex item within .shoji-toolbar-left (not independently
+   positioned) — .shoji-slides still gets the full dialog height either way,
+   no reserved gutter at top or bottom, since the toolbar itself overlays the
+   slides rather than pushing them down. Flowing alongside whatever else is
+   in that slot (e.g. a plugin's ctx.ui.toolbar('left', ...) button) keeps it
+   from overlapping and stealing clicks the way independent absolute
+   positioning did. */
+.shoji-counter {
+  padding: 0.25rem 0.6rem;
+  border-radius: 999px;
+  background: rgba(0, 0, 0, 0.4);
+  font-size: 0.875rem;
+  white-space: nowrap;
+}
+
+.shoji-counter[hidden] {
+  display: none;
+}
+
+.shoji-caption {
+  position: absolute;
+  bottom: var(--shoji-spacing-md);
+  left: var(--shoji-spacing-md);
+  z-index: var(--shoji-z-toolbar);
+  width: fit-content;
+  max-width: calc(100% - 2 * var(--shoji-spacing-md));
+  max-height: var(--shoji-caption-max-height);
+  overflow-y: auto;
+  overscroll-behavior: contain;
+  padding: var(--shoji-spacing-sm) var(--shoji-spacing-md);
+  border-radius: 8px;
+  background: var(--shoji-color-toolbar-bg);
+  text-align: left;
+}
+
+/* A real bug: height-capping the caption (above) still isn't enough on its
+   own — a video that fills most of the dialog leaves little to no
+   letterboxing gap, so even a short caption's opaque background can land
+   directly on the native control bar underneath it (same corner). Letting
+   clicks pass straight through the caption on a video slide (Gallery.ts
+   toggles this class from `item.video`, HTML5 or a provider like YouTube
+   alike) is what actually guarantees the controls stay reachable, not just
+   "usually clear of them." Re-enabled on any real child element so a rich
+   HTML caption's own links/buttons (DESIGN.md §2.1) stay clickable — only
+   a plain-string caption (no element children at all) ever fully passes
+   through. Photo slides are untouched: nothing below them needs protecting,
+   so the caption keeps its normal scrollable/selectable behavior there. */
+.shoji-caption--video {
+  pointer-events: none;
+}
+
+.shoji-caption--video > * {
+  pointer-events: auto;
+}
+
+.shoji-caption[hidden] {
+  display: none;
+}
+
+/* DESIGN.md §2.8 — idle auto-hide. Opacity only, never display:none, never
+   removed from the tab order: a hidden-but-focused control stays interactive,
+   just visually faded (see Gallery's isControlFocused() guard). */
+.shoji-toolbar,
+.shoji-nav,
+.shoji-counter,
+.shoji-caption {
+  transition: opacity var(--shoji-duration) var(--shoji-easing);
+}
+
+.shoji-controls-hidden .shoji-toolbar,
+.shoji-controls-hidden .shoji-nav,
+.shoji-controls-hidden .shoji-counter,
+.shoji-controls-hidden .shoji-caption {
+  opacity: 0;
+  pointer-events: none;
+}
+
+/* !important: wins over any plugin's own cursor styling (e.g. zoom.css's
+   zoom-in/grab affordances) without core needing to know that plugin's
+   selectors — the hidden state means nothing should suggest interactivity. */
+.shoji-controls-hidden,
+.shoji-controls-hidden * {
+  cursor: none !important;
+}
+
+.shoji-live-region {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  overflow: hidden;
+  clip: rect(0 0 0 0);
+  white-space: nowrap;
+}