@ai-matrx/media 0.8.0 → 0.9.0

package/dist/files/engine/handler/types.d.ts

@@ -0,0 +1,367 @@
+/**
+ * features/files/handler/types.ts
+ *
+ * The universal file handler. ONE shape goes in (FileSource), ONE shape
+ * comes out (FileTarget). Between them, every file in the app — owned
+ * cld_files row, blob from a paste, base64 string, external URL — funnels
+ * through the same NormalizedFile representation so the core never
+ * branches on origin.
+ *
+ * Every callsite that touches a file MUST go through this feature. Direct
+ * construction of ImageBlock/AudioBlock/VideoBlock/DocumentBlock literals
+ * and direct object-store SDK calls are banned by ESLint (see .eslintrc).
+ */
+import type { Asset, AssetPreset, CloudFile, FileUploadResponse, MediaRef, PermissionLevel, Visibility } from "../types.js";
+import type { CustomVariantSpec } from "../api/assets.js";
+import type { FileCategory, PreviewKind, ThumbnailStrategy } from "../utils/file-types.js";
+import type { AudioBlock, DocumentBlock, ImageBlock, VideoBlock, YouTubeVideoBlock } from "@ai-matrx/agents/message-parts";
+import type { MessagePart } from "@ai-matrx/agents/generated/stream-events";
+/**
+ * Discriminated union of every file shape that can enter the handler.
+ *
+ * Resolution priority enforced by the resolver: owned identifiers
+ * (`cloud_file`, `file_id`) beat opaque URLs (`share_link`, `public_cdn`)
+ * beat raw bytes (`blob`, `file`, `data_uri`, ...). Two locators on the
+ * same source are tolerated; the resolver picks the best.
+ */
+export type FileSource = BlobSource | FileObjectSource | BufferSource_ | StreamSource | DataUriSource | Base64Source | ExternalUrlSource | YouTubeSource | CloudFileSource | FileIdSource | ShareLinkSource | PublicCdnSource | UploadResultSource | StreamEventSource;
+export interface BlobSource {
+    kind: "blob";
+    blob: Blob;
+    fileName?: string;
+    mime?: string;
+}
+export interface FileObjectSource {
+    kind: "file";
+    file: File;
+}
+export interface BufferSource_ {
+    kind: "buffer";
+    buffer: ArrayBuffer | Uint8Array;
+    mime: string;
+    fileName?: string;
+}
+export interface StreamSource {
+    kind: "stream";
+    stream: ReadableStream<Uint8Array>;
+    mime: string;
+    fileName?: string;
+}
+export interface DataUriSource {
+    kind: "data_uri";
+    dataUri: string;
+}
+export interface Base64Source {
+    kind: "base64";
+    base64: string;
+    mime: string;
+    fileName?: string;
+}
+export interface ExternalUrlSource {
+    kind: "external_url";
+    url: string;
+    mime?: string;
+}
+export interface YouTubeSource {
+    kind: "youtube";
+    url: string;
+}
+export interface CloudFileSource {
+    kind: "cloud_file";
+    cloudFile: CloudFile;
+}
+export interface FileIdSource {
+    kind: "file_id";
+    fileId: string;
+    mime?: string;
+}
+export interface ShareLinkSource {
+    kind: "share_link";
+    token: string;
+    mime?: string;
+}
+export interface PublicCdnSource {
+    kind: "public_cdn";
+    url: string;
+    fileId?: string;
+    mime?: string;
+}
+/** Legacy-compat shape — `{ fileId, url, ... }` payload emitted by older upload pathways. */
+export interface UploadResultSource {
+    kind: "upload_result";
+    uploadResult: {
+        fileId?: string;
+        url: string;
+        pageUrl?: string;
+        type?: string;
+        metadata?: Record<string, unknown>;
+    };
+}
+/**
+ * Stream event payload. The handler unwraps RenderBlock/data/tool-output
+ * envelopes and produces a NormalizedFile. The shape mirrors the
+ * `TypedDataPayload` discriminator for image_output/audio_output/video_output
+ * plus the structured render-block payload for type=image/video/document.
+ */
+export interface StreamEventSource {
+    kind: "stream_event";
+    payload: unknown;
+}
+/**
+ * The canonical internal shape. After normalization, every code path past
+ * the resolver sees only this. There is no second internal shape — adding
+ * one would defeat the entire purpose of the handler.
+ */
+export interface NormalizedFile {
+    /** cld_files UUID — set whenever known. */
+    fileId?: string;
+    /**
+     * User-facing logical path for a persisted cloud file. This is never an
+     * object-store key or transport identity; it is retained so canonical
+     * version writers can target the existing row after resolving by fileId.
+     */
+    filePath?: string;
+    /** Any URL safe to hand to the browser. */
+    url?: string;
+    /** Inline base64. Last resort. Always include `meta.mime`. */
+    base64?: string;
+    /** Resolved share-link token, when the source was a share link. */
+    shareToken?: string;
+    /** YouTube videos are first-class — backend has dedicated handling. */
+    youtubeUrl?: string;
+    origin: FileOrigin;
+    capabilities: FileCapabilities;
+    meta: FileMeta;
+    lifecycle: FileLifecycle;
+    scope: FileScope;
+    derivedFrom?: {
+        fileId: string;
+        kind: string;
+    };
+    /**
+     * Full {@link Asset} envelope — populated when the file was uploaded
+     * through the `/assets` preset pipeline (or when callers explicitly
+     * resolve to one). Carries every rendered variant URL keyed by
+     * canonical variant key (e.g. `og_url`, `thumbnail_url`). Read this
+     * instead of making a second round-trip for variants.
+     */
+    asset?: Asset;
+    /**
+     * Original input — kept so we can re-resolve, refresh, or diagnose.
+     * Never read this from a render path; use the normalized fields.
+     */
+    __source: FileSource;
+}
+/**
+ * Result of a successful canonical upload. Unlike a general NormalizedFile,
+ * a newly-persisted upload must always carry its durable cld_files identity.
+ */
+export interface UploadedNormalizedFile extends NormalizedFile {
+    fileId: string;
+}
+export type FileOrigin = "owned" | "shared" | "public" | "external" | "ephemeral" | "anonymous_public";
+export interface FileCapabilities {
+    canRead: boolean;
+    canEdit: boolean;
+    canShare: boolean;
+    canDelete: boolean;
+    /** True when the consumer needs to hold a JWT to open this URL. */
+    requiresAuth: boolean;
+    /**
+     * True when the URL can be `fetch()`ed from the browser — durable
+     * `/files/{id}/download` route URLs qualify (the python-client attaches
+     * Authorization headers). False for opaque third-party URLs that may be
+     * CORS-blocked; output adapters that need bytes route through the
+     * backend instead when this is false.
+     */
+    transportSafeForFetch: boolean;
+}
+export interface FileMeta {
+    fileName?: string;
+    mime?: string;
+    sizeBytes?: number;
+    checksum?: string;
+    width?: number;
+    height?: number;
+    durationSec?: number;
+    pageCount?: number;
+    category: FileCategory;
+    previewKind: PreviewKind;
+    thumbnailStrategy: ThumbnailStrategy;
+}
+export interface FileLifecycle {
+    /** ms epoch — only set for time-bounded references. */
+    expiresAt?: number;
+    /** True if we have enough identity to re-mint a fresh URL. */
+    refreshable: boolean;
+    /** ms epoch of the last full re-validation. */
+    lastVerifiedAt?: number;
+    /** True once the file is durably persisted (vs in-flight upload). */
+    persisted: boolean;
+}
+export interface FileScope {
+    ownerId?: string;
+    organizationId?: string;
+    projectId?: string;
+    taskId?: string;
+}
+/**
+ * Discriminated union of every consumer surface. The output dispatcher picks
+ * the optimal locator on the NormalizedFile for each target — `<img src>`
+ * prefers a permanent CDN URL, `fetchable_url` prefers the same-origin proxy
+ * for CORS safety, AI media blocks prefer `file_id`.
+ */
+export type FileTarget = {
+    kind: "media_block";
+} | {
+    kind: "media_ref";
+} | {
+    kind: "html_src";
+} | {
+    kind: "fetchable_url";
+} | {
+    kind: "blob";
+} | {
+    kind: "data_uri";
+} | {
+    kind: "form_data_part";
+    field: string;
+} | {
+    kind: "anchor_download";
+    suggestedName?: string;
+} | {
+    kind: "og_image";
+} | {
+    kind: "jsonb_content_part";
+} | {
+    kind: "rag_ingest_source";
+};
+export type RenderedFor<T extends FileTarget> = T extends {
+    kind: "media_block";
+} ? MediaBlock : T extends {
+    kind: "media_ref";
+} ? MediaRef : T extends {
+    kind: "html_src";
+} ? string : T extends {
+    kind: "fetchable_url";
+} ? string : T extends {
+    kind: "blob";
+} ? Blob : T extends {
+    kind: "data_uri";
+} ? string : T extends {
+    kind: "form_data_part";
+} ? {
+    value: Blob;
+    filename: string;
+} : T extends {
+    kind: "anchor_download";
+} ? {
+    url: string;
+    filename: string;
+} : T extends {
+    kind: "og_image";
+} ? string : T extends {
+    kind: "jsonb_content_part";
+} ? MessagePart : T extends {
+    kind: "rag_ingest_source";
+} ? RagIngestSource : never;
+/** All four media block types plus YouTube — what AI APIs accept. */
+export type MediaBlock = ImageBlock | AudioBlock | VideoBlock | DocumentBlock | YouTubeVideoBlock;
+export interface RagIngestSource {
+    source_kind: "cld_file" | "external_url" | "inline";
+    source_id?: string;
+    url?: string;
+    inline?: {
+        mime: string;
+        bytes: Uint8Array;
+    };
+}
+export interface UploadOpts {
+    /**
+     * Logical folder path. Backend creates intermediate folders atomically.
+     * If omitted, defaults to a per-feature inbox like "Inbox/Pasted".
+     */
+    folderPath?: string;
+    /**
+     * Full logical file path (folder + filename). Wins over `folderPath`
+     * when set. Use this to write a new version of an existing file by
+     * pointing at the same path the existing file occupies — the Python
+     * backend treats matching paths as version-increments on the existing
+     * cld_files row rather than creating a new sibling.
+     */
+    filePath?: string;
+    /**
+     * One-line note attached to the new version row (`cld_file_versions.change_summary`).
+     * Surfaces in the version history UI.
+     */
+    changeSummary?: string;
+    /** Visibility on the new cld_files row. Default "personal" (or "public" for preset uploads). */
+    visibility?: Visibility;
+    /** Initial sharing grants. */
+    shareWith?: string[];
+    shareLevel?: PermissionLevel;
+    /** Free-form metadata stored on the row. */
+    metadata?: Record<string, unknown>;
+    /**
+     * The organization that owns the uploaded bytes. When supplied, this wins
+     * over the ambient app context for every visibility and is written into
+     * `metadata.scope.organization_id` before the transport starts.
+     */
+    organizationId?: string;
+    /** Override filename when source has no inherent name. */
+    fileName?: string;
+    /**
+     * When true, scope columns (organization_id/project_id/task_id) are read
+     * from `appContext` and stamped into `metadata.scope` so the row carries
+     * its scope context. Defaults to false for personal uploads and true for
+     * public/shared uploads.
+     */
+    inheritActiveScope?: boolean;
+    /** Per-byte progress callback. */
+    onProgress?: (loaded: number, total: number) => void;
+    /** Abort the upload (buffered XHR abort / TUS abort). */
+    signal?: AbortSignal;
+    /**
+     * Transport override. Default policy: files ≥
+     * `TUS_TRANSPORT_THRESHOLD_BYTES` (features/files/upload/cloudUpload.ts)
+     * go resumable TUS; smaller files use the buffered multipart POST.
+     */
+    transport?: "buffered" | "tus";
+    /**
+     * If true, the handler also creates a permanent share link after upload.
+     * The returned NormalizedFile carries `shareToken` + `url` pointing at
+     * Python's `{BACKEND}/share/{token}` endpoint (no Next.js hop, no
+     * expiry — embed in `<img src>`, persist to DB columns, etc.).
+     */
+    createShareLink?: boolean;
+    /** Default "read". `admin` is not valid for share links. */
+    shareLinkPermissionLevel?: "viewer" | "editor";
+    shareLinkExpiresAt?: string | null;
+    shareLinkMaxUses?: number | null;
+    /**
+     * Override origin for the returned share URL. Defaults to
+     * `window.location.origin`. Rare — useful for SSR/worker contexts that
+     * synthesize their own origin.
+     */
+    appOrigin?: string;
+    /**
+     * Asset-pipeline preset. When set, the handler routes through
+     * `POST /assets` (which renders preset variants server-side) instead of
+     * the plain `POST /files/upload` write. The returned `NormalizedFile`
+     * carries the full {@link Asset} envelope on `asset` so consumers can
+     * read every rendered variant URL without a second round-trip.
+     *
+     * Set this for image uploads that need server-rendered variant sets
+     * (podcast covers, OG cards, org logos, avatars, favicons). Omit for
+     * generic file uploads.
+     */
+    preset?: AssetPreset;
+    /**
+     * Ad-hoc custom variant specs sent verbatim to the server in
+     * `custom_variants_json`. Use when the preset registry doesn't carry a
+     * key you need; otherwise prefer presets so downstream renderers
+     * recognize the resulting variant keys.
+     */
+    customVariants?: CustomVariantSpec[];
+}
+export type { FileUploadResponse };

package/dist/files/engine/handler/types.js

@@ -0,0 +1 @@
+//# sourceMappingURL=types.js.map

package/dist/files/engine/handler/types.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/files/engine/handler/upload.d.ts

@@ -0,0 +1,32 @@
+/**
+ * features/files/handler/upload.ts
+ *
+ * The single write path. Coerces a `FileSource` into a `File`, then runs
+ * it through `cloudUpload` (which dispatches optimistic Redux updates,
+ * calls Python's `/files/upload`, and optionally creates a share link in
+ * the same round-trip). The returned `NormalizedFile` reflects the new
+ * `cld_files` row and carries the share-link URL when requested.
+ *
+ * Org-scope routing is visibility-aware: public/shared uploads inherit
+ * active organization / project / task ids by default; personal uploads
+ * remain independent of ambient app scope unless explicitly opted in.
+ */
+import type { FileSource, NormalizedFile, UploadedNormalizedFile, UploadOpts } from "./types.js";
+/**
+ * Personal files belong to the individual, independent of whichever
+ * organization, project, or task happens to be active in the UI.
+ */
+export declare function shouldInheritActiveScope(visibility: NonNullable<UploadOpts["visibility"]>, override?: boolean, folderPath?: string): boolean;
+export declare function uploadInternal(source: FileSource, opts: UploadOpts): Promise<UploadedNormalizedFile>;
+/**
+ * Merge metadata from a post-upload hydration without letting that secondary
+ * read erase or replace the identity acknowledged by the creation response.
+ * This is shared by ordinary and asset uploads because both are the same
+ * two-step contract: create → hydrate.
+ */
+export declare function preserveUploadedIdentity(hydrated: NormalizedFile, authoritativeFileId: string, label?: string): UploadedNormalizedFile;
+export declare function stampScope(metadata: Record<string, unknown>, inherit: boolean, organizationId?: string, activeScope?: {
+    organizationId?: string | null;
+    projectId?: string | null;
+    taskId?: string | null;
+}): Record<string, unknown>;

package/dist/files/engine/handler/upload.js

@@ -0,0 +1,295 @@
+import { getStoreSingleton } from "../host/store.js";
+import {
+  cloudUpload,
+  isCloudUploadFailure
+} from "../upload/cloudUpload.js";
+import * as Files from "../api/files.js";
+import {
+  uploadAsset,
+  uploadAssetWithProgress
+} from "../api/assets.js";
+import { pythonShareUrl } from "./utils/python-base.js";
+import { apiFileRecordToCloudFile } from "../redux/converters.js";
+import {
+  selectOrganizationId,
+  selectProjectId,
+  selectTaskId
+} from "../host/store.js";
+import { FileUploadError, UploadCancelledError } from "../../../files.js";
+import { fromCloudFile } from "./input/normalize.js";
+import { setCached } from "../hooks/blob-cache.js";
+const DEFAULT_FOLDER = "Inbox";
+function shouldInheritActiveScope(visibility, override, folderPath) {
+  if (override !== void 0) return override;
+  const normalizedFolder = folderPath?.replace(/^\/+|\/+$/g, "") ?? "";
+  if (normalizedFolder === "Shared Assets" || normalizedFolder.startsWith("Shared Assets/") || normalizedFolder === "Private Assets" || normalizedFolder.startsWith("Private Assets/")) {
+    return false;
+  }
+  return visibility !== "personal";
+}
+async function uploadInternal(source, opts) {
+  const file = await sourceToFile(source, opts.fileName);
+  if (!file) {
+    throw new FileUploadError(
+      "Cannot upload: source did not produce raw bytes (use the input shape that already has a fileId instead)"
+    );
+  }
+  const store = getStoreSingleton();
+  if (!store) {
+    throw new FileUploadError("Cannot upload: redux store not yet initialized");
+  }
+  const dispatch = store.dispatch;
+  const folderPath = opts.folderPath ?? defaultFolderForSource(source);
+  const visibility = opts.visibility ?? (opts.preset ? "public" : "personal");
+  const metadata = stampScope(
+    opts.metadata ?? {},
+    shouldInheritActiveScope(visibility, opts.inheritActiveScope, folderPath),
+    opts.organizationId
+  );
+  if (opts.preset) {
+    const params = {
+      file,
+      preset: opts.preset,
+      folder: folderPath.replace(/^\/+|\/+$/g, ""),
+      visibility,
+      customVariants: opts.customVariants,
+      shareWith: opts.shareWith,
+      shareLevel: opts.shareLevel,
+      metadata
+    };
+    const { data: asset } = opts.onProgress ? await uploadAssetWithProgress(
+      params,
+      (event) => opts.onProgress(event.loaded, event.total)
+    ) : await uploadAsset(params);
+    setCached(asset.file_id, file, URL.createObjectURL(file), {
+      mimeType: file.type
+    });
+    const { data: full2 } = await Files.getFile(asset.file_id);
+    const cloudFile2 = apiFileRecordToCloudFile(full2);
+    const normalized2 = preserveUploadedIdentity(
+      fromCloudFile(cloudFile2, source),
+      asset.file_id,
+      "asset upload"
+    );
+    return {
+      ...normalized2,
+      asset,
+      url: asset.primary_url ?? normalized2.url
+    };
+  }
+  const result = await cloudUpload(
+    file,
+    {
+      // filePath wins when set — used by version-replace callers (e.g. the
+      // image editor "Save" path that overwrites the existing cloud file).
+      ...opts.filePath ? { filePath: opts.filePath.replace(/^\/+/, "") } : { folderPath: folderPath.replace(/^\/+|\/+$/g, "") },
+      visibility,
+      shareWith: opts.shareWith,
+      shareLevel: opts.shareLevel,
+      changeSummary: opts.changeSummary,
+      metadata,
+      onProgress: opts.onProgress ? (event) => opts.onProgress(event.loaded, event.total) : void 0,
+      signal: opts.signal,
+      transport: opts.transport,
+      createShareLink: opts.createShareLink,
+      shareLinkPermissionLevel: opts.shareLinkPermissionLevel,
+      shareLinkExpiresAt: opts.shareLinkExpiresAt,
+      shareLinkMaxUses: opts.shareLinkMaxUses
+    },
+    dispatch
+  );
+  if (isCloudUploadFailure(result)) {
+    if (result.errorCode === "upload_cancelled") {
+      throw new UploadCancelledError(result.error);
+    }
+    throw new FileUploadError(result.error);
+  }
+  setCached(result.fileId, file, URL.createObjectURL(file), {
+    mimeType: file.type
+  });
+  const { data: full } = await Files.getFile(result.fileId);
+  const cloudFile = apiFileRecordToCloudFile(full);
+  const normalized = preserveUploadedIdentity(
+    fromCloudFile(cloudFile, source),
+    result.fileId
+  );
+  if (result.shareToken) {
+    const appShareUrl = opts.appOrigin ? `${opts.appOrigin.replace(/\/$/, "")}/s/${result.shareToken}` : void 0;
+    const publicUrl = cloudFile.visibility === "public" ? normalized.url : void 0;
+    const url = publicUrl || result.directUrl || appShareUrl || result.shareUrl || pythonShareUrl(result.shareToken);
+    return {
+      ...normalized,
+      shareToken: result.shareToken,
+      url
+    };
+  }
+  return normalized;
+}
+function preserveUploadedIdentity(hydrated, authoritativeFileId, label = "upload") {
+  if (hydrated.fileId !== authoritativeFileId) {
+    console.error(
+      `[file-handler] hydrated ${label} lost or changed its durable identity (upload=${authoritativeFileId}, hydrated=${hydrated.fileId ?? "<missing>"}); preserving the upload acknowledgement.`
+    );
+  }
+  const uploaded = {
+    ...hydrated,
+    fileId: authoritativeFileId
+  };
+  assertUploadedIdentity(uploaded);
+  return uploaded;
+}
+function assertUploadedIdentity(file) {
+  if (!file.fileId) {
+    throw new FileUploadError(
+      "Upload completed without a durable file identity; refusing to attach a temporary URL"
+    );
+  }
+}
+async function sourceToFile(source, overrideName) {
+  switch (source.kind) {
+    case "file":
+      return overrideName ? renameFile(source.file, overrideName) : source.file;
+    case "blob": {
+      const name = overrideName ?? source.fileName ?? guessFilename(source.blob.type);
+      return new File([source.blob], name, {
+        type: source.mime ?? source.blob.type ?? "application/octet-stream"
+      });
+    }
+    case "buffer": {
+      const blob = bufferToBlob(source.buffer, source.mime);
+      const name = overrideName ?? source.fileName ?? guessFilename(source.mime);
+      return new File([blob], name, { type: source.mime });
+    }
+    case "stream": {
+      const reader = source.stream.getReader();
+      const parts = [];
+      while (true) {
+        const { value, done } = await reader.read();
+        if (done) break;
+        if (value) {
+          const copy = new Uint8Array(value.byteLength);
+          copy.set(value);
+          parts.push(copy.buffer);
+        }
+      }
+      const blob = new Blob(parts, { type: source.mime });
+      const name = overrideName ?? source.fileName ?? guessFilename(source.mime);
+      return new File([blob], name, { type: source.mime });
+    }
+    case "data_uri":
+    case "base64": {
+      const dataUri = source.kind === "data_uri" ? source.dataUri : `data:${source.mime};base64,${source.base64}`;
+      const blob = await dataUriToBlob(dataUri);
+      const fallbackName = "fileName" in source && source.fileName || guessFilename(blob.type);
+      const name = overrideName ?? fallbackName;
+      return new File([blob], name, { type: blob.type });
+    }
+    case "external_url": {
+      const res = await fetch(source.url);
+      if (!res.ok) {
+        throw new FileUploadError(
+          `Failed to fetch external URL for upload (${res.status})`
+        );
+      }
+      const blob = await res.blob();
+      const name = overrideName ?? filenameFromUrl(source.url) ?? guessFilename(blob.type);
+      return new File([blob], name, { type: source.mime ?? blob.type });
+    }
+    case "youtube":
+      throw new FileUploadError(
+        "YouTube URLs cannot be uploaded \u2014 pass them as a source directly"
+      );
+    default:
+      return null;
+  }
+}
+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 dataUriToBlob(dataUri) {
+  return fetch(dataUri).then((r) => r.blob());
+}
+function renameFile(file, name) {
+  return new File([file], name, {
+    type: file.type,
+    lastModified: file.lastModified
+  });
+}
+function filenameFromUrl(url) {
+  try {
+    const path = new URL(url).pathname;
+    const last = path.split("/").pop();
+    return last && last.length > 0 ? last : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function guessFilename(mime) {
+  if (!mime) return "upload.bin";
+  const ext = mime.split("/")[1]?.split(";")[0] ?? "bin";
+  return `upload-${Date.now()}.${ext}`;
+}
+function stampScope(metadata, inherit, organizationId, activeScope) {
+  if (!inherit && !organizationId) return metadata;
+  let resolvedActiveScope = activeScope;
+  if (inherit && !resolvedActiveScope) {
+    const store = getStoreSingleton();
+    if (store) {
+      const state = store.getState();
+      resolvedActiveScope = {
+        organizationId: selectOrganizationId(state),
+        projectId: selectProjectId(state),
+        taskId: selectTaskId(state)
+      };
+    }
+  }
+  const activeOrganizationId = resolvedActiveScope?.organizationId;
+  const projectId = resolvedActiveScope?.projectId;
+  const taskId = resolvedActiveScope?.taskId;
+  if (!organizationId && !activeOrganizationId && !projectId && !taskId) {
+    return metadata;
+  }
+  const existing = metadata.scope ?? {};
+  return {
+    ...metadata,
+    scope: {
+      ...existing,
+      ...activeOrganizationId ? { organization_id: activeOrganizationId } : {},
+      ...projectId ? { project_id: projectId } : {},
+      ...taskId ? { task_id: taskId } : {},
+      // An explicit owner is a record-bound write. It must never be replaced
+      // by whatever organization happens to be active in the shell.
+      ...organizationId ? { organization_id: organizationId } : {}
+    }
+  };
+}
+function defaultFolderForSource(source) {
+  switch (source.kind) {
+    case "file":
+    case "blob":
+      return DEFAULT_FOLDER;
+    case "data_uri":
+    case "base64":
+      return `${DEFAULT_FOLDER}/Pasted`;
+    case "external_url":
+      return `${DEFAULT_FOLDER}/Imported`;
+    default:
+      return DEFAULT_FOLDER;
+  }
+}
+export {
+  preserveUploadedIdentity,
+  shouldInheritActiveScope,
+  stampScope,
+  uploadInternal
+};
+//# sourceMappingURL=upload.js.map