uniweb 0.12.33 → 0.12.35

package/src/commands/push.js

@@ -34,17 +34,23 @@
  * Backend: via BackendClient (the content + folder sync lanes). Origin from
  *   --registry  >  UNIWEB_REGISTER_URL  >  the local default.
  * Auth:  --token  >  UNIWEB_TOKEN  >  `uniweb login` session.
+ *
+ * The two-lane SUBMISSION (POST both lanes, back-fill uuids, persist the
+ * send-only-changed cache) lives in `../backend/site-sync.js` so `uniweb deploy`
+ * (the composite path) reuses the exact same logic. This command owns flag parsing,
+ * the emit, and the `-o`/`--dry-run` preview.
  */
 
-import { writeFileSync, readFileSync, mkdirSync } from 'node:fs'
-import { resolve, join, dirname } from 'node:path'
-import {
-  emitSyncPackages,
-  backfillEntityUuids,
-  writeSiteEntityUuid,
-} from '@uniweb/build/uwx'
+import { writeFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { emitSyncPackages } from '@uniweb/build/uwx'
 import { BackendClient } from '../backend/client.js'
 import { resolveSiteDir } from './deploy.js'
+import { makeModelResolver, readSyncCache, pushSyncPackages } from '../backend/site-sync.js'
+
+// Re-exported for downstream importers (pull.js, push.test.js) that read these
+// helpers from this module — their canonical home is now ../backend/site-sync.js.
+export { extractMintedSiteUuid, makeModelResolver } from '../backend/site-sync.js'
 
 const colors = {
   reset: '\x1b[0m', bright: '\x1b[1m', dim: '\x1b[2m',
@@ -64,101 +70,6 @@ function flagValue(args, name) {
   return null
 }
 
-// Pull the finalized entities out of the restore response. The backend returns
-// `{ report: { finalized: [ { index, uuid, changed, document }, … ] } }` — each
-// entry carries its position in the SUBMITTED sequence (`index`, the correlation
-// key — `$id` is not echoed), the minted entity `uuid`, a `changed` flag, and the
-// full `document` (verbatim stored content with every `$uuid` filled in). A couple
-// of shapes are tolerated; only entries with a valid `index` + `uuid` are usable.
-function extractFinalized(payload) {
-  const list = Array.isArray(payload?.report?.finalized)
-    ? payload.report.finalized
-    : Array.isArray(payload?.finalized)
-      ? payload.finalized
-      : Array.isArray(payload)
-        ? payload
-        : null
-  if (!list) return null
-  return list
-    .map((d) => ({
-      index: d?.index,
-      uuid: d?.uuid ?? d?.document?.$uuid ?? null,
-      changed: d?.changed,
-      document: d?.document ?? null,
-    }))
-    .filter((e) => Number.isInteger(e.index) && e.uuid)
-}
-
-// Pull the minted site-content uuid out of a CREATE
-// response. The exact shape is an open backend item — tolerant of a bare
-// `{ siteContentUuid }` / `{ $uuid }` / `{ uuid }`, or the same `report.finalized[]`
-// envelope the update/folder lanes return (the site entity is submitted alone, so its
-// minted uuid is the first finalized entry). Returns null if none is present. (Single
-// adjust-point to pin at the first live CREATE.)
-export function extractMintedSiteUuid(payload) {
-  if (typeof payload?.siteContentUuid === 'string') return payload.siteContentUuid
-  if (typeof payload?.$uuid === 'string') return payload.$uuid
-  if (typeof payload?.uuid === 'string') return payload.uuid
-  const finalized = extractFinalized(payload)
-  if (finalized && finalized.length) {
-    const site = finalized.find((f) => f.index === 0) || finalized[0]
-    return site?.uuid ?? null
-  }
-  return null
-}
-
-// One-line summary from the authoritative per-entity `changed` flag (`false` = a
-// true no-op). Falls back silently when the backend omits it.
-function changedSummary(finalized) {
-  const changed = finalized.filter((f) => f.changed === true).length
-  const unchanged = finalized.filter((f) => f.changed === false).length
-  const parts = []
-  if (changed) parts.push(`${changed} changed`)
-  if (unchanged) parts.push(`${unchanged} unchanged`)
-  return parts.length ? parts.join(', ') : null
-}
-
-// Resolve a Model NOT defined by the local foundation by reading its declaration
-// (the `@uniweb/data-schema` form) from the backend via the client. Cached per run;
-// HTTP 404 → null (the emitter then says "register it first"). The bearer is acquired
-// lazily by the client, so a fully-local sync never authenticates.
-//
-// `offline` (set for `-o` / `--dry-run`) forces every non-local Model to null WITHOUT
-// touching the backend — an offline emit must never authenticate. The collections
-// emitter then soft-skips a convention-defaulted schema with a warning ("not synced")
-// and still emits the site-content lane; an EXPLICIT non-local schema surfaces as a
-// clear "could not be resolved" error rather than an auth prompt.
-export function makeModelResolver({ client, offline = false }) {
-  const cache = new Map()
-  return async (modelName) => {
-    if (cache.has(modelName)) return cache.get(modelName)
-    const decl = offline ? null : await client.readDataSchema(modelName)
-    cache.set(modelName, decl)
-    return decl
-  }
-}
-
-// "Send only changed" cache: content hashes from the last successful sync, keyed
-// `<model> <id>`. Gitignored, per-clone, deletable (a deleted cache just means one
-// full re-sync, which the backend then no-ops). NOT identity — the minted `$uuid`
-// lives in the source files; this is a pure wire-efficiency cache.
-function syncCachePath(siteDir) {
-  return join(siteDir, '.uniweb', 'sync-cache.json')
-}
-function readSyncCache(siteDir) {
-  try {
-    const obj = JSON.parse(readFileSync(syncCachePath(siteDir), 'utf8'))
-    return obj && typeof obj.hashes === 'object' && obj.hashes ? obj.hashes : {}
-  } catch {
-    return {} // missing / unreadable → treat everything as changed
-  }
-}
-function writeSyncCache(siteDir, hashes) {
-  const p = syncCachePath(siteDir)
-  mkdirSync(dirname(p), { recursive: true })
-  writeFileSync(p, JSON.stringify({ version: 1, hashes }, null, 2) + '\n')
-}
-
 export async function push(args = []) {
   const dryRun = args.includes('--dry-run')
   const output = flagValue(args, '-o') || flagValue(args, '--output')
@@ -197,7 +108,7 @@ export async function push(args = []) {
     error(`Could not build the sync package: ${err.message}`)
     return { exitCode: 2 }
   }
-  const { siteContent, collections, siteContentUuid, warnings, hashes, skipped } = pkg
+  const { siteContent, collections, siteContentUuid, warnings, skipped } = pkg
   log('')
   for (const w of warnings) note(`! ${w}`)
 
@@ -235,116 +146,19 @@ export async function push(args = []) {
     return { exitCode: 0 }
   }
 
-  const wrote = []
-  let finalizedTotal = 0
-
-  // POST one lane via the client and parse the JSON response. `doRequest` is a thunk
-  // returning the client's Response promise (so the "Pushing …" line prints before the
-  // request fires). The client carries `collision=force` (last-push-wins) + the optional
-  // `--as-org`. Returns the parsed payload, or null on any transport/HTTP/parse failure
-  // (already reported).
-  const postLane = async (label, doRequest) => {
-    info(`Pushing ${label} to ${colors.dim}${client.origin}${colors.reset} …`)
-    let res
-    try {
-      res = await doRequest()
-    } catch (err) {
-      error(`Could not reach the backend at ${client.origin}: ${err.message}`)
-      note('Set the origin with --registry <url> or UNIWEB_REGISTER_URL.')
-      return null
-    }
-    if (!res.ok) {
-      error(`${label} push rejected: HTTP ${res.status} ${res.statusText}`)
-      if (res.status === 401 || res.status === 403) {
-        note("Credentials weren't accepted — supply a bearer with --token <bearer> (or UNIWEB_TOKEN).")
-      }
-      const body = await res.text().catch(() => '')
-      if (body) note(body.slice(0, 800))
-      return null
-    }
-    try {
-      return await res.json()
-    } catch (err) {
-      error(`Could not parse the ${label} response as JSON: ${err.message}`)
-      return null
-    }
-  }
-
-  // POST a lane that round-trips entity uuids (content UPDATE + the folder): parse the
-  // finalized list (for record back-fill + the changed summary). Returns the finalized
-  // array, or null on failure (already reported).
-  const pushLane = async (label, doRequest) => {
-    const payload = await postLane(label, doRequest)
-    if (payload === null) return null
-    const finalized = extractFinalized(payload)
-    if (!finalized) {
-      error(`The ${label} response carried no recognizable finalized list (expected report.finalized[] with index + uuid).`)
-      note(JSON.stringify(payload).slice(0, 800))
-      return null
-    }
-    const summary = changedSummary(finalized)
-    if (summary) note(`${label}: ${summary}`)
-    return finalized
-  }
-
-  // Lane 1 — site-content (the site is born here; it must exist before its folder). A
-  // known site uuid → UPDATE by uuid; none → CREATE (the backend mints + adopts the
-  // site and returns its uuid, which we record into site.yml). `boundSiteUuid` carries
-  // the minted/known uuid forward to key the folder push.
-  let boundSiteUuid = siteContentUuid
-  if (siteContent) {
-    if (siteContentUuid) {
-      const finalized = await pushLane(
-        'site-content',
-        () => client.updateSiteContent(siteContentUuid, siteContent.buffer, { asOrg })
-      )
-      if (!finalized) return { exitCode: 1 }
-      finalizedTotal += finalized.length
-    } else {
-      const payload = await postLane(
-        'site-content',
-        () => client.createSiteContent(siteContent.buffer, { asOrg })
-      )
-      if (payload === null) return { exitCode: 1 }
-      const minted = extractMintedSiteUuid(payload)
-      if (!minted) {
-        error('The create response carried no minted site-content uuid — cannot record the site identity or push its folder.')
-        note(JSON.stringify(payload).slice(0, 800))
-        return { exitCode: 1 }
-      }
-      writeSiteEntityUuid(siteDir, minted)
-      boundSiteUuid = minted
-      wrote.push('recorded site $uuid in site.yml')
-      finalizedTotal += extractFinalized(payload)?.length ?? 1
-    }
-  }
-
-  // Lane 2 — collections (the @uniweb/folder + the records it references), keyed by the
-  // site-content uuid. On a brand-new site the backend creates the folder on this first
-  // push. Records round-trip their own $uuid (back-filled into source files); the folder
-  // itself has no uuid (the backend owns it).
-  if (collections) {
-    if (!boundSiteUuid) {
-      error('Cannot push collections — the site has no uuid yet. Push the site-content lane first.')
-      return { exitCode: 1 }
-    }
-    const finalized = await pushLane(
-      'collections',
-      () => client.pushFolder(boundSiteUuid, collections.buffer, { asOrg })
-    )
-    if (!finalized) return { exitCode: 1 }
-    const bf = backfillEntityUuids({ index: collections.index, finalized })
-    for (const w of bf.warnings) note(`! ${w}`)
-    for (const d of bf.deferred) note(`↷ ${d.id ?? `#${d.index}`}: ${d.reason}`)
-    if (bf.updated.length) wrote.push(`wrote ${bf.updated.length} record file(s)`)
-    finalizedTotal += finalized.length
-  }
-
-  // Persist the full content-hash map so the next push skips unchanged entities.
-  writeSyncCache(siteDir, hashes)
+  // Submit both lanes, back-fill the minted uuids, and persist the send-only-changed
+  // cache. Shared with `uniweb deploy` via ../backend/site-sync.js.
+  const result = await pushSyncPackages({
+    client,
+    siteDir,
+    pkg,
+    asOrg,
+    report: { info, note, error, dim: (s) => `${colors.dim}${s}${colors.reset}` },
+  })
+  if (result.exitCode !== 0) return { exitCode: result.exitCode }
   success(
-    `Pushed ${finalizedTotal} entit${finalizedTotal === 1 ? 'y' : 'ies'}` +
-      (wrote.length ? ` — ${wrote.join(', ')}` : '')
+    `Pushed ${result.finalizedTotal} entit${result.finalizedTotal === 1 ? 'y' : 'ies'}` +
+      (result.wrote.length ? ` — ${result.wrote.join(', ')}` : '')
   )
   return { exitCode: 0 }
 }

package/src/commands/rename.js

@@ -30,9 +30,11 @@
  * (target name already taken, target not found, folder collision,
  * type mismatch) we bail with a clear message and no partial state.
  *
- * Out of scope: registry side. The publish id (package.json::uniweb.id)
- * is independent of the workspace name and stays untouched. Users who
- * want to also rename on the registry run `uniweb publish --name <new>`.
+ * Out of scope: registry side. The registered id (the scoped
+ * `package.json::name` / `uniweb.id`) is independent of the workspace name and
+ * stays untouched. There is no registry-rename flag — a registered version is
+ * immutable; to change a foundation's registered identity, register it under
+ * the new name (consuming sites repoint their `foundation:` ref).
  *
  * Usage:
  *   uniweb rename foundation <old> <new>

package/src/commands/status.js

@@ -0,0 +1,174 @@
+/**
+ * uniweb status — show how a site's local files compare to the Uniweb backend:
+ * its sync identity, unpushed content changes, and the foundation it references.
+ *
+ * LOCAL + OFFLINE by default: it builds the sync packages with an OFFLINE Model
+ * resolver and diffs them against the send-only-changed cache (the same diff
+ * `uniweb push` runs) — no auth, no backend round-trip.
+ *
+ * `--remote` adds the backend signals (may prompt for login, like `git fetch`):
+ *   - whether the synced draft differs from what's live (publish needed), and
+ *   - whether a newer foundation version is registered than the site pins.
+ * Those use ASSUMED endpoints (see kb shipping-verbs-and-freshness.md §6.5); until
+ * the backend exposes them, `--remote` degrades silently to the local view.
+ *
+ * Usage:
+ *   uniweb status            Sync identity + unpushed content + foundation ref (local)
+ *   uniweb status --remote   Also: draft-vs-live + a newer-registered-foundation check
+ *   uniweb status --json     One JSON line (adds a `remote` object under --remote)
+ *
+ * Run from a site, or a workspace with one site.
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import yaml from 'js-yaml'
+
+import { resolveSiteDir } from './deploy.js'
+import { probeUnpushed } from '../backend/site-sync.js'
+import { BackendClient } from '../backend/client.js'
+import { readFlagValue } from '../utils/args.js'
+
+const c = {
+  reset: '\x1b[0m', bold: '\x1b[1m', dim: '\x1b[2m',
+  cyan: '\x1b[36m', green: '\x1b[32m', yellow: '\x1b[33m',
+}
+const say = {
+  ok: (m) => console.log(`${c.green}✓${c.reset} ${m}`),
+  info: (m) => console.log(`${c.cyan}→${c.reset} ${m}`),
+  warn: (m) => console.log(`${c.yellow}⚠${c.reset} ${m}`),
+  dim: (m) => console.log(`  ${c.dim}${m}${c.reset}`),
+}
+
+function readSiteYml(siteDir) {
+  const p = join(siteDir, 'site.yml')
+  if (!existsSync(p)) return {}
+  try {
+    return yaml.load(readFileSync(p, 'utf8')) || {}
+  } catch {
+    return {}
+  }
+}
+
+function foundationRef(siteYml) {
+  const f = siteYml.foundation
+  if (!f) return null
+  return typeof f === 'string' ? f : f.ref || null
+}
+
+// A versioned registry ref `@org/name@1.2.3` → its scoped name `@org/name` and
+// pinned version `1.2.3`. A bare/local/unversioned ref → nulls.
+function splitFoundationRef(fnd) {
+  if (!fnd || fnd[0] !== '@') return { scope: null, version: null }
+  const at = fnd.lastIndexOf('@')
+  return at > 0 ? { scope: fnd.slice(0, at), version: fnd.slice(at + 1) } : { scope: null, version: null }
+}
+
+export async function status(args = []) {
+  const jsonMode = args.includes('--json')
+  const remote = args.includes('--remote')
+  const siteDir = await resolveSiteDir(args, 'status')
+  const siteYml = readSiteYml(siteDir)
+  const uuid = siteYml.$uuid || null
+  const fnd = foundationRef(siteYml)
+  const { scope: fndScope, version: fndVersion } = splitFoundationRef(fnd)
+
+  // Local content diff — builds the sync packages, never authenticates.
+  let probe = null
+  let probeErr = null
+  try {
+    probe = await probeUnpushed(siteDir)
+  } catch (err) {
+    probeErr = err.message
+  }
+
+  // Remote signals — opt-in (`--remote`). May prompt for login. Degrades to null
+  // on 404 / any failure, so a backend without the endpoints just shows local.
+  let site = null
+  let fdnLatest = null
+  if (remote) {
+    try {
+      const client = new BackendClient({
+        originFlag: readFlagValue(args, '--backend') || readFlagValue(args, '--registry'),
+        token: readFlagValue(args, '--token') || undefined,
+        args,
+        command: 'Status',
+      })
+      if (uuid) site = await client.siteStatus(uuid)
+      if (fndScope) fdnLatest = await client.readFoundationLatest(fndScope)
+    } catch {
+      // degrade silently
+    }
+  }
+
+  if (jsonMode) {
+    console.log(
+      JSON.stringify({
+        synced: Boolean(uuid),
+        uuid,
+        foundation: fnd,
+        changed: probe ? probe.changed : null,
+        unchanged: probe ? probe.unchanged : null,
+        ...(probeErr ? { error: probeErr } : {}),
+        ...(remote ? { remote: { site, foundation_latest: fdnLatest?.latest_version ?? null } } : {}),
+      })
+    )
+    return { exitCode: 0 }
+  }
+
+  console.log('')
+
+  // Sync identity
+  if (uuid) {
+    say.ok(`Synced — site-content ${c.bold}${uuid}${c.reset}`)
+  } else {
+    say.warn('Not synced — this site has never been pushed to a backend.')
+    say.dim('Run `uniweb push` to create it, or `uniweb deploy` to ship it in one step.')
+  }
+
+  // Content
+  if (probeErr) {
+    say.warn(`Couldn't compute content changes: ${probeErr}`)
+    say.dim('A build error or an unresolved data Model can block the offline diff.')
+  } else if (!uuid) {
+    const n = probe.changed
+    say.info(`${n} content ${n === 1 ? 'entity' : 'entities'} ready to push.`)
+  } else if (probe.changed === 0) {
+    say.ok('Content is in sync with the last push.')
+  } else {
+    const n = probe.changed
+    say.info(
+      `${c.bold}${n}${c.reset} content ${n === 1 ? 'entity' : 'entities'} not pushed` +
+        (probe.unchanged ? ` (${probe.unchanged} unchanged)` : '') +
+        '.'
+    )
+    say.dim('Run `uniweb push` to sync, then `uniweb publish` to go live (or `uniweb deploy` for both).')
+  }
+
+  // Foundation
+  if (fnd) say.dim(`Foundation: ${fnd}`)
+
+  // Remote signals
+  if (remote) {
+    if (site) {
+      if (site.draft_dirty) {
+        say.info('Synced draft has changes not yet live — run `uniweb publish` to go live.')
+      } else if (site.published) {
+        say.ok('Live with the latest synced content.')
+      } else {
+        say.info('Synced but not published yet — run `uniweb publish` to go live.')
+      }
+    }
+    if (fdnLatest?.latest_version && fndVersion && fdnLatest.latest_version !== fndVersion) {
+      say.info(`A newer foundation version (${fdnLatest.latest_version}) is registered than the site pins (${fndVersion}).`)
+    }
+    if (!site && !fdnLatest) {
+      say.dim('(No remote signals — the backend may not expose them yet.)')
+    }
+  }
+
+  console.log('')
+  return { exitCode: 0 }
+}
+
+export default status

package/src/framework-index.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-06-18T03:42:23.549Z",
+  "generatedAt": "2026-06-24T03:15:27.555Z",
   "packages": {
     "@uniweb/build": {
-      "version": "0.14.16",
+      "version": "0.14.18",
       "path": "framework/build",
       "deps": [
         "@uniweb/content-reader",
@@ -99,7 +99,7 @@
       "deps": []
     },
     "@uniweb/unipress": {
-      "version": "0.4.22",
+      "version": "0.4.24",
       "path": "framework/unipress",
       "deps": [
         "@uniweb/build",

package/src/index.js

@@ -627,6 +627,13 @@ async function main() {
     process.exit(result?.exitCode ?? 0)
   }
 
+  // Handle status command (dynamic import — offline emit via @uniweb/build)
+  if (command === 'status') {
+    const { status } = await importProjectCommand('./commands/status.js')
+    const result = await status(args.slice(1))
+    process.exit(result?.exitCode ?? 0)
+  }
+
   // Handle clone command (global — bootstraps a new project from a backend site;
   // STANDALONE, so a global `uniweb clone` runs here instead of delegating to a
   // project-local CLI that doesn't exist yet. clone.js avoids any static
@@ -1470,6 +1477,7 @@ ${colors.bright}Commands:${colors.reset}
   runtime register   Register an @uniweb/runtime version to the backend (@std only)
   push               Push a site's content to the backend
   pull               Pull a site's content from the backend
+  status             Show a site's sync state (unpushed content, foundation)
   inspect <path>     Inspect parsed content shape of a markdown file or folder
   docs               Generate component documentation
   doctor             Diagnose project configuration issues

package/src/utils/asset-upload.js

@@ -73,10 +73,15 @@ export function collectSiteAssets(distDir) {
 
 /**
  * Deliver a site's assets: plan, then PUT each NEW file. Returns the rewrite map
- * (`localUrl → { id, ext }`) — populated for files that uploaded successfully OR
- * that the plan reports already `present`, so a partial failure never injects a
- * broken serve URL into content. Throws only on a plan-level failure; per-file
- * PUT failures surface in `failed`.
+ * (`localUrl → { id, ext, serveUrl }`) — populated for files that uploaded
+ * successfully OR that the plan reports already `present`, so a partial failure
+ * never injects a broken serve URL into content. Throws only on a plan-level
+ * failure; per-file PUT failures surface in `failed`.
+ *
+ * `serveUrl` is the backend's canonical, ready-built serve URL for the asset (the
+ * plan entry's `serve_url`; content-addressed, lane-independent). Callers embed it
+ * verbatim; `buildAssetUrl(origin, assetBase, id, ext)` reconstructs the same
+ * string and stays as a fallback for an older backend that omits `serve_url`.
  *
  * Skip-list (content-addressed dedup): a plan entry with `present: true` is
  * already in the global store — we don't re-PUT it, but we DO record its id+ext
@@ -89,7 +94,7 @@ export function collectSiteAssets(distDir) {
  * @param {string} opts.distDir  - the site's built dist/ directory
  * @param {Array}  [opts.files]  - pre-collected list (default: collectSiteAssets)
  * @param {(msg: string) => void} [opts.onProgress]
- * @returns {Promise<{ mode: string, uploaded: string[], skipped: string[], failed: Array<{path, status, detail}>, assetsByLocalUrl: Record<string, { id: string, ext: string }> }>}
+ * @returns {Promise<{ mode: string, uploaded: string[], skipped: string[], failed: Array<{path, status, detail}>, assetsByLocalUrl: Record<string, { id: string, ext: string, serveUrl?: string }> }>}
  */
 export async function uploadSiteAssets({ apiBase, token, distDir, files, onProgress = () => {} }) {
   const list = files || collectSiteAssets(distDir)
@@ -130,7 +135,7 @@ export async function uploadSiteAssets({ apiBase, token, distDir, files, onProgr
     // ⇒ false (older backend) → falls through to the upload path below.
     if (up.present) {
       skipped.push(src.path)
-      assetsByLocalUrl[src.localUrl] = { id: up.id, ext: String(up.ext || '').replace(/^\./, '') }
+      assetsByLocalUrl[src.localUrl] = { id: up.id, ext: String(up.ext || '').replace(/^\./, ''), serveUrl: up.serve_url }
       continue
     }
 
@@ -144,7 +149,7 @@ export async function uploadSiteAssets({ apiBase, token, distDir, files, onProgr
     try {
       // The plan's url may be origin-relative (direct mode → uniwebd) or
       // absolute (presigned → storage); new URL() resolves both.
-      putRes = await fetch(new URL(up.url, origin), { method: up.method || 'PUT', headers, body: readFileSync(src.diskPath) })
+      putRes = await fetch(new URL(up.url, origin), { method: up.method || 'PUT', headers, body: src.bytes ?? readFileSync(src.diskPath) })
     } catch (err) {
       failed.push({ path: src.path, status: 0, detail: err.message })
       continue
@@ -152,7 +157,7 @@ export async function uploadSiteAssets({ apiBase, token, distDir, files, onProgr
     if (putRes.ok) {
       uploaded.push(src.path)
       // Authoritative id + ext from the plan; mapped only on a successful PUT.
-      assetsByLocalUrl[src.localUrl] = { id: up.id, ext: String(up.ext || '').replace(/^\./, '') }
+      assetsByLocalUrl[src.localUrl] = { id: up.id, ext: String(up.ext || '').replace(/^\./, ''), serveUrl: up.serve_url }
     } else {
       failed.push({ path: src.path, status: putRes.status, detail: await putRes.text().catch(() => '') })
     }
@@ -160,3 +165,12 @@ export async function uploadSiteAssets({ apiBase, token, distDir, files, onProgr
 
   return { mode, uploaded, skipped, failed, assetsByLocalUrl }
 }
+
+// Build a durable asset serve URL from /dev/config's assetBase. Origin-relative
+// (`/gateway/asset/` in dev) → prepend the backend origin; absolute (a prod CDN)
+// → used verbatim. Shape: {assetBase}dist/{id}/base.{ext} — basename literally
+// `base`, {ext} the source extension the plan echoed.
+export function buildAssetUrl(origin, assetBase, id, ext) {
+  const base = /^https?:\/\//.test(assetBase) ? assetBase : `${origin}${assetBase}`
+  return `${base.replace(/\/$/, '')}/dist/${id}/base.${ext}`
+}