@ai-matrx/media 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,227 @@
+/**
+ * @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;
+};
+/**
+ * Brand a URL as durable. FOR MediaClient IMPLEMENTATIONS ONLY — the
+ * implementation must classify the URL first (the ONE signed-URL classifier
+ * lives with the platform's files layer; never re-implement it here or in a
+ * host). Calling this on an unclassified string defeats law 3.
+ */
+declare function mintDurableSrc(url: string): DurableSrc;
+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;
+}
+
+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 };

package/dist/index.js

@@ -0,0 +1,8 @@
+// src/types.ts
+function mintDurableSrc(url) {
+  return url;
+}
+export {
+  mintDurableSrc
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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":[]}