@ai-matrx/media 0.7.15 → 0.8.0

package/dist/files.d.ts

@@ -0,0 +1,1171 @@
+import { AudioMediaPart, AudioOutputData, VideoMediaPart, VideoOutputData, ImageMediaPart, ImageOutputData, PartialImageData, RenderBlockPayload } from '@ai-matrx/agents/generated/stream-events';
+import * as react from 'react';
+
+/**
+ * files/ref-types — the Matrx file reference vocabulary shared by every client:
+ * visibility, permission level, the wire `MediaRef`, and the identity hint a caller
+ * may already know. Moved from matrx-frontend `features/files/types.ts` (P16f).
+ */
+type Visibility = "personal" | "internal" | "link" | "public";
+type PermissionLevel = "read" | "write" | "admin";
+interface MediaRef {
+    /** cld_files UUID — preferred form for any file we own. */
+    file_id?: string;
+    /** Any URL we issued (durable download route, share link) OR external https://. */
+    url?: string;
+    /** Optional client hint; backend overrides with `cld_files.mime_type` for owned files. */
+    mime_type?: string;
+    /** Free-form per-call metadata. Keep small — this rides on every request. */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Metadata a caller may already know when all it has is a durable file id.
+ * These values seed the canonical Redux record before field hydration runs;
+ * omitted keys remain genuinely unloaded and are fetched on demand.
+ */
+interface FileIdentityHint {
+    fileName?: string;
+    mimeType?: string | null;
+    fileSize?: number | null;
+    visibility?: Visibility;
+    /** Permanent public delivery only. Never place a signed URL here. */
+    publicUrl?: string | null;
+    /** Permanent public CDN delivery only. Never place a signed URL here. */
+    cdnUrl?: string | null;
+}
+/** Reads a stored visibility; anything unknown is the private default. */
+declare function toVisibility(raw: string | null | undefined): Visibility;
+/**
+ * Build a MediaRef from just a `file_id` (e.g. when an upload completes
+ * and the caller has the id but not the full record yet).
+ */
+declare function fileIdToMediaRef(fileId: string, mimeType?: string | null): MediaRef;
+/**
+ * Build a MediaRef from an external URL (public website image, signed URL
+ * we don't own, etc.). Use this ONLY when you don't have a `file_id` —
+ * otherwise the backend has to follow the URL to resolve the file.
+ */
+declare function urlToMediaRef(url: string, mimeType?: string | null): MediaRef;
+
+/**
+ * features/files/blocks/types.ts
+ *
+ * THE canonical TypeScript shape for every piece of media (image / video /
+ * audio / document / youtube) in the app — the FE mirror of Python's
+ * `UnifiedMediaBlock` Pydantic union. See:
+ *   - docs/PYTHON_UPDATES.md       — Phase 0/1/2 wire contract & migration plan
+ *   - features/files/blocks/image/UNIFIED_IMAGE_BLOCK.md — backstory
+ *   - packages/matrx-connect/matrx_connect/context/media_block.py (backend)
+ *
+ * Naming convention:
+ *   - This file uses **camelCase** (TS domain shape).
+ *   - The wire shape (`MediaBlockData.block` in stream events,
+ *     `cld_files.metadata.generation` on assets) uses **snake_case**.
+ *   - The adapter `./adapters/from-media-block.ts` converts the wire shape
+ *     to this shape at the boundary. Components only ever see camelCase.
+ *
+ * Two discriminators:
+ *   - `kind`   : "image" | "video" | "audio" | "document" | "youtube"
+ *                Narrow on this first to access kind-specific fields
+ *                (e.g. `width`/`height` on image, `durationMs` on audio).
+ *   - `origin` : "matrx" | "external"
+ *                Narrow on this second to access ownership-specific fields
+ *                (`fileId` on matrx, `externalUrl` on external).
+ *
+ * Invariants (enforced at adapter boundary):
+ *   1. `origin === "matrx"`  → `fileId` non-null when `status === "complete"`.
+ *   2. `origin === "external"` → `externalUrl` non-null OR `base64` non-null.
+ *   3. `status === "streaming"` → `base64` non-null (in-flight bytes).
+ *   4. `status === "error"` → `errorMessage` non-null.
+ */
+type MediaKind = "image" | "video" | "audio" | "document" | "youtube";
+type MediaOrigin = "matrx" | "external";
+type MediaStatus = "complete" | "streaming" | "error";
+/**
+ * THE canonical `platform.visibility` enum — identical to
+ * `features/files/types.ts#Visibility`, the DB, and the server. This used to
+ * be its own dialect (`public | personal | shared`), which is how `internal`
+ * and `link` rows got mis-bucketed on the way to URL resolution.
+ */
+type MediaVisibility = "personal" | "internal" | "link" | "public";
+interface MediaBlockBase {
+    /**
+     * "complete"   — final media; all configured URLs are valid as of emission
+     * "streaming"  — generating; `base64` (partial preview) is the only render source
+     * "error"      — generation failed; `errorMessage` carries the reason
+     */
+    status: MediaStatus;
+    /** 0–1 progress. Meaningful only when status === "streaming". */
+    progress: number | null;
+    /** Populated when status === "error". null otherwise. */
+    errorMessage: string | null;
+    /** Canonical MIME `type/subtype`. */
+    mimeType: string | null;
+    /** Display name (often AI-generated for ai-produced media). */
+    fileName: string | null;
+    /**
+     * File size in bytes (renamed from `file_size` in Phase 0 — see
+     * docs/PYTHON_UPDATES.md §3). null when unknown (typical for streaming
+     * partials and pre-finalize states).
+     */
+    sizeBytes: number | null;
+    /**
+     * Inline base64 bytes. Used for streaming partials and tiny inline assets.
+     * Cleared once `status === "complete"` and a URL is available.
+     */
+    base64: string | null;
+    /**
+     * Free-form. Phase 2 stamps `metadata.generation` (typed as
+     * `MediaGenerationMetadata` below) for any AI-generated asset.
+     * Existing top-level keys (`model`, `provider`, `prompt`, `cost`) are
+     * preserved for back-compat — new code should read `metadata.generation`.
+     */
+    metadata: Record<string, unknown> | null;
+    /**
+     * The reference role this media played as an INPUT (subject, style,
+     * first_frame, extend, …) and its `@name`, carried from the persisted
+     * part so a reload redisplays it. Absent for generated output.
+     */
+    referenceRole?: string | null;
+    referenceName?: string | null;
+}
+/**
+ * Fields present on every matrx-owned (cld_files-backed) media block.
+ * `fileId` is the permanent identity the URL resolver re-mints from on
+ * expiry (via fileHandler). Native storage locations are server-only and
+ * never appear on the client.
+ */
+interface MatrxOriginFields {
+    origin: "matrx";
+    /** cld_files.id — the permanent identity. */
+    fileId: string;
+    /**
+     * cld_files.visibility — drives URL resolution:
+     *   "public"   — prefer cdnUrl; permanent URL, no auth required
+     *   everything else ("personal" / "internal" / "link") — render through
+     *   the durable authenticated URL (`fileUrls(fileId).inline`), which the
+     *   browser authenticates via the `mx_files_session` cookie
+     */
+    visibility: MediaVisibility;
+    /** Permanent CDN URL — no expiry, no auth required. */
+    cdnUrl: string | null;
+    /** Durable attachment-disposition variant. Used for the download action. */
+    downloadUrl: string | null;
+    /** cld_files.parent_file_id — derivation lineage. */
+    parentFileId: string | null;
+    /**
+     * cld_files.derivation_kind — how this was produced from `parentFileId`.
+     * E.g. "manual_upload", "extracted_pages", "cropped", "rendered_page_image".
+     */
+    derivationKind: string | null;
+}
+/**
+ * Fields present on every external (third-party / user-pasted) media block.
+ * We never refresh these and never try to mint fresh URLs.
+ */
+interface ExternalOriginFields {
+    origin: "external";
+    /** The external URL. Always present — empty string fallback means broken. */
+    externalUrl: string;
+    /** Optional provenance label — e.g. "Wikimedia", "Tool: web_search". */
+    sourceLabel: string | null;
+}
+interface ImageKindFields {
+    kind: "image";
+    /** Pixel width. Null when unknown / pre-finalize. */
+    width: number | null;
+    /** Pixel height. Null when unknown / pre-finalize. */
+    height: number | null;
+    /**
+     * Optional content-class hint from vision models — e.g. "photograph",
+     * "diagram", "ui-screenshot". Free-form; consumers should treat as a UI
+     * hint only.
+     */
+    visionClass: string | null;
+}
+interface VideoKindFields {
+    kind: "video";
+    width: number | null;
+    height: number | null;
+    /** Duration in milliseconds. */
+    durationMs: number | null;
+    /**
+     * Poster/cover frame URL (extracted at ~10% of timeline). Phase 1
+     * populates this for matrx-owned videos via `Asset.variants["poster_url"]`.
+     */
+    posterUrl: string | null;
+}
+interface AudioKindFields {
+    kind: "audio";
+    /** Duration in milliseconds. */
+    durationMs: number | null;
+    /**
+     * Inline transcript text when present. Long-form transcripts go in a
+     * separate processed_documents row; this carries the short-form summary
+     * or null.
+     */
+    transcript: string | null;
+}
+interface DocumentKindFields {
+    kind: "document";
+    /** Page count for paginated documents (PDF, DOCX, …). null otherwise. */
+    pageCount: number | null;
+    /**
+     * Page-1 preview rendered to image. Phase 1 populates this for PDFs.
+     * Useful when displaying an inline document chip.
+     */
+    page1Url: string | null;
+}
+interface YouTubeKindFields {
+    kind: "youtube";
+    /** Extracted YouTube video id (the `?v=` token). */
+    videoId: string | null;
+}
+type MatrxImageBlock = MediaBlockBase & MatrxOriginFields & ImageKindFields;
+type ExternalImageBlock = MediaBlockBase & ExternalOriginFields & ImageKindFields;
+type ImageBlock = MatrxImageBlock | ExternalImageBlock;
+type MatrxVideoBlock = MediaBlockBase & MatrxOriginFields & VideoKindFields;
+type ExternalVideoBlock = MediaBlockBase & ExternalOriginFields & VideoKindFields;
+type VideoBlock = MatrxVideoBlock | ExternalVideoBlock;
+type MatrxAudioBlock = MediaBlockBase & MatrxOriginFields & AudioKindFields;
+type ExternalAudioBlock = MediaBlockBase & ExternalOriginFields & AudioKindFields;
+type AudioBlock = MatrxAudioBlock | ExternalAudioBlock;
+type MatrxDocumentBlock = MediaBlockBase & MatrxOriginFields & DocumentKindFields;
+type ExternalDocumentBlock = MediaBlockBase & ExternalOriginFields & DocumentKindFields;
+type DocumentBlock = MatrxDocumentBlock | ExternalDocumentBlock;
+/** YouTube is always external per the Python contract. */
+type YouTubeBlock = MediaBlockBase & ExternalOriginFields & YouTubeKindFields;
+/**
+ * The unified discriminated union for every media reference in the app.
+ *
+ * Narrowing recipe:
+ *   if (block.kind === "image") {
+ *     if (block.origin === "matrx") {
+ *       // block.fileId, block.visibility, block.cdnUrl, ...
+ *     } else {
+ *       // block.externalUrl, block.sourceLabel
+ *     }
+ *     // block.width, block.height (image-specific)
+ *   }
+ */
+type UnifiedMediaBlock = ImageBlock | VideoBlock | AudioBlock | DocumentBlock | YouTubeBlock;
+type MediaGenerationKind = "image" | "video" | "audio" | "speech" | "music";
+interface MediaGenerationMetadata {
+    kind: MediaGenerationKind;
+    provider: string;
+    model: string;
+    prompt: string;
+    negativePrompt: string | null;
+    /**
+     * Provider's rewrite of the user's prompt (OpenAI's `revised_prompt`).
+     * Surface to the user — improves transparency and trust.
+     */
+    revisedPrompt: string | null;
+    width: number | null;
+    height: number | null;
+    /** Free-form, e.g. "16:9", "1:1", "9:16". */
+    aspectRatio: string | null;
+    durationSeconds: number | null;
+    quality: string | null;
+    style: string | null;
+    seed: number | null;
+    steps: number | null;
+    cfgScale: number | null;
+    nRequested: number;
+    nReturned: number;
+    responseId: string | null;
+    durationMs: number | null;
+    costUsd: number | null;
+    /** E.g. "completed", "content_filter", "error". */
+    finishReason: string | null;
+    safetyFlagged: boolean;
+    /** Catch-all for provider-native fields we haven't canonicalized yet. */
+    providerExtras: Record<string, unknown>;
+}
+/**
+ * Wire shape (snake_case) as Python emits it. Adapters read this; consumers
+ * generally don't.
+ */
+interface MediaGenerationMetadataWire {
+    kind: MediaGenerationKind;
+    provider: string;
+    model: string;
+    prompt: string;
+    negative_prompt?: string | null;
+    revised_prompt?: string | null;
+    width?: number | null;
+    height?: number | null;
+    aspect_ratio?: string | null;
+    duration_seconds?: number | null;
+    quality?: string | null;
+    style?: string | null;
+    seed?: number | null;
+    steps?: number | null;
+    cfg_scale?: number | null;
+    n_requested?: number;
+    n_returned?: number;
+    response_id?: string | null;
+    duration_ms?: number | null;
+    cost_usd?: number | null;
+    finish_reason?: string | null;
+    safety_flagged?: boolean;
+    provider_extras?: Record<string, unknown>;
+}
+/**
+ * Pull the typed `MediaGenerationMetadata` out of a block's free-form
+ * metadata bag. Returns null when no `generation` key is present.
+ *
+ * Usage:
+ *   const gen = parseGenerationMetadata(block.metadata);
+ *   if (gen?.revisedPrompt) { renderRevisedPromptBanner(gen.revisedPrompt); }
+ */
+declare function parseGenerationMetadata(metadata: Record<string, unknown> | null | undefined): MediaGenerationMetadata | null;
+
+/**
+ * features/files/blocks/guards.ts
+ *
+ * Runtime type guards for `UnifiedMediaBlock` and its variants. Used at
+ * trust boundaries (Redux reads, adapter inputs) to prove the shape
+ * rather than force-cast.
+ *
+ * All guards accept `unknown` so they're safe to use against raw
+ * `Record<string, unknown>` data (e.g. `block.data` on a render-block
+ * envelope, `block.metadata` on a free-form bag).
+ */
+
+declare function isMatrxMediaBlock(value: unknown): value is Extract<UnifiedMediaBlock, {
+    origin: "matrx";
+}>;
+declare function isExternalMediaBlock(value: unknown): value is Extract<UnifiedMediaBlock, {
+    origin: "external";
+}>;
+declare function isUnifiedMediaBlock(value: unknown): value is UnifiedMediaBlock;
+declare function isImageBlock(value: unknown): value is ImageBlock;
+declare function isVideoBlock(value: unknown): value is VideoBlock;
+declare function isAudioBlock(value: unknown): value is AudioBlock;
+declare function isDocumentBlock(value: unknown): value is DocumentBlock;
+declare function isYouTubeBlock(value: unknown): value is YouTubeBlock;
+declare function isMatrxImageBlock(value: unknown): value is MatrxImageBlock;
+declare function isExternalImageBlock(value: unknown): value is ExternalImageBlock;
+
+/**
+ * features/files/blocks/image/types.ts
+ *
+ * Image-specific types — re-exported from the canonical `UnifiedMediaBlock`
+ * union in `../types.ts`. THIS FILE IS THIN BY DESIGN: there is no
+ * image-only shape anymore; an `ImageBlock` is just the `kind: "image"`
+ * variant of the platform-wide media block.
+ *
+ * Keep this file alive so existing imports
+ *   import type { UnifiedImageBlock, MatrxImageBlock, ExternalImageBlock }
+ *     from "@/features/files/blocks/image/types";
+ * continue to work without churn. New code should prefer importing from
+ * `@/features/files/blocks/types` directly.
+ *
+ * See ../UNIFIED_IMAGE_BLOCK.md and docs/PYTHON_UPDATES.md for the wire
+ * contract.
+ */
+
+/**
+ * Back-compat alias. Past consumers know "UnifiedImageBlock" — this is the
+ * same thing as `ImageBlock` from the canonical union. New code should
+ * spell it `ImageBlock` for consistency with the other kinds.
+ */
+type UnifiedImageBlock = ImageBlock;
+
+/**
+ * features/files/blocks/image/guards.ts
+ *
+ * Image-specific runtime guards. Re-exported from the canonical guards in
+ * `../guards.ts`. New code should prefer importing from there directly.
+ *
+ * Usage:
+ *
+ *     if (!isUnifiedImageBlock(block.data)) return null;
+ *     // block.data is now narrowed to ImageBlock (kind: "image")
+ *     // by TypeScript.
+ *
+ * These guards check BOTH `kind === "image"` and the origin discriminator,
+ * so a stray video/audio/document block will NOT pass through them.
+ */
+
+/**
+ * Back-compat alias for `isImageBlock` — narrows to `UnifiedImageBlock`
+ * (a.k.a. the `kind: "image"` variant of `UnifiedMediaBlock`).
+ */
+declare function isUnifiedImageBlock(value: unknown): value is UnifiedImageBlock;
+
+/**
+ * features/files/blocks/adapters/from-cx-av-part.ts
+ *
+ * Convert a DB-stored `cx_message.content[]` media part (kind: "audio" |
+ * "video") into the `AudioOutputData` / `VideoOutputData` render-block payload
+ * the chat media renderers consume.
+ *
+ * This is the audio/video twin of the image adapter
+ * (`../image/adapters/from-cx-media-part.ts`) and exists for the same reason:
+ * **media identity is the `file_id`, never a URL.** The stored `url` is
+ * whatever happened to be visible at save time (legacy rows: a long-dead
+ * signed S3 URL). `file_id` is what lets `buildMediaSource` → `useFileSrc`
+ * resolve the durable URL on every render.
+ *
+ * `file_id` lives at the TOP LEVEL of the stored media part (and is sometimes
+ * mirrored into `metadata`); the URL flavors are dumped into `metadata`. Both
+ * are lifted back out here so the round-trip is lossless.
+ */
+
+declare function fromCxAudioPart(part: AudioMediaPart): AudioOutputData & {
+    transcription_result: string | null;
+};
+declare function fromCxVideoPart(part: VideoMediaPart): VideoOutputData & {
+    reference_role: string | null;
+    reference_name: string | null;
+};
+
+/**
+ * features/files/blocks/adapters/from-media-block.ts
+ *
+ * THE primary inbound adapter for the new `data.type === "media_block"`
+ * stream event (Phase 0 of Python's unified-media rollout — see
+ * docs/PYTHON_UPDATES.md).
+ *
+ * The wire shape (Python's `UnifiedMediaBlock` Pydantic union) is
+ * snake_case and nearly identical to our domain shape. This adapter does
+ * exactly two things:
+ *   1. Rename fields snake_case → camelCase.
+ *   2. Enforce invariants:
+ *        - matrx → fileId non-null
+ *        - external → externalUrl non-null
+ *      Anything that doesn't satisfy these falls through to an external
+ *      "broken" block; the renderer shows an error state.
+ *
+ * Anything kind-specific (image's `vision_class`, video's `duration_ms`,
+ * etc.) is just propagated — no per-kind logic here.
+ *
+ * Note: Python `main` hasn't deployed yet (as of 2026-05-16). The shape
+ * below is what we'll receive once it does. Until then this adapter is
+ * cold-path; the existing `image_output` / `partial_image` legacy
+ * adapters carry traffic.
+ */
+
+interface WireMediaBlockBase {
+    origin: "matrx" | "external";
+    status?: MediaStatus | null;
+    progress?: number | null;
+    error_message?: string | null;
+    mime_type?: string | null;
+    file_name?: string | null;
+    size_bytes?: number | null;
+    base64?: string | null;
+    metadata?: Record<string, unknown> | null;
+    file_id?: string | null;
+    visibility?: MediaVisibility | null;
+    cdn_url?: string | null;
+    download_url?: string | null;
+    parent_file_id?: string | null;
+    derivation_kind?: string | null;
+    external_url?: string | null;
+    source_label?: string | null;
+}
+interface WireImageBlock extends WireMediaBlockBase {
+    kind: "image";
+    width?: number | null;
+    height?: number | null;
+    vision_class?: string | null;
+}
+interface WireVideoBlock extends WireMediaBlockBase {
+    kind: "video";
+    width?: number | null;
+    height?: number | null;
+    duration_ms?: number | null;
+    poster_url?: string | null;
+}
+interface WireAudioBlock extends WireMediaBlockBase {
+    kind: "audio";
+    duration_ms?: number | null;
+    transcript?: string | null;
+}
+interface WireDocumentBlock extends WireMediaBlockBase {
+    kind: "document";
+    page_count?: number | null;
+    page1_url?: string | null;
+}
+interface WireYouTubeBlock extends WireMediaBlockBase {
+    kind: "youtube";
+    video_id?: string | null;
+}
+type WireMediaBlock = WireImageBlock | WireVideoBlock | WireAudioBlock | WireDocumentBlock | WireYouTubeBlock;
+/**
+ * Wire shape for the `media_block` stream event envelope. Always has
+ * `type: "media_block"` and a `block: WireMediaBlock` payload.
+ */
+interface WireMediaBlockData {
+    type: "media_block";
+    block: WireMediaBlock;
+}
+/**
+ * Lift a wire-shape `UnifiedMediaBlock` (as emitted by Python's new
+ * `media_block` data event) into our domain `UnifiedMediaBlock` shape.
+ *
+ * Discriminates on `kind` and delegates to the kind-specific lifter.
+ * Each lifter handles the matrx-vs-external origin split internally.
+ */
+declare function fromMediaBlock(wire: WireMediaBlock): UnifiedMediaBlock;
+/**
+ * Predicate for narrowing a raw `data` payload (typed as
+ * `Record<string, unknown>` in Redux) down to a `media_block` event.
+ *
+ * Use at the stream-event boundary:
+ *   if (isMediaBlockData(d)) { upsert(fromMediaBlock(d.block)); }
+ */
+declare function isMediaBlockData(value: unknown): value is WireMediaBlockData;
+
+/**
+ * features/files/blocks/adapters/from-media-ref.ts
+ *
+ * Generic platform primitive: turn a bare `MediaRef` (or file_id / URL)
+ * into a minimal `UnifiedMediaBlock` so it can be fed to the canonical
+ * renderers (`UnifiedImageBlockRenderer`, `UnifiedVideoBlockRenderer`)
+ * which consume a `block`, not a `MediaRef`.
+ *
+ * Why this exists: many callsites only ever have a durable reference to a
+ * file — a `{file_id}` (we own it) or a `{url}` (external / already-public)
+ * — yet they want the full rich-media affordances (expand → fullscreen,
+ * the "…" menu, mobile long-press, share, download). Those affordances
+ * live ONLY on the canonical block renderers. This adapter bridges the
+ * gap without forcing every caller to hand-build a block literal (which
+ * the CLAUDE.md file-handling rules forbid).
+ *
+ * Mapping (consistent with the invariants in `../types.ts`):
+ *   - `{ file_id }` ref → an `origin: "matrx"` block. `fileId` is set;
+ *     `visibility` is "personal" (unknown) and `cdnUrl` is null, so
+ *     `useBlockMediaSource` resolves the durable URL via the injected
+ *     `MediaClient`.
+ *   - `{ url }` ref → an `origin: "external"` block. `externalUrl` is set;
+ *     the renderer uses it as-is.
+ *   - A ref that resolves to neither → an `external` "broken" block with a
+ *     null/empty `externalUrl`; the renderer shows its error state.
+ *
+ * `status` is always "complete" — these refs point at finished media. For
+ * streaming partials, use the streaming adapters in `from-media-block.ts`.
+ */
+
+/** The kinds this generic adapter can synthesize a block for. */
+type MediaBlockKindArg = "image" | "video";
+/**
+ * Build a minimal `ImageBlock` from a durable reference.
+ */
+declare function imageBlockFromMediaRef(ref: MediaRef | null): ImageBlock | null;
+/**
+ * Build a minimal `VideoBlock` from a durable reference.
+ */
+declare function videoBlockFromMediaRef(ref: MediaRef | null): VideoBlock | null;
+/**
+ * Kind-dispatching convenience: build an image or video block from a ref.
+ * Returns `null` when `ref` is null.
+ */
+declare function blockFromMediaRef(ref: MediaRef | null, kind: MediaBlockKindArg): ImageBlock | VideoBlock | null;
+
+/**
+ * features/files/blocks/image/adapters/from-cx-media-part.ts
+ *
+ * Convert a DB-stored `cx_message.content[]` media part (kind: "image") into
+ * a UnifiedImageBlock.
+ *
+ * Today's storage shape (CxMediaContent → ImageMediaPart):
+ *   { type: "media", kind: "image", url?, mime_type?, base64_data?,
+ *     metadata? }
+ *
+ * Everything else (file_id, cdn_url, visibility, thumbnails,
+ * dimensions, file_name, prompt, model, etc.) gets dumped into `metadata`
+ * today by `assembleMessageParts`. This adapter pulls them BACK out so the
+ * round-trip is lossless.
+ *
+ * Delete when `cx_message.content[]` storage shape switches to
+ * UnifiedImageBlock natively (Phase 3).
+ */
+
+declare function fromCxMediaPart(part: ImageMediaPart): UnifiedImageBlock;
+
+/**
+ * features/files/blocks/image/adapters/from-image-output-data.ts
+ *
+ * Convert a Python `image_output` data event into a UnifiedImageBlock.
+ *
+ * Today's Python wire shape (ImageOutputData):
+ *   { type: "image_output", url, mime_type, file_id?, cdn_url?, download_url? }
+ *
+ * What this adapter does:
+ *   - Lifts `file_id` to identify a matrx-owned file (most common case).
+ *   - Tries to extract `file_id` from `url` if Python didn't supply one
+ *     (legacy fallback — eventually deletable).
+ *   - Promotes additional fields from `metadata` if Python included them
+ *     there as a transitional shim:
+ *       visibility, thumbnail_url, parent_file_id, derivation_kind,
+ *       file_name, width, height, size_bytes.
+ *   - When no `file_id` is recoverable, falls back to an external block
+ *     using whichever URL is most likely permanent.
+ *
+ * Delete when Python emits UnifiedImageBlock directly (Phase 2).
+ */
+
+declare function fromImageOutputData(data: ImageOutputData, carriedMetadata?: Record<string, unknown> | null): UnifiedImageBlock;
+
+/**
+ * features/files/blocks/image/adapters/from-partial-image-data.ts
+ *
+ * Convert a Python `partial_image` event into an in-flight UnifiedImageBlock.
+ *
+ * Partial images are base64 frames Python emits during image generation.
+ * They arrive BEFORE the final `image_output` event lands, so there's no
+ * fileId yet. We model them as an external block in "streaming" status
+ * whose `base64` carries the latest frame.
+ *
+ * When the final `image_output` arrives, the stream-ingest layer should
+ * upsert by `blockId` so a single block transitions from streaming
+ * (base64-only) → complete (matrx variant with URLs). This means partial
+ * and final SHARE the same blockId in Redux.
+ *
+ * Delete when Python emits UnifiedImageBlock directly with status: "streaming"
+ * (Phase 2).
+ */
+
+declare function fromPartialImageData(data: PartialImageData, carriedMetadata?: Record<string, unknown> | null): UnifiedImageBlock;
+
+/**
+ * features/files/blocks/image/adapters/from-render-block.ts
+ *
+ * Convert a markdown-parsed image render_block (e.g. from a text chunk that
+ * contained `![alt](url)`) into a UnifiedImageBlock.
+ *
+ * Today's wire shape is minimal — `{ src, alt }`. We treat these as external
+ * unless the URL pattern matches our canonical S3 key scheme, in which case
+ * we promote to matrx via `extractFileIdFromUrl` (inside `fromImageOutputData`).
+ *
+ * Input type is `RenderBlockPayload` (not `ImageRenderBlock`) so callers can
+ * pass the redux-stored loose shape without a force-cast. We validate the
+ * payload structure internally; an empty src yields an external block with an
+ * empty URL — the renderer's error state covers it.
+ *
+ * Delete when render_block:image emits UnifiedImageBlock in its `data` field
+ * (Phase 2).
+ */
+
+declare function fromRenderBlock(block: RenderBlockPayload): UnifiedImageBlock;
+
+/**
+ * features/files/blocks/image/adapters/to-cx-media-part.ts
+ *
+ * Convert a `UnifiedImageBlock` into the generated DB on-disk
+ * `ImageMediaPart` shape.
+ *
+ * On-disk shape today (`ImageMediaPart`):
+ *   { type: "media", kind: "image", file_id? | url?, origin?,
+ *     mime_type?, size_bytes?, width?, height?, metadata? }
+ *
+ * Strategy:
+ *   - Keep generated top-level identity fields populated so
+ *     legacy readers that haven't migrated keep working.
+ *   - Pack EVERY canonical field (origin, fileId, cdnUrl, downloadUrl,
+ *     visibility, thumbnails, dimensions, etc.) into
+ *     `metadata` under stable keys so `fromCxMediaPart` can re-lift them
+ *     losslessly when the message is reloaded.
+ *
+ * Delete when `cx_message.content[]` storage switches to UnifiedImageBlock
+ * natively (Phase 3).
+ */
+
+declare function toCxMediaPart(block: UnifiedImageBlock): ImageMediaPart;
+
+/**
+ * features/files/blocks/image/helpers/derive-viewer-url.ts
+ *
+ * Derive the internal viewer route for a matrx-owned image. The route
+ * `/files/f/{fileId}` is the canonical "deep link" for any cld_files row.
+ *
+ * External blocks do not have a viewer URL — return null.
+ */
+
+declare function deriveViewerUrl(block: UnifiedImageBlock): string | null;
+
+/**
+ * features/files/blocks/image/helpers/extract-file-id-from-url.ts
+ *
+ * Best-effort extraction of a cld_files UUID from a storage / CDN URL.
+ *
+ * Canonical S3 key scheme: `/{owner_id}/{file_id}` (no subfolder, no extension).
+ * Legacy fallback: `/{owner_id}/{folder}/{file_id}.{ext}`.
+ *
+ * Used by adapters as a last-resort when Python's payload doesn't carry an
+ * explicit `file_id` field — e.g. legacy stream events. Once Python emits
+ * `file_id` consistently, this becomes dead code.
+ */
+declare function extractFileIdFromUrl(url: string | null | undefined): string | null;
+
+/**
+ * features/files/blocks/image/helpers/parse-filename-from-url.ts
+ *
+ * S3 signed URLs the backend mints for AI-generated images carry the
+ * intended filename in `response-content-disposition`, e.g.:
+ *
+ *   ?response-content-disposition=inline%3B%20filename%3D%22kitten.png%22
+ *
+ * Python's AI-naming step (`features/ai/...`) writes a meaningful name
+ * there based on the prompt, so the browser shows it on download. But
+ * when we use `<a download="...">` we override that — we need the name
+ * in `block.fileName` to pass it back.
+ *
+ * This helper extracts the filename from the query param if present.
+ * Returns null on anything malformed so callers always get a string or
+ * null (never an empty string).
+ *
+ * Handles both RFC 5987 forms:
+ *   - `filename="kitten.png"` (quoted, ASCII)
+ *   - `filename*=UTF-8''ki%CC%88tten.png` (extended, percent-encoded)
+ */
+declare function parseFilenameFromUrl(url: string | null | undefined): string | null;
+
+/** One compact publish-date treatment shared by every video surface. */
+declare function VideoPublishDate({ publishedAt, className, }: {
+    publishedAt?: string | null;
+    className?: string;
+}): react.JSX.Element;
+
+/**
+ * features/files/handler/errors.ts
+ *
+ * Error taxonomy for the universal file handler. Every failure inside the
+ * handler maps to ONE of these classes — callers `instanceof`-check to
+ * decide whether to retry, refresh, surface a UI, or reject.
+ *
+ * The crucial distinction the handler exists to enforce:
+ *
+ *   - FileAccessDeniedError → user does NOT have access. Reject. Never retry.
+ *   - a transient auth failure on a durable URL → refresh the file session
+ *     (see ../session.ts) and retry the SAME URL; never a terminal error.
+ */
+type FileHandlerErrorCode = "access_denied" | "not_found" | "deleted" | "share_link_invalid" | "external_fetch_failed" | "cors_blocked" | "mime_unknown" | "upload_failed" | "upload_cancelled" | "quota_exceeded" | "in_flight" | "internal";
+declare class FileHandlerError extends Error {
+    readonly code: FileHandlerErrorCode;
+    readonly fileId?: string | undefined;
+    readonly cause?: unknown;
+    constructor(code: FileHandlerErrorCode, message: string, opts?: {
+        fileId?: string;
+        cause?: unknown;
+    });
+}
+declare class FileAccessDeniedError extends FileHandlerError {
+    constructor(message?: string, opts?: {
+        fileId?: string;
+    });
+}
+declare class FileNotFoundError extends FileHandlerError {
+    constructor(message?: string, opts?: {
+        fileId?: string;
+    });
+}
+declare class FileDeletedError extends FileHandlerError {
+    constructor(message?: string, opts?: {
+        fileId?: string;
+    });
+}
+declare class ShareLinkInvalidError extends FileHandlerError {
+    constructor(message?: string);
+}
+declare class ExternalFetchError extends FileHandlerError {
+    constructor(message?: string, opts?: {
+        cause?: unknown;
+    });
+}
+declare class FileUploadError extends FileHandlerError {
+    constructor(message: string, opts?: {
+        cause?: unknown;
+    });
+}
+/**
+ * The person was asked which workspace an upload belongs to and declined.
+ *
+ * Deliberately a distinct class, not a `FileUploadError` with a flag: nothing
+ * failed. No bytes moved, no row was written, and there is nothing to retry or
+ * report. Every catch site must swallow it silently — cancelling has to return
+ * the person exactly where they were, which a red toast does not.
+ */
+declare class UploadCancelledError extends FileHandlerError {
+    constructor(message?: string);
+}
+declare function isUploadCancelledError(error: unknown): boolean;
+
+/** Compose a canonical Files folder path from an optional logical root. */
+declare function composeUploadFolderPath(root?: string, path?: string): string;
+
+/**
+ * features/files/utils/folder-conventions.ts
+ *
+ * Canonical folder paths for every feature that uploads on behalf of the
+ * user. The rule is simple: **organize files the way a user would expect to
+ * find them.** When a user opens `/files`, they should be able to
+ * point at a folder and say "that's where X goes" without us explaining it.
+ *
+ * Two buckets:
+ *
+ *  1. Visible folders — real, user-facing. Files go here when the user
+ *     produced them, uploaded them, or attached them to something. Names are
+ *     human-readable (Title Case) because they're shown in the tree.
+ *
+ *  2. Hidden folders (leading `.`) — ephemeral / infrastructure files the
+ *     user doesn't need to see or manage. Auto-collapsed in the UI. These
+ *     should be rare; only use them for true transients (short-lived URL
+ *     staging, drafts) and prefer deletion on completion.
+ *
+ * Every consumer migration should pick its folder from this file or add a
+ * new constant here — do NOT hand-roll folder paths at call sites.
+ *
+ * This file is also the source of truth for the **default visibility** of
+ * every folder — see `resolveDefaultVisibility` near the bottom. Callers
+ * should pick visibility based on render context, not user role: anything
+ * rendered on a public page (org logo, podcast cover, agent-app icon)
+ * defaults to `"public"` so it gets a CDN URL; anything user-scoped
+ * (chat attachment, task attachment, ephemeral temp) stays `"private"`.
+ */
+
+declare const CloudFolders: {
+    /** Top-level "Images" drawer. */
+    readonly IMAGES: "Images";
+    /** Images pasted/attached inside a chat. */
+    readonly IMAGES_CHAT: "Images/Chat";
+    /** Screenshots dragged or pasted into the app. */
+    readonly IMAGES_SCREENSHOTS: "Images/Screenshots";
+    /** User avatars / profile images. */
+    readonly IMAGES_AVATARS: "Images/Avatars";
+    /** Images generated by AI tools. */
+    readonly IMAGES_GENERATED: "Images/Generated";
+    /** Screenshots and images flattened with user-authored markup. */
+    readonly IMAGES_ANNOTATED: "Images/Annotated";
+    /** Top-level "Audio" drawer. */
+    readonly AUDIO: "Audio";
+    /** User-initiated audio recordings (voice-to-text, voice pad, etc.). */
+    readonly AUDIO_RECORDINGS: "Audio/Recordings";
+    /** Podcast asset uploads. */
+    readonly AUDIO_PODCASTS: "Audio/Podcasts";
+    /** Top-level "Captures" drawer — everything the in-browser media-capture
+     *  system saves (features/media-capture). User-produced, so visible. */
+    readonly CAPTURES: "Captures";
+    /** Photos taken with the in-app camera (Capture Studio / device fallback). */
+    readonly CAPTURES_PHOTOS: "Captures/Photos";
+    /** Videos recorded with the in-app camera (media-capture Phase 7). */
+    readonly CAPTURES_VIDEOS: "Captures/Videos";
+    /** Audio recorded through the Capture Studio (media-capture Phase 7). */
+    readonly CAPTURES_AUDIO: "Captures/Audio";
+    /** Product-capture staging (features/product-capture) — per-item folders of
+     *  photos/videos/voice notes shot ahead of listing creation. Org-namespaced
+     *  via `folderForProductCaptureItem` (same server one-path-one-org rule as
+     *  Captures). User-produced, so visible. */
+    readonly PRODUCT_CAPTURES: "Product Captures";
+    /** Commerce intake (W4 capture app): per-asset media filed under
+     *  `Commerce Intake/<orgId>/<batchId>/<asset-leaf>` via
+     *  `folderForIntakeAsset` (same server one-path-one-org rule as Captures).
+     *  User-produced, so visible. */
+    readonly COMMERCE_INTAKE: "Commerce Intake";
+    /**
+     * Static app assets (sounds, hero images, model-card thumbnails, demo
+     * data) owned by an admin service account and rendered globally.
+     * Always public — CDN URL is the goal. Source of truth for the
+     * static-asset migration (see scripts/migrate-public-assets-to-cdn.ts).
+     */
+    readonly APP_ASSETS: "App Assets";
+    /** Top-level documents (PDF, DOCX, etc.). */
+    readonly DOCUMENTS: "Documents";
+    /** PDF-specific drawer. */
+    readonly DOCUMENTS_PDFS: "Documents/PDFs";
+    /** Top-level code files (scripts, snippets). */
+    readonly CODE: "Code";
+    /** Code saved via the code-editor window. */
+    readonly CODE_EDITOR: "Code/Editor";
+    /** Generic AI-generated outputs. */
+    readonly GENERATED: "Generated";
+    /** Files attached to agent apps, keyed by app id at runtime. */
+    readonly AGENT_APPS: "Agent Apps";
+    /** Files attached to tasks, keyed by task id at runtime. */
+    readonly TASK_ATTACHMENTS: "Task Attachments";
+    /** Files attached to War Room tiles, keyed by tile id at runtime. */
+    readonly WAR_ROOM: "War Room";
+    /** Files dropped into a chat composer (pre-send or history). */
+    readonly CHAT_ATTACHMENTS: "Chat Attachments";
+    /** Slack-imported files. */
+    readonly SLACK_IMPORTS: "Slack Imports";
+    /** Web-scrape captures (HTML snapshots, exported markdown). */
+    readonly SCRAPED_CONTENT: "Scraped Content";
+    /**
+     * Org-scoped shared assets — logos, hero images, anything an
+     * organization renders on a public surface. Keyed by org id at
+     * runtime (e.g. `Shared Assets/orgs/<org-id>`). Always public —
+     * the CDN URL is the rendering target.
+     */
+    readonly SHARED_ASSETS_ORGS: "Shared Assets/orgs";
+    /** Public screenshot attachments submitted through the feedback window. */
+    readonly FEEDBACK_IMAGES: "Shared Assets/feedback-images";
+    /**
+     * OG / social-preview covers for HTML pages the user publishes.
+     * Lives under Shared Assets so all org/public-surface previews
+     * share one CDN-backed bucket.
+     */
+    readonly HTML_PAGES_OG: "Shared Assets/html-pages";
+    /**
+     * Favicons rendered by prompt-app / agent-app standalone pages.
+     * Always public — favicon requests are anonymous.
+     */
+    readonly PROMPT_APPS_FAVICONS: "App Assets/prompt-apps/favicons";
+    /**
+     * Per-block assets attached to agent blocks (icons, illustrations,
+     * inline media). Keyed by block id at runtime via
+     * `folderForAgentBlock(blockId)`.
+     */
+    readonly AGENT_BLOCKS: "Agent Apps/blocks";
+    /**
+     * Cover images rendered on canvas social/share surfaces. Public so
+     * the share-card OG image is a stable CDN URL.
+     */
+    readonly CANVAS_COVERS: "Images/Canvas/Covers";
+    /**
+     * Source images the user is editing in the image studio. Private —
+     * these are the user's working files, NOT public render targets.
+     * Outputs that the user explicitly publishes land elsewhere.
+     */
+    readonly IMAGES_EDITED_SOURCES: "Images/Edited/Sources";
+    /** Root for all ephemeral cloud-files work. Hidden in the tree. */
+    readonly TMP: ".matrx-tmp";
+    /** Short-lived audio files staged for URL-based transcription. */
+    readonly TMP_TRANSCRIPTS: ".matrx-tmp/transcripts";
+    /** Upload-in-progress staging (future use). */
+    readonly TMP_UPLOADS: ".matrx-tmp/uploads";
+    /** Root for backend-owned infrastructure files (variants, posters, etc.). */
+    readonly SYSTEM_FILES: "system-files";
+    /** SOCIAL_BASELINE variant storage: og.jpg / thumb.jpg / tiny.jpg / page1_url.jpg. */
+    readonly SYSTEM_VARIANTS: "system-files/variants";
+    /**
+     * Backend "generations" registry root — every AI generation (image,
+     * video, audio/TTS) the server materializes lands under
+     * `generations/<images|video|audio>/...`. Backend-owned; mirrors the
+     * server's `is_system_path()` (which treats `system-files` AND
+     * `generations` as system). Never shown in the user tree.
+     */
+    readonly GENERATIONS: "generations";
+    /**
+     * Recorded audio captured by the Transcripts / voice features. As of
+     * 2026-06-14 the backend relocates every `origin: "transcripts"` upload
+     * here, UNDER the hidden `system-files/` root — one
+     * `recording_<iso>_<rand>.webm` per capture (80+ for an active user).
+     * Because it's under `system-files/`, `isSystemPath` already hides it
+     * from the tree, folder views, AND Recents — no separate predicate
+     * needed. Managed exclusively via the Transcripts UI (by `cld_files.id`).
+     * See docs/files/transcript-recordings-system-relocation.md.
+     */
+    readonly TRANSCRIPT_RECORDINGS: "system-files/transcripts/Recordings";
+    /**
+     * LEGACY user-namespace location for transcript recordings, before the
+     * 2026-06-14 backend relocation to `system-files/transcripts/...`. Kept
+     * ONLY as a defensive Recents guard: the backend relocates every
+     * `origin: "transcripts"` upload, but the presigned/TUS (chunked + large
+     * file) relocation path was genuinely missing and is committed but NOT yet
+     * in prod as of 2026-06-15.
+     *
+     * DO NOT DROP THIS GUARD until that backend fix has DEPLOYED to prod —
+     * dropping it earlier would let a chunked/large recording slip through
+     * unhidden. Sequence: backend deploys → then remove this constant from
+     * `isSystemManagedContentPath` (and delete it). See the FE-response /
+     * "open items" in docs/files/transcript-recordings-system-relocation.md.
+     */
+    readonly TRANSCRIPT_RECORDINGS_LEGACY: "Transcripts/Recordings";
+    /**
+     * Per-tool generated image variants — `tool-images/<id>/v/<name>.jpg`,
+     * multiple sizes per source. Machine-produced output, excluded from
+     * Recents (see `isSystemManagedContentPath`).
+     */
+    readonly TOOL_IMAGES: "tool-images";
+    /**
+     * FastFire voice-drill recordings — full-session + per-card response clips.
+     * Live under the hidden `system-files/fastfire/...` root (same class as
+     * transcript recordings). Managed via Education / FastFire UI only.
+     */
+    readonly SYSTEM_FASTFIRE: "system-files/fastfire";
+    readonly SYSTEM_FASTFIRE_SESSIONS: "system-files/fastfire/sessions";
+    readonly SYSTEM_FASTFIRE_RESPONSES: "system-files/fastfire/responses";
+    /**
+     * Spoken Practice (oral exam / interview / debate) recordings — full-session
+     * clips + per-prompt spoken-answer clips. Same hidden `system-files/` class as
+     * FastFire (so `isSystemPath` keeps them out of the Files browser + Recents).
+     */
+    readonly SYSTEM_SPOKEN_PRACTICE: "system-files/spoken-practice";
+    readonly SYSTEM_SPOKEN_PRACTICE_SESSIONS: "system-files/spoken-practice/sessions";
+    readonly SYSTEM_SPOKEN_PRACTICE_RESPONSES: "system-files/spoken-practice/responses";
+    /**
+     * Handwritten / image-answer grading — photos of worked problems a learner
+     * submits to the vision grader (assessment written-item photo answers +
+     * the standalone "Grade my handwritten work" surface). Same hidden
+     * `system-files/` class (kept out of the Files browser + Recents).
+     */
+    readonly SYSTEM_IMAGE_GRADE: "system-files/image-grade";
+    readonly SYSTEM_IMAGE_GRADE_RESPONSES: "system-files/image-grade/responses";
+    /**
+     * LEGACY user-namespace FastFire paths (pre-2026-07 relocation). Kept as a
+     * defensive tree + Recents guard until every row is backfilled under
+     * `system-files/fastfire/`.
+     */
+    readonly FASTFIRE_SESSIONS: "FastFire/sessions";
+    readonly FASTFIRE_RESPONSES: "FastFire/responses";
+};
+/**
+ * Files attached to a specific task.
+ *   folderForTask("abc-123") → "Task Attachments/abc-123"
+ */
+declare function folderForTask(taskId: string): string;
+/**
+ * Files attached to a specific War Room tile.
+ *   folderForWarRoomThread("abc-123") → "War Room/abc-123"
+ */
+declare function folderForWarRoomThread(threadId: string): string;
+/**
+ * Files attached to a specific chat / conversation.
+ *   folderForConversation("xyz") → "Chat Attachments/xyz"
+ */
+declare function folderForConversation(conversationId: string): string;
+/**
+ * Assets for a specific agent app (favicon, icons, etc.).
+ *   folderForAgentApp("abc") → "Agent Apps/abc"
+ */
+declare function folderForAgentApp(appId: string): string;
+/**
+ * Per-podcast episode assets.
+ */
+declare function folderForPodcast(podcastId: string): string;
+/**
+ * Per-org shared assets.
+ *   folderForOrg("org-abc") → "Shared Assets/orgs/org-abc"
+ */
+declare function folderForOrg(orgId: string): string;
+/**
+ * Per-agent-block assets (icons, illustrations, attached media).
+ *   folderForAgentBlock("blk_123") → "Agent Apps/blocks/blk_123"
+ */
+declare function folderForAgentBlock(blockId: string): string;
+/** Per-org capture subtree. Org id in the path keeps each workspace's
+ *  captures a DISTINCT global folder path (the server allows one folder
+ *  path per user, pinned to one org — a flat `Captures/Videos` cannot exist
+ *  under two orgs). Falls back to the flat path when there is no active org
+ *  (personal context).
+ *
+ *  Nested output still resolves to `personal` visibility: the
+ *  `resolveDefaultVisibility` rule keys on the `Captures` prefix (a
+ *  longest-prefix match), so `Captures/<org>/Videos` matches the same rule as
+ *  the flat `Captures/Videos`. The org id in the path is filing, not access —
+ *  personal-visibility files stay owner-gated regardless of org. */
+declare function folderForCaptures(kind: "photo" | "video" | "audio", orgId?: string | null): string;
+/** Per-item product-capture folder: `Product Captures/<orgId>/<leaf>`.
+ *  `leaf` is the item's sanitized code (the QR value / SKU) when known at
+ *  creation, else the item id — set ONCE at item creation and never renamed.
+ *  Org id in the path for the same one-path-one-org server rule as
+ *  `folderForCaptures`. Files here upload with explicit `visibility:
+ *  "internal"` (org-wide access is the point of the surface), so the
+ *  `resolveDefaultVisibility` prefix rules are deliberately not consulted. */
+declare function folderForProductCaptureItem(orgId: string, leaf: string): string;
+/**
+ * Commerce-intake artifact folder for one asset (or the batch-level stream in
+ * untracked mode — pass the batch id as `leaf`). Fixed at creation, NEVER
+ * renamed — a QR/serial that arrives later lives on identifier rows only
+ * (PROTOTYPE-CONCEPTS P13: the cloud path is never renamed).
+ */
+declare function folderForIntakeAsset(orgId: string, batchId: string, leaf: string): string;
+/** True if the folder is under `.matrx-tmp/` (user-hidden). */
+declare function isHiddenFolder(folderPath: string): boolean;
+/**
+ * True if `path` (a `cld_files.file_path` or `cld_folders.folder_path`)
+ * points at a backend-owned system / infrastructure row that must NEVER
+ * surface in the user's tree.
+ *
+ * Today this covers:
+ *  - `system-files` / `system-files/...` — backfilled SOCIAL_BASELINE
+ *    variant rows (og/thumb/tiny/page1_url) and their per-source-file
+ *    folders. ~3–4 rows per uploaded image, ~10k+ for active accounts.
+ *  - `generations` / `generations/...` — the backend AI-generation
+ *    registry root (image/video/audio output). Mirrors the server's
+ *    `is_system_path()`, which treats BOTH `system-files` and
+ *    `generations` as system; the tree RPC already drops these, this is
+ *    the FE-side parity guard at every other tree boundary.
+ *  - `.matrx-tmp` / `.matrx-tmp/...` — ephemeral staging the user
+ *    shouldn't see or manage.
+ *
+ * The predicate is intentionally path-based (not `derivation_kind` or
+ * `parent_file_id`) because the Python backfill didn't populate those
+ * fields on variant rows. Once they do, we'll add data-shape signals
+ * here and drop the path heuristic.
+ *
+ * Pass either a file path or a folder path — both follow the same
+ * convention (system paths are prefix-rooted).
+ */
+declare function isSystemPath(path: string | null | undefined): boolean;
+/**
+ * THE VISIBILITY RULE IS THE DATABASE'S, NOT THIS FILE'S.
+ *
+ * `isHiddenFromUserTree()` and `isFastFirePath()` used to live here and were a
+ * SECOND copy of the server's rule — the browser hid top-level `FastFire/**`
+ * that the server called user-visible, so the sync daemon wrote those bytes to
+ * disk while the browser refused to show them (folder-sync DECISIONS D16,
+ * SPEC-SERVER §1.4 consumer 2). They are deleted.
+ *
+ * Rows that arrive through `get_user_file_tree` are already filtered by
+ * `files.is_user_visible_path` — never filter them again. Realtime payloads,
+ * which bypass the RPC, use the parity-tested mirror in
+ * `features/files/utils/user-visible.ts`.
+ */
+/**
+ * RECENTS IS THE DATABASE'S RULE TOO. `isExcludedFromRecents`,
+ * `isGeneratedContentPath` and `isSystemManagedContentPath` lived here as a
+ * client-only Recents rule; they are deleted (2026-09-24). Their roots moved
+ * into the one declaration (`files.is_recent_activity*`, aidream
+ * matrx_files/user_visible.py RECENT_EXCLUDED_ROOTS) and the browser applies
+ * its parity-guarded mirror, `isRecentActivityFile` / `isRecentActivityPath`
+ * in `features/files/utils/user-visible.ts`. Rule + registry: common-docs
+ * systems/files/file-service/USER_FILES_VS_MACHINE_FILES.md.
+ */
+/**
+ * True if the folder path matches one of our canonical conventions (either
+ * visible or hidden). Useful for UI that wants to show a pretty icon next
+ * to known folders.
+ */
+declare function isConventionalFolder(folderPath: string): boolean;
+/**
+ * Maps a CloudFolders constant → human-friendly description for tooltips /
+ * empty states. Extend as needed.
+ */
+declare const CloudFolderDescriptions: Record<string, string>;
+/**
+ * Resolve the default visibility for a given folder path. Longest-prefix
+ * match against `DEFAULT_VISIBILITY_RULES`; falls back to `"personal"` for
+ * any folder not in the table. Use at upload sites that don't have an
+ * obvious context-driven choice.
+ */
+declare function resolveDefaultVisibility(folderPath: string): Visibility;
+
+/** Stable, narrow video publish-date text for cards, rows, and embeds. */
+declare function formatVideoPublishDate(value: string | null | undefined): string;
+/** Accessible detail for the compact video publish-date treatment. */
+declare function formatVideoPublishDateTitle(value: string | null | undefined): string;
+/**
+ * Read a provider/schema publish date from the common metadata envelopes used
+ * by research media, crawled site videos, and brand-library assets.
+ */
+declare function videoPublishDateFromMetadata(value: unknown): string | null;
+
+/**
+ * Shared bounded registry for ephemeral `URL.createObjectURL` blobs.
+ *
+ * Consumers that create local blob URLs use this primitive so previews cannot
+ * leak memory without bound. Explicit cleanup remains preferred; the global
+ * ceiling is a final safety net for callers that no longer own their URL.
+ */
+/** Create a tracked object URL; evicts the oldest if over the cap. */
+declare function createTrackedObjectUrl(blob: Blob): string;
+/** Explicitly revoke a tracked URL when a consumer knows it is finished. */
+declare function revokeTrackedObjectUrl(url: string | undefined | null): void;
+
+export { type AudioBlock, CloudFolderDescriptions, CloudFolders, type DocumentBlock, type ExternalAudioBlock, type ExternalDocumentBlock, ExternalFetchError, type ExternalImageBlock, type ExternalVideoBlock, FileAccessDeniedError, FileDeletedError, FileHandlerError, type FileHandlerErrorCode, type FileIdentityHint, FileNotFoundError, FileUploadError, type ImageBlock, type MatrxAudioBlock, type MatrxDocumentBlock, type MatrxImageBlock, type MatrxVideoBlock, type MediaBlockKindArg, type MediaGenerationKind, type MediaGenerationMetadata, type MediaGenerationMetadataWire, type MediaKind, type MediaOrigin, type MediaRef, type MediaStatus, type MediaVisibility, type PermissionLevel, ShareLinkInvalidError, type UnifiedImageBlock, type UnifiedMediaBlock, UploadCancelledError, type VideoBlock, VideoPublishDate, type Visibility, type WireMediaBlock, type WireMediaBlockData, type YouTubeBlock, blockFromMediaRef, composeUploadFolderPath, createTrackedObjectUrl, deriveViewerUrl, extractFileIdFromUrl, fileIdToMediaRef, folderForAgentApp, folderForAgentBlock, folderForCaptures, folderForConversation, folderForIntakeAsset, folderForOrg, folderForPodcast, folderForProductCaptureItem, folderForTask, folderForWarRoomThread, formatVideoPublishDate, formatVideoPublishDateTitle, fromCxAudioPart, fromCxMediaPart, fromCxVideoPart, fromImageOutputData, fromMediaBlock, fromPartialImageData, fromRenderBlock, imageBlockFromMediaRef, isAudioBlock, isConventionalFolder, isDocumentBlock, isExternalImageBlock, isExternalMediaBlock, isHiddenFolder, isImageBlock, isMatrxImageBlock, isMatrxMediaBlock, isMediaBlockData, isSystemPath, isUnifiedImageBlock, isUnifiedMediaBlock, isUploadCancelledError, isVideoBlock, isYouTubeBlock, parseFilenameFromUrl, parseGenerationMetadata, resolveDefaultVisibility, revokeTrackedObjectUrl, toCxMediaPart, toVisibility, urlToMediaRef, videoBlockFromMediaRef, videoPublishDateFromMetadata };