@michaelyagi/shoji 0.1.0-alpha.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael Yagi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,83 @@
+# Shoji
+
+[![CI](https://github.com/MichaelYagi/shoji/actions/workflows/ci.yml/badge.svg)](https://github.com/MichaelYagi/shoji/actions/workflows/ci.yml)
+[![npm (alpha)](https://img.shields.io/npm/v/%40michaelyagi%2Fshoji/alpha.svg)](https://www.npmjs.com/package/@michaelyagi/shoji)
+
+A zero-dependency, plugin-first TypeScript lightbox/gallery. Drop in two `<script>`/`<link>` tags, or install from npm — everything beyond the minimal lightbox, including every official plugin, is opt-in.
+
+> **Status: alpha.** The API is still settling — expect breaking changes between `0.x` releases.
+
+## Features
+
+- **Zero runtime dependencies**, TypeScript strict mode throughout.
+- **Selector mode or dynamic mode** — scan existing DOM markup, or hand it an `items` array.
+- **Plugin system** — zoom (pinch/pan/wheel), fullscreen, rotate/flip, autoplay/slideshow, active-thumbnail sync, YouTube video embeds, and a grid/masonry/justified layout engine, each independently opt-in.
+- **Accessibility is not a plugin** — keyboard nav, focus trapping, ARIA roles, and screen-reader announcements live in core.
+- **Themeable via CSS custom properties** — no hardcoded colors/sizes in JS.
+- **Single-file distribution** — `dist/shoji.js` + `dist/shoji.css` (core + every official plugin, self-registering) for zero-setup `<script>` tag use, plus tree-shakable per-plugin ESM entries for bundler users.
+- Size-budgeted and CI-enforced: core ≤ 21 kB, each plugin ≤ 8 kB, full bundle ≤ 90 kB (all min+gzip).
+
+## Install
+
+```html
+<link rel="stylesheet" href="shoji.min.css" />
+<script src="shoji.min.js"></script>
+<script>
+  new Shoji('#gallery');
+</script>
+```
+
+```bash
+npm install @michaelyagi/shoji@alpha
+```
+
+```js
+import Shoji from '@michaelyagi/shoji';
+import '@michaelyagi/shoji/style.css';
+
+new Shoji('#gallery', { plugins: [Shoji.Zoom] });
+```
+
+## Quickstart
+
+```html
+<div id="gallery">
+  <a href="photo-1-full.jpg"><img src="photo-1-thumb.jpg" alt="Sunset over the bay" /></a>
+  <a href="photo-2-full.jpg"><img src="photo-2-thumb.jpg" alt="Mountain trail" /></a>
+</div>
+```
+
+```js
+new Shoji('#gallery');
+```
+
+No items array, no options object, no plugins — every default is chosen so this is a complete integration. See [`docs/guides/getting-started.html`](docs/guides/getting-started.html) for dynamic mode, the full `data-shoji-*` attribute mapping, and every `GalleryItem` field.
+
+## Docs
+
+- **[michaelyagi.github.io/shoji](https://michaelyagi.github.io/shoji)** — the published docs site, auto-deployed from `main` (see `.github/workflows/ci.yml`'s `publish-docs` job).
+- **[npmjs.com/package/@michaelyagi/shoji](https://www.npmjs.com/package/@michaelyagi/shoji)** — the published package, auto-published on tagged releases (see `.github/workflows/ci.yml`'s `publish-npm` job).
+- [`docs/index.html`](docs/index.html) — the same guides/examples/API reference, as local static HTML (open directly, or run `npm run docs` first to regenerate the API reference from source).
+- [`docs/examples/`](docs/examples/) — real, runnable, self-contained example pages (copy one wholesale into your own project).
+- [`DESIGN.md`](DESIGN.md) — the living architecture/spec document this project is built from.
+
+## Development
+
+```bash
+npm install
+npm run dev        # Vite dev server over demo/
+npm run build      # dist/shoji.(min.)js + .css, plus per-plugin ESM entries
+npm test           # Vitest unit tests
+npm run test:e2e   # Playwright e2e (chromium/firefox/webkit/mobile)
+npm run lint       # eslint + prettier check
+npm run typecheck  # tsc --noEmit
+npm run size       # build + size-limit budget check
+npm run docs       # regenerate docs/api/ (typedoc)
+npm run verify     # the full gate: typecheck + lint + unit + e2e + size
+```
+
+`demo/assets/` (sample photos/video for the local demo pages) is gitignored — drop your own media there, or the demo pages just render with 0 items.
+
+## License
+
+MIT © Michael Yagi

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

@@ -0,0 +1,16 @@
+export type EventMap = Record<string, unknown>;
+export type Unsubscribe = () => void;
+type Listener<T> = (detail: T) => void;
+/**
+ * Typed pub/sub used by Gallery and every plugin (`ctx.on`). Plugin
+ * subscriptions are unsubscribed automatically on destroy by the caller
+ * that owns the PluginContext, not by this class.
+ */
+export declare class EventBus<Events extends EventMap> {
+    private listeners;
+    on<K extends keyof Events>(event: K, fn: Listener<Events[K]>): Unsubscribe;
+    off<K extends keyof Events>(event: K, fn: Listener<Events[K]>): void;
+    emit<K extends keyof Events>(event: K, detail: Events[K]): void;
+    clear(): void;
+}
+export {};

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

@@ -0,0 +1,9 @@
+/** DESIGN.md §2.6 — focus trap on open, focus restore on close, Tab cycles within the dialog. */
+export declare class FocusTrap {
+    private container;
+    private previouslyFocused;
+    private readonly onKeydown;
+    private getFocusable;
+    activate(container: HTMLElement): void;
+    deactivate(): void;
+}

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

@@ -0,0 +1,221 @@
+import { Unsubscribe } from './EventBus';
+import { GalleryEvents, GalleryItem, GalleryItemInput, GalleryOptions } from './types';
+/**
+ * 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
+ * region (§2.6, non-optional), gestures (§2.4, via `GestureController`) and
+ * slide-to-slide transitions (§2.5, via `SlideTransition`).
+ */
+export declare class Gallery {
+    /** DESIGN.md §2.7 — the live instance mounted on `el`, or `undefined` if none exists there (or it's since been destroyed). */
+    static getInstance(el: HTMLElement): Gallery | undefined;
+    /** DESIGN.md §2.7 — every live instance, e.g. for page-wide teardown or devtools inspection. */
+    static instances(): IterableIterator<Gallery>;
+    /** Not `readonly` — `reinit()` (§2.7) reassigns this + every option-derived field below; initializers here just satisfy strict-init. */
+    options: GalleryOptions;
+    readonly element: HTMLElement;
+    private readonly bus;
+    private selector;
+    private isDynamicMode;
+    private preload;
+    private locale;
+    private showCounter;
+    private captionVisibleOnVideo;
+    private loop;
+    private closable;
+    private autoHideDelay;
+    private readonly focusTrap;
+    private readonly liveRegion;
+    private autoHideTimer;
+    private autoHidden;
+    private hoveredControlCount;
+    private isClosing;
+    private itemList;
+    private scannedElements;
+    private activeIndex;
+    private opened;
+    private destroyed;
+    private slides;
+    private dom;
+    private gesture;
+    private transition;
+    private readonly shortcuts;
+    private readonly pluginStorage;
+    /** Backs `getActivePlugins()`. */
+    private readonly activePluginNames;
+    private readonly videoProviders;
+    private zoomGate;
+    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. */
+    private readonly onActivity;
+    private readonly onKeydown;
+    constructor(target: HTMLElement | string, options?: GalleryOptions);
+    /** Everything the constructor does after `this.element` is resolved — shared with `reinit()` (§2.7). */
+    private applyOptions;
+    get items(): readonly GalleryItem[];
+    get currentIndex(): number;
+    /** True from the first `open()` until `close()`/`destroy()`. */
+    get isOpen(): boolean;
+    /** True once `destroy()` has run. */
+    get isDestroyed(): boolean;
+    /** Whether auto-hide (§2.8) currently has controls faded. */
+    get controlsHidden(): boolean;
+    /** Names of plugins that actually initialized. */
+    getActivePlugins(): string[];
+    /** The active slide's `.shoji-slide-media` container. Empty before the first `open()`; `null` only after `destroy()`. */
+    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;
+    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. */
+    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.
+     */
+    private pluginToolbar;
+    private buildToolbarButton;
+    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. */
+    private wireControlHover;
+    /**
+     * DESIGN.md §2.8 — paused only by a real *hover*. Used to also treat a
+     * *focused* control as active via `document.activeElement`, but a click
+     * leaves a `<button>` focused indefinitely, permanently blocking
+     * `hideControls()`. Focus still counts as activity (`focusin` →
+     * `onActivity()`), it just no longer blocks the eventual hide.
+     */
+    private isControlActive;
+    /**
+     * The thumbnail for `index` — what the zoom transition animates to/from,
+     * and what `activeThumbnail` marks/scrolls-to. `data-shoji-id` is an
+     * explicit opt-in that works in any mode (needed for dynamic mode, which
+     * has no scanned DOM); checked first so it can override selector mode's
+     * default `scannedElements[index]` too, e.g. to target an inner element.
+     */
+    getOriginElement(index: number): HTMLElement | null;
+    private scheduleAutoHide;
+    private hideControls;
+    private showControls;
+    /**
+     * DESIGN.md §2.1 — `caption` is `string | HTMLElement | DangerousHtmlCaption`:
+     * a plain string renders as text (`textContent`, auto-escaped, safe by
+     * default); an `HTMLElement` is appended as real DOM (the host built it);
+     * `{ dangerouslySetInnerHTML }` renders raw, unescaped HTML via `innerHTML`
+     * — Shoji does not sanitize it, the host must, same contract as React's
+     * identically-named escape hatch. Returns whether the caption element
+     * should be hidden.
+     */
+    private renderCaption;
+    /**
+     * `.shoji-toolbar-button` only — never `.shoji-close`/`.shoji-nav`, which
+     * are different classes entirely, so this can't accidentally block
+     * closing or navigating away from a slow-loading slide. `tabIndex = -1`
+     * (not just the CSS below) so a keyboard user tabbing through the
+     * toolbar skips these entirely while disabled, not just visually dims
+     * them — `pointer-events: none` alone wouldn't stop Enter/Space
+     * activating an already-focused button.
+     */
+    private setSlideLoading;
+    /**
+     * Content is always kept current (correct the instant loading finishes,
+     * no text flash) — only `hidden` also gates on `isActiveReady()`, so a
+     * caption for the *new* slide can't sit there readable while the
+     * image/video it describes is still a spinner.
+     */
+    private updateCaptionVisibility;
+    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>. */
+    private resolveOpenPlaceholderSrc;
+    /**
+     * DESIGN.md §2.2/§2.6 — navigates while open; always clamps an explicit
+     * out-of-range index (this is a directed jump, not a step — `loop` only
+     * affects `next()`/`prev()`, see below). No-op if not open. `animate`
+     * (default `true`) runs the configured §2.5 transition; hosts that want
+     * an instant jump — e.g. syncing to an external index without a visual
+     * flourish — can pass `{ animate: false }`.
+     */
+    goTo(index: number, options?: {
+        animate?: boolean;
+    }): void;
+    next(): void;
+    prev(): void;
+    private nextIndex;
+    private prevIndex;
+    /**
+     * DESIGN.md §2.5 — the shared path behind `goTo()`/`next()`/`prev()`.
+     * `animate` is `false` only for `GestureController`'s own host callbacks
+     * (see `ensureLightbox()`): a gesture-completed swipe already played its
+     * own live-drag/settle animation, so running a *second*, `mode`-based
+     * transition on top of it would visibly double-animate. Every other
+     * caller — buttons, keyboard, autoplay, a plugin calling `goTo()` — gets
+     * 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;
+    /** `item.width`/`height`, else origin's `naturalWidth`/`naturalHeight` (accurate when `item.thumb` is unset). Feeds `computeTransform`'s letterbox-aware sizing. */
+    private resolveAspectRatio;
+    /**
+     * Idempotent on purpose: a pending zoom-out's `transitionend`/fallback
+     * timeout can still fire after `destroy()` has already force-finished the
+     * close (§ destroy() below) — the `!this.opened` guard makes that a no-op
+     * instead of a second `close`/`afterClose` emission on a torn-down gallery.
+     */
+    private finishClose;
+    /** DESIGN.md §2.1 — diffs by id (fallback src), preserving the active slide. */
+    updateSlides(items: GalleryItemInput[], currentIndex?: number): void;
+    /**
+     * Sugar over `updateSlides()` for the common "insert some items" case —
+     * splices `items` into a copy of the current list at `atIndex` (default:
+     * append at the end) and hands the result to `updateSlides()`, which
+     * still does all the real work (active-item preservation, live re-render
+     * if open, `itemsUpdated`). `atIndex` follows `Array.prototype.splice`'s
+     * own semantics (negative counts from the end, out-of-range clamps) —
+     * no extra validation on top of that.
+     */
+    addSlides(items: GalleryItemInput[], atIndex?: number): void;
+    /**
+     * Sugar over `updateSlides()` for the common "remove some items" case.
+     * Accepts a single id/index or an array mixing both: a `string` matches
+     * the same `id ?? src` key `updateSlides()` already uses for active-item
+     * preservation, a `number` matches that position in the *current*
+     * `items` list (resolved against the list as it is now, before any
+     * removal — passing `[0, 1]` removes the first two items, not "index 0,
+     * then whatever became index 1 after that").
+     */
+    removeSlides(match: string | number | Array<string | number>): void;
+    /** DESIGN.md §2.7 — selector-mode only; sugar over updateSlides() sourced from a DOM rescan. */
+    refresh(): void;
+    /** Shared by `destroy()`/`reinit()` (§2.7): force-close, run plugin cleanups, drop gesture/transition/slide/dialog. */
+    private teardown;
+    destroy(): void;
+    /**
+     * DESIGN.md §2.7 — full teardown + reconstruction on `this`, not a new
+     * object: `Shoji.getInstance(el)`/any held reference keeps working across
+     * the call, unlike `destroy()` + `new Shoji(...)`. Omit `options` to
+     * rebuild unchanged (a hard reset); pass options to reconfigure
+     * structurally. `gallery.on(...)` listeners do NOT survive — the event
+     * bus is fully cleared, same as `destroy()` — re-`on()` anything needed.
+     */
+    reinit(options?: GalleryOptions): void;
+}

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

@@ -0,0 +1,57 @@
+import { GestureEngineOptions } from '../gestures/GestureEngine';
+import { SlideManager } from './SlideManager';
+/**
+ * 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.
+ */
+export declare const INTERACTIVE_CONTROL_SELECTOR = "button, video, input, select, textarea, a[href], [data-shoji-no-drag]";
+/** What `GestureController` needs from `Gallery` — narrow on purpose, so this module never reaches into Gallery internals beyond this contract. */
+export interface GestureControllerHost {
+    dialog: HTMLElement;
+    slides: SlideManager;
+    canGoNext(): boolean;
+    canGoPrev(): boolean;
+    next(): void;
+    prev(): void;
+    close(): void;
+    /** `closable: false` (GalleryOptions) — false suspends vertical drag-to-close entirely: no live feedback, release never calls `close()`. */
+    canClose(): boolean;
+    onActivity(): void;
+    /** DESIGN.md §4-zoom — true while zoomed; suspends drag-to-navigate/close. */
+    isZoomed(): boolean;
+}
+/** Relays for gestures core has no built-in behavior for — DESIGN.md §2.4; the zoom plugin (§4-zoom) consumes these via the gallery event bus. */
+export interface GestureRelayCallbacks {
+    onTap(x: number, y: number): void;
+    onDoubleTap(x: number, y: number): void;
+    onPinchStart(centerX: number, centerY: number): void;
+    onPinchMove(scale: number, centerX: number, centerY: number): void;
+    onPinchEnd(): void;
+    onWheelZoom(deltaScale: number, x: number, y: number): void;
+}
+/**
+ * DESIGN.md §2.4 — owns the gesture-driven side of the lightbox: horizontal
+ * drag-to-navigate and vertical drag-to-close, built on `GestureEngine`
+ * (`src/gestures/`) plus the live-feedback/settle-animation mechanics
+ * specific to this lightbox's DOM. Split out of `Gallery.ts` (CLAUDE.md:
+ * files ≤ ~400 lines) — `Gallery` only constructs this, forwards the host
+ * callbacks it needs, and relays no-built-in-effect gestures onto its bus.
+ */
+export declare class GestureController {
+    private readonly host;
+    private readonly engine;
+    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. */
+    private readonly onDragMove;
+    private readonly onDragEnd;
+    /** `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. */
+    private applyVerticalDragFeedback;
+    private clearVerticalDragFeedback;
+    private finishVerticalDrag;
+}

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

@@ -0,0 +1,6 @@
+/** DESIGN.md §2.6 — visually-hidden `aria-live` region announcing slide changes. */
+export declare class LiveRegion {
+    readonly element: HTMLElement;
+    constructor();
+    announce(text: string): void;
+}

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

@@ -0,0 +1,85 @@
+import { VideoProviderRenderer } from './plugin';
+import { GalleryItem } from './types';
+export interface SlideManagerOptions {
+    preload: number;
+    /** Play-overlay button's label. */
+    playVideoLabel: string;
+    videoProviders: Map<string, VideoProviderRenderer>;
+}
+/**
+ * DESIGN.md §2.3 — only `currentIndex ± preload` exist in the DOM. Content
+ * already resident and ready is never moved between slots — the slot that
+ * already holds it just gets its own `offset` relabeled to its new pool
+ * position; only content resident nowhere yet gets built fresh into
+ * whatever's left over. O(preload) re-render cost either way, but never a
+ * DOM reparent — which matters for a provider video's `<iframe>` (§4.3):
+ * most browsers reload an iframe moved to a new parent, so a live embed can
+ * only safely change position by relabeling, never by being moved.
+ */
+export declare class SlideManager {
+    readonly element: HTMLElement;
+    private readonly slots;
+    private readonly preload;
+    private readonly playVideoLabel;
+    private readonly videoProviders;
+    private dragOffsetPx;
+    /** Ready nodes keyed by item index — trimmed to `centerIndex ± preload` each `render()`, same window the slots cover, so an evicted entry's video/iframe resources get released even if no slot ever reclaims it. */
+    private readonly cache;
+    /**
+     * Image decodes in flight, keyed by item index, not by whichever slot
+     * started them — a real bug this fixes: navigating before a preload
+     * decode resolved used to reassign that slot, abandoning the decode and
+     * starting a duplicate elsewhere, so a slow preload could never finish,
+     * only restart. `reveal()` looks up which slot currently wants this
+     * index at resolve time, so a reshuffled pool still lands it correctly.
+     */
+    private readonly pending;
+    constructor(options: SlideManagerOptions);
+    /** The active slot's `.shoji-slide-media` — not `.shoji-slide`, whose transform is owned by pool-offset positioning. */
+    getActiveMedia(): HTMLElement | null;
+    /** False while the active slot's content is still decoding — Gallery.ts uses this right after `render()` to show the loading state immediately, without waiting for `onLoad`. */
+    isActiveReady(): boolean;
+    /**
+     * DESIGN.md §2.4 — live drag-to-navigate feedback: every slot's
+     * structural `offset * 100%` position gets this same `px` added on top,
+     * so dragging left/right visually slides the whole pool together (the
+     * adjacent preloaded slot already exists at `±100%`) — no new DOM, no
+     * content re-render mid-drag. `transition`: `null` during the live drag
+     * (1:1 with the pointer); a real value only for the post-release settle
+     * animation, reset back to `null` once that transition ends.
+     */
+    setDragOffset(px: number, transition: string | null): void;
+    /** The pool slot's `.shoji-slide` root at a structural offset — what the drag settle animation (§2.4) waits for `transitionend` on. */
+    getSlotRoot(offset: number): HTMLElement | null;
+    private applyTransforms;
+    /** Re-renders whichever slots need a different item; `onLoad` fires per index once its media settles. `openPlaceholderSrc` (only from `Gallery.open()`) swaps the centerIndex slot's spinner for a low-res placeholder once it decodes, if not already ready. */
+    render(items: readonly GalleryItem[], centerIndex: number, onLoad: (index: number) => void, openPlaceholderSrc?: string): void;
+    private applyAspect;
+    /** Releases the slot's old content and swaps the new node in, caching it. `extra` rides as a second child. `ensureImageDecoding` goes through `moveIn` instead. */
+    private swapIn;
+    /**
+     * Inserts a just-decoded node into the slot waiting on it — skips
+     * `releaseVideo`, unlike `swapIn`: this is its first insertion anywhere,
+     * nothing outgoing to release. `render()`'s claim pass (Phase 1) never
+     * calls this — it reuses `ready` content in place, no DOM touch at all.
+     */
+    private moveIn;
+    /** Starts decoding `item` for `index`, only if nothing already is (see `pending`). Resolves by looking up whichever slot currently wants this index, not the one active when the decode started. */
+    private ensureImageDecoding;
+    /** DESIGN.md §2.3 — swaps the spinner for the placeholder once *it* decodes, not immediately: `item.thumb` is often just `item.src` again, so an undecoded placeholder can leave as long a blank gap as the spinner it replaces. */
+    private revealOpenPlaceholder;
+    /** Native `<video controls>` — real playback, not just a poster. Not autoplayed/muted: a deliberate click-to-play, not a background loop. */
+    private renderVideo;
+    /** Tracks the video's own play/pause/ended state. Hide `.shoji-video-play-overlay` in CSS to opt out. */
+    private createVideoPlayOverlay;
+    /** DESIGN.md §4-video. Unregistered provider → same placeholder as no-source video. */
+    private renderProviderVideo;
+    destroy(): void;
+}
+/**
+ * Pauses whatever's playing in `media` — native `<video>`, or a provider
+ * embed wired via `wirePlayableContract` (§4-video) — without
+ * releasing/destroying it, unlike `releaseVideo` above. `Gallery` calls
+ * this on `close()` and before every navigation, on the outgoing slide.
+ */
+export declare function pauseMedia(media: HTMLElement | null): void;

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

@@ -0,0 +1,2 @@
+export declare function lockBodyScroll(): void;
+export declare function unlockBodyScroll(): void;

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

@@ -0,0 +1,27 @@
+export interface LightboxLabels {
+    close: string;
+    previous: string;
+    next: string;
+    showCaption: string;
+    hideCaption: string;
+}
+export interface LightboxDom {
+    outer: HTMLElement;
+    dialog: HTMLElement;
+    counter: HTMLElement;
+    caption: HTMLElement;
+    closeButton: HTMLButtonElement;
+    prevButton: HTMLButtonElement;
+    nextButton: HTMLButtonElement;
+    captionToggleButton: HTMLButtonElement;
+    /** DESIGN.md §3 — `ctx.ui.toolbar(slot, ...)` inserts into these; close lives in `right`. */
+    toolbarLeft: HTMLElement;
+    toolbarCenter: HTMLElement;
+    toolbarRight: HTMLElement;
+}
+/**
+ * DESIGN.md §2.6 — `.shoji-outer` is the exact element `ctx.ui.outer()` (§3)
+ * will return to plugins once the real plugin loader exists. Close/prev/next
+ * are core-owned baseline controls, not routed through any plugin API.
+ */
+export declare function buildLightboxDom(slides: HTMLElement, labels: LightboxLabels): LightboxDom;

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

@@ -0,0 +1,6 @@
+/** DESIGN.md §9 — inline SVG, stroke = currentColor, overridable per-button. */
+export declare const CLOSE_ICON = "<svg viewBox=\"0 0 24 24\" width=\"24\" height=\"24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\"><path d=\"M6 6l12 12M18 6L6 18\"/></svg>";
+export declare const PREV_ICON = "<svg viewBox=\"0 0 24 24\" width=\"24\" height=\"24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\"><path d=\"M15 6l-6 6 6 6\"/></svg>";
+export declare const NEXT_ICON = "<svg viewBox=\"0 0 24 24\" width=\"24\" height=\"24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\"><path d=\"M9 6l6 6-6 6\"/></svg>";
+export declare const PLAY_ICON = "<svg viewBox=\"0 0 24 24\" width=\"28\" height=\"28\" fill=\"currentColor\"><path d=\"M8 5v14l11-7z\"/></svg>";
+export declare const CAPTION_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=\"3\" y=\"5\" width=\"18\" height=\"14\" rx=\"2\"/><path d=\"M7 10h10M7 14h6\"/></svg>";

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

@@ -0,0 +1,5 @@
+export { Gallery } from './Gallery';
+export { EventBus } from './EventBus';
+export type { Unsubscribe } from './EventBus';
+export type { GalleryItem, GalleryOptions, GalleryEvents, MediaSource, VideoDescriptor, } from './types';
+export type { ShojiPlugin, PluginContext, ButtonSpec, KeySpec } from './plugin';