nuxt-media-library 0.0.57 → 0.0.58

package/README.md

@@ -237,9 +237,11 @@ merges the layers, so every widget on the site can use any backend by name.
 export default defineNuxtConfig({
   modules: ['nuxt-media-library'],
   mediaLibrary: {
-    serviceUploads: {
-      backends: { videos: { start: '/api/videos/uploads' } },
-      // refresh defaults to `${start}/:sessionId/grant`
+    backends: {
+      videos: {
+        upload: { start: '/api/videos/uploads' }, // refresh defaults to `${start}/:sessionId/grant`
+        claim: '/api/videos/uploads/:sessionId/attach', // py_client on_attach
+      },
     },
   },
 })
@@ -257,17 +259,26 @@ export default defineNuxtConfig({
 ```vue
 <MLMediaGallery
   v-model="lesson.mediaIds"
-  service="videos"
+  backend="videos"
   profile="lesson-video"
   :service-body="{ context: { lessonId } }"
   @uploaded="(assetId, role, sessionId) => attach(assetId, sessionId)"
 />
 ```
 
-- `service` on `MLMediaGallery`, `MLMediaField` and the file picker (and
-  `useMLMediaUpload`): a backend name, or `{ start }` for a one-off. Without
-  it, widgets upload through Nuxt's own route as before; an unknown name
-  fails that upload with a message naming the missing backend.
+- `backend` on `MLMediaGallery`, `MLMediaField` and the file picker (and
+  `useMLMediaUpload`): a name in `mediaLibrary.backends`. `service` is its
+  older name and still takes `{ start }` for a one-off; `backend` wins.
+  Without either, widgets upload through Nuxt's own route as before; an
+  unknown name fails that upload with a message naming the missing backend.
+- Each backend has a `kind`: `media-library` (the default) or `media-kit`.
+  This version uploads only to `media-library` backends; a `media-kit` one
+  fails the upload with a clear message.
+- With `claim`, the upload queue attaches files whose page was left before
+  the widget attached them (`POST { assetId, profile }`; 409 counts as
+  attached). The tray shows a refusal with "Add again".
+- `mediaLibrary.serviceUploads.backends` still works: each entry becomes a
+  `media-library` backend with that `upload` and no `claim`.
 - The start request carries the file (`mimeType`, `sizeBytes`, `filename`),
   `profile` (each role's, in a gallery with roles) and `service-body`. The
   service's profile decides kind, visibility and processing, so

package/dist/module.d.mts

@@ -1,5 +1,6 @@
 import * as _nuxt_schema from '@nuxt/schema';
 import { ServiceUploadBackend } from '../dist/runtime/utils/uploader/serviceBackends.js';
+import { MediaBackends } from '../dist/runtime/utils/backends.js';
 export * from '../dist/runtime/types/resourcePolicy.js';
 export * from '../dist/runtime/types/uploader.js';
 export * from '../dist/runtime/types/preview.js';
@@ -43,9 +44,8 @@ interface ModuleOptions {
      * public API root with `/v1`, or a proxy route); with `proxy` it defaults
      * to the pass-through route.
      *
-     * `backends` names the services that start uploads, so widgets can use
-     * `service="videos"`. Each service's Nuxt layer registers its own; Nuxt
-     * merges them across layers. Paths only: each layer serves its routes.
+     * `backends`: older form of `mediaLibrary.backends` (start/refresh only).
+     * Each entry becomes a `media-library` backend with that `upload`.
      */
     serviceUploads?: {
         proxy?: boolean;
@@ -62,6 +62,16 @@ interface ModuleOptions {
      * pass-through are still registered.
      */
     manageProxy?: boolean;
+    /**
+     * The backend registry: named places widgets upload to and read from
+     * (`<MLMediaGallery backend="videos" />`). Each entry has a `kind`
+     * (`media-library`, the default, or `media-kit`) and its routes: `upload`
+     * (`{ start, refresh? }`, py_client `create_upload_router`), `claim`
+     * (attach a finished upload, `/…/:sessionId/attach`). Each service's Nuxt
+     * layer registers its own; Nuxt merges them. Paths only: each layer serves
+     * its routes.
+     */
+    backends?: MediaBackends;
 }
 declare const SERVICE_UPLOADS_ROUTE = "/api/media-library/service-uploads";
 declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;

package/dist/module.d.ts

@@ -1,5 +1,6 @@
 import * as _nuxt_schema from '@nuxt/schema';
 import { ServiceUploadBackend } from '../dist/runtime/utils/uploader/serviceBackends.js';
+import { MediaBackends } from '../dist/runtime/utils/backends.js';
 export * from '../dist/runtime/types/resourcePolicy.js';
 export * from '../dist/runtime/types/uploader.js';
 export * from '../dist/runtime/types/preview.js';
@@ -43,9 +44,8 @@ interface ModuleOptions {
      * public API root with `/v1`, or a proxy route); with `proxy` it defaults
      * to the pass-through route.
      *
-     * `backends` names the services that start uploads, so widgets can use
-     * `service="videos"`. Each service's Nuxt layer registers its own; Nuxt
-     * merges them across layers. Paths only: each layer serves its routes.
+     * `backends`: older form of `mediaLibrary.backends` (start/refresh only).
+     * Each entry becomes a `media-library` backend with that `upload`.
      */
     serviceUploads?: {
         proxy?: boolean;
@@ -62,6 +62,16 @@ interface ModuleOptions {
      * pass-through are still registered.
      */
     manageProxy?: boolean;
+    /**
+     * The backend registry: named places widgets upload to and read from
+     * (`<MLMediaGallery backend="videos" />`). Each entry has a `kind`
+     * (`media-library`, the default, or `media-kit`) and its routes: `upload`
+     * (`{ start, refresh? }`, py_client `create_upload_router`), `claim`
+     * (attach a finished upload, `/…/:sessionId/attach`). Each service's Nuxt
+     * layer registers its own; Nuxt merges them. Paths only: each layer serves
+     * its routes.
+     */
+    backends?: MediaBackends;
 }
 declare const SERVICE_UPLOADS_ROUTE = "/api/media-library/service-uploads";
 declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "media-library",
   "configKey": "mediaLibrary",
-  "version": "0.0.57",
+  "version": "0.0.58",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/module.mjs

@@ -1,6 +1,7 @@
 import { existsSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { defineNuxtModule, createResolver, addImportsDir, addComponentsDir, addServerHandler, useLogger, addPlugin } from '@nuxt/kit';
+import { normalizeBackends } from '../dist/runtime/utils/backends.js';
 export * from '../dist/runtime/types/resourcePolicy.js';
 export * from '../dist/runtime/types/uploader.js';
 export * from '../dist/runtime/types/preview.js';
@@ -22,23 +23,6 @@ function browserBaseURL(existingPublic, publicBaseURL) {
 }
 
 const SERVICE_UPLOADS_ROUTE = "/api/media-library/service-uploads";
-function serviceBackends(backends, logger) {
-  const out = {};
-  for (const [name, backend] of Object.entries(backends ?? {})) {
-    if (!backend || typeof backend.start !== "string" || !backend.start) {
-      logger.warn(`mediaLibrary.serviceUploads.backends.${name} has no start path; ignored.`);
-      continue;
-    }
-    if (backend.refresh && !backend.refresh.includes(":sessionId")) {
-      logger.warn(`mediaLibrary.serviceUploads.backends.${name}.refresh needs a :sessionId placeholder; using the default.`);
-    }
-    out[name] = {
-      start: backend.start,
-      ...backend.refresh?.includes(":sessionId") ? { refresh: backend.refresh } : {}
-    };
-  }
-  return out;
-}
 function appCatchAlls(layers) {
   const found = [];
   for (const { config } of layers) {
@@ -171,6 +155,10 @@ const module$1 = defineNuxtModule({
     if (existingPublic.proxyUploads === false && !existingPublic.baseURL && !options.publicBaseURL) {
       logger.warn("proxyUploads is false but no public media library address is set: set mediaLibrary.publicBaseURL. baseURL is server-side only.");
     }
+    const backends = {
+      ...normalizeBackends(options.backends, options.serviceUploads?.backends, (m) => logger.warn(m)),
+      ...normalizeBackends(existingPublic.backends, existingPublic.serviceUploadBackends, (m) => logger.warn(m))
+    };
     nuxt.options.runtimeConfig.public.mediaLibrary = {
       ...existingPublic,
       baseURL: browserBaseURL(existingPublic.baseURL, options.publicBaseURL),
@@ -186,8 +174,12 @@ const module$1 = defineNuxtModule({
       headers: publicHeaders.headers,
       // Where useMLServiceUpload sends parts (NUXT_PUBLIC_MEDIA_LIBRARY_SERVICE_UPLOAD_BASE_URL).
       serviceUploadBaseURL: existingPublic.serviceUploadBaseURL || options.serviceUploads?.baseURL || (options.serviceUploads?.proxy ? SERVICE_UPLOADS_ROUTE : ""),
-      // Names widgets can pass as `service` (NUXT_PUBLIC_MEDIA_LIBRARY_SERVICE_UPLOAD_BACKENDS).
-      serviceUploadBackends: { ...serviceBackends(options.serviceUploads?.backends, logger), ...existingPublic.serviceUploadBackends }
+      // The backend registry (NUXT_PUBLIC_MEDIA_LIBRARY_BACKENDS): names widgets pass as `backend`.
+      backends,
+      // Older form, kept for code that reads it: each backend's upload routes.
+      serviceUploadBackends: Object.fromEntries(
+        Object.entries(backends).flatMap(([name, b]) => b.upload ? [[name, b.upload]] : [])
+      )
     };
     addPlugin({
       src: resolver.resolve("./runtime/plugins/config")

package/dist/runtime/components/MLMedia/Field.d.vue.ts

@@ -18,10 +18,12 @@ type __VLS_Props = {
     /** Upload profile name for new files. */
     profile?: string | null;
     /**
-     * Start uploads at a backend service instead of Nuxt's own route: a name
-     * registered under `mediaLibrary.serviceUploads.backends` (e.g. "videos"),
-     * or `{ start }`. See useMLMediaUpload.
+     * The backend registered under `mediaLibrary.backends` that uploads go to
+     * (e.g. "videos"). Its `claim` route attaches files whose page was left
+     * before they finished. Wins over `service`.
      */
+    backend?: string | null;
+    /** Older name for `backend`; also takes an inline `{ start }`. See useMLMediaUpload. */
     service?: MediaUploadOptions['service'];
     /** Extra fields for the service's start request, e.g. `{ context: { lessonId } }`. */
     serviceBody?: Record<string, unknown> | null;
@@ -65,6 +67,7 @@ declare const __VLS_export: import("vue").DefineComponent<__VLS_PublicProps, {},
     };
     collectionName: string | null;
     profile: string | null;
+    backend: string | null;
     service: string | import("../../index.js").MediaServiceUpload | null;
     serviceBody: Record<string, unknown> | null;
     hint: string;

package/dist/runtime/components/MLMedia/Field.vue

@@ -16,6 +16,7 @@ const props = defineProps({
   processingConfig: { type: Object, required: false, default: void 0 },
   collectionName: { type: [String, null], required: false, default: null },
   profile: { type: [String, null], required: false, default: null },
+  backend: { type: [String, null], required: false, default: null },
   service: { type: null, required: false, default: void 0 },
   serviceBody: { type: [Object, null], required: false, default: null },
   picker: { type: Boolean, required: false, default: true },
@@ -34,6 +35,7 @@ const field = useMLMediaField(model, {
   processingConfig: props.processingConfig,
   collectionName: props.collectionName,
   profile: props.profile,
+  backend: props.backend,
   service: props.service,
   serviceBody: props.serviceBody,
   label: props.label || void 0,
@@ -77,6 +79,7 @@ const uploadOptions = computed(() => ({
   processingConfig: props.processingConfig,
   collectionName: props.collectionName,
   profile: props.profile,
+  backend: props.backend,
   service: props.service,
   serviceBody: props.serviceBody
 }));

package/dist/runtime/components/MLMedia/Field.vue.d.ts

@@ -18,10 +18,12 @@ type __VLS_Props = {
     /** Upload profile name for new files. */
     profile?: string | null;
     /**
-     * Start uploads at a backend service instead of Nuxt's own route: a name
-     * registered under `mediaLibrary.serviceUploads.backends` (e.g. "videos"),
-     * or `{ start }`. See useMLMediaUpload.
+     * The backend registered under `mediaLibrary.backends` that uploads go to
+     * (e.g. "videos"). Its `claim` route attaches files whose page was left
+     * before they finished. Wins over `service`.
      */
+    backend?: string | null;
+    /** Older name for `backend`; also takes an inline `{ start }`. See useMLMediaUpload. */
     service?: MediaUploadOptions['service'];
     /** Extra fields for the service's start request, e.g. `{ context: { lessonId } }`. */
     serviceBody?: Record<string, unknown> | null;
@@ -65,6 +67,7 @@ declare const __VLS_export: import("vue").DefineComponent<__VLS_PublicProps, {},
     };
     collectionName: string | null;
     profile: string | null;
+    backend: string | null;
     service: string | import("../../index.js").MediaServiceUpload | null;
     serviceBody: Record<string, unknown> | null;
     hint: string;

package/dist/runtime/components/MLMedia/Gallery.d.vue.ts

@@ -35,10 +35,12 @@ type __VLS_Props = {
     /** Upload profile for the single list (with `profiles`, each role has its own). */
     profile?: string | null;
     /**
-     * Start uploads at a backend service instead of Nuxt's own route: a name
-     * registered under `mediaLibrary.serviceUploads.backends` (e.g. "videos"),
-     * or `{ start }`. Each role's profile is sent with the start request.
+     * The backend registered under `mediaLibrary.backends` that uploads go to
+     * (e.g. "videos"). Its `claim` route attaches files whose page was left
+     * before they finished. Each role's profile is sent with the start request. Wins over `service`.
      */
+    backend?: string | null;
+    /** Older name for `backend`; also takes an inline `{ start }`. */
     service?: MediaUploadOptions['service'];
     /** Extra fields for the service's start request, e.g. `{ context: { lessonId } }`. */
     serviceBody?: Record<string, unknown> | null;
@@ -76,6 +78,7 @@ declare const __VLS_export: import("vue").DefineComponent<__VLS_PublicProps, {},
     };
     collectionName: string | null;
     profile: string | null;
+    backend: string | null;
     service: string | import("../../index.js").MediaServiceUpload | null;
     serviceBody: Record<string, unknown> | null;
     hint: string;

package/dist/runtime/components/MLMedia/Gallery.vue

@@ -19,6 +19,7 @@ const props = defineProps({
   processingConfig: { type: Object, required: false, default: void 0 },
   collectionName: { type: [String, null], required: false, default: null },
   profile: { type: [String, null], required: false, default: null },
+  backend: { type: [String, null], required: false, default: null },
   service: { type: null, required: false, default: void 0 },
   serviceBody: { type: [Object, null], required: false, default: null },
   picker: { type: Boolean, required: false, default: true },
@@ -275,6 +276,7 @@ function chipCount(key, max) {
     :profile="defaultRole?.profile ?? null"
     :profile-for="profileFor"
     :on-route-files="routeFiles"
+    :backend="backend"
     :service="service"
     :service-body="serviceBody"
     :disabled="disabled"
@@ -353,6 +355,7 @@ function chipCount(key, max) {
     :processing-config="processingConfig"
     :collection-name="collectionName"
     :profile="profile"
+    :backend="backend"
     :service="service"
     :service-body="serviceBody"
     :picker="picker"

package/dist/runtime/components/MLMedia/Gallery.vue.d.ts

@@ -35,10 +35,12 @@ type __VLS_Props = {
     /** Upload profile for the single list (with `profiles`, each role has its own). */
     profile?: string | null;
     /**
-     * Start uploads at a backend service instead of Nuxt's own route: a name
-     * registered under `mediaLibrary.serviceUploads.backends` (e.g. "videos"),
-     * or `{ start }`. Each role's profile is sent with the start request.
+     * The backend registered under `mediaLibrary.backends` that uploads go to
+     * (e.g. "videos"). Its `claim` route attaches files whose page was left
+     * before they finished. Each role's profile is sent with the start request. Wins over `service`.
      */
+    backend?: string | null;
+    /** Older name for `backend`; also takes an inline `{ start }`. */
     service?: MediaUploadOptions['service'];
     /** Extra fields for the service's start request, e.g. `{ context: { lessonId } }`. */
     serviceBody?: Record<string, unknown> | null;
@@ -76,6 +78,7 @@ declare const __VLS_export: import("vue").DefineComponent<__VLS_PublicProps, {},
     };
     collectionName: string | null;
     profile: string | null;
+    backend: string | null;
     service: string | import("../../index.js").MediaServiceUpload | null;
     serviceBody: Record<string, unknown> | null;
     hint: string;

package/dist/runtime/components/MLMedia/GallerySection.d.vue.ts

@@ -26,7 +26,9 @@ type __VLS_Props = {
     onOpen?: (assetId: string) => void;
     /** Upload profile name for new files in this list. */
     profile?: string | null;
-    /** Start uploads at a backend service (name or `{ start }`). See useMLMediaUpload. */
+    /** Registered backend uploads go to (`mediaLibrary.backends`). Wins over `service`. */
+    backend?: string | null;
+    /** Older name for `backend`; also takes an inline `{ start }`. See useMLMediaUpload. */
     service?: MediaUploadOptions['service'];
     /** Extra fields for the service's start request, e.g. `{ context: { lessonId } }`. */
     serviceBody?: Record<string, unknown> | null;
@@ -89,6 +91,7 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_PublicProps, {
     };
     collectionName: string | null;
     profile: string | null;
+    backend: string | null;
     service: string | import("../../index.js").MediaServiceUpload | null;
     serviceBody: Record<string, unknown> | null;
     profileFor: (file: File) => string | null | undefined;

package/dist/runtime/components/MLMedia/GallerySection.vue

@@ -24,6 +24,7 @@ const props = defineProps({
   editor: { type: Boolean, required: false, default: true },
   onOpen: { type: Function, required: false, default: void 0 },
   profile: { type: [String, null], required: false, default: null },
+  backend: { type: [String, null], required: false, default: null },
   service: { type: null, required: false, default: void 0 },
   serviceBody: { type: [Object, null], required: false, default: null },
   removeLabel: { type: String, required: false, default: void 0 },
@@ -45,6 +46,7 @@ const gallery = useMLMediaGallery(model, {
   processingConfig: props.processingConfig,
   collectionName: props.collectionName,
   profile: props.profile,
+  backend: props.backend,
   service: props.service,
   serviceBody: props.serviceBody,
   label: props.recordName ? `${props.title} of ${props.recordName}` : props.title,
@@ -130,6 +132,7 @@ async function pickExisting() {
       collectionName: props.collectionName,
       profile: props.profile,
       profileFor: props.profileFor,
+      backend: props.backend,
       service: props.service,
       serviceBody: props.serviceBody
     },

package/dist/runtime/components/MLMedia/GallerySection.vue.d.ts

@@ -26,7 +26,9 @@ type __VLS_Props = {
     onOpen?: (assetId: string) => void;
     /** Upload profile name for new files in this list. */
     profile?: string | null;
-    /** Start uploads at a backend service (name or `{ start }`). See useMLMediaUpload. */
+    /** Registered backend uploads go to (`mediaLibrary.backends`). Wins over `service`. */
+    backend?: string | null;
+    /** Older name for `backend`; also takes an inline `{ start }`. See useMLMediaUpload. */
     service?: MediaUploadOptions['service'];
     /** Extra fields for the service's start request, e.g. `{ context: { lessonId } }`. */
     serviceBody?: Record<string, unknown> | null;
@@ -89,6 +91,7 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_PublicProps, {
     };
     collectionName: string | null;
     profile: string | null;
+    backend: string | null;
     service: string | import("../../index.js").MediaServiceUpload | null;
     serviceBody: Record<string, unknown> | null;
     profileFor: (file: File) => string | null | undefined;

package/dist/runtime/components/MLMedia/MediaTile.d.vue.ts

@@ -42,12 +42,12 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {},
     progress: number | null;
     name: string;
     kind: string | null;
+    duration: number | null;
     disabled: boolean;
     selected: boolean;
     phase: ProgressVeilPhase | null;
     missingAlt: boolean;
     onOpen: () => void;
-    duration: number | null;
     selectable: boolean;
     selecting: boolean;
     phaseDetail: string;

package/dist/runtime/components/MLMedia/MediaTile.vue.d.ts

@@ -42,12 +42,12 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {},
     progress: number | null;
     name: string;
     kind: string | null;
+    duration: number | null;
     disabled: boolean;
     selected: boolean;
     phase: ProgressVeilPhase | null;
     missingAlt: boolean;
     onOpen: () => void;
-    duration: number | null;
     selectable: boolean;
     selecting: boolean;
     phaseDetail: string;

package/dist/runtime/components/MLMedia/UploadRow.vue

@@ -56,6 +56,7 @@ const subtitle = computed(() => {
       return ["Processing", at, x.step && stepLabel(x.step), elapsed.value].filter(Boolean).join(" \xB7 ");
     }
     case "ready":
+      if (x.orphaned && x.claimError) return `Not added${where.value ? ` to ${where.value}` : ""}: ${x.claimError}`;
       if (x.orphaned) return `Uploaded, not added${where.value ? ` to ${where.value}` : ""}`;
       return ["Ready to use", where.value].filter(Boolean).join(" \xB7 ");
     case "failed":
@@ -191,6 +192,15 @@ async function retryStep() {
         :loading="retrying"
         @click="retryStep"
       />
+      <UButton
+        v-else-if="u.orphaned && u.claimError && u.assetId"
+        icon="i-lucide-rotate-ccw"
+        color="neutral"
+        variant="outline"
+        size="xs"
+        label="Add again"
+        @click="queue.claim(u)"
+      />
       <UButton
         v-if="canShow"
         :to="u.context.to"

package/dist/runtime/composables/useMLMediaUpload.d.ts

@@ -1,6 +1,7 @@
 import type { ChunkUploaderConfig } from '../types/uploader.js';
 import type { ServiceUploadChoice } from '../utils/uploader/serviceBackends.js';
 export type { MediaServiceUpload, ServiceUploadBackend, ServiceUploadChoice } from '../utils/uploader/serviceBackends.js';
+export type { MediaBackend, MediaBackendKind, MediaBackends } from '../utils/backends.js';
 export type MediaUploadPhase = 'uploading' | 'processing' | 'ready' | 'failed' | 'canceled';
 /** What a policy-less upload session takes. See docs/resource-policy/retirement.md. */
 export interface MediaUploadOptions {
@@ -23,10 +24,18 @@ export interface MediaUploadOptions {
     /** Overrides the uploader config the module provides. */
     chunkUploader?: ChunkUploaderConfig;
     /**
+     * The backend registered under `mediaLibrary.backends` that uploads go to
+     * (e.g. `'videos'`). Its `upload.start` starts them (py_client
+     * `create_upload_router`); without one they go through Nuxt's own route.
+     * Its `claim` route attaches files whose widget went away first.
+     * Wins over `service`.
+     */
+    backend?: string | null;
+    /**
+     * Older name for `backend`, which also takes an inline `{ start, … }`.
      * Start uploads at a backend service (py_client `create_upload_router`)
-     * instead of Nuxt's own upload route: the name of a backend registered
-     * under `mediaLibrary.serviceUploads.backends` (e.g. `'videos'`), or
-     * `{ start, … }`. The service creates the session and its profile decides
+     * instead of Nuxt's own upload route: the name of a registered backend
+     * (e.g. `'videos'`), or `{ start, … }`. The service creates the session and its profile decides
      * kind, visibility and processing, so those options are not used here;
      * `profile` is sent as the start request's `profile`. The file's parts go
      * to `mediaLibrary.serviceUploads` (pass-through route or public URL).
@@ -69,11 +78,12 @@ export interface MediaUpload {
     readonly created: Promise<string | null>;
     /** Bytes. Kept for uploads restored after a reload, whose file is gone. */
     size: number;
+    /** The registered backend it went to (`mediaLibrary.backends`), or null. */
+    backend: string | null;
     /**
-     * Where the upload started: the backend name under
-     * `mediaLibrary.serviceUploads.backends` (e.g. `'videos'`), the start URL
-     * for an inline `{ start }`, or null for Nuxt's own route. With `sessionId`
-     * and `assetId`, enough to attach the file at that service.
+     * Where the upload started: the backend name (e.g. `'videos'`), the start
+     * URL for an inline `{ start }`, or null for Nuxt's own route. With
+     * `sessionId` and `assetId`, enough to attach the file at that service.
      */
     service: string | null;
     /** Upload profile sent with the session (after `profileFor`), or null. */
@@ -81,8 +91,14 @@ export interface MediaUpload {
     context: MediaUploadContext | null;
     /** The widget added the asset to its record. */
     attached: boolean;
-    /** The widget went away (page change) before it could add the asset. */
+    /**
+     * The widget went away (page change) before it could add the asset. With
+     * a backend `claim` route the queue attaches it there; otherwise the app
+     * does (onCreated).
+     */
     orphaned: boolean;
+    /** Why attaching an orphaned upload at its backend failed, or null. */
+    claimError: string | null;
     /** Current processing step (server name), and its place in the pipeline. */
     step: string | null;
     stepIndex: number | null;
@@ -150,6 +166,7 @@ export declare function useMLMediaUpload(defaults?: MediaUploadOptions): {
             readonly [Symbol.toStringTag]: string;
         };
         size: number;
+        backend: string | null;
         service: string | null;
         profile: string | null;
         context: {
@@ -163,6 +180,7 @@ export declare function useMLMediaUpload(defaults?: MediaUploadOptions): {
         } | null;
         attached: boolean;
         orphaned: boolean;
+        claimError: string | null;
         step: string | null;
         stepIndex: number | null;
         stepTotal: number | null;
@@ -217,6 +235,7 @@ export declare function useMLMediaUpload(defaults?: MediaUploadOptions): {
             readonly [Symbol.toStringTag]: string;
         };
         size: number;
+        backend: string | null;
         service: string | null;
         profile: string | null;
         context: {
@@ -230,6 +249,7 @@ export declare function useMLMediaUpload(defaults?: MediaUploadOptions): {
         } | null;
         attached: boolean;
         orphaned: boolean;
+        claimError: string | null;
         step: string | null;
         stepIndex: number | null;
         stepTotal: number | null;

package/dist/runtime/composables/useMLMediaUpload.js

@@ -1,5 +1,6 @@
 import { getCurrentScope, onScopeDispose, ref } from "vue";
 import { useRoute, useRuntimeConfig } from "#imports";
+import { legacyBackends } from "../utils/backends.js";
 import { useMLChunkUploader } from "./useMLChunkUploader.js";
 import { useMLUploadQueue } from "./useMLUploadQueue.js";
 let owners = 0;
@@ -8,7 +9,7 @@ export function useMLMediaUpload(defaults = {}) {
   const publicConfig = useRuntimeConfig().public?.mediaLibrary;
   const service = {
     baseURL: publicConfig?.serviceUploadBaseURL,
-    backends: publicConfig?.serviceUploadBackends
+    backends: publicConfig?.backends ?? legacyBackends(publicConfig?.serviceUploadBackends)
   };
   const queue = useMLUploadQueue();
   const route = useRoute();

package/dist/runtime/composables/useMLUploadQueue.d.ts

@@ -1,14 +1,14 @@
 import { type Ref } from 'vue';
 import type { ChunkUploaderConfig } from '../types/uploader.js';
-import { type ServiceUploadBackend } from '../utils/uploader/serviceBackends.js';
+import { type MediaBackends } from '../utils/backends.js';
 import type { MediaUpload, MediaUploadContext, MediaUploadOptions } from './useMLMediaUpload.js';
 interface StartMeta {
     owner: string;
     config: ChunkUploaderConfig;
-    /** Public service-upload config (mediaLibrary.serviceUploads), read in setup by the caller. */
+    /** Public upload config, read in setup by the caller: where service-upload parts go, and the backend registry. */
     service?: {
         baseURL?: string;
-        backends?: Record<string, ServiceUploadBackend>;
+        backends?: MediaBackends;
     };
     context?: MediaUploadContext | null;
 }
@@ -25,6 +25,8 @@ export declare function useMLUploadQueue(): {
     cancelUploads: () => void;
     retryStep: (upload: MediaUpload) => Promise<void>;
     onCreated: (fn: (upload: MediaUpload) => void) => () => boolean;
+    /** Try attaching an orphaned upload at its backend's claim route again. */
+    claim: (upload: MediaUpload) => Promise<void>;
     /** Let the next unload through (the user confirmed it). */
     allowUnload: () => void;
 };

package/dist/runtime/composables/useMLUploadQueue.js

@@ -2,7 +2,7 @@ import { computed, reactive, ref, watch } from "vue";
 import { $fetch } from "ofetch";
 import { ChunkUploader } from "../utils/uploader/uploader.js";
 import { createServiceUpload } from "../utils/uploader/serviceUpload.js";
-import { resolveServiceUpload } from "../utils/uploader/serviceBackends.js";
+import { resolveUploadTarget } from "../utils/backends.js";
 import { kindForFile, mimeForFile } from "../utils/fileAccept.js";
 import { stepLabel, usableAfter } from "../utils/processingSteps.js";
 import { useMLProcessingStatus } from "./useMLProcessingStatus.js";
@@ -14,6 +14,8 @@ function createQueue() {
   const owners = /* @__PURE__ */ new Map();
   const cleanups = /* @__PURE__ */ new Map();
   const createdHandlers = /* @__PURE__ */ new Set();
+  const claimUrls = /* @__PURE__ */ new Map();
+  const claiming = /* @__PURE__ */ new Set();
   const trays = ref(0);
   let allowUnload = false;
   const processing = import.meta.client ? useMLProcessingStatus() : null;
@@ -26,6 +28,7 @@ function createQueue() {
       file,
       kind,
       size: file.size,
+      backend: null,
       service: null,
       profile: null,
       localPreview,
@@ -37,6 +40,7 @@ function createQueue() {
       context,
       attached: false,
       orphaned: false,
+      claimError: null,
       step: null,
       stepIndex: null,
       stepTotal: null,
@@ -170,10 +174,18 @@ function createQueue() {
     const localPreview = isVisual && typeof URL !== "undefined" ? URL.createObjectURL(file) : null;
     const { upload, resolveCreated } = create(file, kind, meta.context ?? null, localPreview);
     upload.profile = opts.profile ?? null;
-    upload.service = typeof opts.service === "string" ? opts.service : opts.service?.start ?? null;
+    upload.service = opts.backend || (typeof opts.service === "string" ? opts.service : opts.service?.start ?? null);
     const cfg = meta.config.proxyUploads ? { ...meta.config, baseURL: "" } : meta.config;
     let uploader = null;
     let serviceRun = null;
+    let target = null;
+    let targetError = null;
+    try {
+      target = resolveUploadTarget(opts.backend, opts.service, meta.service?.backends, opts.serviceBody);
+    } catch (err) {
+      targetError = err;
+    }
+    upload.backend = target?.backend ?? null;
     const onProgress = (p) => {
       upload.progress = p.percent;
     };
@@ -210,9 +222,11 @@ function createQueue() {
       upload.error = null;
       upload.sessionId = null;
       try {
-        const service = resolveServiceUpload(opts.service, meta.service?.backends, opts.serviceBody);
+        if (targetError) throw targetError;
+        const service = target?.service ?? null;
         const { assetId, sessionId } = service ? await uploadViaService(service) : await uploadViaNuxt();
         upload.sessionId = sessionId;
+        claimUrls.set(upload.key, sessionId && target?.claimUrl ? target.claimUrl(sessionId) : null);
         if (!assetId) {
           upload.phase = "failed";
           upload.error = "The upload finished but no file was created";
@@ -222,6 +236,7 @@ function createQueue() {
         upload.assetId = assetId;
         resolveCreated(assetId);
         for (const fn of createdHandlers) fn(upload);
+        if (upload.orphaned) void claim(upload);
         followProcessing(upload, assetId);
       } catch (err) {
         if (upload.phase === "canceled") return;
@@ -255,9 +270,33 @@ function createQueue() {
     owners.get(upload.key)?.delete(owner);
     if (unmounted && !upload.attached && (upload.phase === "uploading" || upload.phase === "processing")) {
       upload.orphaned = true;
+      if (upload.assetId) void claim(upload);
+      persist();
     }
     pruneOrphan(upload);
   }
+  async function claim(upload) {
+    const url = claimUrls.get(upload.key);
+    if (!url || upload.attached || claiming.has(upload.key) || !upload.assetId) return;
+    claiming.add(upload.key);
+    try {
+      await $fetch(url, { method: "POST", body: { assetId: upload.assetId, profile: upload.profile } });
+      upload.attached = true;
+      upload.orphaned = false;
+      upload.claimError = null;
+    } catch (err) {
+      if (err?.statusCode === 409 || err?.status === 409) {
+        upload.attached = true;
+        upload.orphaned = false;
+        upload.claimError = null;
+      } else {
+        upload.claimError = err?.data?.detail ?? err?.data?.message ?? err?.statusMessage ?? err?.message ?? "Could not add the file";
+      }
+    } finally {
+      claiming.delete(upload.key);
+      persist();
+    }
+  }
   function pruneOrphan(upload) {
     const held = owners.get(upload.key)?.size ?? 0;
     const finished = upload.phase === "ready" || upload.phase === "canceled";
@@ -268,6 +307,7 @@ function createQueue() {
     cleanups.get(upload.key)?.();
     cleanups.delete(upload.key);
     owners.delete(upload.key);
+    claimUrls.delete(upload.key);
     items.value = items.value.filter((u) => u.key !== upload.key);
     persist();
   }
@@ -290,7 +330,7 @@ function createQueue() {
   }
   function persist() {
     if (!import.meta.client) return;
-    const stored = items.value.filter((u) => u.phase === "processing" && u.assetId).map((u) => ({ assetId: u.assetId, sessionId: u.sessionId, service: u.service, profile: u.profile, name: u.file.name, kind: u.kind, size: u.size, context: u.context }));
+    const stored = items.value.filter((u) => u.assetId && (u.phase === "processing" || u.orphaned && !u.attached && claimUrls.get(u.key))).map((u) => ({ assetId: u.assetId, sessionId: u.sessionId, backend: u.backend, claimUrl: claimUrls.get(u.key) ?? null, service: u.service, profile: u.profile, name: u.file.name, kind: u.kind, size: u.size, context: u.context }));
     try {
       if (stored.length) sessionStorage.setItem(STORAGE_KEY, JSON.stringify(stored));
       else sessionStorage.removeItem(STORAGE_KEY);
@@ -312,13 +352,20 @@ function createQueue() {
       upload.size = s.size;
       upload.assetId = s.assetId;
       upload.sessionId = s.sessionId ?? null;
+      upload.backend = s.backend ?? null;
       upload.service = s.service ?? null;
       upload.profile = s.profile ?? null;
-      upload.attached = true;
       resolveCreated(s.assetId);
       owners.set(upload.key, /* @__PURE__ */ new Set());
+      claimUrls.set(upload.key, s.claimUrl ?? null);
       items.value = [...items.value, upload];
       followProcessing(upload, s.assetId);
+      if (s.claimUrl) {
+        upload.orphaned = true;
+        void claim(upload);
+      } else {
+        upload.attached = true;
+      }
     }
   }
   if (import.meta.client) {
@@ -341,6 +388,8 @@ function createQueue() {
     cancelUploads,
     retryStep,
     onCreated,
+    /** Try attaching an orphaned upload at its backend's claim route again. */
+    claim,
     /** Let the next unload through (the user confirmed it). */
     allowUnload: () => {
       allowUnload = true;

package/dist/runtime/utils/backends.d.ts

@@ -0,0 +1,63 @@
+import { type MediaServiceUpload, type ServiceUploadBackend, type ServiceUploadChoice } from './uploader/serviceBackends.js';
+/**
+ * Which system a backend is. `media-library`: the current media library,
+ * reached through the module's /api/media-library proxies and media grants.
+ * `media-kit`: an app's own media-kit routes (not supported by this version's
+ * widgets yet; registering one is allowed, using it fails clearly).
+ */
+export type MediaBackendKind = 'media-library' | 'media-kit';
+/**
+ * One entry of `mediaLibrary.backends`: a named place widgets read from and
+ * upload to (`<MLMediaGallery backend="videos" />`). Paths only: each layer
+ * serves its own routes. Paths with `:sessionId` / `:id` get them filled in.
+ */
+export interface MediaBackend {
+    /** Default `media-library`. */
+    kind?: MediaBackendKind;
+    /**
+     * Where uploads start. Without it, a `media-library` backend uploads
+     * through Nuxt's own route (`/api/media-library/manage/uploads`).
+     * `start`: py_client `create_upload_router`'s prefix. `refresh`: its grant
+     * refresh, default `<start>/:sessionId/grant`.
+     */
+    upload?: ServiceUploadBackend;
+    /**
+     * Attach a finished upload: `POST` with `{ assetId, profile }`, e.g.
+     * `/api/videos/uploads/:sessionId/attach` (py_client
+     * `create_upload_router(on_attach=…)`). When set, the upload queue attaches
+     * files whose widget went away before it could (page change), so the app
+     * needs no plugin for them.
+     */
+    claim?: string;
+    /** Planned (media-kit): list, resolve and asset routes. Not used yet; `media-library` backends use the module's proxies. */
+    list?: string;
+    resolve?: string;
+    asset?: string;
+}
+export type MediaBackends = Record<string, MediaBackend>;
+/**
+ * The registry as public config: `backends`, plus the older
+ * `serviceUploads.backends` as `media-library` backends with only `upload`
+ * (an entry in `backends` wins over one of the same name). Invalid entries
+ * are dropped with a warning.
+ */
+export declare function normalizeBackends(backends: MediaBackends | undefined, legacy: Record<string, ServiceUploadBackend> | undefined, warn: (message: string) => void): MediaBackends;
+/** The registry from only the older `serviceUploadBackends` public config (runtime overrides). */
+export declare function legacyBackends(legacy: Record<string, ServiceUploadBackend> | null | undefined): MediaBackends | undefined;
+/** Where an upload goes, resolved from a widget's `backend` (or `service`). */
+export interface ResolvedUploadTarget {
+    /** The registered name, or null (inline `{ start }`, or no backend). */
+    backend: string | null;
+    /** The service that starts the upload, or null for Nuxt's own route. */
+    service: MediaServiceUpload | null;
+    /** The claim URL for this session, when the backend has one. */
+    claimUrl: ((sessionId: string) => string) | null;
+}
+/**
+ * Resolve a widget's `backend` / `service` against the registry. `backend`
+ * wins; `service` is its older name and still takes an inline `{ start }`.
+ * `body` (e.g. `{ context }`) is merged into the start request.
+ *
+ * @throws Error for an unregistered name, or a `media-kit` backend.
+ */
+export declare function resolveUploadTarget(backend: string | null | undefined, service: ServiceUploadChoice, registry: MediaBackends | null | undefined, body?: Record<string, unknown> | null): ResolvedUploadTarget;

package/dist/runtime/utils/backends.js

@@ -0,0 +1,72 @@
+import { resolveServiceUpload } from "./uploader/serviceBackends.js";
+const KINDS = ["media-library", "media-kit"];
+export function normalizeBackends(backends, legacy, warn) {
+  const out = {};
+  const upload = (where, u) => {
+    if (u === void 0) return void 0;
+    if (!u || typeof u.start !== "string" || !u.start) {
+      warn(`${where} has no start path; ignored.`);
+      return null;
+    }
+    if (u.refresh && !u.refresh.includes(":sessionId")) {
+      warn(`${where}.refresh needs a :sessionId placeholder; using the default.`);
+    }
+    return { start: u.start, ...u.refresh?.includes(":sessionId") ? { refresh: u.refresh } : {} };
+  };
+  for (const [name, b] of Object.entries(legacy ?? {})) {
+    const u = upload(`mediaLibrary.serviceUploads.backends.${name}`, b);
+    if (u) out[name] = { kind: "media-library", upload: u };
+  }
+  for (const [name, b] of Object.entries(backends ?? {})) {
+    const where = `mediaLibrary.backends.${name}`;
+    if (!b || typeof b !== "object") {
+      warn(`${where} is not an object; ignored.`);
+      continue;
+    }
+    const kind = b.kind ?? "media-library";
+    if (!KINDS.includes(kind)) {
+      warn(`${where}.kind must be one of ${KINDS.join(", ")}; ignored.`);
+      continue;
+    }
+    const entry = { kind };
+    const u = upload(`${where}.upload`, b.upload);
+    if (u === null) continue;
+    if (u) entry.upload = u;
+    if (b.claim) {
+      if (b.claim.includes(":sessionId")) entry.claim = b.claim;
+      else warn(`${where}.claim needs a :sessionId placeholder; ignored.`);
+    }
+    for (const key of ["list", "resolve", "asset"]) {
+      if (typeof b[key] === "string" && b[key]) entry[key] = b[key];
+    }
+    out[name] = entry;
+  }
+  return out;
+}
+export function legacyBackends(legacy) {
+  return legacy ? normalizeBackends(void 0, legacy, () => {
+  }) : void 0;
+}
+function fill(path, sessionId) {
+  return path.replace(/:sessionId\b|\{sessionId\}/g, encodeURIComponent(sessionId));
+}
+export function resolveUploadTarget(backend, service, registry, body) {
+  const choice = backend || service;
+  if (!choice) return { backend: null, service: null, claimUrl: null };
+  if (typeof choice !== "string") {
+    return { backend: null, service: resolveServiceUpload(choice, null, body), claimUrl: null };
+  }
+  const entry = registry?.[choice];
+  if (!entry) {
+    throw new Error(`No backend '${choice}': add it under mediaLibrary.backends in nuxt.config.`);
+  }
+  if (entry.kind === "media-kit") {
+    throw new Error(`Backend '${choice}' is a media-kit backend; this version of nuxt-media-library cannot upload to media-kit yet.`);
+  }
+  const claim = entry.claim;
+  return {
+    backend: choice,
+    service: entry.upload ? resolveServiceUpload(choice, { [choice]: entry.upload }, body) : null,
+    claimUrl: claim ? (sessionId) => fill(claim, sessionId) : null
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-media-library",
-  "version": "0.0.57",
+  "version": "0.0.58",
   "description": "Nuxt module for media library management — chunked uploads, asset previews, and resource policies",
   "repository": {
     "type": "git",
@@ -38,6 +38,8 @@
     "dev": "yarn dev:prepare && nuxi dev playground",
     "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxi prepare playground",
     "build": "nuxt build playground",
+    "docs:dev": "nuxt-module-build prepare && nuxi dev docs",
+    "docs:generate": "nuxt-module-build prepare && nuxi generate docs",
     "admin:dev": "yarn dev:prepare && yarn --cwd admin-playground dev",
     "prepack": "nuxt-module-build build",
     "lint": "eslint .",
@@ -74,6 +76,7 @@
     "dashjs": "^5.1.1",
     "eslint": "^9.39.2",
     "hls.js": "^1.6.16",
+    "msw": "2.15.0",
     "nuxt": "^4.2.2",
     "sirv": "^3.0.1",
     "typescript": "~5.9.3",