@ai-matrx/media 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,161 @@
 # @ai-matrx/media
 
+## 0.4.1 — 2026-08-30
+
+**Fixes a crash class in 0.4.0's `/viewers` dispatch. Every 0.4.0 consumer must
+move to 0.4.1** — the bug is invisible until a real engine is registered, which
+is what every host does.
+
+### Consumer action (C28)
+
+- Upgrade. No API change; nothing to rewrite.
+
+### The defect
+
+`MediaFileViewer` CALLED the registered viewer as a plain function
+(`viewer(props)`), and `CodeViewer` did the same with the registered
+highlighter. Every real engine adapter uses hooks — it resolves a display URL,
+reads the host theme, joins a playback session — so those hooks landed in the
+DISPATCHER's hook list instead of the body's own. A single body renders fine;
+the moment the file kind changes (image → code, code → PDF) the hook count
+changes and React throws "Rendered fewer hooks than expected", taking the whole
+preview surface down. Both now mount through `createElement`, so each body gets
+its own component instance and its own hook list.
+
+Found while adopting 0.4.0 in matrx-frontend, before the host swap shipped.
+Guarded by a new test that mounts hook-using bodies and then switches kinds
+three times — the exact sequence that used to crash.
+
+## 0.4.0 — 2026-08-30
+
+**The package renders FILES now, not just media elements** — and it knows what
+Next.js is. Two new subpaths close this package's ALL-INCLUSIVE-LAW retrofit
+row: `./next` (the framework seam every Next host was rebuilding) and
+`./viewers` (the full-pane file viewers matrx-frontend owned).
+
+### Consumer action (C28)
+
+- **`./next` replaces every hand-written `next/image` adapter.** A host's
+  `ImageComponent` port collapses to
+  `ImageComponent: NextMediaImage` (or `createNextMediaImageComponent({…})`).
+  Delete the local wrapper — including the four `as React.*Handler` casts it
+  needed; the package owns those now. `next` is an **optional peer** (`>=14`),
+  so non-Next consumers are unaffected and nothing new installs for them.
+- **`./viewers` replaces host-owned text / code / SVG / HTML / generic
+  previewers.** A host now registers only what the package cannot ship — its
+  heavy engines — and renders `<MediaFileViewer>`:
+
+  ```tsx
+  registerMediaViewer("pdf", HostPdfViewer);        // PDF.js, react-pdf…
+  registerMediaCodeHighlighter(PrismHighlighter);   // optional: colour
+  <MediaFileViewer source={{ kind: "ref", ref }} fileName={name} />
+  ```
+
+  Delete the absorbed bodies. Anything NOT registered renders the announcing
+  default, never a dead pane.
+- 🚨 **`formatFileSize` behavior change (`/react`).** It now accepts
+  `number | null | undefined` and returns `"—"` for null / undefined / NaN /
+  negative, where it previously returned a confident, wrong `"0 B"`. Any
+  consumer asserting `"0 B"` for a missing size must update. (Defect found
+  while absorbing the viewers: matrx-frontend's own `formatFileSize` already
+  had this guard and the package's did not — C22 says the package carries the
+  better one.)
+- **No other existing export changed shape.**
+
+### `./next` — the Next.js binding (NEW)
+
+- `NextMediaImage` and `createNextMediaImageComponent({ unoptimized?, quality?,
+  sizes?, priority?, loader?, className? })` — a `MediaHostPorts.ImageComponent`
+  implementation over `next/image`, with `unoptimized: true` as the default
+  because Matrx durable URLs are session-cookie authenticated and Next's
+  optimizer fetches them SERVER-side, where there is no user session.
+- **The deliberate divergence from `@ai-matrx/data`'s `/next`** (which imports
+  no `next/*` module): `next/image` is not data crossing a seam, it IS the
+  renderer, so no structural seam can express it — the ALL-INCLUSIVE LAW names
+  this exact wrapper as package-owned. Confined to this one entry; the
+  package's components still reach Next only through the `ImageComponent` port.
+- The port's structurally-typed handlers are narrowed to DOM handler types
+  here, once, instead of in every host.
+
+### `./viewers` — full-pane file viewers (NEW)
+
+Absorbed from matrx-frontend `features/files/components/core/FilePreview/`:
+`PreviewerSwitch` (the dispatcher) plus the `TextPreview`, `CodePreview`,
+`SvgPreview`, `HtmlPreview` and `GenericPreview` bodies. Behavior ported
+verbatim except where noted below.
+
+- `MediaFileViewer` — kind dispatch with the C23 resolution order: a host
+  registration wins, else the package's built-in body, else the **announcing
+  default** that names the missing engine and the remedy and still offers
+  download / view-as-text. A blank pane is not a reachable state.
+- Built-in bodies: `TextViewer`, `CodeViewer`, `SvgViewer` (rendered + XML
+  source), `HtmlViewer` (sandboxed frame + source), `GenericViewer`.
+- `registerMediaViewer(kind, Component)` / `registerMediaCodeHighlighter(fn)` —
+  the heavy-engine seam, on `globalThis` `Symbol.for` slots so a registration
+  made in one loader graph is visible from the other (the tarball canary
+  proves it across ESM/CJS). Both return an unregister function.
+- `getPreviewKind(fileName, mimeType?)` — kind derivation from the package's
+  own file-kind registry, so a fresh app dispatches correctly with zero setup.
+  A host with a richer registry passes `previewKind` explicitly.
+- `MediaViewerSource` has two lanes: `{kind:"ref"}` (everything through the
+  MediaClient) and `{kind:"blob"}` (bytes the host already downloaded — proven
+  by test to make **zero** client calls).
+- The markup viewers take OPTIONAL `markupControls`; a host control rail drives
+  mode / viewport / reload, and without one the viewer draws its own toolbar
+  and is fully capable (the original hard-wired itself to an app context).
+- **Why `CodeViewer` ships without a highlighter** (C8, the diff-package Monaco
+  precedent): Prism is a ~150KB browser-only engine and a headless consumer
+  must not carry it. The package ships monospace, line-numbered, wrap-toggling,
+  copyable, truncation-honest code — everything but colour — and the engine
+  rides `registerMediaCodeHighlighter`. That default announces nothing because
+  nothing failed.
+- **`HtmlViewer`'s sandbox is non-configurable**: `allow-scripts allow-popups
+  allow-forms`, never `allow-same-origin`, plus `referrerPolicy="no-referrer"`.
+  One wrong token is a real XSS against the host origin, so hosts do not get a
+  knob. Asserted in the source suite AND on the packed artifact.
+
+### Defects fixed in the port (never silently — C22)
+
+- **A user-visible debug artifact is gone.** `GenericPreview` shipped a
+  fuchsia `ring-2` and a "GenericPreview" corner badge — a layering-debug
+  visualization commented "Rip this out when done" — to every user opening an
+  unpreviewable file. The package has no debug chrome.
+- **`blob.text()` is no longer assumed.** All four absorbed text-reading
+  previewers called it directly; it does not exist in Safari < 14, older
+  WebViews (the Tauri shell's floor), or jsdom, and the failure surfaced to the
+  user as `blob.text is not a function` — as though the FILE were broken.
+  `readBlobText` falls back through `arrayBuffer()` and `FileReader`.
+- **`formatFileSize`** — see Consumer action above.
+- **Four copies of the read-cap-truncate-report machinery became one**
+  (`useViewerText`), as did the error card, skeleton and copy button.
+
+### Gate
+
+`pnpm typecheck && pnpm test && pnpm check:package` green: 125 tests
+(14 new C23 tests across three targets — the announcing default incl. its
+falsifiability leg, the built-in bodies unregistered, and dispatch with zero
+host configuration), publint, attw node16, and a tarball canary extended with
+the `/next` no-cast `MediaHostPorts` assignment, the `/viewers` ESM+CJS export
+and render legs, the packed-artifact sandbox assertion, and the viewer-registry
+dual-graph proof. `/next` is not loaded in the bare-node ESM leg by design:
+Next publishes `next/image` extensionless with no `exports` map, so only
+bundlers and TypeScript resolve it — it is proven via attw, the type canary,
+and a real `require()` in the CJS leg.
+
+### Deliberately NOT absorbed (recorded, not forgotten)
+
+- **The PDF viewer tree** (`matrx-frontend/features/pdf`, 49 files): PDF.js +
+  annotation layer + document scanner + surface registry + server-side
+  extraction API. It is a FEATURE, not a viewer body, and it rides the
+  `registerMediaViewer("pdf", …)` seam.
+- **Markdown / spreadsheet / Office viewers**: remark+rehype+KaTeX, SheetJS +
+  PapaParse, and a server extraction endpoint respectively — heavy engines or
+  host-server-coupled. Same seam.
+- **Image / video / audio viewers**: they bind host domain systems (a
+  zoom/rotate control rail, the unified playback-session registry, a
+  design-system slider). They already consume `/core`; absorbing their bodies
+  is the next wave, not this one.
+
 ## 0.3.0 — 2026-08-30
 
 **A terminal media failure can never be silent again.** Born from the

package/README.md

@@ -146,6 +146,63 @@ default, never silent. If your `MediaClient.recoverLoadError` returns a
 `secret_source: "ephemeral"`, the package immediately captures an app-wide
 warning that private renders will break across server restarts/instances.
 
+## File viewers (`/viewers`)
+
+Full-pane rendering of ONE file — a preview pane, a file tab, a code editor's
+binary-file fallback. `MediaFileViewer` dispatches on the file kind and ships
+working bodies for text, code, SVG, HTML and unknown files.
+
+```tsx
+import { MediaFileViewer } from "@ai-matrx/media/viewers";
+
+<MediaFileViewer
+  source={{ kind: "ref", ref: { file_id } }}
+  fileName={file.name}
+  fileSize={file.size}
+  generic={{ onDownload }}
+/>;
+```
+
+Kinds whose rendering IS a heavy browser-only engine — PDF, Markdown,
+spreadsheets, Office documents — are yours to register, so a consumer that only
+shows text files never carries a PDF engine:
+
+```tsx
+import { registerMediaViewer, registerMediaCodeHighlighter } from "@ai-matrx/media/viewers";
+
+registerMediaViewer("pdf", MyPdfViewer);          // gets MediaViewerProps
+registerMediaCodeHighlighter(MyPrismHighlighter); // optional: colour for code
+```
+
+Until you register one, that kind renders an **announcing default**: it names
+the missing engine and the remedy and still offers download / view-as-text. It
+is never a blank pane. (Code is different: with no highlighter registered it
+renders complete — monospace, line-numbered, copyable — just without colour,
+so it announces nothing.)
+
+Registering a kind the package already renders replaces the built-in, which is
+how you plug in a domain-specific viewer of your own.
+
+The `blob` source lane (`{ kind: "blob", blob, url }`) renders bytes you
+already have without touching the `MediaClient` at all.
+
+## Next.js (`/next`)
+
+The `ImageComponent` port, implemented over `next/image` so you never write
+that wrapper again. `next` is an optional peer — nothing installs it for you,
+and no other entry imports it.
+
+```tsx
+import { NextMediaImage } from "@ai-matrx/media/next";
+
+const ports: MediaHostPorts = { ImageComponent: NextMediaImage };
+// or: createNextMediaImageComponent({ unoptimized: false, quality: 90 })
+```
+
+It defaults to `unoptimized`, which is correct for Matrx media: durable file
+URLs are session-cookie authenticated and Next's optimizer fetches them from
+the server, where there is no user session.
+
 ## Styling
 
 `/react` uses Tailwind utility classes with semantic tokens (`bg-muted`,
@@ -157,9 +214,9 @@ warning that private renders will break across server restarts/instances.
 
 ## SSR / RSC
 
-The root entry is server-safe (types + one pure function). `/core`, `/react`
-and `/share` are client modules (`"use client"` is stamped per entry).
-Nothing touches `window` at import time.
+The root entry is server-safe (types + one pure function). `/core`, `/react`,
+`/share`, `/viewers` and `/next` are client modules (`"use client"` is stamped
+per entry). Nothing touches `window` at import time.
 
 ## License
 

package/dist/next.cjs

@@ -0,0 +1,92 @@
+"use client";
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/next.ts
+var next_exports = {};
+__export(next_exports, {
+  NextMediaImage: () => NextMediaImage,
+  createNextMediaImageComponent: () => createNextMediaImageComponent
+});
+module.exports = __toCommonJS(next_exports);
+
+// src/next/image.tsx
+var import_image = __toESM(require("next/image"), 1);
+var import_jsx_runtime = require("react/jsx-runtime");
+function createNextMediaImageComponent(options = {}) {
+  const {
+    unoptimized = true,
+    quality,
+    sizes,
+    priority,
+    loader,
+    className: baseClassName
+  } = options;
+  function NextMediaImageWithOptions({
+    src,
+    alt,
+    width,
+    height,
+    className,
+    onError,
+    onClick,
+    onKeyDown,
+    role,
+    tabIndex
+  }) {
+    return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+      import_image.default,
+      {
+        src,
+        alt,
+        width,
+        height,
+        unoptimized,
+        ...quality !== void 0 ? { quality } : {},
+        ...sizes !== void 0 ? { sizes } : {},
+        ...priority !== void 0 ? { priority } : {},
+        ...loader !== void 0 ? {
+          loader: ({ src: src2, width: width2, quality: loaderQuality }) => loader({ source: src2, width: width2, quality: loaderQuality })
+        } : {},
+        ...baseClassName !== void 0 || className !== void 0 ? {
+          className: [baseClassName, className].filter((part) => !!part).join(" ")
+        } : {},
+        ...onError !== void 0 ? { onError } : {},
+        ...onClick !== void 0 ? { onClick } : {},
+        ...onKeyDown !== void 0 ? { onKeyDown } : {},
+        ...role !== void 0 ? { role } : {},
+        ...tabIndex !== void 0 ? { tabIndex } : {}
+      }
+    );
+  }
+  NextMediaImageWithOptions.displayName = "NextMediaImage";
+  return NextMediaImageWithOptions;
+}
+var NextMediaImage = createNextMediaImageComponent();
+//# sourceMappingURL=next.cjs.map

package/dist/next.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/next.ts","../src/next/image.tsx"],"sourcesContent":["/**\n * `@ai-matrx/media/next` — the Next.js platform binding.\n *\n * ONE export a Next host needs, replacing the wrapper every Next app was\n * hand-writing (`MediaHostPorts.ImageComponent` over `next/image`). This is\n * the ONLY entry in the package that imports a `next/*` module; `next` is an\n * OPTIONAL peer, so no other consumer pays for it and no other entry may\n * reach for it. See the rationale block in `./next/image.tsx`.\n */\n\nexport {\n  createNextMediaImageComponent,\n  NextMediaImage,\n  type NextMediaImageLoaderArgs,\n  type NextMediaImageOptions,\n} from \"./next/image\";\n","/**\n * src/next/image.tsx — the Next.js `ImageComponent` port implementation.\n *\n * WHY THIS ENTRY IMPORTS `next/image` (the deliberate divergence from the\n * data 0.5.0 `/next` precedent, which imports NO `next/*` module):\n *\n * `@ai-matrx/data/next` could keep Next out of its source because everything\n * it needed from Next — `cookies()`, `NextResponse` — is DATA passed across a\n * structural seam. `next/image` is not data: it is the rendering component\n * itself, and its entire value (the optimizer endpoint, the srcset builder,\n * the lazy/priority machinery, the blur placeholder) lives inside the module.\n * A \"seam\" for it degenerates into exactly the thing THE ALL-INCLUSIVE LAW\n * names as the failure — \"the `next/image`/`next/link` wrappers\" that every\n * host was rebuilding by hand (matrx-frontend's was 35 lines of prop\n * forwarding with four `as` casts). So this ONE entry takes `next` as an\n * OPTIONAL peer and owns the wrapper; no other entry in the package may.\n *\n * The seam is preserved where it still buys something: the package's\n * components never import this module. They call `MediaHostPorts.ImageComponent`,\n * which defaults to a plain `<img>`. A Next host assigns `NextMediaImage` (or\n * a configured one) and nothing else in the package learns that Next exists.\n */\n\n\"use client\";\n\nimport Image from \"next/image\";\nimport type { MediaImageComponentProps } from \"../types\";\n\n/**\n * Structural mirror of Next's `ImageLoaderProps` — declared here so the\n * package's public types never re-export a `next/*` type (which would make\n * the shape of our API depend on the consumer's Next version).\n */\nexport interface NextMediaImageLoaderArgs {\n  source: string;\n  width: number;\n  quality?: number | undefined;\n}\n\nexport interface NextMediaImageOptions {\n  /**\n   * Skip Next's optimizer endpoint. Defaults to `true`, which is the ONLY\n   * correct default for Matrx media: durable file URLs are session-cookie\n   * authenticated, and `/_next/image` fetches them from the SERVER, which\n   * carries no user session — an optimized private image 404s. Set this to\n   * `false` only for a host whose media is genuinely public CDN content and\n   * whose `next.config` allows the remote pattern.\n   */\n  unoptimized?: boolean | undefined;\n  quality?: number | undefined;\n  sizes?: string | undefined;\n  priority?: boolean | undefined;\n  loader?: ((args: NextMediaImageLoaderArgs) => string) | undefined;\n  /** Extra class applied under the caller's `className` (last-wins merge). */\n  className?: string | undefined;\n}\n\n/**\n * Build a Next.js `ImageComponent` port with fixed options.\n *\n * ```tsx\n * const ports: MediaHostPorts = {\n *   ImageComponent: createNextMediaImageComponent({ quality: 90 }),\n * };\n * ```\n */\nexport function createNextMediaImageComponent(\n  options: NextMediaImageOptions = {},\n): (props: MediaImageComponentProps) => React.ReactElement {\n  const {\n    unoptimized = true,\n    quality,\n    sizes,\n    priority,\n    loader,\n    className: baseClassName,\n  } = options;\n\n  function NextMediaImageWithOptions({\n    src,\n    alt,\n    width,\n    height,\n    className,\n    onError,\n    onClick,\n    onKeyDown,\n    role,\n    tabIndex,\n  }: MediaImageComponentProps): React.ReactElement {\n    return (\n      <Image\n        src={src}\n        alt={alt}\n        width={width}\n        height={height}\n        unoptimized={unoptimized}\n        {...(quality !== undefined ? { quality } : {})}\n        {...(sizes !== undefined ? { sizes } : {})}\n        {...(priority !== undefined ? { priority } : {})}\n        {...(loader !== undefined\n          ? {\n              loader: ({ src, width, quality: loaderQuality }) =>\n                loader({ source: src, width, quality: loaderQuality }),\n            }\n          : {})}\n        {...(baseClassName !== undefined || className !== undefined\n          ? {\n              className: [baseClassName, className]\n                .filter((part): part is string => !!part)\n                .join(\" \"),\n            }\n          : {})}\n        // The port's handlers are structurally typed (`(event: unknown) => void`)\n        // so the root entry stays free of React type imports. Narrowing them to\n        // the DOM handler shapes is this binding's job — a host must never write\n        // these casts again (C22: the massage lives in the package).\n        {...(onError !== undefined\n          ? { onError: onError as React.ReactEventHandler<HTMLImageElement> }\n          : {})}\n        {...(onClick !== undefined\n          ? { onClick: onClick as React.MouseEventHandler<HTMLImageElement> }\n          : {})}\n        {...(onKeyDown !== undefined\n          ? { onKeyDown: onKeyDown as React.KeyboardEventHandler<HTMLImageElement> }\n          : {})}\n        {...(role !== undefined ? { role } : {})}\n        {...(tabIndex !== undefined ? { tabIndex } : {})}\n      />\n    );\n  }\n\n  NextMediaImageWithOptions.displayName = \"NextMediaImage\";\n  return NextMediaImageWithOptions;\n}\n\n/**\n * The zero-configuration Next.js `ImageComponent` port — `unoptimized`, every\n * port prop forwarded. This is the whole of what a Next host needs:\n *\n * ```tsx\n * import { NextMediaImage } from \"@ai-matrx/media/next\";\n * const ports: MediaHostPorts = { ImageComponent: NextMediaImage };\n * ```\n */\nexport const NextMediaImage = createNextMediaImageComponent();\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACyBA,mBAAkB;AAkEZ;AAzBC,SAAS,8BACd,UAAiC,CAAC,GACuB;AACzD,QAAM;AAAA,IACJ,cAAc;AAAA,IACd;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA,WAAW;AAAA,EACb,IAAI;AAEJ,WAAS,0BAA0B;AAAA,IACjC;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF,GAAiD;AAC/C,WACE;AAAA,MAAC,aAAAA;AAAA,MAAA;AAAA,QACC;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACC,GAAI,YAAY,SAAY,EAAE,QAAQ,IAAI,CAAC;AAAA,QAC3C,GAAI,UAAU,SAAY,EAAE,MAAM,IAAI,CAAC;AAAA,QACvC,GAAI,aAAa,SAAY,EAAE,SAAS,IAAI,CAAC;AAAA,QAC7C,GAAI,WAAW,SACZ;AAAA,UACE,QAAQ,CAAC,EAAE,KAAAC,MAAK,OAAAC,QAAO,SAAS,cAAc,MAC5C,OAAO,EAAE,QAAQD,MAAK,OAAAC,QAAO,SAAS,cAAc,CAAC;AAAA,QACzD,IACA,CAAC;AAAA,QACJ,GAAI,kBAAkB,UAAa,cAAc,SAC9C;AAAA,UACE,WAAW,CAAC,eAAe,SAAS,EACjC,OAAO,CAAC,SAAyB,CAAC,CAAC,IAAI,EACvC,KAAK,GAAG;AAAA,QACb,IACA,CAAC;AAAA,QAKJ,GAAI,YAAY,SACb,EAAE,QAA8D,IAChE,CAAC;AAAA,QACJ,GAAI,YAAY,SACb,EAAE,QAA8D,IAChE,CAAC;AAAA,QACJ,GAAI,cAAc,SACf,EAAE,UAAqE,IACvE,CAAC;AAAA,QACJ,GAAI,SAAS,SAAY,EAAE,KAAK,IAAI,CAAC;AAAA,QACrC,GAAI,aAAa,SAAY,EAAE,SAAS,IAAI,CAAC;AAAA;AAAA,IAChD;AAAA,EAEJ;AAEA,4BAA0B,cAAc;AACxC,SAAO;AACT;AAWO,IAAM,iBAAiB,8BAA8B;","names":["Image","src","width"]}

package/dist/next.d.cts

@@ -0,0 +1,74 @@
+import { MediaImageComponentProps } from './index.cjs';
+
+/**
+ * src/next/image.tsx — the Next.js `ImageComponent` port implementation.
+ *
+ * WHY THIS ENTRY IMPORTS `next/image` (the deliberate divergence from the
+ * data 0.5.0 `/next` precedent, which imports NO `next/*` module):
+ *
+ * `@ai-matrx/data/next` could keep Next out of its source because everything
+ * it needed from Next — `cookies()`, `NextResponse` — is DATA passed across a
+ * structural seam. `next/image` is not data: it is the rendering component
+ * itself, and its entire value (the optimizer endpoint, the srcset builder,
+ * the lazy/priority machinery, the blur placeholder) lives inside the module.
+ * A "seam" for it degenerates into exactly the thing THE ALL-INCLUSIVE LAW
+ * names as the failure — "the `next/image`/`next/link` wrappers" that every
+ * host was rebuilding by hand (matrx-frontend's was 35 lines of prop
+ * forwarding with four `as` casts). So this ONE entry takes `next` as an
+ * OPTIONAL peer and owns the wrapper; no other entry in the package may.
+ *
+ * The seam is preserved where it still buys something: the package's
+ * components never import this module. They call `MediaHostPorts.ImageComponent`,
+ * which defaults to a plain `<img>`. A Next host assigns `NextMediaImage` (or
+ * a configured one) and nothing else in the package learns that Next exists.
+ */
+
+/**
+ * Structural mirror of Next's `ImageLoaderProps` — declared here so the
+ * package's public types never re-export a `next/*` type (which would make
+ * the shape of our API depend on the consumer's Next version).
+ */
+interface NextMediaImageLoaderArgs {
+    source: string;
+    width: number;
+    quality?: number | undefined;
+}
+interface NextMediaImageOptions {
+    /**
+     * Skip Next's optimizer endpoint. Defaults to `true`, which is the ONLY
+     * correct default for Matrx media: durable file URLs are session-cookie
+     * authenticated, and `/_next/image` fetches them from the SERVER, which
+     * carries no user session — an optimized private image 404s. Set this to
+     * `false` only for a host whose media is genuinely public CDN content and
+     * whose `next.config` allows the remote pattern.
+     */
+    unoptimized?: boolean | undefined;
+    quality?: number | undefined;
+    sizes?: string | undefined;
+    priority?: boolean | undefined;
+    loader?: ((args: NextMediaImageLoaderArgs) => string) | undefined;
+    /** Extra class applied under the caller's `className` (last-wins merge). */
+    className?: string | undefined;
+}
+/**
+ * Build a Next.js `ImageComponent` port with fixed options.
+ *
+ * ```tsx
+ * const ports: MediaHostPorts = {
+ *   ImageComponent: createNextMediaImageComponent({ quality: 90 }),
+ * };
+ * ```
+ */
+declare function createNextMediaImageComponent(options?: NextMediaImageOptions): (props: MediaImageComponentProps) => React.ReactElement;
+/**
+ * The zero-configuration Next.js `ImageComponent` port — `unoptimized`, every
+ * port prop forwarded. This is the whole of what a Next host needs:
+ *
+ * ```tsx
+ * import { NextMediaImage } from "@ai-matrx/media/next";
+ * const ports: MediaHostPorts = { ImageComponent: NextMediaImage };
+ * ```
+ */
+declare const NextMediaImage: (props: MediaImageComponentProps) => React.ReactElement;
+
+export { NextMediaImage, type NextMediaImageLoaderArgs, type NextMediaImageOptions, createNextMediaImageComponent };

package/dist/next.d.ts

@@ -0,0 +1,74 @@
+import { MediaImageComponentProps } from './index.js';
+
+/**
+ * src/next/image.tsx — the Next.js `ImageComponent` port implementation.
+ *
+ * WHY THIS ENTRY IMPORTS `next/image` (the deliberate divergence from the
+ * data 0.5.0 `/next` precedent, which imports NO `next/*` module):
+ *
+ * `@ai-matrx/data/next` could keep Next out of its source because everything
+ * it needed from Next — `cookies()`, `NextResponse` — is DATA passed across a
+ * structural seam. `next/image` is not data: it is the rendering component
+ * itself, and its entire value (the optimizer endpoint, the srcset builder,
+ * the lazy/priority machinery, the blur placeholder) lives inside the module.
+ * A "seam" for it degenerates into exactly the thing THE ALL-INCLUSIVE LAW
+ * names as the failure — "the `next/image`/`next/link` wrappers" that every
+ * host was rebuilding by hand (matrx-frontend's was 35 lines of prop
+ * forwarding with four `as` casts). So this ONE entry takes `next` as an
+ * OPTIONAL peer and owns the wrapper; no other entry in the package may.
+ *
+ * The seam is preserved where it still buys something: the package's
+ * components never import this module. They call `MediaHostPorts.ImageComponent`,
+ * which defaults to a plain `<img>`. A Next host assigns `NextMediaImage` (or
+ * a configured one) and nothing else in the package learns that Next exists.
+ */
+
+/**
+ * Structural mirror of Next's `ImageLoaderProps` — declared here so the
+ * package's public types never re-export a `next/*` type (which would make
+ * the shape of our API depend on the consumer's Next version).
+ */
+interface NextMediaImageLoaderArgs {
+    source: string;
+    width: number;
+    quality?: number | undefined;
+}
+interface NextMediaImageOptions {
+    /**
+     * Skip Next's optimizer endpoint. Defaults to `true`, which is the ONLY
+     * correct default for Matrx media: durable file URLs are session-cookie
+     * authenticated, and `/_next/image` fetches them from the SERVER, which
+     * carries no user session — an optimized private image 404s. Set this to
+     * `false` only for a host whose media is genuinely public CDN content and
+     * whose `next.config` allows the remote pattern.
+     */
+    unoptimized?: boolean | undefined;
+    quality?: number | undefined;
+    sizes?: string | undefined;
+    priority?: boolean | undefined;
+    loader?: ((args: NextMediaImageLoaderArgs) => string) | undefined;
+    /** Extra class applied under the caller's `className` (last-wins merge). */
+    className?: string | undefined;
+}
+/**
+ * Build a Next.js `ImageComponent` port with fixed options.
+ *
+ * ```tsx
+ * const ports: MediaHostPorts = {
+ *   ImageComponent: createNextMediaImageComponent({ quality: 90 }),
+ * };
+ * ```
+ */
+declare function createNextMediaImageComponent(options?: NextMediaImageOptions): (props: MediaImageComponentProps) => React.ReactElement;
+/**
+ * The zero-configuration Next.js `ImageComponent` port — `unoptimized`, every
+ * port prop forwarded. This is the whole of what a Next host needs:
+ *
+ * ```tsx
+ * import { NextMediaImage } from "@ai-matrx/media/next";
+ * const ports: MediaHostPorts = { ImageComponent: NextMediaImage };
+ * ```
+ */
+declare const NextMediaImage: (props: MediaImageComponentProps) => React.ReactElement;
+
+export { NextMediaImage, type NextMediaImageLoaderArgs, type NextMediaImageOptions, createNextMediaImageComponent };

package/dist/next.js

@@ -0,0 +1,60 @@
+"use client";
+
+// src/next/image.tsx
+import Image from "next/image";
+import { jsx } from "react/jsx-runtime";
+function createNextMediaImageComponent(options = {}) {
+  const {
+    unoptimized = true,
+    quality,
+    sizes,
+    priority,
+    loader,
+    className: baseClassName
+  } = options;
+  function NextMediaImageWithOptions({
+    src,
+    alt,
+    width,
+    height,
+    className,
+    onError,
+    onClick,
+    onKeyDown,
+    role,
+    tabIndex
+  }) {
+    return /* @__PURE__ */ jsx(
+      Image,
+      {
+        src,
+        alt,
+        width,
+        height,
+        unoptimized,
+        ...quality !== void 0 ? { quality } : {},
+        ...sizes !== void 0 ? { sizes } : {},
+        ...priority !== void 0 ? { priority } : {},
+        ...loader !== void 0 ? {
+          loader: ({ src: src2, width: width2, quality: loaderQuality }) => loader({ source: src2, width: width2, quality: loaderQuality })
+        } : {},
+        ...baseClassName !== void 0 || className !== void 0 ? {
+          className: [baseClassName, className].filter((part) => !!part).join(" ")
+        } : {},
+        ...onError !== void 0 ? { onError } : {},
+        ...onClick !== void 0 ? { onClick } : {},
+        ...onKeyDown !== void 0 ? { onKeyDown } : {},
+        ...role !== void 0 ? { role } : {},
+        ...tabIndex !== void 0 ? { tabIndex } : {}
+      }
+    );
+  }
+  NextMediaImageWithOptions.displayName = "NextMediaImage";
+  return NextMediaImageWithOptions;
+}
+var NextMediaImage = createNextMediaImageComponent();
+export {
+  NextMediaImage,
+  createNextMediaImageComponent
+};
+//# sourceMappingURL=next.js.map

package/dist/next.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/next/image.tsx"],"sourcesContent":["/**\n * src/next/image.tsx — the Next.js `ImageComponent` port implementation.\n *\n * WHY THIS ENTRY IMPORTS `next/image` (the deliberate divergence from the\n * data 0.5.0 `/next` precedent, which imports NO `next/*` module):\n *\n * `@ai-matrx/data/next` could keep Next out of its source because everything\n * it needed from Next — `cookies()`, `NextResponse` — is DATA passed across a\n * structural seam. `next/image` is not data: it is the rendering component\n * itself, and its entire value (the optimizer endpoint, the srcset builder,\n * the lazy/priority machinery, the blur placeholder) lives inside the module.\n * A \"seam\" for it degenerates into exactly the thing THE ALL-INCLUSIVE LAW\n * names as the failure — \"the `next/image`/`next/link` wrappers\" that every\n * host was rebuilding by hand (matrx-frontend's was 35 lines of prop\n * forwarding with four `as` casts). So this ONE entry takes `next` as an\n * OPTIONAL peer and owns the wrapper; no other entry in the package may.\n *\n * The seam is preserved where it still buys something: the package's\n * components never import this module. They call `MediaHostPorts.ImageComponent`,\n * which defaults to a plain `<img>`. A Next host assigns `NextMediaImage` (or\n * a configured one) and nothing else in the package learns that Next exists.\n */\n\n\"use client\";\n\nimport Image from \"next/image\";\nimport type { MediaImageComponentProps } from \"../types\";\n\n/**\n * Structural mirror of Next's `ImageLoaderProps` — declared here so the\n * package's public types never re-export a `next/*` type (which would make\n * the shape of our API depend on the consumer's Next version).\n */\nexport interface NextMediaImageLoaderArgs {\n  source: string;\n  width: number;\n  quality?: number | undefined;\n}\n\nexport interface NextMediaImageOptions {\n  /**\n   * Skip Next's optimizer endpoint. Defaults to `true`, which is the ONLY\n   * correct default for Matrx media: durable file URLs are session-cookie\n   * authenticated, and `/_next/image` fetches them from the SERVER, which\n   * carries no user session — an optimized private image 404s. Set this to\n   * `false` only for a host whose media is genuinely public CDN content and\n   * whose `next.config` allows the remote pattern.\n   */\n  unoptimized?: boolean | undefined;\n  quality?: number | undefined;\n  sizes?: string | undefined;\n  priority?: boolean | undefined;\n  loader?: ((args: NextMediaImageLoaderArgs) => string) | undefined;\n  /** Extra class applied under the caller's `className` (last-wins merge). */\n  className?: string | undefined;\n}\n\n/**\n * Build a Next.js `ImageComponent` port with fixed options.\n *\n * ```tsx\n * const ports: MediaHostPorts = {\n *   ImageComponent: createNextMediaImageComponent({ quality: 90 }),\n * };\n * ```\n */\nexport function createNextMediaImageComponent(\n  options: NextMediaImageOptions = {},\n): (props: MediaImageComponentProps) => React.ReactElement {\n  const {\n    unoptimized = true,\n    quality,\n    sizes,\n    priority,\n    loader,\n    className: baseClassName,\n  } = options;\n\n  function NextMediaImageWithOptions({\n    src,\n    alt,\n    width,\n    height,\n    className,\n    onError,\n    onClick,\n    onKeyDown,\n    role,\n    tabIndex,\n  }: MediaImageComponentProps): React.ReactElement {\n    return (\n      <Image\n        src={src}\n        alt={alt}\n        width={width}\n        height={height}\n        unoptimized={unoptimized}\n        {...(quality !== undefined ? { quality } : {})}\n        {...(sizes !== undefined ? { sizes } : {})}\n        {...(priority !== undefined ? { priority } : {})}\n        {...(loader !== undefined\n          ? {\n              loader: ({ src, width, quality: loaderQuality }) =>\n                loader({ source: src, width, quality: loaderQuality }),\n            }\n          : {})}\n        {...(baseClassName !== undefined || className !== undefined\n          ? {\n              className: [baseClassName, className]\n                .filter((part): part is string => !!part)\n                .join(\" \"),\n            }\n          : {})}\n        // The port's handlers are structurally typed (`(event: unknown) => void`)\n        // so the root entry stays free of React type imports. Narrowing them to\n        // the DOM handler shapes is this binding's job — a host must never write\n        // these casts again (C22: the massage lives in the package).\n        {...(onError !== undefined\n          ? { onError: onError as React.ReactEventHandler<HTMLImageElement> }\n          : {})}\n        {...(onClick !== undefined\n          ? { onClick: onClick as React.MouseEventHandler<HTMLImageElement> }\n          : {})}\n        {...(onKeyDown !== undefined\n          ? { onKeyDown: onKeyDown as React.KeyboardEventHandler<HTMLImageElement> }\n          : {})}\n        {...(role !== undefined ? { role } : {})}\n        {...(tabIndex !== undefined ? { tabIndex } : {})}\n      />\n    );\n  }\n\n  NextMediaImageWithOptions.displayName = \"NextMediaImage\";\n  return NextMediaImageWithOptions;\n}\n\n/**\n * The zero-configuration Next.js `ImageComponent` port — `unoptimized`, every\n * port prop forwarded. This is the whole of what a Next host needs:\n *\n * ```tsx\n * import { NextMediaImage } from \"@ai-matrx/media/next\";\n * const ports: MediaHostPorts = { ImageComponent: NextMediaImage };\n * ```\n */\nexport const NextMediaImage = createNextMediaImageComponent();\n"],"mappings":";;;AAyBA,OAAO,WAAW;AAkEZ;AAzBC,SAAS,8BACd,UAAiC,CAAC,GACuB;AACzD,QAAM;AAAA,IACJ,cAAc;AAAA,IACd;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA,WAAW;AAAA,EACb,IAAI;AAEJ,WAAS,0BAA0B;AAAA,IACjC;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF,GAAiD;AAC/C,WACE;AAAA,MAAC;AAAA;AAAA,QACC;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACC,GAAI,YAAY,SAAY,EAAE,QAAQ,IAAI,CAAC;AAAA,QAC3C,GAAI,UAAU,SAAY,EAAE,MAAM,IAAI,CAAC;AAAA,QACvC,GAAI,aAAa,SAAY,EAAE,SAAS,IAAI,CAAC;AAAA,QAC7C,GAAI,WAAW,SACZ;AAAA,UACE,QAAQ,CAAC,EAAE,KAAAA,MAAK,OAAAC,QAAO,SAAS,cAAc,MAC5C,OAAO,EAAE,QAAQD,MAAK,OAAAC,QAAO,SAAS,cAAc,CAAC;AAAA,QACzD,IACA,CAAC;AAAA,QACJ,GAAI,kBAAkB,UAAa,cAAc,SAC9C;AAAA,UACE,WAAW,CAAC,eAAe,SAAS,EACjC,OAAO,CAAC,SAAyB,CAAC,CAAC,IAAI,EACvC,KAAK,GAAG;AAAA,QACb,IACA,CAAC;AAAA,QAKJ,GAAI,YAAY,SACb,EAAE,QAA8D,IAChE,CAAC;AAAA,QACJ,GAAI,YAAY,SACb,EAAE,QAA8D,IAChE,CAAC;AAAA,QACJ,GAAI,cAAc,SACf,EAAE,UAAqE,IACvE,CAAC;AAAA,QACJ,GAAI,SAAS,SAAY,EAAE,KAAK,IAAI,CAAC;AAAA,QACrC,GAAI,aAAa,SAAY,EAAE,SAAS,IAAI,CAAC;AAAA;AAAA,IAChD;AAAA,EAEJ;AAEA,4BAA0B,cAAc;AACxC,SAAO;AACT;AAWO,IAAM,iBAAiB,8BAA8B;","names":["src","width"]}

package/dist/react.cjs

@@ -1803,7 +1803,7 @@ var import_react11 = require("react");
 var import_jsx_runtime5 = require("react/jsx-runtime");
 var AUTO_DISMISS_MS = 1e4;
 function formatFileSize(bytes) {
-  if (!Number.isFinite(bytes) || bytes < 0) return "0 B";
+  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;