@ai-matrx/media 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @ai-matrx/media
 
+## 0.1.1 — 2026-08-29
+
+Types-only fix; runtime behavior unchanged.
+
+- **Fixed: the `DurableSrc` unique-symbol brand was duplicated in the built
+  declarations.** The dts was built in two passes (mirroring the two-config
+  "use client" banner split), so the root `index.d.ts` declared its own copy
+  of the brand while `/core` and `/react` used a shared-chunk copy — two
+  distinct `unique symbol`s. Result: a `MediaClient` typed via the root entry
+  was nominally incompatible with `/core`'s `MediaProvider`, forcing a
+  documented cast in the host. The dts now builds in ONE pass over all three
+  entries (the JS banner split is unchanged), so the brand is declared once
+  in `index.d.ts` and the other entries' declarations import it.
+- **Canary added:** `verify:tarball` now compiles a consumer against the
+  packed tarball that assigns a root-typed `MediaClient` into
+  `/core`'s `MediaProvider` props with **no cast** — the brand-duplication
+  regression class fails `check:package` from now on.
+
 ## 0.1.0 — 2026-08-29
 
 Initial release (campaign ruling C19). Root types + `/core` headless hooks +

package/dist/core.d.cts

@@ -1,7 +1,7 @@
 import * as react from 'react';
 import { ReactNode } from 'react';
-import { M as MediaClient, a as MediaHostPorts, b as MediaRefLike, c as MediaResolution, d as MediaUnavailableReason, D as DurableSrc, e as MediaActionContext, f as MediaActionKind, g as MediaSlotComponent, h as MediaSharePopoverProps } from './use-media-upload-VjUhqbyY.cjs';
-export { i as MediaUploadEntry, j as MediaUploadEntryStatus, k as MediaUploadProgress, U as UseMediaUploadResult, u as useMediaUpload } from './use-media-upload-VjUhqbyY.cjs';
+import { MediaClient, MediaHostPorts, MediaRefLike, MediaResolution, MediaUnavailableReason, DurableSrc, MediaActionContext, MediaActionKind, MediaSlotComponent, MediaSharePopoverProps } from './index.cjs';
+export { M as MediaUploadEntry, a as MediaUploadEntryStatus, b as MediaUploadProgress, U as UseMediaUploadResult, u as useMediaUpload } from './use-media-upload-v5Uq9Ruq.cjs';
 
 interface MediaProviderProps {
     client: MediaClient;

package/dist/core.d.ts

@@ -1,7 +1,7 @@
 import * as react from 'react';
 import { ReactNode } from 'react';
-import { M as MediaClient, a as MediaHostPorts, b as MediaRefLike, c as MediaResolution, d as MediaUnavailableReason, D as DurableSrc, e as MediaActionContext, f as MediaActionKind, g as MediaSlotComponent, h as MediaSharePopoverProps } from './use-media-upload-VjUhqbyY.js';
-export { i as MediaUploadEntry, j as MediaUploadEntryStatus, k as MediaUploadProgress, U as UseMediaUploadResult, u as useMediaUpload } from './use-media-upload-VjUhqbyY.js';
+import { MediaClient, MediaHostPorts, MediaRefLike, MediaResolution, MediaUnavailableReason, DurableSrc, MediaActionContext, MediaActionKind, MediaSlotComponent, MediaSharePopoverProps } from './index.js';
+export { M as MediaUploadEntry, a as MediaUploadEntryStatus, b as MediaUploadProgress, U as UseMediaUploadResult, u as useMediaUpload } from './use-media-upload-Dg2HSvTq.js';
 
 interface MediaProviderProps {
     client: MediaClient;

package/dist/react.d.cts

@@ -1,6 +1,7 @@
 import * as react from 'react';
 import react__default, { SVGProps, HTMLAttributes, InputHTMLAttributes, ReactNode } from 'react';
-import { b as MediaRefLike, l as MediaUploadOptions, i as MediaUploadEntry, f as MediaActionKind } from './use-media-upload-VjUhqbyY.cjs';
+import { MediaRefLike, MediaUploadOptions, MediaActionKind } from './index.cjs';
+import { M as MediaUploadEntry } from './use-media-upload-v5Uq9Ruq.cjs';
 
 /**
  * src/react/cn.ts — conditional class join with last-wins Tailwind conflict

package/dist/react.d.ts

@@ -1,6 +1,7 @@
 import * as react from 'react';
 import react__default, { SVGProps, HTMLAttributes, InputHTMLAttributes, ReactNode } from 'react';
-import { b as MediaRefLike, l as MediaUploadOptions, i as MediaUploadEntry, f as MediaActionKind } from './use-media-upload-VjUhqbyY.js';
+import { MediaRefLike, MediaUploadOptions, MediaActionKind } from './index.js';
+import { M as MediaUploadEntry } from './use-media-upload-Dg2HSvTq.js';
 
 /**
  * src/react/cn.ts — conditional class join with last-wins Tailwind conflict

package/dist/use-media-upload-Dg2HSvTq.d.ts

@@ -0,0 +1,53 @@
+import { MediaUploadOptions, MediaUploadResult, MediaMultiUploadResult } from './index.js';
+
+/**
+ * src/core/use-media-upload.ts — the React-side upload primitive.
+ *
+ * Ported from matrx-frontend `handler/hooks/useFileUpload.ts` with two seam
+ * inversions: the transport is `MediaClient.upload` (never touched directly),
+ * and the multi-file pre-flight (SHA-256 dedup dialog) is the client's
+ * optional `uploadMany` — when absent, the batch runs sequentially through
+ * `upload` with per-file results.
+ *
+ * Additionally exposes a per-file `entries` tray state (name, size, bytes,
+ * status) so the dropzone's UploadProgressList works without any app store —
+ * the Redux `selectVisibleUploads` coupling of the original, inverted.
+ */
+
+interface MediaUploadProgress {
+    loaded: number;
+    total: number;
+    ratio: number;
+}
+type MediaUploadEntryStatus = "uploading" | "success" | "error";
+interface MediaUploadEntry {
+    id: string;
+    fileName: string;
+    fileSize: number;
+    bytesUploaded: number;
+    status: MediaUploadEntryStatus;
+    error: string | null;
+    fileId: string | null;
+    completedAt: number | null;
+}
+interface UseMediaUploadResult {
+    /** Upload one file/blob. Returns the durable identity. */
+    upload: (file: File | Blob, opts?: MediaUploadOptions) => Promise<MediaUploadResult>;
+    /**
+     * Upload many files. Uses the client's `uploadMany` (host pre-flight /
+     * dedup dialog) when implemented; otherwise a sequential per-file loop with
+     * real per-file error messages.
+     */
+    uploadMany: (files: File[], opts?: MediaUploadOptions) => Promise<MediaMultiUploadResult>;
+    uploading: boolean;
+    progress: MediaUploadProgress | null;
+    result: MediaUploadResult | null;
+    error: Error | null;
+    /** Live per-file tray entries for progress UI. */
+    entries: MediaUploadEntry[];
+    clearEntry: (id: string) => void;
+    reset: () => void;
+}
+declare function useMediaUpload(): UseMediaUploadResult;
+
+export { type MediaUploadEntry as M, type UseMediaUploadResult as U, type MediaUploadEntryStatus as a, type MediaUploadProgress as b, useMediaUpload as u };

package/dist/use-media-upload-v5Uq9Ruq.d.cts

@@ -0,0 +1,53 @@
+import { MediaUploadOptions, MediaUploadResult, MediaMultiUploadResult } from './index.cjs';
+
+/**
+ * src/core/use-media-upload.ts — the React-side upload primitive.
+ *
+ * Ported from matrx-frontend `handler/hooks/useFileUpload.ts` with two seam
+ * inversions: the transport is `MediaClient.upload` (never touched directly),
+ * and the multi-file pre-flight (SHA-256 dedup dialog) is the client's
+ * optional `uploadMany` — when absent, the batch runs sequentially through
+ * `upload` with per-file results.
+ *
+ * Additionally exposes a per-file `entries` tray state (name, size, bytes,
+ * status) so the dropzone's UploadProgressList works without any app store —
+ * the Redux `selectVisibleUploads` coupling of the original, inverted.
+ */
+
+interface MediaUploadProgress {
+    loaded: number;
+    total: number;
+    ratio: number;
+}
+type MediaUploadEntryStatus = "uploading" | "success" | "error";
+interface MediaUploadEntry {
+    id: string;
+    fileName: string;
+    fileSize: number;
+    bytesUploaded: number;
+    status: MediaUploadEntryStatus;
+    error: string | null;
+    fileId: string | null;
+    completedAt: number | null;
+}
+interface UseMediaUploadResult {
+    /** Upload one file/blob. Returns the durable identity. */
+    upload: (file: File | Blob, opts?: MediaUploadOptions) => Promise<MediaUploadResult>;
+    /**
+     * Upload many files. Uses the client's `uploadMany` (host pre-flight /
+     * dedup dialog) when implemented; otherwise a sequential per-file loop with
+     * real per-file error messages.
+     */
+    uploadMany: (files: File[], opts?: MediaUploadOptions) => Promise<MediaMultiUploadResult>;
+    uploading: boolean;
+    progress: MediaUploadProgress | null;
+    result: MediaUploadResult | null;
+    error: Error | null;
+    /** Live per-file tray entries for progress UI. */
+    entries: MediaUploadEntry[];
+    clearEntry: (id: string) => void;
+    reset: () => void;
+}
+declare function useMediaUpload(): UseMediaUploadResult;
+
+export { type MediaUploadEntry as M, type UseMediaUploadResult as U, type MediaUploadEntryStatus as a, type MediaUploadProgress as b, useMediaUpload as u };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-matrx/media",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "The AI Matrx media components kit: durable-ref-only renderers for images, video, audio and file thumbnails that just work with the Matrx file system — headless core hooks plus DOM bindings, wired to an injected MediaClient. A signed URL is a handoff, never an identity.",
   "type": "module",
   "main": "./dist/index.cjs",

package/dist/use-media-upload-VjUhqbyY.d.cts

@@ -1,270 +0,0 @@
-/**
- * @ai-matrx/media — the root types: the MediaClient port and the host ports.
- *
- * The package renders Matrx durable media; it NEVER talks to a network.
- * Everything data-shaped arrives through the injected {@link MediaClient}
- * (canonically implemented by `@ai-matrx/data/files`; any structural
- * implementation works — the strangler step wires it over an app's existing
- * file handler). The five file-handling laws are enforced here at the type
- * level:
- *
- *   1. Never fetch a media URL yourself — the package contains zero network
- *      primitives; bytes exist only via {@link MediaClient.getBlob}.
- *   2. Off-boundary code resolves media itself — every component takes a
- *      {@link MediaRefLike} and calls `resolve()` unconditionally. There is
- *      NO `src` prop on any component in this package.
- *   3. A signed URL is a handoff, never an identity — the only string that
- *      reaches a media element is the branded {@link DurableSrc}, which only
- *      a MediaClient implementation can mint (via {@link mintDurableSrc}).
- *   4. Public-facing media is persisted public, never signed —
- *      {@link MediaClient.shareableUrl} fails closed (`null` → the action
- *      renders disabled).
- *   5. One URL contract; the engine builds URLs — zero URL construction in
- *      this package; `resolve()` is the only door.
- */
-/** The canonical durable media reference. `file_id` is the identity. */
-interface MediaRef {
-    file_id?: string | null;
-    url?: string | null;
-    mime_type?: string | null;
-    metadata?: Record<string, unknown> | null;
-}
-/**
- * Identity in. A raw string is a fileId or an EXTERNAL public URL — never a
- * signed URL (the client's `resolve()` classifies and screams on one).
- */
-type MediaRefLike = MediaRef | string;
-declare const durable: unique symbol;
-/**
- * A URL that has passed through `MediaClient.resolve()` — the only string
- * type any media element in this package will bind. A caller cannot pass an
- * expiring URL through the package's types without an explicit unsafe cast.
- */
-type DurableSrc = string & {
-    readonly [durable]: true;
-};
-type MediaKind = "image" | "video" | "audio" | "file";
-interface MediaResolution {
-    src: DurableSrc;
-    /** RN auth lane (`<Image source={{uri, headers}}>`); absent on web (cookie session). */
-    headers?: Record<string, string> | undefined;
-    mimeType?: string | undefined;
-    kind: MediaKind;
-    /**
-     * How pixels must travel. `"element"` (default): bind `src` directly to the
-     * media element. `"blob"`: the bytes require bearer auth the element cannot
-     * attach — consumers go through {@link MediaClient.getBlob} and render the
-     * returned object URL (the private-image lane).
-     */
-    transport?: "element" | "blob" | undefined;
-    /**
-     * A server-rendered thumbnail for this file, when the client knows one
-     * (Matrx: `FileRecord.thumbnail_url` / asset variants). Consumed by the
-     * thumbnail tier machine.
-     */
-    thumbnailSrc?: DurableSrc | undefined;
-    /**
-     * True when this is a permanent public CDN URL — lets a host-supplied
-     * `ImageComponent` (e.g. a next/image adapter) take the render, and marks
-     * the URL CORS-safe for element-level `crossOrigin`.
-     */
-    isCdn?: boolean | undefined;
-    /**
-     * Whether a load error can be recovered by the client's ONE retry policy
-     * (session-refresh → same-URL retry). False for foreign/external URLs —
-     * a session refresh can't resurrect someone else's link rot. Default true.
-     */
-    recoverable?: boolean | undefined;
-}
-/** Typed unavailable states — render-as-state, never thrown as incidents. */
-type MediaUnavailableReason = "access_denied" | "not_found" | "deleted" | "unknown";
-interface MediaBlobHandle {
-    /** `blob:` object URL safe for any browser API. */
-    url: string;
-    blob: Blob;
-    /** Release the handle. Implementations backed by a shared cache may no-op. */
-    release(): void;
-}
-interface MediaUploadOptions {
-    onProgress?: ((loaded: number, total: number) => void) | undefined;
-    fileName?: string | undefined;
-    mimeType?: string | undefined;
-    /** Host visibility vocabulary passes through structurally. */
-    visibility?: string | undefined;
-    parentFolderId?: string | null | undefined;
-    metadata?: Record<string, unknown> | undefined;
-}
-/** Upload → durable identity. `fileId` is required at compile time and runtime. */
-interface MediaUploadResult {
-    fileId: string;
-    ref: MediaRef;
-}
-interface MediaMultiUploadResult {
-    /** File ids for every successful upload. */
-    uploaded: string[];
-    /** Per-file failure with the real backend error message. */
-    failed: Array<{
-        name: string;
-        error: string;
-    }>;
-    /** True when the host's pre-flight (e.g. a duplicate dialog) cancelled the batch. */
-    cancelled: boolean;
-}
-interface MediaClient {
-    /**
-     * Synchronous durable-URL build + classification. Returns `null` when the
-     * ref carries no usable identity (components render their fallback).
-     * THROWS (and screams via its own diagnostics sink) on a signed/expiring
-     * URL — the D108 guard lives behind this door.
-     */
-    resolve(ref: MediaRefLike): MediaResolution | null;
-    /** Bytes for canvas/crossOrigin/private-pixel consumers. */
-    getBlob(ref: MediaRefLike): Promise<MediaBlobHandle>;
-    /**
-     * Session bootstrap + the ONE retry policy: refresh-then-same-URL-retry,
-     * second failure terminal. Called by the package's onError path, never
-     * re-implemented.
-     */
-    recoverLoadError(src: DurableSrc, attempt: number): Promise<"retry" | "terminal">;
-    /** Upload → durable identity. */
-    upload(file: File | Blob, opts?: MediaUploadOptions): Promise<MediaUploadResult>;
-    /**
-     * Optional batch upload with host pre-flight (dedup dialogs etc.). When
-     * absent, `useMediaUpload().uploadMany` falls back to sequential `upload`.
-     */
-    uploadMany?(files: File[], opts?: MediaUploadOptions): Promise<MediaMultiUploadResult>;
-    /** Share affordances — fails closed (null), never emits a signed URL. */
-    shareableUrl(ref: MediaRefLike): Promise<string | null>;
-    /** Typed unavailable states — render-as-state, never thrown as incidents. */
-    classifyError(err: unknown): MediaUnavailableReason;
-}
-/**
- * Structural component slot. `(props) => unknown` keeps the root entry free
- * of React type imports; any React function component satisfies it.
- */
-type MediaSlotComponent<P> = (props: P) => unknown;
-interface MediaImageComponentProps {
-    src: string;
-    alt: string;
-    width: number;
-    height: number;
-    className?: string | undefined;
-    onError?: ((event: unknown) => void) | undefined;
-    onClick?: ((event: unknown) => void) | undefined;
-    onKeyDown?: ((event: unknown) => void) | undefined;
-    role?: string | undefined;
-    tabIndex?: number | undefined;
-}
-interface PlaybackSessionRegistration {
-    isPlaying: boolean;
-    source: string;
-    label: string;
-    trackKey?: string | undefined;
-}
-/**
- * The host's audio system (exclusive-playback lock, output-sink routing).
- * Both members are HOOKS — the package calls them unconditionally on every
- * render of a media element, so implementations must obey the Rules of Hooks
- * and the port object must be referentially stable.
- */
-interface PlaybackSessionPort {
-    /**
-     * Returns a ref callback for the underlying media element (routes audio
-     * output / setSinkId on hosts that support it) and forwards to the caller's
-     * own element ref.
-     */
-    useMediaElementSink(forward: ((node: unknown) => void) | {
-        current: unknown;
-    } | null | undefined): (node: unknown) => void;
-    /** Joins the host's unified playback session for the element. */
-    usePlaybackSession(registration: PlaybackSessionRegistration, elementRef: {
-        current: unknown;
-    }): void;
-}
-type MediaActionKind = "share" | "download" | "copy" | "open";
-interface MediaActionContext {
-    ref: MediaRefLike;
-    resolution: MediaResolution | null;
-    fileName?: string | undefined;
-    alt?: string | undefined;
-}
-interface MediaSharePopoverProps {
-    context: MediaActionContext;
-    onClose: () => void;
-}
-type MediaActionHandler = (ctx: MediaActionContext) => Promise<void>;
-interface MediaActionsPort {
-    /**
-     * Quick-share handler (copy a share link, open the native share sheet…).
-     * Implementations obtain URLs ONLY via `MediaClient.shareableUrl` /
-     * durable identities — never a signed URL (law 4).
-     */
-    share?: MediaActionHandler | undefined;
-    download?: MediaActionHandler | undefined;
-    copy?: MediaActionHandler | undefined;
-    open?: MediaActionHandler | undefined;
-    /**
-     * Rich share UI body — the slot the associations package fills. When
-     * present, the shells open it instead of (or on top of) the `share`
-     * handler. Receives {@link MediaSharePopoverProps}.
-     */
-    SharePopover?: MediaSlotComponent<MediaSharePopoverProps> | undefined;
-}
-interface MediaHostPorts {
-    playbackSession?: PlaybackSessionPort | undefined;
-    actions?: MediaActionsPort | undefined;
-    /** Web host may pass a next/image adapter; default is a plain `<img>`. */
-    ImageComponent?: MediaSlotComponent<MediaImageComponentProps> | undefined;
-}
-
-/**
- * src/core/use-media-upload.ts — the React-side upload primitive.
- *
- * Ported from matrx-frontend `handler/hooks/useFileUpload.ts` with two seam
- * inversions: the transport is `MediaClient.upload` (never touched directly),
- * and the multi-file pre-flight (SHA-256 dedup dialog) is the client's
- * optional `uploadMany` — when absent, the batch runs sequentially through
- * `upload` with per-file results.
- *
- * Additionally exposes a per-file `entries` tray state (name, size, bytes,
- * status) so the dropzone's UploadProgressList works without any app store —
- * the Redux `selectVisibleUploads` coupling of the original, inverted.
- */
-
-interface MediaUploadProgress {
-    loaded: number;
-    total: number;
-    ratio: number;
-}
-type MediaUploadEntryStatus = "uploading" | "success" | "error";
-interface MediaUploadEntry {
-    id: string;
-    fileName: string;
-    fileSize: number;
-    bytesUploaded: number;
-    status: MediaUploadEntryStatus;
-    error: string | null;
-    fileId: string | null;
-    completedAt: number | null;
-}
-interface UseMediaUploadResult {
-    /** Upload one file/blob. Returns the durable identity. */
-    upload: (file: File | Blob, opts?: MediaUploadOptions) => Promise<MediaUploadResult>;
-    /**
-     * Upload many files. Uses the client's `uploadMany` (host pre-flight /
-     * dedup dialog) when implemented; otherwise a sequential per-file loop with
-     * real per-file error messages.
-     */
-    uploadMany: (files: File[], opts?: MediaUploadOptions) => Promise<MediaMultiUploadResult>;
-    uploading: boolean;
-    progress: MediaUploadProgress | null;
-    result: MediaUploadResult | null;
-    error: Error | null;
-    /** Live per-file tray entries for progress UI. */
-    entries: MediaUploadEntry[];
-    clearEntry: (id: string) => void;
-    reset: () => void;
-}
-declare function useMediaUpload(): UseMediaUploadResult;
-
-export { type DurableSrc as D, type MediaClient as M, type UseMediaUploadResult as U, type MediaHostPorts as a, type MediaRefLike as b, type MediaResolution as c, type MediaUnavailableReason as d, type MediaActionContext as e, type MediaActionKind as f, type MediaSlotComponent as g, type MediaSharePopoverProps as h, type MediaUploadEntry as i, type MediaUploadEntryStatus as j, type MediaUploadProgress as k, type MediaUploadOptions as l, useMediaUpload as u };

package/dist/use-media-upload-VjUhqbyY.d.ts

@@ -1,270 +0,0 @@
-/**
- * @ai-matrx/media — the root types: the MediaClient port and the host ports.
- *
- * The package renders Matrx durable media; it NEVER talks to a network.
- * Everything data-shaped arrives through the injected {@link MediaClient}
- * (canonically implemented by `@ai-matrx/data/files`; any structural
- * implementation works — the strangler step wires it over an app's existing
- * file handler). The five file-handling laws are enforced here at the type
- * level:
- *
- *   1. Never fetch a media URL yourself — the package contains zero network
- *      primitives; bytes exist only via {@link MediaClient.getBlob}.
- *   2. Off-boundary code resolves media itself — every component takes a
- *      {@link MediaRefLike} and calls `resolve()` unconditionally. There is
- *      NO `src` prop on any component in this package.
- *   3. A signed URL is a handoff, never an identity — the only string that
- *      reaches a media element is the branded {@link DurableSrc}, which only
- *      a MediaClient implementation can mint (via {@link mintDurableSrc}).
- *   4. Public-facing media is persisted public, never signed —
- *      {@link MediaClient.shareableUrl} fails closed (`null` → the action
- *      renders disabled).
- *   5. One URL contract; the engine builds URLs — zero URL construction in
- *      this package; `resolve()` is the only door.
- */
-/** The canonical durable media reference. `file_id` is the identity. */
-interface MediaRef {
-    file_id?: string | null;
-    url?: string | null;
-    mime_type?: string | null;
-    metadata?: Record<string, unknown> | null;
-}
-/**
- * Identity in. A raw string is a fileId or an EXTERNAL public URL — never a
- * signed URL (the client's `resolve()` classifies and screams on one).
- */
-type MediaRefLike = MediaRef | string;
-declare const durable: unique symbol;
-/**
- * A URL that has passed through `MediaClient.resolve()` — the only string
- * type any media element in this package will bind. A caller cannot pass an
- * expiring URL through the package's types without an explicit unsafe cast.
- */
-type DurableSrc = string & {
-    readonly [durable]: true;
-};
-type MediaKind = "image" | "video" | "audio" | "file";
-interface MediaResolution {
-    src: DurableSrc;
-    /** RN auth lane (`<Image source={{uri, headers}}>`); absent on web (cookie session). */
-    headers?: Record<string, string> | undefined;
-    mimeType?: string | undefined;
-    kind: MediaKind;
-    /**
-     * How pixels must travel. `"element"` (default): bind `src` directly to the
-     * media element. `"blob"`: the bytes require bearer auth the element cannot
-     * attach — consumers go through {@link MediaClient.getBlob} and render the
-     * returned object URL (the private-image lane).
-     */
-    transport?: "element" | "blob" | undefined;
-    /**
-     * A server-rendered thumbnail for this file, when the client knows one
-     * (Matrx: `FileRecord.thumbnail_url` / asset variants). Consumed by the
-     * thumbnail tier machine.
-     */
-    thumbnailSrc?: DurableSrc | undefined;
-    /**
-     * True when this is a permanent public CDN URL — lets a host-supplied
-     * `ImageComponent` (e.g. a next/image adapter) take the render, and marks
-     * the URL CORS-safe for element-level `crossOrigin`.
-     */
-    isCdn?: boolean | undefined;
-    /**
-     * Whether a load error can be recovered by the client's ONE retry policy
-     * (session-refresh → same-URL retry). False for foreign/external URLs —
-     * a session refresh can't resurrect someone else's link rot. Default true.
-     */
-    recoverable?: boolean | undefined;
-}
-/** Typed unavailable states — render-as-state, never thrown as incidents. */
-type MediaUnavailableReason = "access_denied" | "not_found" | "deleted" | "unknown";
-interface MediaBlobHandle {
-    /** `blob:` object URL safe for any browser API. */
-    url: string;
-    blob: Blob;
-    /** Release the handle. Implementations backed by a shared cache may no-op. */
-    release(): void;
-}
-interface MediaUploadOptions {
-    onProgress?: ((loaded: number, total: number) => void) | undefined;
-    fileName?: string | undefined;
-    mimeType?: string | undefined;
-    /** Host visibility vocabulary passes through structurally. */
-    visibility?: string | undefined;
-    parentFolderId?: string | null | undefined;
-    metadata?: Record<string, unknown> | undefined;
-}
-/** Upload → durable identity. `fileId` is required at compile time and runtime. */
-interface MediaUploadResult {
-    fileId: string;
-    ref: MediaRef;
-}
-interface MediaMultiUploadResult {
-    /** File ids for every successful upload. */
-    uploaded: string[];
-    /** Per-file failure with the real backend error message. */
-    failed: Array<{
-        name: string;
-        error: string;
-    }>;
-    /** True when the host's pre-flight (e.g. a duplicate dialog) cancelled the batch. */
-    cancelled: boolean;
-}
-interface MediaClient {
-    /**
-     * Synchronous durable-URL build + classification. Returns `null` when the
-     * ref carries no usable identity (components render their fallback).
-     * THROWS (and screams via its own diagnostics sink) on a signed/expiring
-     * URL — the D108 guard lives behind this door.
-     */
-    resolve(ref: MediaRefLike): MediaResolution | null;
-    /** Bytes for canvas/crossOrigin/private-pixel consumers. */
-    getBlob(ref: MediaRefLike): Promise<MediaBlobHandle>;
-    /**
-     * Session bootstrap + the ONE retry policy: refresh-then-same-URL-retry,
-     * second failure terminal. Called by the package's onError path, never
-     * re-implemented.
-     */
-    recoverLoadError(src: DurableSrc, attempt: number): Promise<"retry" | "terminal">;
-    /** Upload → durable identity. */
-    upload(file: File | Blob, opts?: MediaUploadOptions): Promise<MediaUploadResult>;
-    /**
-     * Optional batch upload with host pre-flight (dedup dialogs etc.). When
-     * absent, `useMediaUpload().uploadMany` falls back to sequential `upload`.
-     */
-    uploadMany?(files: File[], opts?: MediaUploadOptions): Promise<MediaMultiUploadResult>;
-    /** Share affordances — fails closed (null), never emits a signed URL. */
-    shareableUrl(ref: MediaRefLike): Promise<string | null>;
-    /** Typed unavailable states — render-as-state, never thrown as incidents. */
-    classifyError(err: unknown): MediaUnavailableReason;
-}
-/**
- * Structural component slot. `(props) => unknown` keeps the root entry free
- * of React type imports; any React function component satisfies it.
- */
-type MediaSlotComponent<P> = (props: P) => unknown;
-interface MediaImageComponentProps {
-    src: string;
-    alt: string;
-    width: number;
-    height: number;
-    className?: string | undefined;
-    onError?: ((event: unknown) => void) | undefined;
-    onClick?: ((event: unknown) => void) | undefined;
-    onKeyDown?: ((event: unknown) => void) | undefined;
-    role?: string | undefined;
-    tabIndex?: number | undefined;
-}
-interface PlaybackSessionRegistration {
-    isPlaying: boolean;
-    source: string;
-    label: string;
-    trackKey?: string | undefined;
-}
-/**
- * The host's audio system (exclusive-playback lock, output-sink routing).
- * Both members are HOOKS — the package calls them unconditionally on every
- * render of a media element, so implementations must obey the Rules of Hooks
- * and the port object must be referentially stable.
- */
-interface PlaybackSessionPort {
-    /**
-     * Returns a ref callback for the underlying media element (routes audio
-     * output / setSinkId on hosts that support it) and forwards to the caller's
-     * own element ref.
-     */
-    useMediaElementSink(forward: ((node: unknown) => void) | {
-        current: unknown;
-    } | null | undefined): (node: unknown) => void;
-    /** Joins the host's unified playback session for the element. */
-    usePlaybackSession(registration: PlaybackSessionRegistration, elementRef: {
-        current: unknown;
-    }): void;
-}
-type MediaActionKind = "share" | "download" | "copy" | "open";
-interface MediaActionContext {
-    ref: MediaRefLike;
-    resolution: MediaResolution | null;
-    fileName?: string | undefined;
-    alt?: string | undefined;
-}
-interface MediaSharePopoverProps {
-    context: MediaActionContext;
-    onClose: () => void;
-}
-type MediaActionHandler = (ctx: MediaActionContext) => Promise<void>;
-interface MediaActionsPort {
-    /**
-     * Quick-share handler (copy a share link, open the native share sheet…).
-     * Implementations obtain URLs ONLY via `MediaClient.shareableUrl` /
-     * durable identities — never a signed URL (law 4).
-     */
-    share?: MediaActionHandler | undefined;
-    download?: MediaActionHandler | undefined;
-    copy?: MediaActionHandler | undefined;
-    open?: MediaActionHandler | undefined;
-    /**
-     * Rich share UI body — the slot the associations package fills. When
-     * present, the shells open it instead of (or on top of) the `share`
-     * handler. Receives {@link MediaSharePopoverProps}.
-     */
-    SharePopover?: MediaSlotComponent<MediaSharePopoverProps> | undefined;
-}
-interface MediaHostPorts {
-    playbackSession?: PlaybackSessionPort | undefined;
-    actions?: MediaActionsPort | undefined;
-    /** Web host may pass a next/image adapter; default is a plain `<img>`. */
-    ImageComponent?: MediaSlotComponent<MediaImageComponentProps> | undefined;
-}
-
-/**
- * src/core/use-media-upload.ts — the React-side upload primitive.
- *
- * Ported from matrx-frontend `handler/hooks/useFileUpload.ts` with two seam
- * inversions: the transport is `MediaClient.upload` (never touched directly),
- * and the multi-file pre-flight (SHA-256 dedup dialog) is the client's
- * optional `uploadMany` — when absent, the batch runs sequentially through
- * `upload` with per-file results.
- *
- * Additionally exposes a per-file `entries` tray state (name, size, bytes,
- * status) so the dropzone's UploadProgressList works without any app store —
- * the Redux `selectVisibleUploads` coupling of the original, inverted.
- */
-
-interface MediaUploadProgress {
-    loaded: number;
-    total: number;
-    ratio: number;
-}
-type MediaUploadEntryStatus = "uploading" | "success" | "error";
-interface MediaUploadEntry {
-    id: string;
-    fileName: string;
-    fileSize: number;
-    bytesUploaded: number;
-    status: MediaUploadEntryStatus;
-    error: string | null;
-    fileId: string | null;
-    completedAt: number | null;
-}
-interface UseMediaUploadResult {
-    /** Upload one file/blob. Returns the durable identity. */
-    upload: (file: File | Blob, opts?: MediaUploadOptions) => Promise<MediaUploadResult>;
-    /**
-     * Upload many files. Uses the client's `uploadMany` (host pre-flight /
-     * dedup dialog) when implemented; otherwise a sequential per-file loop with
-     * real per-file error messages.
-     */
-    uploadMany: (files: File[], opts?: MediaUploadOptions) => Promise<MediaMultiUploadResult>;
-    uploading: boolean;
-    progress: MediaUploadProgress | null;
-    result: MediaUploadResult | null;
-    error: Error | null;
-    /** Live per-file tray entries for progress UI. */
-    entries: MediaUploadEntry[];
-    clearEntry: (id: string) => void;
-    reset: () => void;
-}
-declare function useMediaUpload(): UseMediaUploadResult;
-
-export { type DurableSrc as D, type MediaClient as M, type UseMediaUploadResult as U, type MediaHostPorts as a, type MediaRefLike as b, type MediaResolution as c, type MediaUnavailableReason as d, type MediaActionContext as e, type MediaActionKind as f, type MediaSlotComponent as g, type MediaSharePopoverProps as h, type MediaUploadEntry as i, type MediaUploadEntryStatus as j, type MediaUploadProgress as k, type MediaUploadOptions as l, useMediaUpload as u };