@ai-matrx/media 0.2.2 → 0.3.0

package/dist/index.d.ts

@@ -85,6 +85,75 @@ interface MediaResolution {
 }
 /** Typed unavailable states — render-as-state, never thrown as incidents. */
 type MediaUnavailableReason = "access_denied" | "not_found" | "deleted" | "unknown";
+/** Where in the pipeline a media failure surfaced. */
+type MediaFailurePhase = 
+/** `MediaClient.resolve()` refused the ref (threw). */
+"resolve"
+/** The client's session bootstrap/mint failed (`recoverLoadError` rejected),
+ *  or the server reported an ephemeral cookie secret (warning). */
+ | "session"
+/** `MediaClient.getBlob()` rejected — private-pixels bytes never arrived. */
+ | "blob"
+/** The media element errored and recovery was exhausted or impossible. */
+ | "element-load"
+/** The client's recovery machinery declined to retry on the first attempt. */
+ | "recovery";
+/** What the ONE retry policy did before the failure went terminal. */
+type MediaRetryOutcome = 
+/** Recovery was impossible (unrecoverable source) or was never reached. */
+"not-attempted"
+/** The client granted a session-refresh retry and the retry ALSO failed. */
+ | "retried"
+/** The recovery call itself threw/rejected. */
+ | "recovery-failed";
+/**
+ * The strictly-typed structural payload every terminal media failure emits.
+ * `mediaRef` is DURABLE IDENTITY ONLY — a `file:<id>` / query-stripped URL
+ * key, NEVER a signed URL (signatures live in query strings, which
+ * {@link failureMediaIdentity} removes).
+ */
+interface MediaFailureInfo {
+    source: "media";
+    phase: MediaFailurePhase;
+    /** File id / ref key identity — never a signed URL. */
+    mediaRef: string;
+    /** HTTP status when known (e.g. from a structured client error). */
+    status?: number | undefined;
+    /** Outcome of the client's ONE retry policy, when the phase reached it. */
+    retryOutcome?: MediaRetryOutcome | undefined;
+    /** True for a dead render; false for a captured warning (ephemeral secret). */
+    terminal: boolean;
+    message: string;
+}
+/**
+ * The host's error-capture sink. Bind `capture` to the app's error system
+ * (matrx-frontend: `captureError` in lib/diagnostics/errorCaptureStore).
+ * When absent, the package console.errors the same payload once per failure
+ * (the loud default) — it never downgrades to silence.
+ */
+interface MediaDiagnosticsPort {
+    capture?: ((info: MediaFailureInfo) => void) | undefined;
+}
+/** String verdicts of the ONE retry policy. */
+type MediaRecoveryVerdict = "retry" | "terminal";
+/**
+ * Structured `recoverLoadError` result — optional; the bare string verdict
+ * remains fully supported. Lets the client surface what it learned during the
+ * session bootstrap without a second channel:
+ *
+ *   - `status` — HTTP status of the failed mint/probe, forwarded into the
+ *     terminal {@link MediaFailureInfo};
+ *   - `secretSource` — the `/files/session` mint response's `secret_source`
+ *     when the server sends one (a matrx-connect field). `"ephemeral"` means
+ *     the server signs cookies with a boot-generated secret: private renders
+ *     WILL break across restarts/instances, and the package captures a
+ *     non-terminal warning immediately instead of waiting for the outage.
+ */
+interface MediaRecoveryReport {
+    verdict: MediaRecoveryVerdict;
+    status?: number | undefined;
+    secretSource?: string | undefined;
+}
 interface MediaBlobHandle {
     /** `blob:` object URL safe for any browser API. */
     url: string;
@@ -132,7 +201,7 @@ interface MediaClient {
      * second failure terminal. Called by the package's onError path, never
      * re-implemented.
      */
-    recoverLoadError(src: DurableSrc, attempt: number): Promise<"retry" | "terminal">;
+    recoverLoadError(src: DurableSrc, attempt: number): Promise<MediaRecoveryVerdict | MediaRecoveryReport>;
     /** Upload → durable identity. */
     upload(file: File | Blob, opts?: MediaUploadOptions): Promise<MediaUploadResult>;
     /**
@@ -222,6 +291,12 @@ interface MediaHostPorts {
     actions?: MediaActionsPort | undefined;
     /** Web host may pass a next/image adapter; default is a plain `<img>`. */
     ImageComponent?: MediaSlotComponent<MediaImageComponentProps> | undefined;
+    /**
+     * Error-capture sink for terminal media failures (and the ephemeral-secret
+     * warning). Bind to the host's error system; absent → loud console.error
+     * default. See {@link MediaDiagnosticsPort}.
+     */
+    diagnostics?: MediaDiagnosticsPort | undefined;
 }
 
-export { type DurableSrc, type MediaActionContext, type MediaActionHandler, type MediaActionKind, type MediaActionsPort, type MediaBlobHandle, type MediaClient, type MediaHostPorts, type MediaImageComponentProps, type MediaKind, type MediaMultiUploadResult, type MediaRef, type MediaRefLike, type MediaResolution, type MediaSharePopoverProps, type MediaSlotComponent, type MediaUnavailableReason, type MediaUploadOptions, type MediaUploadResult, type PlaybackSessionPort, type PlaybackSessionRegistration, mintDurableSrc };
+export { type DurableSrc, type MediaActionContext, type MediaActionHandler, type MediaActionKind, type MediaActionsPort, type MediaBlobHandle, type MediaClient, type MediaDiagnosticsPort, type MediaFailureInfo, type MediaFailurePhase, type MediaHostPorts, type MediaImageComponentProps, type MediaKind, type MediaMultiUploadResult, type MediaRecoveryReport, type MediaRecoveryVerdict, type MediaRef, type MediaRefLike, type MediaResolution, type MediaRetryOutcome, type MediaSharePopoverProps, type MediaSlotComponent, type MediaUnavailableReason, type MediaUploadOptions, type MediaUploadResult, type PlaybackSessionPort, type PlaybackSessionRegistration, mintDurableSrc };

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// 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(src: DurableSrc, attempt: number): Promise<\"retry\" | \"terminal\">;\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"],"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  /** 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":[]}