@panphora/hyper-cms 0.7.1 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panphora/hyper-cms",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "Live edit-in-place CMS sidebar for HTML pages with a hyper-html-api rules tag",
   "keywords": [
     "HTML",
@@ -44,8 +44,8 @@
     "test:all": "npm run test:node && npm run test:browser"
   },
   "dependencies": {
-    "hyper-html-api": "^0.6.1",
-    "hyper-morph": "^0.4.0"
+    "hyper-html-api": "^0.6.4",
+    "hyper-morph": "^0.5.0"
   },
   "devDependencies": {
     "@open-wc/testing": "^4.0.0",

package/src/events.js

@@ -190,7 +190,12 @@ async function maybeCrop(file, fieldEl) {
   const crop = platform('quickcrop')
   if (typeof crop !== 'function') return { file }
   try {
-    const r = await crop(file, { aspect: parseCropAspect(attr), ...CROP_OUTPUT })
+    // QuickCrop's `auto` modal adapter looks only at window.themodal. clayjs
+    // attaches its dialog as clay.modal and deliberately sets no global, so a
+    // clayjs page would silently get QuickCrop's own plain dialog. Naming it here
+    // keeps QuickCrop free of client knowledge and clayjs free of the global.
+    const modal = (typeof window !== 'undefined' && (window.clay?.modal ?? window.themodal)) || 'auto'
+    const r = await crop(file, { aspect: parseCropAspect(attr), modal, ...CROP_OUTPUT })
     if (r === null) return null
     return { file: blobToFile(r.blob, file.name), dataURL: r.dataURL }
   } catch (err) {
@@ -212,8 +217,8 @@ export function parseCropAspect(value) {
   return w / h
 }
 
-// quickcrop returns a nameless Blob; uploadFileBasic rejects raw Blobs and the
-// server keys content-type off the filename extension, so wrap it as a File
+// quickcrop returns a nameless Blob; the legacy uploader rejects raw Blobs and a
+// host keys content-type off the filename extension, so wrap it as a File
 // whose extension matches the encoded mime. Exported for tests.
 export function blobToFile(blob, originalName) {
   const ext = blob.type === 'image/webp' ? '.webp' : blob.type === 'image/jpeg' ? '.jpg' : '.png'
@@ -225,11 +230,25 @@ export function blobToFile(blob, originalName) {
   }
 }
 
-// A file was picked in an @file/@image widget. Optionally crop, upload via the
-// host's uploadFileBasic (or fall back to a local object-URL preview), write the
-// resulting URL into the bound img.src / a.href leaf, then commit once. The leaf
-// attribute change is an observed page mutation, so undo gets a clean step with
-// no commitWithUndo. Async; failures surface inline and reset the picker.
+// A file was picked in an @file/@image widget. Optionally crop, ask the host to
+// store the file, write the resulting URL into the bound img.src / a.href leaf,
+// then commit once. The leaf attribute change is an observed page mutation, so
+// undo gets a clean step with no commitWithUndo. Async; failures surface inline
+// and reset the picker.
+//
+// The upload either stores the file or it does not, and those are not the same
+// as success and failure. Three outcomes, deliberately spelled out:
+//
+//   stored             write the served URL. The page carries a reference.
+//   cannot store here  embed the bytes. A document open from a plain file server
+//                      or a desktop app has nowhere to put a file, and embedding
+//                      is the RIGHT answer there, not a consolation prize.
+//   failed             write nothing. Embedding a file the host refused for size
+//                      or type is the disease this capability exists to cure: it
+//                      is how a 2 MB photo ends up in the document, in every
+//                      future save, and in every stored version.
+const EMBED_CODES = new Set(['unsupported', 'payment-required'])
+
 export async function onUploadChange(inputEl, ctx) {
   const file = inputEl.files && inputEl.files[0]
   if (!file) return
@@ -246,39 +265,112 @@ export async function onUploadChange(inputEl, ctx) {
   const fileLike = cropped.file
   const previewDataUrl = cropped.dataURL || null
 
-  const upload = platform('uploadFileBasic')
-  let url = null
-  if (typeof upload === 'function') {
-    try {
-      const res = await upload(fileLike)
-      // uploadFileBasic resolves the full envelope { uploads:[{name,nodeId,url}], … };
-      // the served URL is uploads[0].url, NOT res.url.
-      url = res && res.uploads && res.uploads[0] && res.uploads[0].url
-    } catch (err) {
-      if (ctx.closed) { resetPicker(inputEl); return }
-      showFieldUploadError(fieldEl, (err && err.message) || 'Upload failed')
-      ctx.dispatch?.('hcms:error', { error: err, path: pathStr })
-      resetPicker(inputEl)
-      return
-    }
+  const upload = platform('upload')
+  if (typeof upload !== 'function') {
+    // No client at all: a bare HTML file with the CMS dropped in. Same outcome as
+    // a host that answers `unsupported`, and silent for the same reason.
+    return finishUpload(inputEl, fieldEl, ctx, pathStr, await embedUrl(fileLike, previewDataUrl, fieldEl), fileLike)
+  }
+
+  // The crop, shown immediately on the thumb's own chrome and NOT on the bound
+  // leaf. Writing a two-megabyte data URL to the leaf makes it the field's value,
+  // and any commit() landing while the upload is in flight would project it
+  // straight into the live page.
+  showFieldUploadPreview(fieldEl, previewDataUrl)
+  setUploadProgress(fieldEl, 0)
+
+  const controller = beginUpload(ctx)
+  let res
+  try {
+    res = await upload(fileLike, {
+      signal: controller?.signal,
+      onProgress: ({ percent }) => setUploadProgress(fieldEl, percent),
+    })
+  } finally {
+    endUpload(ctx, controller)
+    clearUploadProgress(fieldEl)
   }
+
   // The editor may have been closed while the upload was in flight; bail before
   // writing the (now detached) form leaf or committing to the live page.
   if (ctx.closed) { resetPicker(inputEl); return }
-  if (!url) {
-    // No host uploader (or it returned nothing): local preview only, which the
-    // commit persists into the page as a blob:/data: URL — non-persistent, by
-    // design (documented), so the widget still works in a bare page / demo.
-    url = previewDataUrl || makeLocalPreviewUrl(fileLike)
+  if (res.code === 'aborted') { resetPicker(inputEl); return }
+
+  if (res.ok) {
+    return finishUpload(inputEl, fieldEl, ctx, pathStr, res.uploads[0].url, fileLike)
   }
-  if (!url) { resetPicker(inputEl); return }
 
+  if (!EMBED_CODES.has(res.code)) {
+    showFieldUploadError(fieldEl, res.msg || 'Upload failed')
+    ctx.dispatch?.('hcms:error', { error: new Error(res.msg || 'Upload failed'), code: res.code, path: pathStr })
+    resetPicker(inputEl)
+    return
+  }
+
+  // Embedded, and only `payment-required` says so. A person editing a file on
+  // their own desktop does not need to be told their file is a file; a person on
+  // a host that WOULD store it, for money, is being told why it did not.
+  const note = res.code === 'payment-required'
+    ? 'This file is stored in the page. Add a paid plan to upload files.'
+    : null
+  return finishUpload(inputEl, fieldEl, ctx, pathStr, await embedUrl(fileLike, previewDataUrl, fieldEl), fileLike, note)
+}
+
+// Write the URL into the leaf and commit once. `url` empty (no FileReader, an
+// unreadable file) means there is nothing to write, and writing '' would clear a
+// picture the person already had.
+//
+// The note goes on AFTER the commit, never before: a successful commit calls
+// setError(ctx, null), which clears every inline slot in the form. Writing the
+// note first leaves the person with an embedded file and no explanation of why.
+function finishUpload(inputEl, fieldEl, ctx, pathStr, url, fileLike, note = null) {
+  if (ctx.closed) { resetPicker(inputEl); return }
+  showFieldUploadPreview(fieldEl, null)
   showFieldUploadError(fieldEl, null)
+  if (!url) { resetPicker(inputEl); return }
   writeUploadLeaf(fieldEl, url, fileLike.name)
   commit(extractFormData(ctx), { path: pathStr, structural: false }, ctx)
+  if (note) showFieldUploadError(fieldEl, note, 'info')
   resetPicker(inputEl)
 }
 
+// The crop when there was one, otherwise the file's own bytes. Always a data:
+// URL and never blob:, so both paths degrade identically: a blob: URL is dead the
+// moment the page reloads, so the no-crop path used to commit a picture that
+// looked right until the person came back to it.
+async function embedUrl(fileLike, previewDataUrl, fieldEl) {
+  return previewDataUrl || (await fileToDataUrl(fileLike, fieldEl))
+}
+
+// The FileReader comes from the field's own realm, never from globalThis: a form
+// mounted into another document reads a File belonging to THAT window, and a
+// reader from a different realm rejects it.
+function fileToDataUrl(file, fieldEl) {
+  const Reader = fieldEl?.ownerDocument?.defaultView?.FileReader || globalThis.FileReader
+  if (!Reader) return Promise.resolve('')
+  return new Promise((resolve) => {
+    const reader = new Reader()
+    reader.onload = () => resolve(typeof reader.result === 'string' ? reader.result : '')
+    reader.onerror = () => resolve('')
+    try { reader.readAsDataURL(file) } catch { resolve('') }
+  })
+}
+
+// In-flight uploads hang off the ctx, so close() tears them down the same way it
+// tears down the observer and the undo subscription. Without this the request
+// keeps running after the editor is gone: harmless to the page, because every
+// write is behind a ctx.closed check, but it holds the connection and the bytes.
+function beginUpload(ctx) {
+  if (typeof AbortController !== 'function') return null
+  const controller = new AbortController()
+  ;(ctx.uploads || (ctx.uploads = new Set())).add(controller)
+  return controller
+}
+
+function endUpload(ctx, controller) {
+  if (controller) ctx.uploads?.delete(controller)
+}
+
 // The × on an upload widget. Clears the bound leaf to empty and commits, so the
 // :has()-driven chrome falls back to the empty state. Removes immediately (no
 // consent gate) per the approved design; distinct from the "remove" action,
@@ -319,15 +411,37 @@ function resetPicker(inputEl) {
   try { inputEl.value = '' } catch { /* some inputs reject programmatic clear */ }
 }
 
-function makeLocalPreviewUrl(file) {
-  const U = (typeof URL !== 'undefined' && URL.createObjectURL) ? URL : null
-  if (!U) return ''
-  try { return U.createObjectURL(file) } catch { return '' }
+// The at-upload-time picture, painted on the frame rather than assigned to the
+// leaf, because the leaf IS the field's value. CSS reveals the thumb while
+// [data-hcms-uploading] is set, so the preview shows even on a field that is
+// still empty.
+function showFieldUploadPreview(fieldEl, dataUrl) {
+  const frame = fieldEl.querySelector ? fieldEl.querySelector('.mirk-image__frame') : null
+  if (!frame) return
+  if (dataUrl) frame.style.backgroundImage = `url("${dataUrl.replace(/"/g, '%22')}")`
+  else frame.style.removeProperty('background-image')
+}
+
+// Progress where the person is looking. The percent drives a CSS custom property
+// rather than any markup of its own, so the templates keep their exact shape and
+// a half-finished upload cannot leave an orphan node behind in the form.
+function setUploadProgress(fieldEl, percent) {
+  const pct = Math.max(0, Math.min(100, Number(percent) || 0))
+  fieldEl.setAttribute('data-hcms-uploading', '')
+  fieldEl.style?.setProperty?.('--hcms-upload-progress', `${pct}%`)
+}
+
+function clearUploadProgress(fieldEl) {
+  fieldEl.removeAttribute('data-hcms-uploading')
+  fieldEl.style?.removeProperty?.('--hcms-upload-progress')
 }
 
-function showFieldUploadError(fieldEl, message) {
+// `kind` distinguishes a refusal from a note: 'info' is the file that WAS stored,
+// in the page, and the slot says why rather than shouting about a failure.
+function showFieldUploadError(fieldEl, message, kind = 'error') {
   const slot = fieldEl.querySelector ? fieldEl.querySelector(':scope > .hcms-error') : null
   if (!slot) return
+  slot.classList.toggle('hcms-error--info', !!message && kind === 'info')
   if (message) {
     slot.textContent = message
     slot.hidden = false
@@ -367,6 +481,7 @@ export function onAdd(arrayPath, ctx) {
     // Component arrays (chips) record their item-template key at build time so
     // added items keep the same chrome.
     itemKey: arrayEl.getAttribute('data-hcms-item-tpl') || null,
+    pageRules,
   })
   slot.appendChild(itemNode)
   enhanceFields(itemNode, ctx.doc)

package/src/form-builder.js

@@ -28,14 +28,19 @@ export function fileNameFromUrl(url) {
 
 export function buildForm({ pageRules, formRules: _formRules, data, doc }) {
   const fragment = doc.createDocumentFragment()
-  const root = buildNode(pageRules, [], data, doc)
+  const root = buildNode(pageRules, [], data, doc, pageRules)
   if (root) fragment.appendChild(root)
   return fragment
 }
 
-export function buildItem({ shape, itemShape, pathArr, data, doc, itemKey }) {
+// pageRules rides alongside doc so a scalar bound to its own context element
+// ("." / "@attr") can resolve the row that carries its named control; doc alone
+// cannot answer that, because the row is only knowable from the enclosing array
+// rule. deriveFormRules resolves it from the same pair, which is what keeps the
+// built form and the derived rules in lockstep.
+export function buildItem({ shape, itemShape, pathArr, data, doc, itemKey, pageRules }) {
   if (shape === 'object-array-item') {
-    return buildObjectArrayItem(itemShape, pathArr, data, doc)
+    return buildObjectArrayItem(itemShape, pathArr, data, doc, pageRules)
   }
   if (shape === 'scalar-array-item') {
     return buildScalarArrayItem(pathArr, data, doc, itemKey || null)
@@ -43,23 +48,23 @@ export function buildItem({ shape, itemShape, pathArr, data, doc, itemKey }) {
   throw new Error(`hypercms: buildItem called with unknown shape "${shape}"`)
 }
 
-function buildNode(rule, pathArr, data, doc) {
+function buildNode(rule, pathArr, data, doc, pageRules) {
   const kind = shapeKindOf(rule)
-  if (kind === 'scalar') return buildScalar(rule, pathArr, data, doc)
-  if (kind === 'object') return buildObject(rule, pathArr, data, doc)
-  if (kind === 'object-array') return buildObjectArray(rule, pathArr, data, doc)
+  if (kind === 'scalar') return buildScalar(rule, pathArr, data, doc, pageRules)
+  if (kind === 'object') return buildObject(rule, pathArr, data, doc, pageRules)
+  if (kind === 'object-array') return buildObjectArray(rule, pathArr, data, doc, pageRules)
   if (kind === 'scalar-array') return buildScalarArray(rule, pathArr, data, doc)
   return null
 }
 
-function buildScalar(rule, pathArr, data, doc) {
+function buildScalar(rule, pathArr, data, doc, pageRules) {
   // Opt-in components select a richer template off the bound rule (explicit
   // data-hcms-component, then @prop inference); plain scalars stay @scalar.
   // A path-bound template override still wins inside resolveTemplate.
-  const componentKey = componentForScalarRule(rule, doc, pathArr)
+  const componentKey = componentForScalarRule(rule, doc, pathArr, pageRules)
   const tpl = resolveTemplate(pathArr, componentKey, doc)
   if (!tpl) throw new Error(`hypercms: missing template for scalar at "${pathArr.join('.')}"`)
-  const declaredKey = declaredComponentKey(rule, doc)
+  const declaredKey = declaredComponentKey(rule, doc, pathArr, pageRules)
   // A value-guard fell back to text: say so, or "where did my number input /
   // checkbox go" has no answer.
   if (declaredKey === '@number' && componentKey === '@scalar') {
@@ -81,10 +86,10 @@ function buildScalar(rule, pathArr, data, doc) {
   // corrupt that UI.
   const winnerKey = tpl.getAttribute?.('data-hcms-tpl')
   if ((componentKey === '@select' || componentKey === '@radio') && winnerKey === componentKey) {
-    populateOptions(node, rule, pathArr, data, doc, componentKey)
+    populateOptions(node, rule, pathArr, data, doc, componentKey, pageRules)
   }
   if (componentKey === '@image' && winnerKey === '@image') {
-    const crop = readCropOverride(rule, doc)
+    const crop = readCropOverride(rule, doc, pathArr, pageRules)
     if (crop != null && !node.hasAttribute('data-hcms-crop')) node.setAttribute('data-hcms-crop', crop)
   }
   // Stamp leaf input(s) FIRST so the container's data-hcms-field doesn't
@@ -119,8 +124,8 @@ function noteShadowedComponent(tpl, declaredKey, pathArr) {
 // page value is prepended when it isn't in the list, so opening the editor
 // never silently changes data. Radio inputs get a per-field name derived from
 // the path so sibling fields (and array items) never cross-group.
-function populateOptions(node, rule, pathArr, data, doc, componentKey) {
-  const provided = readOptionsOverride(rule, doc)
+function populateOptions(node, rule, pathArr, data, doc, componentKey, pageRules) {
+  const provided = readOptionsOverride(rule, doc, pathArr, pageRules)
   const values = provided ? [...provided] : []
   const current = data == null ? '' : String(data)
   if (current !== '' && !values.includes(current)) values.unshift(current)
@@ -192,7 +197,7 @@ function syncFileLeafText(node) {
   if (a) a.textContent = fileNameFromUrl(a.getAttribute('href'))
 }
 
-function buildObject(rule, pathArr, data, doc) {
+function buildObject(rule, pathArr, data, doc, pageRules) {
   const tpl = resolveTemplate(pathArr, '@object', doc)
   if (!tpl) throw new Error(`hypercms: missing template for object at "${pathArr.join('.')}"`)
   const node = cloneTemplate(tpl, doc)
@@ -209,13 +214,13 @@ function buildObject(rule, pathArr, data, doc) {
   const slot = requireSlot(node, '.hcms-object-fields', tpl, pathArr)
   for (const [k, child] of Object.entries(rule)) {
     const childData = data == null ? null : data[k]
-    const childNode = buildNode(child, [...pathArr, k], childData, doc)
+    const childNode = buildNode(child, [...pathArr, k], childData, doc, pageRules)
     if (childNode) slot.appendChild(childNode)
   }
   return node
 }
 
-function buildObjectArray(rule, pathArr, data, doc) {
+function buildObjectArray(rule, pathArr, data, doc, pageRules) {
   const tpl = resolveTemplate(pathArr, '@object-array', doc)
   if (!tpl) throw new Error(`hypercms: missing template for object-array at "${pathArr.join('.')}"`)
   const node = cloneTemplate(tpl, doc)
@@ -229,14 +234,14 @@ function buildObjectArray(rule, pathArr, data, doc) {
   const [, itemShape] = rule
   const items = Array.isArray(data) ? data : []
   items.forEach((itemData, i) => {
-    const itemNode = buildObjectArrayItem(itemShape, [...pathArr, i], itemData, doc)
+    const itemNode = buildObjectArrayItem(itemShape, [...pathArr, i], itemData, doc, pageRules)
     if (itemNode) slot.appendChild(itemNode)
   })
   applyConstraintVisibility(node)
   return node
 }
 
-function buildObjectArrayItem(itemShape, pathArr, data, doc) {
+function buildObjectArrayItem(itemShape, pathArr, data, doc, pageRules) {
   const tpl = resolveItemTemplate(pathArr, 'object-array-item', doc)
   if (!tpl) throw new Error(`hypercms: missing item template for "${pathArr.join('.')}"`)
   const node = cloneTemplate(tpl, doc)
@@ -256,7 +261,7 @@ function buildObjectArrayItem(itemShape, pathArr, data, doc) {
   if (itemShape && typeof itemShape === 'object' && !Array.isArray(itemShape)) {
     for (const [k, child] of Object.entries(itemShape)) {
       const childData = data == null ? null : data[k]
-      const childNode = buildNode(child, [...pathArr, k], childData, doc)
+      const childNode = buildNode(child, [...pathArr, k], childData, doc, pageRules)
       if (childNode) slot.appendChild(childNode)
     }
   }

package/src/form-rules.js

@@ -112,7 +112,7 @@ export function deriveFormRules(pageRules, doc) {
     // leaf tag, so an @image field reads img@src and an @file field reads
     // a@href, while a plain scalar still respects a global @scalar override
     // (e.g. a <textarea>) instead of assuming <input>.
-    const shapeEl = findShapeFieldEl(componentForScalarRule(rule, doc, pathArr), fieldKey)
+    const shapeEl = findShapeFieldEl(componentForScalarRule(rule, doc, pathArr, pageRules), fieldKey)
     if (shapeEl) return fieldSelectorFor(shapeEl, fieldKey)
     return `input[data-hcms-field="${cssEscape(fieldKey)}"]@value`
   }

package/src/hypercms.js

@@ -339,6 +339,10 @@ export function close() {
   // host uploader) bails instead of mutating the page / firing onChange after
   // teardown. Mirrors the state.ctx !== ctx guards on the undo/livesync paths.
   ctx.closed = true
+  // An upload still in flight is torn down like any other subscription. The
+  // ctx.closed check above already stops it writing; this stops it running.
+  for (const controller of ctx.uploads || []) { try { controller.abort() } catch {} }
+  ctx.uploads?.clear()
   const previouslyFocused = ctx.previouslyFocused
   ctx.dispatch('hcms:close', null)
   toggleCloseParam()

package/src/platform.js

@@ -4,12 +4,11 @@
 //
 // TWO clients provide this and they disagree on names. hyperclayjs owns
 // window.hyperclay; clayjs owns window.clay and renamed things on the way past
-// (onPrepareForSave -> addDocumentTransform, consent -> confirm). clay.RichClay exists,
-// but quickcrop and uploadFileBasic have no clay equivalent at all, so image crop and
-// file upload silently degrade under clayjs. So this is a capability table
-// rather than a namespace pointer: `window.clay ?? window.hyperclay` would resolve
-// to clay, find no onPrepareForSave, and silently stop stripping the CMS's own
-// chrome out of every save.
+// (onPrepareForSave -> addDocumentTransform, consent -> confirm, uploadFileBasic ->
+// upload). So this is a capability table rather than a namespace pointer:
+// `window.clay ?? window.hyperclay` would resolve to clay, find no
+// onPrepareForSave, and silently stop stripping the CMS's own chrome out of every
+// save.
 //
 // Reads happen per call, never cached. A client can install a capability after
 // hypercms evaluates — that is the whole reason whenReady() below exists.
@@ -20,7 +19,59 @@ const CAPABILITIES = {
   consent:          (clay, hyperclay) => clay?.confirm ?? hyperclay?.consent,
   RichClay:         (clay, hyperclay) => clay?.RichClay ?? hyperclay?.RichClay,
   quickcrop:        (clay, hyperclay) => clay?.quickcrop ?? hyperclay?.quickcrop,
-  uploadFileBasic:  (clay, hyperclay) => clay?.uploadFileBasic ?? hyperclay?.uploadFileBasic,
+  upload:           (clay, hyperclay) =>
+    clay?.upload ?? (hyperclay?.uploadFileBasic ? adaptLegacyUpload(hyperclay.uploadFileBasic) : null),
+}
+
+// The one capability where the two clients differ in SHAPE and not just in name,
+// so it is normalized here rather than at the call site. clay.upload answers one
+// envelope for every outcome and never rejects; uploadFileBasic resolves on
+// success and rejects on failure. A pick handler that had to know which client it
+// was riding would grow two of every branch, and the branch that matters most is
+// the one a rejection reads wrong: "this host does not store files" is not a
+// failure, and a caller that catches it as one stops when it should have embedded.
+//
+// The legacy client has no cancellation, so `signal` is honored on the near side
+// only: an upload already in flight runs to completion, and its result is
+// discarded rather than written. That is the same outcome the caller's own
+// ctx.closed check produces, one branch earlier.
+const LEGACY_STATUS_CODES = {
+  402: 'payment-required',
+  413: 'too-large',
+  415: 'unsupported-type',
+  401: 'unauthorized',
+  403: 'forbidden',
+  404: 'not-found',
+}
+
+const aborted = () => ({ ok: false, msg: 'Upload cancelled', msgType: 'skipped', code: 'aborted', uploads: [] })
+
+function adaptLegacyUpload(uploadFileBasic) {
+  return async function upload(file, { onProgress, signal } = {}) {
+    if (signal?.aborted) return aborted()
+    try {
+      // uploadFileBasic reports a bare percent; clay reports {loaded,total,percent}.
+      // Callers draw from `percent`, which is the only field both can supply.
+      const res = await uploadFileBasic(file, {
+        onProgress: (percent) => { onProgress?.({ loaded: null, total: null, percent }) },
+      })
+      if (signal?.aborted) return aborted()
+      const uploads = (res && res.uploads) || []
+      if (typeof uploads[0]?.url !== 'string') {
+        return { ok: false, msg: 'The host accepted the file but did not say where it put it', msgType: 'error', code: 'bad-response', uploads: [] }
+      }
+      return { ok: true, msg: res.msg || 'Uploaded', msgType: res.msgType || 'success', code: res.code || null, uploads }
+    } catch (err) {
+      if (signal?.aborted) return aborted()
+      // The rejection carries the HTTP status and the raw body, so the host's own
+      // code survives the round trip and the caller branches on the reason rather
+      // than pattern-matching a message.
+      let body = {}
+      try { body = JSON.parse(err?.response || '{}') } catch { body = {} }
+      const code = body.code || LEGACY_STATUS_CODES[err?.status] || 'error'
+      return { ok: false, msg: (err && err.message) || 'Upload failed', msgType: 'error', code, uploads: [] }
+    }
+  }
 }
 
 // Pass `win` when the caller already holds a realm (a doc.defaultView from a form