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

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

@@ -30,6 +30,8 @@ export declare class Gallery {
     private autoHidden;
     private hoveredControlCount;
     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;
     private itemList;
     private scannedElements;
     private activeIndex;
@@ -48,7 +50,18 @@ export declare class Gallery {
     private pluginCleanups;
     private readonly onContainerClick;
     private readonly onOuterClick;
-    /** DESIGN.md §2.8 — any interaction re-shows controls, restarts the idle clock. `autoHideDelay: 0` = "never show controls" — a no-op here. */
+    /**
+     * DESIGN.md §2.8 — any interaction re-shows controls, restarts the idle
+     * clock. `autoHideDelay: 0` = "never show controls" — a no-op here.
+     * `autoHideDelay: false` = "always visible" — also a no-op: nothing to
+     * reveal (already shown) or reschedule (no timer ever runs). Also a no-op
+     * once `isClosing` — a real bug, reported from real usage: moving the
+     * mouse during close()'s own controls-fade-then-zoom-out sequence (§2.6a)
+     * re-showed the just-hidden controls mid-animation, since these listeners
+     * stay wired for the whole close sequence. Same reasoning for
+     * `controlsHiddenByDrag` (§2.4/§2.8): a vertical drag's own `pointermove`
+     * stream would otherwise re-reveal what it just hid, every single frame.
+     */
     private readonly onActivity;
     /** x */
     private controlsHiddenAtGestureStart;
@@ -105,7 +118,18 @@ export declare class Gallery {
      */
     getOriginElement(index: number): HTMLElement | null;
     private scheduleAutoHide;
-    /** Forces the same fade §2.8's idle timer would eventually trigger — public so a plugin can hide controls on its own trigger. Same `isControlActive()` guard as the timer. */
+    /**
+     * Forces the same fade §2.8's idle timer would eventually trigger —
+     * public so a plugin can hide controls on its own trigger. Same
+     * `isControlActive()` guard as the timer. Also a no-op under
+     * `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()`/
+     * `setControlsHiddenForDrag()` (close, drag-to-close) deliberately don't
+     * check this — direct user actions with their own feedback, not auto-hide.
+     */
     hideControls(): void;
     private showControls;
     /**
@@ -177,6 +201,40 @@ export declare class Gallery {
      */
     private applyMobileControlsSetting;
     close(): void;
+    /**
+     * DESIGN.md §2.4/§2.6a — same effect as `close()`, from a completed
+     * vertical swipe. `frozenDrag` is threaded through to `zoomOut()`'s own
+     * `dragStart`, so the whole close continues as one motion from exactly
+     * where the drag left off (see `GestureController.
+     * takeFrozenDragTransform`).
+     */
+    private closeFromSwipe;
+    /**
+     * `frozenDrag` — see `closeFromSwipe()`'s doc comment; absent for a
+     * button-close, which has no drag to continue from. Controls fade and the
+     * zoom-out run concurrently, both starting the instant `forceHideControls()`
+     * runs — not sequenced one after the other. (A previous version waited for
+     * the controls' own fade to fully finish before starting the zoom-out, for
+     * a button-close specifically — requested directly, to avoid stationary
+     * chrome hovering over an already-shrinking photo. Reversed on later,
+     * explicit feedback: waiting read as two distinct steps rather than one
+     * motion; starting both together still avoids stationary chrome, since
+     * 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. */
+    private forceHideControls;
+    /**
+     * DESIGN.md §2.4/§2.8 — `GestureController`'s live vertical-drag cue: hide
+     * past the same distance a release would close, reveal again on retreat.
+     * `hidden: false` only reveals if visible when *this* gesture started
+     * (`controlsHiddenAtGestureStart`) — shouldn't resurrect controls already
+     * separately hidden (idle, or `autoHideDelay: 0`) before the drag began.
+     * `dragCloseThreshold` (bus event) fires on every crossing regardless of
+     * that guard — Autoplay (§4-autoplay) needs to know about the crossing
+     * itself, not just whether controls visibly moved.
+     */
+    private setControlsHiddenForDrag;
     /** `item.width`/`height`, else origin's `naturalWidth`/`naturalHeight` (accurate when `item.thumb` is unset). Feeds `computeTransform`'s letterbox-aware sizing. */
     private resolveAspectRatio;
     /**

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

@@ -1,12 +1,15 @@
 import { GestureEngineOptions } from '../gestures/GestureEngine';
 import { SlideManager } from './SlideManager';
+import { FrozenDragTransform } from './zoomTransition';
 /**
- * A real interactive control. Also used by `Gallery.ts`'s `isBackdropClick`,
- * which used to have its own narrower list (missing select/input/textarea/
- * a[href]) — a plugin-mounted non-button control got misread as a backdrop
- * click and closed the gallery. One shared selector so that can't recur.
+ * A real interactive control, plus `.shoji-caption` — a click/drag starting
+ * there should select/scroll its text natively, not get captured as a
+ * gesture. Also used by `Gallery.ts`'s `isBackdropClick`, which used to have
+ * its own narrower list (missing select/input/textarea/a[href]) — a
+ * plugin-mounted non-button control got misread as a backdrop click and
+ * closed the gallery. One shared selector so that can't recur.
  */
-export declare const INTERACTIVE_CONTROL_SELECTOR = "button, video, input, select, textarea, a[href], [data-shoji-no-drag]";
+export declare const INTERACTIVE_CONTROL_SELECTOR = "button, video, input, select, textarea, a[href], [data-shoji-no-drag], .shoji-caption";
 /** What `GestureController` needs from `Gallery` — narrow on purpose, so this module never reaches into Gallery internals beyond this contract. */
 export interface GestureControllerHost {
     dialog: HTMLElement;
@@ -16,6 +19,10 @@ export interface GestureControllerHost {
     next(): void;
     prev(): void;
     close(): void;
+    /** Same effect as `close()`, but for a completed vertical swipe — skips the separate controls-fade pause in front of the zoom-out (see `finishVerticalDrag`). */
+    closeFromSwipe(frozenDrag: FrozenDragTransform): void;
+    /** Live, reversible — crossing the close threshold mid-drag hides the toolbar/nav/counter/caption (a "let go now and this closes" cue); dragging back under it before release reveals them again. See `applyVerticalDragFeedback`. */
+    setControlsHiddenForDrag(hidden: boolean): void;
     /** `closable: false` (GalleryOptions) — false suspends vertical drag-to-close entirely: no live feedback, release never calls `close()`. */
     canClose(): boolean;
     onActivity(): void;
@@ -42,6 +49,10 @@ export interface GestureRelayCallbacks {
 export declare class GestureController {
     private readonly host;
     private readonly engine;
+    /** Same distance `GestureEngine` itself uses to decide a release would complete the close — reused here so the live controls-hide cue in `applyVerticalDragFeedback` actually means what it visually claims. */
+    private readonly controlsHideThreshold;
+    private controlsHiddenForDrag;
+    private lastDragDelta;
     constructor(host: GestureControllerHost, relay: GestureRelayCallbacks, options?: Partial<GestureEngineOptions>);
     destroy(): void;
     /** Horizontal follows the finger 1:1; vertical drives close-feedback instead. Axis-locked, one branch per drag. */
@@ -50,8 +61,33 @@ export declare class GestureController {
     /** `completed` decides intent; `canGoNext`/`canGoPrev` guard whether that's actually possible (`loop: false` at an end item). */
     private finishHorizontalDrag;
     private settleDragOffset;
-    /** Purely presentational drag feedback — scales/fades the dialog toward `close()`'s target state as the viewer drags, without closing until release decides the outcome. */
+    /**
+     * Purely presentational — scales/fades the *image* as it's dragged away,
+     * without closing until release decides. Applied to `host.slides.element`,
+     * not `host.dialog` — requested directly: toolbar/nav/counter/caption are
+     * siblings, not descendants, so they stay anchored, not moving with it.
+     */
     private applyVerticalDragFeedback;
     private clearVerticalDragFeedback;
     private finishVerticalDrag;
+    /**
+     * Reads the drag's last live appearance, instantly resets `.shoji-slides`
+     * back to neutral (nothing left on it to visibly snap — `Gallery` bakes
+     * these same values onto the photo itself in the same synchronous tick,
+     * so the rendered result is unchanged, just re-homed), and returns them
+     * for that hand-off. Translate is the raw, unclamped drag distance —
+     * requested directly: the close animation must continue from exactly
+     * where the drag left off, full stop, not recenter first. (A previous
+     * version clamped this to the same 160px the dim/scale feedback ramps
+     * over, to bound how far away the close animation could start — but
+     * clamping is itself an instant correction: for any drag past that
+     * distance, release visibly snapped the photo from wherever it actually
+     * was back to the clamped point, before the real shrink-to-thumbnail
+     * motion continued from there. That snap — not the shrink itself — is
+     * what reads as "jumps to a small image in the middle of the screen."
+     * Reported from real usage, confirmed on video: released past the clamp,
+     * the photo visibly jumped from off-screen back to near-center in a
+     * single frame.)
+     */
+    private takeFrozenDragTransform;
 }

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

@@ -7,6 +7,7 @@ export interface LightboxLabels {
 }
 export interface LightboxDom {
     outer: HTMLElement;
+    backdrop: HTMLElement;
     dialog: HTMLElement;
     counter: HTMLElement;
     caption: HTMLElement;

package/dist/esm/core/index.js

@@ -1,24 +1,69 @@
 var __defProp = Object.defineProperty;
 var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
 var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
-import { w as waitForTransitionEnd, c as containedBox, z as zoomIn, a as zoomOut } from "../zoomTransition-2_HG7tyJ.js";
+import { w as waitForTransitionEnd, c as containedBox, z as zoomIn, a as zoomOut } from "../zoomTransition-BeIimqDT.js";
 let lockCount = 0;
-let savedOverflow = "";
 let savedHtmlOverflow = "";
+let savedHtmlPaddingRight = "";
+let savedHtmlPaddingLeft = "";
+let savedScrollX = 0;
+let savedScrollY = 0;
+let styleObserver = null;
+const LIGHTBOX_SELECTOR = ".shoji-outer";
+function isRtl() {
+  return getComputedStyle(document.documentElement).direction === "rtl";
+}
+function onTouchMove(event) {
+  const target = event.target;
+  const insideLightbox = target instanceof Element && target.closest(LIGHTBOX_SELECTOR) !== null;
+  if (!insideLightbox) 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) {
-    savedOverflow = document.body.style.overflow;
-    document.body.style.overflow = "hidden";
+    savedScrollX = window.scrollX;
+    savedScrollY = window.scrollY;
+    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("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) {
-    document.body.style.overflow = savedOverflow;
+    styleObserver == null ? void 0 : styleObserver.disconnect();
+    styleObserver = null;
+    document.removeEventListener("touchmove", onTouchMove);
     document.documentElement.style.overflow = savedHtmlOverflow;
+    document.documentElement.style.paddingRight = savedHtmlPaddingRight;
+    document.documentElement.style.paddingLeft = savedHtmlPaddingLeft;
+    window.scrollTo({ left: savedScrollX, top: savedScrollY, behavior: "instant" });
   }
 }
 class EventBus {
@@ -108,6 +153,7 @@ function buildLightboxDom(slides, labels) {
   outer.appendChild(dialog);
   return {
     outer,
+    backdrop,
     dialog,
     counter,
     caption,
@@ -181,6 +227,8 @@ class GestureEngine {
     // along the locked axis, at the moment direction locked — subtracted so onDragStart's delta is 0
     __publicField(this, "pinching", false);
     __publicField(this, "pinchStartDistance", 0);
+    /** True once `setPointerCapture` has actually been called for the gesture currently in progress — see `suppressRetargetedClick`'s own doc comment for why this needs tracking separately from `direction`. */
+    __publicField(this, "capturedThisGesture", false);
     // -Infinity, not 0: `event.timeStamp` is time-since-navigation-start, so a
     // real first tap is always some large positive number and 0 would seem
     // like a safe "no previous tap" sentinel in practice — but not always: a
@@ -206,6 +254,7 @@ class GestureEngine {
       if (this.pointers.size === 1) {
         this.primaryPointerId = event.pointerId;
         this.direction = null;
+        this.capturedThisGesture = false;
       } else if (this.pointers.size === 2) {
         this.direction = null;
         this.pinching = true;
@@ -240,7 +289,10 @@ class GestureEngine {
         if (Math.max(absX, absY) < this.options.lockThreshold) return;
         this.direction = absX > absY ? "horizontal" : "vertical";
         this.dragStartDistance = this.direction === "horizontal" ? dx : dy;
-        if (((_d = (_c = this.callbacks).shouldCapture) == null ? void 0 : _d.call(_c)) ?? true) this.target.setPointerCapture(event.pointerId);
+        if (((_d = (_c = this.callbacks).shouldCapture) == null ? void 0 : _d.call(_c)) ?? true) {
+          this.target.setPointerCapture(event.pointerId);
+          this.capturedThisGesture = true;
+        }
         (_f = (_e = this.callbacks).onDragStart) == null ? void 0 : _f.call(_e, this.direction, event);
       }
       if (this.direction === "horizontal") event.preventDefault();
@@ -307,9 +359,30 @@ class GestureEngine {
       const velocity = totalDelta / elapsed;
       const completed = !cancelled && (Math.abs(totalDelta) >= this.options.swipeThreshold || Math.abs(velocity) >= this.options.swipeVelocity);
       (_d = (_c = this.callbacks).onDragEnd) == null ? void 0 : _d.call(_c, this.direction, totalDelta, velocity, completed, cancelled);
+      if (this.capturedThisGesture) this.suppressRetargetedClick();
     }
     this.primaryPointerId = null;
     this.direction = null;
+    this.capturedThisGesture = false;
+  }
+  /**
+   * A captured pointer's release still fires a real `click`, retargeted to
+   * `target` regardless of where the pointer visually ends up — misread by
+   * Gallery's click-outside-to-close as landing nowhere recognizable.
+   * Consumes exactly one `click` on `target` in the capture phase, then
+   * removes itself; a fallback timeout also removes it in case no `click`
+   * ever comes, so it can't swallow a later, unrelated one.
+   */
+  suppressRetargetedClick() {
+    let done = false;
+    const cleanup = (event) => {
+      if (done) return;
+      done = true;
+      event == null ? void 0 : event.stopPropagation();
+      this.target.removeEventListener("click", cleanup, { capture: true });
+    };
+    this.target.addEventListener("click", cleanup, { capture: true });
+    setTimeout(cleanup, 500);
   }
   registerTap(x, y, event) {
     var _a, _b, _c, _d;
@@ -335,13 +408,17 @@ function centerOf(a, b) {
 const DRAG_SETTLE_TRANSITION = "transform var(--shoji-duration) var(--shoji-momentum-easing)";
 const DRAG_FEEDBACK_TRANSITION = "transform var(--shoji-duration) var(--shoji-momentum-easing), opacity var(--shoji-duration) var(--shoji-momentum-easing)";
 const VERTICAL_FEEDBACK_DISTANCE = 160;
-const INTERACTIVE_CONTROL_SELECTOR = "button, video, input, select, textarea, a[href], [data-shoji-no-drag]";
+const INTERACTIVE_CONTROL_SELECTOR = "button, video, input, select, textarea, a[href], [data-shoji-no-drag], .shoji-caption";
 function shouldIgnoreGesture(event) {
   return event.composedPath().some((node) => node instanceof Element && node.matches(INTERACTIVE_CONTROL_SELECTOR));
 }
 class GestureController {
   constructor(host, relay, options) {
     __publicField(this, "engine");
+    /** Same distance `GestureEngine` itself uses to decide a release would complete the close — reused here so the live controls-hide cue in `applyVerticalDragFeedback` actually means what it visually claims. */
+    __publicField(this, "controlsHideThreshold");
+    __publicField(this, "controlsHiddenForDrag", false);
+    __publicField(this, "lastDragDelta", 0);
     /** Horizontal follows the finger 1:1; vertical drives close-feedback instead. Axis-locked, one branch per drag. */
     __publicField(this, "onDragMove", (direction, delta) => {
       if (this.host.isZoomed()) return;
@@ -360,6 +437,7 @@ class GestureController {
       }
     });
     this.host = host;
+    this.controlsHideThreshold = (options == null ? void 0 : options.swipeThreshold) ?? 50;
     this.engine = new GestureEngine(
       host.dialog,
       {
@@ -407,28 +485,70 @@ class GestureController {
     }
     waitForTransitionEnd(settleEl, onSettled);
   }
-  /** Purely presentational drag feedback — scales/fades the dialog toward `close()`'s target state as the viewer drags, without closing until release decides the outcome. */
+  /**
+   * Purely presentational — scales/fades the *image* as it's dragged away,
+   * without closing until release decides. Applied to `host.slides.element`,
+   * not `host.dialog` — requested directly: toolbar/nav/counter/caption are
+   * siblings, not descendants, so they stay anchored, not moving with it.
+   */
   applyVerticalDragFeedback(delta) {
     const progress = Math.min(Math.abs(delta) / VERTICAL_FEEDBACK_DISTANCE, 1);
-    const dialog = this.host.dialog;
-    dialog.style.transition = "";
-    dialog.style.transform = `translateY(${delta}px) scale(${1 - progress * 0.15})`;
-    dialog.style.opacity = String(1 - progress * 0.6);
+    const slides = this.host.slides.element;
+    this.lastDragDelta = delta;
+    slides.style.transition = "";
+    slides.style.transform = `translateY(${delta}px) scale(${1 - progress * 0.15})`;
+    slides.style.opacity = String(1 - progress * 0.6);
+    const pastThreshold = Math.abs(delta) >= this.controlsHideThreshold;
+    if (pastThreshold !== this.controlsHiddenForDrag) {
+      this.controlsHiddenForDrag = pastThreshold;
+      this.host.setControlsHiddenForDrag(pastThreshold);
+    }
   }
   clearVerticalDragFeedback(animate) {
-    const dialog = this.host.dialog;
-    dialog.style.transition = animate ? DRAG_FEEDBACK_TRANSITION : "";
-    dialog.style.transform = "";
-    dialog.style.opacity = "";
+    const slides = this.host.slides.element;
+    slides.style.transition = animate ? DRAG_FEEDBACK_TRANSITION : "";
+    slides.style.transform = "";
+    slides.style.opacity = "";
   }
   finishVerticalDrag(completed) {
+    const wasHiddenForDrag = this.controlsHiddenForDrag;
+    this.controlsHiddenForDrag = false;
     if (completed && this.host.canClose()) {
-      this.clearVerticalDragFeedback(false);
-      this.host.close();
+      this.host.closeFromSwipe(this.takeFrozenDragTransform());
     } else {
       this.clearVerticalDragFeedback(true);
+      if (wasHiddenForDrag) this.host.setControlsHiddenForDrag(false);
     }
   }
+  /**
+   * Reads the drag's last live appearance, instantly resets `.shoji-slides`
+   * back to neutral (nothing left on it to visibly snap — `Gallery` bakes
+   * these same values onto the photo itself in the same synchronous tick,
+   * so the rendered result is unchanged, just re-homed), and returns them
+   * for that hand-off. Translate is the raw, unclamped drag distance —
+   * requested directly: the close animation must continue from exactly
+   * where the drag left off, full stop, not recenter first. (A previous
+   * version clamped this to the same 160px the dim/scale feedback ramps
+   * over, to bound how far away the close animation could start — but
+   * clamping is itself an instant correction: for any drag past that
+   * distance, release visibly snapped the photo from wherever it actually
+   * was back to the clamped point, before the real shrink-to-thumbnail
+   * motion continued from there. That snap — not the shrink itself — is
+   * what reads as "jumps to a small image in the middle of the screen."
+   * Reported from real usage, confirmed on video: released past the clamp,
+   * the photo visibly jumped from off-screen back to near-center in a
+   * single frame.)
+   */
+  takeFrozenDragTransform() {
+    const progress = Math.min(Math.abs(this.lastDragDelta) / VERTICAL_FEEDBACK_DISTANCE, 1);
+    const frozen = {
+      translateY: this.lastDragDelta,
+      scale: 1 - progress * 0.15,
+      opacity: 1 - progress * 0.6
+    };
+    this.clearVerticalDragFeedback(false);
+    return frozen;
+  }
 }
 class LiveRegion {
   constructor() {
@@ -1344,7 +1464,7 @@ const DEFAULT_LOCALE = {
 function isBackdropClick(event) {
   return !event.composedPath().some(
     (node) => node instanceof Element && node.matches(
-      `.shoji-slide-img, .shoji-slide-provider-video, .shoji-counter, .shoji-caption, ${INTERACTIVE_CONTROL_SELECTOR}`
+      `.shoji-slide-img, .shoji-slide-provider-video, .shoji-counter, ${INTERACTIVE_CONTROL_SELECTOR}`
     )
   );
 }
@@ -1373,6 +1493,8 @@ class Gallery {
     __publicField(this, "autoHidden", false);
     __publicField(this, "hoveredControlCount", 0);
     __publicField(this, "isClosing", false);
+    /** 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. */
+    __publicField(this, "controlsHiddenByDrag", false);
     __publicField(this, "itemList", []);
     __publicField(this, "scannedElements", []);
     __publicField(this, "activeIndex", 0);
@@ -1406,9 +1528,21 @@ class Gallery {
     __publicField(this, "onOuterClick", (event) => {
       if (this.closable && isBackdropClick(event)) this.close();
     });
-    /** DESIGN.md §2.8 — any interaction re-shows controls, restarts the idle clock. `autoHideDelay: 0` = "never show controls" — a no-op here. */
+    /**
+     * DESIGN.md §2.8 — any interaction re-shows controls, restarts the idle
+     * clock. `autoHideDelay: 0` = "never show controls" — a no-op here.
+     * `autoHideDelay: false` = "always visible" — also a no-op: nothing to
+     * reveal (already shown) or reschedule (no timer ever runs). Also a no-op
+     * once `isClosing` — a real bug, reported from real usage: moving the
+     * mouse during close()'s own controls-fade-then-zoom-out sequence (§2.6a)
+     * re-showed the just-hidden controls mid-animation, since these listeners
+     * stay wired for the whole close sequence. Same reasoning for
+     * `controlsHiddenByDrag` (§2.4/§2.8): a vertical drag's own `pointermove`
+     * stream would otherwise re-reveal what it just hid, every single frame.
+     */
     __publicField(this, "onActivity", () => {
-      if (this.autoHideDelay === 0) return;
+      if (this.autoHideDelay === 0 || this.autoHideDelay === false || this.isClosing || this.controlsHiddenByDrag)
+        return;
       this.showControls();
       this.scheduleAutoHide();
     });
@@ -1538,6 +1672,11 @@ class Gallery {
     this.transition = new SlideTransition(this.slides);
     const dom = buildLightboxDom(this.slides.element, this.locale);
     this.dom = dom;
+    if (this.options.backdropOpacity != null) {
+      const clamped = Math.min(Math.max(this.options.backdropOpacity, 0), 1);
+      dom.outer.style.setProperty("--shoji-backdrop-opacity", String(clamped));
+    }
+    if (this.autoHideDelay === 0) dom.dialog.classList.add("shoji-cursor-visible");
     dom.outer.appendChild(this.liveRegion.element);
     dom.closeButton.addEventListener("click", () => this.close());
     dom.prevButton.addEventListener("click", () => this.prev());
@@ -1580,6 +1719,8 @@ class Gallery {
         next: () => this.navigate(this.nextIndex(), 1, false),
         prev: () => this.navigate(this.prevIndex(), -1, false),
         close: () => this.close(),
+        closeFromSwipe: (frozenDrag) => this.closeFromSwipe(frozenDrag),
+        setControlsHiddenForDrag: (hidden) => this.setControlsHiddenForDrag(hidden),
         canClose: () => this.closable,
         onActivity: () => this.onActivity(),
         isZoomed: () => {
@@ -1761,15 +1902,28 @@ class Gallery {
       this.autoHideTimer = null;
     }
     if (!this.opened) return;
+    if (this.autoHideDelay === false) return;
     if (this.autoHideDelay === 0) {
       this.hideControls();
       return;
     }
     this.autoHideTimer = setTimeout(() => this.hideControls(), this.autoHideDelay);
   }
-  /** Forces the same fade §2.8's idle timer would eventually trigger — public so a plugin can hide controls on its own trigger. Same `isControlActive()` guard as the timer. */
+  /**
+   * Forces the same fade §2.8's idle timer would eventually trigger —
+   * public so a plugin can hide controls on its own trigger. Same
+   * `isControlActive()` guard as the timer. Also a no-op under
+   * `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()`/
+   * `setControlsHiddenForDrag()` (close, drag-to-close) deliberately don't
+   * check this — direct user actions with their own feedback, not auto-hide.
+   */
   hideControls() {
-    if (!this.dom || this.autoHidden || this.isControlActive()) return;
+    if (!this.dom || this.autoHidden || this.isControlActive() || this.autoHideDelay === false)
+      return;
     this.autoHidden = true;
     this.dom.dialog.classList.add("shoji-controls-hidden");
     this.bus.emit("controls:hide", {});
@@ -1996,6 +2150,31 @@ class Gallery {
     }
   }
   close() {
+    this.beginClose();
+  }
+  /**
+   * DESIGN.md §2.4/§2.6a — same effect as `close()`, from a completed
+   * vertical swipe. `frozenDrag` is threaded through to `zoomOut()`'s own
+   * `dragStart`, so the whole close continues as one motion from exactly
+   * where the drag left off (see `GestureController.
+   * takeFrozenDragTransform`).
+   */
+  closeFromSwipe(frozenDrag) {
+    this.beginClose(frozenDrag);
+  }
+  /**
+   * `frozenDrag` — see `closeFromSwipe()`'s doc comment; absent for a
+   * button-close, which has no drag to continue from. Controls fade and the
+   * zoom-out run concurrently, both starting the instant `forceHideControls()`
+   * runs — not sequenced one after the other. (A previous version waited for
+   * the controls' own fade to fully finish before starting the zoom-out, for
+   * a button-close specifically — requested directly, to avoid stationary
+   * chrome hovering over an already-shrinking photo. Reversed on later,
+   * explicit feedback: waiting read as two distinct steps rather than one
+   * motion; starting both together still avoids stationary chrome, since
+   * the chrome is disappearing too, just without the pause.)
+   */
+  beginClose(frozenDrag) {
     var _a, _b;
     if (this.destroyed || !this.opened || this.isClosing) return;
     this.bus.emit("beforeClose", {});
@@ -2006,11 +2185,41 @@ class Gallery {
     const naturalSize = this.resolveNaturalSize(this.activeIndex);
     if (media && origin && (((_b = this.slides) == null ? void 0 : _b.isActiveReady()) || naturalSize)) {
       const aspectRatio = this.resolveAspectRatio(this.activeIndex, origin);
-      zoomOut({ origin, target: media, aspectRatio, naturalSize }, () => this.finishClose());
+      this.forceHideControls();
+      if (this.dom) this.dom.backdrop.style.opacity = "0";
+      zoomOut(
+        { origin, target: media, aspectRatio, naturalSize, dragStart: frozenDrag },
+        () => this.finishClose()
+      );
     } else {
       this.finishClose();
     }
   }
+  /** 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. */
+  forceHideControls() {
+    if (!this.dom || this.autoHidden) return;
+    this.autoHidden = true;
+    this.dom.dialog.classList.add("shoji-controls-hidden");
+    this.bus.emit("controls:hide", {});
+  }
+  /**
+   * DESIGN.md §2.4/§2.8 — `GestureController`'s live vertical-drag cue: hide
+   * past the same distance a release would close, reveal again on retreat.
+   * `hidden: false` only reveals if visible when *this* gesture started
+   * (`controlsHiddenAtGestureStart`) — shouldn't resurrect controls already
+   * separately hidden (idle, or `autoHideDelay: 0`) before the drag began.
+   * `dragCloseThreshold` (bus event) fires on every crossing regardless of
+   * that guard — Autoplay (§4-autoplay) needs to know about the crossing
+   * itself, not just whether controls visibly moved.
+   */
+  setControlsHiddenForDrag(hidden) {
+    var _a;
+    this.controlsHiddenByDrag = hidden;
+    if (hidden) this.forceHideControls();
+    else if (!this.controlsHiddenAtGestureStart) this.showControls();
+    (_a = this.dom) == null ? void 0 : _a.dialog.classList.toggle("shoji-controls-hidden-for-drag", hidden);
+    this.bus.emit("dragCloseThreshold", { hidden });
+  }
   /** `item.width`/`height`, else origin's `naturalWidth`/`naturalHeight` (accurate when `item.thumb` is unset). Feeds `computeTransform`'s letterbox-aware sizing. */
   resolveAspectRatio(index, origin) {
     const item = this.itemList[index];
@@ -2041,7 +2250,7 @@ class Gallery {
    * instead of a second `close`/`afterClose` emission on a torn-down gallery.
    */
   finishClose() {
-    var _a, _b;
+    var _a, _b, _c;
     if (!this.opened) return;
     this.isClosing = false;
     this.opened = false;
@@ -2049,13 +2258,16 @@ class Gallery {
     document.removeEventListener("keydown", this.onKeydown);
     this.focusTrap.deactivate();
     (_a = this.dom) == null ? void 0 : _a.outer.classList.remove("shoji-open");
+    if (this.dom) this.dom.backdrop.style.opacity = "";
     if (this.autoHideTimer !== null) {
       clearTimeout(this.autoHideTimer);
       this.autoHideTimer = null;
     }
     this.autoHidden = false;
     this.hoveredControlCount = 0;
+    this.controlsHiddenByDrag = false;
     (_b = this.dom) == null ? void 0 : _b.dialog.classList.remove("shoji-controls-hidden");
+    (_c = this.dom) == null ? void 0 : _c.dialog.classList.remove("shoji-controls-hidden-for-drag");
     this.bus.emit("close", {});
     this.bus.emit("afterClose", {});
   }