npm - @michaelyagi/shoji - Versions diffs - 0.1.0-beta.2 → 0.1.0-beta.5 - Mend

@michaelyagi/shoji 0.1.0-beta.2 → 0.1.0-beta.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (63) hide show

package/dist/core/shoji-core.css +833 -0
package/dist/core/shoji-core.js +3296 -0
package/dist/core/shoji-core.js.map +1 -0
package/dist/core/shoji-core.min.css +1 -0
package/dist/core/shoji-core.min.js +2 -0
package/dist/core/shoji-core.min.js.map +1 -0
package/dist/esm/core/Gallery.d.ts +2 -0
package/dist/esm/core/index.js +94 -1
package/dist/esm/core/index.js.map +1 -1
package/dist/esm/index.css +86 -820
package/dist/esm/index.js +1 -1
package/dist/esm/index2.css +819 -44
package/dist/esm/index3.css +47 -159
package/dist/esm/index4.css +169 -26
package/dist/esm/index5.css +27 -0
package/dist/esm/plugins/activeThumbnail/index.d.ts +7 -1
package/dist/esm/plugins/activeThumbnail/index.js +55 -16
package/dist/esm/plugins/activeThumbnail/index.js.map +1 -1
package/dist/plugins/activeThumbnail.css +99 -0
package/dist/plugins/activeThumbnail.js +116 -0
package/dist/plugins/activeThumbnail.js.map +1 -0
package/dist/plugins/activeThumbnail.min.css +1 -0
package/dist/plugins/activeThumbnail.min.js +2 -0
package/dist/plugins/activeThumbnail.min.js.map +1 -0
package/dist/plugins/autoplay.css +58 -0
package/dist/plugins/autoplay.js +288 -0
package/dist/plugins/autoplay.js.map +1 -0
package/dist/plugins/autoplay.min.css +1 -0
package/dist/plugins/autoplay.min.js +2 -0
package/dist/plugins/autoplay.min.js.map +1 -0
package/dist/plugins/fullscreen.js +80 -0
package/dist/plugins/fullscreen.js.map +1 -0
package/dist/plugins/fullscreen.min.js +2 -0
package/dist/plugins/fullscreen.min.js.map +1 -0
package/dist/plugins/layout.css +170 -0
package/dist/plugins/layout.js +767 -0
package/dist/plugins/layout.js.map +1 -0
package/dist/plugins/layout.min.css +1 -0
package/dist/plugins/layout.min.js +2 -0
package/dist/plugins/layout.min.js.map +1 -0
package/dist/plugins/rotateFlip.js +196 -0
package/dist/plugins/rotateFlip.js.map +1 -0
package/dist/plugins/rotateFlip.min.js +2 -0
package/dist/plugins/rotateFlip.min.js.map +1 -0
package/dist/plugins/video.js +227 -0
package/dist/plugins/video.js.map +1 -0
package/dist/plugins/video.min.js +2 -0
package/dist/plugins/video.min.js.map +1 -0
package/dist/plugins/zoom.css +27 -0
package/dist/plugins/zoom.js +450 -0
package/dist/plugins/zoom.js.map +1 -0
package/dist/plugins/zoom.min.css +1 -0
package/dist/plugins/zoom.min.js +2 -0
package/dist/plugins/zoom.min.js.map +1 -0
package/dist/shoji.css +99 -0
package/dist/shoji.js +60 -16
package/dist/shoji.js.map +1 -1
package/dist/shoji.min.css +1 -1
package/dist/shoji.min.js +1 -1
package/dist/shoji.min.js.map +1 -1
package/package.json +1 -1
package/dist/esm/bodyScrollLock-CC5PJxJp.js +0 -96
package/dist/esm/bodyScrollLock-CC5PJxJp.js.map +0 -1

package/dist/core/shoji-core.css ADDED Viewed

@@ -0,0 +1,833 @@
+/**
+ * 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.
+ *
+ * `.shoji-outer` always mounts directly on `document.body` (Gallery.ts),
+ * never nested inside the host's own gallery container — so `.shoji-light`
+ * (or any `--shoji-*` override) must be applied to `<body>`/`<html>`/another
+ * real ancestor of the mount point, not the gallery container itself, or it
+ * silently does nothing (custom properties only inherit down real DOM
+ * ancestry).
+ */
+: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-z-caption-modal: 50; /* DESIGN.md §2.3a — above everything else in the dialog, a nested dialog of its own */
+  --shoji-color-bg: #0b0b0d;
+  --shoji-color-fg: #f5f5f5;
+  --shoji-color-accent: #4da3ff;
+  /* Fully opaque hue — the backdrop's actual on-screen transparency is
+     --shoji-backdrop-opacity below, a real 0-1 alpha, not baked in here.
+     A custom theme is still free to use an rgba()/gradient value instead;
+     --shoji-backdrop-opacity then composites on top of that value's own
+     alpha (CSS opacity multiplies), same as it always has. */
+  --shoji-color-backdrop: #000000;
+  --shoji-color-toolbar-bg: rgba(20, 20, 22, 0.85);
+  --shoji-color-disabled: rgba(245, 245, 245, 0.35);
+  /* Real alpha: 1 = fully opaque, 0 = fully transparent. Settable directly
+     via GalleryOptions.backdropOpacity (Gallery.ts) without needing to know
+     or override the full color value. */
+  --shoji-backdrop-opacity: 1;
+  --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;
+  /* The toolbar's own rendered height (44px button + top/bottom padding) —
+     defined before the caption sizing below since it now derives from
+     this. Also reserves space at the top of a provider embed (YouTube
+     etc.) so its own hover-revealed title bar never sits under Shoji's
+     toolbar; permanent there, 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 by that use. */
+  --shoji-provider-video-top-inset: calc(44px + 2 * var(--shoji-spacing-sm));
+  /* DESIGN.md §2.4/§4.3 — a native <video controls>'s own scrub-bar/tap-
+     region is browser-rendered chrome, not real DOM Shoji can measure or
+     exclude by selector; approximated as a fixed bottom margin instead,
+     read by GestureController.ts's isInVideoControlsMargin(). 56px covers
+     the tallest common native controls bar (mobile Safari) with a little
+     headroom; a host that knows its target browsers render a shorter one
+     can safely set this lower. Swipe-to-navigate/drag-to-close only ever
+     reach the video body above this margin — never guaranteed to line up
+     with the real control bar pixel-for-pixel, just a reasonable default. */
+  --shoji-video-gesture-margin: 56px;
+  /* Caps how wide the caption box can grow before wrapping — `width:
+     fit-content` alone let a long caption wrap out to the dialog's full
+     width (only actually bounded by the padding subtracted below),
+     reading as a bar spanning the screen rather than a caption sized to
+     its own content. Desktop-only (see the media query below) — on a
+     narrow/mobile viewport the caption still spans (almost) the full
+     width, unchanged from before. */
+  --shoji-caption-max-width: calc(100% - 2 * var(--shoji-spacing-md));
+  /* DESIGN.md §2.3a — the collapsed default height, applied on top of
+     --shoji-caption-max-height (which only ever guards against reaching
+     the toolbar above, not the vertically-centered nav arrows sharing the
+     caption's own left edge). Requested directly, after a first version
+     that always collapsed to one line regardless of how much real room
+     existed: grow as tall as it can while staying clear of the nav
+     arrow's own footprint — `50%` (the dialog's own height, the
+     containing block `.shoji-caption`'s percentages resolve against) is
+     exactly where `.shoji-nav`'s own `top: 50%` sits, so `50%` minus half
+     its 44px height minus the caption's own bottom inset minus a small
+     breathing gap is the real ceiling, not an arbitrary line count. Pure
+     geometry — the arrow is always dead-center regardless of viewport, no
+     measurement needed the way the toolbar's own wrapping needs
+     `--shoji-toolbar-height` (Gallery.ts's ResizeObserver) to answer.
+     Floored (`max()`) at roughly one line + padding so a pathologically
+     short dialog can't collapse this to zero — the arrow may end up
+     slightly covered in that extreme case, but showing no caption at all
+     would be worse. A caption tall enough to still clip past all of this
+     gets `.shoji-caption--truncated` (Gallery.ts) and its own modal to
+     read the rest. */
+  --shoji-caption-collapsed-max-height: max(
+    calc(50% - 22px - var(--shoji-spacing-md) - var(--shoji-spacing-sm)),
+    calc(1.6em + 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: #ffffff;
+  --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;
+  }
+}
+/* Narrows the caption from its mobile default (spans ~the full dialog
+   width) down to roughly a quarter of the viewport, floored at 14rem so
+   it stays legible in a smaller desktop window — reported from real
+   usage as an aesthetic complaint (a long caption reading as a bar
+   spanning the screen), desktop-only by request: a narrow/mobile
+   viewport keeps the original near-full-width behavior unchanged, since
+   there's much less width to spare there in the first place. 768px is an
+   ordinary phone/tablet breakpoint, not tied to any other Shoji default —
+   there's no matching JS-side concept of "mobile" this needs to stay
+   consistent with. */
+@media (min-width: 768px) {
+  :root {
+    --shoji-caption-max-width: min(calc(100% - 2 * var(--shoji-spacing-md)), max(24vw, 14rem));
+  }
+}
+/* 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);
+  opacity: var(--shoji-backdrop-opacity);
+  /* A real bug: without this, the backdrop had no transition of its own at
+     all — .shoji-outer (backdrop included) goes display:none in one
+     instant step once the zoom-out settles, so the still-fully-dark
+     backdrop behind the shrinking photo would snap straight to fully
+     visible-page-behind-it in a single frame, reading as a flash right as
+     the close finishes. Gallery.ts's beginClose() now starts this fade at
+     the same moment as the zoom-out and the controls fade, so all three
+     finish together instead of the backdrop cutting out abruptly at the end. */
+  transition: opacity var(--shoji-duration) var(--shoji-easing);
+}
+.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;
+  /* DESIGN.md §2.4 — a real bug, reported from real usage: a drag over the
+     photo/video (navigate/close) also started the browser's own native
+     text/image selection — visible as the image or video highlighting blue
+     mid-drag. `GestureEngine.ts` only calls `preventDefault()` on
+     `pointermove` once a direction has locked past `lockThreshold`
+     (horizontal) or not at all (vertical, DESIGN.md's own gesture-engine
+     notes above) — by then, or for a vertical drag, ever, the browser's own
+     selection-start heuristic has already had its chance. `user-select:
+     none` stops it at the source instead of racing preventDefault's own
+     timing. `.shoji-caption` below re-enables it — selecting caption text
+     is a deliberate, still-supported gesture-exclusion (this section,
+     "ignore()"), not something this should also block. */
+  user-select: none;
+  /* Caps how tall the caption box (a descendant, DESIGN.md §2.3a) can grow
+     before it scrolls internally — grows naturally with its content up to
+     that point, no cap kicking in early. The real ceiling is this
+     element's own height (100%) minus the toolbar's footprint at the top
+     minus the caption's own `bottom` offset minus a small breathing gap —
+     i.e. "as tall as it can get without reaching up under the toolbar,"
+     not an arbitrary fixed figure. Declared *here*, not `:root`, on
+     purpose — a real bug caught testing this: a custom property's nested
+     `var()` references substitute at the element where that property is
+     declared, not where a descendant later uses it, so defining this same
+     formula at `:root` baked in whatever `--shoji-toolbar-height`
+     happened to resolve to *there* (never set, always the fallback)
+     regardless of the real, per-instance value Gallery.ts's
+     ResizeObserver sets right on this same `.shoji-dialog` element below.
+     Declaring it here instead means the substitution happens where that
+     inline-set value is actually visible. */
+  --shoji-caption-max-height: calc(
+    100% - var(--shoji-toolbar-height, var(--shoji-provider-video-top-inset)) -
+      var(--shoji-spacing-md) - var(--shoji-spacing-sm)
+  );
+}
+.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.
+   max-width was 45% until a real bug, reported from real usage: the
+   toolbar-overflow popover (DESIGN.md §3.1a) collapses plugin buttons down
+   to `minPinnedToolbarButtons` (default 2), but 2 pinned + close + the
+   caret itself (4 icons, ~200px at the 44px touch-target size plus gaps)
+   already exceeds 45% of a common ~380px mobile width — so this slot fell
+   back to wrapping to a second row (pushing close onto its own line) even
+   though the *whole point* of the popover is that a bounded, small icon
+   count should now reliably fit in one row. Raised to 60% — comfortably
+   covers the default floor plus close/caret at typical mobile widths,
+   confirmed directly — while still leaving `.shoji-toolbar-left`'s own
+   counter room; a host who raises `minPinnedToolbarButtons` well past the
+   default on a narrow viewport can still hit this same wrap, by design
+   (DESIGN.md §3.1a: never collapsing below that floor, even if it still
+   leaves a slot wrapped, is the documented tradeoff). */
+.shoji-toolbar-slot {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--shoji-spacing-sm);
+  pointer-events: auto;
+}
+.shoji-toolbar-left {
+  justify-content: flex-start;
+}
+.shoji-toolbar-right {
+  justify-content: flex-end;
+}
+.shoji-close,
+.shoji-nav,
+.shoji-toolbar-button,
+.shoji-caption-modal-close {
+  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,
+.shoji-caption-modal-close:hover {
+  background: rgba(0, 0, 0, 0.6);
+}
+.shoji-close:focus-visible,
+.shoji-nav:focus-visible,
+.shoji-toolbar-button:focus-visible,
+.shoji-caption-modal-close: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;
+  /* Positioning context for this box's own absolutely-positioned children
+     (the spinner, the open placeholder) specifically, not implicitly
+     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;
+  /* DESIGN.md §4-video — a provider video's real shape (YouTube/Vimeo/
+     html5), as a plain number SlideManager sets from item.width/item.height
+     (`applyAspect()`); `calc(16 / 9)` here is only the fallback for an item
+     that never declares a size, kept exact via calc() rather than a rounded
+     decimal. `.shoji-slide-provider-poster` below reads this directly.
+     `.shoji-slide-provider-video > iframe`/`.shoji-video-mount` also read it,
+     through their own nearer `container-type: size` context (still on
+     `.shoji-slide-provider-video` itself, unchanged) — declared again here
+     too only so a poster, `.shoji-slide-provider-video`'s own *sibling*
+     rather than a descendant of it, has a container-type ancestor to
+     resolve cqw/cqh against at all. */
+  --shoji-provider-video-aspect: calc(16 / 9);
+  container-type: size;
+}
+.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%;
+}
+/* A provider video's poster (§4.3, `item.poster`/a renderer's own fallback)
+   is the same "usually a small thumbnail file, needs to be forced up to
+   fill the frame" case as the open placeholder above — a real bug, a small
+   poster rendering as a postage-stamp-sized image floating in the slide
+   instead of filling it. Sized to the *video's* real shape
+   (`--shoji-provider-video-aspect`, `.shoji-slide-media` above) via the same
+   cqw/cqh contain-within-either-axis formula the real embed below uses, not
+   plain width/height: 100% — so the poster occupies exactly the box the
+   embed will occupy once it swaps in, instead of the two visibly jumping
+   between a video-shaped box and a dialog-shaped one. */
+.shoji-slide-provider-poster {
+  width: min(100cqw, calc(100cqh * var(--shoji-provider-video-aspect)));
+  height: min(100cqh, calc(100cqw / var(--shoji-provider-video-aspect)));
+}
+/* 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. A real
+   bug, reported from real usage, found in two parts:
+   1. Stretching the embed to fill this box regardless of the video's own
+      aspect ratio pushed the bottom of the video (and a provider's own
+      controls, always along that edge) below the visible area whenever the
+      box wasn't already the same shape as the video.
+   2. Fixing that by fitting to the box's actual shape instead exposed a
+      second issue: neither YouTube's nor Vimeo's own player page renders
+      with a background matching Shoji's theme in the letterboxed gap
+      *inside* the iframe (both showed white) — a color this page has no
+      way to reach or override, since that content is cross-origin.
+   Assumes 16:9 (overwhelmingly the common case for both providers, and
+   exactly correct for the video this was diagnosed against) and *contains*
+   within whatever box is actually available — the same shape object-fit
+   already gives an <img>/<video> above, achieved differently here since
+   object-fit doesn't apply to an iframe (or the wrapper div Vimeo's own
+   SDK builds one inside) — so any remaining gap is outside the iframe
+   instead of inside it, showing Shoji's own dark backdrop through this
+   element's own transparent background rather than the provider's white. */
+.shoji-slide-provider-video {
+  /* `position: absolute; inset: 0` instead of sizing this as a centered flex
+     item: a real bug, reported from real usage, traced to this box's parent
+     (`.shoji-slide-media`, `justify-content: center`) miscentering it once
+     `container-type: size` (below) is also in play — confirmed directly via
+     `getBoundingClientRect()` on the real reported case, rendering the box
+     shifted half its own width off-screen. Taking it out of flex flow
+     entirely sidesteps the centering pass for this element altogether: it
+     fills `.shoji-slide-media` directly (already `position: relative`), no
+     distribution/centering math involved. `.shoji-slide-media`'s own
+     `justify-content: center` is untouched — still needed for photo/HTML5-
+     video slides, where content can be smaller than the box. */
+  position: absolute;
+  inset: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  box-sizing: border-box;
+  padding-top: var(--shoji-provider-video-top-inset);
+  container-type: size;
+}
+.shoji-slide-provider-video[hidden] {
+  display: none;
+}
+/* `.shoji-video-mount` — src/plugins/video/vimeo.ts's own wrapper div,
+   which its SDK would otherwise size itself (a small fixed default
+   normally, or its own `responsive: true` option's aspect-ratio-from-width-
+   alone computation, ignoring how much height is actually available either
+   way) — `!important` discards whatever it tries to set inline. The direct
+   `> iframe` case is YouTube, which has no such wrapper at all.
+   `min(100cqw, 100cqh * ratio)`/`min(100cqh, 100cqw / ratio)` is the
+   contain-within-either-axis formula `object-fit: contain` gives an
+   <img>/<video> natively — plain `aspect-ratio` alone can't do this for a
+   non-replaced element like a div/iframe: it only ever derives *one*
+   dimension from the other, so whichever of width/height stays a fixed
+   `100%` never actually shrinks even once the derived dimension gets
+   capped by `max-width`/`max-height`, silently distorting the ratio in
+   whichever direction wasn't the binding constraint. Confirmed directly at
+   both a wide-short viewport (height the binding constraint) and a
+   narrow-tall one (width the binding constraint) — container query units
+   are what actually solve both at once, not `aspect-ratio` by itself.
+   `--shoji-provider-video-aspect` (`.shoji-slide-media` above) is the
+   item's own real `width`/`height` ratio when known — a real bug/gap this
+   replaces a hardcoded `16/9` to fix: every provider video rendered as if
+   it were 16:9 regardless of its declared shape, YouTube/Vimeo/html5 alike
+   (html5's own `<video>` element is fixed the same way, directly, in
+   `SlideManager.ts`'s `renderVideo()` — it doesn't go through this
+   container-query-based sizing at all, having a real intrinsic size of its
+   own once it loads). */
+.shoji-slide-provider-video > iframe,
+.shoji-video-mount {
+  width: min(100cqw, calc(100cqh * var(--shoji-provider-video-aspect))) !important;
+  height: min(100cqh, calc(100cqw / var(--shoji-provider-video-aspect))) !important;
+  margin: 0 !important;
+  padding: 0 !important;
+}
+.shoji-slide-provider-video iframe {
+  display: block;
+  border: 0;
+}
+/* Once `.shoji-video-mount` above is already correctly contain-fitted, its
+   own iframe just needs to fill it completely — no `aspect-ratio` of its
+   own to fight the wrapper's. Same `!important`/static-not-absolute
+   reasoning as `.shoji-video-mount` — Vimeo's SDK may set its own inline
+   sizing/position on the iframe too, not just on the wrapper. */
+.shoji-video-mount iframe {
+  position: static !important;
+  width: 100% !important;
+  height: 100% !important;
+}
+/* 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);
+  /* Re-enables text selection `.shoji-dialog`'s own user-select: none
+     (above) turns off broadly — caption text staying selectable is a
+     deliberate, existing feature (this section's "ignore()"), unaffected
+     by that fix for the photo/video's own native-selection bug. */
+  user-select: text;
+  width: fit-content;
+  max-width: var(--shoji-caption-max-width);
+  max-height: min(var(--shoji-caption-max-height), var(--shoji-caption-collapsed-max-height));
+  /* DESIGN.md §2.3a — a clean clip, not a scrollbar: the collapsed cap is
+     now small (~1 line) by design, so almost any real caption exceeds it;
+     a visible scrollbar on that tiny a box would look broken. Reading the
+     rest is what `.shoji-caption-modal` (Gallery.ts) is for instead — its
+     own content area is where `overflow-y: auto` still applies. */
+  overflow: hidden;
+  padding: var(--shoji-spacing-sm) var(--shoji-spacing-md);
+  /* A real bug, caught by an e2e regression test: without this, max-height
+     only constrains the content box — the element's own padding (16px,
+     top+bottom) then renders on top of that, eating into the breathing
+     gap the height cap's own calc (--shoji-caption-max-height, above)
+     already budgeted for, enough to actually overlap the toolbar instead
+     of stopping just short of it. */
+  box-sizing: border-box;
+  border-radius: 8px;
+  background: var(--shoji-color-toolbar-bg);
+  text-align: left;
+  /* A real bug, caught testing the truncated-caption line-clamp
+     (DESIGN.md §2.3a): left unset, `line-height` computes to the literal
+     keyword "normal" rather than a resolved px value, so
+     `updateCaptionTruncation()`'s own line-height measurement (Gallery.ts)
+     could only ever approximate it — close enough to be off by a
+     fractional line, letting one extra partial line bleed in below the
+     clamp's own ellipsis instead of cutting cleanly. An explicit value
+     here makes that measurement exact instead of estimated. */
+  line-height: 1.4;
+}
+/* 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;
+}
+/* DESIGN.md §2.3a — only ever added once content genuinely overflows the
+   collapsed clip (Gallery.ts measures scrollHeight vs. clientHeight), so a
+   caption that already fits never looks or behaves clickable. On a video
+   slide `.shoji-caption--video`'s own pointer-events: none (above) already
+   makes this a no-op for pointer input there, on purpose — reaching the
+   native video controls underneath still wins; a keyboard user can still
+   Tab to it and open the modal regardless, since that's not competing for
+   the same physical space a click would be. */
+.shoji-caption--truncated {
+  cursor: pointer;
+}
+/* A visible cue, not just a silent clip. `-webkit-line-clamp` (the
+   standard tool for this) was tried first but didn't reliably stop at a
+   clean line boundary here — regardless of how precisely the line count
+   fed into it was computed, a partial extra line kept bleeding through
+   below its own ellipsis. Gallery.ts's updateCaptionTruncation() instead
+   snaps `max-height` itself down to an exact whole-line multiple, so a
+   plain clip can never land mid-line — this "…" chip is what actually
+   supplies the visible cue for that, pinned over the last visible line's
+   corner, background-matched so it masks whatever text it sits on. */
+.shoji-caption--truncated::after {
+  content: '…';
+  position: absolute;
+  right: var(--shoji-spacing-sm);
+  bottom: var(--shoji-spacing-sm);
+  padding-left: 0.5em;
+  background: var(--shoji-color-toolbar-bg);
+}
+/* DESIGN.md §2.3a — the truncated caption's own expanded view. A real
+   backdrop over the whole dialog, not an in-place taller caption: growing
+   the caption itself tall enough to show everything would risk covering
+   the nav arrows again, exactly the bug this feature exists to avoid. */
+.shoji-caption-modal {
+  position: absolute;
+  inset: 0;
+  z-index: var(--shoji-z-caption-modal);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: var(--shoji-spacing-lg);
+  background: rgba(0, 0, 0, 0.6);
+}
+.shoji-caption-modal[hidden] {
+  display: none;
+}
+.shoji-caption-modal-panel {
+  position: relative;
+  max-width: 32rem;
+  max-height: 100%;
+  overflow-y: auto;
+  overscroll-behavior: contain;
+  padding: var(--shoji-spacing-lg);
+  padding-inline-end: calc(44px + var(--shoji-spacing-lg));
+  border-radius: 8px;
+  background: var(--shoji-color-bg);
+  color: var(--shoji-color-fg);
+}
+.shoji-caption-modal-close {
+  position: absolute;
+  top: var(--shoji-spacing-sm);
+  right: var(--shoji-spacing-sm);
+}
+.shoji-caption[hidden] {
+  display: none;
+}
+/* DESIGN.md §3.1a — hidden unless the toolbar actually overflows
+   (Gallery.ts's measureToolbarOverflow() reveals it), so it never adds a
+   permanent extra control to a toolbar that never needed one. */
+.shoji-toolbar-overflow[hidden] {
+  display: none;
+}
+/* 3 columns, wrapping to as many rows as needed — requested directly.
+   Width is content-driven (3 * 44px + 2 gaps + padding), not clamped to a
+   fraction of the dialog, since it never grows past that regardless of how
+   many buttons collapse into it. Columns are 44px with `--shoji-spacing-sm`
+   gaps — deliberately the same pitch as a toolbar button's own size and
+   `.shoji-toolbar-slot`'s own gap, so the popover's icon columns actually
+   line up with the toolbar row's icons above them.
+   `right` here is only a pre-open fallback — Gallery.ts's
+   `positionToolbarOverflowPanel()` sets it inline every time the panel
+   opens, anchored to the caret's own live position (which shifts with
+   `minPinnedToolbarButtons` and viewport width) rather than this fixed
+   offset from the dialog's edge, which otherwise lined up under
+   `closeButton` instead of the caret that actually opens it. */
+.shoji-toolbar-overflow-panel {
+  position: absolute;
+  top: var(--shoji-toolbar-height, 56px);
+  right: var(--shoji-spacing-md);
+  z-index: var(--shoji-z-toast);
+  display: grid;
+  grid-template-columns: repeat(3, 44px);
+  gap: var(--shoji-spacing-sm);
+  max-height: calc(100% - var(--shoji-toolbar-height, 56px) - var(--shoji-spacing-md));
+  overflow-y: auto;
+  padding: var(--shoji-spacing-sm);
+  border-radius: 8px;
+  background: var(--shoji-color-bg);
+  color: var(--shoji-color-fg);
+}
+.shoji-toolbar-overflow-panel[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;
+}
+/* autoHideDelay: 0 (Gallery.ts) — Shoji's own controls stay permanently
+   invisible, but the cursor itself should behave normally, not force-hidden
+   along with them. Higher specificity than the rule above (both compound
+   selectors carry two classes/one-class-plus-descendant vs. one), so this
+   wins despite both using !important. */
+.shoji-cursor-visible.shoji-controls-hidden,
+.shoji-cursor-visible.shoji-controls-hidden * {
+  cursor: auto !important;
+}
+/* A real bug, reported from real usage: dragging past the close threshold
+   (GestureController's live controls-hide cue, §2.4/§2.8) reuses this same
+   `.shoji-controls-hidden` class, so the cursor vanished along with the
+   toolbar/nav/counter/caption — disorienting mid-drag, when the pointer is
+   actively moving and the viewer needs to see it. `cursor: none` only makes
+   sense for an idle/inactive hide; a drag is the opposite of idle. Not
+   reusing `.shoji-cursor-visible` here — that class is a *permanent* marker
+   for `autoHideDelay: 0`, and toggling it on/off with the drag would
+   incorrectly clear it once the drag ends even when that permanent mode is
+   also active. */
+.shoji-controls-hidden-for-drag.shoji-controls-hidden,
+.shoji-controls-hidden-for-drag.shoji-controls-hidden * {
+  cursor: auto !important;
+}
+.shoji-live-region {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  overflow: hidden;
+  clip: rect(0 0 0 0);
+  white-space: nowrap;
+}