@ai-matrx/media 0.8.0 → 0.9.1

package/dist/files/engine/utils/file-types.d.ts

@@ -0,0 +1,243 @@
+/**
+ * features/files/utils/file-types.ts
+ *
+ * THE SINGLE SOURCE OF TRUTH for cloud-files type capabilities.
+ *
+ * If you need to:
+ *   - Add support for a new file type
+ *   - Change which previewer a type uses
+ *   - Change which icon / color a type renders with
+ *   - Change whether a type renders a real thumbnail or a fallback icon
+ *   - Add or remove a thumbnail strategy
+ *   - Change a size cap for a particular kind
+ *
+ * → edit THIS file. Nothing else in the cloud-files feature should
+ * encode this knowledge.
+ *
+ * The supporting modules (`mime.ts`, `icon-map.ts`,
+ * `preview-capabilities.ts`) are thin wrappers that read from this
+ * registry and exist only for backwards-compat with older imports.
+ *
+ * ─────────────────────────────────────────────────────────────────────
+ * Structure
+ * ─────────────────────────────────────────────────────────────────────
+ *
+ *   FILE_TYPES is an array of declarative entries. Each entry says:
+ *
+ *     - which extensions match it
+ *     - the canonical MIME type (used as a fallback when the server
+ *       didn't send one and to canonicalize between the dozens of
+ *       legacy aliases the web has accumulated)
+ *     - which preview component to use
+ *     - which thumbnail strategy to use in grid / list views
+ *     - the icon + color tokens that drive the iconography
+ *     - a human-friendly display name (e.g. "PDF Document" vs "pdf")
+ *     - any size cap that overrides the global preview cap
+ *
+ * Mime-first override: when the browser knows a MIME (e.g. it set
+ * `image/avif` even though we don't have `.avif` in the extension
+ * table), the wrapper helpers fall back to MIME-prefix matching for
+ * `image/*`, `video/*`, `audio/*`, and `application/pdf`, so adding a
+ * brand-new image format never requires more than a one-line entry.
+ */
+import { type LucideIcon } from "lucide-react";
+/** Top-level grouping. Drives sidebar filters and color rhythm. */
+export type FileCategory = "CODE" | "DOCUMENT" | "AUDIO" | "IMAGE" | "VIDEO" | "ARCHIVE" | "DATA" | "NOTEBOOK" | "SUBTITLES" | "EMAIL" | "EBOOK" | "MODEL_3D" | "UNKNOWN" | "FOLDER";
+/** Which previewer should render this kind. `generic` means "no preview".
+ *
+ * `svg` is split out from `image` on purpose: SVG is text-shaped (XML), so
+ * it has a dedicated previewer (`SvgPreview` — renders with a transparency
+ * grid and lets the user toggle to the raw markup) AND is editable in the
+ * standard Monaco inline editor with XML syntax highlighting. Routing it
+ * through `image` would hide the editor handoff and the source-view toggle.
+ */
+export type PreviewKind = "code" | "image" | "svg" | "html" | "audio" | "video" | "pdf" | "text" | "markdown" | "data" | "spreadsheet" | "office" | "generic";
+/**
+ * Strategy hint for the small inline thumbnail rendered in grid / list views.
+ *
+ * Phase 1b note: server-rendered thumbnails are now **universal** —
+ * every uploaded file has `FileRecord.thumbnail_url` populated (image,
+ * PDF page 1, video frame, audio waveform, or mime-family icon for
+ * unknown). `MediaThumbnail` reads `file.thumbnailUrl` first regardless
+ * of the strategy below; this enum now only controls the "live render"
+ * fallback for the brief window between upload and variant render.
+ *
+ *   "image"          — `<img src={masterCdnUrl}>` fallback when the
+ *                      backend variant hasn't finished rendering yet.
+ *   "video-poster"   — `<video preload="metadata">` fallback for the
+ *                      same window.
+ *   "pdf-firstpage"  — historic; Phase 1c now ships `page1_url` via
+ *                      the variants store. The grid path uses
+ *                      `file.thumbnailUrl`; full-page detail views can
+ *                      bind `Asset.variants["page1_url"].url`.
+ *   "backend-thumb"  — historic; now equivalent to `icon` for the live
+ *                      render fallback because the universal pipeline
+ *                      handles every backend-thumb case automatically.
+ *   "icon"           — no live render fallback. The `file.thumbnailUrl`
+ *                      lookup (or icon) is the only source.
+ */
+export type ThumbnailStrategy = "image" | "video-poster" | "pdf-firstpage" | "backend-thumb" | "icon";
+/**
+ * One row in the registry. Most fields are static; the `extensions`,
+ * `aliases`, `aliasPrefixes`, and `mime` fields are the lookup keys.
+ */
+export interface FileTypeEntry {
+    /** Extensions (lowercased, no dot) that map to this entry. First wins. */
+    extensions: readonly string[];
+    /**
+     * Exact filenames (matched as-is, then case-insensitively) that resolve to
+     * this entry — covers the universe of "no extension OR purely dotfile"
+     * text-config files. e.g. `["Dockerfile", ".dockerignore"]`.
+     */
+    aliases?: readonly string[];
+    /**
+     * Filename prefixes that resolve to this entry. Matched after exact
+     * extensions / aliases fail. Useful for `.env*` style variants
+     * (`.env.local`, `.env.production`, ...). Compared case-insensitively.
+     */
+    aliasPrefixes?: readonly string[];
+    /** Canonical MIME. Used to fill `mime_type` when the server didn't send one. */
+    mime: string;
+    category: FileCategory;
+    /** Specific name within the category, e.g. "PYTHON", "MP3". UPPERCASE. */
+    subCategory: string;
+    /** Human-friendly name shown in tooltips / "What can I preview?" lists. */
+    displayName: string;
+    previewKind: PreviewKind;
+    thumbnailStrategy: ThumbnailStrategy;
+    /** Tailwind text color token, e.g. `text-emerald-500`. */
+    color: string;
+    icon: LucideIcon;
+    /** Override the global 10MB preview cap if the previewer can stream. */
+    previewSizeCapOverride?: number | null;
+}
+/** What a caller actually needs to render any given file. */
+export interface FileTypeDetails {
+    category: FileCategory;
+    subCategory: string;
+    displayName: string;
+    previewKind: PreviewKind;
+    thumbnailStrategy: ThumbnailStrategy;
+    color: string;
+    icon: LucideIcon;
+    /** Convenience — true when previewKind !== "generic". */
+    canPreview: boolean;
+    /** Convenience — null = use the global cap. */
+    previewSizeCapOverride: number | null;
+    /** The canonical MIME for the resolved type. */
+    mime: string;
+}
+/** Global default preview cap. Bigger files render a "too large" message. */
+export declare const MAX_INLINE_PREVIEW_BYTES: number;
+/**
+ * The registry. Order matters only when an extension belongs to multiple
+ * entries — the first match wins. In practice every extension is unique.
+ *
+ * Adding a new file type:
+ *   1. Append a new entry.
+ *   2. If the previewKind is something new (not in `PreviewKind`), add it
+ *      to that union AND register a previewer in
+ *      `components/core/FilePreview/FilePreview.tsx`.
+ *   3. If the thumbnail strategy is new, extend `ThumbnailStrategy` and
+ *      handle it in `MediaThumbnail`.
+ *
+ * That's it. No edits to `mime.ts`, `icon-map.ts`, etc.
+ */
+export declare const FILE_TYPES: readonly FileTypeEntry[];
+/** Look up details by file name (basename / alias / prefix / extension match). */
+export declare function getFileTypeDetails(filename: string): FileTypeDetails;
+/**
+ * Same as `getFileTypeDetails` but never falls through to UNKNOWN — used
+ * by the binary viewer's "View as text" override and any caller that has
+ * already decided "treat this as text, no matter what."
+ */
+export declare function getAssumedTextDetails(filename: string): FileTypeDetails;
+/** True when the filename is recognized as text-bearing without sniffing bytes. */
+export declare function isLikelyTextFilename(filename: string): boolean;
+/** Folder details — used by sidebar + tree rendering. */
+export declare function getFolderTypeDetails(open?: boolean): FileTypeDetails;
+/** Canonical MIME for an extension (or `application/octet-stream`). */
+export declare function mimeFromFilename(filename: string): string;
+/**
+ * Resolve a final MIME, preferring the server-supplied value when it's
+ * meaningful, otherwise falling back to the extension table.
+ *
+ * Parameters are stripped so `audio/webm;codecs=opus` resolves like
+ * `audio/webm` — required for BY_MIME lookup and audio/video disambiguation
+ * on `.webm` containers (MediaRecorder speech captures).
+ */
+export declare function resolveMime(explicit: string | null | undefined, filename: string): string;
+/**
+ * Given a (filename, mime, size) tuple, return the full preview profile —
+ * what to render at full size, what to render in a grid thumbnail, whether
+ * either is allowed at the file's current byte size, and the resolved MIME.
+ *
+ * This is THE function components should call. `getPreviewCapability` and
+ * `useFileTypeDetails` are thin views on top.
+ */
+export interface FilePreviewProfile {
+    details: FileTypeDetails;
+    /** Effective `previewKind` after MIME-prefix override. */
+    previewKind: PreviewKind;
+    /** True when the type is renderable AND the byte size fits the cap. */
+    canPreview: boolean;
+    /** False = file is too big for inline preview; offer download instead. */
+    sizeOk: boolean;
+    /** The cap that was effectively applied (in bytes). */
+    effectiveSizeCap: number;
+    /** True iff the registry says this file should render a real thumbnail. */
+    thumbnailStrategy: ThumbnailStrategy;
+    /** Resolved canonical MIME. */
+    mime: string;
+}
+export declare function getFilePreviewProfile(fileName: string, mimeType: string | null, fileSize: number | null): FilePreviewProfile;
+export declare function isTextMime(mime: string): boolean;
+export declare function isImageMime(mime: string): boolean;
+/** Image bytes evergreen browsers can decode directly through `<img>`. */
+export declare function isBrowserRenderableImageMime(mime: string): boolean;
+export declare function isVideoMime(mime: string): boolean;
+export declare function isAudioMime(mime: string): boolean;
+export declare function isPdfMime(mime: string): boolean;
+/**
+ * Result of `sniffTextBytes`. We split "definitely text" from "looks text-y
+ * but we're not sure" so the UI can pick a different default action:
+ *
+ *   - `confidence === "high"` — safe to render in Monaco automatically.
+ *   - `confidence === "medium"` — probably text; offer a button.
+ *   - `confidence === "low"` — almost certainly binary; only show on
+ *     manual override.
+ */
+export interface TextSniffResult {
+    isText: boolean;
+    confidence: "high" | "medium" | "low";
+    reason: string;
+}
+/**
+ * Heuristic byte-level text detector. Inspects the first ~4KB of the
+ * sample and answers "could this be displayed as text?". Designed to be
+ * permissive — false positives are recoverable (the user sees garbage
+ * and closes the tab), while false negatives are exactly the bug we're
+ * fighting (.bashrc, authorized_keys, etc. being declared "binary").
+ *
+ * Rules, in order:
+ *   1. Empty bytes → text (an empty file is fine to open in Monaco).
+ *   2. UTF-8 BOM, UTF-16 BOM, UTF-32 BOM → text (high confidence).
+ *   3. Strict UTF-8 decode succeeds → text (high confidence).
+ *   4. Otherwise count printable / control bytes:
+ *        - any null byte (0x00) → binary (high confidence).
+ *        - >= 95% printable + tab/newline/CR → text (medium).
+ *        - everything else → binary (low).
+ */
+export declare function sniffTextBytes(bytes: Uint8Array, sampleSize?: number): TextSniffResult;
+/** Every supported (extension, displayName, previewKind, thumbnailStrategy). */
+export interface SupportedTypeRow {
+    extensions: readonly string[];
+    mime: string;
+    category: FileCategory;
+    displayName: string;
+    previewKind: PreviewKind;
+    thumbnailStrategy: ThumbnailStrategy;
+    /** True when previewKind !== "generic" — i.e. we have a real previewer. */
+    canPreview: boolean;
+}
+export declare function listSupportedTypes(): SupportedTypeRow[];