@michaelyagi/shoji 0.1.0-alpha.6

package/dist/esm/plugins/video/index.js

@@ -0,0 +1,95 @@
+let apiPromise = null;
+function loadYouTubeApi() {
+  var _a;
+  if ((_a = window.YT) == null ? void 0 : _a.Player) return Promise.resolve(window.YT);
+  if (apiPromise) return apiPromise;
+  apiPromise = new Promise((resolve) => {
+    const previous = window.onYouTubeIframeAPIReady;
+    window.onYouTubeIframeAPIReady = () => {
+      previous == null ? void 0 : previous();
+      resolve(window.YT);
+    };
+    const script = document.createElement("script");
+    script.src = "https://www.youtube.com/iframe_api";
+    document.head.appendChild(script);
+  });
+  return apiPromise;
+}
+function wirePlayableContract(container, player) {
+  const playable = container;
+  playable.paused = true;
+  playable.ended = false;
+  playable.play = () => player.playVideo();
+  playable.pause = () => player.pauseVideo();
+  Object.defineProperty(playable, "muted", {
+    configurable: true,
+    get: () => player.isMuted(),
+    set: (value) => value ? player.mute() : player.unMute()
+  });
+  return playable;
+}
+function handleStateChange(event, YT, playable) {
+  if (event.data === YT.PlayerState.PLAYING) {
+    playable.paused = false;
+    playable.dispatchEvent(new Event("play"));
+  } else if (event.data === YT.PlayerState.PAUSED) {
+    playable.paused = true;
+    playable.dispatchEvent(new Event("pause"));
+  } else if (event.data === YT.PlayerState.ENDED) {
+    playable.paused = true;
+    playable.ended = true;
+    playable.dispatchEvent(new Event("ended"));
+  }
+}
+const renderYouTube = (container, item, onReady, signal) => {
+  var _a;
+  if (((_a = item.video) == null ? void 0 : _a.provider) !== "youtube") return;
+  const videoId = item.video.id;
+  const mount = document.createElement("div");
+  container.appendChild(mount);
+  loadYouTubeApi().then((YT) => {
+    if (signal.aborted) return;
+    const playable = container;
+    const player = new YT.Player(mount, {
+      videoId,
+      playerVars: { playsinline: 1, rel: 0 },
+      events: {
+        // `new YT.Player()` returns before the embed's own internal bootstrap
+        // (its postMessage handshake with youtube.com) finishes — calling
+        // `player.mute()`/`playVideo()`/etc. before that completes can throw
+        // ("player.isMuted is not a function") or silently no-op, even though
+        // the constructor already returned an object. `onReady` is YouTube's
+        // own signal that the real API surface is actually callable now, so
+        // wiring the contract here — not synchronously after construction —
+        // is what makes `findPlayable()`'s "is `.play` wired?" check in
+        // Autoplay (DESIGN.md §4.1) an accurate proxy for "is it really
+        // ready?" instead of just "did we build the wrapper closures?".
+        onReady: () => {
+          wirePlayableContract(container, player);
+          onReady();
+        },
+        onStateChange: (event) => handleStateChange(event, YT, playable),
+        // bubbles: true — reaches .shoji-slide-media (the pool slot, always
+        // present regardless of readiness) without needing wirePlayableContract
+        // to have run first; onError can fire instead of onReady entirely
+        // (e.g. a removed/private video), so playable isn't a safe assumption
+        // here the way it is in onStateChange. Autoplay (DESIGN.md §4.1)
+        // listens for this to skip to the next slide instead of stalling.
+        onError: (event) => playable.dispatchEvent(
+          new CustomEvent("error", { bubbles: true, detail: { code: event.data } })
+        )
+      }
+    });
+    signal.addEventListener("abort", () => player.destroy(), { once: true });
+  });
+};
+const Video = {
+  name: "video",
+  init(ctx) {
+    return ctx.ui.registerVideoProvider("youtube", renderYouTube);
+  }
+};
+export {
+  Video
+};
+//# sourceMappingURL=index.js.map

package/dist/esm/plugins/video/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../../../../src/plugins/video/youtube.ts","../../../../src/plugins/video/index.ts"],"sourcesContent":["import type { VideoProviderRenderer } from '../../core/plugin';\n\n/**\n * The bits of the YouTube IFrame Player API actually used here — not in\n * `lib.dom.d.ts` (a third-party global loaded on demand), so this is a\n * documented interop boundary (CLAUDE.md: `any` only there). Kept\n * intentionally minimal, not a full mirror of YouTube's own typings.\n */\ninterface YTPlayer {\n  playVideo(): void;\n  pauseVideo(): void;\n  mute(): void;\n  unMute(): void;\n  isMuted(): boolean;\n  destroy(): void;\n}\n\ninterface YTPlayerStateEvent {\n  data: number;\n}\n\n/**\n * Same `{ data: number }` shape as `YTPlayerStateEvent` — `data` holds an\n * error code there (2 invalid parameter, 5 HTML5 player error, 100 video\n * not found/private, 101/150 embedding disabled by the owner; undocumented\n * codes like 153 are also reported in the wild) rather than a player state.\n * Named separately from `YTPlayerStateEvent` for readability at the call\n * site, not because the shape actually differs.\n */\ninterface YTPlayerErrorEvent {\n  data: number;\n}\n\ninterface YTNamespace {\n  Player: new (\n    el: HTMLElement,\n    opts: {\n      videoId: string;\n      playerVars?: { playsinline?: 0 | 1; rel?: 0 | 1 };\n      events?: {\n        onReady?: () => void;\n        onStateChange?: (event: YTPlayerStateEvent) => void;\n        onError?: (event: YTPlayerErrorEvent) => void;\n      };\n    },\n  ) => YTPlayer;\n  PlayerState: { ENDED: number; PLAYING: number; PAUSED: number };\n}\n\ndeclare global {\n  interface Window {\n    YT?: YTNamespace;\n    onYouTubeIframeAPIReady?: () => void;\n  }\n}\n\nlet apiPromise: Promise<YTNamespace> | null = null;\n\n/**\n * Loads `https://www.youtube.com/iframe_api` exactly once however many\n * YouTube slides/galleries end up on a page — the API itself is a single\n * global (`window.YT`), and re-injecting the script tag would be wasteful\n * and risks a second, conflicting `onYouTubeIframeAPIReady` firing. Composes\n * with a host's own `onYouTubeIframeAPIReady`, if one already exists\n * (e.g. the host embeds YouTube elsewhere too), instead of clobbering it.\n */\nfunction loadYouTubeApi(): Promise<YTNamespace> {\n  if (window.YT?.Player) return Promise.resolve(window.YT);\n  if (apiPromise) return apiPromise;\n\n  apiPromise = new Promise((resolve) => {\n    const previous = window.onYouTubeIframeAPIReady;\n    window.onYouTubeIframeAPIReady = () => {\n      previous?.();\n      resolve(window.YT!);\n    };\n    const script = document.createElement('script');\n    script.src = 'https://www.youtube.com/iframe_api';\n    document.head.appendChild(script);\n  });\n  return apiPromise;\n}\n\n/**\n * DESIGN.md §4-autoplay — Autoplay looks for exactly this shape (`.play`/\n * `.pause`/`.paused`/`.ended`, plus real `play`/`pause`/`ended` DOM events)\n * on whatever's active, native `<video>` or not. Augmenting `container`\n * this way is what makes slideshow sync work without Autoplay ever having\n * to know YouTube — or any other provider — exists.\n */\ntype PlayableElement = HTMLElement & {\n  play: () => void;\n  pause: () => void;\n  paused: boolean;\n  ended: boolean;\n  muted: boolean;\n};\n\n/**\n * `muted` is a real accessor (not a plain property) backed by the player's\n * own `mute()`/`unMute()`/`isMuted()` — DESIGN.md §4.1's autoplay-policy fix\n * sets `video.muted = true` right before an *automatic* play, the same way\n * it would for a native `<video>`; a plain property here would just be\n * inert state that never actually silences the embed.\n */\nfunction wirePlayableContract(container: HTMLElement, player: YTPlayer): PlayableElement {\n  const playable = container as PlayableElement;\n  playable.paused = true;\n  playable.ended = false;\n  playable.play = () => player.playVideo();\n  playable.pause = () => player.pauseVideo();\n  Object.defineProperty(playable, 'muted', {\n    configurable: true,\n    get: () => player.isMuted(),\n    set: (value: boolean) => (value ? player.mute() : player.unMute()),\n  });\n  return playable;\n}\n\nfunction handleStateChange(\n  event: YTPlayerStateEvent,\n  YT: YTNamespace,\n  playable: PlayableElement,\n): void {\n  if (event.data === YT.PlayerState.PLAYING) {\n    playable.paused = false;\n    playable.dispatchEvent(new Event('play'));\n  } else if (event.data === YT.PlayerState.PAUSED) {\n    playable.paused = true;\n    playable.dispatchEvent(new Event('pause'));\n  } else if (event.data === YT.PlayerState.ENDED) {\n    playable.paused = true;\n    playable.ended = true;\n    playable.dispatchEvent(new Event('ended'));\n  }\n}\n\n/**\n * DESIGN.md §4-video — no poster/thumbnail handling at all: the slide shows\n * nothing until the embed itself is ready (same spinner-then-reveal every\n * other slide type gets), never an auto-fetched or guessed preview image.\n */\nexport const renderYouTube: VideoProviderRenderer = (container, item, onReady, signal) => {\n  if (item.video?.provider !== 'youtube') return;\n  const videoId = item.video.id;\n\n  const mount = document.createElement('div');\n  container.appendChild(mount);\n\n  loadYouTubeApi().then((YT) => {\n    if (signal.aborted) return; // navigated away before the (possibly first-ever, slow) API load resolved\n\n    const playable = container as PlayableElement;\n    const player = new YT.Player(mount, {\n      videoId,\n      playerVars: { playsinline: 1, rel: 0 },\n      events: {\n        // `new YT.Player()` returns before the embed's own internal bootstrap\n        // (its postMessage handshake with youtube.com) finishes — calling\n        // `player.mute()`/`playVideo()`/etc. before that completes can throw\n        // (\"player.isMuted is not a function\") or silently no-op, even though\n        // the constructor already returned an object. `onReady` is YouTube's\n        // own signal that the real API surface is actually callable now, so\n        // wiring the contract here — not synchronously after construction —\n        // is what makes `findPlayable()`'s \"is `.play` wired?\" check in\n        // Autoplay (DESIGN.md §4.1) an accurate proxy for \"is it really\n        // ready?\" instead of just \"did we build the wrapper closures?\".\n        onReady: () => {\n          wirePlayableContract(container, player);\n          onReady();\n        },\n        onStateChange: (event) => handleStateChange(event, YT, playable),\n        // bubbles: true — reaches .shoji-slide-media (the pool slot, always\n        // present regardless of readiness) without needing wirePlayableContract\n        // to have run first; onError can fire instead of onReady entirely\n        // (e.g. a removed/private video), so playable isn't a safe assumption\n        // here the way it is in onStateChange. Autoplay (DESIGN.md §4.1)\n        // listens for this to skip to the next slide instead of stalling.\n        onError: (event) =>\n          playable.dispatchEvent(\n            new CustomEvent('error', { bubbles: true, detail: { code: event.data } }),\n          ),\n      },\n    });\n    signal.addEventListener('abort', () => player.destroy(), { once: true });\n  });\n};\n","import type { PluginContext, ShojiPlugin } from '../../core/plugin';\nimport { renderYouTube } from './youtube';\n\n/**\n * DESIGN.md §4-video — renders `{ video: { provider: 'youtube', id } }`\n * items (produced by `scan.ts`'s `data-shoji-video` host detection, or\n * authored directly in dynamic mode) as a real YouTube embed instead of\n * `SlideManager`'s native-`<video>` fallback, which can't play a YouTube\n * URL at all. Purely a renderer: no options, no toolbar button, no poster/\n * thumbnail handling — the slide shows nothing until the embed itself is\n * ready, same as every other slide type. Autoplay (§4-autoplay) picks up\n * real play/pause/ended sync automatically; see `youtube.ts`'s\n * `wirePlayableContract`.\n */\nexport const Video: ShojiPlugin = {\n  name: 'video',\n\n  init(ctx: PluginContext): () => void {\n    return ctx.ui.registerVideoProvider('youtube', renderYouTube);\n  },\n};\n"],"names":[],"mappings":"AAwDA,IAAI,aAA0C;AAU9C,SAAS,iBAAuC;AAVhD;AAWE,OAAI,YAAO,OAAP,mBAAW,eAAe,QAAQ,QAAQ,OAAO,EAAE;AACvD,MAAI,WAAY,QAAO;AAEvB,eAAa,IAAI,QAAQ,CAAC,YAAY;AACpC,UAAM,WAAW,OAAO;AACxB,WAAO,0BAA0B,MAAM;AACrC;AACA,cAAQ,OAAO,EAAG;AAAA,IACpB;AACA,UAAM,SAAS,SAAS,cAAc,QAAQ;AAC9C,WAAO,MAAM;AACb,aAAS,KAAK,YAAY,MAAM;AAAA,EAClC,CAAC;AACD,SAAO;AACT;AAwBA,SAAS,qBAAqB,WAAwB,QAAmC;AACvF,QAAM,WAAW;AACjB,WAAS,SAAS;AAClB,WAAS,QAAQ;AACjB,WAAS,OAAO,MAAM,OAAO,UAAA;AAC7B,WAAS,QAAQ,MAAM,OAAO,WAAA;AAC9B,SAAO,eAAe,UAAU,SAAS;AAAA,IACvC,cAAc;AAAA,IACd,KAAK,MAAM,OAAO,QAAA;AAAA,IAClB,KAAK,CAAC,UAAoB,QAAQ,OAAO,KAAA,IAAS,OAAO,OAAA;AAAA,EAAO,CACjE;AACD,SAAO;AACT;AAEA,SAAS,kBACP,OACA,IACA,UACM;AACN,MAAI,MAAM,SAAS,GAAG,YAAY,SAAS;AACzC,aAAS,SAAS;AAClB,aAAS,cAAc,IAAI,MAAM,MAAM,CAAC;AAAA,EAC1C,WAAW,MAAM,SAAS,GAAG,YAAY,QAAQ;AAC/C,aAAS,SAAS;AAClB,aAAS,cAAc,IAAI,MAAM,OAAO,CAAC;AAAA,EAC3C,WAAW,MAAM,SAAS,GAAG,YAAY,OAAO;AAC9C,aAAS,SAAS;AAClB,aAAS,QAAQ;AACjB,aAAS,cAAc,IAAI,MAAM,OAAO,CAAC;AAAA,EAC3C;AACF;AAOO,MAAM,gBAAuC,CAAC,WAAW,MAAM,SAAS,WAAW;AAtF1F;AAuFE,QAAI,UAAK,UAAL,mBAAY,cAAa,UAAW;AACxC,QAAM,UAAU,KAAK,MAAM;AAE3B,QAAM,QAAQ,SAAS,cAAc,KAAK;AAC1C,YAAU,YAAY,KAAK;AAE3B,iBAAA,EAAiB,KAAK,CAAC,OAAO;AAC5B,QAAI,OAAO,QAAS;AAEpB,UAAM,WAAW;AACjB,UAAM,SAAS,IAAI,GAAG,OAAO,OAAO;AAAA,MAClC;AAAA,MACA,YAAY,EAAE,aAAa,GAAG,KAAK,EAAA;AAAA,MACnC,QAAQ;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,QAWN,SAAS,MAAM;AACb,+BAAqB,WAAW,MAAM;AACtC,kBAAA;AAAA,QACF;AAAA,QACA,eAAe,CAAC,UAAU,kBAAkB,OAAO,IAAI,QAAQ;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,QAO/D,SAAS,CAAC,UACR,SAAS;AAAA,UACP,IAAI,YAAY,SAAS,EAAE,SAAS,MAAM,QAAQ,EAAE,MAAM,MAAM,OAAK,CAAG;AAAA,QAAA;AAAA,MAC1E;AAAA,IACJ,CACD;AACD,WAAO,iBAAiB,SAAS,MAAM,OAAO,WAAW,EAAE,MAAM,MAAM;AAAA,EACzE,CAAC;AACH;AC5KO,MAAM,QAAqB;AAAA,EAChC,MAAM;AAAA,EAEN,KAAK,KAAgC;AACnC,WAAO,IAAI,GAAG,sBAAsB,WAAW,aAAa;AAAA,EAC9D;AACF;"}

package/dist/esm/plugins/video/youtube.d.ts

@@ -0,0 +1,61 @@
+import { VideoProviderRenderer } from '../../core/plugin';
+/**
+ * The bits of the YouTube IFrame Player API actually used here — not in
+ * `lib.dom.d.ts` (a third-party global loaded on demand), so this is a
+ * documented interop boundary (CLAUDE.md: `any` only there). Kept
+ * intentionally minimal, not a full mirror of YouTube's own typings.
+ */
+interface YTPlayer {
+    playVideo(): void;
+    pauseVideo(): void;
+    mute(): void;
+    unMute(): void;
+    isMuted(): boolean;
+    destroy(): void;
+}
+interface YTPlayerStateEvent {
+    data: number;
+}
+/**
+ * Same `{ data: number }` shape as `YTPlayerStateEvent` — `data` holds an
+ * error code there (2 invalid parameter, 5 HTML5 player error, 100 video
+ * not found/private, 101/150 embedding disabled by the owner; undocumented
+ * codes like 153 are also reported in the wild) rather than a player state.
+ * Named separately from `YTPlayerStateEvent` for readability at the call
+ * site, not because the shape actually differs.
+ */
+interface YTPlayerErrorEvent {
+    data: number;
+}
+interface YTNamespace {
+    Player: new (el: HTMLElement, opts: {
+        videoId: string;
+        playerVars?: {
+            playsinline?: 0 | 1;
+            rel?: 0 | 1;
+        };
+        events?: {
+            onReady?: () => void;
+            onStateChange?: (event: YTPlayerStateEvent) => void;
+            onError?: (event: YTPlayerErrorEvent) => void;
+        };
+    }) => YTPlayer;
+    PlayerState: {
+        ENDED: number;
+        PLAYING: number;
+        PAUSED: number;
+    };
+}
+declare global {
+    interface Window {
+        YT?: YTNamespace;
+        onYouTubeIframeAPIReady?: () => void;
+    }
+}
+/**
+ * DESIGN.md §4-video — no poster/thumbnail handling at all: the slide shows
+ * nothing until the embed itself is ready (same spinner-then-reveal every
+ * other slide type gets), never an auto-fetched or guessed preview image.
+ */
+export declare const renderYouTube: VideoProviderRenderer;
+export {};

package/dist/esm/plugins/zoom/icons.d.ts

@@ -0,0 +1,4 @@
+/** DESIGN.md §9 — inline SVG, stroke = currentColor, matches src/core/icons.ts's convention. A magnifying glass with a +/− in the lens, and a plain expand-corners glyph for "actual size" (distinct from fullscreen's EXPAND_ICON — no diagonal corner arrows, just a frame, so the two aren't visually confusable when both plugins are enabled). */
+export declare const ZOOM_IN_ICON = "<svg viewBox=\"0 0 24 24\" width=\"24\" height=\"24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\"><circle cx=\"10\" cy=\"10\" r=\"7\"/><path d=\"M21 21l-5.5-5.5M10 7v6M7 10h6\"/></svg>";
+export declare const ZOOM_OUT_ICON = "<svg viewBox=\"0 0 24 24\" width=\"24\" height=\"24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\"><circle cx=\"10\" cy=\"10\" r=\"7\"/><path d=\"M21 21l-5.5-5.5M7 10h6\"/></svg>";
+export declare const ZOOM_ACTUAL_SIZE_ICON = "<svg viewBox=\"0 0 24 24\" width=\"24\" height=\"24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\"><rect x=\"4\" y=\"4\" width=\"16\" height=\"16\" rx=\"1\"/><path d=\"M9 15l6-6M9 9h0M15 15h0\"/></svg>";

package/dist/esm/plugins/zoom/index.d.ts

@@ -0,0 +1,30 @@
+import { ShojiPlugin } from '../../core/plugin';
+export interface ZoomOptions {
+    /** Multiplier cap for pinch/wheel/button zoom. "Actual size" can exceed this deliberately — it's an explicit action, not continuous gesture zoom. Default 4. */
+    maxScale?: number;
+    /** Scale a double-tap/double-click jumps to; a second one while already zoomed resets to 1 instead. Default 2. */
+    doubleTapScale?: number;
+    /** Multiplier applied per zoom-in/zoom-out toolbar button click. Default 1.5. */
+    buttonStep?: number;
+}
+/**
+ * DESIGN.md §4-zoom — pinch, double-tap/click, wheel+ctrl, and three toolbar
+ * buttons (zoom in/out/actual-size) all drive a single `scale`/pan state on
+ * the active slide's `<img>` — never `.shoji-slide-media` itself, which the
+ * rotateFlip plugin (§4) already transforms; nesting on the inner element
+ * instead of fighting over the same transform string means a rotated *and*
+ * zoomed photo behaves correctly for free (the outer rotate carries the
+ * inner pan/scale along with it as a rigid unit, which is also the visually
+ * expected result — see DESIGN.md's note on this plugin for the full
+ * reasoning). Pinch/double-tap/wheel are core's own gesture relay (§2.4) —
+ * scaffolding that existed specifically for this plugin to consume, not
+ * reimplemented here. Pan (single-pointer drag while zoomed) is the one
+ * piece core's relay doesn't cover — core's own drag-to-navigate/
+ * drag-to-close would otherwise fight over the same drag — so this plugin
+ * registers a zoom gate (`Gallery.registerZoomGate`, §4-zoom) that suspends
+ * core's drag handling entirely while zoomed, and tracks pan with its own
+ * minimal raw pointer listeners instead of reusing `GestureEngine` (whose
+ * axis-locked model — pick horizontal *or* vertical per gesture — is the
+ * wrong shape for a 2D pan that needs both at once).
+ */
+export declare const Zoom: ShojiPlugin;

package/dist/esm/plugins/zoom/index.js

@@ -0,0 +1,274 @@
+import { w as waitForTransitionEnd } from "../../zoomTransition-bbKHpVpA.js";
+const ZOOM_IN_ICON = '<svg viewBox="0 0 24 24" width="24" height="24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="10" cy="10" r="7"/><path d="M21 21l-5.5-5.5M10 7v6M7 10h6"/></svg>';
+const ZOOM_OUT_ICON = '<svg viewBox="0 0 24 24" width="24" height="24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="10" cy="10" r="7"/><path d="M21 21l-5.5-5.5M7 10h6"/></svg>';
+const ZOOM_ACTUAL_SIZE_ICON = '<svg viewBox="0 0 24 24" width="24" height="24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="4" y="4" width="16" height="16" rx="1"/><path d="M9 15l6-6M9 9h0M15 15h0"/></svg>';
+function clampScale(scale, min, max) {
+  return Math.min(max, Math.max(min, scale));
+}
+function clampAxis(naturalPos, naturalSize, scale, containerPos, containerSize, offset) {
+  const scaledSize = naturalSize * scale;
+  if (scaledSize <= containerSize) {
+    return containerPos + (containerSize - scaledSize) / 2 - naturalPos;
+  }
+  const minPos = containerPos + containerSize - scaledSize;
+  const maxPos = containerPos;
+  const proposedPos = naturalPos + offset;
+  return Math.min(maxPos, Math.max(minPos, proposedPos)) - naturalPos;
+}
+function clampPan(natural, container, scale, pan) {
+  return {
+    tx: clampAxis(natural.left, natural.width, scale, container.left, container.width, pan.tx),
+    ty: clampAxis(natural.top, natural.height, scale, container.top, container.height, pan.ty)
+  };
+}
+function zoomTowardPoint(natural, pan, oldScale, newScale, anchorX, anchorY) {
+  const currentLeft = natural.left + pan.tx;
+  const currentTop = natural.top + pan.ty;
+  const dx = anchorX - currentLeft;
+  const dy = anchorY - currentTop;
+  const factor = 1 - newScale / oldScale;
+  return {
+    tx: pan.tx + dx * factor,
+    ty: pan.ty + dy * factor
+  };
+}
+const ZOOM_EPSILON = 1.001;
+function isRealControl(event) {
+  return event.composedPath().some(
+    (node) => node instanceof Element && node.matches("button, video, input, select, textarea, a[href], [data-shoji-no-drag]")
+  );
+}
+const Zoom = {
+  name: "zoom",
+  defaults: {
+    maxScale: 4,
+    doubleTapScale: 2,
+    buttonStep: 1.5
+  },
+  init(ctx) {
+    const { gallery } = ctx;
+    const maxScale = Number(ctx.options.maxScale ?? 4);
+    const doubleTapScale = Number(ctx.options.doubleTapScale ?? 2);
+    const buttonStep = Number(ctx.options.buttonStep ?? 1.5);
+    const locale = gallery.options.locale ?? {};
+    const zoomInLabel = locale.zoomIn ?? "Zoom in";
+    const zoomOutLabel = locale.zoomOut ?? "Zoom out";
+    const actualSizeLabel = locale.zoomActualSize ?? "Actual size";
+    let scale = 1;
+    let pan = { tx: 0, ty: 0 };
+    let natural = null;
+    let container = null;
+    let pinchStartScale = 1;
+    function getImg() {
+      const media = gallery.getActiveMedia();
+      const child = media == null ? void 0 : media.firstElementChild;
+      return child instanceof HTMLImageElement ? child : null;
+    }
+    function boxOf(el) {
+      const rect = el.getBoundingClientRect();
+      return { left: rect.left, top: rect.top, width: rect.width, height: rect.height };
+    }
+    function ensureNatural(img) {
+      if (natural && container) return true;
+      if (scale !== 1) return false;
+      natural = boxOf(img);
+      container = boxOf(img.parentElement ?? img);
+      return true;
+    }
+    function whenSettled(action) {
+      const media = gallery.getActiveMedia();
+      if (!media || media.style.transition === "") {
+        action();
+        return;
+      }
+      waitForTransitionEnd(media, action);
+    }
+    function apply() {
+      const img = getImg();
+      if (!img) return;
+      img.style.transformOrigin = "0 0";
+      img.style.transform = scale === 1 && pan.tx === 0 && pan.ty === 0 ? "none" : `translate3d(${pan.tx}px, ${pan.ty}px, 0) scale3d(${scale}, ${scale}, 1)`;
+      img.classList.toggle("shoji-zoomed", scale > 1);
+    }
+    function emitChange() {
+      ctx.emit("zoomChange", { index: gallery.currentIndex, scale });
+    }
+    function withTransition(img, run, afterEnd) {
+      img.style.transition = "transform var(--shoji-duration) var(--shoji-easing)";
+      run();
+      waitForTransitionEnd(img, () => {
+        img.style.transition = "";
+        afterEnd == null ? void 0 : afterEnd();
+      });
+    }
+    function zoomTo(targetScale, anchorX, anchorY, ceiling = maxScale, animate = false) {
+      whenSettled(() => {
+        const img = getImg();
+        if (!img || !ensureNatural(img)) return;
+        const clampedScale = clampScale(targetScale, 1, Math.max(ceiling, 1));
+        pan = zoomTowardPoint(natural, pan, scale, clampedScale, anchorX, anchorY);
+        scale = clampedScale;
+        pan = clampPan(natural, container, scale, pan);
+        if (animate) withTransition(img, apply);
+        else apply();
+        emitChange();
+      });
+    }
+    function reset(animate = false) {
+      scale = 1;
+      pan = { tx: 0, ty: 0 };
+      natural = null;
+      container = null;
+      const img = getImg();
+      if (!img) return;
+      const clearTransform = () => {
+        img.style.transform = "";
+        img.classList.remove("shoji-zoomed");
+      };
+      if (animate) {
+        withTransition(img, clearTransform, () => {
+          img.style.transformOrigin = "";
+        });
+      } else {
+        clearTransform();
+        img.style.transformOrigin = "";
+      }
+    }
+    function markEnabled() {
+      var _a;
+      (_a = getImg()) == null ? void 0 : _a.classList.add("shoji-zoom-enabled");
+    }
+    function toggleZoom(x, y) {
+      if (scale > ZOOM_EPSILON) reset(true);
+      else zoomTo(doubleTapScale, x, y, maxScale, true);
+    }
+    const offPinchStart = ctx.on("pinchStart", () => {
+      pinchStartScale = scale;
+    });
+    const offPinchMove = ctx.on("pinchMove", ({ scale: relative, centerX, centerY }) => {
+      zoomTo(pinchStartScale * relative, centerX, centerY);
+    });
+    const offPinchEnd = ctx.on("pinchEnd", () => {
+      if (scale <= ZOOM_EPSILON) reset();
+    });
+    const offDoubleTap = ctx.on("doubleTap", ({ x, y }) => toggleZoom(x, y));
+    const offWheelZoom = ctx.on("wheelZoom", ({ deltaScale, x, y }) => {
+      zoomTo(scale + deltaScale, x, y);
+    });
+    let panPointerId = null;
+    let lastX = 0;
+    let lastY = 0;
+    const outer = ctx.ui.outer();
+    function onPointerDown(event) {
+      if (scale <= ZOOM_EPSILON || isRealControl(event)) return;
+      panPointerId = event.pointerId;
+      lastX = event.clientX;
+      lastY = event.clientY;
+    }
+    function onPointerMove(event) {
+      if (panPointerId !== event.pointerId || !natural || !container) return;
+      event.preventDefault();
+      const dx = event.clientX - lastX;
+      const dy = event.clientY - lastY;
+      lastX = event.clientX;
+      lastY = event.clientY;
+      pan = clampPan(natural, container, scale, { tx: pan.tx + dx, ty: pan.ty + dy });
+      apply();
+    }
+    function onPointerUp(event) {
+      if (panPointerId === event.pointerId) panPointerId = null;
+    }
+    outer.addEventListener("pointerdown", onPointerDown);
+    outer.addEventListener("pointermove", onPointerMove, { passive: false });
+    outer.addEventListener("pointerup", onPointerUp);
+    outer.addEventListener("pointercancel", onPointerUp);
+    function buildButton(icon, label) {
+      const button = document.createElement("button");
+      button.type = "button";
+      button.className = "shoji-toolbar-button";
+      button.innerHTML = icon;
+      button.setAttribute("aria-label", label);
+      button.title = label;
+      return button;
+    }
+    function centerAnchor() {
+      const media = gallery.getActiveMedia();
+      const rect = media == null ? void 0 : media.getBoundingClientRect();
+      return rect ? { x: rect.left + rect.width / 2, y: rect.top + rect.height / 2 } : { x: 0, y: 0 };
+    }
+    function zoomInStep() {
+      const { x, y } = centerAnchor();
+      zoomTo(scale * buttonStep, x, y, maxScale, true);
+    }
+    function zoomOutStep() {
+      const { x, y } = centerAnchor();
+      if (scale / buttonStep <= ZOOM_EPSILON) reset(true);
+      else zoomTo(scale / buttonStep, x, y, maxScale, true);
+    }
+    const zoomInBtn = buildButton(ZOOM_IN_ICON, zoomInLabel);
+    const zoomOutBtn = buildButton(ZOOM_OUT_ICON, zoomOutLabel);
+    const actualSizeBtn = buildButton(ZOOM_ACTUAL_SIZE_ICON, actualSizeLabel);
+    zoomInBtn.addEventListener("click", zoomInStep);
+    zoomOutBtn.addEventListener("click", zoomOutStep);
+    actualSizeBtn.addEventListener("click", () => {
+      whenSettled(() => {
+        const img = getImg();
+        if (!img || !img.naturalWidth) return;
+        if (!ensureNatural(img)) return;
+        if (scale > ZOOM_EPSILON) {
+          reset(true);
+          return;
+        }
+        const targetScale = img.naturalWidth / natural.width;
+        const { x, y } = centerAnchor();
+        zoomTo(targetScale, x, y, targetScale, true);
+      });
+    });
+    const removeButtons = [zoomInBtn, zoomOutBtn, actualSizeBtn].map(
+      (button) => ctx.ui.toolbar("right", button)
+    );
+    const removeShortcuts = [
+      ctx.ui.registerShortcut("w", zoomInStep),
+      ctx.ui.registerShortcut("W", zoomInStep),
+      ctx.ui.registerShortcut("s", zoomOutStep),
+      ctx.ui.registerShortcut("S", zoomOutStep)
+    ];
+    const offOpen = ctx.on("afterOpen", () => {
+      reset();
+      markEnabled();
+    });
+    const offBeforeSlide = ctx.on("beforeSlide", () => reset());
+    const offSlide = ctx.on("afterSlide", () => {
+      reset();
+      markEnabled();
+    });
+    const offBeforeClose = ctx.on("beforeClose", () => reset());
+    const unregisterGate = gallery.registerZoomGate(() => scale > ZOOM_EPSILON);
+    markEnabled();
+    return () => {
+      var _a;
+      for (const remove of removeButtons) remove();
+      for (const remove of removeShortcuts) remove();
+      offOpen();
+      offBeforeSlide();
+      offSlide();
+      offBeforeClose();
+      offPinchStart();
+      offPinchMove();
+      offPinchEnd();
+      offDoubleTap();
+      offWheelZoom();
+      outer.removeEventListener("pointerdown", onPointerDown);
+      outer.removeEventListener("pointermove", onPointerMove);
+      outer.removeEventListener("pointerup", onPointerUp);
+      outer.removeEventListener("pointercancel", onPointerUp);
+      unregisterGate();
+      reset();
+      (_a = getImg()) == null ? void 0 : _a.classList.remove("shoji-zoom-enabled");
+    };
+  }
+};
+export {
+  Zoom
+};
+//# sourceMappingURL=index.js.map

package/dist/esm/plugins/zoom/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../../../../src/plugins/zoom/icons.ts","../../../../src/plugins/zoom/zoomMath.ts","../../../../src/plugins/zoom/index.ts"],"sourcesContent":["/** DESIGN.md §9 — inline SVG, stroke = currentColor, matches src/core/icons.ts's convention. A magnifying glass with a +/− in the lens, and a plain expand-corners glyph for \"actual size\" (distinct from fullscreen's EXPAND_ICON — no diagonal corner arrows, just a frame, so the two aren't visually confusable when both plugins are enabled). */\nexport const ZOOM_IN_ICON =\n  '<svg viewBox=\"0 0 24 24\" width=\"24\" height=\"24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\"><circle cx=\"10\" cy=\"10\" r=\"7\"/><path d=\"M21 21l-5.5-5.5M10 7v6M7 10h6\"/></svg>';\n\nexport const ZOOM_OUT_ICON =\n  '<svg viewBox=\"0 0 24 24\" width=\"24\" height=\"24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\"><circle cx=\"10\" cy=\"10\" r=\"7\"/><path d=\"M21 21l-5.5-5.5M7 10h6\"/></svg>';\n\nexport const ZOOM_ACTUAL_SIZE_ICON =\n  '<svg viewBox=\"0 0 24 24\" width=\"24\" height=\"24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\"><rect x=\"4\" y=\"4\" width=\"16\" height=\"16\" rx=\"1\"/><path d=\"M9 15l6-6M9 9h0M15 15h0\"/></svg>';\n","/** A viewport-relative rect: `{left, top, width, height}`, same shape as `DOMRect` but plain-object so it's trivial to mock in tests. */\nexport interface ZoomBox {\n  left: number;\n  top: number;\n  width: number;\n  height: number;\n}\n\nexport interface PanOffset {\n  tx: number;\n  ty: number;\n}\n\nexport function clampScale(scale: number, min: number, max: number): number {\n  return Math.min(max, Math.max(min, scale));\n}\n\n/**\n * One axis of `clampPan` below. `natural*` is the element's own unscaled\n * rendered box (captured once at scale 1, before any transform — `apply()`\n * in `index.ts` renders `translate(tx, ty) scale(s)` with `transform-origin:\n * 0 0`, so the natural box's top-left is exactly where the scaled box's own\n * local origin sits on screen, and `tx`/`ty` are the *only* thing moving it\n * from there). If the scaled content is still smaller than the container on\n * this axis, no pan range can avoid a gap on *both* sides at once — centered\n * is the only sensible answer, not an inverted min>max range.\n */\nfunction clampAxis(\n  naturalPos: number,\n  naturalSize: number,\n  scale: number,\n  containerPos: number,\n  containerSize: number,\n  offset: number,\n): number {\n  const scaledSize = naturalSize * scale;\n  if (scaledSize <= containerSize) {\n    return containerPos + (containerSize - scaledSize) / 2 - naturalPos;\n  }\n  const minPos = containerPos + containerSize - scaledSize;\n  const maxPos = containerPos;\n  const proposedPos = naturalPos + offset;\n  return Math.min(maxPos, Math.max(minPos, proposedPos)) - naturalPos;\n}\n\n/** Keeps the scaled+panned content's edges from retreating inside `container`'s edges (no empty gap beyond the image), on both axes independently. */\nexport function clampPan(\n  natural: ZoomBox,\n  container: ZoomBox,\n  scale: number,\n  pan: PanOffset,\n): PanOffset {\n  return {\n    tx: clampAxis(natural.left, natural.width, scale, container.left, container.width, pan.tx),\n    ty: clampAxis(natural.top, natural.height, scale, container.top, container.height, pan.ty),\n  };\n}\n\n/**\n * The standard \"zoom toward a point\" formula: adjusts pan so the viewport\n * point `(anchorX, anchorY)` stays visually fixed as scale changes from\n * `oldScale` to `newScale`, given `transform-origin: 0 0` (see `natural`'s\n * doc comment on `clampAxis` above for why that makes this tractable —\n * scaling never moves the natural box's own top-left on screen, only `pan`\n * does). Callers still need to clamp the result with `clampPan` afterward;\n * this only solves the anchor-fixed part, not boundary containment.\n */\nexport function zoomTowardPoint(\n  natural: ZoomBox,\n  pan: PanOffset,\n  oldScale: number,\n  newScale: number,\n  anchorX: number,\n  anchorY: number,\n): PanOffset {\n  const currentLeft = natural.left + pan.tx;\n  const currentTop = natural.top + pan.ty;\n  const dx = anchorX - currentLeft;\n  const dy = anchorY - currentTop;\n  const factor = 1 - newScale / oldScale;\n  return {\n    tx: pan.tx + dx * factor,\n    ty: pan.ty + dy * factor,\n  };\n}\n","import type { PluginContext, ShojiPlugin } from '../../core/plugin';\nimport { waitForTransitionEnd } from '../../core/zoomTransition';\nimport { ZOOM_ACTUAL_SIZE_ICON, ZOOM_IN_ICON, ZOOM_OUT_ICON } from './icons';\nimport { clampPan, clampScale, zoomTowardPoint, type PanOffset, type ZoomBox } from './zoomMath';\nimport './zoom.css';\n\nexport interface ZoomOptions {\n  /** Multiplier cap for pinch/wheel/button zoom. \"Actual size\" can exceed this deliberately — it's an explicit action, not continuous gesture zoom. Default 4. */\n  maxScale?: number;\n  /** Scale a double-tap/double-click jumps to; a second one while already zoomed resets to 1 instead. Default 2. */\n  doubleTapScale?: number;\n  /** Multiplier applied per zoom-in/zoom-out toolbar button click. Default 1.5. */\n  buttonStep?: number;\n}\n\nconst ZOOM_EPSILON = 1.001; // treat \"just barely above 1\" as unzoomed — avoids float residue pinning isZoomed() true forever\n\n/** A click/drag starting on a real control shouldn't engage pan — same exclusion list GestureController's shouldIgnoreGesture uses, duplicated rather than imported since that function isn't part of core's exported surface. */\nfunction isRealControl(event: PointerEvent): boolean {\n  return event\n    .composedPath()\n    .some(\n      (node) =>\n        node instanceof Element &&\n        node.matches('button, video, input, select, textarea, a[href], [data-shoji-no-drag]'),\n    );\n}\n\n/**\n * DESIGN.md §4-zoom — pinch, double-tap/click, wheel+ctrl, and three toolbar\n * buttons (zoom in/out/actual-size) all drive a single `scale`/pan state on\n * the active slide's `<img>` — never `.shoji-slide-media` itself, which the\n * rotateFlip plugin (§4) already transforms; nesting on the inner element\n * instead of fighting over the same transform string means a rotated *and*\n * zoomed photo behaves correctly for free (the outer rotate carries the\n * inner pan/scale along with it as a rigid unit, which is also the visually\n * expected result — see DESIGN.md's note on this plugin for the full\n * reasoning). Pinch/double-tap/wheel are core's own gesture relay (§2.4) —\n * scaffolding that existed specifically for this plugin to consume, not\n * reimplemented here. Pan (single-pointer drag while zoomed) is the one\n * piece core's relay doesn't cover — core's own drag-to-navigate/\n * drag-to-close would otherwise fight over the same drag — so this plugin\n * registers a zoom gate (`Gallery.registerZoomGate`, §4-zoom) that suspends\n * core's drag handling entirely while zoomed, and tracks pan with its own\n * minimal raw pointer listeners instead of reusing `GestureEngine` (whose\n * axis-locked model — pick horizontal *or* vertical per gesture — is the\n * wrong shape for a 2D pan that needs both at once).\n */\nexport const Zoom: ShojiPlugin = {\n  name: 'zoom',\n  defaults: {\n    maxScale: 4,\n    doubleTapScale: 2,\n    buttonStep: 1.5,\n  } satisfies ZoomOptions,\n\n  init(ctx: PluginContext): () => void {\n    const { gallery } = ctx;\n    const maxScale = Number(ctx.options.maxScale ?? 4);\n    const doubleTapScale = Number(ctx.options.doubleTapScale ?? 2);\n    const buttonStep = Number(ctx.options.buttonStep ?? 1.5);\n    const locale = (gallery.options.locale ?? {}) as Record<string, string>;\n    const zoomInLabel = locale.zoomIn ?? 'Zoom in';\n    const zoomOutLabel = locale.zoomOut ?? 'Zoom out';\n    const actualSizeLabel = locale.zoomActualSize ?? 'Actual size';\n\n    let scale = 1;\n    let pan: PanOffset = { tx: 0, ty: 0 };\n    let natural: ZoomBox | null = null;\n    let container: ZoomBox | null = null;\n    let pinchStartScale = 1;\n\n    function getImg(): HTMLImageElement | null {\n      const media = gallery.getActiveMedia();\n      const child = media?.firstElementChild;\n      return child instanceof HTMLImageElement ? child : null;\n    }\n\n    function boxOf(el: Element): ZoomBox {\n      const rect = el.getBoundingClientRect();\n      return { left: rect.left, top: rect.top, width: rect.width, height: rect.height };\n    }\n\n    /** Only valid to measure while scale===1 (untransformed) — the very first zoom action on a slide; every subsequent action within the same slide reuses the cached box, since measuring an already-scaled element would capture the scaled size, not the natural one. */\n    function ensureNatural(img: HTMLImageElement): boolean {\n      if (natural && container) return true;\n      if (scale !== 1) return false; // shouldn't happen — defensive\n      natural = boxOf(img);\n      container = boxOf(img.parentElement ?? img);\n      return true;\n    }\n\n    /**\n     * A real bug: `ensureNatural`'s first measurement of a slide is only\n     * trustworthy once the lightbox's own open FLIP transition (`zoomIn`,\n     * `core/zoomTransition.ts`) has actually settled — that transition\n     * applies its own transform directly to `.shoji-slide-media`, the exact\n     * element `ensureNatural` measures as `container`. A zoom action firing\n     * before it settles (any interaction within `--shoji-duration` of\n     * opening — a fast click, or a test that only waits for the dialog to\n     * become visible) captured a wildly wrong, mid-animation rect,\n     * permanently poisoning that slide's zoom math (every later action\n     * reuses the same cached, wrong box). `zoomIn` is fire-and-forget by\n     * design (nothing to await when opening) and clears this exact inline\n     * style once its own transition ends — the one signal available for\n     * \"is it still running.\" Runs `action` immediately once settled, which\n     * is right away in the overwhelming common case (any real interaction\n     * more than ~300ms after open).\n     */\n    function whenSettled(action: () => void): void {\n      const media = gallery.getActiveMedia();\n      if (!media || media.style.transition === '') {\n        action();\n        return;\n      }\n      waitForTransitionEnd(media, action);\n    }\n\n    /**\n     * `translate3d`/`scale3d`, not the 2D `translate`/`scale` this used to\n     * use — a real bug, reported from real usage: evenly-spaced horizontal\n     * lines visible across a zoomed photo, at certain zoom levels, on real\n     * GPU hardware (not reproducible in headless/software rendering, so\n     * this can't be verified here). The regular spacing matches Chromium's\n     * own raster-tile boundaries — a known quirk where scaling large\n     * content via a 2D `scale()` transform can show seams between GPU\n     * tiles. Forcing the fully 3D compositing path instead (functionally\n     * identical — `scale3d(s, s, 1)` and `scale(s)` produce the same\n     * on-screen result) is the commonly effective fix, since it takes a\n     * different rasterization path than the 2D one.\n     */\n    function apply(): void {\n      const img = getImg();\n      if (!img) return;\n      img.style.transformOrigin = '0 0';\n      img.style.transform =\n        scale === 1 && pan.tx === 0 && pan.ty === 0\n          ? 'none'\n          : `translate3d(${pan.tx}px, ${pan.ty}px, 0) scale3d(${scale}, ${scale}, 1)`;\n      img.classList.toggle('shoji-zoomed', scale > 1);\n    }\n\n    function emitChange(): void {\n      ctx.emit('zoomChange', { index: gallery.currentIndex, scale });\n    }\n\n    /** Wraps a transform-setting `run` in a transition, for discrete jumps (buttons, double-tap, actual-size) — never for pinch/pan/wheel, which already track the input 1:1 and would visibly lag behind it under a transition. `afterEnd`, if given, runs once the transition actually completes, not before — `reset()` uses it to clear `transformOrigin` only once it's safe to (see its own comment for why clearing it any earlier is a real bug). The transition itself is always cleared afterward, so it doesn't linger onto the next, possibly-continuous, zoom action. */\n    function withTransition(img: HTMLImageElement, run: () => void, afterEnd?: () => void): void {\n      img.style.transition = 'transform var(--shoji-duration) var(--shoji-easing)';\n      run();\n      waitForTransitionEnd(img, () => {\n        img.style.transition = '';\n        afterEnd?.();\n      });\n    }\n\n    /** Shared by every zoom-in/out entry point (pinch, wheel, buttons, double-tap, actual-size) — anchors on (anchorX, anchorY), clamps scale to [1, ceiling] and pan to the container bounds. `ceiling` defaults to maxScale; actual-size passes its own (possibly larger) target so it isn't capped by the gesture-zoom limit. Deferred via `whenSettled` — see its doc comment — so a zoom action landing right as the lightbox opens doesn't measure mid-animation. `animate` — see `withTransition`. */\n    function zoomTo(\n      targetScale: number,\n      anchorX: number,\n      anchorY: number,\n      ceiling = maxScale,\n      animate = false,\n    ): void {\n      whenSettled(() => {\n        const img = getImg();\n        if (!img || !ensureNatural(img)) return;\n        const clampedScale = clampScale(targetScale, 1, Math.max(ceiling, 1));\n        pan = zoomTowardPoint(natural!, pan, scale, clampedScale, anchorX, anchorY);\n        scale = clampedScale;\n        pan = clampPan(natural!, container!, scale, pan);\n        if (animate) withTransition(img, apply);\n        else apply();\n        emitChange();\n      });\n    }\n\n    function reset(animate = false): void {\n      scale = 1;\n      pan = { tx: 0, ty: 0 };\n      natural = null;\n      container = null;\n      const img = getImg();\n      if (!img) return;\n      const clearTransform = (): void => {\n        img.style.transform = '';\n        img.classList.remove('shoji-zoomed');\n      };\n      if (animate) {\n        // transform-origin has to stay put (0 0) for the duration of the\n        // transition — clearing it to the browser default (center) in the\n        // same tick as starting the transition snaps the scale anchor\n        // instantly, which visibly jumped the image before it eased down\n        // to neutral. Deferred to `afterEnd`, once the transition is done\n        // and transform-origin no longer affects anything visible.\n        withTransition(img, clearTransform, () => {\n          img.style.transformOrigin = '';\n        });\n      } else {\n        clearTransform();\n        img.style.transformOrigin = '';\n      }\n    }\n\n    /** Each slide gets a freshly-created `<img>` (SlideManager never reuses elements across renders), so the cursor-affordance marker (`zoom.css`) needs reapplying every time the active media changes, not just once. */\n    function markEnabled(): void {\n      getImg()?.classList.add('shoji-zoom-enabled');\n    }\n\n    function toggleZoom(x: number, y: number): void {\n      if (scale > ZOOM_EPSILON) reset(true);\n      else zoomTo(doubleTapScale, x, y, maxScale, true);\n    }\n\n    // --- pinch (relayed by core, §2.4 — no built-in effect until this plugin exists) ---\n    const offPinchStart = ctx.on('pinchStart', () => {\n      pinchStartScale = scale;\n    });\n    const offPinchMove = ctx.on('pinchMove', ({ scale: relative, centerX, centerY }) => {\n      zoomTo(pinchStartScale * relative, centerX, centerY);\n    });\n    const offPinchEnd = ctx.on('pinchEnd', () => {\n      if (scale <= ZOOM_EPSILON) reset(); // snap fully back to neutral rather than leaving float residue\n    });\n\n    // --- double-tap / double-click (relayed by core; Pointer Events unify the two, see GestureEngine) ---\n    const offDoubleTap = ctx.on('doubleTap', ({ x, y }) => toggleZoom(x, y));\n\n    // --- ctrl+wheel / trackpad pinch (relayed by core) ---\n    const offWheelZoom = ctx.on('wheelZoom', ({ deltaScale, x, y }) => {\n      zoomTo(scale + deltaScale, x, y);\n    });\n\n    // --- pan while zoomed — the one gesture core's relay doesn't cover; see the plugin doc comment for why this can't reuse GestureEngine. ---\n    let panPointerId: number | null = null;\n    let lastX = 0;\n    let lastY = 0;\n    const outer = ctx.ui.outer();\n\n    function onPointerDown(event: PointerEvent): void {\n      if (scale <= ZOOM_EPSILON || isRealControl(event)) return;\n      panPointerId = event.pointerId;\n      lastX = event.clientX;\n      lastY = event.clientY;\n    }\n    function onPointerMove(event: PointerEvent): void {\n      if (panPointerId !== event.pointerId || !natural || !container) return;\n      event.preventDefault();\n      const dx = event.clientX - lastX;\n      const dy = event.clientY - lastY;\n      lastX = event.clientX;\n      lastY = event.clientY;\n      pan = clampPan(natural, container, scale, { tx: pan.tx + dx, ty: pan.ty + dy });\n      apply();\n    }\n    function onPointerUp(event: PointerEvent): void {\n      if (panPointerId === event.pointerId) panPointerId = null;\n    }\n\n    outer.addEventListener('pointerdown', onPointerDown);\n    outer.addEventListener('pointermove', onPointerMove, { passive: false });\n    outer.addEventListener('pointerup', onPointerUp);\n    outer.addEventListener('pointercancel', onPointerUp);\n\n    // --- toolbar buttons ---\n    function buildButton(icon: string, label: string): HTMLButtonElement {\n      const button = document.createElement('button');\n      button.type = 'button';\n      button.className = 'shoji-toolbar-button';\n      button.innerHTML = icon;\n      button.setAttribute('aria-label', label);\n      button.title = label;\n      return button;\n    }\n\n    function centerAnchor(): { x: number; y: number } {\n      const media = gallery.getActiveMedia();\n      const rect = media?.getBoundingClientRect();\n      return rect\n        ? { x: rect.left + rect.width / 2, y: rect.top + rect.height / 2 }\n        : { x: 0, y: 0 };\n    }\n\n    /** Shared by the zoom-in toolbar button and the `w` keyboard shortcut — same fixed `buttonStep` multiplier either way. */\n    function zoomInStep(): void {\n      const { x, y } = centerAnchor();\n      zoomTo(scale * buttonStep, x, y, maxScale, true);\n    }\n\n    /** Shared by the zoom-out toolbar button and the `s` keyboard shortcut. */\n    function zoomOutStep(): void {\n      const { x, y } = centerAnchor();\n      if (scale / buttonStep <= ZOOM_EPSILON) reset(true);\n      else zoomTo(scale / buttonStep, x, y, maxScale, true);\n    }\n\n    const zoomInBtn = buildButton(ZOOM_IN_ICON, zoomInLabel);\n    const zoomOutBtn = buildButton(ZOOM_OUT_ICON, zoomOutLabel);\n    const actualSizeBtn = buildButton(ZOOM_ACTUAL_SIZE_ICON, actualSizeLabel);\n\n    zoomInBtn.addEventListener('click', zoomInStep);\n    zoomOutBtn.addEventListener('click', zoomOutStep);\n    actualSizeBtn.addEventListener('click', () => {\n      // Reads natural.width directly (unlike every other entry point, which\n      // just hands zoomTo a target and lets it call ensureNatural itself) —\n      // needs its own whenSettled wrap for that reason, not just zoomTo's.\n      whenSettled(() => {\n        const img = getImg();\n        if (!img || !img.naturalWidth) return;\n        if (!ensureNatural(img)) return;\n        if (scale > ZOOM_EPSILON) {\n          reset(true);\n          return;\n        }\n        const targetScale = img.naturalWidth / natural!.width;\n        const { x, y } = centerAnchor();\n        zoomTo(targetScale, x, y, targetScale, true); // ceiling = targetScale — bypasses maxScale deliberately\n      });\n    });\n\n    // 'right' — registered in this order, so they cluster left-to-right as\n    // zoomIn, zoomOut, actualSize, then whatever later plugin (or the close\n    // button) follows (DESIGN.md §3.1).\n    const removeButtons = [zoomInBtn, zoomOutBtn, actualSizeBtn].map((button) =>\n      ctx.ui.toolbar('right', button),\n    );\n\n    // w/s zoom in/out, same step as the toolbar buttons — both cases\n    // registered explicitly (registerShortcut matches event.key verbatim,\n    // no case-insensitive matching of its own) so Shift/CapsLock still work.\n    const removeShortcuts = [\n      ctx.ui.registerShortcut('w', zoomInStep),\n      ctx.ui.registerShortcut('W', zoomInStep),\n      ctx.ui.registerShortcut('s', zoomOutStep),\n      ctx.ui.registerShortcut('S', zoomOutStep),\n    ];\n\n    const offOpen = ctx.on('afterOpen', () => {\n      reset();\n      markEnabled();\n    });\n    // Un-animated, and on beforeSlide rather than only afterSlide below:\n    // SlideManager.render() (called synchronously between the two) reuses a\n    // still-cached slide's node via a plain reparent (moveIn(), no state\n    // clearing of its own) into whichever pool slot its new offset needs —\n    // there is no code path afterward that can still find *this* image to\n    // reset it. A real bug, reported from real usage: zoom in via \"Actual\n    // size\", click next — the old, still-scaled image, now reparented into\n    // the (unclipped, per shoji.css) neighboring slot, visibly bled into the\n    // new slide instead of being invisible off-screen like an unzoomed one\n    // always is. Resetting here, while getActiveMedia() still resolves to\n    // the about-to-move image, clears it before that reparent ever happens.\n    const offBeforeSlide = ctx.on('beforeSlide', () => reset());\n    const offSlide = ctx.on('afterSlide', () => {\n      reset();\n      markEnabled();\n    });\n    // Fires synchronously, before Gallery.close() measures the active\n    // media's rect to compute the zoom-out-to-thumbnail animation — reset\n    // here (not just afterOpen/afterSlide) so that measurement sees the\n    // image at its natural position/scale, not wherever it was left\n    // zoomed/panned to. Skipping this made closing while zoomed animate\n    // from the image's current (zoomed, often partly off-screen) rect\n    // instead of its real thumbnail-relative size, landing \"closed\" at a\n    // seemingly random spot instead of visibly shrinking into the thumbnail.\n    const offBeforeClose = ctx.on('beforeClose', () => reset());\n    const unregisterGate = gallery.registerZoomGate(() => scale > ZOOM_EPSILON);\n    markEnabled(); // covers the (unusual but possible) case of the gallery already being open when this plugin initializes\n\n    return () => {\n      for (const remove of removeButtons) remove();\n      for (const remove of removeShortcuts) remove();\n      offOpen();\n      offBeforeSlide();\n      offSlide();\n      offBeforeClose();\n      offPinchStart();\n      offPinchMove();\n      offPinchEnd();\n      offDoubleTap();\n      offWheelZoom();\n      outer.removeEventListener('pointerdown', onPointerDown);\n      outer.removeEventListener('pointermove', onPointerMove);\n      outer.removeEventListener('pointerup', onPointerUp);\n      outer.removeEventListener('pointercancel', onPointerUp);\n      unregisterGate();\n      reset();\n      getImg()?.classList.remove('shoji-zoom-enabled');\n    };\n  },\n};\n"],"names":[],"mappings":"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"}

package/dist/esm/plugins/zoom/zoomMath.d.ts

@@ -0,0 +1,24 @@
+/** A viewport-relative rect: `{left, top, width, height}`, same shape as `DOMRect` but plain-object so it's trivial to mock in tests. */
+export interface ZoomBox {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+export interface PanOffset {
+    tx: number;
+    ty: number;
+}
+export declare function clampScale(scale: number, min: number, max: number): number;
+/** Keeps the scaled+panned content's edges from retreating inside `container`'s edges (no empty gap beyond the image), on both axes independently. */
+export declare function clampPan(natural: ZoomBox, container: ZoomBox, scale: number, pan: PanOffset): PanOffset;
+/**
+ * The standard "zoom toward a point" formula: adjusts pan so the viewport
+ * point `(anchorX, anchorY)` stays visually fixed as scale changes from
+ * `oldScale` to `newScale`, given `transform-origin: 0 0` (see `natural`'s
+ * doc comment on `clampAxis` above for why that makes this tractable —
+ * scaling never moves the natural box's own top-left on screen, only `pan`
+ * does). Callers still need to clamp the result with `clampPan` afterward;
+ * this only solves the anchor-fixed part, not boundary containment.
+ */
+export declare function zoomTowardPoint(natural: ZoomBox, pan: PanOffset, oldScale: number, newScale: number, anchorX: number, anchorY: number): PanOffset;

package/dist/esm/transitions/SlideTransition.d.ts

@@ -0,0 +1,25 @@
+import { SlideManager } from '../core/SlideManager';
+import { TransitionPreset } from './presets';
+/**
+ * DESIGN.md §2.5 — animates a slide-to-slide navigation via a temporary
+ * "ghost": a clone of the outgoing `.shoji-slide-media`, positioned over
+ * the real slot, playing the preset's `leave` keyframe while `swapContent`
+ * (the real `SlideManager.render()` reassignment) runs invisibly underneath
+ * it. The newly-swapped-in real active media then plays `enter`. Both
+ * animate concurrently.
+ *
+ * Deliberately separate from the gesture engine's own live-drag/settle
+ * animation (`GestureController.ts`, §2.4): `mode` is a discrete "jump" for
+ * programmatic navigation, not layered onto a continuous drag — a completed
+ * swipe always uses its own pool-shift regardless of `mode`. See
+ * `Gallery.navigate()`'s `animate` flag.
+ */
+export declare class SlideTransition {
+    private readonly slides;
+    constructor(slides: SlideManager);
+    /** A recognized built-in preset (`TRANSITION_PRESETS`). */
+    animate(preset: TransitionPreset, direction: 1 | -1, swapContent: () => void): void;
+    /** An unrecognized `mode` string: a host-supplied CSS class pair (`shoji-transition-<mode>-leave`/`-enter`), not an error — §2.5's "custom animation = a CSS class pair, no JS needed." */
+    animateCustom(mode: string, direction: 1 | -1, swapContent: () => void): void;
+    private run;
+}

package/dist/esm/transitions/presets.d.ts

@@ -0,0 +1,21 @@
+/**
+ * DESIGN.md §2.5 — built-in presets, generated from a small config→transform
+ * DSL rather than ~20 hand-written keyframe functions. `enter(direction)` is
+ * where the incoming slide starts (then transitions to natural: `transform:
+ * none; opacity: 1`); `leave(direction)` is where the outgoing clone (see
+ * `SlideTransition.ts`) ends up (starts at natural, transitions to this).
+ * `direction` is `1` for next()-style, `-1` for prev()-style — presets that
+ * don't care (fade, zoom, flipX, deck, drop...) never read it. transform/
+ * opacity only, per CLAUDE.md's hardware-accelerated-CSS3 constraint.
+ */
+export interface TransitionState {
+    transform: string;
+    opacity: number;
+}
+export interface TransitionPreset {
+    name: string;
+    enter(direction: 1 | -1): TransitionState;
+    leave(direction: 1 | -1): TransitionState;
+}
+/** Keyed by name for `Gallery`'s `mode`/`mobileSettings.mode` lookup — an unrecognized string is treated as a custom CSS-class-pair mode instead (see `SlideTransition.animateCustom`), not an error. */
+export declare const TRANSITION_PRESETS: Readonly<Record<string, TransitionPreset>>;