@ai-matrx/media 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,61 @@
+# @ai-matrx/media
+
+## 0.1.0 — 2026-08-29
+
+Initial release (campaign ruling C19). Root types + `/core` headless hooks +
+`/react` DOM bindings, ported from the matrx-frontend originals with only the
+coupling seams inverted.
+
+**Ported units** (behavior verbatim; seams noted):
+
+- `InlineMediaRef` (from `features/files/components/inline/InlineMediaRef.tsx`) —
+  resolution/transport/Redux hydration → `MediaClient.resolve`
+  (`transport: "blob"` is the private-pixels lane); blob bytes →
+  `MediaClient.getBlob`; the session-refresh retry → `MediaClient.recoverLoadError`;
+  `next/image` → the injected `MediaHostPorts.ImageComponent`; the audio
+  output-sink and exclusive-playback hooks → `MediaHostPorts.playbackSession`.
+  The `ref` CONTENT prop is preserved for the existing 116 call sites.
+- `MediaThumbnail` — the 4-tier source priority became `/core`'s
+  `useThumbnailSource` (explicit `thumbnailUrl` → `resolution.thumbnailSrc`
+  variant metadata → live source render incl. video poster + private blob
+  lane → icon).
+- `FileIcon` + the icon-relevant slice of the `file-types.ts` registry
+  (`getFileKindDetails`/`getFolderKindDetails`) — every extension→icon/color
+  row, MIME-prefix override, audio/webm disambiguation, dotfile-text
+  heuristic, folder + unknown defaults. Preview/thumbnail-strategy/size-cap
+  columns deliberately stay in the app (C8).
+- `useFileAs`/`useDurableSrc`/`useFileBlob`/`useFileUpload` → the headless
+  `useMediaResolution`, `useMediaLoadRecovery`, `useMediaBlob`,
+  `useMediaUpload` (+ per-file tray `entries`, replacing the Redux
+  `selectVisibleUploads` coupling).
+- `FileUploadDropzone` + `UploadProgressList` — `react-dropzone` replaced by
+  the package's own headless `useMediaDropzone` (native drag/paste/picker);
+  acquisition sources (Drive, local folder, existing files) became the
+  `actions` slot.
+
+**THE SHARE MANDATE (C19)**: the complete headless `MediaActionsPort`
+contract (share/download/copy/open + the `SharePopover` slot) ships now, with
+`MediaActionToolbar` and `MediaLightbox` shells wired to it and failing
+closed. The share-popover BODIES land as a mandated tracked wave the moment
+the associations package provides its ports — additively, through this same
+contract.
+
+**Icons**: the package ships its own inlined SVGs (32 glyphs copied from
+lucide-react v1.22.0, ISC) — no icon-library dependency, per C19.
+
+**Deliberate divergences from the originals** (not defects in either):
+
+- `UploadProgressList` counts only `"uploading"` entries as active (the
+  original also counted a Redux-only `"pending"` state that has no analog in
+  the hook-owned tray).
+- `InlineMediaRef` renders a skeleton while the private blob lane loads
+  (the original rendered the resolved-URL path immediately because its blob
+  cache hydrated synchronously; the cache now lives behind the client).
+- The dropzone's inline mode renders a "Browse files" button (the original's
+  picker affordance lived in the app-shaped `FileAcquisitionActions`, now the
+  `actions` slot).
+
+**Defects found in the originals during the port**: none rising to a fix —
+the known duplicate retry implementations (`useUnifiedImageUrl` /
+`useUnifiedVideoUrl`) are wave-2 scope and recorded in the design doc, not
+silently patched here.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AI Matrix Engine
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,106 @@
+# @ai-matrx/media
+
+Media components that **just work** with a durable file system. Renderers for
+images, video, audio and file thumbnails that take a durable reference — a
+`file_id` or a permanent public URL — and own the whole URL lifecycle:
+resolution, auth transport, load-error recovery, typed unavailable states,
+upload progress, and share/download/copy/open actions.
+
+The package ships **zero transport**. Everything data-shaped arrives through
+one injected port, the `MediaClient`. That is the point: every media breakage
+we ever shipped came from code that hand-built a URL or an `<img>`; here the
+correct path is the only path the types allow.
+
+```
+@ai-matrx/media          types only — MediaRef, DurableSrc, MediaClient, host ports
+@ai-matrx/media/core     headless React hooks (platform-free state machines)
+@ai-matrx/media/react    DOM components (Tailwind classes, inlined SVG icons)
+```
+
+## The rules the types enforce
+
+1. **The package never fetches a media URL itself.** Bytes exist only via
+   `MediaClient.getBlob`.
+2. **Every component takes a ref, never a `src`.** Even a caller-supplied URL
+   string is classified by `resolve()`, never trusted.
+3. **A signed URL is a handoff, never an identity.** The only string a media
+   element binds is the branded `DurableSrc`, which only a `MediaClient`
+   implementation can mint. An expiring URL cannot pass the types without an
+   unsafe cast.
+4. **Share affordances fail closed.** `shareableUrl` returns `null` rather
+   than ever emitting a signed URL; unwired actions render disabled.
+5. **One retry policy.** Load errors route through
+   `MediaClient.recoverLoadError` (session refresh → same-URL retry →
+   terminal). The package has no retry logic of its own.
+
+## Quick start
+
+```tsx
+import { MediaProvider } from "@ai-matrx/media/core";
+import { InlineMediaRef, MediaThumbnail, MediaLightbox } from "@ai-matrx/media/react";
+
+// `client` implements the MediaClient interface from "@ai-matrx/media".
+// Matrx apps wire the canonical implementation from @ai-matrx/data/files;
+// any structural implementation works.
+<MediaProvider client={client} ports={{ ImageComponent, actions, playbackSession }}>
+  <InlineMediaRef ref={{ file_id }} size="md" fit="cover" />
+  <MediaThumbnail mediaRef={{ file_id }} fileName="report.pdf" />
+</MediaProvider>
+```
+
+`InlineMediaRef` accepts a `MediaRef` (`{ file_id, url?, mime_type? }`), a
+bare fileId string, or an external public URL string — and renders a
+correctly-sized `<img>` / `<video>` / `<audio>` with fallback and informative
+error states. `ref` is a content prop (React 19); use `mediaElementRef` for
+DOM access.
+
+## Headless hooks (`/core`)
+
+| Hook | What it owns |
+|---|---|
+| `useMediaResolution(ref)` | ref → `MediaResolution` as state (`empty` / `ready` / `unavailable` with a typed reason) |
+| `useMediaLoadRecovery(src)` | the retry-key/error machine over the client's ONE recovery policy |
+| `useMediaBlob(ref)` | object-URL bytes with lifecycle + release |
+| `useMediaUpload()` | single + batch upload, progress, and a per-file tray (`entries`) |
+| `useThumbnailSource(ref, opts)` | the 4-tier thumbnail decision (rendered thumb → variant → live source → icon) |
+| `useMediaActions(ref)` | share/download/copy/open availability + execution over the injected actions port |
+| `getFileKindDetails(name, mime)` | filename/MIME → category, icon name, color |
+
+## Components (`/react`)
+
+`InlineMediaRef` · `MediaThumbnail` · `FileIcon` · `FileUploadDropzone` (+
+`UploadProgressList`, `useMediaDropzone`) · `MediaActionToolbar` ·
+`MediaLightbox` — plus the package's own inlined SVG icon set (no icon
+library dependency).
+
+### Actions & sharing
+
+Hosts inject a `MediaActionsPort` (`share`, `download`, `copy`, `open`
+handlers and/or a rich `SharePopover` component). The toolbar and lightbox
+render whatever is wired and disable the rest — sharing integration plugs in
+without touching this package.
+
+```tsx
+<MediaProvider client={client} ports={{ actions: { download, share, SharePopover } }}>
+  <MediaActionToolbar mediaRef={{ file_id }} fileName="photo.png" />
+</MediaProvider>
+```
+
+## Styling
+
+`/react` uses Tailwind utility classes with semantic tokens (`bg-muted`,
+`text-destructive`, …). Tailwind v4 hosts register the package as a source:
+
+```css
+@source "../node_modules/@ai-matrx/media";
+```
+
+## SSR / RSC
+
+The root entry is server-safe (types + one pure function). `/core` and
+`/react` are client modules (`"use client"` is stamped per entry). Nothing
+touches `window` at import time.
+
+## License
+
+MIT. Inlined icon paths copied from [Lucide](https://lucide.dev) (ISC).