@ai-matrx/media 0.7.16 → 0.9.0

package/dist/files/engine/handler/input/normalize.js

@@ -0,0 +1,365 @@
+import { classify } from "../utils/classify.js";
+import { pythonFileInlineUrl, pythonShareUrl } from "../utils/python-base.js";
+import { createTrackedObjectUrl } from "../../../../files.js";
+import {
+  EPHEMERAL_CAPS,
+  EXTERNAL_CAPS,
+  PUBLIC_CAPS
+} from "../intelligence/access.js";
+const STREAM_RENDER_TYPES = /* @__PURE__ */ new Set(["image", "audio", "video", "document"]);
+function normalize(source) {
+  switch (source.kind) {
+    case "blob":
+      return fromBlob(source);
+    case "file":
+      return fromFile(source);
+    case "buffer":
+      return fromBuffer(source);
+    case "stream":
+      return fromStream(source);
+    case "data_uri":
+      return fromDataUri(source);
+    case "base64":
+      return fromBase64(source);
+    case "external_url":
+      return fromExternalUrl(source);
+    case "youtube":
+      return fromYouTube(source);
+    case "cloud_file":
+      return fromCloudFile(source.cloudFile, source);
+    case "file_id":
+      return fromFileId(source);
+    case "share_link":
+      return fromShareLink(source);
+    case "public_cdn":
+      return fromPublicCdn(source);
+    case "upload_result":
+      return fromUploadResult(source);
+    case "stream_event":
+      return fromStreamEvent(source);
+  }
+}
+function fromBlob(source) {
+  const url = createTrackedObjectUrl(source.blob);
+  const meta = classify({
+    fileName: source.fileName,
+    mime: source.mime ?? source.blob.type,
+    sizeBytes: source.blob.size
+  });
+  return {
+    url,
+    origin: "ephemeral",
+    capabilities: EPHEMERAL_CAPS,
+    meta,
+    lifecycle: { refreshable: false, persisted: false },
+    scope: {},
+    __source: source
+  };
+}
+function fromFile(source) {
+  const url = createTrackedObjectUrl(source.file);
+  const meta = classify({
+    fileName: source.file.name,
+    mime: source.file.type,
+    sizeBytes: source.file.size
+  });
+  return {
+    url,
+    origin: "ephemeral",
+    capabilities: EPHEMERAL_CAPS,
+    meta,
+    lifecycle: { refreshable: false, persisted: false },
+    scope: {},
+    __source: source
+  };
+}
+function fromBuffer(source) {
+  const blob = bufferToBlob(source.buffer, source.mime);
+  const url = createTrackedObjectUrl(blob);
+  const meta = classify({
+    fileName: source.fileName,
+    mime: source.mime,
+    sizeBytes: blob.size
+  });
+  return {
+    url,
+    origin: "ephemeral",
+    capabilities: EPHEMERAL_CAPS,
+    meta,
+    lifecycle: { refreshable: false, persisted: false },
+    scope: {},
+    __source: source
+  };
+}
+function fromStream(source) {
+  return {
+    origin: "ephemeral",
+    capabilities: EPHEMERAL_CAPS,
+    meta: classify({ fileName: source.fileName, mime: source.mime }),
+    lifecycle: { refreshable: false, persisted: false },
+    scope: {},
+    __source: source
+  };
+}
+function fromDataUri(source) {
+  const match = /^data:([^;,]+)(;base64)?,(.+)$/i.exec(source.dataUri);
+  const mime = match?.[1];
+  const isBase64 = !!match?.[2];
+  const payload = match?.[3] ?? "";
+  return {
+    url: source.dataUri,
+    base64: isBase64 ? payload : void 0,
+    origin: "ephemeral",
+    capabilities: EPHEMERAL_CAPS,
+    meta: classify({ mime }),
+    lifecycle: { refreshable: false, persisted: false },
+    scope: {},
+    __source: source
+  };
+}
+function fromBase64(source) {
+  return {
+    url: `data:${source.mime};base64,${source.base64}`,
+    base64: source.base64,
+    origin: "ephemeral",
+    capabilities: EPHEMERAL_CAPS,
+    meta: classify({ fileName: source.fileName, mime: source.mime }),
+    lifecycle: { refreshable: false, persisted: false },
+    scope: {},
+    __source: source
+  };
+}
+function fromExternalUrl(source) {
+  return {
+    url: source.url,
+    origin: "external",
+    capabilities: EXTERNAL_CAPS,
+    meta: classify({
+      mime: source.mime,
+      fileName: filenameFromUrl(source.url)
+    }),
+    lifecycle: { refreshable: false, persisted: true },
+    scope: {},
+    __source: source
+  };
+}
+function fromYouTube(source) {
+  return {
+    url: source.url,
+    youtubeUrl: source.url,
+    origin: "external",
+    capabilities: EXTERNAL_CAPS,
+    meta: classify({ mime: "video/youtube", fileName: "youtube.video" }),
+    lifecycle: { refreshable: false, persisted: true },
+    scope: {},
+    __source: source
+  };
+}
+function fromCloudFile(cloudFile, source) {
+  const meta = classify({
+    fileName: cloudFile.fileName,
+    mime: cloudFile.mimeType ?? void 0,
+    sizeBytes: cloudFile.fileSize ?? void 0,
+    checksum: cloudFile.checksum ?? void 0
+  });
+  const isPublic = cloudFile.visibility === "public";
+  const bestUrl = isPublic ? cloudFile.cdnUrl ?? cloudFile.url ?? cloudFile.publicUrl ?? pythonFileInlineUrl(cloudFile.id) : cloudFile.url ?? cloudFile.publicUrl ?? pythonFileInlineUrl(cloudFile.id);
+  return {
+    fileId: cloudFile.id,
+    filePath: cloudFile.filePath,
+    url: bestUrl,
+    origin: cloudFile.visibility === "public" ? "public" : "owned",
+    capabilities: {
+      canRead: true,
+      canEdit: true,
+      canShare: true,
+      canDelete: true,
+      requiresAuth: cloudFile.visibility !== "public",
+      // Durable route URLs (and CDN/public URLs) are fetch-safe: the
+      // python-client attaches Authorization headers to our own routes.
+      transportSafeForFetch: true
+    },
+    meta,
+    lifecycle: {
+      refreshable: true,
+      persisted: !cloudFile.deletedAt
+    },
+    scope: {
+      ownerId: cloudFile.ownerId,
+      organizationId: cloudFile.organizationId ?? readOrgScope(cloudFile),
+      projectId: readProjectScope(cloudFile),
+      taskId: readTaskScope(cloudFile)
+    },
+    derivedFrom: cloudFile.parentFileId ? { fileId: cloudFile.parentFileId, kind: cloudFile.derivationKind ?? "" } : void 0,
+    __source: source
+  };
+}
+function fromFileId(source) {
+  return {
+    fileId: source.fileId,
+    // The durable inline URL is a pure function of the id — seed it here so
+    // render paths are synchronous. The resolver still hydrates metadata and
+    // may replace it with a permanent CDN URL for public files.
+    url: pythonFileInlineUrl(source.fileId),
+    origin: "owned",
+    capabilities: {
+      canRead: true,
+      canEdit: false,
+      canShare: false,
+      canDelete: false,
+      requiresAuth: true,
+      transportSafeForFetch: true
+    },
+    meta: classify({ mime: source.mime }),
+    lifecycle: { refreshable: true, persisted: true },
+    scope: {},
+    __source: source
+  };
+}
+function fromShareLink(source) {
+  return {
+    shareToken: source.token,
+    url: pythonShareUrl(source.token),
+    origin: "public",
+    capabilities: PUBLIC_CAPS,
+    meta: classify({ mime: source.mime }),
+    lifecycle: { refreshable: true, persisted: true },
+    scope: {},
+    __source: source
+  };
+}
+function fromPublicCdn(source) {
+  return {
+    fileId: source.fileId,
+    url: source.url,
+    origin: "public",
+    capabilities: { ...PUBLIC_CAPS, transportSafeForFetch: true },
+    meta: classify({
+      mime: source.mime,
+      fileName: filenameFromUrl(source.url)
+    }),
+    lifecycle: { refreshable: !!source.fileId, persisted: true },
+    scope: {},
+    __source: source
+  };
+}
+function fromUploadResult(source) {
+  const r = source.uploadResult;
+  return {
+    fileId: r.fileId,
+    url: r.url,
+    origin: "owned",
+    capabilities: {
+      canRead: true,
+      canEdit: !!r.fileId,
+      canShare: !!r.fileId,
+      canDelete: !!r.fileId,
+      requiresAuth: true,
+      transportSafeForFetch: true
+    },
+    meta: classify({
+      mime: typeof r.metadata?.mimetype === "string" ? r.metadata.mimetype : void 0,
+      fileName: typeof r.metadata?.name === "string" ? r.metadata.name : void 0
+    }),
+    lifecycle: { refreshable: !!r.fileId, persisted: true },
+    scope: {},
+    __source: source
+  };
+}
+function fromStreamEvent(source) {
+  const payload = source.payload;
+  if (!payload || typeof payload !== "object") {
+    return emptyEphemeral(source);
+  }
+  const type = String(payload.type ?? "");
+  let url;
+  let mime;
+  if (type === "image_output" || type === "audio_output" || type === "video_output") {
+    url = payload.url;
+    mime = payload.mime_type;
+  } else if (STREAM_RENDER_TYPES.has(type)) {
+    const data = payload.data;
+    url = data?.src ?? data?.url;
+    const meta = payload.metadata;
+    mime = meta?.mime_type ?? meta?.mime;
+  }
+  const fileId = payload.file_id ?? payload.metadata?.file_id;
+  return {
+    fileId,
+    url,
+    origin: fileId ? "owned" : "external",
+    capabilities: {
+      canRead: true,
+      canEdit: false,
+      canShare: false,
+      canDelete: false,
+      requiresAuth: !!fileId,
+      transportSafeForFetch: !fileId
+    },
+    meta: classify({ mime, fileName: filenameFromUrl(url ?? "") }),
+    lifecycle: { refreshable: !!fileId, persisted: true },
+    scope: {},
+    __source: source
+  };
+}
+function filenameFromUrl(url) {
+  if (!url) return void 0;
+  try {
+    const path = new URL(url, "https://x").pathname;
+    const last = path.split("/").pop();
+    return last && last.length > 0 ? last : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function emptyEphemeral(source) {
+  return {
+    origin: "ephemeral",
+    capabilities: EPHEMERAL_CAPS,
+    meta: classify({}),
+    lifecycle: { refreshable: false, persisted: false },
+    scope: {},
+    __source: source
+  };
+}
+function bufferToBlob(buffer, mime) {
+  if (buffer instanceof Uint8Array) {
+    const copy2 = new Uint8Array(buffer.byteLength);
+    copy2.set(buffer);
+    return new Blob([copy2.buffer], { type: mime });
+  }
+  if (buffer instanceof ArrayBuffer) return new Blob([buffer], { type: mime });
+  const view = new Uint8Array(buffer);
+  const copy = new Uint8Array(view.byteLength);
+  copy.set(view);
+  return new Blob([copy.buffer], { type: mime });
+}
+function readOrgScope(file) {
+  const v = file.metadata?.["scope"];
+  if (v && typeof v === "object" && !Array.isArray(v)) {
+    const orgId = v.organization_id;
+    if (typeof orgId === "string") return orgId;
+  }
+  return void 0;
+}
+function readProjectScope(file) {
+  const v = file.metadata?.["scope"];
+  if (v && typeof v === "object" && !Array.isArray(v)) {
+    const projectId = v.project_id;
+    if (typeof projectId === "string") return projectId;
+  }
+  return void 0;
+}
+function readTaskScope(file) {
+  const v = file.metadata?.["scope"];
+  if (v && typeof v === "object" && !Array.isArray(v)) {
+    const taskId = v.task_id;
+    if (typeof taskId === "string") return taskId;
+  }
+  return void 0;
+}
+export {
+  fromCloudFile,
+  normalize
+};
+//# sourceMappingURL=normalize.js.map

package/dist/files/engine/handler/input/normalize.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../src/files/engine/handler/input/normalize.ts"],"sourcesContent":["/**\n * features/files/handler/input/normalize.ts\n *\n * Pure first-pass: turn a `FileSource` into a partial `NormalizedFile`.\n * \"Pure\" means no I/O, no Redux. Anything that needs the network or auth\n * runs in the resolver, not here.\n *\n * Each `FileSource` kind gets its own arm. Adding a new shape is a single\n * edit in this file plus a `FileSource` variant in `../types.ts`.\n */\n\nimport type { CloudFile } from \"../../types\";\nimport { classify } from \"../utils/classify\";\nimport { pythonFileInlineUrl, pythonShareUrl } from \"../utils/python-base\";\nimport { createTrackedObjectUrl } from \"../../../../files\";\nimport {\n  EPHEMERAL_CAPS,\n  EXTERNAL_CAPS,\n  PUBLIC_CAPS,\n} from \"../intelligence/access\";\nimport type { FileSource, NormalizedFile } from \"../types\";\n\nconst STREAM_RENDER_TYPES = new Set([\"image\", \"audio\", \"video\", \"document\"]);\n\nexport function normalize(source: FileSource): NormalizedFile {\n  switch (source.kind) {\n    case \"blob\":\n      return fromBlob(source);\n    case \"file\":\n      return fromFile(source);\n    case \"buffer\":\n      return fromBuffer(source);\n    case \"stream\":\n      return fromStream(source);\n    case \"data_uri\":\n      return fromDataUri(source);\n    case \"base64\":\n      return fromBase64(source);\n    case \"external_url\":\n      return fromExternalUrl(source);\n    case \"youtube\":\n      return fromYouTube(source);\n    case \"cloud_file\":\n      return fromCloudFile(source.cloudFile, source);\n    case \"file_id\":\n      return fromFileId(source);\n    case \"share_link\":\n      return fromShareLink(source);\n    case \"public_cdn\":\n      return fromPublicCdn(source);\n    case \"upload_result\":\n      return fromUploadResult(source);\n    case \"stream_event\":\n      return fromStreamEvent(source);\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Ephemeral / raw bytes\n// ---------------------------------------------------------------------------\n\nfunction fromBlob(\n  source: Extract<FileSource, { kind: \"blob\" }>,\n): NormalizedFile {\n  const url = createTrackedObjectUrl(source.blob);\n  const meta = classify({\n    fileName: source.fileName,\n    mime: source.mime ?? source.blob.type,\n    sizeBytes: source.blob.size,\n  });\n  return {\n    url,\n    origin: \"ephemeral\",\n    capabilities: EPHEMERAL_CAPS,\n    meta,\n    lifecycle: { refreshable: false, persisted: false },\n    scope: {},\n    __source: source,\n  };\n}\n\nfunction fromFile(\n  source: Extract<FileSource, { kind: \"file\" }>,\n): NormalizedFile {\n  const url = createTrackedObjectUrl(source.file);\n  const meta = classify({\n    fileName: source.file.name,\n    mime: source.file.type,\n    sizeBytes: source.file.size,\n  });\n  return {\n    url,\n    origin: \"ephemeral\",\n    capabilities: EPHEMERAL_CAPS,\n    meta,\n    lifecycle: { refreshable: false, persisted: false },\n    scope: {},\n    __source: source,\n  };\n}\n\nfunction fromBuffer(\n  source: Extract<FileSource, { kind: \"buffer\" }>,\n): NormalizedFile {\n  const blob = bufferToBlob(source.buffer, source.mime);\n  const url = createTrackedObjectUrl(blob);\n  const meta = classify({\n    fileName: source.fileName,\n    mime: source.mime,\n    sizeBytes: blob.size,\n  });\n  return {\n    url,\n    origin: \"ephemeral\",\n    capabilities: EPHEMERAL_CAPS,\n    meta,\n    lifecycle: { refreshable: false, persisted: false },\n    scope: {},\n    __source: source,\n  };\n}\n\nfunction fromStream(\n  source: Extract<FileSource, { kind: \"stream\" }>,\n): NormalizedFile {\n  // Stream sources can't produce a synchronous URL — output adapters that\n  // need bytes will tee the stream in `to-blob.ts`. The normalized form\n  // carries no URL at this stage; consumers that need one will be fed a\n  // blob URL after the stream is consumed.\n  return {\n    origin: \"ephemeral\",\n    capabilities: EPHEMERAL_CAPS,\n    meta: classify({ fileName: source.fileName, mime: source.mime }),\n    lifecycle: { refreshable: false, persisted: false },\n    scope: {},\n    __source: source,\n  };\n}\n\nfunction fromDataUri(\n  source: Extract<FileSource, { kind: \"data_uri\" }>,\n): NormalizedFile {\n  const match = /^data:([^;,]+)(;base64)?,(.+)$/i.exec(source.dataUri);\n  const mime = match?.[1];\n  const isBase64 = !!match?.[2];\n  const payload = match?.[3] ?? \"\";\n  return {\n    url: source.dataUri,\n    base64: isBase64 ? payload : undefined,\n    origin: \"ephemeral\",\n    capabilities: EPHEMERAL_CAPS,\n    meta: classify({ mime }),\n    lifecycle: { refreshable: false, persisted: false },\n    scope: {},\n    __source: source,\n  };\n}\n\nfunction fromBase64(\n  source: Extract<FileSource, { kind: \"base64\" }>,\n): NormalizedFile {\n  return {\n    url: `data:${source.mime};base64,${source.base64}`,\n    base64: source.base64,\n    origin: \"ephemeral\",\n    capabilities: EPHEMERAL_CAPS,\n    meta: classify({ fileName: source.fileName, mime: source.mime }),\n    lifecycle: { refreshable: false, persisted: false },\n    scope: {},\n    __source: source,\n  };\n}\n\n// ---------------------------------------------------------------------------\n// External\n// ---------------------------------------------------------------------------\n\nfunction fromExternalUrl(\n  source: Extract<FileSource, { kind: \"external_url\" }>,\n): NormalizedFile {\n  return {\n    url: source.url,\n    origin: \"external\",\n    capabilities: EXTERNAL_CAPS,\n    meta: classify({\n      mime: source.mime,\n      fileName: filenameFromUrl(source.url),\n    }),\n    lifecycle: { refreshable: false, persisted: true },\n    scope: {},\n    __source: source,\n  };\n}\n\nfunction fromYouTube(\n  source: Extract<FileSource, { kind: \"youtube\" }>,\n): NormalizedFile {\n  return {\n    url: source.url,\n    youtubeUrl: source.url,\n    origin: \"external\",\n    capabilities: EXTERNAL_CAPS,\n    meta: classify({ mime: \"video/youtube\", fileName: \"youtube.video\" }),\n    lifecycle: { refreshable: false, persisted: true },\n    scope: {},\n    __source: source,\n  };\n}\n\n// ---------------------------------------------------------------------------\n// Owned / identifier-bearing\n// ---------------------------------------------------------------------------\n\nexport function fromCloudFile(\n  cloudFile: CloudFile,\n  source: FileSource,\n): NormalizedFile {\n  const meta = classify({\n    fileName: cloudFile.fileName,\n    mime: cloudFile.mimeType ?? undefined,\n    sizeBytes: cloudFile.fileSize ?? undefined,\n    checksum: cloudFile.checksum ?? undefined,\n  });\n  // Every URL flavour is DURABLE now. Public files prefer the permanent\n  // CDN URL (cdn_url → canonical url → legacy public_url). Private/shared\n  // files bind the server's canonical `url` (the durable\n  // `/files/{id}/download?inline=1` route) when the envelope carries it,\n  // else build the identical durable URL from the file id — synchronously,\n  // no minting round-trip.\n  const isPublic = cloudFile.visibility === \"public\";\n  const bestUrl = isPublic\n    ? (cloudFile.cdnUrl ??\n      cloudFile.url ??\n      cloudFile.publicUrl ??\n      pythonFileInlineUrl(cloudFile.id))\n    : (cloudFile.url ??\n      cloudFile.publicUrl ??\n      pythonFileInlineUrl(cloudFile.id));\n  return {\n    fileId: cloudFile.id,\n    filePath: cloudFile.filePath,\n    url: bestUrl,\n    origin: cloudFile.visibility === \"public\" ? \"public\" : \"owned\",\n    capabilities: {\n      canRead: true,\n      canEdit: true,\n      canShare: true,\n      canDelete: true,\n      requiresAuth: cloudFile.visibility !== \"public\",\n      // Durable route URLs (and CDN/public URLs) are fetch-safe: the\n      // python-client attaches Authorization headers to our own routes.\n      transportSafeForFetch: true,\n    },\n    meta,\n    lifecycle: {\n      refreshable: true,\n      persisted: !cloudFile.deletedAt,\n    },\n    scope: {\n      ownerId: cloudFile.ownerId,\n      organizationId: cloudFile.organizationId ?? readOrgScope(cloudFile),\n      projectId: readProjectScope(cloudFile),\n      taskId: readTaskScope(cloudFile),\n    },\n    derivedFrom: cloudFile.parentFileId\n      ? { fileId: cloudFile.parentFileId, kind: cloudFile.derivationKind ?? \"\" }\n      : undefined,\n    __source: source,\n  };\n}\n\nfunction fromFileId(\n  source: Extract<FileSource, { kind: \"file_id\" }>,\n): NormalizedFile {\n  return {\n    fileId: source.fileId,\n    // The durable inline URL is a pure function of the id — seed it here so\n    // render paths are synchronous. The resolver still hydrates metadata and\n    // may replace it with a permanent CDN URL for public files.\n    url: pythonFileInlineUrl(source.fileId),\n    origin: \"owned\",\n    capabilities: {\n      canRead: true,\n      canEdit: false,\n      canShare: false,\n      canDelete: false,\n      requiresAuth: true,\n      transportSafeForFetch: true,\n    },\n    meta: classify({ mime: source.mime }),\n    lifecycle: { refreshable: true, persisted: true },\n    scope: {},\n    __source: source,\n  };\n}\n\n// ---------------------------------------------------------------------------\n// Server-issued URLs\n// ---------------------------------------------------------------------------\n\nfunction fromShareLink(\n  source: Extract<FileSource, { kind: \"share_link\" }>,\n): NormalizedFile {\n  return {\n    shareToken: source.token,\n    url: pythonShareUrl(source.token),\n    origin: \"public\",\n    capabilities: PUBLIC_CAPS,\n    meta: classify({ mime: source.mime }),\n    lifecycle: { refreshable: true, persisted: true },\n    scope: {},\n    __source: source,\n  };\n}\n\nfunction fromPublicCdn(\n  source: Extract<FileSource, { kind: \"public_cdn\" }>,\n): NormalizedFile {\n  return {\n    fileId: source.fileId,\n    url: source.url,\n    origin: \"public\",\n    capabilities: { ...PUBLIC_CAPS, transportSafeForFetch: true },\n    meta: classify({\n      mime: source.mime,\n      fileName: filenameFromUrl(source.url),\n    }),\n    lifecycle: { refreshable: !!source.fileId, persisted: true },\n    scope: {},\n    __source: source,\n  };\n}\n\nfunction fromUploadResult(\n  source: Extract<FileSource, { kind: \"upload_result\" }>,\n): NormalizedFile {\n  const r = source.uploadResult;\n  return {\n    fileId: r.fileId,\n    url: r.url,\n    origin: \"owned\",\n    capabilities: {\n      canRead: true,\n      canEdit: !!r.fileId,\n      canShare: !!r.fileId,\n      canDelete: !!r.fileId,\n      requiresAuth: true,\n      transportSafeForFetch: true,\n    },\n    meta: classify({\n      mime:\n        typeof r.metadata?.mimetype === \"string\"\n          ? (r.metadata.mimetype as string)\n          : undefined,\n      fileName:\n        typeof r.metadata?.name === \"string\"\n          ? (r.metadata.name as string)\n          : undefined,\n    }),\n    lifecycle: { refreshable: !!r.fileId, persisted: true },\n    scope: {},\n    __source: source,\n  };\n}\n\n// ---------------------------------------------------------------------------\n// Stream events — server-emitted file references arriving mid-stream\n// ---------------------------------------------------------------------------\n\nfunction fromStreamEvent(\n  source: Extract<FileSource, { kind: \"stream_event\" }>,\n): NormalizedFile {\n  const payload = source.payload as Record<string, unknown> | null;\n  if (!payload || typeof payload !== \"object\") {\n    return emptyEphemeral(source);\n  }\n\n  // Two shapes the stream produces:\n  //   1. RenderBlock — { type, data: { src }, ... } for type in image/audio/video/document\n  //   2. TypedDataPayload — { type: \"image_output\"|\"audio_output\"|\"video_output\", url, mime_type }\n  // Both reduce to: a URL + a MIME, with optional fileId.\n  const type = String(payload.type ?? \"\");\n  let url: string | undefined;\n  let mime: string | undefined;\n\n  if (\n    type === \"image_output\" ||\n    type === \"audio_output\" ||\n    type === \"video_output\"\n  ) {\n    url = payload.url as string | undefined;\n    mime = payload.mime_type as string | undefined;\n  } else if (STREAM_RENDER_TYPES.has(type)) {\n    const data = payload.data as Record<string, unknown> | undefined;\n    url = (data?.src ?? data?.url) as string | undefined;\n    const meta = payload.metadata as Record<string, unknown> | undefined;\n    mime = (meta?.mime_type ?? meta?.mime) as string | undefined;\n  }\n\n  const fileId =\n    (payload.file_id as string | undefined) ??\n    ((payload.metadata as Record<string, unknown> | undefined)?.file_id as\n      string | undefined);\n\n  return {\n    fileId,\n    url,\n    origin: fileId ? \"owned\" : \"external\",\n    capabilities: {\n      canRead: true,\n      canEdit: false,\n      canShare: false,\n      canDelete: false,\n      requiresAuth: !!fileId,\n      transportSafeForFetch: !fileId,\n    },\n    meta: classify({ mime, fileName: filenameFromUrl(url ?? \"\") }),\n    lifecycle: { refreshable: !!fileId, persisted: true },\n    scope: {},\n    __source: source,\n  };\n}\n\n// ---------------------------------------------------------------------------\n// Helpers\n// ---------------------------------------------------------------------------\n\nfunction filenameFromUrl(url: string): string | undefined {\n  if (!url) return undefined;\n  try {\n    const path = new URL(url, \"https://x\").pathname;\n    const last = path.split(\"/\").pop();\n    return last && last.length > 0 ? last : undefined;\n  } catch {\n    return undefined;\n  }\n}\n\nfunction emptyEphemeral(source: FileSource): NormalizedFile {\n  return {\n    origin: \"ephemeral\",\n    capabilities: EPHEMERAL_CAPS,\n    meta: classify({}),\n    lifecycle: { refreshable: false, persisted: false },\n    scope: {},\n    __source: source,\n  };\n}\n\nfunction bufferToBlob(\n  buffer: ArrayBuffer | Uint8Array | SharedArrayBuffer,\n  mime: string,\n): Blob {\n  if (buffer instanceof Uint8Array) {\n    const copy = new Uint8Array(buffer.byteLength);\n    copy.set(buffer);\n    return new Blob([copy.buffer], { type: mime });\n  }\n  if (buffer instanceof ArrayBuffer) return new Blob([buffer], { type: mime });\n  const view = new Uint8Array(buffer);\n  const copy = new Uint8Array(view.byteLength);\n  copy.set(view);\n  return new Blob([copy.buffer], { type: mime });\n}\n\nfunction readOrgScope(file: CloudFile): string | undefined {\n  const v = file.metadata?.[\"scope\"];\n  if (v && typeof v === \"object\" && !Array.isArray(v)) {\n    const orgId = (v as Record<string, unknown>).organization_id;\n    if (typeof orgId === \"string\") return orgId;\n  }\n  return undefined;\n}\n\nfunction readProjectScope(file: CloudFile): string | undefined {\n  const v = file.metadata?.[\"scope\"];\n  if (v && typeof v === \"object\" && !Array.isArray(v)) {\n    const projectId = (v as Record<string, unknown>).project_id;\n    if (typeof projectId === \"string\") return projectId;\n  }\n  return undefined;\n}\n\nfunction readTaskScope(file: CloudFile): string | undefined {\n  const v = file.metadata?.[\"scope\"];\n  if (v && typeof v === \"object\" && !Array.isArray(v)) {\n    const taskId = (v as Record<string, unknown>).task_id;\n    if (typeof taskId === \"string\") return taskId;\n  }\n  return undefined;\n}\n"],"mappings":"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","names":["copy"]}

package/dist/files/engine/handler/intelligence/access.d.ts

@@ -0,0 +1,35 @@
+/**
+ * features/files/handler/intelligence/access.ts
+ *
+ * The "can this user access this file?" decision. The handler consults
+ * this BEFORE deciding whether a backend failure is "expired URL, refresh"
+ * or "no access, reject".
+ *
+ * Order of checks:
+ *   1. owner_id === current user → owned (full caps)
+ *   2. visibility === "public" OR public CDN URL → public (read-only)
+ *   3. canonical `public.permissions` grant matches user → shared
+ *      (level-derived caps). Grants are loaded into Redux via `loadPermissions`
+ *      and passed in here; the authoritative server-side check is
+ *      `iam.has_access('file', fileId, level)` / `public.has_permission(...)`.
+ *   4. file.organizationId is in user's active orgs → check org-level grant
+ *   5. share_token is non-revoked → public (read-only by token)
+ *   6. external URL → external (read-only, no caps over the file itself)
+ *   7. None of the above → unauthorized
+ */
+import { type RootState } from "../../host/store.js";
+import type { CloudFile, CloudFilePermission } from "../../types.js";
+import type { FileCapabilities, FileOrigin } from "../types.js";
+export interface AccessDecision {
+    origin: FileOrigin;
+    capabilities: FileCapabilities;
+}
+/**
+ * Decide origin + capabilities for an OWNED-OR-SHARED cld_files row, given
+ * the current user from Redux. Public files and external URLs are decided
+ * by the input adapter — not here — because they don't need the user.
+ */
+export declare function decideForOwnedFile(file: CloudFile, state: RootState, permissions?: CloudFilePermission[]): AccessDecision;
+export declare const PUBLIC_CAPS: FileCapabilities;
+export declare const EXTERNAL_CAPS: FileCapabilities;
+export declare const EPHEMERAL_CAPS: FileCapabilities;

package/dist/files/engine/handler/intelligence/access.js

@@ -0,0 +1,85 @@
+import { selectUserId } from "../../host/store.js";
+const READ_ONLY = {
+  canRead: true,
+  canEdit: false,
+  canShare: false,
+  canDelete: false,
+  requiresAuth: false,
+  transportSafeForFetch: true
+};
+const NO_ACCESS = {
+  canRead: false,
+  canEdit: false,
+  canShare: false,
+  canDelete: false,
+  requiresAuth: true,
+  transportSafeForFetch: true
+};
+function fromLevel(level) {
+  return {
+    canRead: true,
+    canEdit: level === "write" || level === "admin",
+    canShare: level === "admin",
+    canDelete: level === "admin",
+    requiresAuth: true,
+    transportSafeForFetch: true
+  };
+}
+function decideForOwnedFile(file, state, permissions) {
+  const userId = selectUserId(state);
+  if (userId && file.ownerId === userId) {
+    return {
+      origin: "owned",
+      capabilities: {
+        canRead: true,
+        canEdit: true,
+        canShare: true,
+        canDelete: true,
+        requiresAuth: true,
+        transportSafeForFetch: true
+      }
+    };
+  }
+  if (file.visibility === "public") {
+    return { origin: "public", capabilities: READ_ONLY };
+  }
+  if (userId && permissions?.length) {
+    const grant = permissions.find(
+      (p) => p.granteeType === "user" && p.granteeId === userId
+    );
+    if (grant) {
+      const expired = grant.expiresAt && Date.parse(grant.expiresAt) < Date.now();
+      if (!expired) {
+        return {
+          origin: "shared",
+          capabilities: fromLevel(grant.permissionLevel)
+        };
+      }
+    }
+  }
+  return { origin: "owned", capabilities: NO_ACCESS };
+}
+const PUBLIC_CAPS = READ_ONLY;
+const EXTERNAL_CAPS = {
+  canRead: true,
+  canEdit: false,
+  canShare: false,
+  canDelete: false,
+  requiresAuth: false,
+  transportSafeForFetch: false
+};
+const EPHEMERAL_CAPS = {
+  canRead: true,
+  canEdit: true,
+  canShare: false,
+  canDelete: true,
+  requiresAuth: false,
+  transportSafeForFetch: true
+};
+export {
+  EPHEMERAL_CAPS,
+  EXTERNAL_CAPS,
+  PUBLIC_CAPS,
+  decideForOwnedFile
+};
+//# sourceMappingURL=access.js.map

package/dist/files/engine/handler/intelligence/access.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../src/files/engine/handler/intelligence/access.ts"],"sourcesContent":["/**\n * features/files/handler/intelligence/access.ts\n *\n * The \"can this user access this file?\" decision. The handler consults\n * this BEFORE deciding whether a backend failure is \"expired URL, refresh\"\n * or \"no access, reject\".\n *\n * Order of checks:\n *   1. owner_id === current user → owned (full caps)\n *   2. visibility === \"public\" OR public CDN URL → public (read-only)\n *   3. canonical `public.permissions` grant matches user → shared\n *      (level-derived caps). Grants are loaded into Redux via `loadPermissions`\n *      and passed in here; the authoritative server-side check is\n *      `iam.has_access('file', fileId, level)` / `public.has_permission(...)`.\n *   4. file.organizationId is in user's active orgs → check org-level grant\n *   5. share_token is non-revoked → public (read-only by token)\n *   6. external URL → external (read-only, no caps over the file itself)\n *   7. None of the above → unauthorized\n */\n\nimport { selectUserId, type RootState } from \"../../host/store\";\nimport type { CloudFile, CloudFilePermission } from \"../../types\";\nimport type { FileCapabilities, FileOrigin } from \"../types\";\n\nexport interface AccessDecision {\n  origin: FileOrigin;\n  capabilities: FileCapabilities;\n}\n\nconst READ_ONLY: FileCapabilities = {\n  canRead: true,\n  canEdit: false,\n  canShare: false,\n  canDelete: false,\n  requiresAuth: false,\n  transportSafeForFetch: true,\n};\n\nconst NO_ACCESS: FileCapabilities = {\n  canRead: false,\n  canEdit: false,\n  canShare: false,\n  canDelete: false,\n  requiresAuth: true,\n  transportSafeForFetch: true,\n};\n\nfunction fromLevel(level: \"read\" | \"write\" | \"admin\"): FileCapabilities {\n  return {\n    canRead: true,\n    canEdit: level === \"write\" || level === \"admin\",\n    canShare: level === \"admin\",\n    canDelete: level === \"admin\",\n    requiresAuth: true,\n    transportSafeForFetch: true,\n  };\n}\n\n/**\n * Decide origin + capabilities for an OWNED-OR-SHARED cld_files row, given\n * the current user from Redux. Public files and external URLs are decided\n * by the input adapter — not here — because they don't need the user.\n */\nexport function decideForOwnedFile(\n  file: CloudFile,\n  state: RootState,\n  permissions?: CloudFilePermission[],\n): AccessDecision {\n  const userId = selectUserId(state);\n\n  if (userId && file.ownerId === userId) {\n    return {\n      origin: \"owned\",\n      capabilities: {\n        canRead: true,\n        canEdit: true,\n        canShare: true,\n        canDelete: true,\n        requiresAuth: true,\n        transportSafeForFetch: true,\n      },\n    };\n  }\n\n  if (file.visibility === \"public\") {\n    return { origin: \"public\", capabilities: READ_ONLY };\n  }\n\n  if (userId && permissions?.length) {\n    const grant = permissions.find(\n      (p) => p.granteeType === \"user\" && p.granteeId === userId,\n    );\n    if (grant) {\n      const expired =\n        grant.expiresAt && Date.parse(grant.expiresAt) < Date.now();\n      if (!expired) {\n        return {\n          origin: \"shared\",\n          capabilities: fromLevel(grant.permissionLevel),\n        };\n      }\n    }\n  }\n\n  return { origin: \"owned\", capabilities: NO_ACCESS };\n}\n\nexport const PUBLIC_CAPS = READ_ONLY;\nexport const EXTERNAL_CAPS: FileCapabilities = {\n  canRead: true,\n  canEdit: false,\n  canShare: false,\n  canDelete: false,\n  requiresAuth: false,\n  transportSafeForFetch: false,\n};\nexport const EPHEMERAL_CAPS: FileCapabilities = {\n  canRead: true,\n  canEdit: true,\n  canShare: false,\n  canDelete: true,\n  requiresAuth: false,\n  transportSafeForFetch: true,\n};\n"],"mappings":"AAoBA,SAAS,oBAAoC;AAS7C,MAAM,YAA8B;AAAA,EAClC,SAAS;AAAA,EACT,SAAS;AAAA,EACT,UAAU;AAAA,EACV,WAAW;AAAA,EACX,cAAc;AAAA,EACd,uBAAuB;AACzB;AAEA,MAAM,YAA8B;AAAA,EAClC,SAAS;AAAA,EACT,SAAS;AAAA,EACT,UAAU;AAAA,EACV,WAAW;AAAA,EACX,cAAc;AAAA,EACd,uBAAuB;AACzB;AAEA,SAAS,UAAU,OAAqD;AACtE,SAAO;AAAA,IACL,SAAS;AAAA,IACT,SAAS,UAAU,WAAW,UAAU;AAAA,IACxC,UAAU,UAAU;AAAA,IACpB,WAAW,UAAU;AAAA,IACrB,cAAc;AAAA,IACd,uBAAuB;AAAA,EACzB;AACF;AAOO,SAAS,mBACd,MACA,OACA,aACgB;AAChB,QAAM,SAAS,aAAa,KAAK;AAEjC,MAAI,UAAU,KAAK,YAAY,QAAQ;AACrC,WAAO;AAAA,MACL,QAAQ;AAAA,MACR,cAAc;AAAA,QACZ,SAAS;AAAA,QACT,SAAS;AAAA,QACT,UAAU;AAAA,QACV,WAAW;AAAA,QACX,cAAc;AAAA,QACd,uBAAuB;AAAA,MACzB;AAAA,IACF;AAAA,EACF;AAEA,MAAI,KAAK,eAAe,UAAU;AAChC,WAAO,EAAE,QAAQ,UAAU,cAAc,UAAU;AAAA,EACrD;AAEA,MAAI,UAAU,aAAa,QAAQ;AACjC,UAAM,QAAQ,YAAY;AAAA,MACxB,CAAC,MAAM,EAAE,gBAAgB,UAAU,EAAE,cAAc;AAAA,IACrD;AACA,QAAI,OAAO;AACT,YAAM,UACJ,MAAM,aAAa,KAAK,MAAM,MAAM,SAAS,IAAI,KAAK,IAAI;AAC5D,UAAI,CAAC,SAAS;AACZ,eAAO;AAAA,UACL,QAAQ;AAAA,UACR,cAAc,UAAU,MAAM,eAAe;AAAA,QAC/C;AAAA,MACF;AAAA,IACF;AAAA,EACF;AAEA,SAAO,EAAE,QAAQ,SAAS,cAAc,UAAU;AACpD;AAEO,MAAM,cAAc;AACpB,MAAM,gBAAkC;AAAA,EAC7C,SAAS;AAAA,EACT,SAAS;AAAA,EACT,UAAU;AAAA,EACV,WAAW;AAAA,EACX,cAAc;AAAA,EACd,uBAAuB;AACzB;AACO,MAAM,iBAAmC;AAAA,EAC9C,SAAS;AAAA,EACT,SAAS;AAAA,EACT,UAAU;AAAA,EACV,WAAW;AAAA,EACX,cAAc;AAAA,EACd,uBAAuB;AACzB;","names":[]}

package/dist/files/engine/handler/intelligence/magic-bytes.d.ts

@@ -0,0 +1,21 @@
+/**
+ * features/files/handler/intelligence/magic-bytes.ts
+ *
+ * MIME sniffing from the first ~16 bytes of a file. Used when a source
+ * arrives with no Content-Type and no extension (rare but happens with
+ * paste-from-clipboard, raw buffers, and stream events).
+ *
+ * The big eight image formats plus PDF cover ~99% of real input. Anything
+ * else falls through to `application/octet-stream` and the resolver
+ * defers to the file extension or the FILE_TYPES registry.
+ */
+/**
+ * Sniff a MIME from the leading bytes. Returns `null` if no rule matches —
+ * the caller decides whether to fall back to extension or octet-stream.
+ */
+export declare function sniffMime(bytes: Uint8Array): string | null;
+/**
+ * Read the first N bytes of a Blob/File without loading the whole thing.
+ * Sniff window is 32 bytes — enough for every rule above.
+ */
+export declare function sniffMimeFromBlob(blob: Blob): Promise<string | null>;

package/dist/files/engine/handler/intelligence/magic-bytes.js

@@ -0,0 +1,67 @@
+const MAGIC_TABLE = [
+  { mime: "image/png", prefix: [137, 80, 78, 71] },
+  { mime: "image/jpeg", prefix: [255, 216, 255] },
+  { mime: "image/gif", prefix: [71, 73, 70, 56] },
+  { mime: "image/webp", prefix: [82, 73, 70, 70], match: isWebp },
+  { mime: "image/bmp", prefix: [66, 77] },
+  { mime: "image/x-icon", prefix: [0, 0, 1, 0] },
+  { mime: "image/avif", prefix: [], match: isAvif },
+  { mime: "image/heic", prefix: [], match: isHeic },
+  { mime: "application/pdf", prefix: [37, 80, 68, 70] },
+  { mime: "application/zip", prefix: [80, 75, 3, 4] },
+  { mime: "video/mp4", prefix: [], match: isMp4 },
+  { mime: "video/webm", prefix: [26, 69, 223, 163] },
+  { mime: "audio/mpeg", prefix: [255, 251] },
+  { mime: "audio/mpeg", prefix: [73, 68, 51] },
+  { mime: "audio/wav", prefix: [82, 73, 70, 70], match: isWav },
+  { mime: "audio/ogg", prefix: [79, 103, 103, 83] },
+  { mime: "audio/flac", prefix: [102, 76, 97, 67] }
+];
+function startsWith(bytes, prefix, offset = 0) {
+  if (bytes.length < offset + prefix.length) return false;
+  for (let i = 0; i < prefix.length; i++) {
+    if (bytes[offset + i] !== prefix[i]) return false;
+  }
+  return true;
+}
+function isWebp(bytes) {
+  return bytes.length >= 12 && startsWith(bytes, [82, 73, 70, 70]) && startsWith(bytes, [87, 69, 66, 80], 8);
+}
+function isWav(bytes) {
+  return bytes.length >= 12 && startsWith(bytes, [82, 73, 70, 70]) && startsWith(bytes, [87, 65, 86, 69], 8);
+}
+function isMp4(bytes) {
+  return bytes.length >= 12 && startsWith(bytes, [102, 116, 121, 112], 4);
+}
+function isAvif(bytes) {
+  if (bytes.length < 12) return false;
+  if (!startsWith(bytes, [102, 116, 121, 112], 4)) return false;
+  const brand = String.fromCharCode(bytes[8], bytes[9], bytes[10], bytes[11]);
+  return brand === "avif" || brand === "avis";
+}
+function isHeic(bytes) {
+  if (bytes.length < 12) return false;
+  if (!startsWith(bytes, [102, 116, 121, 112], 4)) return false;
+  const brand = String.fromCharCode(bytes[8], bytes[9], bytes[10], bytes[11]);
+  return brand === "heic" || brand === "heix" || brand === "heim" || brand === "heis";
+}
+function sniffMime(bytes) {
+  for (const rule of MAGIC_TABLE) {
+    if (rule.match) {
+      if (rule.match(bytes)) return rule.mime;
+      continue;
+    }
+    if (startsWith(bytes, rule.prefix, rule.offset)) return rule.mime;
+  }
+  return null;
+}
+async function sniffMimeFromBlob(blob) {
+  const slice = blob.slice(0, 32);
+  const buffer = await slice.arrayBuffer();
+  return sniffMime(new Uint8Array(buffer));
+}
+export {
+  sniffMime,
+  sniffMimeFromBlob
+};
+//# sourceMappingURL=magic-bytes.js.map

package/dist/files/engine/handler/intelligence/magic-bytes.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../src/files/engine/handler/intelligence/magic-bytes.ts"],"sourcesContent":["/**\n * features/files/handler/intelligence/magic-bytes.ts\n *\n * MIME sniffing from the first ~16 bytes of a file. Used when a source\n * arrives with no Content-Type and no extension (rare but happens with\n * paste-from-clipboard, raw buffers, and stream events).\n *\n * The big eight image formats plus PDF cover ~99% of real input. Anything\n * else falls through to `application/octet-stream` and the resolver\n * defers to the file extension or the FILE_TYPES registry.\n */\n\nconst MAGIC_TABLE: Array<{\n  mime: string;\n  prefix: number[];\n  offset?: number;\n  match?: (bytes: Uint8Array) => boolean;\n}> = [\n  { mime: \"image/png\", prefix: [0x89, 0x50, 0x4e, 0x47] },\n  { mime: \"image/jpeg\", prefix: [0xff, 0xd8, 0xff] },\n  { mime: \"image/gif\", prefix: [0x47, 0x49, 0x46, 0x38] },\n  { mime: \"image/webp\", prefix: [0x52, 0x49, 0x46, 0x46], match: isWebp },\n  { mime: \"image/bmp\", prefix: [0x42, 0x4d] },\n  { mime: \"image/x-icon\", prefix: [0x00, 0x00, 0x01, 0x00] },\n  { mime: \"image/avif\", prefix: [], match: isAvif },\n  { mime: \"image/heic\", prefix: [], match: isHeic },\n  { mime: \"application/pdf\", prefix: [0x25, 0x50, 0x44, 0x46] },\n  { mime: \"application/zip\", prefix: [0x50, 0x4b, 0x03, 0x04] },\n  { mime: \"video/mp4\", prefix: [], match: isMp4 },\n  { mime: \"video/webm\", prefix: [0x1a, 0x45, 0xdf, 0xa3] },\n  { mime: \"audio/mpeg\", prefix: [0xff, 0xfb] },\n  { mime: \"audio/mpeg\", prefix: [0x49, 0x44, 0x33] },\n  { mime: \"audio/wav\", prefix: [0x52, 0x49, 0x46, 0x46], match: isWav },\n  { mime: \"audio/ogg\", prefix: [0x4f, 0x67, 0x67, 0x53] },\n  { mime: \"audio/flac\", prefix: [0x66, 0x4c, 0x61, 0x43] },\n];\n\nfunction startsWith(bytes: Uint8Array, prefix: number[], offset = 0): boolean {\n  if (bytes.length < offset + prefix.length) return false;\n  for (let i = 0; i < prefix.length; i++) {\n    if (bytes[offset + i] !== prefix[i]) return false;\n  }\n  return true;\n}\n\nfunction isWebp(bytes: Uint8Array): boolean {\n  return (\n    bytes.length >= 12 &&\n    startsWith(bytes, [0x52, 0x49, 0x46, 0x46]) &&\n    startsWith(bytes, [0x57, 0x45, 0x42, 0x50], 8)\n  );\n}\n\nfunction isWav(bytes: Uint8Array): boolean {\n  return (\n    bytes.length >= 12 &&\n    startsWith(bytes, [0x52, 0x49, 0x46, 0x46]) &&\n    startsWith(bytes, [0x57, 0x41, 0x56, 0x45], 8)\n  );\n}\n\nfunction isMp4(bytes: Uint8Array): boolean {\n  return bytes.length >= 12 && startsWith(bytes, [0x66, 0x74, 0x79, 0x70], 4);\n}\n\nfunction isAvif(bytes: Uint8Array): boolean {\n  if (bytes.length < 12) return false;\n  if (!startsWith(bytes, [0x66, 0x74, 0x79, 0x70], 4)) return false;\n  const brand = String.fromCharCode(bytes[8], bytes[9], bytes[10], bytes[11]);\n  return brand === \"avif\" || brand === \"avis\";\n}\n\nfunction isHeic(bytes: Uint8Array): boolean {\n  if (bytes.length < 12) return false;\n  if (!startsWith(bytes, [0x66, 0x74, 0x79, 0x70], 4)) return false;\n  const brand = String.fromCharCode(bytes[8], bytes[9], bytes[10], bytes[11]);\n  return brand === \"heic\" || brand === \"heix\" || brand === \"heim\" || brand === \"heis\";\n}\n\n/**\n * Sniff a MIME from the leading bytes. Returns `null` if no rule matches —\n * the caller decides whether to fall back to extension or octet-stream.\n */\nexport function sniffMime(bytes: Uint8Array): string | null {\n  for (const rule of MAGIC_TABLE) {\n    if (rule.match) {\n      if (rule.match(bytes)) return rule.mime;\n      continue;\n    }\n    if (startsWith(bytes, rule.prefix, rule.offset)) return rule.mime;\n  }\n  return null;\n}\n\n/**\n * Read the first N bytes of a Blob/File without loading the whole thing.\n * Sniff window is 32 bytes — enough for every rule above.\n */\nexport async function sniffMimeFromBlob(blob: Blob): Promise<string | null> {\n  const slice = blob.slice(0, 32);\n  const buffer = await slice.arrayBuffer();\n  return sniffMime(new Uint8Array(buffer));\n}\n"],"mappings":"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","names":[]}