@ai-matrx/media 0.1.0

package/dist/react.d.cts

@@ -0,0 +1,310 @@
+import * as react from 'react';
+import react__default, { SVGProps, HTMLAttributes, InputHTMLAttributes, ReactNode } from 'react';
+import { b as MediaRefLike, l as MediaUploadOptions, i as MediaUploadEntry, f as MediaActionKind } from './use-media-upload-VjUhqbyY.cjs';
+
+/**
+ * src/react/cn.ts — conditional class join with last-wins Tailwind conflict
+ * merging. The originals used the app's `cn` (clsx + tailwind-merge); public
+ * `className` overrides depend on last-wins class-conflict merging, so a
+ * naive join would be a behavior divergence (the kit `./confirm` precedent —
+ * this is why `tailwind-merge` is a sanctioned runtime dep of `/react`).
+ */
+type ClassValue = string | false | null | undefined | 0;
+declare function cn(...inputs: ClassValue[]): string;
+
+type MediaIconProps = SVGProps<SVGSVGElement>;
+declare function ArchiveIcon(props: MediaIconProps): react.JSX.Element;
+declare function BracesIcon(props: MediaIconProps): react.JSX.Element;
+declare function CheckIcon(props: MediaIconProps): react.JSX.Element;
+declare function CodeIcon(props: MediaIconProps): react.JSX.Element;
+declare function CopyIcon(props: MediaIconProps): react.JSX.Element;
+declare function DatabaseIcon(props: MediaIconProps): react.JSX.Element;
+declare function DownloadIcon(props: MediaIconProps): react.JSX.Element;
+declare function ExternalLinkIcon(props: MediaIconProps): react.JSX.Element;
+declare function FileAudioIcon(props: MediaIconProps): react.JSX.Element;
+declare function FileCodeIcon(props: MediaIconProps): react.JSX.Element;
+declare function FileJsonIcon(props: MediaIconProps): react.JSX.Element;
+declare function FileSpreadsheetIcon(props: MediaIconProps): react.JSX.Element;
+declare function FileTextIcon(props: MediaIconProps): react.JSX.Element;
+declare function FileTypeIcon(props: MediaIconProps): react.JSX.Element;
+declare function FileVideoIcon(props: MediaIconProps): react.JSX.Element;
+declare function FolderIcon(props: MediaIconProps): react.JSX.Element;
+declare function FolderOpenIcon(props: MediaIconProps): react.JSX.Element;
+declare function ImageIcon(props: MediaIconProps): react.JSX.Element;
+declare function ImageOffIcon(props: MediaIconProps): react.JSX.Element;
+declare function MusicIcon(props: MediaIconProps): react.JSX.Element;
+declare function PackageBoxIcon(props: MediaIconProps): react.JSX.Element;
+declare function PenToolIcon(props: MediaIconProps): react.JSX.Element;
+declare function Share2Icon(props: MediaIconProps): react.JSX.Element;
+declare function SubtitlesIcon(props: MediaIconProps): react.JSX.Element;
+declare function UploadIcon(props: MediaIconProps): react.JSX.Element;
+declare function VideoIcon(props: MediaIconProps): react.JSX.Element;
+declare function VideoOffIcon(props: MediaIconProps): react.JSX.Element;
+declare function VolumeXIcon(props: MediaIconProps): react.JSX.Element;
+declare function XIcon(props: MediaIconProps): react.JSX.Element;
+declare function AlertCircleIcon(props: MediaIconProps): react.JSX.Element;
+declare function CheckCircle2Icon(props: MediaIconProps): react.JSX.Element;
+
+/**
+ * src/react/file-icon.tsx — icon tile for any file or folder.
+ *
+ * Verbatim port of matrx-frontend `components/core/FileIcon/FileIcon.tsx`
+ * with two seam inversions: the registry lookup is the package's own
+ * `getFileKindDetails` (`/core`), and the glyphs are the package's own
+ * inlined SVGs (C19 — no lucide peer).
+ */
+interface FileIconProps {
+    /** Either the filename (for files) or omitted for folders. */
+    fileName?: string | undefined;
+    /** Server MIME — when set, resolves audio/webm vs video/webm correctly. */
+    mimeType?: string | null | undefined;
+    /** If true, renders a folder icon. `open` picks the open-folder glyph. */
+    isFolder?: boolean | undefined;
+    open?: boolean | undefined;
+    /** Override the mapped color (useful for selected states). */
+    colorClass?: string | undefined;
+    className?: string | undefined;
+    size?: number | undefined;
+}
+declare function FileIcon({ fileName, mimeType, isFolder, open, colorClass, className, size, }: FileIconProps): react.JSX.Element;
+
+/**
+ * src/react/inline-media-ref.tsx — the canonical inline media renderer.
+ *
+ * Verbatim behavior port of matrx-frontend
+ * `features/files/components/inline/InlineMediaRef.tsx` (849 LOC, 116
+ * importers) with only the coupling seams inverted:
+ *
+ *   - URL resolution / public-CDN detection / auth-transport choice →
+ *     `MediaClient.resolve` (`transport: "blob"` is the private-pixels lane;
+ *     the Redux `useEnsureCloudFile`/`selectFileById` hydration lives behind
+ *     the client now)
+ *   - bearer-authenticated bytes → `MediaClient.getBlob` via `useMediaBlob`
+ *   - session-refresh retry → `MediaClient.recoverLoadError` via
+ *     `useMediaLoadRecovery`
+ *   - `next/image` → the injected `MediaHostPorts.ImageComponent` (plain
+ *     `<img>` default)
+ *   - audio output sink + exclusive-playback join → the injected
+ *     `MediaHostPorts.playbackSession` (inert default)
+ *   - lucide icons → the package's own inlined SVGs (C19)
+ *
+ * Pass a `MediaRef` (or a fileId / EXTERNAL public URL string), get back a
+ * correctly-sized `<img>` / `<video>` / `<audio>`. There is NO `src` prop —
+ * durable refs are the only identity this component accepts (law 2/3).
+ */
+
+type InlineMediaRefSize = "xs" | "sm" | "md" | "lg" | "xl" | "fill" | {
+    width: number;
+    height: number;
+};
+type InlineMediaRefFit = "cover" | "contain" | "fill";
+interface InlineMediaRefProps {
+    /**
+     * Reference to the media: a {@link MediaRef}, a bare fileId string, an
+     * EXTERNAL public URL string, or null/undefined (renders the fallback).
+     *
+     * Named `ref` as a CONTENT prop, exactly like the original (React 19
+     * treats ref as a regular prop on function components) — the 116 existing
+     * call sites pass `ref={mediaRef}` and must keep working at the C9 swap.
+     * Use `mediaElementRef` for imperative access to the DOM node.
+     */
+    ref?: MediaRefLike | null | undefined;
+    /** Square dimension preset or explicit width/height. Default `"md"` (64×64). */
+    size?: InlineMediaRefSize | undefined;
+    /** CSS object-fit. Default `"cover"`. */
+    fit?: InlineMediaRefFit | undefined;
+    /** Rendered when the ref can't be resolved to a URL at all. Default `"icon"`. */
+    fallback?: "icon" | "skeleton" | null | undefined;
+    /** Override the icon shown in `fallback="icon"`. */
+    fallbackIcon?: react__default.ReactNode | undefined;
+    /**
+     * Rendered when the URL *was* resolved but the media element failed to
+     * load. Default `"info"` — an informative destructive-tinted panel with
+     * URL + copy button + alt text; compacts to icon-only below ~64px.
+     */
+    errorFallback?: "info" | "icon" | "skeleton" | null | undefined;
+    /** Alt text for `<img>`. Defaults to "" (decorative). */
+    alt?: string | undefined;
+    /** Force the media element type. Default: infer from `mime_type` / resolution. */
+    as?: "img" | "video" | "audio" | undefined;
+    controls?: boolean | undefined;
+    autoPlay?: boolean | undefined;
+    loop?: boolean | undefined;
+    muted?: boolean | undefined;
+    playsInline?: boolean | undefined;
+    preload?: "none" | "metadata" | "auto" | undefined;
+    /** Space-separated native controls to hide — forwarded to `<video controlsList>`. */
+    controlsList?: string | undefined;
+    rounded?: "none" | "sm" | "md" | "lg" | "full" | undefined;
+    /** Click handler — wires up cursor + role + keyboard activation. */
+    onClick?: ((event: react__default.MouseEvent | react__default.KeyboardEvent) => void) | undefined;
+    /**
+     * Fires after the client's ONE recovery attempt is exhausted (or the
+     * failure was unrecoverable). The internal error fallback still renders
+     * unless `errorFallback={null}`.
+     */
+    onError?: ((event: react__default.SyntheticEvent<HTMLImageElement | HTMLVideoElement | HTMLAudioElement>) => void) | undefined;
+    onLoad?: ((event: react__default.SyntheticEvent<HTMLImageElement | HTMLVideoElement | HTMLAudioElement>) => void) | undefined;
+    /**
+     * Forwarded to the underlying element for imperative DOM access. Not a
+     * React `forwardRef` — pass any ref-like value here instead. When
+     * supplied, the ImageComponent branch is skipped so the ref attaches to
+     * the real DOM node.
+     */
+    mediaElementRef?: react__default.Ref<HTMLImageElement | HTMLVideoElement | HTMLAudioElement> | undefined;
+    /**
+     * Canvas pixel reads: `crossOrigin` consumers route through the
+     * bearer-authenticated blob lane unless the resolution is a CORS-safe
+     * public CDN URL.
+     */
+    crossOrigin?: "anonymous" | "use-credentials" | undefined;
+    border?: "none" | "subtle" | undefined;
+    className?: string | undefined;
+}
+declare function InlineMediaRef({ ref: mediaRef, size, fit, fallback, fallbackIcon, errorFallback, alt, as, controls, autoPlay, loop, muted, playsInline, preload, controlsList, rounded, onClick, onError, onLoad, mediaElementRef, crossOrigin, border, className, }: InlineMediaRefProps): react__default.JSX.Element | null;
+
+interface MediaThumbnailProps {
+    /** The file's durable ref (a MediaRef or bare fileId). */
+    mediaRef: MediaRefLike;
+    /** Display name — drives the icon fallback and alt text. */
+    fileName: string;
+    /** Server MIME, when known. */
+    mimeType?: string | null | undefined;
+    /** A known server-rendered thumbnail URL (`FileRecord.thumbnail_url`). */
+    thumbnailUrl?: string | null | undefined;
+    /** Pixel size for the icon fallback. Image/video fill their container. */
+    iconSize?: number | undefined;
+    /** Aspect ratio classes applied to the container, e.g. "aspect-[4/3]". */
+    className?: string | undefined;
+    /** Override the rounded corners of the container. */
+    rounded?: string | undefined;
+    /**
+     * Whether to fall back to a source-file URL when no rendered thumbnail is
+     * available. Disable in dense pickers to avoid a byte request per row.
+     */
+    allowSourceFallback?: boolean | undefined;
+}
+declare function MediaThumbnail({ mediaRef, fileName, mimeType, thumbnailUrl, iconSize, className, rounded, allowSourceFallback, }: MediaThumbnailProps): react.JSX.Element;
+
+/**
+ * src/react/use-media-dropzone.ts — headless drag + paste + picker intake.
+ *
+ * Replaces the original's `react-dropzone` dependency with native DOM events
+ * (the package's `/react` entry carries no UI-library deps). The behavior
+ * contract is the original FileUploadDropzone's: drag-over highlight, hidden
+ * input picker (`openPicker`), clipboard paste of images with a brief
+ * highlight pulse, an optional window event that opens the picker, and
+ * accept/maxSize filtering (UI-only; the server enforces its own caps).
+ */
+
+interface MediaDropzoneOptions {
+    /** Receives every accepted batch (drop, paste, or picker). */
+    onFiles: (files: File[]) => void;
+    /** Restrict accepted types, e.g. ["image/*", "application/pdf", ".csv"]. */
+    accept?: string[] | undefined;
+    /** Max size per file in bytes (UI-only filter). */
+    maxSize?: number | undefined;
+    /** Fires for files filtered out by accept/maxSize. */
+    onRejected?: ((rejected: Array<{
+        file: File;
+        reason: "type" | "size";
+    }>) => void) | undefined;
+    /** Enable clipboard paste (images only). Defaults true. */
+    enablePaste?: boolean | undefined;
+    /** Optional window event name that opens the native file picker. */
+    pickerEventName?: string | undefined;
+    disabled?: boolean | undefined;
+    multiple?: boolean | undefined;
+}
+interface MediaDropzoneState {
+    /** Spread onto the drop surface element. */
+    getRootProps: () => HTMLAttributes<HTMLElement>;
+    /** Spread onto a hidden `<input type="file">`. */
+    getInputProps: () => InputHTMLAttributes<HTMLInputElement> & {
+        ref: (node: HTMLInputElement | null) => void;
+    };
+    isDragActive: boolean;
+    /** Brief pulse after a successful clipboard paste. */
+    pasteHighlight: boolean;
+    openPicker: () => void;
+}
+declare function useMediaDropzone(options: MediaDropzoneOptions): MediaDropzoneState;
+
+interface FileUploadDropzoneActions {
+    openLocalPicker: () => void;
+    uploadFiles: (files: File[]) => Promise<void>;
+}
+interface FileUploadDropzoneProps {
+    /** Upload options forwarded to the client (visibility, folder, metadata…). */
+    uploadOptions?: MediaUploadOptions | undefined;
+    /** Restrict accepted types (e.g. ["image/*"]). */
+    accept?: string[] | undefined;
+    /** Max size per file in bytes (UI-only; server enforces its own cap). */
+    maxSize?: number | undefined;
+    /** Enable paste from clipboard (images only). Defaults true. */
+    enablePaste?: boolean | undefined;
+    /** Rendering mode. */
+    mode?: "overlay" | "inline" | undefined;
+    /** Children render inside the drop surface. */
+    children?: ReactNode | ((actions: FileUploadDropzoneActions) => ReactNode) | undefined;
+    className?: string | undefined;
+    /** Host-shaped acquisition sources (Drive, local folder, existing files…). */
+    actions?: ReactNode | undefined;
+    /** Fires the moment an upload batch STARTS (before any network completes). */
+    onUploadStart?: ((files: File[]) => void) | undefined;
+    onUploaded?: ((fileIds: string[]) => void) | undefined;
+    onError?: ((message: string) => void) | undefined;
+    /** Reveal a finished file from the upload tray. */
+    onOpenFile?: ((fileId: string) => void) | undefined;
+    /** Optional window event name that opens the native file picker. */
+    pickerEventName?: string | undefined;
+}
+declare function FileUploadDropzone({ uploadOptions, accept, maxSize, enablePaste, mode, children, className, actions, onUploadStart, onUploaded, onError, onOpenFile, pickerEventName, }: FileUploadDropzoneProps): react.JSX.Element;
+
+declare function formatFileSize(bytes: number): string;
+interface UploadProgressListProps {
+    uploads: MediaUploadEntry[];
+    /** Remove an entry from the tray (wire to `useMediaUpload().clearEntry`). */
+    onDismiss: (id: string) => void;
+    /**
+     * Reveal a finished file — opens the preview pane / scrolls the row.
+     * When omitted, the "Open" affordance is hidden.
+     */
+    onOpenFile?: ((fileId: string) => void) | undefined;
+    className?: string | undefined;
+}
+declare function UploadProgressListImpl({ uploads, onDismiss, onOpenFile, className, }: UploadProgressListProps): react.JSX.Element | null;
+declare const UploadProgressList: react.MemoExoticComponent<typeof UploadProgressListImpl>;
+
+interface MediaActionToolbarProps {
+    mediaRef: MediaRefLike | null | undefined;
+    fileName?: string | undefined;
+    alt?: string | undefined;
+    /** Which actions to render, in order. Default: share, download, copy, open. */
+    actions?: MediaActionKind[] | undefined;
+    /** Hide unavailable actions instead of rendering them disabled. */
+    hideUnavailable?: boolean | undefined;
+    className?: string | undefined;
+    buttonClassName?: string | undefined;
+}
+declare function MediaActionToolbar({ mediaRef, fileName, alt, actions, hideUnavailable, className, buttonClassName, }: MediaActionToolbarProps): react.JSX.Element | null;
+
+interface MediaLightboxProps {
+    open: boolean;
+    onClose: () => void;
+    mediaRef: MediaRefLike | null | undefined;
+    fileName?: string | undefined;
+    alt?: string | undefined;
+    /** Force the media element type (default: inferred from the resolution). */
+    as?: "img" | "video" | "audio" | undefined;
+    /** Toolbar actions to offer. Default: share, download, copy, open. */
+    actions?: MediaActionKind[] | undefined;
+    /** Hide unavailable toolbar actions instead of disabling them. */
+    hideUnavailableActions?: boolean | undefined;
+    /** Extra chrome rendered in the header row (left of the toolbar). */
+    headerExtra?: ReactNode | undefined;
+    className?: string | undefined;
+}
+declare function MediaLightbox({ open, onClose, mediaRef, fileName, alt, as, actions, hideUnavailableActions, headerExtra, className, }: MediaLightboxProps): react.JSX.Element | null;
+
+export { AlertCircleIcon, ArchiveIcon, BracesIcon, CheckCircle2Icon, CheckIcon, CodeIcon, CopyIcon, DatabaseIcon, DownloadIcon, ExternalLinkIcon, FileAudioIcon, FileCodeIcon, FileIcon, type FileIconProps, FileJsonIcon, FileSpreadsheetIcon, FileTextIcon, FileTypeIcon, FileUploadDropzone, type FileUploadDropzoneActions, type FileUploadDropzoneProps, FileVideoIcon, FolderIcon, FolderOpenIcon, ImageIcon, ImageOffIcon, InlineMediaRef, type InlineMediaRefFit, type InlineMediaRefProps, type InlineMediaRefSize, MediaActionToolbar, type MediaActionToolbarProps, type MediaDropzoneOptions, type MediaDropzoneState, type MediaIconProps, MediaLightbox, type MediaLightboxProps, MediaThumbnail, type MediaThumbnailProps, MusicIcon, PackageBoxIcon, PenToolIcon, Share2Icon, SubtitlesIcon, UploadIcon, UploadProgressList, type UploadProgressListProps, VideoIcon, VideoOffIcon, VolumeXIcon, XIcon, cn, formatFileSize, useMediaDropzone };

package/dist/react.d.ts

@@ -0,0 +1,310 @@
+import * as react from 'react';
+import react__default, { SVGProps, HTMLAttributes, InputHTMLAttributes, ReactNode } from 'react';
+import { b as MediaRefLike, l as MediaUploadOptions, i as MediaUploadEntry, f as MediaActionKind } from './use-media-upload-VjUhqbyY.js';
+
+/**
+ * src/react/cn.ts — conditional class join with last-wins Tailwind conflict
+ * merging. The originals used the app's `cn` (clsx + tailwind-merge); public
+ * `className` overrides depend on last-wins class-conflict merging, so a
+ * naive join would be a behavior divergence (the kit `./confirm` precedent —
+ * this is why `tailwind-merge` is a sanctioned runtime dep of `/react`).
+ */
+type ClassValue = string | false | null | undefined | 0;
+declare function cn(...inputs: ClassValue[]): string;
+
+type MediaIconProps = SVGProps<SVGSVGElement>;
+declare function ArchiveIcon(props: MediaIconProps): react.JSX.Element;
+declare function BracesIcon(props: MediaIconProps): react.JSX.Element;
+declare function CheckIcon(props: MediaIconProps): react.JSX.Element;
+declare function CodeIcon(props: MediaIconProps): react.JSX.Element;
+declare function CopyIcon(props: MediaIconProps): react.JSX.Element;
+declare function DatabaseIcon(props: MediaIconProps): react.JSX.Element;
+declare function DownloadIcon(props: MediaIconProps): react.JSX.Element;
+declare function ExternalLinkIcon(props: MediaIconProps): react.JSX.Element;
+declare function FileAudioIcon(props: MediaIconProps): react.JSX.Element;
+declare function FileCodeIcon(props: MediaIconProps): react.JSX.Element;
+declare function FileJsonIcon(props: MediaIconProps): react.JSX.Element;
+declare function FileSpreadsheetIcon(props: MediaIconProps): react.JSX.Element;
+declare function FileTextIcon(props: MediaIconProps): react.JSX.Element;
+declare function FileTypeIcon(props: MediaIconProps): react.JSX.Element;
+declare function FileVideoIcon(props: MediaIconProps): react.JSX.Element;
+declare function FolderIcon(props: MediaIconProps): react.JSX.Element;
+declare function FolderOpenIcon(props: MediaIconProps): react.JSX.Element;
+declare function ImageIcon(props: MediaIconProps): react.JSX.Element;
+declare function ImageOffIcon(props: MediaIconProps): react.JSX.Element;
+declare function MusicIcon(props: MediaIconProps): react.JSX.Element;
+declare function PackageBoxIcon(props: MediaIconProps): react.JSX.Element;
+declare function PenToolIcon(props: MediaIconProps): react.JSX.Element;
+declare function Share2Icon(props: MediaIconProps): react.JSX.Element;
+declare function SubtitlesIcon(props: MediaIconProps): react.JSX.Element;
+declare function UploadIcon(props: MediaIconProps): react.JSX.Element;
+declare function VideoIcon(props: MediaIconProps): react.JSX.Element;
+declare function VideoOffIcon(props: MediaIconProps): react.JSX.Element;
+declare function VolumeXIcon(props: MediaIconProps): react.JSX.Element;
+declare function XIcon(props: MediaIconProps): react.JSX.Element;
+declare function AlertCircleIcon(props: MediaIconProps): react.JSX.Element;
+declare function CheckCircle2Icon(props: MediaIconProps): react.JSX.Element;
+
+/**
+ * src/react/file-icon.tsx — icon tile for any file or folder.
+ *
+ * Verbatim port of matrx-frontend `components/core/FileIcon/FileIcon.tsx`
+ * with two seam inversions: the registry lookup is the package's own
+ * `getFileKindDetails` (`/core`), and the glyphs are the package's own
+ * inlined SVGs (C19 — no lucide peer).
+ */
+interface FileIconProps {
+    /** Either the filename (for files) or omitted for folders. */
+    fileName?: string | undefined;
+    /** Server MIME — when set, resolves audio/webm vs video/webm correctly. */
+    mimeType?: string | null | undefined;
+    /** If true, renders a folder icon. `open` picks the open-folder glyph. */
+    isFolder?: boolean | undefined;
+    open?: boolean | undefined;
+    /** Override the mapped color (useful for selected states). */
+    colorClass?: string | undefined;
+    className?: string | undefined;
+    size?: number | undefined;
+}
+declare function FileIcon({ fileName, mimeType, isFolder, open, colorClass, className, size, }: FileIconProps): react.JSX.Element;
+
+/**
+ * src/react/inline-media-ref.tsx — the canonical inline media renderer.
+ *
+ * Verbatim behavior port of matrx-frontend
+ * `features/files/components/inline/InlineMediaRef.tsx` (849 LOC, 116
+ * importers) with only the coupling seams inverted:
+ *
+ *   - URL resolution / public-CDN detection / auth-transport choice →
+ *     `MediaClient.resolve` (`transport: "blob"` is the private-pixels lane;
+ *     the Redux `useEnsureCloudFile`/`selectFileById` hydration lives behind
+ *     the client now)
+ *   - bearer-authenticated bytes → `MediaClient.getBlob` via `useMediaBlob`
+ *   - session-refresh retry → `MediaClient.recoverLoadError` via
+ *     `useMediaLoadRecovery`
+ *   - `next/image` → the injected `MediaHostPorts.ImageComponent` (plain
+ *     `<img>` default)
+ *   - audio output sink + exclusive-playback join → the injected
+ *     `MediaHostPorts.playbackSession` (inert default)
+ *   - lucide icons → the package's own inlined SVGs (C19)
+ *
+ * Pass a `MediaRef` (or a fileId / EXTERNAL public URL string), get back a
+ * correctly-sized `<img>` / `<video>` / `<audio>`. There is NO `src` prop —
+ * durable refs are the only identity this component accepts (law 2/3).
+ */
+
+type InlineMediaRefSize = "xs" | "sm" | "md" | "lg" | "xl" | "fill" | {
+    width: number;
+    height: number;
+};
+type InlineMediaRefFit = "cover" | "contain" | "fill";
+interface InlineMediaRefProps {
+    /**
+     * Reference to the media: a {@link MediaRef}, a bare fileId string, an
+     * EXTERNAL public URL string, or null/undefined (renders the fallback).
+     *
+     * Named `ref` as a CONTENT prop, exactly like the original (React 19
+     * treats ref as a regular prop on function components) — the 116 existing
+     * call sites pass `ref={mediaRef}` and must keep working at the C9 swap.
+     * Use `mediaElementRef` for imperative access to the DOM node.
+     */
+    ref?: MediaRefLike | null | undefined;
+    /** Square dimension preset or explicit width/height. Default `"md"` (64×64). */
+    size?: InlineMediaRefSize | undefined;
+    /** CSS object-fit. Default `"cover"`. */
+    fit?: InlineMediaRefFit | undefined;
+    /** Rendered when the ref can't be resolved to a URL at all. Default `"icon"`. */
+    fallback?: "icon" | "skeleton" | null | undefined;
+    /** Override the icon shown in `fallback="icon"`. */
+    fallbackIcon?: react__default.ReactNode | undefined;
+    /**
+     * Rendered when the URL *was* resolved but the media element failed to
+     * load. Default `"info"` — an informative destructive-tinted panel with
+     * URL + copy button + alt text; compacts to icon-only below ~64px.
+     */
+    errorFallback?: "info" | "icon" | "skeleton" | null | undefined;
+    /** Alt text for `<img>`. Defaults to "" (decorative). */
+    alt?: string | undefined;
+    /** Force the media element type. Default: infer from `mime_type` / resolution. */
+    as?: "img" | "video" | "audio" | undefined;
+    controls?: boolean | undefined;
+    autoPlay?: boolean | undefined;
+    loop?: boolean | undefined;
+    muted?: boolean | undefined;
+    playsInline?: boolean | undefined;
+    preload?: "none" | "metadata" | "auto" | undefined;
+    /** Space-separated native controls to hide — forwarded to `<video controlsList>`. */
+    controlsList?: string | undefined;
+    rounded?: "none" | "sm" | "md" | "lg" | "full" | undefined;
+    /** Click handler — wires up cursor + role + keyboard activation. */
+    onClick?: ((event: react__default.MouseEvent | react__default.KeyboardEvent) => void) | undefined;
+    /**
+     * Fires after the client's ONE recovery attempt is exhausted (or the
+     * failure was unrecoverable). The internal error fallback still renders
+     * unless `errorFallback={null}`.
+     */
+    onError?: ((event: react__default.SyntheticEvent<HTMLImageElement | HTMLVideoElement | HTMLAudioElement>) => void) | undefined;
+    onLoad?: ((event: react__default.SyntheticEvent<HTMLImageElement | HTMLVideoElement | HTMLAudioElement>) => void) | undefined;
+    /**
+     * Forwarded to the underlying element for imperative DOM access. Not a
+     * React `forwardRef` — pass any ref-like value here instead. When
+     * supplied, the ImageComponent branch is skipped so the ref attaches to
+     * the real DOM node.
+     */
+    mediaElementRef?: react__default.Ref<HTMLImageElement | HTMLVideoElement | HTMLAudioElement> | undefined;
+    /**
+     * Canvas pixel reads: `crossOrigin` consumers route through the
+     * bearer-authenticated blob lane unless the resolution is a CORS-safe
+     * public CDN URL.
+     */
+    crossOrigin?: "anonymous" | "use-credentials" | undefined;
+    border?: "none" | "subtle" | undefined;
+    className?: string | undefined;
+}
+declare function InlineMediaRef({ ref: mediaRef, size, fit, fallback, fallbackIcon, errorFallback, alt, as, controls, autoPlay, loop, muted, playsInline, preload, controlsList, rounded, onClick, onError, onLoad, mediaElementRef, crossOrigin, border, className, }: InlineMediaRefProps): react__default.JSX.Element | null;
+
+interface MediaThumbnailProps {
+    /** The file's durable ref (a MediaRef or bare fileId). */
+    mediaRef: MediaRefLike;
+    /** Display name — drives the icon fallback and alt text. */
+    fileName: string;
+    /** Server MIME, when known. */
+    mimeType?: string | null | undefined;
+    /** A known server-rendered thumbnail URL (`FileRecord.thumbnail_url`). */
+    thumbnailUrl?: string | null | undefined;
+    /** Pixel size for the icon fallback. Image/video fill their container. */
+    iconSize?: number | undefined;
+    /** Aspect ratio classes applied to the container, e.g. "aspect-[4/3]". */
+    className?: string | undefined;
+    /** Override the rounded corners of the container. */
+    rounded?: string | undefined;
+    /**
+     * Whether to fall back to a source-file URL when no rendered thumbnail is
+     * available. Disable in dense pickers to avoid a byte request per row.
+     */
+    allowSourceFallback?: boolean | undefined;
+}
+declare function MediaThumbnail({ mediaRef, fileName, mimeType, thumbnailUrl, iconSize, className, rounded, allowSourceFallback, }: MediaThumbnailProps): react.JSX.Element;
+
+/**
+ * src/react/use-media-dropzone.ts — headless drag + paste + picker intake.
+ *
+ * Replaces the original's `react-dropzone` dependency with native DOM events
+ * (the package's `/react` entry carries no UI-library deps). The behavior
+ * contract is the original FileUploadDropzone's: drag-over highlight, hidden
+ * input picker (`openPicker`), clipboard paste of images with a brief
+ * highlight pulse, an optional window event that opens the picker, and
+ * accept/maxSize filtering (UI-only; the server enforces its own caps).
+ */
+
+interface MediaDropzoneOptions {
+    /** Receives every accepted batch (drop, paste, or picker). */
+    onFiles: (files: File[]) => void;
+    /** Restrict accepted types, e.g. ["image/*", "application/pdf", ".csv"]. */
+    accept?: string[] | undefined;
+    /** Max size per file in bytes (UI-only filter). */
+    maxSize?: number | undefined;
+    /** Fires for files filtered out by accept/maxSize. */
+    onRejected?: ((rejected: Array<{
+        file: File;
+        reason: "type" | "size";
+    }>) => void) | undefined;
+    /** Enable clipboard paste (images only). Defaults true. */
+    enablePaste?: boolean | undefined;
+    /** Optional window event name that opens the native file picker. */
+    pickerEventName?: string | undefined;
+    disabled?: boolean | undefined;
+    multiple?: boolean | undefined;
+}
+interface MediaDropzoneState {
+    /** Spread onto the drop surface element. */
+    getRootProps: () => HTMLAttributes<HTMLElement>;
+    /** Spread onto a hidden `<input type="file">`. */
+    getInputProps: () => InputHTMLAttributes<HTMLInputElement> & {
+        ref: (node: HTMLInputElement | null) => void;
+    };
+    isDragActive: boolean;
+    /** Brief pulse after a successful clipboard paste. */
+    pasteHighlight: boolean;
+    openPicker: () => void;
+}
+declare function useMediaDropzone(options: MediaDropzoneOptions): MediaDropzoneState;
+
+interface FileUploadDropzoneActions {
+    openLocalPicker: () => void;
+    uploadFiles: (files: File[]) => Promise<void>;
+}
+interface FileUploadDropzoneProps {
+    /** Upload options forwarded to the client (visibility, folder, metadata…). */
+    uploadOptions?: MediaUploadOptions | undefined;
+    /** Restrict accepted types (e.g. ["image/*"]). */
+    accept?: string[] | undefined;
+    /** Max size per file in bytes (UI-only; server enforces its own cap). */
+    maxSize?: number | undefined;
+    /** Enable paste from clipboard (images only). Defaults true. */
+    enablePaste?: boolean | undefined;
+    /** Rendering mode. */
+    mode?: "overlay" | "inline" | undefined;
+    /** Children render inside the drop surface. */
+    children?: ReactNode | ((actions: FileUploadDropzoneActions) => ReactNode) | undefined;
+    className?: string | undefined;
+    /** Host-shaped acquisition sources (Drive, local folder, existing files…). */
+    actions?: ReactNode | undefined;
+    /** Fires the moment an upload batch STARTS (before any network completes). */
+    onUploadStart?: ((files: File[]) => void) | undefined;
+    onUploaded?: ((fileIds: string[]) => void) | undefined;
+    onError?: ((message: string) => void) | undefined;
+    /** Reveal a finished file from the upload tray. */
+    onOpenFile?: ((fileId: string) => void) | undefined;
+    /** Optional window event name that opens the native file picker. */
+    pickerEventName?: string | undefined;
+}
+declare function FileUploadDropzone({ uploadOptions, accept, maxSize, enablePaste, mode, children, className, actions, onUploadStart, onUploaded, onError, onOpenFile, pickerEventName, }: FileUploadDropzoneProps): react.JSX.Element;
+
+declare function formatFileSize(bytes: number): string;
+interface UploadProgressListProps {
+    uploads: MediaUploadEntry[];
+    /** Remove an entry from the tray (wire to `useMediaUpload().clearEntry`). */
+    onDismiss: (id: string) => void;
+    /**
+     * Reveal a finished file — opens the preview pane / scrolls the row.
+     * When omitted, the "Open" affordance is hidden.
+     */
+    onOpenFile?: ((fileId: string) => void) | undefined;
+    className?: string | undefined;
+}
+declare function UploadProgressListImpl({ uploads, onDismiss, onOpenFile, className, }: UploadProgressListProps): react.JSX.Element | null;
+declare const UploadProgressList: react.MemoExoticComponent<typeof UploadProgressListImpl>;
+
+interface MediaActionToolbarProps {
+    mediaRef: MediaRefLike | null | undefined;
+    fileName?: string | undefined;
+    alt?: string | undefined;
+    /** Which actions to render, in order. Default: share, download, copy, open. */
+    actions?: MediaActionKind[] | undefined;
+    /** Hide unavailable actions instead of rendering them disabled. */
+    hideUnavailable?: boolean | undefined;
+    className?: string | undefined;
+    buttonClassName?: string | undefined;
+}
+declare function MediaActionToolbar({ mediaRef, fileName, alt, actions, hideUnavailable, className, buttonClassName, }: MediaActionToolbarProps): react.JSX.Element | null;
+
+interface MediaLightboxProps {
+    open: boolean;
+    onClose: () => void;
+    mediaRef: MediaRefLike | null | undefined;
+    fileName?: string | undefined;
+    alt?: string | undefined;
+    /** Force the media element type (default: inferred from the resolution). */
+    as?: "img" | "video" | "audio" | undefined;
+    /** Toolbar actions to offer. Default: share, download, copy, open. */
+    actions?: MediaActionKind[] | undefined;
+    /** Hide unavailable toolbar actions instead of disabling them. */
+    hideUnavailableActions?: boolean | undefined;
+    /** Extra chrome rendered in the header row (left of the toolbar). */
+    headerExtra?: ReactNode | undefined;
+    className?: string | undefined;
+}
+declare function MediaLightbox({ open, onClose, mediaRef, fileName, alt, as, actions, hideUnavailableActions, headerExtra, className, }: MediaLightboxProps): react.JSX.Element | null;
+
+export { AlertCircleIcon, ArchiveIcon, BracesIcon, CheckCircle2Icon, CheckIcon, CodeIcon, CopyIcon, DatabaseIcon, DownloadIcon, ExternalLinkIcon, FileAudioIcon, FileCodeIcon, FileIcon, type FileIconProps, FileJsonIcon, FileSpreadsheetIcon, FileTextIcon, FileTypeIcon, FileUploadDropzone, type FileUploadDropzoneActions, type FileUploadDropzoneProps, FileVideoIcon, FolderIcon, FolderOpenIcon, ImageIcon, ImageOffIcon, InlineMediaRef, type InlineMediaRefFit, type InlineMediaRefProps, type InlineMediaRefSize, MediaActionToolbar, type MediaActionToolbarProps, type MediaDropzoneOptions, type MediaDropzoneState, type MediaIconProps, MediaLightbox, type MediaLightboxProps, MediaThumbnail, type MediaThumbnailProps, MusicIcon, PackageBoxIcon, PenToolIcon, Share2Icon, SubtitlesIcon, UploadIcon, UploadProgressList, type UploadProgressListProps, VideoIcon, VideoOffIcon, VolumeXIcon, XIcon, cn, formatFileSize, useMediaDropzone };