@ai-matrx/media 0.4.4 → 0.5.0

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/types.ts"],"sourcesContent":["/**\n * @ai-matrx/media — the root types: the MediaClient port and the host ports.\n *\n * The package renders Matrx durable media; it NEVER talks to a network.\n * Everything data-shaped arrives through the injected {@link MediaClient}\n * (canonically implemented by `@ai-matrx/data/files`; any structural\n * implementation works — the strangler step wires it over an app's existing\n * file handler). The five file-handling laws are enforced here at the type\n * level:\n *\n *   1. Never fetch a media URL yourself — the package contains zero network\n *      primitives; bytes exist only via {@link MediaClient.getBlob}.\n *   2. Off-boundary code resolves media itself — every component takes a\n *      {@link MediaRefLike} and calls `resolve()` unconditionally. There is\n *      NO `src` prop on any component in this package.\n *   3. A signed URL is a handoff, never an identity — the only string that\n *      reaches a media element is the branded {@link DurableSrc}, which only\n *      a MediaClient implementation can mint (via {@link mintDurableSrc}).\n *   4. Public-facing media is persisted public, never signed —\n *      {@link MediaClient.shareableUrl} fails closed (`null` → the action\n *      renders disabled).\n *   5. One URL contract; the engine builds URLs — zero URL construction in\n *      this package; `resolve()` is the only door.\n */\n\n// ---------------------------------------------------------------------------\n// Identity\n// ---------------------------------------------------------------------------\n\n/** The canonical durable media reference. `file_id` is the identity. */\nexport interface MediaRef {\n  file_id?: string | null;\n  url?: string | null;\n  mime_type?: string | null;\n  metadata?: Record<string, unknown> | null;\n}\n\n/**\n * Identity in. A raw string is a fileId or an EXTERNAL public URL — never a\n * signed URL (the client's `resolve()` classifies and screams on one).\n */\nexport type MediaRefLike = MediaRef | string;\n\ndeclare const durable: unique symbol;\n\n/**\n * A URL that has passed through `MediaClient.resolve()` — the only string\n * type any media element in this package will bind. A caller cannot pass an\n * expiring URL through the package's types without an explicit unsafe cast.\n */\nexport type DurableSrc = string & { readonly [durable]: true };\n\n/**\n * Brand a URL as durable. FOR MediaClient IMPLEMENTATIONS ONLY — the\n * implementation must classify the URL first (the ONE signed-URL classifier\n * lives with the platform's files layer; never re-implement it here or in a\n * host). Calling this on an unclassified string defeats law 3.\n */\nexport function mintDurableSrc(url: string): DurableSrc {\n  return url as DurableSrc;\n}\n\n// ---------------------------------------------------------------------------\n// Resolution\n// ---------------------------------------------------------------------------\n\nexport type MediaKind = \"image\" | \"video\" | \"audio\" | \"file\";\n\nexport interface MediaResolution {\n  src: DurableSrc;\n  /** RN auth lane (`<Image source={{uri, headers}}>`); absent on web (cookie session). */\n  headers?: Record<string, string> | undefined;\n  mimeType?: string | undefined;\n  kind: MediaKind;\n  /**\n   * How pixels must travel. `\"element\"` (default): bind `src` directly to the\n   * media element. `\"blob\"`: the bytes require bearer auth the element cannot\n   * attach — consumers go through {@link MediaClient.getBlob} and render the\n   * returned object URL (the private-image lane).\n   */\n  transport?: \"element\" | \"blob\" | undefined;\n  /**\n   * A server-rendered thumbnail for this file, when the client knows one\n   * (Matrx: `FileRecord.thumbnail_url` / asset variants). Consumed by the\n   * thumbnail tier machine.\n   */\n  thumbnailSrc?: DurableSrc | undefined;\n  /**\n   * True when this is a permanent public CDN URL — lets a host-supplied\n   * `ImageComponent` (e.g. a next/image adapter) take the render, and marks\n   * the URL CORS-safe for element-level `crossOrigin`.\n   */\n  isCdn?: boolean | undefined;\n  /**\n   * Whether a load error can be recovered by the client's ONE retry policy\n   * (session-refresh → same-URL retry). False for foreign/external URLs —\n   * a session refresh can't resurrect someone else's link rot. Default true.\n   */\n  recoverable?: boolean | undefined;\n}\n\n/** Typed unavailable states — render-as-state, never thrown as incidents. */\nexport type MediaUnavailableReason =\n  | \"access_denied\"\n  | \"not_found\"\n  | \"deleted\"\n  | \"unknown\";\n\n// ---------------------------------------------------------------------------\n// Diagnostics — the terminal-failure capture contract (the 2026-08-30 outage\n// class: every private image failed, the honest unavailable panel rendered,\n// and NOTHING reached the host's error system because the package had no\n// diagnostics port). Per C22 the capture logic lives IN the package; a host\n// binds only a sink. Absent sink → the package console.errors the same\n// structured payload once per failure — a media failure is NEVER silent.\n// ---------------------------------------------------------------------------\n\n/** Where in the pipeline a media failure surfaced. */\nexport type MediaFailurePhase =\n  /** `MediaClient.resolve()` refused the ref (threw). */\n  | \"resolve\"\n  /** The client's session bootstrap/mint failed (`recoverLoadError` rejected),\n   *  or the server reported an ephemeral cookie secret (warning). */\n  | \"session\"\n  /** `MediaClient.getBlob()` rejected — private-pixels bytes never arrived. */\n  | \"blob\"\n  /** The media element errored and recovery was exhausted or impossible. */\n  | \"element-load\"\n  /** The client's recovery machinery declined to retry on the first attempt. */\n  | \"recovery\";\n\n/** What the ONE retry policy did before the failure went terminal. */\nexport type MediaRetryOutcome =\n  /** Recovery was impossible (unrecoverable source) or was never reached. */\n  | \"not-attempted\"\n  /** The client granted a session-refresh retry and the retry ALSO failed. */\n  | \"retried\"\n  /** The recovery call itself threw/rejected. */\n  | \"recovery-failed\";\n\n/**\n * The strictly-typed structural payload every terminal media failure emits.\n * `mediaRef` is DURABLE IDENTITY ONLY — a `file:<id>` / query-stripped URL\n * key, NEVER a signed URL (signatures live in query strings, which\n * {@link failureMediaIdentity} removes).\n */\nexport interface MediaFailureInfo {\n  source: \"media\";\n  phase: MediaFailurePhase;\n  /** File id / ref key identity — never a signed URL. */\n  mediaRef: string;\n  /** HTTP status when known (e.g. from a structured client error). */\n  status?: number | undefined;\n  /** Outcome of the client's ONE retry policy, when the phase reached it. */\n  retryOutcome?: MediaRetryOutcome | undefined;\n  /** True for a dead render; false for a captured warning (ephemeral secret). */\n  terminal: boolean;\n  message: string;\n}\n\n/**\n * The host's error-capture sink. Bind `capture` to the app's error system\n * (matrx-frontend: `captureError` in lib/diagnostics/errorCaptureStore).\n * When absent, the package console.errors the same payload once per failure\n * (the loud default) — it never downgrades to silence.\n */\nexport interface MediaDiagnosticsPort {\n  capture?: ((info: MediaFailureInfo) => void) | undefined;\n}\n\n/** String verdicts of the ONE retry policy. */\nexport type MediaRecoveryVerdict = \"retry\" | \"terminal\";\n\n/**\n * Structured `recoverLoadError` result — optional; the bare string verdict\n * remains fully supported. Lets the client surface what it learned during the\n * session bootstrap without a second channel:\n *\n *   - `status` — HTTP status of the failed mint/probe, forwarded into the\n *     terminal {@link MediaFailureInfo};\n *   - `secretSource` — the `/files/session` mint response's `secret_source`\n *     when the server sends one (a matrx-connect field). `\"ephemeral\"` means\n *     the server signs cookies with a boot-generated secret: private renders\n *     WILL break across restarts/instances, and the package captures a\n *     non-terminal warning immediately instead of waiting for the outage.\n */\nexport interface MediaRecoveryReport {\n  verdict: MediaRecoveryVerdict;\n  status?: number | undefined;\n  secretSource?: string | undefined;\n}\n\n// ---------------------------------------------------------------------------\n// Bytes / upload\n// ---------------------------------------------------------------------------\n\nexport interface MediaBlobHandle {\n  /** `blob:` object URL safe for any browser API. */\n  url: string;\n  blob: Blob;\n  /** Release the handle. Implementations backed by a shared cache may no-op. */\n  release(): void;\n}\n\nexport interface MediaUploadOptions {\n  onProgress?: ((loaded: number, total: number) => void) | undefined;\n  fileName?: string | undefined;\n  mimeType?: string | undefined;\n  /** Host visibility vocabulary passes through structurally. */\n  visibility?: string | undefined;\n  parentFolderId?: string | null | undefined;\n  metadata?: Record<string, unknown> | undefined;\n}\n\n/** Upload → durable identity. `fileId` is required at compile time and runtime. */\nexport interface MediaUploadResult {\n  fileId: string;\n  ref: MediaRef;\n}\n\nexport interface MediaMultiUploadResult {\n  /** File ids for every successful upload. */\n  uploaded: string[];\n  /** Per-file failure with the real backend error message. */\n  failed: Array<{ name: string; error: string }>;\n  /** True when the host's pre-flight (e.g. a duplicate dialog) cancelled the batch. */\n  cancelled: boolean;\n}\n\n// ---------------------------------------------------------------------------\n// THE port — one structural interface, owned by this package, implemented by\n// the data layer (canonically `@ai-matrx/data/files`).\n// ---------------------------------------------------------------------------\n\nexport interface MediaClient {\n  /**\n   * Synchronous durable-URL build + classification. Returns `null` when the\n   * ref carries no usable identity (components render their fallback).\n   * THROWS (and screams via its own diagnostics sink) on a signed/expiring\n   * URL — the D108 guard lives behind this door.\n   */\n  resolve(ref: MediaRefLike): MediaResolution | null;\n  /** Bytes for canvas/crossOrigin/private-pixel consumers. */\n  getBlob(ref: MediaRefLike): Promise<MediaBlobHandle>;\n  /**\n   * Session bootstrap + the ONE retry policy: refresh-then-same-URL-retry,\n   * second failure terminal. Called by the package's onError path, never\n   * re-implemented.\n   */\n  recoverLoadError(\n    src: DurableSrc,\n    attempt: number,\n  ): Promise<MediaRecoveryVerdict | MediaRecoveryReport>;\n  /** Upload → durable identity. */\n  upload(file: File | Blob, opts?: MediaUploadOptions): Promise<MediaUploadResult>;\n  /**\n   * Optional batch upload with host pre-flight (dedup dialogs etc.). When\n   * absent, `useMediaUpload().uploadMany` falls back to sequential `upload`.\n   */\n  uploadMany?(files: File[], opts?: MediaUploadOptions): Promise<MediaMultiUploadResult>;\n  /** Share affordances — fails closed (null), never emits a signed URL. */\n  shareableUrl(ref: MediaRefLike): Promise<string | null>;\n  /** Typed unavailable states — render-as-state, never thrown as incidents. */\n  classifyError(err: unknown): MediaUnavailableReason;\n}\n\n// ---------------------------------------------------------------------------\n// Host ports — all optional, all defaulting to inert.\n// ---------------------------------------------------------------------------\n\n/**\n * Structural component slot. `(props) => unknown` keeps the root entry free\n * of React type imports; any React function component satisfies it.\n */\nexport type MediaSlotComponent<P> = (props: P) => unknown;\n\nexport interface MediaImageComponentProps {\n  src: string;\n  alt: string;\n  width: number;\n  height: number;\n  className?: string | undefined;\n  onError?: ((event: unknown) => void) | undefined;\n  onClick?: ((event: unknown) => void) | undefined;\n  onKeyDown?: ((event: unknown) => void) | undefined;\n  role?: string | undefined;\n  tabIndex?: number | undefined;\n}\n\nexport interface PlaybackSessionRegistration {\n  isPlaying: boolean;\n  source: string;\n  label: string;\n  trackKey?: string | undefined;\n}\n\n/**\n * The host's audio system (exclusive-playback lock, output-sink routing).\n * Both members are HOOKS — the package calls them unconditionally on every\n * render of a media element, so implementations must obey the Rules of Hooks\n * and the port object must be referentially stable.\n */\nexport interface PlaybackSessionPort {\n  /**\n   * Returns a ref callback for the underlying media element (routes audio\n   * output / setSinkId on hosts that support it) and forwards to the caller's\n   * own element ref.\n   */\n  useMediaElementSink(\n    forward:\n      | ((node: unknown) => void)\n      | { current: unknown }\n      | null\n      | undefined,\n  ): (node: unknown) => void;\n  /** Joins the host's unified playback session for the element. */\n  usePlaybackSession(\n    registration: PlaybackSessionRegistration,\n    elementRef: { current: unknown },\n  ): void;\n}\n\n// ---------------------------------------------------------------------------\n// THE SHARE MANDATE (C19) — the complete headless media-actions contract.\n//\n// v0.1 ships this contract plus toolbar/lightbox shells wired to it, typed so\n// the associations/sharing package can plug in WITHOUT a media release: it\n// implements MediaActionsPort (handlers and/or the SharePopover body) and the\n// host injects it through MediaHostPorts. Nothing here may change shape in a\n// breaking way for that wave.\n// ---------------------------------------------------------------------------\n\nexport type MediaActionKind = \"share\" | \"download\" | \"copy\" | \"open\";\n\nexport interface MediaActionContext {\n  ref: MediaRefLike;\n  resolution: MediaResolution | null;\n  fileName?: string | undefined;\n  alt?: string | undefined;\n}\n\nexport interface MediaSharePopoverProps {\n  context: MediaActionContext;\n  onClose: () => void;\n}\n\nexport type MediaActionHandler = (ctx: MediaActionContext) => Promise<void>;\n\nexport interface MediaActionsPort {\n  /**\n   * Quick-share handler (copy a share link, open the native share sheet…).\n   * Implementations obtain URLs ONLY via `MediaClient.shareableUrl` /\n   * durable identities — never a signed URL (law 4).\n   */\n  share?: MediaActionHandler | undefined;\n  download?: MediaActionHandler | undefined;\n  copy?: MediaActionHandler | undefined;\n  open?: MediaActionHandler | undefined;\n  /**\n   * Rich share UI body — the slot the associations package fills. When\n   * present, the shells open it instead of (or on top of) the `share`\n   * handler. Receives {@link MediaSharePopoverProps}.\n   */\n  SharePopover?: MediaSlotComponent<MediaSharePopoverProps> | undefined;\n}\n\nexport interface MediaHostPorts {\n  playbackSession?: PlaybackSessionPort | undefined;\n  actions?: MediaActionsPort | undefined;\n  /** Web host may pass a next/image adapter; default is a plain `<img>`. */\n  ImageComponent?: MediaSlotComponent<MediaImageComponentProps> | undefined;\n  /**\n   * Error-capture sink for terminal media failures (and the ephemeral-secret\n   * warning). Bind to the host's error system; absent → loud console.error\n   * default. See {@link MediaDiagnosticsPort}.\n   */\n  diagnostics?: MediaDiagnosticsPort | undefined;\n}\n"],"mappings":";AA0DO,SAAS,eAAe,KAAyB;AACtD,SAAO;AACT;","names":[]}
+{"version":3,"sources":["../src/types.ts"],"sourcesContent":["/**\n * @ai-matrx/media — the root types: the MediaClient port and the host ports.\n *\n * The package renders Matrx durable media; it NEVER talks to a network.\n * Everything data-shaped arrives through the injected {@link MediaClient}\n * (canonically implemented by `@ai-matrx/data/files`; any structural\n * implementation works — the strangler step wires it over an app's existing\n * file handler). The five file-handling laws are enforced here at the type\n * level:\n *\n *   1. Never fetch a media URL yourself — the package contains zero network\n *      primitives; bytes exist only via {@link MediaClient.getBlob}.\n *   2. Off-boundary code resolves media itself — every component takes a\n *      {@link MediaRefLike} and calls `resolve()` unconditionally. There is\n *      NO `src` prop on any component in this package.\n *   3. A signed URL is a handoff, never an identity — the only string that\n *      reaches a media element is the branded {@link DurableSrc}, which only\n *      a MediaClient implementation can mint (via {@link mintDurableSrc}).\n *   4. Public-facing media is persisted public, never signed —\n *      {@link MediaClient.shareableUrl} fails closed (`null` → the action\n *      renders disabled).\n *   5. One URL contract; the engine builds URLs — zero URL construction in\n *      this package; `resolve()` is the only door.\n */\n\n// ---------------------------------------------------------------------------\n// Identity\n// ---------------------------------------------------------------------------\n\n/** The canonical durable media reference. `file_id` is the identity. */\nexport interface MediaRef {\n  file_id?: string | null;\n  url?: string | null;\n  mime_type?: string | null;\n  metadata?: Record<string, unknown> | null;\n}\n\n/**\n * Identity in. A raw string is a fileId or an EXTERNAL public URL — never a\n * signed URL (the client's `resolve()` classifies and screams on one).\n */\nexport type MediaRefLike = MediaRef | string;\n\ndeclare const durable: unique symbol;\n\n/**\n * A URL that has passed through `MediaClient.resolve()` — the only string\n * type any media element in this package will bind. A caller cannot pass an\n * expiring URL through the package's types without an explicit unsafe cast.\n */\nexport type DurableSrc = string & { readonly [durable]: true };\n\n/**\n * Brand a URL as durable. FOR MediaClient IMPLEMENTATIONS ONLY — the\n * implementation must classify the URL first (the ONE signed-URL classifier\n * lives with the platform's files layer; never re-implement it here or in a\n * host). Calling this on an unclassified string defeats law 3.\n */\nexport function mintDurableSrc(url: string): DurableSrc {\n  return url as DurableSrc;\n}\n\n// ---------------------------------------------------------------------------\n// Resolution\n// ---------------------------------------------------------------------------\n\nexport type MediaKind = \"image\" | \"video\" | \"audio\" | \"file\";\n\nexport interface MediaResolution {\n  src: DurableSrc;\n  /** RN auth lane (`<Image source={{uri, headers}}>`); absent on web (cookie session). */\n  headers?: Record<string, string> | undefined;\n  mimeType?: string | undefined;\n  kind: MediaKind;\n  /**\n   * How pixels must travel. `\"element\"` (default): bind `src` directly to the\n   * media element. `\"blob\"`: the bytes require bearer auth the element cannot\n   * attach — consumers go through {@link MediaClient.getBlob} and render the\n   * returned object URL (the private-image lane).\n   */\n  transport?: \"element\" | \"blob\" | undefined;\n  /**\n   * A server-rendered thumbnail for this file, when the client knows one\n   * (Matrx: `FileRecord.thumbnail_url` / asset variants). Consumed by the\n   * thumbnail tier machine.\n   */\n  thumbnailSrc?: DurableSrc | undefined;\n  /**\n   * True when this is a permanent public CDN URL — lets a host-supplied\n   * `ImageComponent` (e.g. a next/image adapter) take the render, and marks\n   * the URL CORS-safe for element-level `crossOrigin`.\n   */\n  isCdn?: boolean | undefined;\n  /**\n   * Whether a load error can be recovered by the client's ONE retry policy\n   * (session-refresh → same-URL retry). False for foreign/external URLs —\n   * a session refresh can't resurrect someone else's link rot. Default true.\n   */\n  recoverable?: boolean | undefined;\n}\n\n/** Typed unavailable states — render-as-state, never thrown as incidents. */\nexport type MediaUnavailableReason =\n  | \"access_denied\"\n  | \"not_found\"\n  | \"deleted\"\n  | \"unknown\";\n\n// ---------------------------------------------------------------------------\n// Diagnostics — the terminal-failure capture contract (the 2026-08-30 outage\n// class: every private image failed, the honest unavailable panel rendered,\n// and NOTHING reached the host's error system because the package had no\n// diagnostics port). Per C22 the capture logic lives IN the package; a host\n// binds only a sink. Absent sink → the package console.errors the same\n// structured payload once per failure — a media failure is NEVER silent.\n// ---------------------------------------------------------------------------\n\n/** Where in the pipeline a media failure surfaced. */\nexport type MediaFailurePhase =\n  /** `MediaClient.resolve()` refused the ref (threw). */\n  | \"resolve\"\n  /** The client's session bootstrap/mint failed (`recoverLoadError` rejected),\n   *  or the server reported an ephemeral cookie secret (warning). */\n  | \"session\"\n  /** `MediaClient.getBlob()` rejected — private-pixels bytes never arrived. */\n  | \"blob\"\n  /** The media element errored and recovery was exhausted or impossible. */\n  | \"element-load\"\n  /** The client's recovery machinery declined to retry on the first attempt. */\n  | \"recovery\";\n\n/** What the ONE retry policy did before the failure went terminal. */\nexport type MediaRetryOutcome =\n  /** Recovery was impossible (unrecoverable source) or was never reached. */\n  | \"not-attempted\"\n  /** The client granted a session-refresh retry and the retry ALSO failed. */\n  | \"retried\"\n  /** The recovery call itself threw/rejected. */\n  | \"recovery-failed\";\n\n/**\n * The strictly-typed structural payload every terminal media failure emits.\n * `mediaRef` is DURABLE IDENTITY ONLY — a `file:<id>` / query-stripped URL\n * key, NEVER a signed URL (signatures live in query strings, which\n * {@link failureMediaIdentity} removes).\n */\nexport interface MediaFailureInfo {\n  source: \"media\";\n  phase: MediaFailurePhase;\n  /** File id / ref key identity — never a signed URL. */\n  mediaRef: string;\n  /** HTTP status when known (e.g. from a structured client error). */\n  status?: number | undefined;\n  /** Outcome of the client's ONE retry policy, when the phase reached it. */\n  retryOutcome?: MediaRetryOutcome | undefined;\n  /** True for a dead render; false for a captured warning (ephemeral secret). */\n  terminal: boolean;\n  message: string;\n}\n\n/**\n * The host's error-capture sink. Bind `capture` to the app's error system\n * (matrx-frontend: `captureError` in lib/diagnostics/errorCaptureStore).\n * When absent, the package console.errors the same payload once per failure\n * (the loud default) — it never downgrades to silence.\n */\nexport interface MediaDiagnosticsPort {\n  capture?: ((info: MediaFailureInfo) => void) | undefined;\n}\n\n/** String verdicts of the ONE retry policy. */\nexport type MediaRecoveryVerdict = \"retry\" | \"terminal\";\n\n/**\n * Structured `recoverLoadError` result — optional; the bare string verdict\n * remains fully supported. Lets the client surface what it learned during the\n * session bootstrap without a second channel:\n *\n *   - `status` — HTTP status of the failed mint/probe, forwarded into the\n *     terminal {@link MediaFailureInfo};\n *   - `secretSource` — the `/files/session` mint response's `secret_source`\n *     when the server sends one (a matrx-connect field). `\"ephemeral\"` means\n *     the server signs cookies with a boot-generated secret: private renders\n *     WILL break across restarts/instances, and the package captures a\n *     non-terminal warning immediately instead of waiting for the outage.\n */\nexport interface MediaRecoveryReport {\n  verdict: MediaRecoveryVerdict;\n  status?: number | undefined;\n  secretSource?: string | undefined;\n}\n\n// ---------------------------------------------------------------------------\n// Bytes / upload\n// ---------------------------------------------------------------------------\n\nexport interface MediaBlobHandle {\n  /** `blob:` object URL safe for any browser API. */\n  url: string;\n  blob: Blob;\n  /** Release the handle. Implementations backed by a shared cache may no-op. */\n  release(): void;\n}\n\nexport interface MediaUploadOptions {\n  onProgress?: ((loaded: number, total: number) => void) | undefined;\n  fileName?: string | undefined;\n  mimeType?: string | undefined;\n  /** Host visibility vocabulary passes through structurally. */\n  visibility?: string | undefined;\n  parentFolderId?: string | null | undefined;\n  metadata?: Record<string, unknown> | undefined;\n}\n\n/** Upload → durable identity. `fileId` is required at compile time and runtime. */\nexport interface MediaUploadResult {\n  fileId: string;\n  ref: MediaRef;\n}\n\nexport interface MediaMultiUploadResult {\n  /** File ids for every successful upload. */\n  uploaded: string[];\n  /** Per-file failure with the real backend error message. */\n  failed: Array<{ name: string; error: string }>;\n  /** True when the host's pre-flight (e.g. a duplicate dialog) cancelled the batch. */\n  cancelled: boolean;\n}\n\n// ---------------------------------------------------------------------------\n// THE port — one structural interface, owned by this package, implemented by\n// the data layer (canonically `@ai-matrx/data/files`).\n// ---------------------------------------------------------------------------\n\nexport interface MediaClient {\n  /**\n   * Synchronous durable-URL build + classification. Returns `null` when the\n   * ref carries no usable identity (components render their fallback).\n   * THROWS (and screams via its own diagnostics sink) on a signed/expiring\n   * URL — the D108 guard lives behind this door.\n   */\n  resolve(ref: MediaRefLike): MediaResolution | null;\n  /** Bytes for canvas/crossOrigin/private-pixel consumers. */\n  getBlob(ref: MediaRefLike): Promise<MediaBlobHandle>;\n  /**\n   * Session bootstrap + the ONE retry policy: refresh-then-same-URL-retry,\n   * second failure terminal. Called by the package's onError path, never\n   * re-implemented.\n   */\n  recoverLoadError(\n    src: DurableSrc,\n    attempt: number,\n  ): Promise<MediaRecoveryVerdict | MediaRecoveryReport>;\n  /**\n   * Optional object-URL recovery policy for private blob-backed media.\n   * The client decides whether the durable ref should be re-read; older\n   * clients may omit this and fail terminally.\n   */\n  recoverBlobLoadError?(\n    ref: MediaRefLike,\n    attempt: number,\n  ): Promise<MediaRecoveryVerdict>;\n  /** Upload → durable identity. */\n  upload(file: File | Blob, opts?: MediaUploadOptions): Promise<MediaUploadResult>;\n  /**\n   * Optional batch upload with host pre-flight (dedup dialogs etc.). When\n   * absent, `useMediaUpload().uploadMany` falls back to sequential `upload`.\n   */\n  uploadMany?(files: File[], opts?: MediaUploadOptions): Promise<MediaMultiUploadResult>;\n  /** Share affordances — fails closed (null), never emits a signed URL. */\n  shareableUrl(ref: MediaRefLike): Promise<string | null>;\n  /** Typed unavailable states — render-as-state, never thrown as incidents. */\n  classifyError(err: unknown): MediaUnavailableReason;\n}\n\n// ---------------------------------------------------------------------------\n// Host ports — all optional, all defaulting to inert.\n// ---------------------------------------------------------------------------\n\n/**\n * Structural component slot. `(props) => unknown` keeps the root entry free\n * of React type imports; any React function component satisfies it.\n */\nexport type MediaSlotComponent<P> = (props: P) => unknown;\n\nexport interface MediaImageComponentProps {\n  src: string;\n  alt: string;\n  width: number;\n  height: number;\n  className?: string | undefined;\n  onError?: ((event: unknown) => void) | undefined;\n  onClick?: ((event: unknown) => void) | undefined;\n  onKeyDown?: ((event: unknown) => void) | undefined;\n  role?: string | undefined;\n  tabIndex?: number | undefined;\n}\n\nexport interface PlaybackSessionRegistration {\n  isPlaying: boolean;\n  source: string;\n  label: string;\n  trackKey?: string | undefined;\n}\n\n/**\n * The host's audio system (exclusive-playback lock, output-sink routing).\n * Both members are HOOKS — the package calls them unconditionally on every\n * render of a media element, so implementations must obey the Rules of Hooks\n * and the port object must be referentially stable.\n */\nexport interface PlaybackSessionPort {\n  /**\n   * Returns a ref callback for the underlying media element (routes audio\n   * output / setSinkId on hosts that support it) and forwards to the caller's\n   * own element ref.\n   */\n  useMediaElementSink(\n    forward:\n      | ((node: unknown) => void)\n      | { current: unknown }\n      | null\n      | undefined,\n  ): (node: unknown) => void;\n  /** Joins the host's unified playback session for the element. */\n  usePlaybackSession(\n    registration: PlaybackSessionRegistration,\n    elementRef: { current: unknown },\n  ): void;\n}\n\n// ---------------------------------------------------------------------------\n// THE SHARE MANDATE (C19) — the complete headless media-actions contract.\n//\n// v0.1 ships this contract plus toolbar/lightbox shells wired to it, typed so\n// the associations/sharing package can plug in WITHOUT a media release: it\n// implements MediaActionsPort (handlers and/or the SharePopover body) and the\n// host injects it through MediaHostPorts. Nothing here may change shape in a\n// breaking way for that wave.\n// ---------------------------------------------------------------------------\n\nexport type MediaActionKind = \"share\" | \"download\" | \"copy\" | \"open\";\n\nexport interface MediaActionContext {\n  ref: MediaRefLike;\n  resolution: MediaResolution | null;\n  fileName?: string | undefined;\n  alt?: string | undefined;\n}\n\nexport interface MediaSharePopoverProps {\n  context: MediaActionContext;\n  onClose: () => void;\n}\n\nexport type MediaActionHandler = (ctx: MediaActionContext) => Promise<void>;\n\nexport interface MediaActionsPort {\n  /**\n   * Quick-share handler (copy a share link, open the native share sheet…).\n   * Implementations obtain URLs ONLY via `MediaClient.shareableUrl` /\n   * durable identities — never a signed URL (law 4).\n   */\n  share?: MediaActionHandler | undefined;\n  download?: MediaActionHandler | undefined;\n  copy?: MediaActionHandler | undefined;\n  open?: MediaActionHandler | undefined;\n  /**\n   * Rich share UI body — the slot the associations package fills. When\n   * present, the shells open it instead of (or on top of) the `share`\n   * handler. Receives {@link MediaSharePopoverProps}.\n   */\n  SharePopover?: MediaSlotComponent<MediaSharePopoverProps> | undefined;\n}\n\nexport interface MediaHostPorts {\n  playbackSession?: PlaybackSessionPort | undefined;\n  actions?: MediaActionsPort | undefined;\n  /** Web host may pass a next/image adapter; default is a plain `<img>`. */\n  ImageComponent?: MediaSlotComponent<MediaImageComponentProps> | undefined;\n  /**\n   * Error-capture sink for terminal media failures (and the ephemeral-secret\n   * warning). Bind to the host's error system; absent → loud console.error\n   * default. See {@link MediaDiagnosticsPort}.\n   */\n  diagnostics?: MediaDiagnosticsPort | undefined;\n}\n"],"mappings":";AA0DO,SAAS,eAAe,KAAyB;AACtD,SAAO;AACT;","names":[]}

package/dist/react.cjs

@@ -66,7 +66,6 @@ __export(react_exports, {
   VolumeXIcon: () => VolumeXIcon,
   XIcon: () => XIcon,
   cn: () => cn,
-  formatFileSize: () => formatFileSize,
   useMediaDropzone: () => useMediaDropzone
 });
 module.exports = __toCommonJS(react_exports);
@@ -535,7 +534,7 @@ function FileIcon2({
 }
 
 // src/react/inline-media-ref.tsx
-var import_react6 = require("react");
+var import_react7 = require("react");
 
 // src/core/context.ts
 var import_react = require("react");
@@ -681,8 +680,83 @@ function useMediaBlob(ref) {
   };
 }
 
-// src/core/use-media-load-recovery.ts
+// src/core/use-media-blob-load-recovery.ts
 var import_react4 = require("react");
+function useMediaBlobLoadRecovery(ref, source, options) {
+  const client = useMediaClient();
+  const capture = useMediaFailureCapture();
+  const refKey = stableRefKey(ref);
+  const [failed, setFailed] = (0, import_react4.useState)(false);
+  const attemptRef = (0, import_react4.useRef)(0);
+  const recoveryInFlightRef = (0, import_react4.useRef)(false);
+  const onRetry = options.onRetry;
+  const onTerminal = options.onTerminal;
+  (0, import_react4.useEffect)(() => {
+    attemptRef.current = 0;
+    recoveryInFlightRef.current = false;
+    setFailed(false);
+  }, [refKey]);
+  (0, import_react4.useEffect)(() => {
+    recoveryInFlightRef.current = false;
+  }, [source]);
+  const finishTerminal = (0, import_react4.useCallback)(
+    (event, attempt, message) => {
+      setFailed(true);
+      capture({
+        phase: "element-load",
+        mediaRef: failureMediaIdentity(ref ?? null, source),
+        terminal: true,
+        retryOutcome: attempt > 1 ? "retried" : "not-attempted",
+        message
+      });
+      onTerminal?.(event);
+    },
+    [capture, onTerminal, ref, source]
+  );
+  const onLoadError = (0, import_react4.useCallback)(
+    (event) => {
+      if (recoveryInFlightRef.current || !source) return;
+      recoveryInFlightRef.current = true;
+      attemptRef.current += 1;
+      const attempt = attemptRef.current;
+      const recover = client.recoverBlobLoadError;
+      if (!ref || !recover) {
+        finishTerminal(
+          event,
+          attempt,
+          "blob-backed media element failed to load and the client exposes no object-URL recovery policy"
+        );
+        return;
+      }
+      recover(ref, attempt).then(
+        (verdict) => {
+          if (verdict === "retry") {
+            setFailed(false);
+            onRetry();
+            return;
+          }
+          finishTerminal(
+            event,
+            attempt,
+            attempt > 1 ? "blob-backed media element failed after the client-approved re-read" : "blob-backed media recovery was declined on the first attempt"
+          );
+        },
+        (err) => {
+          finishTerminal(
+            event,
+            attempt,
+            `blob-backed media recovery failed: ${err instanceof Error ? err.message : String(err ?? "unknown error")}`
+          );
+        }
+      );
+    },
+    [client, finishTerminal, onRetry, ref, source]
+  );
+  return { onLoadError, failed };
+}
+
+// src/core/use-media-load-recovery.ts
+var import_react5 = require("react");
 
 // src/types.ts
 function mintDurableSrc(url) {
@@ -700,14 +774,14 @@ function useMediaLoadRecovery(src, options) {
   const recoverable = options?.recoverable !== false;
   const onTerminal = options?.onTerminal;
   const failureRef = options?.failureRef;
-  const [result, setResult] = (0, import_react4.useState)({ source: src, retryKey: 0, failed: false });
-  const attemptRef = (0, import_react4.useRef)(0);
-  const recoveryInFlightRef = (0, import_react4.useRef)(false);
-  (0, import_react4.useEffect)(() => {
+  const [result, setResult] = (0, import_react5.useState)({ source: src, retryKey: 0, failed: false });
+  const attemptRef = (0, import_react5.useRef)(0);
+  const recoveryInFlightRef = (0, import_react5.useRef)(false);
+  (0, import_react5.useEffect)(() => {
     attemptRef.current = 0;
     recoveryInFlightRef.current = false;
   }, [src]);
-  (0, import_react4.useLayoutEffect)(() => {
+  (0, import_react5.useLayoutEffect)(() => {
     recoveryInFlightRef.current = false;
   }, [result.retryKey]);
   const identity = () => failureMediaIdentity(failureRef ?? null, src);
@@ -781,12 +855,12 @@ function useMediaLoadRecovery(src, options) {
 }
 
 // src/core/use-media-resolution.ts
-var import_react5 = require("react");
+var import_react6 = require("react");
 function useMediaResolution(ref) {
   const client = useMediaClient();
   const capture = useMediaFailureCapture();
   const refKey = stableRefKey(ref);
-  const { state, failureMessage } = (0, import_react5.useMemo)(() => {
+  const { state, failureMessage } = (0, import_react6.useMemo)(() => {
     if (!ref) {
       return {
         state: { resolution: null, status: "empty", reason: null },
@@ -816,7 +890,7 @@ function useMediaResolution(ref) {
       };
     }
   }, [client, refKey]);
-  (0, import_react5.useEffect)(() => {
+  (0, import_react6.useEffect)(() => {
     if (state.status !== "unavailable") return;
     capture({
       phase: "resolve",
@@ -871,7 +945,7 @@ function prettifyUrl(url) {
 }
 var INERT_PLAYBACK = {
   useMediaElementSink(forward) {
-    return (0, import_react6.useCallback)(
+    return (0, import_react7.useCallback)(
       (node) => {
         if (!forward) return;
         if (typeof forward === "function") forward(node);
@@ -922,7 +996,7 @@ function InformativeErrorFallback({
 }) {
   const capture = useMediaFailureCapture();
   const identity = failureMediaIdentity(mediaRef ?? null, url);
-  (0, import_react6.useEffect)(() => {
+  (0, import_react7.useEffect)(() => {
     capture({
       phase: failurePhase,
       mediaRef: identity,
@@ -986,10 +1060,10 @@ function InformativeErrorPanel({
   icon,
   tooltip
 }) {
-  const [copied, setCopied] = (0, import_react6.useState)(false);
+  const [copied, setCopied] = (0, import_react7.useState)(false);
   const isFill = dimensions === "fill";
   const { host, tail } = prettifyUrl(url);
-  const handleCopy = (0, import_react6.useCallback)(
+  const handleCopy = (0, import_react7.useCallback)(
     (event) => {
       event.stopPropagation();
       event.preventDefault();
@@ -1106,16 +1180,25 @@ function InlineMediaRef({
   );
   const blob = useMediaBlob(needsBlob ? mediaRef : null);
   const url = needsBlob ? blob.url : resolution?.src ?? null;
+  const terminalCallback = (event) => onError?.(
+    event
+  );
   const recovery = useMediaLoadRecovery(url, {
-    recoverable: !needsBlob && resolution?.recoverable !== false,
+    recoverable: resolution?.recoverable !== false,
     failureRef: mediaRef,
-    onTerminal: (event) => onError?.(
-      event
-    )
+    onTerminal: terminalCallback
   });
+  const blobRecovery = useMediaBlobLoadRecovery(
+    needsBlob ? mediaRef : null,
+    needsBlob ? url : null,
+    {
+      onRetry: blob.retry,
+      onTerminal: terminalCallback
+    }
+  );
   const playback = ports.playbackSession ?? INERT_PLAYBACK;
-  const sessionElRef = (0, import_react6.useRef)(null);
-  const [isMediaPlaying, setIsMediaPlaying] = (0, import_react6.useState)(false);
+  const sessionElRef = (0, import_react7.useRef)(null);
+  const [isMediaPlaying, setIsMediaPlaying] = (0, import_react7.useState)(false);
   const portSinkRef = playback.useMediaElementSink(
     mediaElementRef
   );
@@ -1123,7 +1206,7 @@ function InlineMediaRef({
     sessionElRef.current = node;
     portSinkRef(node);
   };
-  const trackKey = (0, import_react6.useMemo)(() => {
+  const trackKey = (0, import_react7.useMemo)(() => {
     if (mediaRef && typeof mediaRef === "object" && mediaRef.file_id) {
       return mediaRef.file_id;
     }
@@ -1146,8 +1229,10 @@ function InlineMediaRef({
   const mediaResolutionError = status === "unavailable" ? reason ?? "unknown" : blob.error ?? null;
   const dimensions = resolveDimensions(size);
   const isFill = dimensions === "fill";
-  const hasLoadError = recovery.failed;
-  const handleLoadError = recovery.onLoadError;
+  const activeRecovery = needsBlob ? blobRecovery : recovery;
+  const retryKey = needsBlob ? 0 : recovery.retryKey;
+  const hasLoadError = activeRecovery.failed;
+  const handleLoadError = activeRecovery.onLoadError;
   const defaultIcon = elementType === "video" ? /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(FileVideoIcon, { className: "h-1/2 w-1/2" }) : elementType === "audio" ? /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(FileAudioIcon, { className: "h-1/2 w-1/2" }) : mediaRef ? /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(ImageIcon, { className: "h-1/2 w-1/2" }) : /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(FileIcon, { className: "h-1/2 w-1/2" });
   const unresolvedDisplayUrl = mediaRef && typeof mediaRef === "object" && mediaRef.file_id ? `file:${mediaRef.file_id}` : "unresolved-media";
   if (!url) {
@@ -1283,7 +1368,7 @@ function InlineMediaRef({
         ...mediaSessionEvents,
         ...interactiveProps
       },
-      recovery.retryKey
+      retryKey
     );
   }
   if (elementType === "audio") {
@@ -1304,7 +1389,7 @@ function InlineMediaRef({
         crossOrigin,
         ...interactiveProps
       },
-      recovery.retryKey
+      retryKey
     );
   }
   const needsPlainImg = !!onLoad || !!mediaElementRef || !!crossOrigin;
@@ -1322,7 +1407,7 @@ function InlineMediaRef({
         onError: handleLoadError,
         ...interactiveProps
       },
-      recovery.retryKey
+      retryKey
     );
   }
   return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
@@ -1338,20 +1423,20 @@ function InlineMediaRef({
       crossOrigin,
       ...interactiveProps
     },
-    recovery.retryKey
+    retryKey
   );
 }
 
 // src/react/media-thumbnail.tsx
-var import_react8 = require("react");
+var import_react9 = require("react");
 
 // src/core/use-thumbnail-source.ts
-var import_react7 = require("react");
+var import_react8 = require("react");
 function useThumbnailSource(ref, options = {}) {
   const { thumbnailUrl, allowSourceFallback = true } = options;
   const client = useMediaClient();
   const { resolution } = useMediaResolution(ref);
-  const explicitThumb = (0, import_react7.useMemo)(() => {
+  const explicitThumb = (0, import_react8.useMemo)(() => {
     if (!thumbnailUrl) return null;
     try {
       return client.resolve(thumbnailUrl);
@@ -1501,8 +1586,8 @@ function VideoPosterThumb({
     recoverable,
     failureRef: mediaRef
   });
-  const ref = (0, import_react8.useRef)(null);
-  (0, import_react8.useEffect)(() => {
+  const ref = (0, import_react9.useRef)(null);
+  (0, import_react9.useEffect)(() => {
     const v = ref.current;
     if (!v) return void 0;
     const onMeta = () => {
@@ -1531,7 +1616,7 @@ function VideoPosterThumb({
 }
 
 // src/react/use-media-dropzone.ts
-var import_react9 = require("react");
+var import_react10 = require("react");
 function matchesAccept(file, accept) {
   if (!accept || accept.length === 0) return true;
   const name = file.name.toLowerCase();
@@ -1555,16 +1640,16 @@ function useMediaDropzone(options) {
     disabled = false,
     multiple = true
   } = options;
-  const [isDragActive, setIsDragActive] = (0, import_react9.useState)(false);
-  const [pasteHighlight, setPasteHighlight] = (0, import_react9.useState)(false);
-  const dragDepth = (0, import_react9.useRef)(0);
-  const inputRef = (0, import_react9.useRef)(null);
-  const onFilesRef = (0, import_react9.useRef)(onFiles);
+  const [isDragActive, setIsDragActive] = (0, import_react10.useState)(false);
+  const [pasteHighlight, setPasteHighlight] = (0, import_react10.useState)(false);
+  const dragDepth = (0, import_react10.useRef)(0);
+  const inputRef = (0, import_react10.useRef)(null);
+  const onFilesRef = (0, import_react10.useRef)(onFiles);
   onFilesRef.current = onFiles;
-  const onRejectedRef = (0, import_react9.useRef)(onRejected);
+  const onRejectedRef = (0, import_react10.useRef)(onRejected);
   onRejectedRef.current = onRejected;
   const acceptKey = accept?.join(",") ?? "";
-  const filterFiles = (0, import_react9.useCallback)(
+  const filterFiles = (0, import_react10.useCallback)(
     (files) => {
       const accepted = [];
       const rejected = [];
@@ -1582,23 +1667,23 @@ function useMediaDropzone(options) {
     },
     [acceptKey, maxSize]
   );
-  const emit = (0, import_react9.useCallback)(
+  const emit = (0, import_react10.useCallback)(
     (files) => {
       const accepted = filterFiles(files);
       if (accepted.length) onFilesRef.current(accepted);
     },
     [filterFiles]
   );
-  const openPicker = (0, import_react9.useCallback)(() => {
+  const openPicker = (0, import_react10.useCallback)(() => {
     if (!disabled) inputRef.current?.click();
   }, [disabled]);
-  (0, import_react9.useEffect)(() => {
+  (0, import_react10.useEffect)(() => {
     if (!pickerEventName || typeof window === "undefined") return void 0;
     const handler = () => openPicker();
     window.addEventListener(pickerEventName, handler);
     return () => window.removeEventListener(pickerEventName, handler);
   }, [openPicker, pickerEventName]);
-  (0, import_react9.useEffect)(() => {
+  (0, import_react10.useEffect)(() => {
     if (!enablePaste || disabled || typeof window === "undefined") {
       return void 0;
     }
@@ -1624,7 +1709,7 @@ function useMediaDropzone(options) {
     window.addEventListener("paste", handler);
     return () => window.removeEventListener("paste", handler);
   }, [enablePaste, disabled, emit]);
-  const getRootProps = (0, import_react9.useCallback)(
+  const getRootProps = (0, import_react10.useCallback)(
     () => ({
       onDragEnter: (event) => {
         if (disabled) return;
@@ -1653,11 +1738,11 @@ function useMediaDropzone(options) {
     }),
     [disabled, emit, multiple]
   );
-  const inputAccept = (0, import_react9.useMemo)(
+  const inputAccept = (0, import_react10.useMemo)(
     () => acceptKey.length ? acceptKey : void 0,
     [acceptKey]
   );
-  const getInputProps = (0, import_react9.useCallback)(
+  const getInputProps = (0, import_react10.useCallback)(
     () => ({
       ref: (node) => {
         inputRef.current = node;
@@ -1679,20 +1764,20 @@ function useMediaDropzone(options) {
 }
 
 // src/react/file-upload-dropzone.tsx
-var import_react12 = require("react");
+var import_react13 = require("react");
 
 // src/core/use-media-upload.ts
-var import_react10 = require("react");
+var import_react11 = require("react");
 var entrySeq = 0;
 function useMediaUpload() {
   const client = useMediaClient();
-  const [uploading, setUploading] = (0, import_react10.useState)(false);
-  const [progress, setProgress] = (0, import_react10.useState)(null);
-  const [result, setResult] = (0, import_react10.useState)(null);
-  const [error, setError] = (0, import_react10.useState)(null);
-  const [entries, setEntries] = (0, import_react10.useState)([]);
-  const activeCount = (0, import_react10.useRef)(0);
-  const patchEntry = (0, import_react10.useCallback)(
+  const [uploading, setUploading] = (0, import_react11.useState)(false);
+  const [progress, setProgress] = (0, import_react11.useState)(null);
+  const [result, setResult] = (0, import_react11.useState)(null);
+  const [error, setError] = (0, import_react11.useState)(null);
+  const [entries, setEntries] = (0, import_react11.useState)([]);
+  const activeCount = (0, import_react11.useRef)(0);
+  const patchEntry = (0, import_react11.useCallback)(
     (id, patch) => {
       setEntries(
         (current) => current.map((e) => e.id === id ? { ...e, ...patch } : e)
@@ -1700,7 +1785,7 @@ function useMediaUpload() {
     },
     []
   );
-  const upload = (0, import_react10.useCallback)(
+  const upload = (0, import_react11.useCallback)(
     async (file, opts = {}) => {
       const id = `up-${++entrySeq}`;
       const fileName = opts.fileName ?? (file instanceof File ? file.name : "file");
@@ -1754,7 +1839,7 @@ function useMediaUpload() {
     },
     [client, patchEntry]
   );
-  const uploadMany = (0, import_react10.useCallback)(
+  const uploadMany = (0, import_react11.useCallback)(
     async (files, opts = {}) => {
       if (client.uploadMany) {
         activeCount.current += 1;
@@ -1783,10 +1868,10 @@ function useMediaUpload() {
     },
     [client, upload]
   );
-  const clearEntry = (0, import_react10.useCallback)((id) => {
+  const clearEntry = (0, import_react11.useCallback)((id) => {
     setEntries((current) => current.filter((e) => e.id !== id));
   }, []);
-  const reset = (0, import_react10.useCallback)(() => {
+  const reset = (0, import_react11.useCallback)(() => {
     setResult(null);
     setError(null);
     setProgress(null);
@@ -1806,37 +1891,26 @@ function useMediaUpload() {
 }
 
 // src/react/upload-progress-list.tsx
-var import_react11 = require("react");
+var import_react12 = require("react");
+var import_format = require("@ai-matrx/kit/format");
 var import_jsx_runtime5 = require("react/jsx-runtime");
 var AUTO_DISMISS_MS = 1e4;
-function formatFileSize(bytes) {
-  if (bytes == null || !Number.isFinite(bytes) || bytes < 0) return "\u2014";
-  if (bytes < 1024) return `${bytes} B`;
-  const units = ["KB", "MB", "GB", "TB"];
-  let value = bytes;
-  let unit = -1;
-  do {
-    value /= 1024;
-    unit += 1;
-  } while (value >= 1024 && unit < units.length - 1);
-  return `${value >= 10 ? Math.round(value) : value.toFixed(1)} ${units[unit] ?? "TB"}`;
-}
 function UploadProgressListImpl({
   uploads,
   onDismiss,
   onOpenFile,
   className
 }) {
-  const [hovered, setHovered] = (0, import_react11.useState)(false);
+  const [hovered, setHovered] = (0, import_react12.useState)(false);
   const activeCount = uploads.filter((u) => u.status === "uploading").length;
   const successCount = uploads.filter((u) => u.status === "success").length;
   const errorCount = uploads.filter((u) => u.status === "error").length;
-  const timersRef = (0, import_react11.useRef)(
+  const timersRef = (0, import_react12.useRef)(
     /* @__PURE__ */ new Map()
   );
-  const onDismissRef = (0, import_react11.useRef)(onDismiss);
+  const onDismissRef = (0, import_react12.useRef)(onDismiss);
   onDismissRef.current = onDismiss;
-  (0, import_react11.useEffect)(() => {
+  (0, import_react12.useEffect)(() => {
     const timers = timersRef.current;
     if (hovered) {
       timers.forEach((t) => clearTimeout(t));
@@ -1864,7 +1938,7 @@ function UploadProgressListImpl({
       }
     }
   }, [uploads, hovered]);
-  (0, import_react11.useEffect)(() => {
+  (0, import_react12.useEffect)(() => {
     const timers = timersRef.current;
     return () => {
       timers.forEach((t) => clearTimeout(t));
@@ -1930,10 +2004,10 @@ function UploadProgressListImpl({
                     }
                   ) }),
                   failed && u.error ? /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("p", { className: "mt-0.5 truncate text-[10px] text-destructive", children: u.error }) : !done ? /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)("p", { className: "mt-0.5 text-[10px] text-muted-foreground", children: [
-                    formatFileSize(u.bytesUploaded),
+                    (0, import_format.formatFileSize)(u.bytesUploaded),
                     " /",
                     " ",
-                    formatFileSize(u.fileSize)
+                    (0, import_format.formatFileSize)(u.fileSize)
                   ] }) : null
                 ] }),
                 canOpen ? /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)("span", { className: "flex shrink-0 items-center gap-1 rounded px-1.5 py-0.5 text-[11px] font-medium text-primary", children: [
@@ -1976,7 +2050,7 @@ function UploadProgressListImpl({
     }
   );
 }
-var UploadProgressList = (0, import_react11.memo)(UploadProgressListImpl);
+var UploadProgressList = (0, import_react12.memo)(UploadProgressListImpl);
 
 // src/react/file-upload-dropzone.tsx
 var import_jsx_runtime6 = require("react/jsx-runtime");
@@ -1996,7 +2070,7 @@ function FileUploadDropzone({
   pickerEventName
 }) {
   const { uploadMany, entries, clearEntry } = useMediaUpload();
-  const handleUpload = (0, import_react12.useCallback)(
+  const handleUpload = (0, import_react13.useCallback)(
     async (files) => {
       if (!files.length) return;
       try {
@@ -2103,22 +2177,22 @@ function FileUploadDropzone({
 }
 
 // src/react/media-action-toolbar.tsx
-var import_react14 = require("react");
+var import_react15 = require("react");
 
 // src/core/use-media-actions.ts
-var import_react13 = require("react");
+var import_react14 = require("react");
 function useMediaActions(ref, options = {}) {
   const ports = useMediaHostPorts();
   const { resolution } = useMediaResolution(ref);
-  const [busy, setBusy] = (0, import_react13.useState)(null);
-  const [lastError, setLastError] = (0, import_react13.useState)(null);
+  const [busy, setBusy] = (0, import_react14.useState)(null);
+  const [lastError, setLastError] = (0, import_react14.useState)(null);
   const actions = ports.actions;
   const { fileName, alt } = options;
-  const context = (0, import_react13.useMemo)(() => {
+  const context = (0, import_react14.useMemo)(() => {
     if (!ref) return null;
     return { ref, resolution, fileName, alt };
   }, [ref, resolution, fileName, alt]);
-  const isAvailable = (0, import_react13.useCallback)(
+  const isAvailable = (0, import_react14.useCallback)(
     (kind) => {
       if (!context || !actions) return false;
       if (kind === "share") return Boolean(actions.share || actions.SharePopover);
@@ -2126,7 +2200,7 @@ function useMediaActions(ref, options = {}) {
     },
     [context, actions]
   );
-  const run = (0, import_react13.useCallback)(
+  const run = (0, import_react14.useCallback)(
     async (kind) => {
       if (!context || !actions) return;
       const handler = actions[kind];
@@ -2175,7 +2249,7 @@ function MediaActionToolbar({
   buttonClassName
 }) {
   const state = useMediaActions(mediaRef, { fileName, alt });
-  const [shareOpen, setShareOpen] = (0, import_react14.useState)(false);
+  const [shareOpen, setShareOpen] = (0, import_react15.useState)(false);
   const SharePopover = state.SharePopover;
   const visible = hideUnavailable ? actions.filter((kind) => state.isAvailable(kind)) : actions;
   if (visible.length === 0) return null;
@@ -2232,7 +2306,7 @@ function MediaActionToolbar({
 }
 
 // src/react/media-lightbox.tsx
-var import_react15 = require("react");
+var import_react16 = require("react");
 var import_jsx_runtime8 = require("react/jsx-runtime");
 function MediaLightbox({
   open,
@@ -2250,7 +2324,7 @@ function MediaLightbox({
   headerExtra,
   className
 }) {
-  (0, import_react15.useEffect)(() => {
+  (0, import_react16.useEffect)(() => {
     if (!open || typeof window === "undefined") return void 0;
     const handler = (event) => {
       if (event.key === "Escape") {