@ai-matrx/media 0.1.0

package/dist/core.cjs

@@ -0,0 +1,577 @@
+"use client";
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/core.ts
+var core_exports = {};
+__export(core_exports, {
+  MediaProvider: () => MediaProvider,
+  getFileKindDetails: () => getFileKindDetails,
+  getFolderKindDetails: () => getFolderKindDetails,
+  stableRefKey: () => stableRefKey,
+  useMediaActions: () => useMediaActions,
+  useMediaBlob: () => useMediaBlob,
+  useMediaClient: () => useMediaClient,
+  useMediaHostPorts: () => useMediaHostPorts,
+  useMediaLoadRecovery: () => useMediaLoadRecovery,
+  useMediaResolution: () => useMediaResolution,
+  useMediaUpload: () => useMediaUpload,
+  useThumbnailSource: () => useThumbnailSource
+});
+module.exports = __toCommonJS(core_exports);
+
+// src/core/context.ts
+var import_react = require("react");
+var CLIENT_SLOT = /* @__PURE__ */ Symbol.for("ai-matrx.media.client-context");
+var PORTS_SLOT = /* @__PURE__ */ Symbol.for("ai-matrx.media.host-ports-context");
+function clientContext() {
+  const host = globalThis;
+  host[CLIENT_SLOT] ??= (0, import_react.createContext)(null);
+  return host[CLIENT_SLOT];
+}
+var INERT_PORTS = {};
+function portsContext() {
+  const host = globalThis;
+  host[PORTS_SLOT] ??= (0, import_react.createContext)(INERT_PORTS);
+  return host[PORTS_SLOT];
+}
+function MediaProvider({ client, ports, children }) {
+  const ClientCtx = clientContext();
+  const PortsCtx = portsContext();
+  return (0, import_react.createElement)(
+    ClientCtx.Provider,
+    { value: client },
+    (0, import_react.createElement)(PortsCtx.Provider, { value: ports ?? INERT_PORTS }, children)
+  );
+}
+function useMediaClient() {
+  const client = (0, import_react.useContext)(clientContext());
+  if (!client) {
+    throw new Error(
+      "@ai-matrx/media: no MediaClient. Mount <MediaProvider client={...}> above every media surface (canonically wired to @ai-matrx/data/files)."
+    );
+  }
+  return client;
+}
+function useMediaHostPorts() {
+  return (0, import_react.useContext)(portsContext());
+}
+
+// src/core/ref-key.ts
+function stableRefKey(ref) {
+  if (!ref) return "<none>";
+  if (typeof ref === "string") return `s:${ref}`;
+  if (ref.file_id) return `id:${ref.file_id}:${ref.mime_type ?? ""}`;
+  if (ref.url) return `url:${ref.url}:${ref.mime_type ?? ""}`;
+  return "<empty-ref>";
+}
+
+// src/core/use-media-resolution.ts
+var import_react2 = require("react");
+function useMediaResolution(ref) {
+  const client = useMediaClient();
+  const refKey = stableRefKey(ref);
+  return (0, import_react2.useMemo)(() => {
+    if (!ref) return { resolution: null, status: "empty", reason: null };
+    try {
+      const resolution = client.resolve(ref);
+      if (!resolution) return { resolution: null, status: "empty", reason: null };
+      return { resolution, status: "ready", reason: null };
+    } catch (err) {
+      return {
+        resolution: null,
+        status: "unavailable",
+        reason: client.classifyError(err)
+      };
+    }
+  }, [client, refKey]);
+}
+
+// src/core/use-media-load-recovery.ts
+var import_react3 = require("react");
+
+// src/types.ts
+function mintDurableSrc(url) {
+  return url;
+}
+
+// src/core/use-media-load-recovery.ts
+function useMediaLoadRecovery(src, options) {
+  const client = useMediaClient();
+  const recoverable = options?.recoverable !== false;
+  const onTerminal = options?.onTerminal;
+  const [result, setResult] = (0, import_react3.useState)({ source: src, retryKey: 0, failed: false });
+  const attemptRef = (0, import_react3.useRef)(0);
+  (0, import_react3.useEffect)(() => {
+    attemptRef.current = 0;
+  }, [src]);
+  const onLoadError = (event) => {
+    if (!src || !recoverable) {
+      setResult({ source: src, retryKey: 0, failed: true });
+      onTerminal?.(event);
+      return;
+    }
+    attemptRef.current += 1;
+    const attempt = attemptRef.current;
+    client.recoverLoadError(mintDurableSrc(src), attempt).then(
+      (verdict) => {
+        if (verdict === "retry") {
+          setResult((current) => ({
+            source: src,
+            retryKey: current.source === src ? current.retryKey + 1 : 1,
+            failed: false
+          }));
+        } else {
+          setResult({ source: src, retryKey: 0, failed: true });
+          onTerminal?.(event);
+        }
+      },
+      () => {
+        setResult({ source: src, retryKey: 0, failed: true });
+        onTerminal?.(event);
+      }
+    );
+  };
+  return {
+    retryKey: result.source === src ? result.retryKey : 0,
+    onLoadError,
+    failed: result.source === src ? result.failed : false
+  };
+}
+
+// src/core/use-media-blob.ts
+var import_react4 = require("react");
+function useMediaBlob(ref) {
+  const client = useMediaClient();
+  const refKey = stableRefKey(ref);
+  const [state, setState] = (0, import_react4.useState)({ url: null, blob: null, loading: !!ref, error: null });
+  const [retryToken, setRetryToken] = (0, import_react4.useState)(0);
+  (0, import_react4.useEffect)(() => {
+    if (!ref) {
+      setState({ url: null, blob: null, loading: false, error: null });
+      return void 0;
+    }
+    let cancelled = false;
+    let release = null;
+    setState({ url: null, blob: null, loading: true, error: null });
+    client.getBlob(ref).then(
+      (handle) => {
+        if (cancelled) {
+          handle.release();
+          return;
+        }
+        release = handle.release;
+        setState({ url: handle.url, blob: handle.blob, loading: false, error: null });
+      },
+      (err) => {
+        if (cancelled) return;
+        const message = err instanceof Error ? err.message : String(err ?? "Failed to load file");
+        setState({ url: null, blob: null, loading: false, error: message });
+      }
+    );
+    return () => {
+      cancelled = true;
+      release?.();
+    };
+  }, [client, refKey, retryToken]);
+  return {
+    ...state,
+    retry: () => setRetryToken((t) => t + 1)
+  };
+}
+
+// src/core/use-media-upload.ts
+var import_react5 = require("react");
+var entrySeq = 0;
+function useMediaUpload() {
+  const client = useMediaClient();
+  const [uploading, setUploading] = (0, import_react5.useState)(false);
+  const [progress, setProgress] = (0, import_react5.useState)(null);
+  const [result, setResult] = (0, import_react5.useState)(null);
+  const [error, setError] = (0, import_react5.useState)(null);
+  const [entries, setEntries] = (0, import_react5.useState)([]);
+  const activeCount = (0, import_react5.useRef)(0);
+  const patchEntry = (0, import_react5.useCallback)(
+    (id, patch) => {
+      setEntries(
+        (current) => current.map((e) => e.id === id ? { ...e, ...patch } : e)
+      );
+    },
+    []
+  );
+  const upload = (0, import_react5.useCallback)(
+    async (file, opts = {}) => {
+      const id = `up-${++entrySeq}`;
+      const fileName = opts.fileName ?? (file instanceof File ? file.name : "file");
+      setEntries((current) => [
+        ...current,
+        {
+          id,
+          fileName,
+          fileSize: file.size,
+          bytesUploaded: 0,
+          status: "uploading",
+          error: null,
+          fileId: null,
+          completedAt: null
+        }
+      ]);
+      activeCount.current += 1;
+      setUploading(true);
+      setError(null);
+      setProgress(null);
+      try {
+        const uploaded = await client.upload(file, {
+          ...opts,
+          onProgress: (loaded, total) => {
+            setProgress({ loaded, total, ratio: total > 0 ? loaded / total : 0 });
+            patchEntry(id, { bytesUploaded: loaded });
+            opts.onProgress?.(loaded, total);
+          }
+        });
+        setResult(uploaded);
+        patchEntry(id, {
+          status: "success",
+          fileId: uploaded.fileId,
+          bytesUploaded: file.size,
+          completedAt: Date.now()
+        });
+        return uploaded;
+      } catch (err) {
+        const e = err instanceof Error ? err : new Error(String(err));
+        setError(e);
+        patchEntry(id, {
+          status: "error",
+          error: e.message,
+          completedAt: Date.now()
+        });
+        throw e;
+      } finally {
+        activeCount.current -= 1;
+        if (activeCount.current <= 0) setUploading(false);
+      }
+    },
+    [client, patchEntry]
+  );
+  const uploadMany = (0, import_react5.useCallback)(
+    async (files, opts = {}) => {
+      if (client.uploadMany) {
+        activeCount.current += 1;
+        setUploading(true);
+        try {
+          return await client.uploadMany(files, opts);
+        } finally {
+          activeCount.current -= 1;
+          if (activeCount.current <= 0) setUploading(false);
+        }
+      }
+      const uploaded = [];
+      const failed = [];
+      for (const file of files) {
+        try {
+          const one = await upload(file, opts);
+          uploaded.push(one.fileId);
+        } catch (err) {
+          failed.push({
+            name: file.name,
+            error: err instanceof Error ? err.message : String(err)
+          });
+        }
+      }
+      return { uploaded, failed, cancelled: false };
+    },
+    [client, upload]
+  );
+  const clearEntry = (0, import_react5.useCallback)((id) => {
+    setEntries((current) => current.filter((e) => e.id !== id));
+  }, []);
+  const reset = (0, import_react5.useCallback)(() => {
+    setResult(null);
+    setError(null);
+    setProgress(null);
+    setEntries([]);
+  }, []);
+  return {
+    upload,
+    uploadMany,
+    uploading,
+    progress,
+    result,
+    error,
+    entries,
+    clearEntry,
+    reset
+  };
+}
+
+// src/core/use-thumbnail-source.ts
+var import_react6 = require("react");
+function useThumbnailSource(ref, options = {}) {
+  const { thumbnailUrl, allowSourceFallback = true } = options;
+  const client = useMediaClient();
+  const { resolution } = useMediaResolution(ref);
+  const explicitThumb = (0, import_react6.useMemo)(() => {
+    if (!thumbnailUrl) return null;
+    try {
+      return client.resolve(thumbnailUrl);
+    } catch {
+      return null;
+    }
+  }, [client, thumbnailUrl]);
+  const needsBlob = allowSourceFallback && !explicitThumb && !resolution?.thumbnailSrc && resolution?.transport === "blob";
+  const blob = useMediaBlob(needsBlob ? ref : null);
+  if (explicitThumb) {
+    return {
+      src: explicitThumb.src,
+      mode: "thumbnail",
+      loading: false,
+      resolution,
+      recoverable: explicitThumb.recoverable !== false
+    };
+  }
+  if (resolution?.thumbnailSrc) {
+    return {
+      src: resolution.thumbnailSrc,
+      mode: "thumbnail",
+      loading: false,
+      resolution,
+      recoverable: resolution.recoverable !== false
+    };
+  }
+  if (allowSourceFallback && resolution) {
+    if (needsBlob) {
+      return {
+        src: blob.url,
+        mode: blob.url ? resolution.kind === "video" ? "live-video-poster" : "live-image" : "icon",
+        loading: blob.loading,
+        resolution,
+        recoverable: false
+      };
+    }
+    if (resolution.kind === "image") {
+      return {
+        src: resolution.src,
+        mode: "live-image",
+        loading: false,
+        resolution,
+        recoverable: resolution.recoverable !== false
+      };
+    }
+    if (resolution.kind === "video") {
+      return {
+        src: resolution.src,
+        mode: "live-video-poster",
+        loading: false,
+        resolution,
+        recoverable: resolution.recoverable !== false
+      };
+    }
+  }
+  return {
+    src: null,
+    mode: "icon",
+    loading: false,
+    resolution,
+    recoverable: false
+  };
+}
+
+// src/core/use-media-actions.ts
+var import_react7 = require("react");
+function useMediaActions(ref, options = {}) {
+  const ports = useMediaHostPorts();
+  const { resolution } = useMediaResolution(ref);
+  const [busy, setBusy] = (0, import_react7.useState)(null);
+  const [lastError, setLastError] = (0, import_react7.useState)(null);
+  const actions = ports.actions;
+  const { fileName, alt } = options;
+  const context = (0, import_react7.useMemo)(() => {
+    if (!ref) return null;
+    return { ref, resolution, fileName, alt };
+  }, [ref, resolution, fileName, alt]);
+  const isAvailable = (0, import_react7.useCallback)(
+    (kind) => {
+      if (!context || !actions) return false;
+      if (kind === "share") return Boolean(actions.share || actions.SharePopover);
+      return Boolean(actions[kind]);
+    },
+    [context, actions]
+  );
+  const run = (0, import_react7.useCallback)(
+    async (kind) => {
+      if (!context || !actions) return;
+      const handler = actions[kind];
+      if (!handler) return;
+      setBusy(kind);
+      setLastError(null);
+      try {
+        await handler(context);
+      } catch (err) {
+        setLastError({
+          kind,
+          message: err instanceof Error ? err.message : String(err)
+        });
+      } finally {
+        setBusy(null);
+      }
+    },
+    [context, actions]
+  );
+  return {
+    context,
+    isAvailable,
+    run,
+    busy,
+    lastError,
+    SharePopover: actions?.SharePopover ?? null
+  };
+}
+
+// src/core/file-kind.ts
+var ROWS = [
+  [["jpg", "jpeg", "png", "gif", "webp", "avif", "heic", "heif", "bmp", "tif", "tiff", "ico"], "IMAGE", "text-emerald-500", "image", "Image"],
+  [["svg"], "IMAGE", "text-amber-500", "pen-tool", "SVG image"],
+  [["mp4", "mov", "webm", "mkv", "avi", "m4v"], "VIDEO", "text-purple-500", "video", "Video"],
+  [["mp3", "wav", "ogg", "m4a", "aac", "flac", "opus"], "AUDIO", "text-pink-500", "music", "Audio"],
+  [["pdf"], "DOCUMENT", "text-red-500", "file-type", "PDF Document"],
+  [["md", "markdown", "mdx", "rst", "adoc", "asciidoc", "org"], "DOCUMENT", "text-slate-400", "file-text", "Markdown"],
+  [["txt", "text", "asc", "me", "log", "out", "err"], "DOCUMENT", "text-muted-foreground", "file-text", "Text"],
+  [["dockerfile", "containerfile", "lua"], "CODE", "text-blue-500", "code", "Code"],
+  [["mk", "make", "swift", "ml", "mli", "fs", "fsi", "fsx", "svelte"], "CODE", "text-orange-500", "code", "Code"],
+  [["diff", "patch", "pem", "csr", "crt", "cer", "der", "key", "pub", "p7b", "p7c", "pfx", "p12"], "CODE", "text-amber-500", "file-text", "Text"],
+  [["ini", "cfg", "conf", "config", "properties", "prefs"], "CODE", "text-amber-400", "braces", "Config"],
+  [["tex", "latex", "ltx", "sty", "cls", "bib"], "CODE", "text-emerald-500", "file-text", "LaTeX"],
+  [["srt", "vtt"], "SUBTITLES", "text-cyan-500", "subtitles", "Subtitles"],
+  [["js", "mjs", "cjs", "jsx"], "CODE", "text-yellow-500", "file-code", "JavaScript"],
+  [["ts", "tsx"], "CODE", "text-blue-500", "file-code", "TypeScript"],
+  [["py", "clj", "cljs", "cljc", "edn", "vue", "styl", "stylus"], "CODE", "text-emerald-500", "code", "Code"],
+  [["rb", "rbw", "rake", "ru", "gemspec", "scala", "sbt"], "CODE", "text-red-500", "code", "Code"],
+  [["go", "dart"], "CODE", "text-cyan-500", "code", "Code"],
+  [["rs"], "CODE", "text-orange-600", "code", "Rust"],
+  [["java"], "CODE", "text-red-600", "code", "Java"],
+  [["c", "h"], "CODE", "text-blue-600", "code", "C"],
+  [["cpp", "cc", "cxx", "hpp"], "CODE", "text-blue-700", "code", "C++"],
+  [["cs"], "CODE", "text-purple-600", "code", "C#"],
+  [["html", "htm", "kt", "kts"], "CODE", "text-orange-400", "code", "Code"],
+  [["css"], "CODE", "text-sky-400", "code", "CSS"],
+  [["scss"], "CODE", "text-pink-400", "code", "SCSS"],
+  [["sh", "bash", "zsh", "fish", "ksh", "ash", "bat", "cmd", "twig", "jinja", "j2", "njk"], "CODE", "text-emerald-400", "code", "Script"],
+  [["sql"], "CODE", "text-amber-400", "code", "SQL"],
+  [["pl", "pm"], "CODE", "text-indigo-400", "code", "Perl"],
+  [["r", "rmd", "proto", "ps1", "psm1", "psd1", "less"], "CODE", "text-blue-400", "code", "Code"],
+  [["ex", "exs"], "CODE", "text-purple-400", "code", "Elixir"],
+  [["erl", "hrl"], "CODE", "text-rose-500", "code", "Erlang"],
+  [["hs", "lhs"], "CODE", "text-violet-500", "code", "Haskell"],
+  [["zig"], "CODE", "text-yellow-500", "code", "Zig"],
+  [["nim", "nims"], "CODE", "text-yellow-400", "code", "Nim"],
+  [["jl"], "CODE", "text-purple-500", "code", "Julia"],
+  [["astro"], "CODE", "text-fuchsia-500", "code", "Astro"],
+  [["graphql", "gql", "graphqls"], "CODE", "text-pink-500", "code", "GraphQL"],
+  [["sol"], "CODE", "text-slate-400", "code", "Solidity"],
+  [["php", "phtml", "phps"], "CODE", "text-indigo-500", "code", "PHP"],
+  [["hbs", "handlebars", "mustache", "ejs", "liquid"], "CODE", "text-amber-500", "code", "Template"],
+  [["json", "jsonc", "json5", "har", "geojson", "topojson"], "DATA", "text-amber-500", "file-json", "JSON"],
+  [["yaml", "yml", "toml"], "CODE", "text-amber-500", "braces", "Config"],
+  [["xml"], "DATA", "text-amber-500", "braces", "XML"],
+  [["csv", "tsv"], "DATA", "text-orange-500", "file-spreadsheet", "Spreadsheet data"],
+  [["sqlite", "sqlite3", "db"], "DATA", "text-blue-400", "database", "Database"],
+  [["ttl", "n3", "nt", "nq", "trig"], "DATA", "text-fuchsia-400", "braces", "RDF data"],
+  [["xlsx", "xls"], "DOCUMENT", "text-emerald-600", "file-spreadsheet", "Excel workbook"],
+  [["doc", "docx"], "DOCUMENT", "text-blue-500", "file-text", "Word document"],
+  [["ppt", "pptx"], "DOCUMENT", "text-orange-600", "file-type", "Presentation"],
+  [["ipynb"], "NOTEBOOK", "text-orange-400", "file-json", "Notebook"],
+  [["epub"], "EBOOK", "text-indigo-500", "file-text", "eBook"],
+  [["eml"], "EMAIL", "text-blue-400", "file-text", "Email"],
+  [["glb", "gltf", "stl", "obj", "fbx"], "MODEL_3D", "text-violet-400", "package", "3D model"],
+  [["zip", "rar", "7z"], "ARCHIVE", "text-amber-600", "archive", "Archive"],
+  [["tar", "gz", "tgz"], "ARCHIVE", "text-amber-600", "package", "Archive"]
+];
+var BY_EXTENSION = /* @__PURE__ */ new Map();
+for (const [extensions, category, colorClass, icon, displayName] of ROWS) {
+  for (const ext of extensions) {
+    BY_EXTENSION.set(ext, { category, colorClass, icon, displayName });
+  }
+}
+var UNKNOWN_DETAILS = {
+  category: "UNKNOWN",
+  displayName: "File",
+  colorClass: "text-muted-foreground",
+  icon: "file"
+};
+var ASSUMED_TEXT_DETAILS = {
+  category: "DOCUMENT",
+  displayName: "Text",
+  colorClass: "text-muted-foreground",
+  icon: "file-text"
+};
+var FOLDER_DETAILS = {
+  category: "FOLDER",
+  displayName: "Folder",
+  colorClass: "text-sky-500",
+  icon: "folder"
+};
+var IMAGE_DETAILS = BY_EXTENSION.get("png");
+var VIDEO_DETAILS = BY_EXTENSION.get("mp4");
+var AUDIO_DETAILS = BY_EXTENSION.get("mp3");
+var PDF_DETAILS = BY_EXTENSION.get("pdf");
+var SVG_DETAILS = BY_EXTENSION.get("svg");
+function basenameOf(path) {
+  const idx = Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\"));
+  return idx >= 0 ? path.slice(idx + 1) : path;
+}
+function extOf(name) {
+  const idx = name.lastIndexOf(".");
+  if (idx <= 0 || idx === name.length - 1) return null;
+  return name.slice(idx + 1).toLowerCase();
+}
+function dotfileLooksLikeText(filename) {
+  const name = basenameOf(filename);
+  if (!name.startsWith(".")) return false;
+  for (let i = 1; i < name.length; i++) {
+    const c = name.charCodeAt(i);
+    if (c >= 48 && c <= 57 || c >= 65 && c <= 90 || c >= 97 && c <= 122 || c === 95 || c === 45) {
+      return true;
+    }
+  }
+  return false;
+}
+function canonicalMimeBase(raw) {
+  return raw.split(";")[0]?.trim().toLowerCase() ?? raw;
+}
+function getFileKindDetails(fileName, mimeType) {
+  const name = basenameOf(fileName);
+  const lower = name.toLowerCase();
+  const ext = lower === "dockerfile" || lower === "containerfile" ? lower : extOf(name);
+  const fromExt = ext ? BY_EXTENSION.get(ext) : void 0;
+  const mime = mimeType ? canonicalMimeBase(mimeType) : null;
+  if (mime) {
+    if (mime === "image/svg+xml") return fromExt ?? SVG_DETAILS;
+    if (mime.startsWith("image/")) return fromExt?.category === "IMAGE" ? fromExt : IMAGE_DETAILS;
+    if (mime.startsWith("video/")) return fromExt?.category === "VIDEO" ? fromExt : VIDEO_DETAILS;
+    if (mime.startsWith("audio/")) return fromExt?.category === "AUDIO" ? fromExt : AUDIO_DETAILS;
+    if (mime === "application/pdf") return PDF_DETAILS;
+  }
+  if (fromExt) return fromExt;
+  if (dotfileLooksLikeText(fileName)) return ASSUMED_TEXT_DETAILS;
+  return UNKNOWN_DETAILS;
+}
+function getFolderKindDetails(open = false) {
+  return open ? { ...FOLDER_DETAILS, icon: "folder-open" } : FOLDER_DETAILS;
+}
+//# sourceMappingURL=core.cjs.map