uniweb 0.12.32 → 0.12.34

package/src/commands/pull.js

@@ -32,18 +32,20 @@
  * Auth:  --token  >  UNIWEB_TOKEN  >  `uniweb login` session.
  *
  * A project that never pushed has no `$uuid` to pull by — pull is a no-op with a
- * clear message. NOTE: the backend pull routes have not been exercised live; the
- * response-envelope extraction (extractDocument / splitCollectionsPull) is
- * deliberately tolerant and is the single point to adjust at the first live run.
+ * clear message. The backend serves each lane as a `.uwx` (ZIP: `manifest.json` +
+ * `entities/<uuid>.json`); `readPullDocuments` reads the entity files out of it, with
+ * a tolerant JSON fallback (`extractDocument` / `splitCollectionsPull`). Verified live
+ * against the playground backend, 2026-06-17.
  */
 
-import { readFileSync } from 'node:fs'
-import { join } from 'node:path'
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs'
+import { join, dirname } from 'node:path'
 import yaml from 'js-yaml'
 import {
   siteContentDocumentToProject,
   collectionsToProject,
   resolveCollectionsConfig,
+  readZip,
 } from '@uniweb/build/uwx'
 import { makeModelResolver } from './push.js'
 import { BackendClient } from '../backend/client.js'
@@ -76,6 +78,27 @@ function readYamlUuid(filePath) {
   }
 }
 
+// Conditional-pull ETag cache (gitignored `.uniweb/pull-cache.json`): the last ETag
+// seen per lane. The ETag is OPAQUE — cached and echoed verbatim in If-None-Match,
+// never parsed or recomputed (the backend owns the hash; the client treats it as a
+// token). A missing cache just means a full (unconditional) pull.
+function pullCachePath(siteDir) {
+  return join(siteDir, '.uniweb', 'pull-cache.json')
+}
+function readPullCache(siteDir) {
+  try {
+    const obj = JSON.parse(readFileSync(pullCachePath(siteDir), 'utf8'))
+    return obj && typeof obj === 'object' ? obj : {}
+  } catch {
+    return {}
+  }
+}
+function writePullCache(siteDir, { content, folder }) {
+  const p = pullCachePath(siteDir)
+  mkdirSync(dirname(p), { recursive: true })
+  writeFileSync(p, JSON.stringify({ version: 1, content, folder }, null, 2) + '\n')
+}
+
 // Extract a single entity `$`-document from a pull response. Tolerant of a raw
 // document, or a `{ document }` / `{ entity }` envelope. (Adjust at live e2e.)
 export function extractDocument(payload) {
@@ -104,6 +127,46 @@ export function splitCollectionsPull(payload) {
   }
 }
 
+// Read a pull lane's bytes into entity `$`-documents. The backend serves a `.uwx`
+// (our Stored ZIP: `manifest.json` + `entities/<uuid>.json`); the entity files ARE the
+// documents. Falls back to a JSON body (a raw doc, a `{document}`/`{entity}` envelope,
+// or a list) so the lane survives a future envelope change. Returns an array (possibly
+// empty).
+export function readPullDocuments(buf) {
+  // `.uwx` ZIP — the local-file signature is "PK\x03\x04".
+  if (buf.length >= 2 && buf[0] === 0x50 && buf[1] === 0x4b) {
+    const docs = []
+    for (const [name, data] of readZip(buf)) {
+      if (name === 'manifest.json' || !name.endsWith('.json')) continue
+      try {
+        docs.push(JSON.parse(data.toString('utf8')))
+      } catch {
+        /* skip a non-document entry */
+      }
+    }
+    return docs
+  }
+  // JSON fallback — flatten any envelope splitCollectionsPull understands into a
+  // flat `$`-document list (a raw doc, a list, `{entities}`/`{documents}`, or
+  // `{folder, records}`).
+  let payload
+  try {
+    payload = JSON.parse(buf.toString('utf8'))
+  } catch {
+    return []
+  }
+  if (Array.isArray(payload)) return payload.map(extractDocument).filter(Boolean)
+  if (payload?.folder) return [payload.folder, ...(payload.records || [])].filter(Boolean)
+  const list = Array.isArray(payload?.entities)
+    ? payload.entities
+    : Array.isArray(payload?.documents)
+      ? payload.documents
+      : null
+  if (list) return list.map(extractDocument).filter(Boolean)
+  const single = extractDocument(payload)
+  return single ? [single] : []
+}
+
 /**
  * @param {string[]} args
  * @param {object} [deps] - injectable seams for testing: `fetch` (default global
@@ -141,10 +204,12 @@ export async function pull(args = [], deps = {}) {
     return { exitCode: 0 }
   }
 
-  // GET a pull lane via the client and parse it as JSON. `doRequest` is a thunk
-  // returning the client's Response promise. 404 → null (deleted / no access); any
-  // failure is reported and returns null (the lane is skipped, not fatal).
-  const getJson = async (label, doRequest) => {
+  // GET a pull lane via the client and return `{ docs, etag }` from its `.uwx` (ZIP)
+  // body — `readPullDocuments` reads the entity files out of it (JSON fallback). A
+  // conditional request whose ETag matches returns `{ notModified: true }` (304, empty
+  // body). `doRequest` is a thunk returning the client's Response promise. 404 / any
+  // failure → null (the lane is skipped, not fatal).
+  const getDocs = async (label, doRequest) => {
     info(`Pulling ${colors.bright}${label}${colors.reset} from ${colors.dim}${client.origin}${colors.reset} …`)
     let res
     try {
@@ -158,15 +223,21 @@ export async function pull(args = [], deps = {}) {
       note(`${label}: not found (404) — it was deleted, or you lack access.`)
       return null
     }
+    if (res.status === 304) {
+      note(`${label}: unchanged (304)`)
+      return { notModified: true }
+    }
     if (!res.ok) {
       error(`${label} pull failed: HTTP ${res.status} ${res.statusText}`)
       if (res.status === 401 || res.status === 403) note("Credentials weren't accepted — supply a bearer with --token <bearer>.")
       return null
     }
     try {
-      return await res.json()
+      const etag = res.headers?.get?.('etag') ?? null
+      const docs = readPullDocuments(Buffer.from(await res.arrayBuffer()))
+      return { docs, etag }
     } catch (err) {
-      error(`Could not parse the ${label} response as JSON: ${err.message}`)
+      error(`Could not read the ${label} response: ${err.message}`)
       return null
     }
   }
@@ -176,25 +247,34 @@ export async function pull(args = [], deps = {}) {
   let records = 0
   let deleted = 0
 
-  // Lane 1 — content → config + pages/** + layout/**.
-  const siteDoc = extractDocument(
-    await getJson('content', () => client.pullSiteContent(siteContentUuid))
-  )
-  if (siteDoc) {
-    const report = siteContentDocumentToProject({ document: siteDoc, siteRoot: siteDir, prune })
-    pages += report.pages.length
-    sections += report.sections.length
-    deleted += report.deleted.length
+  // Conditional-pull cache: the last ETag seen per lane (opaque token — cached and
+  // echoed verbatim, never recomputed). Lives in the gitignored `.uniweb/`.
+  const cache = readPullCache(siteDir)
+  let etagContent = cache.content
+  let etagFolder = cache.folder
+
+  // Lane 1 — content → config + pages/** + layout/**. The .uwx carries a single
+  // entity (the site-content document). A 304 (unchanged) leaves local files as-is.
+  const content = await getDocs('content', () => client.pullSiteContent(siteContentUuid, { etag: etagContent }))
+  if (content && !content.notModified) {
+    const siteDoc = content.docs && (content.docs.find((d) => d?.info || d?.$model) || content.docs[0] || null)
+    if (siteDoc) {
+      const report = siteContentDocumentToProject({ document: siteDoc, siteRoot: siteDir, prune })
+      pages += report.pages.length
+      sections += report.sections.length
+      deleted += report.deleted.length
+    }
+    if (content.etag) etagContent = content.etag
   }
 
   // Lane 2 — folder → the folder + record files, keyed by the SAME site-content uuid
   // (the backend resolves the site's `@uniweb/folder` from it; the framework never
   // holds a folder uuid). Models are resolved by name (async) up front, so
-  // collectionsToProject keeps its synchronous contract.
+  // collectionsToProject keeps its synchronous contract. A 304 leaves files as-is.
   if (!noCollections) {
-    const payload = await getJson('collections', () => client.pullFolder(siteContentUuid))
-    if (payload) {
-      const { folderDoc, recordDocs } = splitCollectionsPull(payload)
+    const folder = await getDocs('collections', () => client.pullFolder(siteContentUuid, { etag: etagFolder }))
+    if (folder && !folder.notModified && folder.docs?.length) {
+      const { folderDoc, recordDocs } = splitCollectionsPull(folder.docs)
       const resolveModel = makeModelResolver({ client })
       const declByModel = new Map()
       for (const model of [...new Set(recordDocs.map((d) => d.$model).filter(Boolean))]) {
@@ -215,8 +295,12 @@ export async function pull(args = [], deps = {}) {
       for (const s of report.skipped) note(`↷ ${s.slug ?? s.uuid ?? '(record)'}: ${s.reason}`)
       for (const w of report.warnings) note(`! ${w}`)
     }
+    if (folder?.etag) etagFolder = folder.etag
   }
 
+  // Persist the ETags so the next pull is conditional (304 when unchanged).
+  writePullCache(siteDir, { content: etagContent, folder: etagFolder })
+
   success(
     `Pulled — ${pages} page(s), ${sections} section(s), ${records} record(s)` + (deleted ? `, ${deleted} deleted` : '')
   )

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/framework-index.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-06-17T20:00:18.933Z",
+  "generatedAt": "2026-06-23T17:13:47.118Z",
   "packages": {
     "@uniweb/build": {
-      "version": "0.14.15",
+      "version": "0.14.17",
       "path": "framework/build",
       "deps": [
         "@uniweb/content-reader",
@@ -61,7 +61,7 @@
       "deps": []
     },
     "@uniweb/runtime": {
-      "version": "0.8.19",
+      "version": "0.8.20",
       "path": "framework/runtime",
       "deps": [
         "@uniweb/core",
@@ -99,7 +99,7 @@
       "deps": []
     },
     "@uniweb/unipress": {
-      "version": "0.4.21",
+      "version": "0.4.23",
       "path": "framework/unipress",
       "deps": [
         "@uniweb/build",

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}`
+}