@mohasinac/appkit 4.70.0 → 4.71.2

package/dist/ui/components/MediaImage.js

@@ -0,0 +1,194 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import Image from "next/image.js";
+import { useEffect, useRef, useState } from "react";
+import { Div } from "./Div.js";
+import { Row } from "./Layout.js";
+import { Span } from "./Typography.js";
+import { ROUNDED_MAP, SHADOW_MAP } from "./surface-tokens.js";
+import { MEDIA_PROXY_PREFIX, resolveMediaUrl } from "../../utils/media-url.js";
+const SIZE_HINTS = {
+    thumbnail: "(max-width: 640px) 80px, (max-width: 1024px) 96px, 112px",
+    card: "(max-width: 640px) 50vw, (max-width: 1024px) 33vw, 25vw",
+    // Use a constrained fallback instead of unconditional 100vw to avoid
+    // the Next.js runtime warning when `fill` is used inside non-viewport
+    // width containers (cards, sliders). This still provides a helpful
+    // responsive hint while avoiding false-positive perf warnings.
+    hero: "(max-width: 768px) 100vw, 1200px",
+    banner: "(max-width: 768px) 100vw, 1200px",
+    gallery: "(max-width: 640px) 100vw, (max-width: 1024px) 50vw, 33vw",
+    avatar: "(max-width: 640px) 48px, 56px",
+};
+/**
+ * The BOX each size establishes on the wrapper.
+ *
+ * 🛑 THIS IS THE FIX FOR A DEFECT THAT MADE `size` A LIE. Until 2026-10-21 the
+ * `size` prop fed exactly two things — `SIZE_HINTS` (the `sizes` download
+ * attribute) and `FALLBACK_ICONS` (which emoji) — and **neither affected
+ * layout**. Every render branch was `relative w-full h-full` around an
+ * `<Image fill>`, so the component had an unstated contract: the PARENT must
+ * supply a definite height. `h-full` against an auto-height parent is 0, and a
+ * `fill` child is absolutely positioned and contributes none of its own, so
+ * the whole thing collapsed to zero and rendered as blank space.
+ *
+ * `size="hero"` therefore read as "this is hero-shaped" and produced **zero
+ * pixels**. `ProductGrid` worked only because its own call site wraps the
+ * image in `aspect-square` — so `card` was correct BY ACCIDENT OF WHERE IT WAS
+ * USED, which is why the reported symptom was "anything which is not a card".
+ *
+ * Same mechanism as Root Cause #68, one component over, and fixed the same
+ * way: at the primitive, not at ~100 call sites. A `Record<MediaImageSize, …>`
+ * means a seventh size cannot be added without declaring its shape.
+ *
+ * Call sites that must genuinely fill a parent they have already sized pass
+ * `fill` — see that prop.
+ */
+const SIZE_BOX = {
+    thumbnail: "aspect-square",
+    card: "aspect-square",
+    gallery: "aspect-square",
+    avatar: "aspect-square",
+    hero: "aspect-video",
+    banner: "aspect-[3/1]",
+};
+const FALLBACK_ICONS = {
+    thumbnail: "📦",
+    card: "📦",
+    hero: "🖼️",
+    banner: "🖼️",
+    gallery: "📦",
+    avatar: "👤",
+};
+// A freshly-uploaded media slug can legitimately 404 for a brief window
+// right after upload — the Firestore doc write and the Storage object write
+// don't land atomically (see src/app/api/media/[...slug]/route.ts's own
+// comment on this race). Retry with backoff before latching the fallback
+// icon, instead of failing permanently on the very first request.
+const MAX_LOAD_RETRIES = 3;
+const RETRY_BACKOFF_MS = [600, 1200, 2400];
+/**
+ * Only `/media/<slug>` may be retried.
+ *
+ * 🛑 The retry appends `?retry=N`, which mints a BRAND-NEW CDN cache key that is
+ * guaranteed cold — so a failing image costs up to 4 cold function invocations
+ * instead of 1, on precisely the images that are already flaky. That is a real
+ * cost multiplier and it suspended this project once (HTTP 402, 2026-10-09).
+ *
+ * It is worth paying for our own Storage objects, because the post-upload race
+ * above is genuine and transient — retrying actually succeeds. It is NOT worth
+ * paying for `/api/media/ext`: there is no upload, the upstream is a third party
+ * we do not control, and an upstream that just failed will almost certainly fail
+ * again. Those fall straight through to the fallback icon on the first error.
+ */
+function isRetryableSrc(resolvedSrc) {
+    return resolvedSrc.startsWith(MEDIA_PROXY_PREFIX);
+}
+/** Resolve every URL in a comma-separated srcset string through the media proxy. */
+function resolveSrcSet(input) {
+    return input
+        .split(",")
+        .map((entry) => {
+        const trimmed = entry.trim();
+        if (!trimmed)
+            return "";
+        // Each entry is `<url> <descriptor>?` — split on whitespace.
+        const [url, ...descriptors] = trimmed.split(/\s+/);
+        const resolved = resolveMediaUrl(url) ?? url;
+        return descriptors.length ? `${resolved} ${descriptors.join(" ")}` : resolved;
+    })
+        .filter(Boolean)
+        .join(", ");
+}
+export function MediaImage({ src, alt, size = "card", priority = false, loading, fetchPriority, objectFit = "contain", fallback, className, rounded, shadow, style, sources, onError, fill = false, }) {
+    const [hasError, setHasError] = useState(false);
+    const [isLoaded, setIsLoaded] = useState(false);
+    const [retryCount, setRetryCount] = useState(0);
+    const retryTimeoutRef = useRef(null);
+    const icon = fallback ?? FALLBACK_ICONS[size];
+    const fitClass = objectFit === "contain" ? "object-contain" : "object-cover";
+    const resolvedSrc = resolveMediaUrl(src);
+    /*
+     * The wrapper's box: the size's own shape by default, the parent's when the
+     * caller opts in with `fill`. Shared by all three render branches below so
+     * the placeholder, the `<picture>` and the plain `<Image>` cannot disagree
+     * about their dimensions — a fallback that occupies a different box from the
+     * image it replaces makes a grid jump as things load.
+     *
+     * 🛑 `max-h-full` IS THE OTHER HALF OF SIZE_BOX, added 2026-10-23. SIZE_BOX
+     * alone fixed the auto-height parent and broke the ALREADY-SIZED one: a
+     * parent that is 320x128 got a 320x320 box, so `overflow-hidden` cropped it
+     * to the top 40% of a letterboxed square. Measured 89 of 143 call sites in
+     * that shape — every image preview on the review, document and site-settings
+     * surfaces. `max-height:100%` resolves to `none` against an auto-height
+     * parent, so it clamps ONLY in the broken case.
+     *
+     * Measured in a browser (box for each parent shape), not argued:
+     *
+     *   parent               w-full aspect  +max-h-full   +h-full
+     *   320x128 definite     320x320  ✗     320x128  ✓    320x128 ✓
+     *   h128, width shrink   320x320  ✗     320x128  ✓    320x128 ✓
+     *   width 200, h AUTO    200x200  ✓     200x200  ✓    200x784 ✗
+     *   64px thumb stretched
+     *     by a flex row       64x64   ✓      64x64   ✓     64x90  ✗
+     *
+     * So `h-full` is NOT the fix — it wins over `aspect-ratio` whenever the
+     * parent's height is definite, including the height a flex/grid row hands a
+     * thumbnail by stretching it. That is why this is a MAX and not a height.
+     */
+    const boxClass = fill ? "h-full" : `${SIZE_BOX[size]} max-h-full`;
+    // Reset error/load/retry state whenever the resolved src actually changes.
+    // Without this, a component instance that hit a load failure once (e.g.
+    // lost the post-upload propagation race above) latches hasError forever,
+    // even across a later prop change to a src that would now succeed.
+    useEffect(() => {
+        setHasError(false);
+        setIsLoaded(false);
+        setRetryCount(0);
+        return () => {
+            if (retryTimeoutRef.current) {
+                clearTimeout(retryTimeoutRef.current);
+                retryTimeoutRef.current = null;
+            }
+        };
+    }, [resolvedSrc]);
+    const wrapperExtra = [
+        rounded ? ROUNDED_MAP[rounded] : "",
+        shadow ? SHADOW_MAP[shadow] : "",
+        className ?? "",
+    ].filter(Boolean).join(" ");
+    const handleError = () => {
+        if (resolvedSrc && isRetryableSrc(resolvedSrc) && retryCount < MAX_LOAD_RETRIES) {
+            retryTimeoutRef.current = setTimeout(() => {
+                setRetryCount((count) => count + 1);
+            }, RETRY_BACKOFF_MS[retryCount]);
+            return;
+        }
+        setHasError(true);
+        onError?.();
+    };
+    if (!resolvedSrc || hasError) {
+        return (_jsx(Row, { className: `relative w-full ${boxClass} overflow-hidden text-zinc-400 text-[length:var(--appkit-text-4xl)]${wrapperExtra ? ` ${wrapperExtra}` : ""}`, align: "center", justify: "center", surface: "subtle", role: "img", "aria-label": alt, children: _jsx(Span, { "aria-hidden": "true", children: icon }) }));
+    }
+    const isSvg = resolvedSrc.toLowerCase().endsWith(".svg") ||
+        resolvedSrc.includes("image/svg") ||
+        /[./]svg(\?|$)/i.test(resolvedSrc);
+    // Cache-bust the retried request so a browser-cached 404 response isn't
+    // silently re-served — the underlying URL is otherwise byte-identical.
+    const requestSrc = retryCount > 0
+        ? `${resolvedSrc}${resolvedSrc.includes("?") ? "&" : "?"}retry=${retryCount}`
+        : resolvedSrc;
+    // An explicit hint always wins; otherwise mirror what `priority` already
+    // implies, so existing call sites keep their current behaviour exactly.
+    const resolvedFetchPriority = fetchPriority ?? (priority ? "high" : undefined);
+    // Art-directed `<picture>` path — bypasses Next.js `<Image>` because the
+    // browser must pick the matching `<source>` itself. Loading + decoding hints
+    // come from the consumer's preset.
+    if (sources && sources.length > 0) {
+        return (_jsxs(Div, { className: `relative w-full ${boxClass} overflow-hidden${wrapperExtra ? ` ${wrapperExtra}` : ""}`, style: style, children: [!isLoaded && (_jsx(Div, { className: "absolute inset-0 animate-pulse", surface: "subtle", "aria-hidden": "true" })), _jsxs("picture", { children: [sources.map((source, index) => (_jsx("source", { srcSet: resolveSrcSet(source.srcSet), type: source.type, media: source.media }, `${source.media ?? ""}-${source.type ?? ""}-${index}`))), _jsx("img", { src: requestSrc, alt: alt, loading: loading ?? (priority ? "eager" : "lazy"), fetchPriority: resolvedFetchPriority, decoding: "async", 
+                            // catalogued primitive for media (variant catalogue allows the inner
+                            // <img> here). Object-fit + className come from typed props.
+                            className: `absolute inset-0 w-full h-full ${fitClass}`, onLoad: () => setIsLoaded(true), onError: handleError })] })] }));
+    }
+    return (_jsxs(Div, { className: `relative w-full ${boxClass} overflow-hidden${wrapperExtra ? ` ${wrapperExtra}` : ""}`, style: style, children: [!isLoaded && (_jsx(Div, { className: "absolute inset-0 animate-pulse", surface: "subtle", "aria-hidden": "true" })), _jsx(Image, { src: requestSrc, alt: alt, fill: true, priority: priority, fetchPriority: resolvedFetchPriority, loading: loading ?? (priority ? "eager" : "lazy"), className: fitClass, sizes: SIZE_HINTS[size], onLoad: () => setIsLoaded(true), onError: handleError, unoptimized: isSvg })] }));
+}
+export default MediaImage;

package/dist/ui/components/MediaLightbox.js

@@ -0,0 +1,246 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useCallback, useRef, useState } from "react";
+import { X, ZoomIn, ZoomOut, Maximize, Minimize, ChevronLeft, ChevronRight, RotateCcw, } from "lucide-react";
+import { MediaImage } from "./MediaImage.js";
+import { Button } from "./Button.js";
+import { Div } from "./Div.js";
+import { Row } from "./Layout.js";
+import { Span } from "./Typography.js";
+import { joinClasses } from "../../utils/classnames.js";
+const CLS_CLOSE_HOVER = "hover:!bg-error-surface";
+const MIN_ZOOM = 1;
+const MAX_ZOOM = 4;
+const ZOOM_STEP = 0.5;
+const DEFAULT_LABELS = {
+    prevImage: "Previous image",
+    nextImage: "Next image",
+    zoomIn: "Zoom in",
+    zoomOut: "Zoom out",
+    resetZoom: "Reset zoom",
+    enterFullscreen: "Enter fullscreen",
+    exitFullscreen: "Exit fullscreen",
+    close: "Close",
+    imageThumbnail: (n) => `Image ${n}`,
+    lightboxTitle: "Image viewer",
+};
+function IconBtn({ onClick, disabled, ariaLabel, ariaCurrent, className, children, }) {
+    return (_jsx(Button, { type: "button", onClick: onClick, disabled: disabled, "aria-label": ariaLabel, "aria-current": ariaCurrent, className: joinClasses("inline-flex items-center justify-center w-12 h-12 rounded-full bg-white/15 hover:bg-white/30 text-white border-0 active:scale-95 transition-colors disabled:opacity-30 disabled:cursor-not-allowed", className), children: children }));
+}
+// --- Controls bar sub-components ---------------------------------------------
+function LightboxControlsBar({ items, index, zoom, isFullscreen, L, goPrev, goNext, zoomIn, zoomOut, resetZoom, toggleFullscreen, onClose, }) {
+    return (_jsxs(Row, { gap: "xs", className: "bg-black/85 backdrop-blur-sm shrink-0 border-t border-white/10", padding: "inline", align: "center", justify: "center", wrap: true, children: [items.length > 1 && (_jsx(IconBtn, { onClick: (e) => { e.stopPropagation(); goPrev(); }, ariaLabel: L.prevImage, children: _jsx(ChevronLeft, { className: "w-7 h-7" }) })), _jsx(IconBtn, { onClick: zoomOut, disabled: zoom <= MIN_ZOOM, ariaLabel: L.zoomOut, children: _jsx(ZoomOut, { className: "w-7 h-7" }) }), _jsxs(Span, { color: "inverse-muted", size: "xs", className: "w-14 tabular-nums", align: "center", children: [Math.round(zoom * 100), "%"] }), _jsx(IconBtn, { onClick: zoomIn, disabled: zoom >= MAX_ZOOM, ariaLabel: L.zoomIn, children: _jsx(ZoomIn, { className: "w-7 h-7" }) }), zoom > 1 && (_jsx(IconBtn, { onClick: resetZoom, ariaLabel: L.resetZoom, children: _jsx(RotateCcw, { className: "w-7 h-7" }) })), _jsx(Span, { className: "w-px h-6 bg-white/15 mx-1 shrink-0", "aria-hidden": "true" }), _jsxs(Span, { color: "inverse-muted", size: "xs", className: "w-12 tabular-nums", align: "center", children: [index + 1, " / ", items.length] }), _jsx(Span, { className: "w-px h-6 bg-white/15 mx-1 shrink-0", "aria-hidden": "true" }), _jsx(IconBtn, { onClick: toggleFullscreen, ariaLabel: isFullscreen ? L.exitFullscreen : L.enterFullscreen, children: isFullscreen ? _jsx(Minimize, { className: "w-6 h-6" }) : _jsx(Maximize, { className: "w-6 h-6" }) }), _jsx(IconBtn, { onClick: onClose, ariaLabel: L.close, className: CLS_CLOSE_HOVER, children: _jsx(X, { className: "w-7 h-7" }) }), items.length > 1 && (_jsx(IconBtn, { onClick: (e) => { e.stopPropagation(); goNext(); }, ariaLabel: L.nextImage, children: _jsx(ChevronRight, { className: "w-7 h-7" }) }))] }));
+}
+function LightboxThumbnailStrip({ items, index, onSelect, resetZoom, L, }) {
+    return (_jsx(Row, { surface: "overlay-xl", className: "backdrop-blur-sm overflow-x-auto shrink-0", padding: "inline", justify: "center", gap: "sm", style: { paddingBottom: "calc(0.75rem + env(safe-area-inset-bottom, 0px))" }, children: items.map((item, i) => (_jsx(Button, { type: "button", onClick: () => { onSelect(i); resetZoom(); }, "aria-label": L.imageThumbnail(i + 1), "aria-current": i === index ? "true" : undefined, className: joinClasses("relative shrink-0 w-14 h-14 p-[var(--appkit-space-0)] overflow-hidden rounded-lg border-2 transition-all active:scale-95", i === index ? "border-white opacity-100" : "border-transparent opacity-40 hover:opacity-75"), children: _jsx(MediaImage, { src: item.src, alt: item.alt, size: "thumbnail" }) }, i))) }));
+}
+// --- MediaLightbox ------------------------------------------------------------
+export function MediaLightbox({ items, initialIndex = 0, isOpen, onClose, labels, }) {
+    const L = { ...DEFAULT_LABELS, ...labels };
+    const containerRef = useRef(null);
+    const imageAreaRef = useRef(null);
+    const [index, setIndex] = useState(initialIndex);
+    const [zoom, setZoom] = useState(1);
+    const [offset, setOffset] = useState({ x: 0, y: 0 });
+    const [isDragging, setIsDragging] = useState(false);
+    const [dragStart, setDragStart] = useState({ x: 0, y: 0 });
+    const [isFullscreen, setIsFullscreen] = useState(false);
+    // Sync index when caller changes the initialIndex (clicking a different thumbnail)
+    useEffect(() => {
+        if (isOpen) {
+            setIndex(initialIndex);
+            setZoom(1);
+            setOffset({ x: 0, y: 0 });
+        }
+    }, [isOpen, initialIndex]);
+    const resetZoom = useCallback(() => {
+        setZoom(1);
+        setOffset({ x: 0, y: 0 });
+    }, []);
+    const goNext = useCallback(() => {
+        setIndex((prev) => (prev + 1) % items.length);
+        resetZoom();
+    }, [items.length, resetZoom]);
+    const goPrev = useCallback(() => {
+        setIndex((prev) => (prev - 1 + items.length) % items.length);
+        resetZoom();
+    }, [items.length, resetZoom]);
+    const zoomIn = useCallback(() => {
+        setZoom((prev) => Math.min(prev + ZOOM_STEP, MAX_ZOOM));
+    }, []);
+    const zoomOut = useCallback(() => {
+        setZoom((prev) => {
+            const next = Math.max(prev - ZOOM_STEP, MIN_ZOOM);
+            if (next <= MIN_ZOOM)
+                setOffset({ x: 0, y: 0 });
+            return next;
+        });
+    }, []);
+    // Keyboard navigation
+    useEffect(() => {
+        if (!isOpen)
+            return;
+        const handler = (e) => {
+            switch (e.key) {
+                case "Escape":
+                    onClose();
+                    break;
+                case "ArrowRight":
+                    goNext();
+                    break;
+                case "ArrowLeft":
+                    goPrev();
+                    break;
+                case "+":
+                case "=":
+                    zoomIn();
+                    break;
+                case "-":
+                    zoomOut();
+                    break;
+            }
+        };
+        window.addEventListener("keydown", handler);
+        return () => window.removeEventListener("keydown", handler);
+    }, [isOpen, onClose, goNext, goPrev, zoomIn, zoomOut]);
+    // Fullscreen API
+    const toggleFullscreen = useCallback(() => {
+        if (!document.fullscreenElement) {
+            containerRef.current?.requestFullscreen();
+        }
+        else {
+            document.exitFullscreen();
+        }
+    }, []);
+    useEffect(() => {
+        const handler = () => setIsFullscreen(!!document.fullscreenElement);
+        document.addEventListener("fullscreenchange", handler);
+        return () => document.removeEventListener("fullscreenchange", handler);
+    }, []);
+    // Lock body scroll when open
+    useEffect(() => {
+        if (isOpen) {
+            document.body.style.overflow = "hidden";
+        }
+        return () => {
+            document.body.style.overflow = "";
+        };
+    }, [isOpen]);
+    // Non-passive wheel zoom
+    useEffect(() => {
+        const el = imageAreaRef.current;
+        if (!el || !isOpen)
+            return;
+        const handler = (e) => {
+            e.preventDefault();
+            if (e.deltaY < 0) {
+                setZoom((prev) => Math.min(prev + ZOOM_STEP, MAX_ZOOM));
+            }
+            else {
+                setZoom((prev) => {
+                    const next = Math.max(prev - ZOOM_STEP, MIN_ZOOM);
+                    if (next <= MIN_ZOOM)
+                        setOffset({ x: 0, y: 0 });
+                    return next;
+                });
+            }
+        };
+        el.addEventListener("wheel", handler, { passive: false });
+        return () => el.removeEventListener("wheel", handler);
+    }, [isOpen]);
+    // Pan drag
+    const handleMouseDown = useCallback((e) => {
+        if (zoom <= 1)
+            return;
+        e.preventDefault();
+        setIsDragging(true);
+        setDragStart({ x: e.clientX - offset.x, y: e.clientY - offset.y });
+    }, [zoom, offset]);
+    const handleMouseMove = useCallback((e) => {
+        if (!isDragging)
+            return;
+        setOffset({ x: e.clientX - dragStart.x, y: e.clientY - dragStart.y });
+    }, [isDragging, dragStart]);
+    const handleMouseUp = useCallback(() => {
+        setIsDragging(false);
+    }, []);
+    // Touch: pinch-zoom + swipe navigation
+    const touchState = useRef({});
+    const handleTouchStart = useCallback((e) => {
+        if (e.touches.length === 2) {
+            const dx = e.touches[0].clientX - e.touches[1].clientX;
+            const dy = e.touches[0].clientY - e.touches[1].clientY;
+            touchState.current = {
+                startDist: Math.hypot(dx, dy),
+                startZoom: zoom,
+                startOffset: { x: offset.x, y: offset.y },
+            };
+        }
+        else if (e.touches.length === 1) {
+            touchState.current = {
+                touchStart: { x: e.touches[0].clientX, y: e.touches[0].clientY },
+                startOffset: { x: offset.x, y: offset.y },
+            };
+        }
+    }, [zoom, offset]);
+    const handleTouchMove = useCallback((e) => {
+        if (e.touches.length === 2 &&
+            touchState.current.startDist !== undefined &&
+            touchState.current.startZoom !== undefined) {
+            const dx = e.touches[0].clientX - e.touches[1].clientX;
+            const dy = e.touches[0].clientY - e.touches[1].clientY;
+            const dist = Math.hypot(dx, dy);
+            const newZoom = Math.max(MIN_ZOOM, Math.min(MAX_ZOOM, touchState.current.startZoom *
+                (dist / touchState.current.startDist)));
+            setZoom(newZoom);
+        }
+        else if (e.touches.length === 1 &&
+            zoom > 1 &&
+            touchState.current.touchStart &&
+            touchState.current.startOffset) {
+            const dx = e.touches[0].clientX - touchState.current.touchStart.x;
+            const dy = e.touches[0].clientY - touchState.current.touchStart.y;
+            setOffset({
+                x: touchState.current.startOffset.x + dx,
+                y: touchState.current.startOffset.y + dy,
+            });
+        }
+    }, [zoom]);
+    const handleTouchEnd = useCallback((e) => {
+        if (e.changedTouches.length === 1 &&
+            zoom <= 1 &&
+            touchState.current.touchStart) {
+            const dx = e.changedTouches[0].clientX - touchState.current.touchStart.x;
+            const dy = Math.abs(e.changedTouches[0].clientY - touchState.current.touchStart.y);
+            if (Math.abs(dx) > 50 && dy < 80) {
+                if (dx < 0)
+                    goNext();
+                else
+                    goPrev();
+            }
+        }
+        touchState.current = {};
+    }, [zoom, goNext, goPrev]);
+    // An interrupted gesture (OS/browser takeover) never fires touchend —
+    // without this, stale touchState.current values corrupt the math for the
+    // next unrelated pinch/swipe gesture.
+    const handleTouchCancel = useCallback(() => {
+        touchState.current = {};
+    }, []);
+    if (!isOpen || items.length === 0)
+        return null;
+    const current = items[index];
+    return (_jsxs(Div, { layout: "flex", ref: containerRef, className: "fixed inset-0 z-[var(--appkit-z-tooltip)] bg-black/95 flex-col", role: "dialog", "aria-modal": "true", "aria-label": L.lightboxTitle, children: [_jsx(Div, { ref: imageAreaRef, className: "flex-1 relative overflow-hidden select-none", onMouseDown: handleMouseDown, onMouseMove: handleMouseMove, onMouseUp: handleMouseUp, onMouseLeave: handleMouseUp, onTouchStart: handleTouchStart, onTouchMove: handleTouchMove, onTouchEnd: handleTouchEnd, onTouchCancel: handleTouchCancel, style: {
+                    cursor: zoom > 1 ? (isDragging ? "grabbing" : "grab") : "default",
+                    touchAction: "none",
+                }, onClick: (e) => {
+                    if (e.target === e.currentTarget)
+                        onClose();
+                }, children: _jsx(Div, { className: "absolute inset-0", style: {
+                        transform: `translate(${offset.x}px, ${offset.y}px) scale(${zoom})`,
+                        transformOrigin: "center center",
+                        transition: isDragging ? "none" : "transform 0.2s ease",
+                        pointerEvents: "none",
+                    }, children: _jsx(MediaImage, { src: current.src, alt: current.alt, size: "hero", objectFit: "contain" }) }) }), _jsx(LightboxControlsBar, { items: items, index: index, zoom: zoom, isFullscreen: isFullscreen, L: L, goPrev: goPrev, goNext: goNext, zoomIn: zoomIn, zoomOut: zoomOut, resetZoom: resetZoom, toggleFullscreen: toggleFullscreen, onClose: onClose }), items.length > 1 && (_jsx(LightboxThumbnailStrip, { items: items, index: index, onSelect: setIndex, resetZoom: resetZoom, L: L }))] }));
+}
+export default MediaLightbox;

package/dist/ui/components/MediaVideo.js

@@ -0,0 +1,141 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { useRef, useEffect } from "react";
+import { Div } from "./Div.js";
+import { Row } from "./Layout.js";
+import { Span } from "./Typography.js";
+import { resolveMediaUrl, resolveVideoUrl, getYouTubeVideoId } from "../../utils/media-url.js";
+import { useSiteSettings } from "../../core/hooks/useSiteSettings.js";
+import { getBrandDomain } from "../../core/brand-resolver.js";
+export function MediaVideo({ src, thumbnailUrl, alt = "Video", controls = true, autoPlayMuted = false, loop = false, trimStart, trimEnd, objectFit = "cover", watermark, }) {
+    const videoRef = useRef(null);
+    const fitClass = objectFit === "contain" ? "object-contain" : "object-cover";
+    // Video src must NOT fall through to /api/media/ext (image-only, 400s on
+    // video/mp4). The poster is an image and stays on the normal image path.
+    const resolvedSrc = resolveVideoUrl(src);
+    const resolvedPoster = resolveMediaUrl(thumbnailUrl);
+    const youtubeId = getYouTubeVideoId(src);
+    // Apply trimStart on load
+    useEffect(() => {
+        const el = videoRef.current;
+        if (!el || trimStart === undefined)
+            return;
+        const onLoaded = () => {
+            el.currentTime = trimStart;
+        };
+        el.addEventListener("loadedmetadata", onLoaded);
+        return () => el.removeEventListener("loadedmetadata", onLoaded);
+    }, [trimStart]);
+    // Enforce trimEnd
+    useEffect(() => {
+        const el = videoRef.current;
+        if (!el || trimEnd === undefined)
+            return;
+        const onTimeUpdate = () => {
+            if (el.currentTime >= trimEnd) {
+                el.pause();
+                el.currentTime = trimStart ?? 0;
+            }
+        };
+        el.addEventListener("timeupdate", onTimeUpdate);
+        return () => el.removeEventListener("timeupdate", onTimeUpdate);
+    }, [trimEnd, trimStart]);
+    // Watermark precedence: explicit prop > runtime site-settings. `null` opts out.
+    const { data: siteSettings } = useSiteSettings();
+    const effectiveWatermark = watermark === null
+        ? null
+        : (watermark ?? siteSettings?.effectiveWatermark ?? siteSettings?.watermark ?? null);
+    if (!resolvedSrc) {
+        return (_jsx(Row
+        // audit-color-pair-function-ok: deliberate faded placeholder-icon shade, not a readability regression
+        , { 
+            // audit-color-pair-function-ok: deliberate faded placeholder-icon shade, not a readability regression
+            className: "absolute inset-0 text-zinc-400 text-[length:var(--appkit-text-4xl)]", surface: "subtle", align: "center", justify: "center", role: "img", "aria-label": alt, children: _jsx(Span, { "aria-hidden": "true", children: "\uD83C\uDFAC" }) }));
+    }
+    // A YouTube watch/share URL (MediaUploadField's "YouTube" tab writes one)
+    // is never a raw playable file — <video src> fails with "no supported
+    // format" for it. Render the iframe embed instead of the native player.
+    if (youtubeId) {
+        const embedParams = new URLSearchParams({ playsinline: "1", rel: "0" });
+        if (autoPlayMuted) {
+            embedParams.set("autoplay", "1");
+            embedParams.set("mute", "1");
+        }
+        if (loop) {
+            embedParams.set("loop", "1");
+            embedParams.set("playlist", youtubeId);
+        }
+        return (_jsx("iframe", { src: `https://www.youtube-nocookie.com/embed/${youtubeId}?${embedParams.toString()}`, title: alt, allow: "accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share", allowFullScreen: true, className: "absolute inset-0 w-full h-full border-0" }));
+    }
+    return (_jsxs(_Fragment, { children: [_jsx("video", { ref: videoRef, src: resolvedSrc, poster: resolvedPoster, controls: controls, autoPlay: autoPlayMuted, muted: autoPlayMuted, loop: loop, playsInline: true, "aria-label": alt, className: `absolute inset-0 w-full h-full ${fitClass}` }), effectiveWatermark ? _jsx(MediaVideoWatermarkLayer, { config: effectiveWatermark }) : null] }));
+}
+/**
+ * Mirrors the server-side Sharp pipeline's 5 anchor presets + `"custom"`
+ * %-offset-from-center (`resolveCompositePlacement` in
+ * `src/app/api/media/_watermark.ts`) as CSS insets, so a video's live
+ * overlay and its poster-frame-as-image watermark land in the same spot.
+ * Default `"center"`, 0/0 offset — matches the server-side default too.
+ */
+function resolveWatermarkPlacementStyle(config) {
+    const position = config.position ?? "center";
+    const inset = "2%";
+    switch (position) {
+        case "top-left":
+            return { top: inset, left: inset };
+        case "top-right":
+            return { top: inset, right: inset };
+        case "bottom-left":
+            return { bottom: inset, left: inset };
+        case "bottom-right":
+            return { bottom: inset, right: inset };
+        case "custom": {
+            const offsetX = Math.max(-45, Math.min(45, config.offsetX ?? 0));
+            const offsetY = Math.max(-45, Math.min(45, config.offsetY ?? 0));
+            return {
+                top: `calc(50% + ${offsetY}%)`,
+                left: `calc(50% + ${offsetX}%)`,
+                transform: "translate(-50%, -50%)",
+            };
+        }
+        case "center":
+        default:
+            return { top: "50%", left: "50%", transform: "translate(-50%, -50%)" };
+    }
+}
+/**
+ * Visual watermark overlay rendered on top of the playing `<video>`. Native
+ * video controls render in a higher layer (the browser shadow DOM), so this
+ * overlay sits below the controls but on top of the frames — visible enough
+ * to assert provenance, transparent enough not to obscure content.
+ *
+ * `pointer-events-none` lets clicks pass through to the underlying video for
+ * play/pause toggling.
+ */
+function MediaVideoWatermarkLayer({ config }) {
+    // Fallbacks match the server-side Sharp pipeline's DEFAULT_SIZE/DEFAULT_OPACITY
+    // (resolve-effective-watermark.ts) — these only kick in if no config is passed
+    // at all; in practice callers read siteSettings.effectiveWatermark, which
+    // always carries the real size/opacity.
+    const widthPct = Math.max(0, Math.min(100, config.size ?? 10));
+    const opacity = Math.max(0, Math.min(100, config.opacity ?? 10)) / 100;
+    if (widthPct === 0 || opacity === 0)
+        return null;
+    // Width is a percentage of the container so the watermark scales with the
+    // video, just like the server-side Sharp pipeline scales images — capped at
+    // an absolute max so a large player (hero banner, carousel) doesn't render
+    // an oversized mark just because the percentage of a big box is a big
+    // number. Mirrors MAX_WATERMARK_PX in src/app/api/media/_watermark.ts.
+    const containerStyle = {
+        position: "absolute",
+        width: `${widthPct}%`,
+        maxWidth: "180px",
+        pointerEvents: "none",
+        opacity,
+        ...resolveWatermarkPlacementStyle(config),
+    };
+    if (config.type === "image" && config.imageUrl) {
+        return (_jsx(Div, { className: "z-10", style: containerStyle, "aria-hidden": "true", children: _jsx("img", { src: resolveMediaUrl(config.imageUrl), alt: "", className: "block w-full h-auto" }) }));
+    }
+    return (_jsx(Div, { className: "z-10", style: containerStyle, "aria-hidden": "true", children: _jsx(Span, { className: "block text-white drop-shadow-[0_1px_2px_rgba(0,0,0,0.7)]", style: { fontSize: "0.8em", fontWeight: 700, textAlign: "right" }, children: config.text ?? getBrandDomain() }) }));
+}
+export default MediaVideo;

package/dist/ui/components/Modal.d.ts

@@ -10,7 +10,7 @@ export interface ModalProps {
     actions?: React.ReactNode;
     className?: string;
 }
-export declare function Modal({ isOpen, open, onClose, title, children, size, showCloseButton, actions, className, }: ModalProps): React.ReactPortal | null;
+export declare function Modal({ isOpen, open, onClose, title, children, size, showCloseButton, actions, className, }: ModalProps): React.JSX.Element | null;
 /**
  * A dialog's action row.
  *