uniweb 0.36.0 → 0.37.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.36.0",
+  "version": "0.37.1",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -41,15 +41,15 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
-    "@uniweb/kit": "^0.15.2",
-    "@uniweb/semantic-parser": "^1.4.0",
+    "@uniweb/core": "^0.16.0",
+    "@uniweb/kit": "^0.15.3",
     "@uniweb/runtime": "^0.13.5",
-    "@uniweb/core": "^0.16.0"
+    "@uniweb/semantic-parser": "^1.4.0"
   },
   "peerDependencies": {
-    "@uniweb/build": "^0.32.0",
-    "@uniweb/content-reader": "^1.2.4",
-    "@uniweb/semantic-parser": "^1.4.0"
+    "@uniweb/build": "^0.33.0",
+    "@uniweb/semantic-parser": "^1.4.0",
+    "@uniweb/content-reader": "^1.2.4"
   },
   "peerDependenciesMeta": {
     "@uniweb/build": {

package/src/commands/publish.js

@@ -95,7 +95,10 @@ import {
   reportPaymentRefusal
 } from '../backend/payment-handoff.js'
 import { reportSchemalessQueries } from '../utils/schemaless-report.js'
-import { uploadSiteData } from '../utils/site-data-upload.js'
+import {
+  uploadSiteData,
+  describeDataRefusal
+} from '../utils/site-data-upload.js'
 
 const c = {
   reset: '\x1b[0m',
@@ -456,7 +459,12 @@ export async function publish(args = []) {
   // destructive — a placeholder file, created meaning to fill it in — so the count
   // is reported and confirmed before anything is sent.
   {
-    const guard = await guardEmptyRecords({ siteDir, args, warn: say.warn, note: say.dim })
+    const guard = await guardEmptyRecords({
+      siteDir,
+      args,
+      warn: say.warn,
+      note: say.dim
+    })
     if (!guard.ok) return { exitCode: 1 }
   }
 
@@ -602,28 +610,56 @@ export async function publish(args = []) {
   //     does not exist, which is the failure this work kept catching in others.
   //     `client.discover()` is the mechanism if that changes — `DISCOVERY_DEFAULTS`
   //     makes an absent key non-breaking by construction.
-  if (ball) {
-    say.info('Uploading schema-less record data…')
-    try {
-      const r = await uploadSiteData({
-        apiBase: client.origin,
-        token: await client.token(),
-        siteUuid: site.uuid,
-        ball,
-        onProgress: (m) => say.dim(`  ${m}`)
-      })
-      if (r.failed.length) {
-        // A file whose bytes did not land must not be published: the site would
-        // serve a stale copy or 404, and the only trace would be a warning.
-        say.err(`${r.failed.length} data file(s) failed to upload — not publishing.`)
-        for (const f of r.failed) say.dim(`  ${f.path} (HTTP ${f.status})`)
-        return { exitCode: 1 }
-      }
-      say.dim(`Record data     : ${r.uploaded.length} file(s) [${r.mode}]`)
-    } catch (err) {
-      say.err(`Record data upload failed: ${err.message}`)
+  //
+  // ⛔ UNCONDITIONAL — `if (ball)` was here until 2026-09-01 and it was the bug.
+  //
+  //     `collectSchemalessData` returns null for an empty set, so a publish that
+  //     carried no schema-less data sent NO PLAN AT ALL. The backend reconciles a
+  //     site's data usage against this manifest, and a request that never arrives
+  //     is not a manifest saying "none" — it is silence, indistinguishable from a
+  //     publish that never happened. So deleting your LAST schema-less collection
+  //     — the exact operation the reconcile exists to make free — was the one
+  //     operation that could not be expressed, and the site kept paying for it
+  //     until the whole site was deleted.
+  //
+  // ⭐ The general shape, worth more than the fix: an EMPTY set and NO set are
+  //    different statements, and an `if (x)` guard collapses them into one. The
+  //    cost is always paid by whoever is downstream trying to tell them apart.
+  //
+  // Both halves agreed in channel backend-framework-82f2 (2026-09-01); the
+  // backend's route accepts an empty `files` array as of the same exchange.
+  say.info('Uploading schema-less record data…')
+  try {
+    const r = await uploadSiteData({
+      apiBase: client.origin,
+      token: await client.token(),
+      siteUuid: site.uuid,
+      ball,
+      onProgress: (m) => say.dim(`  ${m}`)
+    })
+    if (r.failed.length) {
+      // A file whose bytes did not land must not be published: the site would
+      // serve a stale copy or 404, and the only trace would be a warning.
+      say.err(
+        `${r.failed.length} data file(s) failed to upload — not publishing.`
+      )
+      for (const f of r.failed) say.dim(`  ${f.path} (HTTP ${f.status})`)
       return { exitCode: 1 }
     }
+    say.dim(`Record data     : ${r.uploaded.length} file(s) [${r.mode}]`)
+  } catch (err) {
+    // A typed plan refusal gets its own account (quota, or whatever else the
+    // backend names); anything else falls through to the raw message. Same
+    // treatment the asset plan and the site create already get — this was the
+    // last door still printing the problem document at the user verbatim.
+    const refusal = describeDataRefusal(err)
+    if (refusal) {
+      say.err(refusal.headline)
+      for (const line of refusal.notes) say.dim(line)
+    } else {
+      say.err(`Record data upload failed: ${err.message}`)
+    }
+    return { exitCode: 1 }
   }
 
   // 5. Push the site (content + folder) over the send-only-changed cache —
@@ -680,9 +716,7 @@ export async function publish(args = []) {
         ? { baseVersions, itemBaseVersions: readItemBaseVersions(siteDir) }
         : {}),
       ...(Object.keys(injectInfo).length ? { injectInfo } : {}),
-      ...(Object.keys(ext.pins).length
-        ? { injectExtensions: ext.pins }
-        : {}),
+      ...(Object.keys(ext.pins).length ? { injectExtensions: ext.pins } : {}),
       ...(assetRewrite ? { assetRewrite } : {}),
       ...(assetIds ? { assetIds } : {})
     })

package/src/commands/update.js

@@ -257,7 +257,15 @@ export function printSurvey(
         statusText = `${colors.dim}aligned${colors.reset}`
       } else if (row.status === 'behind') {
         icon = `${colors.yellow}✗${colors.reset}`
-        statusText = `${colors.yellow}behind${colors.reset}`
+        // ⛔ `behind` alone was the whole message, in one colour, for every
+        // distance. In 0.x the minor slot is where our breaking changes live
+        // (`publish.js` derives it from a breaking marker and nothing else), so
+        // `^0.14.1 → ^0.16.0` is two releases a consumer must act on and
+        // `^0.15.0 → ^0.15.2` is not — and the table said the same thing about
+        // both. Naming the class is the difference between a list and a signal.
+        statusText = row.breaking
+          ? `${colors.red}${row.bump} · BREAKING${colors.reset}`
+          : `${colors.yellow}${row.bump}${colors.reset}`
       } else {
         icon = `${colors.cyan}↑${colors.reset}`
         statusText = `${colors.cyan}ahead of CLI${colors.reset}`
@@ -272,6 +280,35 @@ export function printSurvey(
       `  ${colors.dim}(${alignedCount} other${alignedCount === 1 ? '' : 's'} already aligned — ${colors.reset}${colors.cyan}--verbose${colors.reset}${colors.dim} to list)${colors.reset}`
     )
   }
+
+  // ⭐ **A summary, because the table scrolls and `--yes` does not stop.** The
+  // per-row label above is invisible to the case that matters most: a CI or an
+  // agent running `update --yes`, where nobody reads a table and the only
+  // artifact is a log. This block names the packages, so "what did that
+  // upgrade cross?" is answerable afterwards from the log alone.
+  //
+  // ⚖️ It reports; it does not gate. Crossing a 0.x minor IS the ordinary way
+  // to take a Uniweb update — gating it would gate nearly every real upgrade
+  // and make the verb useless. The decision stays the operator's; what changed
+  // is that they can now make it knowingly.
+  const breakingRows = report.rows.filter((r) => r.breaking)
+  if (breakingRows.length > 0) {
+    const names = [...new Set(breakingRows.map((r) => r.name))]
+    log('')
+    log(
+      `${colors.red}⚠${colors.reset}  ${colors.bright}${names.length} package${names.length === 1 ? '' : 's'} cross${names.length === 1 ? 'es' : ''} a breaking boundary:${colors.reset}`
+    )
+    for (const name of names) {
+      const r = breakingRows.find((x) => x.name === name)
+      log(`     ${colors.red}${name}${colors.reset}  ${r.current} → ${r.target}  ${colors.dim}(${r.bump})${colors.reset}`)
+    }
+    log(
+      `   ${colors.dim}In 0.x the minor slot is where breaking changes go, so these are releases${colors.reset}`
+    )
+    log(
+      `   ${colors.dim}you may need to act on. Read their changelogs before shipping.${colors.reset}`
+    )
+  }
   log('')
 }
 

package/src/framework-index.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-09-02T03:17:32.722Z",
+  "generatedAt": "2026-09-02T17:42:38.924Z",
   "packages": {
     "@uniweb/api": {
       "version": "0.2.2",
@@ -10,7 +10,7 @@
       ]
     },
     "@uniweb/build": {
-      "version": "0.32.0",
+      "version": "0.33.0",
       "path": "framework/build",
       "deps": [
         "@uniweb/content-reader",
@@ -54,7 +54,7 @@
       ]
     },
     "@uniweb/kit": {
-      "version": "0.15.2",
+      "version": "0.15.3",
       "path": "framework/kit",
       "deps": [
         "@uniweb/core",
@@ -119,7 +119,7 @@
       "deps": []
     },
     "@uniweb/unipress": {
-      "version": "0.8.18",
+      "version": "0.8.20",
       "path": "framework/unipress",
       "deps": [
         "@uniweb/build",

package/src/templates/fetchers/github.js

@@ -8,6 +8,7 @@ import { mkdtemp, rm } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import * as tar from 'tar'
+import { fetchWithRetry as sharedFetchWithRetry } from '../../utils/fetch-retry.js'
 
 /**
  * Fetch a template from a GitHub repository
@@ -78,21 +79,9 @@ export async function fetchGitHubTemplate(owner, repo, options = {}) {
   }
 }
 
-/**
- * Fetch with retry and timeout
- */
-async function fetchWithRetry(url, options = {}, maxRetries = 3) {
-  for (let attempt = 1; attempt <= maxRetries; attempt++) {
-    try {
-      const response = await fetch(url, {
-        ...options,
-        signal: AbortSignal.timeout(60000) // 60s timeout for GitHub (can be slow)
-      })
-      return response
-    } catch (err) {
-      if (attempt === maxRetries) throw err
-      const delay = Math.min(1000 * Math.pow(2, attempt), 10000)
-      await new Promise((r) => setTimeout(r, delay))
-    }
-  }
-}
+// Retry + timeout live in one place now (`../../utils/fetch-retry.js`).
+// This file carried its own copy, as did the other two fetchers — three
+// byte-identical implementations, and none reachable from the upload paths
+// that had no retry at all. The wrapper keeps this caller's own timeout.
+const fetchWithRetry = (url, options = {}, maxRetries = 3) =>
+  sharedFetchWithRetry(url, { ...options }, { retries: maxRetries, timeoutMs: 60000 })

package/src/templates/fetchers/npm.js

@@ -8,6 +8,7 @@ import { mkdtemp, rm } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import * as tar from 'tar'
+import { fetchWithRetry as sharedFetchWithRetry } from '../../utils/fetch-retry.js'
 
 /**
  * Fetch a template from npm registry
@@ -76,21 +77,9 @@ export async function fetchNpmTemplate(packageName, options = {}) {
   }
 }
 
-/**
- * Fetch with retry and timeout
- */
-async function fetchWithRetry(url, options = {}, maxRetries = 3) {
-  for (let attempt = 1; attempt <= maxRetries; attempt++) {
-    try {
-      const response = await fetch(url, {
-        ...options,
-        signal: AbortSignal.timeout(30000) // 30s timeout
-      })
-      return response
-    } catch (err) {
-      if (attempt === maxRetries) throw err
-      const delay = Math.min(1000 * Math.pow(2, attempt), 10000)
-      await new Promise((r) => setTimeout(r, delay))
-    }
-  }
-}
+// Retry + timeout live in one place now (`../../utils/fetch-retry.js`).
+// This file carried its own copy, as did the other two fetchers — three
+// byte-identical implementations, and none reachable from the upload paths
+// that had no retry at all. The wrapper keeps this caller's own timeout.
+const fetchWithRetry = (url, options = {}, maxRetries = 3) =>
+  sharedFetchWithRetry(url, { ...options }, { retries: maxRetries, timeoutMs: 30000 })

package/src/templates/fetchers/release.js

@@ -8,6 +8,7 @@ import { mkdtemp, rm } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import * as tar from 'tar'
+import { fetchWithRetry as sharedFetchWithRetry } from '../../utils/fetch-retry.js'
 
 // GitHub repository for official templates
 const TEMPLATES_REPO = 'uniweb/templates'
@@ -222,22 +223,9 @@ async function handleGitHubError(response) {
   throw new Error(`GitHub API error: ${response.status}`)
 }
 
-/**
- * Fetch with retry and timeout
- */
-async function fetchWithRetry(url, options = {}, maxRetries = 3) {
-  for (let attempt = 1; attempt <= maxRetries; attempt++) {
-    try {
-      const response = await fetch(url, {
-        ...options,
-        redirect: 'follow',
-        signal: AbortSignal.timeout(60000) // 60s timeout
-      })
-      return response
-    } catch (err) {
-      if (attempt === maxRetries) throw err
-      const delay = Math.min(1000 * Math.pow(2, attempt), 10000)
-      await new Promise((r) => setTimeout(r, delay))
-    }
-  }
-}
+// Retry + timeout live in one place now (`../../utils/fetch-retry.js`).
+// This file carried its own copy, as did the other two fetchers — three
+// byte-identical implementations, and none reachable from the upload paths
+// that had no retry at all. The wrapper keeps this caller's own timeout.
+const fetchWithRetry = (url, options = {}, maxRetries = 3) =>
+  sharedFetchWithRetry(url, { redirect: 'follow', ...options }, { retries: maxRetries, timeoutMs: 60000 })

package/src/utils/asset-upload.js

@@ -30,6 +30,7 @@ import { createHash } from 'node:crypto'
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
 import { join } from 'node:path'
 import { contentTypeFor } from './code-upload.js'
+import { fetchWithRetry, isTransientStatus } from './fetch-retry.js'
 
 /**
  * Walk a built site's `dist/assets/` and produce the upload file list. `path` is
@@ -202,11 +203,20 @@ export async function uploadSiteAssets({
     try {
       // The plan's url may be origin-relative (direct mode → the backend) or
       // absolute (presigned → storage); new URL() resolves both.
-      putRes = await fetch(new URL(up.url, origin), {
+      // ⭐ **Retried.** A single connection-level failure used to fail the whole
+      // verb after every other file had already gone up. The PUT is idempotent
+      // here — same bytes, same target, verified by `x-uniweb-sha256` on receipt
+      // — so repeating it is safe by construction, which is why this opts in to
+      // `retryOnStatus` rather than inheriting it.
+      //
+      // ⚠️ 120s per attempt, not the helper's 30s default: this bounds the time
+      // to send a whole BODY, and aborting a legitimately slow upload only to
+      // retry it is worse than not timing out at all.
+      putRes = await fetchWithRetry(new URL(up.url, origin), {
         method: up.method || 'PUT',
         headers,
         body: src.bytes ?? readFileSync(src.diskPath)
-      })
+      }, { timeoutMs: 120_000, retryOnStatus: isTransientStatus })
     } catch (err) {
       failed.push({ path: src.path, status: 0, detail: err.message })
       continue

package/src/utils/code-upload.js

@@ -41,6 +41,7 @@
 import { createHash } from 'node:crypto'
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
 import { join } from 'node:path'
+import { fetchWithRetry, isTransientStatus } from './fetch-retry.js'
 
 // Extension → declared content type. Extension-honest by construction (Vite
 // output); anything unknown ships as octet-stream.
@@ -287,7 +288,16 @@ export async function uploadFoundationCode({
     }
     const bytes = readFileSync(join(distDir, file.path))
     try {
-      const res = await fetch(new URL(target.url, origin), {
+      // ⭐ **Retried.** A single connection-level failure used to fail the whole
+      // verb after every other file had already gone up. The PUT is idempotent
+      // here — same bytes, same target, verified by `x-uniweb-sha256` on receipt
+      // — so repeating it is safe by construction, which is why this opts in to
+      // `retryOnStatus` rather than inheriting it.
+      //
+      // ⚠️ 120s per attempt, not the helper's 30s default: this bounds the time
+      // to send a whole BODY, and aborting a legitimately slow upload only to
+      // retry it is worse than not timing out at all.
+      const res = await fetchWithRetry(new URL(target.url, origin), {
         method: target.method || 'PUT',
         // x-uniweb-sha256: optional integrity guard — direct mode verifies
         // the received bytes and 400s on mismatch (corruption-in-flight).
@@ -297,7 +307,7 @@ export async function uploadFoundationCode({
           'x-uniweb-sha256': file.sha256
         },
         body: bytes
-      })
+      }, { timeoutMs: 120_000, retryOnStatus: isTransientStatus })
       if (res.ok) {
         uploaded.push(file.path)
         onProgress(`${file.path} (${file.size} bytes)`)

package/src/utils/dep-survey.js

@@ -33,6 +33,53 @@ export function stripVersionRange(spec) {
   )
 }
 
+/**
+ * How far a bump moves, in the terms our versioning actually uses.
+ *
+ * ⭐ **In 0.x the MINOR slot is the breaking one, and it is the only channel we
+ * have.** `scripts/framework/publish.js` derives a package's bump from its own
+ * commits: a breaking marker means minor, everything else patch. So
+ * `^0.14.1 → ^0.16.0` is two breaking releases and `^0.15.0 → ^0.15.2` is not —
+ * and until 2026-09-02 `update` printed both as `behind`, in the same colour,
+ * and `--yes` applied them without a word.
+ *
+ * That is the one signal the version scheme exists to send, discarded by the
+ * command we tell every project to run — `AGENTS.md` ships that instruction
+ * into every scaffold. The `flows` lane crossed `@uniweb/core` `^0.14.1 →
+ * ^0.15.0` this way and learned it afterwards, from a changelog.
+ *
+ * @param {string} from - the currently declared range or version
+ * @param {string} to   - the version the matrix carries
+ * @returns {'patch'|'minor'|'major'|'none'}
+ */
+export function bumpClass(from, to) {
+  const [aMaj = 0, aMin = 0, aPat = 0] = stripVersionRange(from).split('.').map(Number)
+  const [bMaj = 0, bMin = 0, bPat = 0] = stripVersionRange(to).split('.').map(Number)
+  if (bMaj !== aMaj) return 'major'
+  if (bMin !== aMin) return 'minor'
+  if (bPat !== aPat) return 'patch'
+  return 'none'
+}
+
+/**
+ * Is this crossing one a consumer must act on?
+ *
+ * A major always is. A minor is **when the major is 0**, because that is where
+ * our scheme puts breaking changes — and npm agrees, which is the check that
+ * makes this more than our own convention: `^0.14.1` admits `0.14.x` and
+ * refuses `0.15.0`, so the range itself already treats the slot as a wall.
+ *
+ * @param {string} from
+ * @param {string} to
+ * @returns {boolean}
+ */
+export function isBreakingBump(from, to) {
+  const cls = bumpClass(from, to)
+  if (cls === 'major') return true
+  if (cls !== 'minor') return false
+  return Number(stripVersionRange(to).split('.')[0]) === 0
+}
+
 /**
  * Compare two version specs (range prefix tolerated). Returns 1 / -1 / 0.
  * @param {string} a
@@ -115,7 +162,12 @@ export async function surveyWorkspaceDeps(workspaceDir) {
           name,
           current,
           target,
-          status
+          status,
+          // Classified here rather than at print time so every consumer of a
+          // survey row gets the same answer — the report, the summary, and any
+          // gate a caller applies.
+          bump: status === 'behind' ? bumpClass(current, target) : 'none',
+          breaking: status === 'behind' && isBreakingBump(current, target)
         })
       }
     }

package/src/utils/fetch-retry.js

@@ -0,0 +1,109 @@
+/**
+ * `fetch` with bounded retry and a timeout. **The one implementation.**
+ *
+ * ## Why this file exists
+ *
+ * There were three, byte-identical apart from a timeout constant — one each in
+ * `templates/fetchers/{npm,release,github}.js` — and **none of them was reachable
+ * from the code that needed it most.** The three upload paths (`code-upload`,
+ * `asset-upload`, `site-data-upload`) had no retry at all, so a single
+ * connection-level failure on any one file failed the whole `register` / `push`
+ * / `publish` after every other file had already gone up.
+ *
+ * ⭐ **Measured by the `flows` lane, 2026-09-02:** roughly one red per full suite
+ * run, landing on a *different flow each time* and passing on re-run every time —
+ * the signature of an unretried transient, with the network as the variable
+ * rather than any flow. Their symptom was recorded as "not diagnosed, may be the
+ * manor, the CDN, or the connection"; it was none of those. It was us.
+ *
+ * ## ⚠️ What a retry does NOT do
+ *
+ * It masks whatever drops the connection. That is the right trade for a genuine
+ * transient and the wrong one for a systematic fault: if the failure rate ever
+ * climbs, a retry turns a fast red into a slow one and hides the cause. **Do not
+ * read a green run as evidence the network is healthy.**
+ *
+ * ## Retrying a PUT is safe HERE, and not in general
+ *
+ * These uploads are idempotent by construction — the same bytes to the same
+ * target, with an `x-uniweb-sha256` integrity guard the far side verifies. That
+ * is why `retryOnStatus` is **opt-in** rather than the default: a caller has to
+ * assert its own idempotence, because this helper cannot know it.
+ */
+
+const DEFAULT_RETRIES = 3
+const DEFAULT_TIMEOUT_MS = 30_000
+const MAX_BACKOFF_MS = 10_000
+
+/** Exponential backoff, capped. Attempt is 1-based. */
+const backoffMs = (attempt) => Math.min(1000 * Math.pow(2, attempt), MAX_BACKOFF_MS)
+
+/**
+ * @param {string|URL} url
+ * @param {RequestInit} [options] - passed to `fetch`; `signal` is supplied here.
+ * @param {Object} [config]
+ * @param {number} [config.retries=3] - total attempts, not extra ones.
+ * @param {number} [config.timeoutMs=30000] - per ATTEMPT, not for the whole call.
+ *   ⚠️ For an upload this bounds the time to send a whole body, so a large file
+ *   on a slow link needs a generous value — too short and a legitimately slow
+ *   upload is aborted and then retried, which is worse than no timeout at all.
+ * @param {(status: number) => boolean} [config.retryOnStatus] - opt-in. Without
+ *   it only a THROWN fetch is retried (a connection-level failure, which is what
+ *   surfaces as `status: 0` in the upload paths). A caller passing this asserts
+ *   its request is safe to repeat.
+ * @param {(info: {attempt: number, of: number, reason: string, delayMs: number}) => void} [config.onRetry]
+ *   Called before each wait. ⭐ Worth passing: a retry that no one can see turns
+ *   a visible failure into an invisible slowdown, which is its own defect.
+ * @returns {Promise<Response>}
+ */
+export async function fetchWithRetry(url, options = {}, config = {}) {
+  const {
+    retries = DEFAULT_RETRIES,
+    timeoutMs = DEFAULT_TIMEOUT_MS,
+    retryOnStatus = null,
+    onRetry = null,
+  } = config
+
+  let lastErr = null
+
+  for (let attempt = 1; attempt <= retries; attempt++) {
+    try {
+      const res = await fetch(url, {
+        ...options,
+        signal: options.signal ?? AbortSignal.timeout(timeoutMs),
+      })
+
+      if (attempt < retries && retryOnStatus && retryOnStatus(res.status)) {
+        const delayMs = backoffMs(attempt)
+        onRetry?.({ attempt, of: retries, reason: `HTTP ${res.status}`, delayMs })
+        await new Promise((r) => setTimeout(r, delayMs))
+        continue
+      }
+
+      return res
+    } catch (err) {
+      lastErr = err
+      // The last attempt throws to the caller, which keeps this a drop-in for
+      // the three template fetchers whose contract was "throws like fetch".
+      if (attempt === retries) throw err
+      const delayMs = backoffMs(attempt)
+      onRetry?.({ attempt, of: retries, reason: err.message, delayMs })
+      await new Promise((r) => setTimeout(r, delayMs))
+    }
+  }
+
+  /* c8 ignore next 2 -- unreachable: the loop returns or throws on the last attempt */
+  throw lastErr
+}
+
+/**
+ * The statuses worth repeating an idempotent request for: a server that failed
+ * to answer this time, or asked us to slow down.
+ *
+ * ⛔ Never a 4xx other than 429 — a rejection does not improve on repetition,
+ * and retrying one turns a clear error into a delayed clear error.
+ *
+ * @param {number} status
+ * @returns {boolean}
+ */
+export const isTransientStatus = (status) => status === 429 || status >= 500

package/src/utils/site-data-upload.js

@@ -51,6 +51,8 @@
  */
 
 import { createHash } from 'node:crypto'
+import { humanBytes } from './bytes.js'
+import { fetchWithRetry, isTransientStatus } from './fetch-retry.js'
 
 /**
  * Plan + upload a site's static collection data files.
@@ -72,10 +74,23 @@ export async function uploadSiteData({
   ball,
   onProgress = () => {}
 }) {
+  // ⛔ An EMPTY set still posts a plan, and that is the whole point of this lane
+  // being a manifest rather than a stream of files.
+  //
+  // The backend reconciles a site's data usage against what this plan declares:
+  // whatever is not in the manifest is gone, so deleting a collection stops
+  // costing on the next publish. ⭐ A plan with zero files is a STATEMENT that
+  // there are none; the ABSENCE of a request says nothing at all. Returning
+  // early here — which this did until 2026-09-01 — made "the user deleted their
+  // last schema-less collection" unexpressible on the wire, so that site kept
+  // paying for bytes it no longer served until the whole site was deleted.
+  // Nothing looked wrong at either end: no error, no warning, just a request
+  // that was never sent.
+  //
+  // Agreed both sides in channel backend-framework-82f2; the backend's plan
+  // route accepted an empty `files` array in the same exchange (it was a 400
+  // before, which is what made the omission look like the only option).
   const entries = Object.entries(ball?.data || {})
-  if (!entries.length) {
-    return { mode: 'none', uploaded: [], failed: [], serveBase: null }
-  }
 
   // One plan for the whole set. The per-request file cap counts a plan, so
   // splitting would evade it rather than respect it; if a set ever exceeds it,
@@ -129,9 +144,25 @@ export async function uploadSiteData({
   )
   if (!planRes.ok) {
     const body = await planRes.text().catch(() => '')
-    throw new Error(
+    // The PARSED problem document has to survive the throw. Flattening it into
+    // the message is what left the other two doors unable to branch on `reason`
+    // and printing raw JSON at users; this lane was the last one still doing it.
+    // Callers read `err.problem`; `describeDataRefusal` turns it into lines.
+    let problem = null
+    if (body) {
+      try {
+        const parsed = JSON.parse(body)
+        if (parsed && typeof parsed === 'object') problem = parsed
+      } catch {
+        /* not a problem document — prose refusal, or an upstream error page */
+      }
+    }
+    const err = new Error(
       `site data-uploads plan rejected: HTTP ${planRes.status}${body ? ` — ${body.slice(0, 300)}` : ''}`
     )
+    err.status = planRes.status
+    err.problem = problem
+    throw err
   }
 
   const plan = await planRes.json()
@@ -149,13 +180,26 @@ export async function uploadSiteData({
     if (!target) {
       // A file the plan did not answer for is unaddressable. Report it; never
       // invent a location for it.
-      failed.push({ path: f.path, status: 0, detail: 'no upload target in plan' })
+      failed.push({
+        path: f.path,
+        status: 0,
+        detail: 'no upload target in plan'
+      })
       continue
     }
     try {
       // Relative on the direct arm, absolute on presigned — `new URL` resolves
       // both against the origin.
-      const res = await fetch(new URL(target.url, origin), {
+      // ⭐ **Retried.** A single connection-level failure used to fail the whole
+      // verb after every other file had already gone up. The PUT is idempotent
+      // here — same bytes, same target, verified by `x-uniweb-sha256` on receipt
+      // — so repeating it is safe by construction, which is why this opts in to
+      // `retryOnStatus` rather than inheriting it.
+      //
+      // ⚠️ 120s per attempt, not the helper's 30s default: this bounds the time
+      // to send a whole BODY, and aborting a legitimately slow upload only to
+      // retry it is worse than not timing out at all.
+      const res = await fetchWithRetry(new URL(target.url, origin), {
         method: target.method || 'PUT',
         headers: {
           'Content-Type': 'application/json',
@@ -163,7 +207,7 @@ export async function uploadSiteData({
           ...authHeaders
         },
         body: f.bytes
-      })
+      }, { timeoutMs: 120_000, retryOnStatus: isTransientStatus })
       if (res.ok) {
         uploaded.push(f.path)
         onProgress(`${f.path}`)
@@ -182,3 +226,65 @@ export async function uploadSiteData({
     serveBase: plan.serve_base || null
   }
 }
+
+/**
+ * Turn a typed data-uploads refusal into user-facing lines, or null when there is
+ * no typed `reason` (⇒ fall through to the generic message, degrading rather than
+ * swallowing).
+ *
+ * ⭐ The THIRD door, and the last to get one. `/dev/assets` has
+ * `describeAssetRefusal`, `POST /dev/site` has `describeCreateRefusal`, and this
+ * lane threw prose with the JSON inlined until 2026-09-01 — which is the failure
+ * the other two describers exist to prevent, so leaving it was just an untreated
+ * instance of a solved problem.
+ *
+ * ⛔ Branch on `reason`, never the status: `507` alone cannot be told from any
+ * other `507` and carries none of the numbers, and `detail` is prose the backend
+ * may reword.
+ *
+ * ⚖️ **The advice DIVERGES from the asset lane's, and that divergence is the whole
+ * reason this is a separate function rather than a reused one.** On the asset lane
+ * removing an image frees nothing — freeing is entity-deletion-granular. Here the
+ * publish declares the COMPLETE set of schema-less data files every time, so
+ * dropping a collection and re-publishing is a real way to stop paying for it.
+ * Telling a data user "editing content frees nothing" would be false, and telling
+ * an asset user "just remove it" would be worse.
+ *
+ * @param {Error & { problem?: object|null }} err
+ * @returns {{ headline: string, notes: string[] } | null}
+ */
+export function describeDataRefusal(err) {
+  const p = err?.problem
+  const reason = p?.reason
+  if (typeof reason !== 'string') return null
+
+  if (reason === 'storage_quota_exceeded') {
+    const notes = []
+    const used = humanBytes(p.used_bytes)
+    const limit = humanBytes(p.limit_bytes)
+    const needed = humanBytes(p.needed_bytes)
+    if (used) notes.push(`  Used: ${used}`)
+    if (limit) notes.push(`  Limit: ${limit}`)
+    if (needed) notes.push(`  This publish adds: ${needed}`)
+    notes.push(
+      'Every publish declares the full set of schema-less data files, so removing'
+    )
+    notes.push(
+      'a collection and re-publishing stops it counting. Deleting a site or entity'
+    )
+    notes.push('frees space too.')
+    return {
+      headline:
+        "Storage quota reached — the site owner's workspace cannot take on more record data.",
+      notes
+    }
+  }
+
+  // An unrecognised reason still beats a status dump: name it, and let the
+  // backend's own prose follow when it sent any.
+  const detail = typeof p.detail === 'string' ? p.detail : ''
+  return {
+    headline: `Record data upload refused by the backend (${reason}).`,
+    notes: detail ? [`  ${detail}`] : []
+  }
+}