@devultur/convex 1.3.1 → 1.4.0

package/dist/react.d.ts

@@ -1,10 +1,89 @@
 import React from 'react';
-import { Visibility, DevulturMedia, MediaUrlOptions, ProcessingPhase, FailureReason, MediaStatusValue } from '@devultur/core';
+import { DevulturMedia, MediaUrlOptions, Visibility, ProcessingPhase, FailureReason, MediaStatusValue } from '@devultur/core';
 import { BakeOutputFormat, MediaUploadState, MediaUploadError, UploadProgress } from '@devultur/react';
 export { MediaUploadError, MediaUploadState, UploadProgress } from '@devultur/react';
 import { FunctionReference } from 'convex/server';
-import { a as PdfjsLoader } from './pdf-render-CiCK6V1X.js';
-export { P as PdfjsModule } from './pdf-render-CiCK6V1X.js';
+import { Value } from 'convex/values';
+import { A as AttachmentLabels, M as MediaLibraryLabels, a as MediaPickerLabels } from './media-picker-labels-CiVcNUZo.js';
+export { b as AttachmentKind, d as defaultAttachmentLabels, c as defaultMediaLibraryLabels, e as defaultMediaPickerLabels, f as formatDuration, g as formatFileSize } from './media-picker-labels-CiVcNUZo.js';
+import { M as MediaRecord } from './types-LrusGVDf.js';
+import { P as PdfjsLoader } from './pdf-render-BwJGagvz.js';
+export { a as PdfjsModule } from './pdf-render-BwJGagvz.js';
+
+/** Why a media fetch was refused. Stable: match on it, not on `message`. */
+type MediaFetchErrorCode = 
+/** The delivery answered with a non-2xx status (`status` has it). */
+"http_error"
+/** `Content-Length`, or the streamed body, exceeds `maxBytes`. */
+ | "too_large"
+/** The expected content type isn't one that can be previewed inline. */
+ | "unsupported_type"
+/** The response's `Content-Type` doesn't agree with the expected one. */
+ | "type_mismatch"
+/** No viewer token for private media: its issuance failed (`useDevultur().tokenError` has why) or was refused. */
+ | "token_unavailable"
+/** The delivery refused the token for this browser session, also after a re-issue (video playback). */
+ | "session_mismatch";
+declare class MediaFetchError extends Error {
+    readonly code: MediaFetchErrorCode;
+    /** HTTP status, for `http_error`. */
+    readonly status?: number;
+    constructor(code: MediaFetchErrorCode, message: string, status?: number, options?: ErrorOptions);
+}
+
+/** What a viewer token action returns: the token with its lifetime, or the bare token (default lifetime). */
+type ViewerTokenResult = {
+    token: string;
+    expiresIn: number;
+} | string;
+/** Extra arguments sent with `sessionSecret` to the viewer token action. */
+type ViewerTokenArgs = Record<string, Value>;
+/**
+ * Where the viewer token for the current `tokenArgs` stands: not requested yet, being issued (no token yet), held, or
+ * failed (the action threw or returned no token). A renewal in flight, or one that failed, keeps `"ready"`.
+ */
+type TokenStatus = "idle" | "loading" | "ready" | "error";
+
+/** Transform/delivery options for media URLs (without `token`, which the context injects). */
+type MediaRenderOptions = Omit<MediaUrlOptions, "token">;
+type ViewerTokenAction = FunctionReference<"action", "public", {
+    sessionSecret: string;
+}>;
+interface MediaSession {
+    token: string | null;
+    /** Where the viewer token stands; `"error"` makes private previews fail fast with `token_unavailable`. */
+    tokenStatus: TokenStatus;
+    /** Why the last issuance failed (the action threw or returned no token), while `tokenStatus` is `"error"`. */
+    tokenError: Error | null;
+    /** Issues the viewer token again (after a failure, for example). Resolves to the new token, or `null`. */
+    retryToken: () => Promise<string | null>;
+    baseUrl: string | null;
+    /** Browser session secret → sent in `${SESSION_HEADER}` on every private delivery. */
+    sessionSecret: string;
+    /** Delivery URL from a reference (non-hook → usable in handlers and `.map`). Token-transparent. */
+    url: (media: DevulturMedia, options?: MediaRenderOptions) => string;
+    /** Downloads a video's subtitle text for a locale (auth-transparent). */
+    getCaptionsText: (media: DevulturMedia, locale: string) => Promise<string>;
+    /**
+     * Re-issues the viewer token (new session fingerprint with the current UA/IP) and updates the context.
+     * Single-flight: concurrent calls share the same issuance. Returns the new token (or null if it
+     * failed). The render uses it to transparently recover from a 401 `session_mismatch`.
+     */
+    reissueToken: () => Promise<string | null>;
+}
+
+/** What `useDevultur()` can do only under a `<DevulturProvider>` given the matching actions. */
+type DevulturCapability = "upload" | "uploadUrl" | "deleteMedia" | "api";
+/**
+ * Thrown (or rejected) when an app calls something its provider wasn't given: `upload`, `uploadUrl` or `deleteMedia`
+ * under a `<DevulturViewerProvider>`, or a hook that needs the `api` (`useMediaUpload`, `<MediaLibrary>`, ...).
+ * Stable `code`: `capability_unavailable`.
+ */
+declare class DevulturCapabilityError extends Error {
+    readonly code = "capability_unavailable";
+    readonly capability: DevulturCapability;
+    constructor(capability: DevulturCapability);
+}
 
 interface CropUploadRenderProps {
     /** The state machine of the full cycle (idle → uploading → ready / failed). */
@@ -53,22 +132,147 @@ interface CropUploadProps {
  */
 declare function CropUpload({ aspectRatio, visibility, outputFormat, maxWidth, minSourceWidth, replaces, onComplete, onReject, accept, cropperClassName, labels, children, }: CropUploadProps): React.JSX.Element;
 
-/** Why a media fetch was refused. Stable: match on it, not on `message`. */
-type MediaFetchErrorCode = 
-/** The delivery answered with a non-2xx status (`status` has it). */
-"http_error"
-/** `Content-Length`, or the streamed body, exceeds `maxBytes`. */
- | "too_large"
-/** The expected content type isn't one that can be previewed inline. */
- | "unsupported_type"
-/** The response's `Content-Type` doesn't agree with the expected one. */
- | "type_mismatch";
-declare class MediaFetchError extends Error {
-    readonly code: MediaFetchErrorCode;
-    /** HTTP status, for `http_error`. */
-    readonly status?: number;
-    constructor(code: MediaFetchErrorCode, message: string, status?: number);
+interface DocumentLinkProps extends Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, "href" | "download" | "media"> {
+    /** Typed reference. `null`/`undefined` → renders nothing. */
+    media: DevulturMedia | null | undefined;
+    /** `true` → the link downloads the file instead of opening it. Private media always downloads. Default `false`. */
+    download?: boolean;
+    /** Text of the link. Default: the media's `title`, else its filename, else `labels.untitled`. */
+    children?: React.ReactNode;
+    labels?: Partial<AttachmentLabels>;
+}
+/**
+ * A link to a media's file, named after it. Public: a plain link to the delivery URL (it opens in the browser, or
+ * downloads with `download`). Private: a navigation can't send the session header, so the click fetches the file
+ * with it and downloads it, as `<DownloadLink>` does.
+ *
+ * @example
+ * <DocumentLink media={invoice.file} target="_blank" rel="noopener" />
+ */
+declare function DocumentLink({ media, download, children, labels, ...anchorProps }: DocumentLinkProps): React.JSX.Element | null;
+type HeadingLevel = 2 | 3 | 4 | 5 | 6;
+interface AttachmentCardProps extends Omit<React.HTMLAttributes<HTMLElement>, "children"> {
+    /** Typed reference. `null`/`undefined` → renders nothing. */
+    media: DevulturMedia | null | undefined;
+    /** The type you know the media has. Default: inferred from `media.filename`'s extension (picks the icon). */
+    contentType?: string;
+    /** Shows an "Open preview" button that calls this, e.g. to render `<Preview>` in a dialog. */
+    onOpen?: (media: DevulturMedia) => void;
+    /** Shown in place of the type icon, e.g. a `<PdfThumbnail>` or an `<Image>`. */
+    preview?: React.ReactNode;
+    /** Level of the name's heading. Default `3`. */
+    headingLevel?: HeadingLevel;
+    /** Locale for the size. Default: `labels.locale` (`en`). */
+    locale?: string;
+    labels?: Partial<AttachmentLabels>;
+}
+/**
+ * A card for an attachment: an icon by type (or your `preview`), its name, its type and size, its page count (PDF)
+ * or duration (audio, video), a download link and, with `onOpen`, an "Open preview" button. Unstyled: target its
+ * parts with `data-part` (`icon`, `name`, `details`, `actions`, `download`, `open`).
+ *
+ * @example
+ * <AttachmentCard media={file} onOpen={setPreviewed} />
+ */
+declare function AttachmentCard({ media, contentType, onOpen, preview, headingLevel, locale, labels, ...articleProps }: AttachmentCardProps): React.JSX.Element | null;
+
+/** An explicit `srcSet` is passed through to the `<img>` as is, and wins over the one `widths` builds. */
+interface ImageProps extends Omit<React.ImgHTMLAttributes<HTMLImageElement>, "src" | "width" | "height"> {
+    /** Typed reference. `null`/`undefined` → renders `fallback` (or `externalFallback`). Its `alt` is the default `alt`. */
+    media: DevulturMedia | null | undefined;
+    /** Resize width (px). With `widths`, the width a private image is picked for when `sizes` can't tell. */
+    width?: number;
+    /** Resize height (px). With `widths` and `width`, it sets the ratio every variant keeps. */
+    height?: number;
+    fit?: MediaUrlOptions["fit"];
+    format?: MediaUrlOptions["format"];
+    quality?: number;
+    /**
+     * Responsive widths (px). Public images get a `srcset` with one transformed variant per width, and default to
+     * `loading="lazy"` and `decoding="async"`. Private images are fetched once, at the largest width up to twice the
+     * width `sizes` (or `width`) gives them: a `blob:` URL can't be a `srcset` candidate.
+     */
+    widths?: readonly number[];
+    /** What to show when there's no media (or it's loading). */
+    fallback?: React.ReactNode;
+    /** Explicit external URL (e.g. Unsplash) when `media` is null or the load fails. */
+    externalFallback?: string;
+    /** background-image mode: composes the URL as this element's `background-image` (doesn't force `<img>`). */
+    render?: React.ReactElement<{
+        style?: React.CSSProperties;
+    }>;
+    /**
+     * A private image that can't be shown: a `MediaFetchError` (`token_unavailable` right away when the viewer token
+     * couldn't be issued, `http_error` when the delivery refused it) or a network error. `fallback` shows meanwhile.
+     */
+    onLoadError?: (error: Error) => void;
+}
+/**
+ * Renders any media declaratively: token-transparent, with typed transforms, and works inside a
+ * `.map()` (no wrappers or hooks rules on the consumer's side).
+ *
+ * @example
+ * <Image media={course.thumbnail} alt={course.title} width={512} format="webp" fallback={<Placeholder />} />
+ * <Image media={post.cover} widths={[480, 960, 1440]} sizes="(min-width: 768px) 50vw, 100vw" format="webp" />
+ */
+declare function Image({ media, width, height, fit, format, quality, widths, sizes, fallback, externalFallback, render, alt, onLoadError, ...imgProps }: ImageProps): React.JSX.Element;
+
+/** What `renderItem` gets besides the record. */
+interface MediaLibraryItemState {
+    /** The record's reference (`mediaFromRecord`), `null` for a record without a visibility. */
+    media: DevulturMedia | null;
+    /** Chosen (only with `selectable`). */
+    isSelected: boolean;
+    /** The item the arrow keys move from (the one in the tab order). */
+    isActive: boolean;
 }
+/** The parts of `<MediaLibrary>` that have a class name (`devultur-media-library__{part}`, `root`'s without the suffix). */
+type MediaLibraryPart = "root" | "search" | "filter" | "list" | "item" | "thumbnail" | "name" | "size" | "status" | "more";
+type MediaLibraryClassNames = Partial<Record<MediaLibraryPart, string>>;
+
+type MediaType$1 = MediaRecord["type"];
+interface MediaLibraryProps {
+    /** Called when an item is chosen (click, Enter or Space), with its reference (`null` for a record without one). */
+    onSelect: (record: MediaRecord, media: DevulturMedia | null) => void;
+    /** Overrides any of the strings; the rest stay English. */
+    labels?: Partial<MediaLibraryLabels>;
+    /** Only this kind of media; the type filter is then hidden. */
+    type?: MediaType$1;
+    /** Keeps the chosen item selected (`aria-selected`, `data-selected`), as a picker. Default `false`. */
+    selectable?: boolean;
+    /**
+     * The selected records' keys (the media ids), controlled by the app: with it, the library shows these as selected
+     * instead of the last one chosen. Implies `selectable`.
+     */
+    selectedKeys?: readonly string[];
+    /** Several items can be selected at once (`aria-multiselectable`), for `selectedKeys`. Default `false`. */
+    multiple?: boolean;
+    /** Shows only the records it returns `true` for, of each loaded page (a page can then show fewer items). */
+    filter?: (record: MediaRecord) => boolean;
+    /** Replaces an item's content (thumbnail, name and size). The item itself stays the focusable option. */
+    renderItem?: (record: MediaRecord, state: MediaLibraryItemState) => React.ReactNode;
+    /** Records per page. Default 24. */
+    pageSize?: number;
+    /**
+     * Draws page 1 of PDFs (`<PdfThumbnail>`, inside a `PdfPreviewProvider`). Each one downloads its PDF as it nears the
+     * viewport, so it's off by default: PDFs show an icon.
+     */
+    pdfThumbnails?: boolean;
+    /** Added to the root's `devultur-media-library` class. */
+    className?: string;
+    /** Added to each part's `devultur-media-library__{part}` class. */
+    classNames?: MediaLibraryClassNames;
+}
+/**
+ * A searchable grid of the media library: a search box, a type filter and the items (a thumbnail for images, an icon,
+ * the name and the size), a page at a time. Arrow keys, Home and End move between items. Needs `listMediaPage` and
+ * `searchMedia` in `<DevulturProvider api>`. Unstyled but for the layout; style it through the class names and the
+ * `--devultur-library-*` custom properties.
+ *
+ * @example
+ * <MediaLibrary type="image" selectable onSelect={(record, media) => setCover(media)} />
+ */
+declare function MediaLibrary(props: MediaLibraryProps): React.JSX.Element;
 
 interface UseMediaObjectUrlOptions {
     /** `false` → nothing is fetched (e.g. a list row that isn't selected). Default `true`. */
@@ -156,6 +360,153 @@ declare function PdfPreviewProvider({ pdfjs, workerSrc, labels, children, }: Pdf
     children: React.ReactNode;
 }): React.JSX.Element;
 
+/** A file the picker is uploading, or one that failed (a finished upload leaves the list for the selection). */
+interface MediaPickerUpload$1 {
+    /** Stable for the upload's lifetime, for React keys and `cancel(id)`. */
+    id: string;
+    file: File;
+    /** Bytes sent over the file's size, 0 to 1. */
+    fraction: number;
+    status: "uploading" | "failed";
+    /** Why it failed (`labels.uploadError` or `labels.notAccepted`), `null` while uploading. */
+    error: string | null;
+    /** A failed upload `accept` let through can be retried; a rejected file can't. */
+    canRetry: boolean;
+}
+interface MediaPickerUploads {
+    uploads: MediaPickerUpload$1[];
+    /** Uploads the files `accept` lets through (only the first one without `multiple`) and lists the rest as failed. */
+    start: (files: Iterable<File>) => void;
+    cancel: (id: string) => void;
+    retry: (id: string) => void;
+    dismiss: (id: string) => void;
+}
+
+/** What every part of a `<MediaPicker>` (and its render prop, and `useMediaPicker()`) gets. */
+interface MediaPickerState extends MediaPickerUploads {
+    /** The selection, in order (one item at most without `multiple`). */
+    selected: readonly DevulturMedia[];
+    multiple: boolean;
+    /** The upload `accept`: the picker's own, else the one its `type` implies. */
+    accept: readonly string[] | undefined;
+    /** The library's type filter: the picker's `type`, else the one `accept` implies. */
+    libraryType: MediaRecord["type"] | undefined;
+    labels: MediaPickerLabels;
+    libraryLabels: Partial<MediaLibraryLabels> | undefined;
+    attachmentLabels: Partial<AttachmentLabels> | undefined;
+    /** Selects a media (replaces the selection without `multiple`). */
+    select: (media: DevulturMedia) => void;
+    /** Selects a media, or removes it when it's selected already (with `multiple`). */
+    toggle: (media: DevulturMedia) => void;
+    remove: (media: DevulturMedia) => void;
+    clear: () => void;
+    /** Opens the browser's file chooser. */
+    openFileDialog: () => void;
+    /** Says `message` in the picker's polite live region. */
+    announce: (message: string) => void;
+    /** The selection's region, focused after an upload and a removal (the `<MediaPicker.Selection>` sets it). */
+    selectionRef: React.RefObject<HTMLElement | null>;
+}
+/** The state of the nearest `<MediaPicker>`, to build a part of your own. */
+declare function useMediaPicker(): MediaPickerState;
+
+/** What `<MediaPicker.Library>` passes through to `<MediaLibrary>`; the picker sets the rest. */
+type MediaPickerLibraryProps = Pick<MediaLibraryProps, "renderItem" | "pageSize" | "pdfThumbnails" | "className" | "classNames">;
+/**
+ * The picker's `<MediaLibrary>`: shows the selection as selected, picks (and, with `multiple`, unpicks) an item on
+ * click, Enter or Space, and lists only what `accept` lets through.
+ */
+declare function MediaPickerLibrary(props: MediaPickerLibraryProps): React.JSX.Element;
+
+interface MediaPickerSelectionProps {
+    /** Replaces an item's card. The remove button stays below it. */
+    renderItem?: (media: DevulturMedia) => React.ReactNode;
+    /** Level of the selection's heading (the cards' are one below). Default `3`. */
+    headingLevel?: 2 | 3 | 4 | 5;
+    /** Added to the region's `devultur-media-picker__selection` class. */
+    className?: string;
+}
+/**
+ * The picker's selection: a card per item (a thumbnail for images, the name, type, size and a download link) with
+ * "Open preview" (an inline `<Preview>`) and remove, plus clear, and replace without `multiple`. Focused after an
+ * upload and a removal, so a keyboard user lands on the result.
+ */
+declare function MediaPickerSelection({ renderItem, headingLevel, className }: MediaPickerSelectionProps): React.JSX.Element;
+
+interface MediaPickerUploadProps {
+    /** Added to the drop zone's `devultur-media-picker__upload` class. */
+    className?: string;
+}
+/**
+ * The picker's upload area: a button that opens the file chooser, a drop target for files, and each upload's
+ * progress with a cancel button (or its error, with retry and dismiss).
+ */
+declare function MediaPickerUpload({ className }: MediaPickerUploadProps): React.JSX.Element;
+
+interface SingleValueProps {
+    multiple?: false;
+    /** The selected media, controlled. Omitted → the picker keeps its own. */
+    value?: DevulturMedia | null;
+    /** Called with the new selection: on an upload, a pick from the library, a removal or a clear. */
+    onChange: (value: DevulturMedia | null) => void;
+}
+interface MultipleValueProps {
+    /** Several media can be selected; `value` and `onChange` take arrays. */
+    multiple: true;
+    value?: readonly DevulturMedia[];
+    onChange: (value: DevulturMedia[]) => void;
+}
+interface CommonProps {
+    /**
+     * File types to pick, as an `<input accept>` takes them (`image/*`, `application/pdf`, `.pdf`). Filters the files to
+     * upload and the library's records, and sets the library's type filter when they're all of one type.
+     */
+    accept?: readonly string[];
+    /** Only this kind of media in the library; without `accept`, also what can be uploaded (`image/*`, `video/*`). */
+    type?: MediaRecord["type"];
+    /** Overrides any of the picker's strings; the rest stay English. */
+    labels?: Partial<MediaPickerLabels>;
+    /** Labels for the library (`<MediaPicker.Library>`). */
+    libraryLabels?: Partial<MediaLibraryLabels>;
+    /** Labels for the selection's cards (`<AttachmentCard>`). */
+    attachmentLabels?: Partial<AttachmentLabels>;
+    /** Added to the root's `devultur-media-picker` class. */
+    className?: string;
+    /**
+     * The picker's layout: the parts (`<MediaPicker.Upload>`, `.Library`, `.Selection`) in any order and markup, or a
+     * function of the picker's state. Default: the upload, the library and the selection, in that order.
+     */
+    children?: React.ReactNode | ((picker: MediaPickerState) => React.ReactNode);
+}
+type MediaPickerProps = CommonProps & (SingleValueProps | MultipleValueProps);
+/**
+ * Lets an editor pick media: upload new files (progress, cancel, retry), browse and search the library, and review
+ * the selection. Returns `DevulturMedia` references through `onChange`; a new upload is selected. It renders inline,
+ * with no dialog of its own: put it in yours. Needs `createUploadUrl`, `listMediaPage` and `searchMedia` in
+ * `<DevulturProvider api>` (and `confirmUpload` to record uploads). Under a `PdfPreviewProvider` with pdf.js, a PDF's
+ * page count is read before it uploads.
+ *
+ * @example
+ * <MediaPicker accept={["image/*"]} value={cover} onChange={setCover} />
+ */
+declare function MediaPicker(props: MediaPickerProps): React.JSX.Element;
+declare namespace MediaPicker {
+    var Upload: typeof MediaPickerUpload;
+    var Library: typeof MediaPickerLibrary;
+    var Selection: typeof MediaPickerSelection;
+}
+
+/** A file's name and type, or a record's filename and content type. */
+interface Candidate {
+    name: string;
+    type: string;
+}
+/**
+ * Whether `candidate` matches one of the `accept` patterns, as an `<input accept>` does: a MIME type
+ * (`application/pdf`), a wildcard (`image/*`) or an extension (`.pdf`). No `accept` (or an empty one) accepts all.
+ */
+declare function matchesAccept(candidate: Candidate, accept: readonly string[] | undefined): boolean;
+
 interface PdfThumbnailProps {
     /** Typed reference. `null`/`undefined` → renders nothing. */
     media: DevulturMedia | null | undefined;
@@ -198,7 +549,8 @@ interface PreviewProps {
     /**
      * Shown for types that don't preview inline and when the fetch fails. Default: a `<DownloadLink>`.
      * As a function it receives why: a `MediaFetchError` when the fetch was refused (`http_error`, `too_large`,
-     * `type_mismatch`) or the type doesn't preview inline (`unsupported_type`, nothing fetched), `null` otherwise
+     * `type_mismatch`), the viewer token couldn't be issued (`token_unavailable`, nothing fetched), a video's session
+     * was refused (`session_mismatch`) or the type doesn't preview inline (`unsupported_type`), `null` otherwise
      * (a network failure, a PDF pdf.js can't open, or the link after the `maxPages` note).
      */
     fallback?: React.ReactNode | ((error: MediaFetchError | null) => React.ReactNode);
@@ -231,8 +583,40 @@ declare function Preview({ media, contentType, fallback, loading, labels, ...vie
 /** How a content type renders inline: `<img>`, a PDF view (pdf.js canvases or `<iframe>`), `<audio>` or `<pre>`. */
 type PreviewKind = "image" | "pdf" | "audio" | "text";
 
-/** Transform/delivery options for media URLs (without `token`, which the context injects). */
-type MediaRenderOptions = Omit<MediaUrlOptions, "token">;
+type MediaType = MediaRecord["type"];
+interface UseMediaLibraryOptions {
+    /** Only this kind of media. Default: every kind. */
+    type?: MediaType;
+    /** Matches the title and filename. Debounced 250 ms; clearing it applies at once. Blank → newest first. */
+    search?: string;
+    /** Records in the first page and in each `loadMore()`. Default 24. */
+    pageSize?: number;
+}
+/** Convex's pagination status. */
+type MediaLibraryStatus = "LoadingFirstPage" | "CanLoadMore" | "LoadingMore" | "Exhausted";
+interface MediaLibraryState {
+    /** The records loaded so far: newest first, or best match first while searching. */
+    items: MediaRecord[];
+    status: MediaLibraryStatus;
+    /** Loads `numItems` more (default `pageSize`). Does nothing unless `status` is `"CanLoadMore"`. */
+    loadMore: (numItems?: number) => void;
+    /** The first page or a further one is loading. */
+    isLoading: boolean;
+    /** The search the items are for (the debounced `search`, trimmed). */
+    search: string;
+    /** `search` changed and the debounce hasn't applied it yet. */
+    isSearchPending: boolean;
+}
+/**
+ * The media library a page at a time, from the `listMediaPage` and `searchMedia` your `<DevulturProvider api>`
+ * passes. A new search or type starts again from the first page. Like Convex's `usePaginatedQuery`, a failed query
+ * throws to the nearest error boundary (`<MediaLibrary>` has its own).
+ *
+ * @example
+ * const { items, status, loadMore } = useMediaLibrary({ type: "image", search });
+ */
+declare function useMediaLibrary(options?: UseMediaLibraryOptions): MediaLibraryState;
+
 type AnyAction = FunctionReference<"action">;
 type AnyMutation = FunctionReference<"mutation">;
 type AnyQuery = FunctionReference<"query">;
@@ -247,6 +631,10 @@ interface DevulturApi {
     /** Requests the transcode of an uploaded video. Required by `useMediaUpload` for auto-process. */
     processVideo?: AnyAction;
     getMedia?: AnyQuery;
+    /** The library, newest first. Required by `useMediaLibrary` and `<MediaLibrary>`. */
+    listMediaPage?: AnyQuery;
+    /** The library matching a search. Required by `useMediaLibrary` and `<MediaLibrary>` to search. */
+    searchMedia?: AnyQuery;
     saveProgress?: AnyMutation;
     loadProgress?: AnyQuery;
     markComplete?: AnyMutation;
@@ -259,6 +647,8 @@ interface UploadOptions {
     onProgress?: (progress: UploadProgress) => void;
     /** Aborts the PUT → `upload()` rejects with an `AbortError`. */
     signal?: AbortSignal;
+    /** A PDF's page count to record with it, a hint (`countPdfPages` from `@devultur/convex/pdfjs` counts it). */
+    pageCount?: number;
 }
 /**
  * The reference `upload()` resolves to: a `DevulturMedia` whose `key` is always set (the uploaded object's key; a
@@ -267,29 +657,19 @@ interface UploadOptions {
 type UploadedMedia = DevulturMedia & {
     readonly key: string;
 };
-interface DevulturContextValue {
-    token: string | null;
-    baseUrl: string | null;
-    /** Browser session secret → sent in `${SESSION_HEADER}` on every private delivery. */
-    sessionSecret: string;
+/**
+ * What `useDevultur()` returns. Under a `<DevulturViewerProvider>`, `uploadUrl`, `upload` and `deleteMedia` throw a
+ * `DevulturCapabilityError` (`capability_unavailable`).
+ */
+interface DevulturContextValue extends MediaSession {
     uploadUrl: (file: File) => Promise<{
         url: string;
         key: string;
     }>;
     /** Uploads a file (reporting progress), records it in the component, and returns the reference ready to save. */
     upload: (file: File, options?: UploadOptions) => Promise<UploadedMedia>;
-    /** Delivery URL from a reference (non-hook → usable in handlers and `.map`). Token-transparent. */
-    url: (media: DevulturMedia, options?: MediaRenderOptions) => string;
-    /** Downloads a video's subtitle text for a locale (auth-transparent). */
-    getCaptionsText: (media: DevulturMedia, locale: string) => Promise<string>;
     /** Deletes a media by reference: video → full folder; image/file → the object. */
     deleteMedia: (media: DevulturMedia) => void;
-    /**
-     * Re-issues the viewer token (new session fingerprint with the current UA/IP) and updates the context.
-     * Single-flight: concurrent calls share the same issuance. Returns the new token (or null if it
-     * failed). The render uses it to transparently recover from a 401 `session_mismatch`.
-     */
-    reissueToken: () => Promise<string | null>;
 }
 interface ProgressContextValue {
     save: (videoId: string, position: number) => Promise<void>;
@@ -304,10 +684,48 @@ interface DevulturProviderProps {
     api: DevulturApi;
     /** Media worker base (e.g. `https://media.your-domain.com`). Required for `useMediaUrl`. */
     baseUrl?: string;
+    /**
+     * Extra arguments sent with `sessionSecret` on every viewer token issuance (first, renewal and re-issue), for
+     * example `{ workspaceId }`. Compared by value: when they change, the current token is dropped and a new one is
+     * issued. The component's own `issueViewerToken` accepts only `sessionSecret`, so pass your own action in
+     * `issueViewerToken` that takes these arguments.
+     */
+    tokenArgs?: ViewerTokenArgs;
+    /**
+     * Your own viewer token action, used instead of `api.issueViewerToken`. It receives `{ sessionSecret, ...tokenArgs }`
+     * and returns what the component's `issueViewerToken` returns.
+     */
+    issueViewerToken?: ViewerTokenAction;
     children: React.ReactNode;
 }
-declare function DevulturProvider({ api, baseUrl, children }: DevulturProviderProps): React.JSX.Element;
+declare function DevulturProvider({ api, baseUrl, tokenArgs, issueViewerToken, children }: DevulturProviderProps): React.JSX.Element;
 declare function useDevultur(): DevulturContextValue;
+/**
+ * The `api` passed to `<DevulturProvider>`: your app's exported Devultur functions. Under a `<DevulturViewerProvider>`
+ * it throws a `DevulturCapabilityError`.
+ */
+declare function useDevulturApi(): DevulturApi;
+interface DevulturViewerProviderProps {
+    /** Media worker base (e.g. `https://media.your-domain.com`). */
+    baseUrl: string;
+    /** Your viewer token action. It receives `{ sessionSecret, ...tokenArgs }`, like `<DevulturProvider>`'s. */
+    issueViewerToken: ViewerTokenAction;
+    /** Extra arguments for `issueViewerToken`, compared by value (see `<DevulturProvider tokenArgs>`). */
+    tokenArgs?: ViewerTokenArgs;
+    children: React.ReactNode;
+}
+/**
+ * A provider for apps that only display media: it issues and renews the viewer token, so `<Image>`, `<Preview>`,
+ * `<DownloadLink>`, `useMediaObjectUrl` and the video hooks work, and it needs no upload or delete actions. `upload`,
+ * `uploadUrl` and `deleteMedia` throw a `DevulturCapabilityError`, as do the hooks that need the `api`
+ * (`useMediaUpload`, `useDevulturApi`, `<MediaLibrary>`, `<MediaPicker>`).
+ *
+ * @example
+ * <DevulturViewerProvider baseUrl={MEDIA_URL} issueViewerToken={api.admin.issueViewerToken} tokenArgs={{ workspaceId }}>
+ *   <Preview media={document.file} />
+ * </DevulturViewerProvider>
+ */
+declare function DevulturViewerProvider({ baseUrl, issueViewerToken, tokenArgs, children, }: DevulturViewerProviderProps): React.JSX.Element;
 declare function useDevulturProgress(): ProgressContextValue;
 /**
  * Ready-to-use delivery URL for a key, with the context's viewer token already injected. The consumer
@@ -338,35 +756,15 @@ interface VideoProps {
 declare function useVideoProps(media: DevulturMedia | null | undefined, options?: {
     locales?: string[];
 }): VideoProps | null;
-interface ImageProps extends Omit<React.ImgHTMLAttributes<HTMLImageElement>, "src" | "width" | "height"> {
-    /** Typed reference. `null`/`undefined` → renders `fallback` (or `externalFallback`). */
-    media: DevulturMedia | null | undefined;
-    width?: number;
-    height?: number;
-    fit?: MediaUrlOptions["fit"];
-    format?: MediaUrlOptions["format"];
-    quality?: number;
-    /** What to show when there's no media (or it's loading). */
-    fallback?: React.ReactNode;
-    /** Explicit external URL (e.g. Unsplash) when `media` is null or the load fails. */
-    externalFallback?: string;
-    /** background-image mode: composes the URL as this element's `background-image` (doesn't force `<img>`). */
-    render?: React.ReactElement<{
-        style?: React.CSSProperties;
-    }>;
-}
-/**
- * Renders any media declaratively: token-transparent, with typed transforms, and works inside a
- * `.map()` (no wrappers or hooks rules on the consumer's side).
- *
- * @example
- * <Image media={course.thumbnail} alt={course.title} width={512} format="webp" fallback={<Placeholder />} />
- */
-declare function Image({ media, width, height, fit, format, quality, fallback, externalFallback, render, alt, ...imgProps }: ImageProps): React.JSX.Element;
 interface DownloadLinkProps extends Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, "href" | "download" | "media"> {
     media: DevulturMedia | null | undefined;
     /** Name it downloads as. Without this it uses the upload's original name. */
     filename?: string;
+    /**
+     * A private download that failed: `token_unavailable` right away when the viewer token couldn't be issued
+     * (`useDevultur().retryToken()` tries again), `http_error` when the delivery refused it.
+     */
+    onDownloadError?: (error: MediaFetchError) => void;
     children: React.ReactNode;
 }
 /**
@@ -377,7 +775,7 @@ interface DownloadLinkProps extends Omit<React.AnchorHTMLAttributes<HTMLAnchorEl
  * binding the gate gives a 401. So, for private media, we intercept the click, blob-fetch with the header
  * (like private `<Image>`) and trigger the download from the object URL. Public keeps native navigation.
  */
-declare function DownloadLink({ media, filename, children, ...anchorProps }: DownloadLinkProps): React.JSX.Element | null;
+declare function DownloadLink({ media, filename, onDownloadError, children, ...anchorProps }: DownloadLinkProps): React.JSX.Element | null;
 interface MediaStatusReturn {
     status: MediaStatusValue;
     /** Typed progress: `phase` is the pipeline step (no `as any`). */
@@ -471,4 +869,4 @@ interface UseMediaUploadReturn {
  */
 declare function useMediaUpload(options?: UseMediaUploadOptions): UseMediaUploadReturn;
 
-export { type CaptionTrack, CropUpload, type CropUploadLabels, type CropUploadProps, type CropUploadRenderProps, DevulturProvider, DownloadLink, Image, MediaFetchError, type MediaFetchErrorCode, type MediaObjectUrl, type PdfPreviewConfig, PdfPreviewProvider, PdfThumbnail, type PdfThumbnailProps, PdfjsLoader, Preview, type PreviewKind, type PreviewLabels, type PreviewProps, type UploadedMedia, type UseMediaObjectUrlOptions, type UseMediaUploadOptions, type UseMediaUploadReturn, type VideoProps, type VideoState, defaultPreviewLabels, useDevultur, useDevulturMedia, useDevulturProgress, useMediaObjectUrl, useMediaUpload, useMediaUrl, useVideoProps, useVideoState };
+export { AttachmentCard, type AttachmentCardProps, AttachmentLabels, type CaptionTrack, CropUpload, type CropUploadLabels, type CropUploadProps, type CropUploadRenderProps, type DevulturApi, type DevulturCapability, DevulturCapabilityError, DevulturProvider, DevulturViewerProvider, DocumentLink, type DocumentLinkProps, DownloadLink, Image, type ImageProps, MediaFetchError, type MediaFetchErrorCode, MediaLibrary, type MediaLibraryItemState, MediaLibraryLabels, type MediaLibraryPart, type MediaLibraryProps, type MediaLibraryState, type MediaLibraryStatus, type MediaObjectUrl, MediaPicker, MediaPickerLabels, type MediaPickerLibraryProps, type MediaPickerProps, type MediaPickerSelectionProps, type MediaPickerState, type MediaPickerUpload$1 as MediaPickerUpload, type MediaPickerUploadProps, type MediaPickerUploads, type PdfPreviewConfig, PdfPreviewProvider, PdfThumbnail, type PdfThumbnailProps, PdfjsLoader, Preview, type PreviewKind, type PreviewLabels, type PreviewProps, type TokenStatus, type UploadedMedia, type UseMediaLibraryOptions, type UseMediaObjectUrlOptions, type UseMediaUploadOptions, type UseMediaUploadReturn, type VideoProps, type VideoState, type ViewerTokenArgs, type ViewerTokenResult, defaultPreviewLabels, matchesAccept, useDevultur, useDevulturApi, useDevulturMedia, useDevulturProgress, useMediaLibrary, useMediaObjectUrl, useMediaPicker, useMediaUpload, useMediaUrl, useVideoProps, useVideoState };