@devultur/convex 1.4.3 → 1.5.0

package/dist/react.js

@@ -26,7 +26,7 @@ import {
 } from "./chunk-YYOZ3PDH.js";
 
 // src/react.tsx
-import React22 from "react";
+import React24 from "react";
 import {
   buildMediaUrl as buildMediaUrl2,
   CaptionLocaleLabel,
@@ -36,12 +36,12 @@ import {
   mediaUrl as mediaUrl4,
   visibilityFromKey
 } from "@devultur/core";
-import {
-  UploadHttpError,
-  uploadFileWithProgress
-} from "@devultur/react";
+import { UploadHttpError, uploadFileWithProgress } from "@devultur/react";
 import { useAction as useAction2, useConvex, useMutation, useQuery } from "convex/react";
 
+// src/devultur-context.ts
+import React from "react";
+
 // src/capability-error.ts
 var DevulturCapabilityError = class extends Error {
   code = "capability_unavailable";
@@ -55,6 +55,24 @@ var DevulturCapabilityError = class extends Error {
   }
 };
 
+// src/devultur-context.ts
+var DevulturContext = /* @__PURE__ */ React.createContext(null);
+var DevulturApiContext = /* @__PURE__ */ React.createContext(null);
+function useDevultur() {
+  const context = React.use(DevulturContext);
+  if (!context) throw new Error("useDevultur must be used within <DevulturProvider> or <DevulturViewerProvider>");
+  return context;
+}
+function useDevulturOptional() {
+  return React.use(DevulturContext);
+}
+function useDevulturApi() {
+  const api = React.use(DevulturApiContext);
+  if (api) return api;
+  if (React.use(DevulturContext)) throw new DevulturCapabilityError("api");
+  throw new Error("useDevulturApi must be used within <DevulturProvider>");
+}
+
 // src/media-fetch.ts
 import { SESSION_HEADER } from "@devultur/core";
 
@@ -157,17 +175,16 @@ async function readCapped(body, maxBytes) {
 }
 
 // src/media-session.ts
-import React2 from "react";
+import React3 from "react";
 import {
   buildMediaUrl,
   mediaCaptionPath,
   mediaUrl,
   SESSION_HEADER as SESSION_HEADER2
 } from "@devultur/core";
-import { useAction } from "convex/react";
 
 // src/viewer-token.ts
-import React from "react";
+import React2 from "react";
 import { DEFAULT_TOKEN_EXPIRY_SECONDS } from "@devultur/core";
 import { convexToJson } from "convex/values";
 var REFRESH_BUFFER_MS = 5 * 60 * 1e3;
@@ -193,30 +210,34 @@ function sortKeys(json) {
 function tokenArgsKey(tokenArgs) {
   return JSON.stringify(sortKeys(convexToJson(tokenArgs ?? {})));
 }
-function useViewerToken({ issueViewerToken, sessionSecret, tokenArgs }) {
+function useViewerToken({ issueViewerToken, sessionSecret, tokenArgs, isLazy = false }) {
   const argsKey = tokenArgsKey(tokenArgs);
-  const stableArgs = React.useMemo(() => tokenArgs ?? {}, [argsKey]);
-  const [issued, setIssued] = React.useState(null);
-  const [attempt, setAttempt] = React.useState(null);
+  const stableArgs = React2.useMemo(() => tokenArgs ?? {}, [argsKey]);
+  const [issued, setIssued] = React2.useState(null);
+  const [attempt, setAttempt] = React2.useState(null);
+  const [isRequested, setIsRequested] = React2.useState(!isLazy);
   const token = issued?.argsKey === argsKey ? issued.token : null;
   const currentAttempt = attempt?.argsKey === argsKey ? attempt : null;
-  const currentArgsKeyRef = React.useRef(argsKey);
-  const refreshTimerRef = React.useRef(null);
-  const inFlightRef = React.useRef(null);
-  React.useEffect(() => {
+  const currentArgsKeyRef = React2.useRef(argsKey);
+  const refreshTimerRef = React2.useRef(null);
+  const inFlightRef = React2.useRef(null);
+  const isMountedRef = React2.useRef(true);
+  React2.useEffect(() => {
     currentArgsKeyRef.current = argsKey;
   }, [argsKey]);
-  React.useEffect(() => {
+  React2.useEffect(() => {
+    isMountedRef.current = true;
     return () => {
+      isMountedRef.current = false;
       if (refreshTimerRef.current) clearTimeout(refreshTimerRef.current);
     };
   }, []);
-  const request = React.useCallback(async () => {
+  const request = React2.useCallback(async () => {
     const renew = () => {
       request().catch((error) => console.warn("Devultur: could not renew the viewer token", error));
     };
     const result = await issueViewerToken({ ...stableArgs, sessionSecret });
-    if (currentArgsKeyRef.current !== argsKey) return null;
+    if (!isMountedRef.current || currentArgsKeyRef.current !== argsKey) return null;
     const { tokenValue, ttlMs } = extractTokenResult(result);
     setIssued({ token: tokenValue, argsKey });
     setAttempt(null);
@@ -224,7 +245,7 @@ function useViewerToken({ issueViewerToken, sessionSecret, tokenArgs }) {
     refreshTimerRef.current = setTimeout(renew, Math.max(ttlMs - REFRESH_BUFFER_MS, MIN_REFRESH_MS));
     return tokenValue;
   }, [issueViewerToken, stableArgs, argsKey, sessionSecret]);
-  const issueOnce = React.useCallback(() => {
+  const issueOnce = React2.useCallback(() => {
     const inFlight = inFlightRef.current;
     if (inFlight?.argsKey === argsKey) return inFlight.promise;
     setAttempt({ argsKey, status: "loading" });
@@ -240,50 +261,62 @@ function useViewerToken({ issueViewerToken, sessionSecret, tokenArgs }) {
     return promise;
   }, [request, argsKey]);
   const hasAttempt = currentAttempt !== null;
-  React.useEffect(() => {
-    if (token || hasAttempt) return;
+  React2.useEffect(() => {
+    if (!isRequested || token || hasAttempt) return;
     issueOnce().catch(() => {
     });
-  }, [token, hasAttempt, issueOnce]);
-  const reissueToken = React.useCallback(
+  }, [isRequested, token, hasAttempt, issueOnce]);
+  const requestToken = React2.useCallback(() => setIsRequested(true), []);
+  const reissueToken = React2.useCallback(
     () => issueOnce().catch(() => {
       setIssued((current) => current?.argsKey === argsKey ? null : current);
       return null;
     }),
     [issueOnce, argsKey]
   );
-  const retryToken = React.useCallback(() => issueOnce().catch(() => null), [issueOnce]);
+  const retryToken = React2.useCallback(() => {
+    setIsRequested(true);
+    return issueOnce().catch(() => null);
+  }, [issueOnce]);
   const tokenStatus = token ? "ready" : currentAttempt?.status ?? "idle";
   const tokenError = !token && currentAttempt?.status === "error" ? currentAttempt.error : null;
-  return { token, tokenStatus, tokenError, reissueToken, retryToken };
+  return { token, tokenStatus, tokenError, reissueToken, retryToken, requestToken };
 }
 
 // src/media-session.ts
-function useMediaSession({ issueViewerToken, tokenArgs, baseUrl }) {
-  const [sessionSecret] = React2.useState(() => typeof crypto !== "undefined" ? crypto.randomUUID() : "");
-  const issueViewerTokenAction = useAction(issueViewerToken);
-  const { token, tokenStatus, tokenError, reissueToken, retryToken } = useViewerToken({
-    issueViewerToken: issueViewerTokenAction,
+function useMediaSession({ issueViewerToken, tokenArgs, baseUrl, isLazy }) {
+  const [sessionSecret] = React3.useState(() => typeof crypto !== "undefined" ? crypto.randomUUID() : "");
+  const { token, tokenStatus, tokenError, reissueToken, retryToken, requestToken } = useViewerToken({
+    issueViewerToken,
     sessionSecret,
-    tokenArgs
+    tokenArgs,
+    isLazy
   });
-  const url = React2.useCallback(
+  const hasRequestedRef = React3.useRef(!isLazy);
+  const requestTokenAfterRender = React3.useCallback(() => {
+    if (hasRequestedRef.current) return;
+    hasRequestedRef.current = true;
+    queueMicrotask(requestToken);
+  }, [requestToken]);
+  const url = React3.useCallback(
     (media, options) => {
       if (!baseUrl) throw new Error("Devultur `url()` requires `baseUrl` on <DevulturProvider>");
+      if (media.visibility === "private" && !token) requestTokenAfterRender();
       return mediaUrl(baseUrl, media, { ...options, token: token ?? void 0 });
     },
-    [baseUrl, token]
+    [baseUrl, token, requestTokenAfterRender]
   );
-  const getCaptionsText = React2.useCallback(
+  const getCaptionsText = React3.useCallback(
     async (media, locale) => {
       if (!baseUrl) throw new Error("Devultur `getCaptionsText()` requires `baseUrl` on <DevulturProvider>");
       const path = mediaCaptionPath(media, locale);
       if (!path) throw new Error("getCaptionsText: the reference is not a video");
       const isPrivate = media.visibility === "private";
-      const fetchWith = (viewerToken) => fetch(buildMediaUrl(baseUrl, path, { token: viewerToken }), {
+      const fetchWith = (viewerToken2) => fetch(buildMediaUrl(baseUrl, path, { token: viewerToken2 }), {
         headers: sessionSecret ? { [SESSION_HEADER2]: sessionSecret } : void 0
       });
-      let response = await fetchWith(isPrivate ? token ?? void 0 : void 0);
+      const viewerToken = isPrivate ? token ?? await retryToken() : null;
+      let response = await fetchWith(viewerToken ?? void 0);
       if (isPrivate && response.status === 401 && await isSessionMismatch(response)) {
         const fresh = await reissueToken();
         if (fresh) response = await fetchWith(fresh);
@@ -291,23 +324,42 @@ function useMediaSession({ issueViewerToken, tokenArgs, baseUrl }) {
       if (!response.ok) throw new Error(`Captions fetch failed: ${response.status}`);
       return response.text();
     },
-    [baseUrl, token, reissueToken, sessionSecret]
+    [baseUrl, token, reissueToken, retryToken, sessionSecret]
   );
-  return React2.useMemo(
+  return React3.useMemo(
     () => ({
       token,
       tokenStatus,
       tokenError,
       retryToken,
+      requestToken,
       baseUrl: baseUrl ?? null,
       sessionSecret,
       url,
       getCaptionsText,
       reissueToken
     }),
-    [token, tokenStatus, tokenError, retryToken, baseUrl, sessionSecret, url, getCaptionsText, reissueToken]
+    [
+      token,
+      tokenStatus,
+      tokenError,
+      retryToken,
+      requestToken,
+      baseUrl,
+      sessionSecret,
+      url,
+      getCaptionsText,
+      reissueToken
+    ]
   );
 }
+function useRequestTokenWhen(session, isNeeded) {
+  const { requestToken, token } = session;
+  const hasToken = token !== null;
+  React3.useEffect(() => {
+    if (isNeeded && !hasToken) requestToken();
+  }, [isNeeded, hasToken, requestToken]);
+}
 
 // src/media-upload-derive.ts
 function deriveUploadState(local, videoState, retry) {
@@ -352,7 +404,7 @@ function deriveUploadState(local, videoState, retry) {
 }
 
 // src/crop-upload.tsx
-import React3 from "react";
+import React4 from "react";
 import { ImageCropper } from "@devultur/react";
 import { jsx, jsxs } from "react/jsx-runtime";
 var DEFAULT_LABELS = {
@@ -376,18 +428,18 @@ function CropUpload({
   children
 }) {
   const text = { ...DEFAULT_LABELS, ...labels };
-  const [pendingFile, setPendingFile] = React3.useState(null);
-  const inputRef = React3.useRef(null);
+  const [pendingFile, setPendingFile] = React4.useState(null);
+  const inputRef = React4.useRef(null);
   const { upload, state, cancel, reset } = useMediaUpload({ visibility, replaces, onComplete });
-  const pickFile = React3.useCallback(() => inputRef.current?.click(), []);
-  const handleCrop = React3.useCallback(
+  const pickFile = React4.useCallback(() => inputRef.current?.click(), []);
+  const handleCrop = React4.useCallback(
     (baked) => {
       setPendingFile(null);
       upload(baked);
     },
     [upload]
   );
-  const resetAll = React3.useCallback(() => {
+  const resetAll = React4.useCallback(() => {
     setPendingFile(null);
     reset();
   }, [reset]);
@@ -440,7 +492,7 @@ function CropUpload({
 }
 
 // src/document-renderers.tsx
-import React4 from "react";
+import React5 from "react";
 
 // src/attachment-icons.tsx
 import { jsx as jsx2 } from "react/jsx-runtime";
@@ -495,7 +547,7 @@ function AttachmentCard({
   labels,
   ...articleProps
 }) {
-  const headingId = React4.useId();
+  const headingId = React5.useId();
   if (!media) return null;
   const text = mergeAttachmentLabels(labels);
   const kind = attachmentKindOf(media, contentType);
@@ -513,7 +565,7 @@ function AttachmentCard({
 }
 
 // src/image.tsx
-import React5 from "react";
+import React6 from "react";
 import { mediaUrl as mediaUrl2 } from "@devultur/core";
 
 // src/responsive-image.ts
@@ -607,7 +659,7 @@ function Image({
   }
   if (!src) return /* @__PURE__ */ jsx4(Fragment, { children: fallback });
   if (render) {
-    return React5.cloneElement(render, {
+    return React6.cloneElement(render, {
       style: { ...render.props.style, backgroundImage: `url("${src}")` }
     });
   }
@@ -627,26 +679,28 @@ function Image({
   );
 }
 function usePrivateImage(media, transforms, onLoadError) {
-  const { token, tokenStatus, tokenError, baseUrl, reissueToken, sessionSecret } = useDevultur();
-  const [isFailed, setIsFailed] = React5.useState(false);
-  const [blobSrc, setBlobSrc] = React5.useState(null);
-  const sessionRef = React5.useRef({ token, reissueToken, onLoadError });
-  React5.useEffect(() => {
+  const devultur = useDevultur();
+  const { token, tokenStatus, tokenError, baseUrl, reissueToken, sessionSecret } = devultur;
+  const [isFailed, setIsFailed] = React6.useState(false);
+  const [blobSrc, setBlobSrc] = React6.useState(null);
+  const sessionRef = React6.useRef({ token, reissueToken, onLoadError });
+  React6.useEffect(() => {
     sessionRef.current = { token, reissueToken, onLoadError };
   });
   const isPrivate = media?.visibility === "private";
+  useRequestTokenWhen(devultur, isPrivate);
   const hasToken = token !== null;
   const isTokenUnavailable = isPrivate && tokenStatus === "error";
   const { width, height, fit, format, quality } = transforms;
-  React5.useEffect(() => {
+  React6.useEffect(() => {
     setIsFailed(false);
     setBlobSrc(null);
   }, [media]);
-  React5.useEffect(() => {
+  React6.useEffect(() => {
     if (!isTokenUnavailable || !media) return;
     sessionRef.current.onLoadError?.(tokenUnavailableError(tokenError));
   }, [isTokenUnavailable, media, tokenError]);
-  React5.useEffect(() => {
+  React6.useEffect(() => {
     if (!isPrivate || isFailed || !media || !hasToken) return;
     let cancelled = false;
     let objectUrl = null;
@@ -685,21 +739,21 @@ function usePrivateImage(media, transforms, onLoadError) {
       if (objectUrl) URL.revokeObjectURL(objectUrl);
     };
   }, [isPrivate, isFailed, media, hasToken, baseUrl, sessionSecret, width, height, fit, format, quality]);
-  const handleError = React5.useCallback(() => setIsFailed(true), []);
+  const handleError = React6.useCallback(() => setIsFailed(true), []);
   return { blobSrc, isFailed: isFailed || isTokenUnavailable, handleError };
 }
 
 // src/media-library.tsx
-import React14 from "react";
+import React15 from "react";
 
 // src/media-library-item.tsx
-import React11 from "react";
+import React12 from "react";
 
 // src/pdf-thumbnail.tsx
-import React10 from "react";
+import React11 from "react";
 
 // src/media-resource.ts
-import React6 from "react";
+import React7 from "react";
 import { mediaPath, mediaUrl as mediaUrl3 } from "@devultur/core";
 var IDLE = { value: null, contentType: null, isLoading: false, error: null };
 var LOADING = { value: null, contentType: null, isLoading: true, error: null };
@@ -707,19 +761,20 @@ function useMediaResource(media, options) {
   const devultur = useDevultur();
   const { isEnabled, maxBytes, contentType } = options;
   const isPrivate = media?.visibility === "private";
+  useRequestTokenWhen(devultur, isPrivate && isEnabled);
   const isReady = !isPrivate || devultur.token !== null;
   const isTokenUnavailable = isPrivate && devultur.tokenStatus === "error";
-  const tokenFailure = React6.useMemo(
+  const tokenFailure = React7.useMemo(
     () => isTokenUnavailable ? tokenUnavailableError(devultur.tokenError) : null,
     [isTokenUnavailable, devultur.tokenError]
   );
   const requestKey = media && isEnabled ? [devultur.baseUrl, media.visibility, mediaPath(media), contentType ?? "", maxBytes ?? ""].join("|") : null;
-  const [settled, setSettled] = React6.useState(null);
-  const inputsRef = React6.useRef({ media, devultur, options });
-  React6.useEffect(() => {
+  const [settled, setSettled] = React7.useState(null);
+  const inputsRef = React7.useRef({ media, devultur, options });
+  React7.useEffect(() => {
     inputsRef.current = { media, devultur, options };
   });
-  React6.useEffect(() => {
+  React7.useEffect(() => {
     if (!requestKey || !isReady) return;
     const { media: target, devultur: context, options: current } = inputsRef.current;
     if (!target || !context.baseUrl) return;
@@ -757,7 +812,7 @@ function useMediaResource(media, options) {
 }
 
 // src/pdf-context.tsx
-import React7 from "react";
+import React8 from "react";
 
 // src/preview-labels.ts
 var ERROR_TEXT = {
@@ -793,14 +848,14 @@ function mergePreviewLabels(...sources) {
 
 // src/pdf-context.tsx
 import { jsx as jsx5 } from "react/jsx-runtime";
-var PdfPreviewContext = /* @__PURE__ */ React7.createContext({});
+var PdfPreviewContext = /* @__PURE__ */ React8.createContext({});
 function PdfPreviewProvider({
   pdfjs,
   workerSrc,
   labels,
   children
 }) {
-  const config = React7.useMemo(() => ({ pdfjs, workerSrc, labels }), [pdfjs, workerSrc, labels]);
+  const config = React8.useMemo(() => ({ pdfjs, workerSrc, labels }), [pdfjs, workerSrc, labels]);
   return /* @__PURE__ */ jsx5(PdfPreviewContext.Provider, { value: config, children });
 }
 var loadedModules = /* @__PURE__ */ new WeakMap();
@@ -812,9 +867,9 @@ function loadOnce(loader) {
   return loading;
 }
 function usePdfjs(workerSrcOverride) {
-  const { pdfjs: loader, workerSrc } = React7.useContext(PdfPreviewContext);
-  const [loaded, setLoaded] = React7.useState(null);
-  React7.useEffect(() => {
+  const { pdfjs: loader, workerSrc } = React8.useContext(PdfPreviewContext);
+  const [loaded, setLoaded] = React8.useState(null);
+  React8.useEffect(() => {
     if (!loader) return;
     let isCurrent = true;
     loadOnce(loader).then((pdfjs) => {
@@ -830,8 +885,8 @@ function usePdfjs(workerSrcOverride) {
   return { status: "ready", pdfjs: loaded.pdfjs, workerSrc: workerSrcOverride ?? workerSrc };
 }
 function usePdfPageCounter() {
-  const { pdfjs: loader, workerSrc } = React7.useContext(PdfPreviewContext);
-  return React7.useMemo(() => {
+  const { pdfjs: loader, workerSrc } = React8.useContext(PdfPreviewContext);
+  return React8.useMemo(() => {
     if (!loader) return null;
     return async (file) => {
       const pdfjs = await loadOnce(loader);
@@ -841,15 +896,15 @@ function usePdfPageCounter() {
   }, [loader, workerSrc]);
 }
 function usePreviewLabels(labels) {
-  const providerLabels = React7.useContext(PdfPreviewContext).labels;
+  const providerLabels = React8.useContext(PdfPreviewContext).labels;
   return mergePreviewLabels(providerLabels, labels);
 }
 
 // src/pdf-hooks.ts
-import React8 from "react";
+import React9 from "react";
 function useIsVisible(ref, rootMargin = "200px") {
-  const [isVisible, setIsVisible] = React8.useState(false);
-  React8.useEffect(() => {
+  const [isVisible, setIsVisible] = React9.useState(false);
+  React9.useEffect(() => {
     const element = ref.current;
     if (isVisible || !element) return;
     if (typeof IntersectionObserver === "undefined") {
@@ -870,12 +925,12 @@ function useIsVisible(ref, rootMargin = "200px") {
   return isVisible;
 }
 function usePdfDocument({ pdfjs, bytes, workerSrc }) {
-  const [state, setState] = React8.useState({
+  const [state, setState] = React9.useState({
     bytes: null,
     document: null,
     error: null
   });
-  React8.useEffect(() => {
+  React9.useEffect(() => {
     let isCurrent = true;
     const loadingTask = openPdf(pdfjs, bytes, workerSrc);
     loadingTask.promise.then((document2) => {
@@ -894,8 +949,8 @@ function usePdfDocument({ pdfjs, bytes, workerSrc }) {
 }
 function usePageRender(options) {
   const { document: document2, pageNumber, canvasRef, width, isEnabled, shouldExtractText = false } = options;
-  const [state, setState] = React8.useState({ isRendered: false, text: "" });
-  React8.useEffect(() => {
+  const [state, setState] = React9.useState({ isRendered: false, text: "" });
+  React9.useEffect(() => {
     const canvas = canvasRef.current;
     if (!document2 || !isEnabled || !canvas) return;
     let isCurrent = true;
@@ -925,7 +980,7 @@ function usePageRender(options) {
 }
 
 // src/pdf-preview.tsx
-import React9 from "react";
+import React10 from "react";
 import { Fragment as Fragment2, jsx as jsx6, jsxs as jsxs3 } from "react/jsx-runtime";
 var VISUALLY_HIDDEN = {
   position: "absolute",
@@ -971,9 +1026,9 @@ function PdfPreview(props) {
 function PdfCanvasDocument(props) {
   const { pdfjs, workerSrc, bytes, label, className, renderFallback, loading, labels, maxPages } = props;
   const { document: document2, error } = usePdfDocument({ pdfjs, bytes, workerSrc });
-  const containerRef = React9.useRef(null);
-  const [width, setWidth] = React9.useState(null);
-  React9.useLayoutEffect(() => {
+  const containerRef = React10.useRef(null);
+  const [width, setWidth] = React10.useState(null);
+  React10.useLayoutEffect(() => {
     if (document2) setWidth(containerRef.current?.clientWidth ?? 0);
   }, [document2]);
   if (error) return /* @__PURE__ */ jsx6(Fragment2, { children: renderFallback(renderFailedError(error)) });
@@ -1009,8 +1064,8 @@ function PdfCanvasDocument(props) {
   );
 }
 function PdfPageView({ document: document2, pageNumber, width, label }) {
-  const pageRef = React9.useRef(null);
-  const canvasRef = React9.useRef(null);
+  const pageRef = React10.useRef(null);
+  const canvasRef = React10.useRef(null);
   const isVisible = useIsVisible(pageRef);
   const { isRendered, text } = usePageRender({
     document: document2,
@@ -1027,8 +1082,8 @@ function PdfPageView({ document: document2, pageNumber, width, label }) {
   ] });
 }
 function PdfFrame({ bytes, label, className }) {
-  const [objectUrl, setObjectUrl] = React9.useState(null);
-  React9.useEffect(() => {
+  const [objectUrl, setObjectUrl] = React10.useState(null);
+  React10.useEffect(() => {
     const url = URL.createObjectURL(new Blob([bytes], { type: "application/pdf" }));
     setObjectUrl(url);
     return () => URL.revokeObjectURL(url);
@@ -1043,7 +1098,7 @@ var DEFAULT_THUMBNAIL_WIDTH = 96;
 var DEFAULT_THUMBNAIL_MAX_BYTES = 50 * 1024 * 1024;
 function PdfThumbnail(props) {
   const { media, contentType, width = DEFAULT_THUMBNAIL_WIDTH, fallback = null, loading = null } = props;
-  const containerRef = React10.useRef(null);
+  const containerRef = React11.useRef(null);
   const isVisible = useIsVisible(containerRef);
   const pdfjsState = usePdfjs(props.pdfWorkerSrc);
   const labels = usePreviewLabels(props.labels);
@@ -1076,7 +1131,7 @@ function PdfThumbnail(props) {
   return /* @__PURE__ */ jsx7("div", { ref: containerRef, className: props.className, style: { width }, children: content() });
 }
 function ThumbnailCanvas({ pdfjs, workerSrc, bytes, width, label, fallback, loading }) {
-  const canvasRef = React10.useRef(null);
+  const canvasRef = React11.useRef(null);
   const { document: document2, error } = usePdfDocument({ pdfjs, bytes, workerSrc });
   const { isRendered } = usePageRender({ document: document2, pageNumber: 1, canvasRef, width, isEnabled: true });
   if (error) return /* @__PURE__ */ jsx7(Fragment3, { children: fallback });
@@ -1144,7 +1199,7 @@ var ITEM_STYLE = {
 };
 function MediaLibraryItem(props) {
   const { ref, record, isSelected, isActive, tabIndex, classNames, renderItem, onChoose, onFocus } = props;
-  const media = React11.useMemo(() => mediaFromRecord(record), [record]);
+  const media = React12.useMemo(() => mediaFromRecord(record), [record]);
   const handleKeyDown = (event) => {
     if (event.key !== "Enter" && event.key !== " ") return;
     event.preventDefault();
@@ -1207,13 +1262,13 @@ function mergeMediaLibraryLabels(labels) {
 }
 
 // src/use-media-library.ts
-import React12 from "react";
+import React13 from "react";
 import { usePaginatedQuery } from "convex/react";
 var SEARCH_DEBOUNCE_MS = 250;
 var DEFAULT_PAGE_SIZE = 24;
 function useDebouncedSearch(value, delayMs) {
-  const [debounced, setDebounced] = React12.useState(value);
-  React12.useEffect(() => {
+  const [debounced, setDebounced] = React13.useState(value);
+  React13.useEffect(() => {
     if (value === "") {
       setDebounced("");
       return;
@@ -1238,7 +1293,7 @@ function useMediaLibrary(options = {}) {
   const args = isSearching ? { search, ...typeArg } : typeArg;
   const result = usePaginatedQuery(reference, args, { initialNumItems: pageSize });
   const resultLoadMore = result.loadMore;
-  const loadMore = React12.useCallback(
+  const loadMore = React13.useCallback(
     (numItems) => resultLoadMore(numItems ?? pageSize),
     [resultLoadMore, pageSize]
   );
@@ -1253,7 +1308,7 @@ function useMediaLibrary(options = {}) {
 }
 
 // src/use-roving-focus.ts
-import React13 from "react";
+import React14 from "react";
 function nextIndex(key, current, count, columns) {
   const last = count - 1;
   const clamp = (index) => Math.min(Math.max(index, 0), last);
@@ -1281,16 +1336,16 @@ function columnCount(items) {
   return Math.max(inFirstRow.length, 1);
 }
 function useRovingFocus(count) {
-  const [activeIndex, setActiveIndex] = React13.useState(0);
-  const itemsRef = React13.useRef([]);
+  const [activeIndex, setActiveIndex] = React14.useState(0);
+  const itemsRef = React14.useRef([]);
   const currentIndex = Math.min(activeIndex, Math.max(count - 1, 0));
-  const itemRef = React13.useCallback(
+  const itemRef = React14.useCallback(
     (index) => (element) => {
       itemsRef.current[index] = element;
     },
     []
   );
-  const handleKeyDown = React13.useCallback(
+  const handleKeyDown = React14.useCallback(
     (event) => {
       if (count === 0) return;
       const items = itemsRef.current.slice(0, count);
@@ -1322,16 +1377,16 @@ var LIST_STYLE = {
   padding: 0
 };
 function MediaLibrary(props) {
-  const labels = React14.useMemo(() => mergeMediaLibraryLabels(props.labels), [props.labels]);
+  const labels = React15.useMemo(() => mergeMediaLibraryLabels(props.labels), [props.labels]);
   const classNames = { ...props.classNames, root: props.className ?? props.classNames?.root };
-  const [search, setSearch] = React14.useState("");
-  const [chosenType, setChosenType] = React14.useState("");
-  const [selectedKey, setSelectedKey] = React14.useState(null);
+  const [search, setSearch] = React15.useState("");
+  const [chosenType, setChosenType] = React15.useState("");
+  const [selectedKey, setSelectedKey] = React15.useState(null);
   const type = props.type ?? (chosenType === "" ? void 0 : chosenType);
   const { onSelect } = props;
   const isSelectable = props.selectable ?? props.selectedKeys !== void 0;
   const selectedKeys = props.selectedKeys ?? (selectedKey === null ? [] : [selectedKey]);
-  const handleChoose = React14.useCallback(
+  const handleChoose = React15.useCallback(
     (record) => {
       if (isSelectable) setSelectedKey(record.key);
       onSelect(record, mediaFromRecord(record));
@@ -1443,7 +1498,7 @@ function LibraryResults(props) {
     )
   ] });
 }
-var LibraryErrorBoundary = class extends React14.Component {
+var LibraryErrorBoundary = class extends React15.Component {
   state = { hasError: false, error: null };
   static getDerivedStateFromError(error) {
     return { hasError: true, error };
@@ -1485,7 +1540,7 @@ function useMediaObjectUrl(media, options) {
 }
 
 // src/media-picker.tsx
-import React21 from "react";
+import React22 from "react";
 
 // src/media-picker-accept.ts
 function matchesAccept(candidate, accept) {
@@ -1525,10 +1580,10 @@ function recordMatchesAccept(record, accept) {
 }
 
 // src/media-picker-context.ts
-import React15 from "react";
-var MediaPickerContext = /* @__PURE__ */ React15.createContext(null);
+import React16 from "react";
+var MediaPickerContext = /* @__PURE__ */ React16.createContext(null);
 function useMediaPicker() {
-  const picker = React15.use(MediaPickerContext);
+  const picker = React16.use(MediaPickerContext);
   if (!picker) throw new Error("useMediaPicker must be used within <MediaPicker>");
   return picker;
 }
@@ -1569,13 +1624,13 @@ function mergeMediaPickerLabels(labels) {
 }
 
 // src/media-picker-library.tsx
-import React16 from "react";
+import React17 from "react";
 import { jsx as jsx10 } from "react/jsx-runtime";
 function MediaPickerLibrary(props) {
   const picker = useMediaPicker();
   const { accept, toggle } = picker;
   const selectedKeys = picker.selected.map((media) => media.id);
-  const filter = React16.useMemo(
+  const filter = React17.useMemo(
     () => accept ? (record) => recordMatchesAccept(record, accept) : void 0,
     [accept]
   );
@@ -1596,13 +1651,13 @@ function MediaPickerLibrary(props) {
 }
 
 // src/media-picker-selection.tsx
-import React18 from "react";
+import React19 from "react";
 
 // src/preview.tsx
 import { mediaPath as mediaPath2 } from "@devultur/core";
 
 // src/video-preview.tsx
-import React17 from "react";
+import React18 from "react";
 import { VideoPlayer } from "@devultur/react";
 import { Fragment as Fragment6, jsx as jsx11 } from "react/jsx-runtime";
 var UNAUTHORIZED = 401;
@@ -1616,13 +1671,13 @@ function fetchErrorOf(error) {
   if (HLS_NETWORK_FAILURE.test(error.details)) return networkError(error);
   return renderFailedError(error);
 }
-function VideoPreview({ media, renderFallback, className }) {
-  const { tokenStatus, tokenError, reissueToken } = useDevultur();
+function VideoPreview({ media, renderFallback, loading, metrics, className }) {
+  const { token, tokenStatus, tokenError, reissueToken } = useDevultur();
   const videoProps = useVideoProps(media);
-  const [failure, setFailure] = React17.useState(null);
-  const hasReissuedRef = React17.useRef(false);
+  const [failure, setFailure] = React18.useState(null);
+  const hasReissuedRef = React18.useRef(false);
   const playerToken = videoProps?.token;
-  const handleError = React17.useCallback(
+  const handleError = React18.useCallback(
     (error) => {
       const isFirstMismatch = error.code === "session_mismatch" && !hasReissuedRef.current;
       if (isFirstMismatch) {
@@ -1635,18 +1690,18 @@ function VideoPreview({ media, renderFallback, className }) {
     [reissueToken, playerToken]
   );
   if (!videoProps) return null;
-  if (media.visibility === "private" && tokenStatus === "error") {
-    return /* @__PURE__ */ jsx11(Fragment6, { children: renderFallback(tokenUnavailableError(tokenError)) });
-  }
+  const isPrivate = media.visibility === "private";
+  if (isPrivate && tokenStatus === "error") return /* @__PURE__ */ jsx11(Fragment6, { children: renderFallback(tokenUnavailableError(tokenError)) });
+  if (isPrivate && !token) return /* @__PURE__ */ jsx11(Fragment6, { children: loading });
   if (failure && failure.token === playerToken) return /* @__PURE__ */ jsx11(Fragment6, { children: renderFallback(failure.error) });
-  return /* @__PURE__ */ jsx11(VideoPlayer, { ...videoProps, className, onError: handleError });
+  return /* @__PURE__ */ jsx11(VideoPlayer, { ...videoProps, className, metrics, onError: handleError });
 }
 
 // src/preview.tsx
 import { Fragment as Fragment7, jsx as jsx12 } from "react/jsx-runtime";
 var DEFAULT_MAX_TEXT_BYTES = 1024 * 1024;
 var DEFAULT_MAX_BYTES = 50 * 1024 * 1024;
-function Preview({ media, contentType, fallback, loading, labels, ...viewProps }) {
+function Preview({ media, contentType, fallback, loading, labels, metrics, ...viewProps }) {
   const text = usePreviewLabels(labels);
   if (!media) return null;
   const renderFallback = (error) => {
@@ -1655,12 +1710,15 @@ function Preview({ media, contentType, fallback, loading, labels, ...viewProps }
     if (fallback !== void 0) return fallback;
     return /* @__PURE__ */ jsx12(DefaultFallback, { media, error: fetchError, labels: text });
   };
+  const loadingNode = loading === void 0 ? /* @__PURE__ */ jsx12(LoadingStatus, { text: text.loading }) : loading;
   if (media.kind === "video") {
     return /* @__PURE__ */ jsx12(
       VideoPreview,
       {
         media,
         renderFallback,
+        loading: loadingNode,
+        metrics,
         className: viewProps.className
       },
       mediaPath2(media)
@@ -1669,7 +1727,6 @@ function Preview({ media, contentType, fallback, loading, labels, ...viewProps }
   const expectedType = expectedContentType(media, contentType);
   const kind = previewKindOf(expectedType);
   if (!expectedType || !kind) return /* @__PURE__ */ jsx12(Fragment7, { children: renderFallback(unsupportedType(expectedType)) });
-  const loadingNode = loading === void 0 ? /* @__PURE__ */ jsx12(LoadingStatus, { text: text.loading }) : loading;
   const props = { ...viewProps, media, expectedType, renderFallback, loading: loadingNode, labels: text };
   if (kind === "text") return /* @__PURE__ */ jsx12(TextPreview, { ...props });
   if (kind === "pdf") return /* @__PURE__ */ jsx12(PdfPreview, { ...props, maxBytes: props.maxBytes ?? DEFAULT_MAX_BYTES });
@@ -1732,8 +1789,8 @@ var THUMBNAIL_WIDTH2 = 96;
 function MediaPickerSelection({ renderItem, headingLevel = 3, className }) {
   const picker = useMediaPicker();
   const { labels, selected } = picker;
-  const headingId = React18.useId();
-  const [previewedId, setPreviewedId] = React18.useState(null);
+  const headingId = React19.useId();
+  const [previewedId, setPreviewedId] = React19.useState(null);
   const Heading = `h${headingLevel}`;
   const cardHeadingLevel = headingLevel + 1;
   const regionClass = className ? `devultur-media-picker__selection ${className}` : "devultur-media-picker__selection";
@@ -1799,12 +1856,12 @@ function SelectionActions() {
 }
 
 // src/media-picker-upload.tsx
-import React19 from "react";
+import React20 from "react";
 import { jsx as jsx14, jsxs as jsxs8 } from "react/jsx-runtime";
 function MediaPickerUpload({ className }) {
   const picker = useMediaPicker();
   const { labels, multiple } = picker;
-  const [isDragging, setIsDragging] = React19.useState(false);
+  const [isDragging, setIsDragging] = React20.useState(false);
   const handleDragOver = (event) => {
     event.preventDefault();
     setIsDragging(true);
@@ -1861,7 +1918,7 @@ function UploadRow({ upload }) {
 }
 
 // src/use-media-picker-uploads.ts
-import React20 from "react";
+import React21 from "react";
 var isAbortError = (error) => typeof error === "object" && error !== null && error.name === "AbortError";
 var isPdf = (file) => file.type === "application/pdf" || file.name.toLowerCase().endsWith(".pdf");
 var nextUploadId = 0;
@@ -1872,18 +1929,18 @@ async function pageCountOf(file, countPdfPages) {
 }
 function useMediaPickerUploads(options) {
   const { upload } = useDevultur();
-  const [uploads, setUploads] = React20.useState([]);
-  const controllers = React20.useRef(/* @__PURE__ */ new Map());
-  const optionsRef = React20.useRef(options);
+  const [uploads, setUploads] = React21.useState([]);
+  const controllers = React21.useRef(/* @__PURE__ */ new Map());
+  const optionsRef = React21.useRef(options);
   optionsRef.current = options;
-  const patch = React20.useCallback((id, changes) => {
+  const patch = React21.useCallback((id, changes) => {
     setUploads((current) => current.map((entry) => entry.id === id ? { ...entry, ...changes } : entry));
   }, []);
-  const drop = React20.useCallback((id) => {
+  const drop = React21.useCallback((id) => {
     controllers.current.delete(id);
     setUploads((current) => current.filter((entry) => entry.id !== id));
   }, []);
-  const run = React20.useCallback(
+  const run = React21.useCallback(
     async (id, file) => {
       const { labels, announce } = optionsRef.current;
       const controller = new AbortController();
@@ -1913,7 +1970,7 @@ function useMediaPickerUploads(options) {
     },
     [upload, patch, drop]
   );
-  const start = React20.useCallback(
+  const start = React21.useCallback(
     (files) => {
       const { accept, multiple, labels } = optionsRef.current;
       const chosen = multiple ? [...files] : [...files].slice(0, 1);
@@ -1935,8 +1992,8 @@ function useMediaPickerUploads(options) {
     },
     [run]
   );
-  const cancel = React20.useCallback((id) => controllers.current.get(id)?.abort(), []);
-  const retry = React20.useCallback(
+  const cancel = React21.useCallback((id) => controllers.current.get(id)?.abort(), []);
+  const retry = React21.useCallback(
     (id) => {
       const entry = uploads.find((candidate) => candidate.id === id);
       if (!entry?.canRetry) return;
@@ -1944,7 +2001,7 @@ function useMediaPickerUploads(options) {
     },
     [uploads, run]
   );
-  React20.useEffect(() => {
+  React21.useEffect(() => {
     const active = controllers.current;
     return () => {
       for (const controller of active.values()) controller.abort();
@@ -1971,22 +2028,22 @@ function emit(props, next) {
 var isSame = (a, b) => a.id === b.id;
 function MediaPickerRoot(props) {
   const isMultiple = props.multiple ?? false;
-  const labels = React21.useMemo(() => mergeMediaPickerLabels(props.labels), [props.labels]);
+  const labels = React22.useMemo(() => mergeMediaPickerLabels(props.labels), [props.labels]);
   const accept = uploadAcceptOf(props.accept, props.type);
   const libraryType = props.type ?? mediaTypeOfAccept(props.accept);
   const countPdfPages = usePdfPageCounter();
-  const [announcement, setAnnouncement] = React21.useState("");
-  const inputRef = React21.useRef(null);
-  const selectionRef = React21.useRef(null);
-  const [ownSelection, setOwnSelection] = React21.useState(EMPTY);
+  const [announcement, setAnnouncement] = React22.useState("");
+  const inputRef = React22.useRef(null);
+  const selectionRef = React22.useRef(null);
+  const [ownSelection, setOwnSelection] = React22.useState(EMPTY);
   const controlledSelection = selectionOf(props);
   const selected = controlledSelection ?? ownSelection;
-  const selectedRef = React21.useRef(selected);
+  const selectedRef = React22.useRef(selected);
   selectedRef.current = selected;
-  const propsRef = React21.useRef(props);
+  const propsRef = React22.useRef(props);
   propsRef.current = props;
   const isControlled = controlledSelection !== void 0;
-  const commit = React21.useCallback(
+  const commit = React22.useCallback(
     (next) => {
       selectedRef.current = next;
       if (!isControlled) setOwnSelection(next);
@@ -1994,15 +2051,15 @@ function MediaPickerRoot(props) {
     },
     [isControlled]
   );
-  const announce = React21.useCallback((message) => setAnnouncement(message), []);
-  const select = React21.useCallback(
+  const announce = React22.useCallback((message) => setAnnouncement(message), []);
+  const select = React22.useCallback(
     (media) => {
       const current = selectedRef.current.filter((item) => !isSame(item, media));
       commit(isMultiple ? [...current, media] : [media]);
     },
     [commit, isMultiple]
   );
-  const remove = React21.useCallback(
+  const remove = React22.useCallback(
     (media) => {
       commit(selectedRef.current.filter((item) => !isSame(item, media)));
       announce(labels.removed(mediaName(media)));
@@ -2010,7 +2067,7 @@ function MediaPickerRoot(props) {
     },
     [commit, announce, labels]
   );
-  const toggle = React21.useCallback(
+  const toggle = React22.useCallback(
     (media) => {
       const isSelected = selectedRef.current.some((item) => isSame(item, media));
       if (isMultiple && isSelected) {
@@ -2022,12 +2079,12 @@ function MediaPickerRoot(props) {
     },
     [isMultiple, remove, select, announce, labels]
   );
-  const clear = React21.useCallback(() => {
+  const clear = React22.useCallback(() => {
     commit([]);
     announce(labels.cleared);
     selectionRef.current?.focus();
   }, [commit, announce, labels]);
-  const handleUploaded = React21.useCallback(
+  const handleUploaded = React22.useCallback(
     (media) => {
       select(media);
       selectionRef.current?.focus();
@@ -2096,25 +2153,59 @@ var MediaPicker = /* @__PURE__ */ Object.assign(MediaPickerRoot, {
   Selection: MediaPickerSelection
 });
 
-// src/react.tsx
+// src/viewer-provider.tsx
+import React23 from "react";
+import { useAction } from "convex/react";
 import { jsx as jsx16 } from "react/jsx-runtime";
-var DevulturContext = /* @__PURE__ */ React22.createContext(null);
-var DevulturApiContext = /* @__PURE__ */ React22.createContext(null);
-var ProgressContext = /* @__PURE__ */ React22.createContext(null);
+var VIEWER_ACTIONS = {
+  uploadUrl: () => Promise.reject(new DevulturCapabilityError("uploadUrl")),
+  upload: () => Promise.reject(new DevulturCapabilityError("upload")),
+  deleteMedia: () => {
+    throw new DevulturCapabilityError("deleteMedia");
+  }
+};
+var NO_TOKEN_ACTION = () => Promise.reject(new Error("<DevulturViewerProvider> has no `issueViewerToken`: private media can't be shown"));
+function DevulturViewerProvider({ issueViewerToken, ...props }) {
+  if (!issueViewerToken) return /* @__PURE__ */ jsx16(ViewerSession, { ...props, issueViewerToken: NO_TOKEN_ACTION, lazyToken: true });
+  return /* @__PURE__ */ jsx16(ConvexViewerSession, { ...props, issueViewerToken });
+}
+function ConvexViewerSession({
+  issueViewerToken,
+  ...props
+}) {
+  const issueViewerTokenAction = useAction(issueViewerToken);
+  return /* @__PURE__ */ jsx16(ViewerSession, { issueViewerToken: issueViewerTokenAction, ...props });
+}
+function ViewerSession({
+  baseUrl,
+  issueViewerToken,
+  tokenArgs,
+  lazyToken = false,
+  children
+}) {
+  const session = useMediaSession({ issueViewerToken, tokenArgs, baseUrl, isLazy: lazyToken });
+  const devulturValue = React23.useMemo(() => ({ ...session, ...VIEWER_ACTIONS }), [session]);
+  return /* @__PURE__ */ jsx16(DevulturContext, { value: devulturValue, children });
+}
+
+// src/react.tsx
+import { jsx as jsx17 } from "react/jsx-runtime";
+var ProgressContext = /* @__PURE__ */ React24.createContext(null);
 function DevulturProvider({ api, baseUrl, tokenArgs, issueViewerToken, children }) {
-  const session = useMediaSession({ issueViewerToken: issueViewerToken ?? api.issueViewerToken, tokenArgs, baseUrl });
+  const issueViewerTokenAction = useAction2(issueViewerToken ?? api.issueViewerToken);
+  const session = useMediaSession({ issueViewerToken: issueViewerTokenAction, tokenArgs, baseUrl });
   const createUploadUrlAction = useAction2(api.createUploadUrl);
   const deleteMediaAction = useAction2(api.deleteMedia);
   const confirmUploadAction = useAction2(api.confirmUpload ?? api.createUploadUrl);
   const deleteVideoAction = useAction2(api.deleteVideo ?? api.deleteMedia);
-  const uploadUrl = React22.useCallback(
+  const uploadUrl = React24.useCallback(
     async (file) => {
       const result = await createUploadUrlAction({ filename: file.name, contentType: file.type });
       return { url: result.url, key: result.key };
     },
     [createUploadUrlAction]
   );
-  const upload = React22.useCallback(
+  const upload = React24.useCallback(
     async (file, options) => {
       const dimensions = await readImageDimensions(file);
       options?.signal?.throwIfAborted();
@@ -2140,7 +2231,7 @@ function DevulturProvider({ api, baseUrl, tokenArgs, issueViewerToken, children
     },
     [createUploadUrlAction, confirmUploadAction, api.confirmUpload]
   );
-  const deleteMedia = React22.useCallback(
+  const deleteMedia = React24.useCallback(
     (media) => {
       if (media.kind === "video" && api.deleteVideo) {
         deleteVideoAction({ videoId: media.id, visibility: media.visibility }).catch(console.error);
@@ -2150,13 +2241,13 @@ function DevulturProvider({ api, baseUrl, tokenArgs, issueViewerToken, children
     },
     [deleteMediaAction, deleteVideoAction, api.deleteVideo]
   );
-  const devulturValue = React22.useMemo(
+  const devulturValue = React24.useMemo(
     () => ({ ...session, uploadUrl, upload, deleteMedia }),
     [session, uploadUrl, upload, deleteMedia]
   );
-  let content = /* @__PURE__ */ jsx16(DevulturApiContext, { value: api, children: /* @__PURE__ */ jsx16(DevulturContext, { value: devulturValue, children }) });
+  let content = /* @__PURE__ */ jsx17(DevulturApiContext, { value: api, children: /* @__PURE__ */ jsx17(DevulturContext, { value: devulturValue, children }) });
   if (api.saveProgress && api.loadProgress && api.markComplete && api.resetProgress) {
-    content = /* @__PURE__ */ jsx16(
+    content = /* @__PURE__ */ jsx17(
       ProgressBridge,
       {
         save: api.saveProgress,
@@ -2180,13 +2271,13 @@ function ProgressBridge({
   const saveMutation = useMutation(save);
   const markCompleteMutation = useMutation(markComplete);
   const resetMutation = useMutation(reset);
-  const onSave = React22.useCallback(
+  const onSave = React24.useCallback(
     async (videoId, position) => {
       await saveMutation({ videoId, position });
     },
     [saveMutation]
   );
-  const onLoad = React22.useCallback(
+  const onLoad = React24.useCallback(
     async (videoId) => {
       const result = await convex.query(load, { videoId });
       if (!result) return null;
@@ -2197,60 +2288,34 @@ function ProgressBridge({
     },
     [convex, load]
   );
-  const onMarkComplete = React22.useCallback(
+  const onMarkComplete = React24.useCallback(
     async (videoId) => {
       await markCompleteMutation({ videoId });
     },
     [markCompleteMutation]
   );
-  const onReset = React22.useCallback(
+  const onReset = React24.useCallback(
     async (videoId) => {
       await resetMutation({ videoId });
     },
     [resetMutation]
   );
-  const value = React22.useMemo(
+  const value = React24.useMemo(
     () => ({ save: onSave, load: onLoad, markComplete: onMarkComplete, reset: onReset }),
     [onSave, onLoad, onMarkComplete, onReset]
   );
-  return /* @__PURE__ */ jsx16(ProgressContext, { value, children });
-}
-function useDevultur() {
-  const context = React22.use(DevulturContext);
-  if (!context) throw new Error("useDevultur must be used within <DevulturProvider> or <DevulturViewerProvider>");
-  return context;
-}
-function useDevulturApi() {
-  const api = React22.use(DevulturApiContext);
-  if (api) return api;
-  if (React22.use(DevulturContext)) throw new DevulturCapabilityError("api");
-  throw new Error("useDevulturApi must be used within <DevulturProvider>");
-}
-var VIEWER_ACTIONS = {
-  uploadUrl: () => Promise.reject(new DevulturCapabilityError("uploadUrl")),
-  upload: () => Promise.reject(new DevulturCapabilityError("upload")),
-  deleteMedia: () => {
-    throw new DevulturCapabilityError("deleteMedia");
-  }
-};
-function DevulturViewerProvider({
-  baseUrl,
-  issueViewerToken,
-  tokenArgs,
-  children
-}) {
-  const session = useMediaSession({ issueViewerToken, tokenArgs, baseUrl });
-  const devulturValue = React22.useMemo(() => ({ ...session, ...VIEWER_ACTIONS }), [session]);
-  return /* @__PURE__ */ jsx16(DevulturContext, { value: devulturValue, children });
+  return /* @__PURE__ */ jsx17(ProgressContext, { value, children });
 }
 function useDevulturProgress() {
-  const context = React22.use(ProgressContext);
+  const context = React24.use(ProgressContext);
   if (!context) throw new Error("useDevulturProgress requires progress API in DevulturProvider");
   return context;
 }
 function useMediaUrl(key, options) {
-  const { token, baseUrl } = useDevultur();
-  return React22.useMemo(() => {
+  const devultur = useDevultur();
+  const { token, baseUrl } = devultur;
+  useRequestTokenWhen(devultur, Boolean(key) && visibilityFromKey(key ?? "") !== "public");
+  return React24.useMemo(() => {
     if (!key) return null;
     if (!baseUrl) throw new Error("useMediaUrl requires `baseUrl` on <DevulturProvider>");
     const isPublic = visibilityFromKey(key) === "public";
@@ -2276,9 +2341,11 @@ async function readImageDimensions(file) {
   }
 }
 function useVideoProps(media, options) {
-  const { token, baseUrl, sessionSecret } = useDevultur();
+  const devultur = useDevultur();
+  const { token, baseUrl, sessionSecret } = devultur;
+  useRequestTokenWhen(devultur, media?.kind === "video" && media.visibility === "private");
   const locales = options?.locales;
-  return React22.useMemo(() => {
+  return React24.useMemo(() => {
     if (media?.kind !== "video") return null;
     if (!baseUrl) throw new Error("useVideoProps requires `baseUrl` on <DevulturProvider>");
     const viewerToken = media.visibility === "private" ? token ?? void 0 : void 0;
@@ -2297,8 +2364,10 @@ function useVideoProps(media, options) {
   }, [media, baseUrl, token, locales, sessionSecret]);
 }
 function DownloadLink({ media, filename, onDownloadError, children, ...anchorProps }) {
-  const { url, token, tokenStatus, tokenError, baseUrl, sessionSecret, reissueToken } = useDevultur();
-  const handleClick = React22.useCallback(
+  const devultur = useDevultur();
+  const { url, token, tokenStatus, tokenError, baseUrl, sessionSecret, reissueToken } = devultur;
+  useRequestTokenWhen(devultur, media?.visibility === "private");
+  const handleClick = React24.useCallback(
     async (event) => {
       if (media?.visibility !== "private" || !baseUrl) return;
       event.preventDefault();
@@ -2327,10 +2396,10 @@ function DownloadLink({ media, filename, onDownloadError, children, ...anchorPro
     [media, baseUrl, token, tokenStatus, tokenError, filename, sessionSecret, reissueToken, onDownloadError]
   );
   if (!media) return null;
-  return /* @__PURE__ */ jsx16("a", { href: url(media, { download: filename ?? true }), download: true, ...anchorProps, onClick: handleClick, children });
+  return /* @__PURE__ */ jsx17("a", { href: url(media, { download: filename ?? true }), download: true, ...anchorProps, onClick: handleClick, children });
 }
 function useDevulturMedia(key) {
-  const apiCtx = React22.use(DevulturApiContext);
+  const apiCtx = React24.use(DevulturApiContext);
   if (!apiCtx?.getMedia) {
     throw new Error("useDevulturMedia requires getMedia in DevulturProvider api");
   }
@@ -2384,10 +2453,12 @@ function useDevulturMedia(key) {
   };
 }
 function useVideoState(media, options) {
-  const { token, baseUrl, sessionSecret } = useDevultur();
+  const devultur = useDevultur();
+  const { token, baseUrl, sessionSecret } = devultur;
+  useRequestTokenWhen(devultur, media?.kind === "video" && media.visibility === "private");
   const status = useDevulturMedia(media?.kind === "video" ? media.id : null);
   const locales = options?.locales;
-  return React22.useMemo(() => {
+  return React24.useMemo(() => {
     if (media?.kind !== "video") return { phase: "idle" };
     if (status.isFailed) {
       return {
@@ -2436,17 +2507,17 @@ function useMediaUpload(options) {
   const deleteMediaAction = useAction2(api.deleteMedia);
   const confirmUploadAction = useAction2(api.confirmUpload ?? api.createUploadUrl);
   const processVideoAction = useAction2(api.processVideo ?? api.createUploadUrl);
-  const [phase, setPhase] = React22.useState("idle");
-  const [percent, setPercent] = React22.useState(0);
-  const [currentFile, setCurrentFile] = React22.useState(null);
-  const [media, setMedia] = React22.useState(null);
-  const [uploadFailure, setUploadFailure] = React22.useState(null);
-  const [processRequested, setProcessRequested] = React22.useState(false);
-  const abortRef = React22.useRef(null);
-  const lastFileRef = React22.useRef(null);
-  const lastKeyRef = React22.useRef(null);
+  const [phase, setPhase] = React24.useState("idle");
+  const [percent, setPercent] = React24.useState(0);
+  const [currentFile, setCurrentFile] = React24.useState(null);
+  const [media, setMedia] = React24.useState(null);
+  const [uploadFailure, setUploadFailure] = React24.useState(null);
+  const [processRequested, setProcessRequested] = React24.useState(false);
+  const abortRef = React24.useRef(null);
+  const lastFileRef = React24.useRef(null);
+  const lastKeyRef = React24.useRef(null);
   const videoState = useVideoState(media, { locales });
-  const triggerProcess = React22.useCallback(
+  const triggerProcess = React24.useCallback(
     (key) => {
       if (!api.processVideo) {
         throw new Error("useMediaUpload: processing a video requires `processVideo` in the <DevulturProvider> api");
@@ -2459,7 +2530,7 @@ function useMediaUpload(options) {
     },
     [api.processVideo, processVideoAction]
   );
-  const runUpload = React22.useCallback(
+  const runUpload = React24.useCallback(
     async (file) => {
       const controller = new AbortController();
       abortRef.current = controller;
@@ -2530,10 +2601,10 @@ function useMediaUpload(options) {
       onError
     ]
   );
-  const cancel = React22.useCallback(() => {
+  const cancel = React24.useCallback(() => {
     abortRef.current?.abort();
   }, []);
-  const reset = React22.useCallback(() => {
+  const reset = React24.useCallback(() => {
     abortRef.current?.abort();
     setPhase("idle");
     setPercent(0);
@@ -2542,15 +2613,15 @@ function useMediaUpload(options) {
     setUploadFailure(null);
     setProcessRequested(false);
   }, []);
-  const retry = React22.useCallback(() => {
+  const retry = React24.useCallback(() => {
     if (phase === "upload-failed" && lastFileRef.current) {
       runUpload(lastFileRef.current);
       return;
     }
     if (lastKeyRef.current) triggerProcess(lastKeyRef.current);
   }, [phase, runUpload, triggerProcess]);
-  React22.useEffect(() => () => abortRef.current?.abort(), []);
-  const state = React22.useMemo(
+  React24.useEffect(() => () => abortRef.current?.abort(), []);
+  const state = React24.useMemo(
     () => deriveUploadState(
       { phase, percent, file: currentFile, failure: uploadFailure, media, processRequested },
       videoState,
@@ -2558,7 +2629,7 @@ function useMediaUpload(options) {
     ),
     [phase, percent, currentFile, uploadFailure, media, processRequested, videoState, retry]
   );
-  const upload = React22.useCallback((file) => runUpload(file), [runUpload]);
+  const upload = React24.useCallback((file) => runUpload(file), [runUpload]);
   return { upload, state, cancel, reset };
 }
 export {
@@ -2586,6 +2657,7 @@ export {
   useDevultur,
   useDevulturApi,
   useDevulturMedia,
+  useDevulturOptional,
   useDevulturProgress,
   useMediaLibrary,
   useMediaObjectUrl,