@ai-matrx/media 0.3.0 → 0.4.1

package/dist/viewers.d.cts

@@ -0,0 +1,289 @@
+import * as react from 'react';
+import { MediaRefLike } from './index.cjs';
+
+/**
+ * src/viewers/types.ts — the viewer vocabulary.
+ *
+ * A "viewer" is a full-pane rendering of ONE file: what a file-preview pane,
+ * a file tab, or a binary-file fallback in a code editor shows. It is the
+ * layer above `/react`'s inline media elements.
+ */
+
+/**
+ * The kinds the dispatcher understands. Ported from the matrx-frontend
+ * `PreviewKind` vocabulary so a host registry maps 1:1.
+ */
+type MediaViewerKind = "image" | "svg" | "video" | "audio" | "pdf" | "markdown" | "data" | "spreadsheet" | "code" | "office" | "html" | "text" | "generic";
+/**
+ * Where the viewer's bytes and display URL come from.
+ *
+ * - `ref` — the normal lane: identity in, everything through the MediaClient
+ *   (`resolve()` for the display URL, `getBlob()` for bytes).
+ * - `blob` — bytes the host ALREADY has (a code editor that downloaded the
+ *   file to decide it was binary). No MediaClient round-trip, and the URL is
+ *   an object URL, so load recovery is off by construction (law 3 is not
+ *   violated: a `blob:` URL is not a signed URL and never leaves the tab).
+ */
+type MediaViewerSource = {
+    kind: "ref";
+    ref: MediaRefLike;
+} | {
+    kind: "blob";
+    blob: Blob;
+    url: string;
+};
+/** Escape-hatch actions the generic card offers. */
+interface MediaViewerGenericOptions {
+    onDownload?: (() => void) | undefined;
+    onViewAsText?: (() => void) | undefined;
+    viewAsTextLabel?: string | undefined;
+    viewAsTextPrimary?: boolean | undefined;
+    viewAsTextBusy?: boolean | undefined;
+    message?: string | undefined;
+}
+/** Rendered-vs-source mode for the markup viewers (SVG, HTML). */
+type MediaViewerMarkupMode = "rendered" | "source";
+/** Device-width simulation for the HTML viewer. */
+type MediaViewerViewport = "auto" | "mobile" | "tablet" | "desktop";
+/**
+ * Optional external control of the markup viewers. When a host mounts its own
+ * control rail (matrx-frontend's `FileViewerControlsProvider`), it drives the
+ * viewer through these props and the viewer hides its built-in toolbar. When
+ * absent, the viewer owns the state and renders its own toolbar — the C23
+ * default: capable standalone, steerable when the host has a rail.
+ */
+interface MediaViewerMarkupControls {
+    mode?: MediaViewerMarkupMode | undefined;
+    onModeChange?: ((mode: MediaViewerMarkupMode) => void) | undefined;
+    viewport?: MediaViewerViewport | undefined;
+    /** Bump to force a clean re-mount of the rendered frame. */
+    reloadKey?: number | undefined;
+}
+/** The props EVERY viewer body (built-in or host-registered) receives. */
+interface MediaViewerProps {
+    source: MediaViewerSource;
+    fileName: string;
+    fileSize?: number | null | undefined;
+    mimeType?: string | null | undefined;
+    className?: string | undefined;
+    /** Max bytes read for text-shaped viewers. Defaults to 1MB. */
+    maxBytes?: number | undefined;
+    /** Controlled 1-based page, for paged engines (PDF). */
+    pageNumber?: number | undefined;
+    onPageChange?: ((pageNumber: number) => void) | undefined;
+    /** Passthroughs for the generic (no-viewer) card. */
+    generic?: MediaViewerGenericOptions | undefined;
+    /** External control of the markup viewers (SVG / HTML). */
+    markupControls?: MediaViewerMarkupControls | undefined;
+}
+/** A viewer body. Structural so a host component satisfies it with no import. */
+type MediaViewerComponent = (props: MediaViewerProps) => unknown;
+/**
+ * The code-highlighting seam. A syntax highlighter (Prism, Shiki, Monaco) is
+ * a multi-hundred-kilobyte browser-only engine — C8 says a headless consumer
+ * must never be forced to carry it, so the package ships the code viewer's
+ * CHROME and an honest, capable un-highlighted default, and a host registers
+ * the engine. `language` is the package's detected Prism-style language id.
+ */
+interface MediaCodeHighlighterProps {
+    code: string;
+    language: string;
+}
+type MediaCodeHighlighter = (props: MediaCodeHighlighterProps) => unknown;
+
+interface MediaFileViewerProps extends MediaViewerProps {
+    /**
+     * The kind to render. Omit to let the package derive it from the file name
+     * and MIME type (`getPreviewKind`).
+     */
+    previewKind?: MediaViewerKind | undefined;
+}
+declare function MediaFileViewer({ previewKind, ...props }: MediaFileViewerProps): react.JSX.Element;
+
+/**
+ * src/viewers/registry.ts — the heavy-engine seam.
+ *
+ * The package ships working bodies for every viewer kind it can render with
+ * DOM primitives alone (text, code chrome, svg, html, generic). The kinds
+ * whose rendering IS a multi-megabyte browser-only engine — PDF.js, a
+ * Markdown/KaTeX stack, SheetJS, a server-side Office extractor — ride this
+ * seam instead (C8 + the diff-package Monaco precedent): a host registers the
+ * engine once, and until it does, the dispatcher renders an ANNOUNCING
+ * default that names the missing engine and still offers download/open. A
+ * dead pane is never an outcome.
+ *
+ * MODULE-LEVEL MUTABLE STATE IS BANNED (the dual ESM/CJS bundle rule): with
+ * `splitting: false` and two formats, each loader graph instantiates its own
+ * copy of this module, so a plain module-scope Map would silently split the
+ * registry — a host registering through the CJS graph would be invisible to a
+ * component rendered from the ESM graph. The maps therefore live on
+ * `globalThis` under `Symbol.for` slots, and the tarball canary proves a
+ * registration made in one graph is visible from the other.
+ */
+
+/**
+ * Register the viewer body for a kind. Registering a kind the package already
+ * renders REPLACES the built-in — that is the sanctioned host override (a
+ * feature-specific domain viewer implementing the same contract).
+ *
+ * Returns an unregister function so a test or a hot-reloading host can undo it.
+ */
+declare function registerMediaViewer(kind: MediaViewerKind, viewer: MediaViewerComponent): () => void;
+/** The registered viewer for a kind, or `null` when nothing is registered. */
+declare function getMediaViewer(kind: MediaViewerKind): MediaViewerComponent | null;
+/** Every kind a host has registered — for diagnostics and tests. */
+declare function registeredMediaViewerKinds(): MediaViewerKind[];
+/**
+ * Register the syntax-highlighting engine for the built-in code viewer.
+ * Without one the code viewer still renders — monospace, line-numbered,
+ * copyable, truncation-honest — it simply is not colored.
+ */
+declare function registerMediaCodeHighlighter(highlighter: MediaCodeHighlighter): () => void;
+declare function getMediaCodeHighlighter(): MediaCodeHighlighter | null;
+
+declare function TextViewer({ source, className, maxBytes, }: MediaViewerProps): react.JSX.Element;
+
+/** Filename → language id. Exported: hosts registering an engine reuse it. */
+declare function detectCodeLanguage(fileName: string): string;
+declare function CodeViewer({ source, fileName, className, maxBytes, }: MediaViewerProps): react.JSX.Element;
+
+declare function SvgViewer(props: MediaViewerProps): react.JSX.Element;
+
+declare function HtmlViewer(props: MediaViewerProps): react.JSX.Element;
+
+declare function GenericViewer({ fileName, fileSize, generic, className, }: MediaViewerProps): react.JSX.Element;
+
+declare function MediaViewerUnavailable({ kind, ...props }: MediaViewerProps & {
+    kind: MediaViewerKind;
+}): react.JSX.Element;
+
+/**
+ * src/viewers/preview-kind.ts — filename/MIME → viewer kind.
+ *
+ * The DEFAULT resolution, derived from the package's own file-kind registry
+ * (`getFileKindDetails`) so a fresh app gets correct dispatch with zero setup.
+ * A host with a richer registry of its own — matrx-frontend's `FILE_TYPES`
+ * carries preview/thumbnail/size-cap columns this package deliberately does
+ * not absorb (C8) — passes `previewKind` explicitly and this is never called.
+ */
+
+declare function getPreviewKind(fileName: string, mimeType?: string | null): MediaViewerKind;
+
+/**
+ * src/viewers/chrome.tsx — the shared viewer chrome.
+ *
+ * The five absorbed matrx-frontend previewers each hand-rolled the same
+ * error card, the same skeleton, and the same copy button. One copy here;
+ * one place to make them good.
+ */
+/** The uniform loading bar every viewer shows while bytes are in flight. */
+declare function ViewerSkeleton({ className, tone, }: {
+    className?: string | undefined;
+    tone?: "muted" | "plain" | undefined;
+}): react.JSX.Element;
+/**
+ * The honest failure card. It shows the REAL underlying message (HTTP
+ * 401/403/404/network) rather than a generic "Preview failed" — the original
+ * previewers' deliberate choice, kept: a user who can see the status can act
+ * on it, and a support thread starts with a fact instead of a shrug.
+ */
+declare function ViewerError({ title, message, hint, className, }: {
+    title?: string | undefined;
+    message?: string | null | undefined;
+    hint?: string | undefined;
+    className?: string | undefined;
+}): react.JSX.Element;
+/**
+ * Copy-to-clipboard button with the settled-state flip. Swallows the
+ * clipboard rejection that non-secure contexts always throw — a failed copy
+ * is not an error worth a card, and the un-flipped button IS the signal.
+ */
+declare function ViewerCopyButton({ text, className, }: {
+    text: string | null;
+    className?: string | undefined;
+}): react.JSX.Element;
+/** The strip above a text-shaped viewer: status on the left, copy on the right. */
+declare function ViewerToolbar({ children, className, }: {
+    children?: React.ReactNode;
+    className?: string | undefined;
+}): react.JSX.Element;
+
+/**
+ * src/viewers/transparency-grid.ts — the alpha-channel checkerboard.
+ *
+ * Ships as inline style rather than a utility class: the matrx-frontend
+ * originals used two different mechanisms for the same thing (an inline
+ * gradient stack in ImagePreview, a `bg-checkerboard` utility in SvgPreview),
+ * and a utility class is exactly the kind of host-owned dependency C26 bans a
+ * package component from assuming. Sized in CSS pixels so the pattern reads
+ * the same at any zoom.
+ */
+declare const TRANSPARENCY_GRID_STYLE: {
+    backgroundImage: string;
+    backgroundSize: string;
+    backgroundPosition: string;
+};
+
+/**
+ * src/viewers/use-viewer-bytes.ts — the ONE byte/text/URL machinery every
+ * viewer body shares.
+ *
+ * Four separate matrx-frontend previewers (Text, Code, the SVG source view,
+ * the HTML source view) each carried their own copy of "read the blob, cap it
+ * at N bytes, mark it truncated, surface the REAL backend error verbatim,
+ * cancel on unmount". Four copies is four places to drift; C22 says that
+ * machinery lives in the package exactly once.
+ */
+
+interface ViewerBytesState {
+    blob: Blob | null;
+    loading: boolean;
+    /** The real underlying message (HTTP 401/403/404/network) — never generic. */
+    error: string | null;
+}
+/**
+ * Bytes for a viewer source. A `blob` source is already resolved; a `ref`
+ * source goes through `MediaClient.getBlob` (which is also what emits the
+ * terminal-failure diagnostics — see `useMediaBlob`).
+ *
+ * `useMediaBlob` is called UNCONDITIONALLY (with `null` for blob sources) so
+ * the hook order never changes with the source shape.
+ */
+declare function useViewerBytes(source: MediaViewerSource): ViewerBytesState;
+interface ViewerTextState {
+    text: string | null;
+    loading: boolean;
+    error: string | null;
+    /** True when the file exceeded `maxBytes` and only the head was read. */
+    truncated: boolean;
+}
+/**
+ * Bytes → text, capped. The cap is not a nicety: a 500MB log file decoded in
+ * full takes the tab down, which is how the original previewers were written
+ * and why the cap must travel with the package rather than be re-derived.
+ */
+declare function useViewerText(source: MediaViewerSource, maxBytes?: number): ViewerTextState;
+interface ViewerDisplayUrlState {
+    /**
+     * The URL a media element may bind. Durable by construction: it is either
+     * a `MediaClient.resolve()` result or the host's own object URL.
+     */
+    url: string | null;
+    /**
+     * Whether the client's ONE retry policy can rescue a load failure. False
+     * for object URLs and for resolutions the client marked unrecoverable
+     * (foreign links) — a session refresh cannot resurrect someone else's URL.
+     */
+    recoverable: boolean;
+    /** `resolve()` refused the ref — render the honest unavailable state. */
+    unavailable: boolean;
+    loading: boolean;
+}
+/**
+ * The display URL for a viewer source. Law 2: even for a `ref` carrying a
+ * caller-supplied URL, resolution goes through the client — the package never
+ * trusts a string it was handed.
+ */
+declare function useViewerDisplayUrl(source: MediaViewerSource): ViewerDisplayUrlState;
+
+export { CodeViewer, GenericViewer, HtmlViewer, type MediaCodeHighlighter, type MediaCodeHighlighterProps, MediaFileViewer, type MediaFileViewerProps, type MediaViewerComponent, type MediaViewerGenericOptions, type MediaViewerKind, type MediaViewerMarkupControls, type MediaViewerMarkupMode, type MediaViewerProps, type MediaViewerSource, MediaViewerUnavailable, type MediaViewerViewport, SvgViewer, TRANSPARENCY_GRID_STYLE, TextViewer, type ViewerBytesState, ViewerCopyButton, type ViewerDisplayUrlState, ViewerError, ViewerSkeleton, type ViewerTextState, ViewerToolbar, detectCodeLanguage, getMediaCodeHighlighter, getMediaViewer, getPreviewKind, registerMediaCodeHighlighter, registerMediaViewer, registeredMediaViewerKinds, useViewerBytes, useViewerDisplayUrl, useViewerText };

package/dist/viewers.d.ts

@@ -0,0 +1,289 @@
+import * as react from 'react';
+import { MediaRefLike } from './index.js';
+
+/**
+ * src/viewers/types.ts — the viewer vocabulary.
+ *
+ * A "viewer" is a full-pane rendering of ONE file: what a file-preview pane,
+ * a file tab, or a binary-file fallback in a code editor shows. It is the
+ * layer above `/react`'s inline media elements.
+ */
+
+/**
+ * The kinds the dispatcher understands. Ported from the matrx-frontend
+ * `PreviewKind` vocabulary so a host registry maps 1:1.
+ */
+type MediaViewerKind = "image" | "svg" | "video" | "audio" | "pdf" | "markdown" | "data" | "spreadsheet" | "code" | "office" | "html" | "text" | "generic";
+/**
+ * Where the viewer's bytes and display URL come from.
+ *
+ * - `ref` — the normal lane: identity in, everything through the MediaClient
+ *   (`resolve()` for the display URL, `getBlob()` for bytes).
+ * - `blob` — bytes the host ALREADY has (a code editor that downloaded the
+ *   file to decide it was binary). No MediaClient round-trip, and the URL is
+ *   an object URL, so load recovery is off by construction (law 3 is not
+ *   violated: a `blob:` URL is not a signed URL and never leaves the tab).
+ */
+type MediaViewerSource = {
+    kind: "ref";
+    ref: MediaRefLike;
+} | {
+    kind: "blob";
+    blob: Blob;
+    url: string;
+};
+/** Escape-hatch actions the generic card offers. */
+interface MediaViewerGenericOptions {
+    onDownload?: (() => void) | undefined;
+    onViewAsText?: (() => void) | undefined;
+    viewAsTextLabel?: string | undefined;
+    viewAsTextPrimary?: boolean | undefined;
+    viewAsTextBusy?: boolean | undefined;
+    message?: string | undefined;
+}
+/** Rendered-vs-source mode for the markup viewers (SVG, HTML). */
+type MediaViewerMarkupMode = "rendered" | "source";
+/** Device-width simulation for the HTML viewer. */
+type MediaViewerViewport = "auto" | "mobile" | "tablet" | "desktop";
+/**
+ * Optional external control of the markup viewers. When a host mounts its own
+ * control rail (matrx-frontend's `FileViewerControlsProvider`), it drives the
+ * viewer through these props and the viewer hides its built-in toolbar. When
+ * absent, the viewer owns the state and renders its own toolbar — the C23
+ * default: capable standalone, steerable when the host has a rail.
+ */
+interface MediaViewerMarkupControls {
+    mode?: MediaViewerMarkupMode | undefined;
+    onModeChange?: ((mode: MediaViewerMarkupMode) => void) | undefined;
+    viewport?: MediaViewerViewport | undefined;
+    /** Bump to force a clean re-mount of the rendered frame. */
+    reloadKey?: number | undefined;
+}
+/** The props EVERY viewer body (built-in or host-registered) receives. */
+interface MediaViewerProps {
+    source: MediaViewerSource;
+    fileName: string;
+    fileSize?: number | null | undefined;
+    mimeType?: string | null | undefined;
+    className?: string | undefined;
+    /** Max bytes read for text-shaped viewers. Defaults to 1MB. */
+    maxBytes?: number | undefined;
+    /** Controlled 1-based page, for paged engines (PDF). */
+    pageNumber?: number | undefined;
+    onPageChange?: ((pageNumber: number) => void) | undefined;
+    /** Passthroughs for the generic (no-viewer) card. */
+    generic?: MediaViewerGenericOptions | undefined;
+    /** External control of the markup viewers (SVG / HTML). */
+    markupControls?: MediaViewerMarkupControls | undefined;
+}
+/** A viewer body. Structural so a host component satisfies it with no import. */
+type MediaViewerComponent = (props: MediaViewerProps) => unknown;
+/**
+ * The code-highlighting seam. A syntax highlighter (Prism, Shiki, Monaco) is
+ * a multi-hundred-kilobyte browser-only engine — C8 says a headless consumer
+ * must never be forced to carry it, so the package ships the code viewer's
+ * CHROME and an honest, capable un-highlighted default, and a host registers
+ * the engine. `language` is the package's detected Prism-style language id.
+ */
+interface MediaCodeHighlighterProps {
+    code: string;
+    language: string;
+}
+type MediaCodeHighlighter = (props: MediaCodeHighlighterProps) => unknown;
+
+interface MediaFileViewerProps extends MediaViewerProps {
+    /**
+     * The kind to render. Omit to let the package derive it from the file name
+     * and MIME type (`getPreviewKind`).
+     */
+    previewKind?: MediaViewerKind | undefined;
+}
+declare function MediaFileViewer({ previewKind, ...props }: MediaFileViewerProps): react.JSX.Element;
+
+/**
+ * src/viewers/registry.ts — the heavy-engine seam.
+ *
+ * The package ships working bodies for every viewer kind it can render with
+ * DOM primitives alone (text, code chrome, svg, html, generic). The kinds
+ * whose rendering IS a multi-megabyte browser-only engine — PDF.js, a
+ * Markdown/KaTeX stack, SheetJS, a server-side Office extractor — ride this
+ * seam instead (C8 + the diff-package Monaco precedent): a host registers the
+ * engine once, and until it does, the dispatcher renders an ANNOUNCING
+ * default that names the missing engine and still offers download/open. A
+ * dead pane is never an outcome.
+ *
+ * MODULE-LEVEL MUTABLE STATE IS BANNED (the dual ESM/CJS bundle rule): with
+ * `splitting: false` and two formats, each loader graph instantiates its own
+ * copy of this module, so a plain module-scope Map would silently split the
+ * registry — a host registering through the CJS graph would be invisible to a
+ * component rendered from the ESM graph. The maps therefore live on
+ * `globalThis` under `Symbol.for` slots, and the tarball canary proves a
+ * registration made in one graph is visible from the other.
+ */
+
+/**
+ * Register the viewer body for a kind. Registering a kind the package already
+ * renders REPLACES the built-in — that is the sanctioned host override (a
+ * feature-specific domain viewer implementing the same contract).
+ *
+ * Returns an unregister function so a test or a hot-reloading host can undo it.
+ */
+declare function registerMediaViewer(kind: MediaViewerKind, viewer: MediaViewerComponent): () => void;
+/** The registered viewer for a kind, or `null` when nothing is registered. */
+declare function getMediaViewer(kind: MediaViewerKind): MediaViewerComponent | null;
+/** Every kind a host has registered — for diagnostics and tests. */
+declare function registeredMediaViewerKinds(): MediaViewerKind[];
+/**
+ * Register the syntax-highlighting engine for the built-in code viewer.
+ * Without one the code viewer still renders — monospace, line-numbered,
+ * copyable, truncation-honest — it simply is not colored.
+ */
+declare function registerMediaCodeHighlighter(highlighter: MediaCodeHighlighter): () => void;
+declare function getMediaCodeHighlighter(): MediaCodeHighlighter | null;
+
+declare function TextViewer({ source, className, maxBytes, }: MediaViewerProps): react.JSX.Element;
+
+/** Filename → language id. Exported: hosts registering an engine reuse it. */
+declare function detectCodeLanguage(fileName: string): string;
+declare function CodeViewer({ source, fileName, className, maxBytes, }: MediaViewerProps): react.JSX.Element;
+
+declare function SvgViewer(props: MediaViewerProps): react.JSX.Element;
+
+declare function HtmlViewer(props: MediaViewerProps): react.JSX.Element;
+
+declare function GenericViewer({ fileName, fileSize, generic, className, }: MediaViewerProps): react.JSX.Element;
+
+declare function MediaViewerUnavailable({ kind, ...props }: MediaViewerProps & {
+    kind: MediaViewerKind;
+}): react.JSX.Element;
+
+/**
+ * src/viewers/preview-kind.ts — filename/MIME → viewer kind.
+ *
+ * The DEFAULT resolution, derived from the package's own file-kind registry
+ * (`getFileKindDetails`) so a fresh app gets correct dispatch with zero setup.
+ * A host with a richer registry of its own — matrx-frontend's `FILE_TYPES`
+ * carries preview/thumbnail/size-cap columns this package deliberately does
+ * not absorb (C8) — passes `previewKind` explicitly and this is never called.
+ */
+
+declare function getPreviewKind(fileName: string, mimeType?: string | null): MediaViewerKind;
+
+/**
+ * src/viewers/chrome.tsx — the shared viewer chrome.
+ *
+ * The five absorbed matrx-frontend previewers each hand-rolled the same
+ * error card, the same skeleton, and the same copy button. One copy here;
+ * one place to make them good.
+ */
+/** The uniform loading bar every viewer shows while bytes are in flight. */
+declare function ViewerSkeleton({ className, tone, }: {
+    className?: string | undefined;
+    tone?: "muted" | "plain" | undefined;
+}): react.JSX.Element;
+/**
+ * The honest failure card. It shows the REAL underlying message (HTTP
+ * 401/403/404/network) rather than a generic "Preview failed" — the original
+ * previewers' deliberate choice, kept: a user who can see the status can act
+ * on it, and a support thread starts with a fact instead of a shrug.
+ */
+declare function ViewerError({ title, message, hint, className, }: {
+    title?: string | undefined;
+    message?: string | null | undefined;
+    hint?: string | undefined;
+    className?: string | undefined;
+}): react.JSX.Element;
+/**
+ * Copy-to-clipboard button with the settled-state flip. Swallows the
+ * clipboard rejection that non-secure contexts always throw — a failed copy
+ * is not an error worth a card, and the un-flipped button IS the signal.
+ */
+declare function ViewerCopyButton({ text, className, }: {
+    text: string | null;
+    className?: string | undefined;
+}): react.JSX.Element;
+/** The strip above a text-shaped viewer: status on the left, copy on the right. */
+declare function ViewerToolbar({ children, className, }: {
+    children?: React.ReactNode;
+    className?: string | undefined;
+}): react.JSX.Element;
+
+/**
+ * src/viewers/transparency-grid.ts — the alpha-channel checkerboard.
+ *
+ * Ships as inline style rather than a utility class: the matrx-frontend
+ * originals used two different mechanisms for the same thing (an inline
+ * gradient stack in ImagePreview, a `bg-checkerboard` utility in SvgPreview),
+ * and a utility class is exactly the kind of host-owned dependency C26 bans a
+ * package component from assuming. Sized in CSS pixels so the pattern reads
+ * the same at any zoom.
+ */
+declare const TRANSPARENCY_GRID_STYLE: {
+    backgroundImage: string;
+    backgroundSize: string;
+    backgroundPosition: string;
+};
+
+/**
+ * src/viewers/use-viewer-bytes.ts — the ONE byte/text/URL machinery every
+ * viewer body shares.
+ *
+ * Four separate matrx-frontend previewers (Text, Code, the SVG source view,
+ * the HTML source view) each carried their own copy of "read the blob, cap it
+ * at N bytes, mark it truncated, surface the REAL backend error verbatim,
+ * cancel on unmount". Four copies is four places to drift; C22 says that
+ * machinery lives in the package exactly once.
+ */
+
+interface ViewerBytesState {
+    blob: Blob | null;
+    loading: boolean;
+    /** The real underlying message (HTTP 401/403/404/network) — never generic. */
+    error: string | null;
+}
+/**
+ * Bytes for a viewer source. A `blob` source is already resolved; a `ref`
+ * source goes through `MediaClient.getBlob` (which is also what emits the
+ * terminal-failure diagnostics — see `useMediaBlob`).
+ *
+ * `useMediaBlob` is called UNCONDITIONALLY (with `null` for blob sources) so
+ * the hook order never changes with the source shape.
+ */
+declare function useViewerBytes(source: MediaViewerSource): ViewerBytesState;
+interface ViewerTextState {
+    text: string | null;
+    loading: boolean;
+    error: string | null;
+    /** True when the file exceeded `maxBytes` and only the head was read. */
+    truncated: boolean;
+}
+/**
+ * Bytes → text, capped. The cap is not a nicety: a 500MB log file decoded in
+ * full takes the tab down, which is how the original previewers were written
+ * and why the cap must travel with the package rather than be re-derived.
+ */
+declare function useViewerText(source: MediaViewerSource, maxBytes?: number): ViewerTextState;
+interface ViewerDisplayUrlState {
+    /**
+     * The URL a media element may bind. Durable by construction: it is either
+     * a `MediaClient.resolve()` result or the host's own object URL.
+     */
+    url: string | null;
+    /**
+     * Whether the client's ONE retry policy can rescue a load failure. False
+     * for object URLs and for resolutions the client marked unrecoverable
+     * (foreign links) — a session refresh cannot resurrect someone else's URL.
+     */
+    recoverable: boolean;
+    /** `resolve()` refused the ref — render the honest unavailable state. */
+    unavailable: boolean;
+    loading: boolean;
+}
+/**
+ * The display URL for a viewer source. Law 2: even for a `ref` carrying a
+ * caller-supplied URL, resolution goes through the client — the package never
+ * trusts a string it was handed.
+ */
+declare function useViewerDisplayUrl(source: MediaViewerSource): ViewerDisplayUrlState;
+
+export { CodeViewer, GenericViewer, HtmlViewer, type MediaCodeHighlighter, type MediaCodeHighlighterProps, MediaFileViewer, type MediaFileViewerProps, type MediaViewerComponent, type MediaViewerGenericOptions, type MediaViewerKind, type MediaViewerMarkupControls, type MediaViewerMarkupMode, type MediaViewerProps, type MediaViewerSource, MediaViewerUnavailable, type MediaViewerViewport, SvgViewer, TRANSPARENCY_GRID_STYLE, TextViewer, type ViewerBytesState, ViewerCopyButton, type ViewerDisplayUrlState, ViewerError, ViewerSkeleton, type ViewerTextState, ViewerToolbar, detectCodeLanguage, getMediaCodeHighlighter, getMediaViewer, getPreviewKind, registerMediaCodeHighlighter, registerMediaViewer, registeredMediaViewerKinds, useViewerBytes, useViewerDisplayUrl, useViewerText };