@michaelyagi/shoji 0.1.0-alpha.13 → 0.1.0-alpha.37

package/dist/esm/bodyScrollLock-CC5PJxJp.js

@@ -0,0 +1,96 @@
+let lockCount = 0;
+let savedHtmlOverflow = "";
+let savedHtmlPaddingRight = "";
+let savedHtmlPaddingLeft = "";
+let savedScrollX = 0;
+let savedScrollY = 0;
+let styleObserver = null;
+let intentionalScrollOccurred = false;
+const LIGHTBOX_SELECTOR = ".shoji-outer";
+function markIntentionalScroll() {
+  intentionalScrollOccurred = true;
+}
+function isRtl() {
+  return getComputedStyle(document.documentElement).direction === "rtl";
+}
+function hasScrollableAncestor(node) {
+  let el = node instanceof Element ? node : (node == null ? void 0 : node.parentElement) ?? null;
+  while (el && el !== document.documentElement) {
+    const style = getComputedStyle(el);
+    if ((style.overflowY === "auto" || style.overflowY === "scroll") && el.scrollHeight > el.clientHeight) {
+      return true;
+    }
+    el = el.parentElement;
+  }
+  return false;
+}
+let touchAllowsScrollThrough = false;
+function onTouchStart(event) {
+  const target = event.target;
+  const insideLightbox = target instanceof Element && target.closest(LIGHTBOX_SELECTOR) !== null;
+  touchAllowsScrollThrough = !insideLightbox && hasScrollableAncestor(target);
+}
+function onTouchMove(event) {
+  const target = event.target;
+  const insideLightbox = target instanceof Element && target.closest(LIGHTBOX_SELECTOR) !== null;
+  if (!insideLightbox && !touchAllowsScrollThrough) event.preventDefault();
+}
+function onStyleMutation() {
+  if (lockCount === 0) return;
+  const html = document.documentElement;
+  if (getComputedStyle(html).overflow !== "hidden") {
+    html.style.overflow = "hidden";
+    styleObserver == null ? void 0 : styleObserver.takeRecords();
+  }
+}
+function lockBodyScroll() {
+  if (lockCount === 0) {
+    savedScrollX = window.scrollX;
+    savedScrollY = window.scrollY;
+    intentionalScrollOccurred = false;
+    const scrollbarWidth = window.innerWidth - document.documentElement.clientWidth;
+    const rtl = isRtl();
+    savedHtmlPaddingRight = document.documentElement.style.paddingRight;
+    savedHtmlPaddingLeft = document.documentElement.style.paddingLeft;
+    if (scrollbarWidth > 0) {
+      if (rtl) {
+        const currentPaddingLeft = parseFloat(getComputedStyle(document.documentElement).paddingLeft) || 0;
+        document.documentElement.style.paddingLeft = `${currentPaddingLeft + scrollbarWidth}px`;
+      } else {
+        const currentPaddingRight = parseFloat(getComputedStyle(document.documentElement).paddingRight) || 0;
+        document.documentElement.style.paddingRight = `${currentPaddingRight + scrollbarWidth}px`;
+      }
+    }
+    savedHtmlOverflow = document.documentElement.style.overflow;
+    document.documentElement.style.overflow = "hidden";
+    document.addEventListener("touchstart", onTouchStart, { passive: true });
+    document.addEventListener("touchmove", onTouchMove, { passive: false });
+    styleObserver = new MutationObserver(onStyleMutation);
+    styleObserver.observe(document.documentElement, {
+      attributes: true,
+      attributeFilter: ["style"]
+    });
+  }
+  lockCount++;
+}
+function unlockBodyScroll() {
+  lockCount = Math.max(0, lockCount - 1);
+  if (lockCount === 0) {
+    styleObserver == null ? void 0 : styleObserver.disconnect();
+    styleObserver = null;
+    document.removeEventListener("touchstart", onTouchStart);
+    document.removeEventListener("touchmove", onTouchMove);
+    document.documentElement.style.overflow = savedHtmlOverflow;
+    document.documentElement.style.paddingRight = savedHtmlPaddingRight;
+    document.documentElement.style.paddingLeft = savedHtmlPaddingLeft;
+    if (!intentionalScrollOccurred) {
+      window.scrollTo({ left: savedScrollX, top: savedScrollY, behavior: "instant" });
+    }
+  }
+}
+export {
+  lockBodyScroll as l,
+  markIntentionalScroll as m,
+  unlockBodyScroll as u
+};
+//# sourceMappingURL=bodyScrollLock-CC5PJxJp.js.map

package/dist/esm/bodyScrollLock-CC5PJxJp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bodyScrollLock-CC5PJxJp.js","sources":["../../src/core/bodyScrollLock.ts"],"sourcesContent":["/** DESIGN.md §2.6a — reference-counted page scroll lock. */\nlet lockCount = 0;\nlet savedHtmlOverflow = '';\nlet savedHtmlPaddingRight = '';\nlet savedHtmlPaddingLeft = '';\nlet savedScrollX = 0;\nlet savedScrollY = 0;\nlet styleObserver: MutationObserver | null = null;\n// Set by markIntentionalScroll() (ActiveThumbnail's own scrollIntoView while\n// locked, DESIGN.md §2.6a/§4.2) — a real bug/regression: unlockBodyScroll()\n// unconditionally restoring savedScrollX/Y (below) was meant to undo\n// *unrelated* code hijacking scroll during the lock (a router, a stray\n// \"scroll to top\" button), but it just as unconditionally undid Shoji's own\n// legitimate background-page scrolling too, making ActiveThumbnail's\n// scrollIntoView a complete no-op the instant the lightbox that triggers it\n// is also what's holding the lock — every navigation while open, always.\n// Once anything marks an intentional scroll during this lock session, skip\n// the restore entirely rather than try to track a smooth-scroll animation's\n// eventual resting position (no reliable completion signal across browsers)\n// — same \"leave it where legitimate code put it\" reasoning, just without\n// pinpointing the exact pixel.\nlet intentionalScrollOccurred = false;\n\nconst LIGHTBOX_SELECTOR = '.shoji-outer';\n\n/** Call after intentionally scrolling something on the host page while the lock is active (e.g. ActiveThumbnail's own `scrollIntoView`) — tells `unlockBodyScroll()` not to undo it. */\nexport function markIntentionalScroll(): void {\n  intentionalScrollOccurred = true;\n}\n\nfunction isRtl(): boolean {\n  return getComputedStyle(document.documentElement).direction === 'rtl';\n}\n\n/**\n * Walks up from `node` looking for a real scrollable container — lets\n * `onTouchMove` below allow touch-scrolling through to something like a\n * host-app modal/sidebar opened on top of the lightbox, instead of\n * blocking it just because it's outside `.shoji-outer`. Stops at\n * `document.documentElement` deliberately — that's the exact background\n * scroll this lock exists to block, not a container to exempt from it.\n */\nfunction hasScrollableAncestor(node: Node | null): boolean {\n  let el = node instanceof Element ? node : (node?.parentElement ?? null);\n  while (el && el !== document.documentElement) {\n    const style = getComputedStyle(el);\n    if (\n      (style.overflowY === 'auto' || style.overflowY === 'scroll') &&\n      el.scrollHeight > el.clientHeight\n    ) {\n      return true;\n    }\n    el = el.parentElement;\n  }\n  return false;\n}\n\n// Computed once per gesture, in onTouchStart below, not recomputed on every\n// onTouchMove — a touch's `event.target` stays fixed to the original\n// touchstart target for the whole gesture regardless of where the finger\n// moves (Touch Events spec), so re-walking the ancestor chain and calling\n// getComputedStyle again on every move would just repeat the same, not-free\n// answer for no benefit (CLAUDE.md: no forced synchronous layout in hot\n// paths like gestures/scroll).\nlet touchAllowsScrollThrough = false;\n\nfunction onTouchStart(event: TouchEvent): void {\n  const target = event.target;\n  const insideLightbox = target instanceof Element && target.closest(LIGHTBOX_SELECTOR) !== null;\n  touchAllowsScrollThrough = !insideLightbox && hasScrollableAncestor(target as Node | null);\n}\n\n/**\n * A real gap: `overflow: hidden` on `<html>` doesn't reliably block iOS\n * Safari's own touch-driven rubber-band/bounce scroll in every case — a\n * well-known limitation of this technique across the ecosystem. The common\n * workaround (flipping `body` to `position: fixed` while locked) has its\n * own real tradeoffs: a full reflow, plus manual scroll-position capture/\n * restore that's a frequent source of bugs in other libraries (the exact\n * class of bug this whole lock has already had twice — see the other real\n * bugs in this file's history). Lighter alternative: block the browser's\n * default only for a touchmove that didn't start inside a lightbox,\n * leaving Shoji's own in-dialog gesture handling (which already manages\n * its own `preventDefault`, see `GestureEngine.ts`) completely untouched.\n * Not a passive listener — `preventDefault` is genuinely required here to\n * suppress the browser's native scroll, not just observe it.\n *\n * Also untouched: a touch that started on a genuinely scrollable ancestor\n * outside the lightbox (`touchAllowsScrollThrough`, set in `onTouchStart`\n * above) — a real bug, reported from real usage: this used to block\n * touch-scrolling in *any* host-app UI outside `.shoji-outer`, including\n * something like a Bootstrap modal or sidebar opened on top of the\n * lightbox, not just the page body behind it.\n */\nfunction onTouchMove(event: TouchEvent): void {\n  const target = event.target;\n  const insideLightbox = target instanceof Element && target.closest(LIGHTBOX_SELECTOR) !== null;\n  if (!insideLightbox && !touchAllowsScrollThrough) event.preventDefault();\n}\n\n/**\n * A real gap: this lock is reference-counted against other `Gallery`\n * instances, but has no way to know about unrelated code on the host page\n * — another modal/dropdown library that also sets\n * `document.documentElement.style.overflow`, then clears it back to `''`\n * on its own close, would silently undo this lock mid-lightbox with\n * neither library aware of the other. Watching the one attribute this\n * lock itself owns is the only way to detect and correct that reactively.\n * `takeRecords()` discards the mutation record our own corrective write\n * below just queued — otherwise the observer would fire again for a\n * change it caused itself, forever.\n */\nfunction onStyleMutation(): void {\n  if (lockCount === 0) return;\n  const html = document.documentElement;\n  if (getComputedStyle(html).overflow !== 'hidden') {\n    html.style.overflow = 'hidden';\n    styleObserver?.takeRecords();\n  }\n}\n\nexport function lockBodyScroll(): void {\n  if (lockCount === 0) {\n    // A real gap: `overflow: hidden` blocks wheel/touch/keyboard-driven\n    // scrolling, but not a programmatic `window.scrollTo()`/`scrollTop`\n    // write — confirmed directly. If the host's own code scrolls the\n    // window while the lightbox is open (a router restoring scroll\n    // position, an unrelated \"scroll to top\" button), the page ends up\n    // somewhere different than where the viewer left it once the lock\n    // releases. Restored unconditionally on unlock below — a scroll\n    // *lock* implies the background stays frozen in place for the whole\n    // time the lightbox is open, not just protected from direct input.\n    savedScrollX = window.scrollX;\n    savedScrollY = window.scrollY;\n    intentionalScrollOccurred = false;\n\n    // A real bug: hiding overflow below reclaims the scrollbar's own\n    // gutter, widening <html>'s content box by however many px the\n    // scrollbar was — on a host page whose content spans the full viewport\n    // width, that reflow is visible as a shift right when the lightbox\n    // opens/closes (and reverses on close). Measured *before* overflow is\n    // hidden (clientWidth only grows once the gutter is actually reclaimed,\n    // so measuring after would always read 0) and only compensated for when\n    // a real scrollbar was actually there — a page that never had one gets\n    // no padding at all, nothing to compensate for.\n    //\n    // Two rejected approaches, both real bugs of their own: padding-right\n    // on `document.body` compensates the wrong element — a page whose body\n    // is narrower than the viewport (a centered, `max-width`-capped layout,\n    // this docs site included) never touches the scrollbar's gutter in the\n    // first place, so padding body just shrinks its own content box by an\n    // *extra* scrollbar-width's worth, a new, self-inflicted reflow.\n    // `scrollbar-gutter: stable` compensates the right element (`<html>`,\n    // the same one the width is measured on) but paints its own visible,\n    // if non-interactive, scrollbar-track styling for as long as the lock\n    // is active — trading a brief shift for a permanent scrollbar-shaped\n    // strip sitting over the page the whole time the lightbox is open,\n    // which reads as more wrong, not less. Padding is genuinely invisible\n    // — the same blank space a wider margin would be — and, applied to\n    // `<html>` (not `body`), compensates the actual element the scrollbar's\n    // gutter belongs to either way.\n    const scrollbarWidth = window.innerWidth - document.documentElement.clientWidth;\n    const rtl = isRtl();\n    savedHtmlPaddingRight = document.documentElement.style.paddingRight;\n    savedHtmlPaddingLeft = document.documentElement.style.paddingLeft;\n    if (scrollbarWidth > 0) {\n      // A real gap: a classic scrollbar renders on the *left* on a\n      // `direction: rtl` page, not the right — compensating the wrong\n      // side would reintroduce the exact reflow this exists to prevent,\n      // just mirrored. Checked at lock time, not baked in as a fixed\n      // assumption.\n      if (rtl) {\n        const currentPaddingLeft =\n          parseFloat(getComputedStyle(document.documentElement).paddingLeft) || 0;\n        document.documentElement.style.paddingLeft = `${currentPaddingLeft + scrollbarWidth}px`;\n      } else {\n        const currentPaddingRight =\n          parseFloat(getComputedStyle(document.documentElement).paddingRight) || 0;\n        document.documentElement.style.paddingRight = `${currentPaddingRight + scrollbarWidth}px`;\n      }\n    }\n\n    // A real bug: `document.body.style.overflow = 'hidden'` (this function's\n    // original, and until now only, scroll-blocking mechanism) was still\n    // set here alongside <html>'s own below — redundant, and not harmless:\n    // any value of `overflow` other than `visible` makes an element\n    // establish a new block-formatting context, which blocks top-margin\n    // collapsing between it and its first child. Confirmed directly via\n    // real-browser instrumentation: with body's overflow locked, an h1\n    // immediately inside it rendered `bodyMarginTop + h1's own default\n    // margin-top` below the viewport top (its margin no longer collapsing\n    // into body's own); the instant `unlockBodyScroll()` restored body's\n    // overflow, collapsing resumed and the h1 snapped back up by its own\n    // margin's worth — reading as the page shifting upward right as the\n    // lightbox closes, on *any* page where the first child's margin would\n    // otherwise collapse with body's (essentially any page without padding/\n    // border on body itself — not a corner case). <html>'s own overflow:\n    // hidden below is sufficient on its own to block user-driven scrolling\n    // (wheel/touch/keyboard) — confirmed directly — since it's the real\n    // scrolling element in standards mode; body's lock was never adding\n    // independent protection, only this side effect.\n    //\n    // <html>'s own overflow, not just body's — mobile viewport-widening\n    // bug, see DESIGN.md §2.6a. Both axes, not just overflow-x: setting\n    // only one non-'visible' axis forces the browser to silently promote\n    // the other from 'visible' to 'auto' (mixing hidden+visible isn't\n    // allowed per spec), which revealed a real scrollbar that wasn't\n    // there before.\n    savedHtmlOverflow = document.documentElement.style.overflow;\n    document.documentElement.style.overflow = 'hidden';\n\n    // passive: true — onTouchStart only ever reads/caches, never calls\n    // preventDefault(), unlike onTouchMove below.\n    document.addEventListener('touchstart', onTouchStart, { passive: true });\n    document.addEventListener('touchmove', onTouchMove, { passive: false });\n\n    // Starts observing only after the writes above have already landed, so\n    // it never reacts to its own initial setup — only to a later, external\n    // change.\n    styleObserver = new MutationObserver(onStyleMutation);\n    styleObserver.observe(document.documentElement, {\n      attributes: true,\n      attributeFilter: ['style'],\n    });\n  }\n  lockCount++;\n}\n\nexport function unlockBodyScroll(): void {\n  lockCount = Math.max(0, lockCount - 1);\n  if (lockCount === 0) {\n    styleObserver?.disconnect();\n    styleObserver = null;\n    document.removeEventListener('touchstart', onTouchStart);\n    document.removeEventListener('touchmove', onTouchMove);\n\n    document.documentElement.style.overflow = savedHtmlOverflow;\n    document.documentElement.style.paddingRight = savedHtmlPaddingRight;\n    document.documentElement.style.paddingLeft = savedHtmlPaddingLeft;\n\n    if (!intentionalScrollOccurred) {\n      window.scrollTo({ left: savedScrollX, top: savedScrollY, behavior: 'instant' });\n    }\n  }\n}\n"],"names":[],"mappings":"AACA,IAAI,YAAY;AAChB,IAAI,oBAAoB;AACxB,IAAI,wBAAwB;AAC5B,IAAI,uBAAuB;AAC3B,IAAI,eAAe;AACnB,IAAI,eAAe;AACnB,IAAI,gBAAyC;AAc7C,IAAI,4BAA4B;AAEhC,MAAM,oBAAoB;AAGnB,SAAS,wBAA8B;AAC5C,8BAA4B;AAC9B;AAEA,SAAS,QAAiB;AACxB,SAAO,iBAAiB,SAAS,eAAe,EAAE,cAAc;AAClE;AAUA,SAAS,sBAAsB,MAA4B;AACzD,MAAI,KAAK,gBAAgB,UAAU,QAAQ,6BAAM,kBAAiB;AAClE,SAAO,MAAM,OAAO,SAAS,iBAAiB;AAC5C,UAAM,QAAQ,iBAAiB,EAAE;AACjC,SACG,MAAM,cAAc,UAAU,MAAM,cAAc,aACnD,GAAG,eAAe,GAAG,cACrB;AACA,aAAO;AAAA,IACT;AACA,SAAK,GAAG;AAAA,EACV;AACA,SAAO;AACT;AASA,IAAI,2BAA2B;AAE/B,SAAS,aAAa,OAAyB;AAC7C,QAAM,SAAS,MAAM;AACrB,QAAM,iBAAiB,kBAAkB,WAAW,OAAO,QAAQ,iBAAiB,MAAM;AAC1F,6BAA2B,CAAC,kBAAkB,sBAAsB,MAAqB;AAC3F;AAwBA,SAAS,YAAY,OAAyB;AAC5C,QAAM,SAAS,MAAM;AACrB,QAAM,iBAAiB,kBAAkB,WAAW,OAAO,QAAQ,iBAAiB,MAAM;AAC1F,MAAI,CAAC,kBAAkB,CAAC,gCAAgC,eAAA;AAC1D;AAcA,SAAS,kBAAwB;AAC/B,MAAI,cAAc,EAAG;AACrB,QAAM,OAAO,SAAS;AACtB,MAAI,iBAAiB,IAAI,EAAE,aAAa,UAAU;AAChD,SAAK,MAAM,WAAW;AACtB,mDAAe;AAAA,EACjB;AACF;AAEO,SAAS,iBAAuB;AACrC,MAAI,cAAc,GAAG;AAUnB,mBAAe,OAAO;AACtB,mBAAe,OAAO;AACtB,gCAA4B;AA2B5B,UAAM,iBAAiB,OAAO,aAAa,SAAS,gBAAgB;AACpE,UAAM,MAAM,MAAA;AACZ,4BAAwB,SAAS,gBAAgB,MAAM;AACvD,2BAAuB,SAAS,gBAAgB,MAAM;AACtD,QAAI,iBAAiB,GAAG;AAMtB,UAAI,KAAK;AACP,cAAM,qBACJ,WAAW,iBAAiB,SAAS,eAAe,EAAE,WAAW,KAAK;AACxE,iBAAS,gBAAgB,MAAM,cAAc,GAAG,qBAAqB,cAAc;AAAA,MACrF,OAAO;AACL,cAAM,sBACJ,WAAW,iBAAiB,SAAS,eAAe,EAAE,YAAY,KAAK;AACzE,iBAAS,gBAAgB,MAAM,eAAe,GAAG,sBAAsB,cAAc;AAAA,MACvF;AAAA,IACF;AA4BA,wBAAoB,SAAS,gBAAgB,MAAM;AACnD,aAAS,gBAAgB,MAAM,WAAW;AAI1C,aAAS,iBAAiB,cAAc,cAAc,EAAE,SAAS,MAAM;AACvE,aAAS,iBAAiB,aAAa,aAAa,EAAE,SAAS,OAAO;AAKtE,oBAAgB,IAAI,iBAAiB,eAAe;AACpD,kBAAc,QAAQ,SAAS,iBAAiB;AAAA,MAC9C,YAAY;AAAA,MACZ,iBAAiB,CAAC,OAAO;AAAA,IAAA,CAC1B;AAAA,EACH;AACA;AACF;AAEO,SAAS,mBAAyB;AACvC,cAAY,KAAK,IAAI,GAAG,YAAY,CAAC;AACrC,MAAI,cAAc,GAAG;AACnB,mDAAe;AACf,oBAAgB;AAChB,aAAS,oBAAoB,cAAc,YAAY;AACvD,aAAS,oBAAoB,aAAa,WAAW;AAErD,aAAS,gBAAgB,MAAM,WAAW;AAC1C,aAAS,gBAAgB,MAAM,eAAe;AAC9C,aAAS,gBAAgB,MAAM,cAAc;AAE7C,QAAI,CAAC,2BAA2B;AAC9B,aAAO,SAAS,EAAE,MAAM,cAAc,KAAK,cAAc,UAAU,WAAW;AAAA,IAChF;AAAA,EACF;AACF;"}

package/dist/esm/core/FocusTrap.d.ts

@@ -5,5 +5,20 @@ export declare class FocusTrap {
     private readonly onKeydown;
     private getFocusable;
     activate(container: HTMLElement): void;
+    /**
+     * DESIGN.md §2.3a — narrows (or widens back) which subtree Tab cycles
+     * within, without touching `previouslyFocused`/the listener registration
+     * — a caption modal nested inside the already-trapped dialog needs Tab
+     * confined to just itself while open, then back to the whole dialog on
+     * close, but must NOT trigger `activate()`'s own focus-capture (that's
+     * reserved for the real open/close boundary; re-running it mid-session
+     * would capture the wrong "previously focused" element and restore focus
+     * to it too early). `getFocusable()` reads `this.container` fresh on
+     * every keydown, so simply reassigning it is enough — no need for a
+     * second, independent `FocusTrap` instance, which would double-handle
+     * every Tab keypress (two capture-phase `document` listeners, each
+     * computing its own overlapping focusable list).
+     */
+    retarget(container: HTMLElement): void;
     deactivate(): void;
 }

package/dist/esm/core/Gallery.d.ts

@@ -1,5 +1,6 @@
 import { Unsubscribe } from './EventBus';
 import { GalleryEvents, GalleryItem, GalleryItemInput, GalleryOptions } from './types';
+import { Box } from './zoomTransition';
 /**
  * Core lifecycle (DESIGN.md §2.2), item model / DOM scanning (§2.1), and the
  * lightbox itself: pooled slides (§2.3), dialog semantics/focus trap/live
@@ -21,14 +22,51 @@ export declare class Gallery {
     private locale;
     private showCounter;
     private captionVisibleOnVideo;
+    private captionFadePending;
     private loop;
     private closable;
     private autoHideDelay;
+    /** DESIGN.md §3.1a — GalleryOptions.maxPinnedToolbarButtons; see measureToolbarOverflow(). */
+    private maxPinnedToolbarButtons;
     private readonly focusTrap;
     private readonly liveRegion;
     private autoHideTimer;
     private autoHidden;
-    private hoveredControlCount;
+    /**
+     * Every control `wireControlHover()` has ever wired — the full candidate
+     * list `reconcileHover()` (below) checks `:hover` against, kept separate
+     * from `hoveringElements` (elements *believed* to be hovered) so
+     * reconciliation can also *add* one currently missing from that set, not
+     * just remove a stale one.
+     */
+    private readonly hoverableElements;
+    /**
+     * The subset of `hoverableElements` the pointer is currently considered
+     * to be over — a `Set`, not a plain incrementing counter, so
+     * `onActivity()` (below) can reconcile it against the browser's own live
+     * `:hover` ground truth on every real pointer movement, self-healing from
+     * a `pointerenter`/`pointerleave` pair that never fired at all. Two real
+     * bugs, both reported from real usage, both variations on the same
+     * browser behavior already leveraged elsewhere in this file (`hidden`
+     * doesn't fire `pointerleave` under a stationary cursor, §2.3a): (1) a
+     * control that synchronously replaces its own children while the pointer
+     * sits stationary over it (Autoplay's own play/pause icon swap) can
+     * desync the browser's internal hover-chain tracking badly enough that
+     * the *next* real pointer movement away from it never fires `pointerleave`
+     * — a plain counter has no way to detect a leave that never reports
+     * itself. (2) the mirror image: a control that *appears* under an
+     * already-stationary cursor (the common case right after `open()` —
+     * whatever the viewer clicked to get here is often right where a
+     * toolbar/caption/nav control ends up) never gets a `pointerenter`
+     * either, since browsers only recompute hover state on actual pointer
+     * movement, not on an element materializing under one already sitting
+     * still — so idle auto-hide could fire and hide a control the viewer's
+     * cursor is, visibly, still resting directly on top of. Re-deriving "is
+     * this actually hovered" fresh from the browser on every real pointer
+     * move fixes both directions at once, since neither depends on any
+     * event having fired correctly in the first place.
+     */
+    private readonly hoveringElements;
     private isClosing;
     /** True while a vertical drag has hidden controls past its own distance threshold (`setControlsHiddenForDrag`) — `onActivity()` defers to it, since the drag's own continuous pointermove stream would otherwise immediately re-reveal what it just hid on every single move. */
     private controlsHiddenByDrag;
@@ -41,12 +79,48 @@ export declare class Gallery {
     private dom;
     private gesture;
     private transition;
+    /** DESIGN.md §2.3a — measures `.shoji-toolbar`'s real rendered height (it can wrap to multiple rows on a narrow viewport with many toolbar buttons registered) so the caption's own height cap can reserve exactly that much space, not a fixed single-row guess. */
+    private toolbarHeightObserver;
+    private toolbarHeightFrame;
+    private captionTruncationFrame;
+    /** DESIGN.md §2.3a — a truncated caption's own click/Enter/Space target opens this; also gates `GestureController`'s `isZoomed` (alongside the real zoom gate) so a drag over the open modal can't also navigate/close the lightbox underneath it. */
+    private captionModalOpen;
+    private captionModalReturnFocus;
+    /**
+     * DESIGN.md §2.3a — every real path into `openCaptionModal()` starts from
+     * a click *or* a keydown on the caption, so `captionModalReturnFocus`
+     * above is always the caption itself either way; this instead
+     * distinguishes *how* it got there, so `closeCaptionModal()` only
+     * actually calls `.focus()` for the keyboard path (a real Tab+Enter user,
+     * where restoring focus continues their tab sequence correctly) and
+     * leaves it alone for a mouse click (where the resulting focus was
+     * purely incidental — nothing about clicking to read a caption means the
+     * *next* keypress, e.g. a plugin's own Space shortcut, should still
+     * silently target it).
+     */
+    private captionModalOpenedViaKeyboard;
+    /**
+     * DESIGN.md §3.1a — every `ctx.ui.toolbar()`-registered button, in
+     * registration order, alongside the slot it was registered into (so a
+     * collapsed one can be restored to the right place, not just anywhere).
+     * Registration order is what decides overflow priority: up to
+     * `maxPinnedToolbarButtons` stay pinned, the rest collapse into the
+     * popover before them, latest-registered first — see
+     * `measureToolbarOverflow()`.
+     */
+    private readonly pluginToolbarButtons;
+    private toolbarOverflowOpen;
+    private toolbarOverflowReturnFocus;
     private readonly shortcuts;
     private readonly pluginStorage;
     /** Backs `getActivePlugins()`. */
     private readonly activePluginNames;
     private readonly videoProviders;
     private zoomGate;
+    /** DESIGN.md §2.6a/§4.6 — the zoomed `<img>`'s own real on-screen rect, read by `beginClose()` before `beforeClose` fires (see `registerZoomStartProvider()`), so a button-close continues the zoom-out from wherever the viewer was actually zoomed/panned to instead of snapping back to neutral first. */
+    private zoomStartProvider;
+    /** DESIGN.md §2.5/§4.5 — plugins with a per-slide visual override (RotateFlip's rotate/flip, Zoom's scale/pan) that reset unanimated on `beforeSlide` (must clear before `SlideManager.render()` reparents the outgoing node). Multi-slot: more than one can be active on the same slide, each targeting a different part of the clone, so they don't conflict. See `registerSlideLeaveDecorator()`. */
+    private readonly slideLeaveDecorators;
     private pluginCleanups;
     private readonly onContainerClick;
     private readonly onOuterClick;
@@ -67,6 +141,27 @@ export declare class Gallery {
     private controlsHiddenAtGestureStart;
     private readonly captureGestureStartState;
     private readonly onKeydown;
+    /**
+     * DESIGN.md §2.3a — capture phase, added only while the caption modal is
+     * open (not from `open()` onward like `onKeydown`, which is bubble
+     * phase): capture always finishes before bubble starts, so
+     * `stopPropagation()` here reliably beats `onKeydown`'s own bubble-phase
+     * handling regardless of where in the dialog focus happens to be. A real
+     * bug, reported from real usage: an earlier version of this only special-
+     * cased `Escape`, leaving every other key (`Space` — Autoplay's own
+     * play/pause shortcut if that plugin's loaded, arrow keys, `w`/`s` for
+     * Zoom, any plugin-registered shortcut) to fall straight through to
+     * `onKeydown` while the modal sat open on screen. A modal dialog should
+     * make the background fully inert to keyboard input while it's open, not
+     * just for one key — so this now stops propagation for *every* key
+     * unconditionally, closing the modal as the one piece of extra behavior
+     * layered on top for `Escape` specifically. Deliberately no
+     * `preventDefault()` here — the modal's own contents (the close button,
+     * a scrollable panel) keep their normal native key behavior (Space
+     * activating a focused button, arrow/Space scrolling), only the
+     * *background* gallery is what this isolates it from.
+     */
+    private readonly onCaptionModalKeydown;
     constructor(target: HTMLElement | string, options?: GalleryOptions);
     /** Everything the constructor does after `this.element` is resolved — shared with `reinit()` (§2.7). */
     private applyOptions;
@@ -84,22 +179,159 @@ export declare class Gallery {
     getActiveMedia(): HTMLElement | null;
     /** DESIGN.md §4-zoom — suspends drag-to-navigate/close while zoomed. Single slot, not a multi-subscriber event. */
     registerZoomGate(isZoomed: () => boolean): () => void;
+    /** DESIGN.md §2.6a/§4.6 — returns the zoomed image's current on-screen rect (`getBoundingClientRect()`), or `null` when not zoomed. Single slot, same pattern as `registerZoomGate` above. */
+    registerZoomStartProvider(provider: () => Box | null): () => void;
+    /**
+     * DESIGN.md §2.5/§4.5 — called once per navigation with the leave-
+     * ghost's clone, right after `SlideTransition` creates it. Freeze
+     * whatever per-slide visual state is about to be reset onto the clone
+     * (or a descendant, e.g. Zoom's own `<img>`) and return a `() => void`
+     * to trigger the transition back to neutral once committed — or return
+     * nothing if there's nothing to animate away this time.
+     */
+    registerSlideLeaveDecorator(decorator: (clonedMedia: HTMLElement) => (() => void) | void): () => void;
     on<K extends keyof GalleryEvents>(event: K, fn: (detail: GalleryEvents[K]) => void): Unsubscribe;
     private clampToRange;
     private ensureLightbox;
-    /** DESIGN.md §3 — plugins init here, not the constructor. `requires` checks names loaded earlier; an unmet one is skipped (logged), not thrown. Cleared up front so a `reinit()` doesn't inherit names from before. */
+    /**
+     * DESIGN.md §3 — which of `declared`'s plugins will actually load,
+     * resolved as a fixed point rather than a single pass: start with every
+     * *structurally* valid entry (a real object with an `init` function),
+     * then repeatedly drop any whose `requires` points at a name no longer
+     * in the set, until a full pass drops nothing. That repetition is what
+     * makes a chain cascade correctly — if a plugin gets dropped because
+     * *its* own requirement failed, anything requiring that plugin drops on
+     * the very next pass, the same as if the original problem were its own.
+     * A genuine mutual requirement (A needs B, B needs A, both otherwise
+     * fine) never gets caught in this — each still finds the other present
+     * whenever it's checked, so both stay valid. That's correct, not a
+     * missed case: this only ever decides *whether* something loads, never
+     * *when* — nothing here reorders execution, so two plugins depending on
+     * each other creates no actual ordering conflict to detect in the first
+     * place.
+     */
+    private resolveValidPluginNames;
+    /**
+     * DESIGN.md §3 — plugins init here, not the constructor. `requires` is
+     * resolved against the *whole* declared `plugins` list up front, not
+     * registration order — a real friction point, reported directly: a host
+     * with a `requires` chain had to carefully order the array by hand, with
+     * no actual reason to (nothing about *execution* order needs to match
+     * declaration order for a name-presence check). `resolveValidPluginNames()`
+     * decides who's actually going to load, independent of position; this
+     * loop still runs — and every `ctx.ui.toolbar()` registration still
+     * lands — in exactly the array's own order regardless, so toolbar/
+     * collapse-priority order (also array-order-driven, DESIGN.md §3.1a)
+     * is completely unaffected by this. Cleared up front so a `reinit()`
+     * doesn't inherit names from before.
+     */
     private initPlugins;
     /**
-     * DESIGN.md §3.1 — 'right' inserts immediately before the close button
-     * (never after), so close stays fixed rightmost and plugins cluster to
-     * its left in registration order: `plugins: [A, B, C]` reads A, B, C,
-     * close. 'left'/'center' are independent zones for a plugin that doesn't
-     * want to sit next to close.
+     * DESIGN.md §3.1 — 'right' inserts immediately before the overflow caret
+     * (DESIGN.md §3.1a — never after, and never after close either), so
+     * close stays fixed absolute-rightmost, the caret sits just to its left,
+     * and plugins cluster further left still, in registration order:
+     * `plugins: [A, B, C]` reads A, B, C, caret, close. 'left'/'center' are
+     * independent zones for a plugin that doesn't want to sit next to close.
      */
     private pluginToolbar;
     private buildToolbarButton;
+    /**
+     * DESIGN.md §3.1a — coalesces both toolbar-overflow measurement and the
+     * pre-existing `--shoji-toolbar-height` update into one rAF-batched pass
+     * (CLAUDE.md: batch DOM writes that can thrash layout), triggered by the
+     * toolbar's own `ResizeObserver` (width *or* height changes — a busy
+     * toolbar wrapping counts as both) and by `pluginToolbar()` registering
+     * or unregistering a button. Order matters: overflow collapse has to run
+     * *before* the height read, so the height custom property reflects the
+     * settled (ideally single-row, post-collapse) toolbar, not a momentarily
+     * wrapped one the caption's own height cap would otherwise over-reserve
+     * space for.
+     */
+    private scheduleToolbarOverflowMeasure;
+    /**
+     * DESIGN.md §3.1a — collapses plugin toolbar buttons into
+     * `toolbarOverflowPanel` once they don't fit in one row, instead of
+     * letting the toolbar wrap to a second/third one. Always restores every
+     * plugin button to its own original slot first and recomputes from that
+     * clean slate, rather than incrementally adjusting whatever the previous
+     * pass left behind — the *set* of buttons and the viewport width can
+     * both have changed since then, and a fresh, deterministic pass is both
+     * simpler and self-correcting than trying to reason about a delta.
+     *
+     * "Fits in one row" is measured, not assumed: each slot's own rendered
+     * height is compared against `closeButton`'s (always exactly one row
+     * tall, always present) — a slot has wrapped if it's taller than that,
+     * regardless of *which* slot a plugin happened to register into (the
+     * three slots wrap independently, DESIGN.md §3.1a's own CSS notes).
+     *
+     * Collapses latest-registered first (DESIGN.md §3's own registration-
+     * order-is-priority convention — `plugins: [A, B, C]` keeps A pinned
+     * before B/C). `maxPinnedToolbarButtons` (default 2, see
+     * `GalleryOptions.maxPinnedToolbarButtons`) is a ceiling, not a
+     * guarantee: collapsing always goes down to at most that many pinned,
+     * but keeps going *below* it — down to zero if it must — whenever even
+     * that many still leaves a slot wrapped. `closeButton` and the counter
+     * (`toolbarLeft`) must never wrap onto their own line, and `fitsOneRow()`
+     * already checks every slot's height, not just `toolbarRight`'s, so a
+     * wide counter or other left-slot content competing for the same row
+     * pushes the pinned count down too, not just the right slot's own
+     * button count. `closeButton`/`toolbarOverflowButton` themselves are
+     * never candidates for collapse — everything else relocates into the
+     * popover, which renders directly below that row.
+     */
+    private measureToolbarOverflow;
+    private readonly onToolbarOverflowKeydown;
+    private toggleToolbarOverflow;
+    private openToolbarOverflow;
+    /**
+     * DESIGN.md §3.1a — the panel's `right` offset is set here, per open,
+     * rather than as a fixed CSS value: the caret's own x-position isn't
+     * fixed, it shifts with how many buttons are pinned ahead of it
+     * (`maxPinnedToolbarButtons` is host-configurable, and can itself be
+     * reduced further at measure time, DESIGN.md §3.1a), so a static
+     * `right: var(--shoji-spacing-md)` only happened to line up with the
+     * caret at one particular pinned-button count and viewport width. It
+     * otherwise anchored to the toolbar/dialog's own right edge — under
+     * `closeButton`, which sits to the right of the caret, not under the
+     * caret that actually opens it.
+     *
+     * Aligns the panel's own *content* edge (inside its padding), not just
+     * its border box, with the caret's right edge — the panel's grid pitch
+     * (44px columns, `--shoji-spacing-sm` gaps, `.shoji-toolbar-overflow-
+     * panel` in shoji.css) already matches the toolbar row's own button
+     * size/gap, so subtracting the panel's own right padding here is what
+     * makes the popover's icon columns actually line up with the toolbar
+     * row's icons above them, not just the panel block sitting roughly
+     * nearby.
+     *
+     * Also sets the grid's own column count to match the toolbar row's own
+     * column count right now: however many buttons are *actually* still
+     * pinned on `toolbarRight`, *plus the caret itself* — requested directly:
+     * the popover should read as the same row of columns continuing
+     * downward, caret included, not a fixed 3 columns regardless of how many
+     * ended up pinned. At the default `maxPinnedToolbarButtons` (2), that's 2
+     * pinned + the caret = 3 columns. Collapsed buttons beyond that count
+     * still wrap onto further rows within it, same as before.
+     *
+     * **A real bug: "pinned" is counted from `this.pluginToolbarButtons`
+     * (registered via `ctx.ui.toolbar()`), never by querying `toolbarRight`'s
+     * DOM children.** The old filter (`toolbarRight.children`, excluding
+     * `closeButton`/`toolbarOverflowButton` by identity, `!el.hidden`) broke
+     * once a host appended an unrelated element straight into `toolbarRight`
+     * — not a documented extension point, but nothing stops it. Reported from
+     * real usage: a plugin's own loading spinner, toggled via `style.display`
+     * rather than the `hidden` attribute, passed `!el.hidden` and got
+     * miscounted as a pinned button, turning a 3-column popover into 4.
+     * Counting from the registry instead is immune to this regardless of how
+     * such an element manages its own visibility. `closeButton`/
+     * `toolbarOverflowButton` were never in `pluginToolbarButtons`, so
+     * excluding them by identity is no longer needed either.
+     */
+    private positionToolbarOverflowPanel;
+    private closeToolbarOverflow;
     private pluginOverlay;
-    /** DESIGN.md §2.8/§3 — pauses auto-hide while genuinely hovered: controls, caption, and any plugin overlay (`ctx.ui.overlay()`). Unsubscribe also corrects the count if removed mid-hover — a real risk for overlay content a plugin can toggle while the gallery stays open, unlike static buttons. */
+    /** DESIGN.md §2.8/§3 — pauses auto-hide while genuinely hovered: controls, caption, and any plugin overlay (`ctx.ui.overlay()`). Unsubscribe also corrects the set if removed mid-hover — a real risk for overlay content a plugin can toggle while the gallery stays open, unlike static buttons. */
     private wireControlHover;
     /**
      * DESIGN.md §2.8 — paused only by a real *hover*. Used to also treat a
@@ -109,6 +341,20 @@ export declare class Gallery {
      * `onActivity()`), it just no longer blocks the eventual hide.
      */
     private isControlActive;
+    /**
+     * Syncs `hoveringElements` to the browser's own live `:hover` truth for
+     * every registered control — both directions, not just dropping a stale
+     * entry: also picks up one that's genuinely hovered but never got a
+     * `pointerenter` of its own (see `hoveringElements`'s own doc comment for
+     * why either direction can happen). Whichever ends up true here is what
+     * `isControlActive()` reads immediately after, in the same `onActivity()`
+     * call — no separate reveal step needed for a newly-added element; that
+     * call already does it for any activity, hover included. Cheap in
+     * practice: `hoverableElements` is normally single digits, and `:hover`
+     * matching is a native, already-computed browser check, not a
+     * layout-triggering one.
+     */
+    private reconcileHover;
     /**
      * The thumbnail for `index` — what the zoom transition animates to/from,
      * and what `activeThumbnail` marks/scrolls-to. `data-shoji-id` is an
@@ -125,8 +371,7 @@ export declare class Gallery {
      * `autoHideDelay: false` — a real bug, reported from real usage: Autoplay's
      * tap-to-toggle-chrome behavior called this directly and ignored `false`
      * entirely, since only the idle timer checked it. `false` has to hold for
-     * every caller, not just the timer — `mobileSettings.controls: false` is
-     * affected the same way, by design. `forceHideControls()`/
+     * every caller, not just the timer. `forceHideControls()`/
      * `setControlsHiddenForDrag()` (close, drag-to-close) deliberately don't
      * check this — direct user actions with their own feedback, not auto-hide.
      */
@@ -152,6 +397,21 @@ export declare class Gallery {
      * activating an already-focused button.
      */
     private setSlideLoading;
+    /**
+     * DESIGN.md §2.5 — the caption's disappear-then-reappear fits inside the
+     * *same* `--shoji-duration` window the slide's own mode animation runs
+     * in, not a separate one after it: fades out over the first half, swaps
+     * content invisibly at the midpoint, fades back in over the second half
+     * — timed to finish exactly when the mode animation does, not still
+     * catching up a beat behind it. Self-timed off the resolved
+     * `--shoji-duration` value rather than hooked to the mode animation's
+     * own completion event: both are driven by the same duration either way,
+     * and the fade-in's own completion is what has to line up, which a
+     * "start on completion, then animate" hook can't give — by definition,
+     * a fade started only once something else finishes hasn't finished
+     * *with* it.
+     */
+    private transitionCaption;
     /**
      * Content is always kept current (correct the instant loading finishes,
      * no text flash) — only `hidden` also gates on `isActiveReady()`, so a
@@ -159,6 +419,89 @@ export declare class Gallery {
      * image/video it describes is still a spinner.
      */
     private updateCaptionVisibility;
+    /**
+     * DESIGN.md §2.3a — the caption's own default height cap (above) already
+     * keeps it clear of the toolbar, but says nothing about the vertically-
+     * centered prev/next nav arrows sharing its same left edge; a long
+     * enough caption could still grow up over one of those. `--shoji-*`
+     * collapses it to roughly one line by default (shoji.css) regardless, so
+     * this only ever needs to detect whether that collapse actually clipped
+     * something — `scrollHeight > clientHeight` after layout, the same
+     * technique already used elsewhere in this codebase (and its own tests)
+     * to detect caption overflow. Marks it truncated/interactive only when
+     * there's genuinely more to read; a caption that already fits shouldn't
+     * look or behave clickable.
+     *
+     * A real bug, reported from real usage: the first version only capped
+     * `max-height` + `overflow: hidden` — a plain pixel clip with no regard
+     * for where a line of text actually ends, so the cutoff routinely sliced
+     * straight through the middle of the last visible line instead of
+     * stopping at a clean line boundary, reading as broken rather than
+     * intentionally truncated.
+     *
+     * Two follow-up attempts, both also wrong, both worth recording so they
+     * aren't retried: `-webkit-line-clamp` never cleanly stopped at a line
+     * boundary here regardless of the line count fed into it. Replacing it
+     * with `lines * lineHeight + paddingY` arithmetic (using
+     * `getComputedStyle(el).lineHeight`) still left a sliver of the next
+     * line visible in a real browser — confirmed by screenshot, not just
+     * this sandbox. Root cause: a browser doesn't necessarily lay out N
+     * stacked lines at exactly N times the CSS `line-height` value: text
+     * layout does its own sub-pixel rounding per line, so arithmetic
+     * multiplication drifts from the real rendered geometry by enough to
+     * expose part of an extra line, and no fixed safety margin is correct
+     * for every font/zoom/line-count combination.
+     *
+     * This version doesn't compute line boundaries at all — it reads them
+     * straight from the browser's own layout via `Range.getClientRects()`,
+     * which returns one rect per actual rendered line fragment (rich
+     * captions with inline markup can put more than one rect on the same
+     * visual row; each is handled independently below rather than grouped,
+     * since only the topmost/bottommost edges per row matter here). The cap
+     * is set to the bottom edge of the last line whose bottom still fits
+     * inside the current (arbitrary, CSS-calc'd) height budget — a real
+     * measured boundary, never an assumed one.
+     *
+     * A third real bug, caught after switching to this measured approach:
+     * padding the box out by a full `padding-bottom` past that last line's
+     * *measured* bottom still isn't safe, because line boxes butt up much
+     * closer together than the padding value — the next (excluded) line's
+     * own top can fall well inside that padding band, so its glyph
+     * ascenders paint into what was supposed to be empty breathing room.
+     * Fixed by also finding that next line's top and never letting the cap
+     * reach it, regardless of how much of `padding-bottom` that leaves.
+     */
+    private updateCaptionTruncation;
+    private readonly onCaptionActivate;
+    /**
+     * DESIGN.md §2.3a — shows the full caption (re-rendered via the same
+     * `renderCaption()` the truncated one already used, so a rich-HTML
+     * caption's own links/formatting are identical in both places) in a
+     * small nested dialog, scrollable if it's still taller than the
+     * viewport allows. `FocusTrap.retarget()` narrows Tab-cycling to just
+     * this modal without touching the outer trap's own focus-restore state
+     * (see its own doc comment for why a second `FocusTrap` instance isn't
+     * used instead). Requested directly: the modal *replaces* the truncated
+     * caption rather than just visually sitting on top of it — hiding
+     * `dom.caption` too, not only because the modal's own opaque backdrop
+     * already covers it, but so it can't still be reached by a screen
+     * reader's browse-mode cursor (unlike Tab, `FocusTrap`/`retarget()`
+     * don't affect that) while a completely different dialog is the one
+     * actually open.
+     */
+    private openCaptionModal;
+    /**
+     * Requested directly: closing should leave the viewer looking at a fully
+     * normal, fully visible gallery — not just the modal gone, but the
+     * truncated caption back (via `updateCaptionVisibility()`, which
+     * recomputes its real hidden state from scratch rather than blindly
+     * flipping a flag back — the more robust "recompute from source of
+     * truth" this codebase already prefers elsewhere) and any auto-hidden
+     * toolbar/nav explicitly re-shown (`onActivity()`, same pairing every
+     * other real interaction already uses) rather than left hidden until
+     * the viewer happens to move the mouse.
+     */
+    private closeCaptionModal;
     private renderCurrentSlide;
     open(index?: number): void;
     /** DESIGN.md §2.3 — low-res open() placeholder source, checked in order: item.thumb, a live data-shoji-thumb on origin, else origin's own rendered <img>. */
@@ -188,18 +531,7 @@ export declare class Gallery {
      * the real, configured transition.
      */
     private navigate;
-    /** DESIGN.md §2.5 — `mobileSettings.mode` overrides `mode` on a coarse-pointer device, evaluated fresh each navigation. */
     private resolveTransitionMode;
-    private isMobileQuery;
-    /**
-     * DESIGN.md §2.5 — `mobileSettings.controls: false` starts controls
-     * hidden on a coarse-pointer device, reusing the existing §2.8 auto-hide
-     * mechanism (`hideControls()`) rather than a separate permanent-hide
-     * state: auto-hide is opacity-only, never removed from the tab order,
-     * and already reveals on any activity — a genuinely *permanent* hide
-     * would strand a touch user with no way to ever reach Close.
-     */
-    private applyMobileControlsSetting;
     close(): void;
     /**
      * DESIGN.md §2.4/§2.6a — same effect as `close()`, from a completed
@@ -222,7 +554,25 @@ export declare class Gallery {
      * the chrome is disappearing too, just without the pause.)
      */
     private beginClose;
-    /** Forces the same fade §2.8's idle timer would eventually trigger, bypassing `hideControls()`'s own `isControlActive()` hover guard — the most common close path (clicking close) is hovering a control at this exact instant, and a deliberate close should hide regardless. No-op if already hidden. */
+    /**
+     * Forces the same fade §2.8's idle timer would eventually trigger, bypassing `hideControls()`'s own `isControlActive()` hover guard — the most common close path (clicking close) is hovering a control at this exact instant, and a deliberate close should hide regardless. No-op if already hidden.
+     *
+     * Also marks `.shoji-controls-hidden-for-close` alongside the ordinary
+     * class — a real bug, reported from real usage: a plugin's own overlay
+     * (Autoplay's progress bar, `autoplay.css`) was wired to fade on plain
+     * `.shoji-controls-hidden`, the same class *ordinary idle auto-hide* also
+     * applies — so it faded out and stayed gone through every idle period
+     * too, not just the close animation the original request was actually
+     * about. That went unnoticed for a while because until recently, tapping
+     * the image toggled play/pause *and* revealed controls on the same tap,
+     * papering over how often it was actually gone; once that tap-to-toggle
+     * was removed (§4.1 point 15) as a separate, unrelated fix, an idle
+     * slideshow now visibly loses its own progress indicator and never gets
+     * it back without an unrelated interaction — surfacing this as a real
+     * regression in practice, even though no code touching this class had
+     * changed. This second class is the hook a plugin's CSS can key off
+     * specifically for "closing," without it ever matching ordinary idle-hide.
+     */
     private forceHideControls;
     /**
      * DESIGN.md §2.4/§2.8 — `GestureController`'s live vertical-drag cue: hide