@byline/admin 3.17.1 → 3.19.0

package/dist/vendor/noble-argon2/blake2.js

@@ -1,7 +1,7 @@
 import { BSIGMA, G1s, G2s } from "./_blake.js";
 import { SHA256_IV } from "./_md.js";
 import { abytes, aexists, anumber, aoutput, clean, createHasher, swap32IfBE, swap8IfBE, u32 } from "./utils.js";
-import * as __rspack_external__u64_js_3c1fe104 from "./_u64.js";
+import * as __rspack_external__u64_js_5917676b from "./_u64.js";
 const B2B_IV = /* @__PURE__ */ Uint32Array.from([
     0xf3bcc908,
     0x6a09e667,
@@ -27,25 +27,25 @@ function G1b(a, b, c, d, msg, x) {
     let Bl = BBUF[2 * b], Bh = BBUF[2 * b + 1];
     let Cl = BBUF[2 * c], Ch = BBUF[2 * c + 1];
     let Dl = BBUF[2 * d], Dh = BBUF[2 * d + 1];
-    let ll = __rspack_external__u64_js_3c1fe104.add3L(Al, Bl, Xl);
-    Ah = __rspack_external__u64_js_3c1fe104.add3H(ll, Ah, Bh, Xh);
+    let ll = __rspack_external__u64_js_5917676b.add3L(Al, Bl, Xl);
+    Ah = __rspack_external__u64_js_5917676b.add3H(ll, Ah, Bh, Xh);
     Al = 0 | ll;
     ({ Dh, Dl } = {
         Dh: Dh ^ Ah,
         Dl: Dl ^ Al
     });
     ({ Dh, Dl } = {
-        Dh: __rspack_external__u64_js_3c1fe104.rotr32H(Dh, Dl),
-        Dl: __rspack_external__u64_js_3c1fe104.rotr32L(Dh, Dl)
+        Dh: __rspack_external__u64_js_5917676b.rotr32H(Dh, Dl),
+        Dl: __rspack_external__u64_js_5917676b.rotr32L(Dh, Dl)
     });
-    ({ h: Ch, l: Cl } = __rspack_external__u64_js_3c1fe104.add(Ch, Cl, Dh, Dl));
+    ({ h: Ch, l: Cl } = __rspack_external__u64_js_5917676b.add(Ch, Cl, Dh, Dl));
     ({ Bh, Bl } = {
         Bh: Bh ^ Ch,
         Bl: Bl ^ Cl
     });
     ({ Bh, Bl } = {
-        Bh: __rspack_external__u64_js_3c1fe104.rotrSH(Bh, Bl, 24),
-        Bl: __rspack_external__u64_js_3c1fe104.rotrSL(Bh, Bl, 24)
+        Bh: __rspack_external__u64_js_5917676b.rotrSH(Bh, Bl, 24),
+        Bl: __rspack_external__u64_js_5917676b.rotrSL(Bh, Bl, 24)
     });
     BBUF[2 * a] = Al, BBUF[2 * a + 1] = Ah;
     BBUF[2 * b] = Bl, BBUF[2 * b + 1] = Bh;
@@ -58,25 +58,25 @@ function G2b(a, b, c, d, msg, x) {
     let Bl = BBUF[2 * b], Bh = BBUF[2 * b + 1];
     let Cl = BBUF[2 * c], Ch = BBUF[2 * c + 1];
     let Dl = BBUF[2 * d], Dh = BBUF[2 * d + 1];
-    let ll = __rspack_external__u64_js_3c1fe104.add3L(Al, Bl, Xl);
-    Ah = __rspack_external__u64_js_3c1fe104.add3H(ll, Ah, Bh, Xh);
+    let ll = __rspack_external__u64_js_5917676b.add3L(Al, Bl, Xl);
+    Ah = __rspack_external__u64_js_5917676b.add3H(ll, Ah, Bh, Xh);
     Al = 0 | ll;
     ({ Dh, Dl } = {
         Dh: Dh ^ Ah,
         Dl: Dl ^ Al
     });
     ({ Dh, Dl } = {
-        Dh: __rspack_external__u64_js_3c1fe104.rotrSH(Dh, Dl, 16),
-        Dl: __rspack_external__u64_js_3c1fe104.rotrSL(Dh, Dl, 16)
+        Dh: __rspack_external__u64_js_5917676b.rotrSH(Dh, Dl, 16),
+        Dl: __rspack_external__u64_js_5917676b.rotrSL(Dh, Dl, 16)
     });
-    ({ h: Ch, l: Cl } = __rspack_external__u64_js_3c1fe104.add(Ch, Cl, Dh, Dl));
+    ({ h: Ch, l: Cl } = __rspack_external__u64_js_5917676b.add(Ch, Cl, Dh, Dl));
     ({ Bh, Bl } = {
         Bh: Bh ^ Ch,
         Bl: Bl ^ Cl
     });
     ({ Bh, Bl } = {
-        Bh: __rspack_external__u64_js_3c1fe104.rotrBH(Bh, Bl, 63),
-        Bl: __rspack_external__u64_js_3c1fe104.rotrBL(Bh, Bl, 63)
+        Bh: __rspack_external__u64_js_5917676b.rotrBH(Bh, Bl, 63),
+        Bl: __rspack_external__u64_js_5917676b.rotrBL(Bh, Bl, 63)
     });
     BBUF[2 * a] = Al, BBUF[2 * a + 1] = Ah;
     BBUF[2 * b] = Bl, BBUF[2 * b + 1] = Bh;
@@ -226,7 +226,7 @@ class _BLAKE2b extends _BLAKE2 {
     compress(msg, offset, isLast) {
         this.get().forEach((v, i)=>BBUF[i] = v);
         BBUF.set(B2B_IV, 16);
-        let { h, l } = __rspack_external__u64_js_3c1fe104.fromBig(BigInt(this.length));
+        let { h, l } = __rspack_external__u64_js_5917676b.fromBig(BigInt(this.length));
         BBUF[24] = B2B_IV[8] ^ l;
         BBUF[25] = B2B_IV[9] ^ h;
         if (isLast) {
@@ -376,7 +376,7 @@ class _BLAKE2s extends _BLAKE2 {
         this.v7 = 0 | v7;
     }
     compress(msg, offset, isLast) {
-        const { h, l } = __rspack_external__u64_js_3c1fe104.fromBig(BigInt(this.length));
+        const { h, l } = __rspack_external__u64_js_5917676b.fromBig(BigInt(this.length));
         const { v0, v1, v2, v3, v4, v5, v6, v7, v8, v9, v10, v11, v12, v13, v14, v15 } = compress(BSIGMA, offset, msg, 10, this.v0, this.v1, this.v2, this.v3, this.v4, this.v5, this.v6, this.v7, B2S_IV[0], B2S_IV[1], B2S_IV[2], B2S_IV[3], l ^ B2S_IV[4], h ^ B2S_IV[5], isLast ? ~B2S_IV[6] : B2S_IV[6], B2S_IV[7]);
         this.v0 ^= v0 ^ v8;
         this.v1 ^= v1 ^ v9;

package/dist/widgets/source-locale-badge/source-locale-badge.d.ts

@@ -10,21 +10,7 @@ export interface SourceLocaleBadgeProps {
     locale: string;
     className?: string;
 }
-/**
- * Small neutral badge indicating a document's content **source locale** — the
- * locale it was authored in (its anchor: fallback floor, path locale,
- * completeness yardstick). Rendered next to the document title in the edit and
- * list views. Mirrors the localized-field {@link LocaleBadge} in spirit but uses
- * the shared {@link Badge} with the `noeffect` (neutral) intent.
- *
- * NOTE: currently rendered for *every* document so the anchor is visible during
- * development. The intended end state is to show it only when `locale` differs
- * from the system's current default content locale (a normal single-default
- * install then shows nothing). See docs/07-internationalization/index.md.
- *
- * Stable override handle: `.byline-source-locale-badge`.
- */
-export declare const SourceLocaleBadge: {
-    ({ locale, className }: SourceLocaleBadgeProps): import("react").JSX.Element;
-    displayName: string;
-};
+export declare function SourceLocaleBadge({ locale, className }: SourceLocaleBadgeProps): import("react").JSX.Element;
+export declare namespace SourceLocaleBadge {
+    var displayName: string;
+}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/admin",
   "private": false,
   "license": "MPL-2.0",
-  "version": "3.17.1",
+  "version": "3.19.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -153,31 +153,31 @@
     "classnames": "^2.5.1",
     "jose": "^6.2.3",
     "react-diff-viewer-continued": "^4.2.2",
-    "uuid": "^14.0.0",
+    "uuid": "^14.0.1",
     "zod": "^4.4.3",
-    "@byline/auth": "3.17.1",
-    "@byline/i18n": "3.17.1",
-    "@byline/ui": "3.17.1",
-    "@byline/core": "3.17.1"
+    "@byline/auth": "3.19.0",
+    "@byline/ui": "3.19.0",
+    "@byline/core": "3.19.0",
+    "@byline/i18n": "3.19.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.4.15",
-    "@rsbuild/plugin-react": "^2.0.0",
-    "@rslib/core": "^0.21.5",
-    "@types/node": "^25.9.1",
-    "@types/react": "19.2.15",
+    "@biomejs/biome": "2.5.2",
+    "@rsbuild/plugin-react": "^2.1.0",
+    "@rslib/core": "^0.23.2",
+    "@types/node": "^26.1.0",
+    "@types/react": "19.2.17",
     "@types/react-dom": "19.2.3",
-    "react": "19.2.6",
-    "react-dom": "19.2.6",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
     "rimraf": "^6.1.3",
-    "tsx": "^4.22.3",
-    "typescript": "6.0.3",
+    "tsx": "^4.23.0",
+    "typescript": "^7.0.2",
     "typescript-plugin-css-modules": "^5.2.0",
-    "vitest": "^4.1.7"
+    "vitest": "^4.1.10"
   },
   "publishConfig": {
     "access": "public",

package/src/fields/file/file-field.tsx

@@ -79,7 +79,7 @@ export const FileField = ({
   const isDirty = useIsDirty(fieldPath)
   const fieldValue = useFieldValue<StoredFileValue | null | undefined>(fieldPath)
   const isUploading = useIsFieldUploading(fieldPath)
-  const { removePendingUpload } = useFormContext()
+  const { removePendingUpload, documentId } = useFormContext()
 
   const handleChange = useFieldChangeHandler(field, fieldPath)
 
@@ -102,6 +102,12 @@ export const FileField = ({
 
   const showUploadWidget = incomingValue == null || isOldPlaceholder(incomingValue)
 
+  // `upload.requireSavedDocument` gate: until the document is persisted,
+  // render a "save first" notice in place of the upload zone. Server-side
+  // upload hooks that depend on save-time state (counters, document id)
+  // rely on this; existing stored values still render normally below.
+  const uploadGated = field.upload?.requireSavedDocument === true && documentId == null
+
   const handleRemove = () => {
     if (isPending) {
       removePendingUpload(fieldPath)
@@ -131,7 +137,15 @@ export const FileField = ({
       </div>
 
       {showUploadWidget ? (
-        collectionPath ? (
+        uploadGated ? (
+          <div
+            className={cx('byline-field-file-empty', styles.empty)}
+            role="note"
+            data-testid="upload-require-saved-document"
+          >
+            {t('fields.upload.requireSavedDocument')}
+          </div>
+        ) : collectionPath ? (
           <FileUploadField
             field={field}
             collectionPath={collectionPath}

package/src/fields/image/image-field.tsx

@@ -61,7 +61,7 @@ export const ImageField = ({
   const isDirty = useIsDirty(fieldPath)
   const fieldValue = useFieldValue<StoredFileValue | null | undefined>(fieldPath)
   const isUploading = useIsFieldUploading(fieldPath)
-  const { removePendingUpload } = useFormContext()
+  const { removePendingUpload, documentId } = useFormContext()
   const { t } = useTranslation('byline-admin')
 
   // Re-use the standard field change handler so patches are emitted correctly.
@@ -87,6 +87,12 @@ export const ImageField = ({
   // Show upload widget only if no value or old placeholder
   const showUploadWidget = incomingValue == null || isOldPlaceholder(incomingValue)
 
+  // `upload.requireSavedDocument` gate: until the document is persisted,
+  // render a "save first" notice in place of the upload zone. Server-side
+  // upload hooks that depend on save-time state (counters, document id)
+  // rely on this; existing stored values still render normally below.
+  const uploadGated = field.upload?.requireSavedDocument === true && documentId == null
+
   // Prefer the generated thumbnail variant for the preview tile. SVGs and
   // other bypass types have no variants — fall back to the original.
   const thumbVariant =
@@ -122,7 +128,15 @@ export const ImageField = ({
       </div>
 
       {showUploadWidget ? (
-        collectionPath ? (
+        uploadGated ? (
+          <div
+            className={cx('byline-field-image-empty', styles.empty)}
+            role="note"
+            data-testid="upload-require-saved-document"
+          >
+            {t('fields.upload.requireSavedDocument')}
+          </div>
+        ) : collectionPath ? (
           <ImageUploadField
             field={field}
             collectionPath={collectionPath}

package/src/forms/form-context.tsx

@@ -83,6 +83,13 @@ const SYSTEM_PATH_DIRTY_KEY = '__systemPath__'
 const SYSTEM_AVAILABLE_LOCALES_DIRTY_KEY = '__systemAvailableLocales__'
 
 interface FormContextType {
+  /**
+   * The persisted document id when the form edits an existing document,
+   * `null` while the document is unsaved (create mode). Upload widgets use
+   * this to honour `upload.requireSavedDocument` (see `UploadConfig` in
+   * `@byline/core`).
+   */
+  documentId: string | null
   setFieldValue: (name: string, value: any) => void
   setFieldStore: (name: string, value: any) => void
   getFieldValue: (name: string) => any
@@ -150,9 +157,15 @@ export const useFormContext = () => {
 export const FormProvider = ({
   children,
   initialData = {},
+  documentId = null,
 }: {
   children: React.ReactNode
   initialData?: Record<string, any>
+  /**
+   * The persisted document id (edit mode); `null` while unsaved. Exposed on
+   * the context for upload widgets honouring `upload.requireSavedDocument`.
+   */
+  documentId?: string | null
 }) => {
   const fieldValues = useRef<Record<string, any>>(
     JSON.parse(JSON.stringify(initialData?.fields ?? initialData))
@@ -640,6 +653,7 @@ export const FormProvider = ({
   return (
     <FormContext.Provider
       value={{
+        documentId,
         setFieldValue,
         setFieldStore,
         getFieldValue,

package/src/forms/form-renderer.tsx

@@ -18,6 +18,7 @@ import type {
   TabSetDefinition,
   WorkflowStatus,
 } from '@byline/core'
+import { getClientConfig } from '@byline/core'
 import type { DocumentPatch } from '@byline/core/patches'
 import { useTranslation } from '@byline/i18n/react'
 import { Alert, Button, ComboButton } from '@byline/ui/react'
@@ -241,6 +242,19 @@ const FormContent = ({
   const [contentLocale, setContentLocale] = useState(initialLocale ?? defaultLocale)
   const { uploadField } = useBylineFieldServices()
 
+  // Path-widget wiring. The live preview must use the installation's
+  // client-side slugifier (same function as `ServerConfig.slugifier`) so it
+  // agrees with the persisted path. And when the `useAsPath` source is a
+  // server-assigned `counter` or a read-only field, its value can't be
+  // reproduced or changed through the form, so the widget suppresses its
+  // source-derived preview and "Regenerate" affordance.
+  const pathSlugifier = getClientConfig().slugifier
+  const pathSourceLocked = useMemo(() => {
+    if (!useAsPath) return false
+    const source = fields.find((f) => f.name === useAsPath)
+    return source != null && (source.type === 'counter' || source.readOnly === true)
+  }, [useAsPath, fields])
+
   // Sync contentLocale when the route re-fetches with a different locale.
   useEffect(() => {
     if (initialLocale) setContentLocale(initialLocale)
@@ -373,6 +387,16 @@ const FormContent = ({
             uploadField,
             ({ fieldPath, status }) => {
               setFieldUploading(fieldPath, status === 'uploading')
+            },
+            {
+              // Document context for server-side upload hooks: the persisted
+              // document id (edit mode only) plus any `upload.context` form
+              // values declared on the schema field. See UploadConfig.context
+              // in @byline/core.
+              documentId:
+                mode === 'edit' && typeof initialData?.id === 'string' ? initialData.id : undefined,
+              fields,
+              getFormValues: getFieldValues,
             }
           )
 
@@ -672,6 +696,8 @@ const FormContent = ({
               defaultLocale={defaultLocale}
               activeLocale={contentLocale}
               mode={mode}
+              slugifier={pathSlugifier}
+              sourceLocked={pathSourceLocked}
             />
           )}
           {tree && mode === 'edit' && typeof initialData?.id === 'string' && (
@@ -749,6 +775,7 @@ export const FormRenderer = ({
     <FormProvider
       key={`${initialLocale ?? 'default'}-${initialData?.versionId ?? ''}`}
       initialData={initialData}
+      documentId={mode === 'edit' && typeof initialData?.id === 'string' ? initialData.id : null}
     >
       <FormContent
         mode={mode}

package/src/forms/path-widget.test.tsx

@@ -105,6 +105,9 @@ describe('PathWidget', () => {
     props: Partial<{
       useAsPath: string | undefined
       mode: 'create' | 'edit'
+      activeLocale: string
+      slugifier: (value: string, ctx: { locale: string; collectionPath: string }) => string
+      sourceLocked: boolean
     }> = {}
   ) => {
     act(() => {
@@ -113,7 +116,10 @@ describe('PathWidget', () => {
           useAsPath={props.useAsPath ?? 'title'}
           collectionPath="pages"
           defaultLocale="en"
+          activeLocale={props.activeLocale ?? 'en'}
           mode={props.mode ?? 'create'}
+          slugifier={props.slugifier}
+          sourceLocked={props.sourceLocked}
         />
       )
     })
@@ -214,4 +220,31 @@ describe('PathWidget', () => {
     render({ mode: 'edit', useAsPath: undefined })
     expect(container.querySelector('button')).toBeNull()
   })
+
+  it('derives the preview with the provided slugifier instead of the default', () => {
+    // A custom slugifier that zero-pads a numeric serial to 7 digits — the
+    // shape used when a `counter` field feeds the path.
+    const padSerial = (value: string) => value.padStart(7, '0')
+    setFixture({ systemPath: null, sourceValue: 1 })
+    render({ mode: 'create', slugifier: padSerial })
+
+    const input = getInput()
+    // Default slugify would yield "1"; the custom slugifier yields "0000001".
+    expect(input.getAttribute('placeholder')).toBe('Will be saved as "0000001"')
+  })
+
+  it('suppresses the create-mode placeholder preview when the source is locked', () => {
+    setFixture({ systemPath: null, sourceValue: 1 })
+    render({ mode: 'create', sourceLocked: true })
+    expect(getInput().getAttribute('placeholder')).toBeNull()
+  })
+
+  it('suppresses the Regenerate button when the source is locked', () => {
+    // Persisted path differs from what a naive re-derivation would produce,
+    // which would normally surface Regenerate — but a locked (server-assigned)
+    // source can't be regenerated from the form, so it must stay hidden.
+    setFixture({ systemPath: '0000001', sourceValue: 1 })
+    render({ mode: 'edit', sourceLocked: true })
+    expect(container.querySelector('button')).toBeNull()
+  })
 })

package/src/forms/path-widget.tsx

@@ -10,6 +10,7 @@
 
 import { useCallback, useMemo } from 'react'
 
+import type { SlugifierFn } from '@byline/core'
 import { slugify } from '@byline/core'
 import { useTranslation } from '@byline/i18n/react'
 import { Input, Label } from '@byline/ui/react'
@@ -47,6 +48,23 @@ export interface PathWidgetProps {
   activeLocale: string
   /** `'create'` shows the live derived preview as placeholder text. */
   mode: 'create' | 'edit'
+  /**
+   * Installation slugifier used to derive the live preview. Must match the
+   * server-side `ServerConfig.slugifier` so the preview agrees with what is
+   * persisted. Defaults to the built-in `slugify` when omitted — callers
+   * that keep the default slugifier need not pass this.
+   */
+  slugifier?: SlugifierFn
+  /**
+   * When `true`, the `useAsPath` source field's value is not editable through
+   * this form (e.g. it is an allocator-assigned `counter`, or an otherwise
+   * read-only field). Its value is either server-assigned — and so not
+   * reproducible client-side — or simply cannot change, which means the
+   * source-derived live preview and the "Regenerate" affordance are
+   * meaningless. When set, the widget suppresses both and just shows the
+   * persisted path. Defaults to `false`.
+   */
+  sourceLocked?: boolean
 }
 
 /**
@@ -71,12 +89,20 @@ export const PathWidget = ({
   defaultLocale,
   activeLocale,
   mode,
+  slugifier,
+  sourceLocked = false,
 }: PathWidgetProps) => {
   const { setSystemPath } = useFormContext()
   const { t } = useTranslation('byline-admin')
   const systemPath = useSystemPath()
   const sourceValue = useFieldValue<unknown>(useAsPath ?? '')
 
+  // The installation slugifier, or the built-in default. Server-side path
+  // derivation uses `ServerConfig.slugifier`; this must be the same function
+  // (registered via `ClientConfig.slugifier`) or the preview will disagree
+  // with what the server persists.
+  const runSlugify = slugifier ?? slugify
+
   // Phase 1: paths are written/edited only under the default content
   // locale. When editing a translation, the widget locks down — the
   // input is read-only, the Regenerate action is suppressed, and a
@@ -87,11 +113,13 @@ export const PathWidget = ({
   // field value if no override were set. Used as placeholder in create
   // mode and as the target of the "Regenerate" action.
   const livePreview = useMemo(() => {
-    if (!useAsPath) return ''
+    // A locked source (server-assigned counter / read-only field) can't be
+    // previewed or regenerated from the form — suppress the derivation.
+    if (!useAsPath || sourceLocked) return ''
     const asString = coerceToString(sourceValue)
     if (asString.length === 0) return ''
-    return slugify(asString, { locale: defaultLocale, collectionPath })
-  }, [useAsPath, sourceValue, defaultLocale, collectionPath])
+    return runSlugify(asString, { locale: defaultLocale, collectionPath })
+  }, [useAsPath, sourceLocked, sourceValue, defaultLocale, collectionPath, runSlugify])
 
   const inputValue = systemPath ?? ''
 
@@ -115,8 +143,8 @@ export const PathWidget = ({
   // field-hook advisory behaviour).
   const formatted = useMemo(() => {
     if (inputValue.length === 0) return ''
-    return slugify(inputValue, { locale: defaultLocale, collectionPath })
-  }, [inputValue, defaultLocale, collectionPath])
+    return runSlugify(inputValue, { locale: defaultLocale, collectionPath })
+  }, [inputValue, defaultLocale, collectionPath, runSlugify])
 
   const validationHint =
     inputValue.length > 0 && formatted !== inputValue

package/src/forms/upload-executor.test.node.ts

@@ -0,0 +1,176 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import type { Field } from '@byline/core'
+import { describe, expect, it, vi } from 'vitest'
+
+import { executeUploads } from './upload-executor'
+import type { PendingUpload } from './form-context'
+
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+
+/** Schema mirroring the publications files-array shape. */
+const publicationsFields: Field[] = [
+  { name: 'title', label: 'Title', type: 'text' },
+  { name: 'serialNumber', label: 'Serial', type: 'counter', group: 'test-serial' },
+  {
+    name: 'files',
+    label: 'Files',
+    type: 'array',
+    fields: [
+      {
+        name: 'filesGroup',
+        type: 'group',
+        fields: [
+          {
+            name: 'publicationFile',
+            label: 'File',
+            type: 'file',
+            upload: {
+              mimeTypes: ['application/pdf'],
+              context: ['language', '/serialNumber', '../missingSibling'],
+            },
+          },
+          {
+            name: 'language',
+            label: 'Language',
+            type: 'relation',
+            targetCollection: 'languages',
+          },
+        ],
+      },
+    ],
+  },
+  {
+    name: 'cover',
+    label: 'Cover',
+    type: 'image',
+    upload: { mimeTypes: ['image/*'] },
+  },
+]
+
+function pendingUpload(name = 'test.pdf'): PendingUpload {
+  return {
+    file: new File(['%PDF'], name, { type: 'application/pdf' }),
+    previewUrl: 'blob:mock',
+    collectionPath: 'publications',
+  }
+}
+
+/** Capture the FormData each call receives; echo a minimal result. */
+function captureUploadField() {
+  const bodies: FormData[] = []
+  const fn = vi.fn(async (_collection: string, formData: FormData) => {
+    bodies.push(formData)
+    return { storedFile: { fileId: '1', filename: 'stored.pdf' } as any }
+  })
+  return { fn, bodies }
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('executeUploads — context transmission', () => {
+  it('always sends field (leaf name) and fieldPath; documentId only when provided', async () => {
+    const { fn, bodies } = captureUploadField()
+    const uploads = new Map([['files[0].filesGroup.publicationFile', pendingUpload()]])
+
+    await executeUploads(uploads, fn, {
+      documentId: 'doc-123',
+      fields: publicationsFields,
+      getFormValues: () => ({}),
+    })
+
+    const body = bodies[0]!
+    expect(body.get('field')).toBe('publicationFile')
+    expect(body.get('fieldPath')).toBe('files[0].filesGroup.publicationFile')
+    expect(body.get('documentId')).toBe('doc-123')
+  })
+
+  it('omits documentId in create mode (undefined)', async () => {
+    const { fn, bodies } = captureUploadField()
+    const uploads = new Map([['cover', pendingUpload('c.png')]])
+
+    await executeUploads(uploads, fn, { fields: publicationsFields, getFormValues: () => ({}) })
+
+    expect(bodies[0]?.get('documentId')).toBeNull()
+  })
+
+  it('resolves sibling, root-absolute, and missing context paths against the item scope', async () => {
+    const { fn, bodies } = captureUploadField()
+    const uploads = new Map([['files[1].filesGroup.publicationFile', pendingUpload()]])
+
+    await executeUploads(uploads, fn, {
+      documentId: 'doc-123',
+      fields: publicationsFields,
+      getFormValues: () => ({
+        serialNumber: 447,
+        files: [
+          { filesGroup: { language: { targetDocumentId: 'lang-th', targetCollectionId: 'c' } } },
+          { filesGroup: { language: { targetDocumentId: 'lang-en', targetCollectionId: 'c' } } },
+        ],
+      }),
+    })
+
+    const body = bodies[0]!
+    // Sibling path reads THIS item's language, not item 0's.
+    expect(body.get('language')).toBe('lang-en')
+    // Root-absolute path.
+    expect(body.get('serialNumber')).toBe('447')
+    // Unresolvable context values are omitted, not sent as ''.
+    expect(body.get('missingSibling')).toBeNull()
+  })
+
+  it('serialises relation envelopes to their targetDocumentId', async () => {
+    const { fn, bodies } = captureUploadField()
+    const uploads = new Map([['files[0].filesGroup.publicationFile', pendingUpload()]])
+
+    await executeUploads(uploads, fn, {
+      fields: publicationsFields,
+      getFormValues: () => ({
+        serialNumber: 1,
+        files: [
+          { filesGroup: { language: { targetDocumentId: 'lang-de', targetCollectionId: 'c' } } },
+        ],
+      }),
+    })
+
+    expect(bodies[0]?.get('language')).toBe('lang-de')
+  })
+
+  it('fields without upload.context send no extra entries', async () => {
+    const { fn, bodies } = captureUploadField()
+    const uploads = new Map([['cover', pendingUpload('c.png')]])
+
+    await executeUploads(uploads, fn, {
+      documentId: 'doc-9',
+      fields: publicationsFields,
+      getFormValues: () => ({ serialNumber: 5 }),
+    })
+
+    const body = bodies[0]!
+    expect(body.get('field')).toBe('cover')
+    expect(body.get('serialNumber')).toBeNull()
+  })
+
+  it('works without an execution context (legacy call shape)', async () => {
+    const { fn, bodies } = captureUploadField()
+    const uploads = new Map([['cover', pendingUpload('c.png')]])
+
+    const result = await executeUploads(uploads, fn)
+
+    expect(result.allSucceeded).toBe(true)
+    const body = bodies[0]!
+    expect(body.get('field')).toBe('cover')
+    expect(body.get('fieldPath')).toBe('cover')
+    expect(body.get('documentId')).toBeNull()
+  })
+})