uniweb 0.12.33 → 0.12.34

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.12.33",
+  "version": "0.12.34",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -41,14 +41,14 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
-    "@uniweb/kit": "0.9.18",
     "@uniweb/core": "0.7.14",
+    "@uniweb/kit": "0.9.18",
     "@uniweb/runtime": "0.8.20"
   },
   "peerDependencies": {
-    "@uniweb/semantic-parser": "1.1.17",
-    "@uniweb/build": "0.14.16",
-    "@uniweb/content-reader": "1.1.12"
+    "@uniweb/build": "0.14.17",
+    "@uniweb/content-reader": "1.1.12",
+    "@uniweb/semantic-parser": "1.1.17"
   },
   "peerDependenciesMeta": {
     "@uniweb/build": {

package/partials/agents.md

@@ -1762,6 +1762,8 @@ export default {
 
 The content handler receives `block.parsedContent.data` and reads raw ProseMirror from `block.rawContent`. It returns a new ProseMirror document — the framework re-parses it through the semantic parser. Returning `null` or the same reference as `block.rawContent` signals no change.
 
+> **`instantiateContent` resolves `{placeholders}` in text nodes only** — not in link `href`s or other node/mark attributes. So `[{email}](mailto:{email})` fills the visible label but leaves the `mailto:` URL literal. For dynamic URLs, emit the value as plain text and let the component linkify it, or build the href in the handler yourself.
+
 ### Reserved frontmatter fields
 
 `source` and `where` are convention-level reserved fields — they flow through to both `block.properties` (for handler access) and `params` (visible to components). Components can ignore them. This is consistent with how `background` and `theme` work. List them in `meta.js` params with descriptions so the editor and schema recognize them.

package/src/backend/data-bundle.js

@@ -0,0 +1,43 @@
+/**
+ * Upload the static-data ball (assembleDataBall's `{ data, search }` doc) to the
+ * backend's content-addressed asset store via the SAME asset lane deploy uses for
+ * media, and return its durable serve URL — the `info.data_bundle` the composite push
+ * stamps on the site-content entity. The backend unwraps the ball into the `/data/*`
+ * + `/_search/*` bytes the gateway serves.
+ *
+ * The ball is in-memory (not a built file on disk), so it rides as `bytes` on the
+ * single upload entry — `uploadSiteAssets` PUTs `bytes` when present, else reads a
+ * `diskPath` (its media path). Content-addressed like every asset: identical ball →
+ * same id → a re-deploy of unchanged data is a cheap no-op PUT.
+ */
+
+import { createHash } from 'node:crypto'
+import { buildAssetUrl } from '../utils/asset-upload.js'
+
+/**
+ * @param {object} client - BackendClient (origin + uploadSiteAssets + discover)
+ * @param {{ data: object, search: object }} ball - the assembled data ball
+ * @param {{ onProgress?: (m: string) => void }} [opts]
+ * @returns {Promise<string>} the content-addressed serve URL (→ `info.data_bundle`)
+ */
+export async function uploadDataBundle(client, ball, { onProgress } = {}) {
+  const bytes = Buffer.from(JSON.stringify(ball))
+  const sha256 = createHash('sha256').update(bytes).digest('hex')
+  const localUrl = '/data-bundle/base.json' // bookkeeping key into assetsByLocalUrl
+
+  const result = await client.uploadSiteAssets({
+    files: [
+      { path: 'data-bundle/base.json', content_type: 'application/json', size: bytes.length, sha256, localUrl, bytes },
+    ],
+    onProgress,
+  })
+  if (result.failed?.length) {
+    const f = result.failed[0]
+    throw new Error(`data-bundle upload failed: HTTP ${f.status} ${f.detail}`)
+  }
+  const entry = result.assetsByLocalUrl[localUrl]
+  if (!entry) throw new Error('data-bundle upload returned no asset id')
+
+  const config = await client.discover()
+  return buildAssetUrl(client.origin, config.assetBase, entry.id, entry.ext)
+}

package/src/backend/site-media.js

@@ -0,0 +1,61 @@
+/**
+ * Upload a site's local media to the backend's content-addressed asset store via the
+ * SAME asset lane the data bundle rides, and return a `{ ref → serveUrl }` map for the
+ * deploy's second emit (`assetRewrite`) to swap the entity content refs for.
+ *
+ * Input is the site-root asset refs the producer surfaced in
+ * `emitSyncPackages().localAssets` (`/images/hero.png`); `resolveAssetPath` finds the
+ * file under the site's `public/` (or `assets/`). A ref whose file is missing is
+ * skipped (warned), never a broken serve URL. The serve URL is the backend's canonical
+ * `serve_url` when present, else reconstructed from `id`+`assetBase` (the dev fallback).
+ * Content-addressed like every asset: identical bytes → same id → a re-deploy of
+ * unchanged media is a cheap no-op PUT (the lane's `present` skip-list).
+ */
+
+import { createHash } from 'node:crypto'
+import { existsSync, readFileSync } from 'node:fs'
+import { basename } from 'node:path'
+import { resolveAssetPath } from '@uniweb/build/site'
+import { buildAssetUrl } from '../utils/asset-upload.js'
+import { contentTypeFor } from '../utils/code-upload.js'
+
+/**
+ * @param {object} client - BackendClient (origin + uploadSiteAssets + discover)
+ * @param {string} siteDir - the site root (site-root refs resolve under public/)
+ * @param {string[]} refs - site-root local asset refs (`/images/x.png`)
+ * @param {{ onProgress?: (m: string) => void, warn?: (m: string) => void }} [opts]
+ * @returns {Promise<Record<string,string>>} ref → serve URL (only resolved + uploaded refs)
+ */
+export async function uploadSiteMedia(client, siteDir, refs, { onProgress, warn } = {}) {
+  if (!refs?.length) return {}
+
+  const files = []
+  for (const ref of refs) {
+    const { resolved } = resolveAssetPath(ref, siteDir, siteDir)
+    if (!resolved || !existsSync(resolved)) {
+      warn?.(`local-media: ${ref} not found under the site (skipped)`)
+      continue
+    }
+    const bytes = readFileSync(resolved)
+    files.push({
+      path: ref.replace(/^\/+/, ''), // bookkeeping key into the plan (must be unique)
+      content_type: contentTypeFor(basename(resolved)),
+      size: bytes.length,
+      sha256: createHash('sha256').update(bytes).digest('hex'),
+      localUrl: ref, // the rewrite key — the original content ref
+      diskPath: resolved,
+    })
+  }
+  if (!files.length) return {}
+
+  const result = await client.uploadSiteAssets({ files, onProgress })
+  for (const f of result.failed || []) warn?.(`local-media: upload failed for ${f.path} (HTTP ${f.status})`)
+
+  const config = await client.discover()
+  const map = {}
+  for (const ref of refs) {
+    const entry = result.assetsByLocalUrl[ref]
+    if (entry) map[ref] = entry.serveUrl || buildAssetUrl(client.origin, config.assetBase, entry.id, entry.ext)
+  }
+  return map
+}

package/src/backend/site-sync.js

@@ -0,0 +1,246 @@
+/**
+ * site-sync — the reusable core of `uniweb push`: given a site's emitted sync
+ * packages, submit them over the two directional lanes (site-content first, then the
+ * folder keyed by the site's uuid), back-fill the minted uuids into the source files,
+ * and persist the send-only-changed cache. Extracted from the push command so
+ * `uniweb deploy` (the composite path) reuses the exact same lane submission.
+ *
+ * The command keeps flag parsing, the emit, and the `-o`/`--dry-run` preview;
+ * everything from "the packages are built, now POST them" lives here. Logging is
+ * injected via `report` ({ info, note, error, dim }) so each caller styles output its
+ * own way.
+ */
+
+import { writeFileSync, readFileSync, mkdirSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { backfillEntityUuids, writeSiteEntityUuid } from '@uniweb/build/uwx'
+
+// 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.
+export 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, so the extractor is deliberately 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.
+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.
+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')
+}
+export 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
+  }
+}
+export function writeSyncCache(siteDir, hashes) {
+  const p = syncCachePath(siteDir)
+  mkdirSync(dirname(p), { recursive: true })
+  writeFileSync(p, JSON.stringify({ version: 1, hashes }, null, 2) + '\n')
+}
+
+/**
+ * Submit a site's emitted sync packages over both directional lanes, back-fill the
+ * minted uuids, and persist the send-only-changed cache. The HTTP + file-write-back
+ * half that `emitSyncPackages` (producer-pure) deliberately omits.
+ *
+ * @param {object} params
+ * @param {object} params.client - BackendClient (carries the origin + the lane methods)
+ * @param {string} params.siteDir - the site root (for $uuid write-back + the cache)
+ * @param {object} params.pkg - the `emitSyncPackages` result
+ *        ({ siteContent, collections, siteContentUuid, hashes })
+ * @param {string|null} [params.asOrg] - act-as org (membership-gated), forwarded to each lane
+ * @param {{info,note,error,dim?:Function}} params.report - injected logging
+ * @returns {Promise<{ exitCode: number, boundSiteUuid?: string, finalizedTotal: number, wrote: string[] }>}
+ *   exitCode 1 on any lane failure (already reported, cache NOT persisted); 0 on success.
+ */
+export async function pushSyncPackages({ client, siteDir, pkg, asOrg, report }) {
+  const { siteContent, collections, siteContentUuid, hashes } = pkg
+  const { info, note, error } = report
+  const dim = report.dim || ((s) => s)
+
+  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 ${dim(client.origin)} …`)
+    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).")
+      } else if (res.status === 409) {
+        // The site's @uniweb/folder is genesis-owned: its structure is fixed on first
+        // deploy and not reconciled in place (the v1 rule — see gotcha #20's mode switch).
+        note(
+          "This site's collection structure is already established on the backend and can't be changed " +
+            'in place — e.g. adding or removing a schema-backed collection, or switching one between ' +
+            'static (data-bundle) and schema-backed delivery. To change it: delete the deployed site and ' +
+            'redeploy, or clear `$uuid` in site.yml to deploy a fresh one.'
+        )
+      }
+      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, wrote }
+      finalizedTotal += finalized.length
+    } else {
+      const payload = await postLane(
+        'site-content',
+        () => client.createSiteContent(siteContent.buffer, { asOrg })
+      )
+      if (payload === null) return { exitCode: 1, finalizedTotal, wrote }
+      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, finalizedTotal, wrote }
+      }
+      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, finalizedTotal, wrote }
+    }
+    const finalized = await pushLane(
+      'collections',
+      () => client.pushFolder(boundSiteUuid, collections.buffer, { asOrg })
+    )
+    if (!finalized) return { exitCode: 1, finalizedTotal, wrote }
+    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)
+  return { exitCode: 0, boundSiteUuid, finalizedTotal, wrote }
+}

package/src/commands/deploy.js

@@ -16,19 +16,22 @@
  * For static-host artifacts WITHOUT upload, see `uniweb export`. To publish a
  * site that already lives on the backend as a synced draft, see `uniweb release`.
  *
- * Uniweb-host flow (deployToUniwebBackend):
- *   1. Resolve the site dir + the deploy.yml target.
- *   2. discover() — the backend's anonymous capability handshake (GET /dev/config):
- *      delivery support + the installed-runtime list.
- *   3. Resolve the runtime: `site.yml::runtime` if pinned, else the highest
- *      version the backend reports installed (fail closed if neither resolves).
- *   4. Build the site data (link mode): site-content.json (+ per-locale variants),
- *      collection data, search indexes.
- *   5. Assemble the deploy payload (foundation, runtimeVersion, theme, languages,
- *      defaultLanguage, locales, optional dataFiles/searchFiles).
- *   6. POST /dev/deploy via BackendClient — the login bearer authorizes; on first
- *      deploy the backend mints a delivery uuid (round-tripped through
- *      deploy.yml::lastDeploy) and returns the serve URL.
+ * Uniweb-host flow (deployToUniwebBackend) — the composite deploy = build → ball →
+ * media → push → publish:
+ *   1. Resolve the site dir + deploy.yml target; discover() the backend (GET
+ *      /dev/config) and resolve the runtime (`site.yml::runtime` if pinned, else the
+ *      backend's highest installed; fail closed if neither resolves).
+ *   2. Build the site data (link mode): site-content.json (+ per-locale variants),
+ *      collection data, search indexes, processed assets.
+ *   3. Partition collections by schema presence: schema-less → the static-data ball;
+ *      schema-backed → typed folder entities on the push lane.
+ *   4. Upload the site's local media (entity refs + the ball's refs, one deduped set) →
+ *      each site-root ref's backend serve URL; rewrite the ball with it, then upload the
+ *      rewritten ball (content-addressed → `info.data_bundle`).
+ *   5. Push — the SAME two-lane sync `uniweb push` uses (site-content with
+ *      `info.data_bundle` stamped + media refs rewritten, then the folder + records) —
+ *      over the send-only-changed cache; the backend mints/round-trips the site uuid.
+ *   6. Publish — make the just-pushed composite live; the backend returns the serve URL.
  *
  * Usage:
  *   uniweb deploy                  Build + deploy to the resolved target
@@ -45,17 +48,20 @@
  */
 
 import { existsSync } from 'node:fs'
-import { readFile, readdir } from 'node:fs/promises'
-import { resolve, join, relative } from 'node:path'
+import { readFile } from 'node:fs/promises'
+import { resolve, join } from 'node:path'
 import { execSync } from 'node:child_process'
 import yaml from 'js-yaml'
 
-import { loadDeployYml, resolveTarget, recordLastDeploy, rewriteSiteContentPaths } from '@uniweb/build/site'
+import { loadDeployYml, resolveTarget, recordLastDeploy, assembleDataBall, collectBallAssets, rewriteBallAssets } from '@uniweb/build/site'
 import { promptForHost } from '../utils/host-prompt.js'
 import { readFlagValue } from '../utils/args.js'
 import { parseBoolEnv } from '../utils/env.js'
 import { BackendClient } from '../backend/client.js'
-import { collectSiteAssets } from '../utils/asset-upload.js'
+import { emitSyncPackages } from '@uniweb/build/uwx'
+import { makeModelResolver, readSyncCache, pushSyncPackages } from '../backend/site-sync.js'
+import { uploadDataBundle } from '../backend/data-bundle.js'
+import { uploadSiteMedia } from '../backend/site-media.js'
 
 import {
   findWorkspaceRoot,
@@ -262,27 +268,20 @@ async function deployToUniwebBackend(siteDir, siteYml, { foundation, args, dryRu
     command: 'Deploying',
   })
 
-  // Steer-hint (not enforced): a site that's been synced (has site.yml::$uuid) is
-  // CMS-managed — `uniweb release` publishes its current backend state, including
-  // app-side edits. `deploy` still works: it hosts the LOCAL file-built payload as
-  // a separate delivery (deploy ⊥ publish — alternative lifecycles, your choice).
-  if (siteYml.$uuid) {
-    say.warn('This site is synced (site.yml::$uuid) — CMS-managed.')
-    say.dim('`uniweb release` publishes its current backend state; `deploy` hosts your local files as a separate delivery.')
-  }
+  const foundationDir = readFlagValue(args, '--foundation') // optional local foundation for Model schemas
+  const asOrg = readFlagValue(args, '--as-org')
 
-  // Anonymous capability handshake (cached). Confirms the deploy lane is offered
-  // and supplies the installed-runtime list (the /dev/config replacement for the
-  // retired Worker /runtime/latest).
+  // Anonymous capability handshake (cached). The composite deploy ends in a publish,
+  // so confirm that lane is offered (the push/sync lanes are the backend's baseline).
   const config = await client.discover()
-  if (config?.delivery && config.delivery.deploy === false) {
-    say.err(`Backend at ${client.origin} does not offer the deploy lane (delivery.deploy=false).`)
+  if (config?.delivery && config.delivery.publish === false) {
+    say.err(`Backend at ${client.origin} does not offer the publish lane (delivery.publish=false).`)
     process.exit(1)
   }
 
   // Runtime resolution: an explicit site.yml::runtime pin wins; else the highest
   // version the backend reports installed; else fail closed with a clear
-  // precondition error (better than serving a site with no runtime — §9.4).
+  // precondition error (better than serving a site with no runtime).
   const installed = Array.isArray(config?.runtime?.installed) ? config.runtime.installed : []
   if (siteYml.runtime && installed.length && !installed.includes(siteYml.runtime)) {
     say.err(`Runtime ${siteYml.runtime} (from site.yml) is not installed on the backend.`)
@@ -296,23 +295,18 @@ async function deployToUniwebBackend(siteDir, siteYml, { foundation, args, dryRu
     process.exit(1)
   }
 
-  // deploy.yml uuid round-trip: a prior deploy recorded the minted delivery uuid
-  // under lastDeploy.<target>.siteUuid; resend it so /gateway/site/{uuid}/ stays
-  // stable. First deploy has none → the backend mints one and we write it back.
-  const priorUuid = readDeployedSiteUuid(deployYml, resolved.targetName)
-
   if (dryRun) {
-    say.info('Dry run — would deploy to the Uniweb backend:')
+    say.info('Dry run — would deploy to the Uniweb backend as a composite (ball → push → publish):')
     say.dim(`Backend     : ${client.origin}`)
     say.dim(`Foundation  : ${typeof foundation === 'string' ? foundation : foundation.ref}`)
     say.dim(`Runtime     : ${runtimeVersion}${siteYml.runtime ? '' : ' (highest installed)'}`)
-    say.dim(`site_uuid   : ${priorUuid || '(none — backend will mint)'}`)
+    say.dim(`site_uuid   : ${siteYml.$uuid || '(none — the first push mints it)'}`)
     return
   }
 
-  // Build (link mode): emits dist/site-content.json (+ per-locale variants under
-  // dist/<lang>/), dist/data/*, dist/_search/*. Spawn the SAME CLI binary that's
-  // running so the inner build can't resolve to a different installed version.
+  // Build (link mode): emits dist/data/*, dist/_search/*, dist/assets/*, and
+  // dist/site-content.json. Spawn the SAME CLI binary so the inner build can't resolve
+  // to a different installed version.
   say.info('Building site…')
   console.log('')
   execSync(`node ${JSON.stringify(process.argv[1])} build --link`, {
@@ -329,105 +323,125 @@ async function deployToUniwebBackend(siteDir, siteYml, { foundation, args, dryRu
     process.exit(1)
   }
 
-  const siteContent = JSON.parse(await readFile(contentPath, 'utf8'))
-  const languages = extractLanguages(siteContent)
-  const defaultLanguage = siteContent?.config?.defaultLanguage || languages[0] || 'en'
-  const theme = await readTheme(siteDir, siteContent)
-
-  // Per-locale content: default + each non-default dist/<lang>/site-content.json.
-  const localeContents = { [defaultLanguage]: siteContent }
-  for (const lang of languages) {
-    if (lang === defaultLanguage) continue
-    const p = join(distDir, lang, 'site-content.json')
-    if (existsSync(p)) localeContents[lang] = JSON.parse(await readFile(p, 'utf8'))
-    else say.warn(`Locale "${lang}" listed in site config but no dist/${lang}/site-content.json — skipping.`)
-  }
-
-  // Collection JSON (→ /data/<key>) and search indexes (→ /_search/<key>) — two
-  // distinct serve namespaces on the backend.
-  const dataFiles = await collectDataFiles(distDir)
-  if (Object.keys(dataFiles).length) say.dim(`Data files     : ${Object.keys(dataFiles).length} (collection JSON)`)
-  const searchFiles = await collectSearchFiles(distDir)
-  if (Object.keys(searchFiles).length) say.dim(`Search indexes : ${Object.keys(searchFiles).length} (_search/ JSON)`)
-
-  // Assets: when the backend advertises the lane (config.assets.supported), upload
-  // the site's processed media (dist/assets/*) to the content-addressed store and
-  // rewrite the content's local refs to durable serve URLs. Image-free sites
-  // collect nothing and deploy unchanged; an un-advertised lane is skipped.
-  // Contract: kb/framework/build/delivery-lane.md §Assets (channel f90d).
-  if (config?.assets && config.assets.supported === false) {
-    say.dim('Asset lane not yet available on this backend — skipping upload (image-free deploy).')
-  } else {
-    const assetFiles = collectSiteAssets(distDir)
-    if (assetFiles.length) {
-      say.info(`Uploading ${assetFiles.length} asset(s)…`)
-      let assetResult
-      try {
-        assetResult = await client.uploadSiteAssets({ distDir, files: assetFiles, onProgress: (m) => say.dim(`  ${m}`) })
-      } catch (err) {
-        say.err(`Asset upload failed: ${err.message}`)
-        process.exit(1)
-      }
-      if (assetResult.failed.length) {
-        say.err(`${assetResult.failed.length} asset(s) failed to upload:`)
-        for (const f of assetResult.failed) say.dim(`  ${f.path} — HTTP ${f.status} ${f.detail}`)
-        process.exit(1)
-      }
-      // Build localUrl → durable serve URL, then re-run the build's own rewrite
-      // over each locale's content (image nodes, marks, dataBlocks, param fields).
-      // assetBase comes from /dev/config (origin-relative in dev → prepend origin;
-      // absolute CDN in prod → used verbatim).
-      const urlMapping = {}
-      for (const [localUrl, { id, ext }] of Object.entries(assetResult.assetsByLocalUrl)) {
-        urlMapping[localUrl] = buildAssetUrl(client.origin, config.assetBase, id, ext)
-      }
-      for (const lang of Object.keys(localeContents)) {
-        localeContents[lang] = rewriteSiteContentPaths(localeContents[lang], urlMapping)
-      }
-      const skippedNote = assetResult.skipped?.length ? `, ${assetResult.skipped.length} already present` : ''
-      say.dim(`Assets         : ${assetResult.uploaded.length} uploaded${skippedNote} (${assetResult.mode}) → ${config.assetBase}`)
+  // Non-local @std/registry Model schemas resolve through the backend (same as push).
+  const resolveModel = makeModelResolver({ client, offline: false })
+
+  // 1. Partition the collections by schema presence. A first emit reads `schemaless`
+  //    — the collections with no data schema, delivered statically via the ball. Its
+  //    packages are discarded (deploy is not a hot path; the cheap clarity beats a
+  //    schemaless-only fast path, a later optimization).
+  let probe
+  try {
+    probe = await emitSyncPackages(siteDir, { ...(foundationDir ? { foundationDir } : {}), resolveModel })
+  } catch (err) {
+    say.err(`Could not build the sync package: ${err.message}`)
+    process.exit(1)
+  }
+  const schemalessNames = (probe.schemaless || []).map((col) => col.name)
+  const localAssets = probe.localAssets || [] // entity-content site-root media refs
+
+  // 2. Assemble the static-data ball (schema-less collection data + the search index) —
+  //    BEFORE uploading it, because its schema-less records can carry local media too,
+  //    which we upload + rewrite to serve URLs exactly like entity content (the backend
+  //    serves a serve_url in the ball identically — it unwraps the ball verbatim).
+  let ball = await assembleDataBall(distDir, schemalessNames)
+  const ballAssets = collectBallAssets(ball)
+
+  // 2b. Upload ALL local media (entity refs + ball refs) on one asset lane → the
+  //     ref→serveUrl map. The same map rewrites the entity content (assetRewrite, real
+  //     emit below) AND the ball (here, before it's uploaded). Co-located refs were
+  //     warned + skipped by the producer; a missing file is skipped here (warned).
+  let assetRewrite = null
+  const mediaRefs = [...new Set([...localAssets, ...ballAssets])]
+  if (mediaRefs.length) {
+    say.info('Uploading media…')
+    try {
+      const map = await uploadSiteMedia(client, siteDir, mediaRefs, {
+        onProgress: (m) => say.dim(`  ${m}`),
+        warn: (m) => say.dim(`! ${m}`),
+      })
+      if (Object.keys(map).length) assetRewrite = map
+      if (ballAssets.length) ball = rewriteBallAssets(ball, map) // swap the ball's local refs → serve URLs
+      say.dim(`Media          : ${Object.keys(map).length}/${mediaRefs.length} ref(s) → serve URL`)
+    } catch (err) {
+      say.err(`Media upload failed: ${err.message}`)
+      process.exit(1)
     }
   }
 
-  const payload = {
-    foundation,
-    runtimeVersion,
-    theme,
-    languages,
-    defaultLanguage,
-    ...(Object.keys(dataFiles).length ? { dataFiles } : {}),
-    ...(Object.keys(searchFiles).length ? { searchFiles } : {}),
-    // One entry per language — single-locale sites end up with { [default]: content };
-    // multi-locale carry per-locale translated content. Same shape as Editor publish.
-    locales: localeContents,
+  // 2c. Upload the (media-rewritten) ball. `data_bundle` is its content-addressed serve
+  //     URL; omitted when there is nothing static to deliver.
+  let dataBundle
+  if (ball) {
+    say.info('Uploading data bundle…')
+    try {
+      dataBundle = await uploadDataBundle(client, ball, { onProgress: (m) => say.dim(`  ${m}`) })
+    } catch (err) {
+      say.err(`Data bundle upload failed: ${err.message}`)
+      process.exit(1)
+    }
+    say.dim(`Data bundle    : ${Object.keys(ball.data).length} data + ${Object.keys(ball.search).length} search file(s)`)
+  }
+
+  // 3. Push the site (content + folder) over the send-only-changed cache — the SAME
+  //    two-lane submission `uniweb push` uses — stamping info.data_bundle on the
+  //    site-content entity and rewriting local media refs to their backend serve URLs.
+  const priorHashes = readSyncCache(siteDir)
+  let pkg
+  try {
+    pkg = await emitSyncPackages(siteDir, {
+      ...(foundationDir ? { foundationDir } : {}),
+      resolveModel,
+      priorHashes,
+      ...(dataBundle ? { injectInfo: { data_bundle: dataBundle } } : {}),
+      ...(assetRewrite ? { assetRewrite } : {}),
+    })
+  } catch (err) {
+    say.err(`Could not build the sync package: ${err.message}`)
+    process.exit(1)
+  }
+  for (const w of pkg.warnings) say.dim(`! ${w}`)
+  const report = {
+    info: (m) => say.info(m),
+    note: (m) => say.dim(m),
+    error: (m) => say.err(m),
+    dim: (s) => `${c.dim}${s}${c.reset}`,
+  }
+  const pushResult = await pushSyncPackages({ client, siteDir, pkg, asOrg, report })
+  if (pushResult.exitCode !== 0) process.exit(pushResult.exitCode)
+  const siteUuid = pushResult.boundSiteUuid
+  if (!siteUuid) {
+    say.err('Push did not yield a site uuid — cannot publish.')
+    process.exit(1)
   }
 
-  say.info(`Deploying to ${c.dim}${client.origin}${c.reset} …`)
-  let res
+  // 4. Publish: make the just-pushed composite live (its current backend state).
+  const siteContent = JSON.parse(await readFile(contentPath, 'utf8'))
+  const languages = extractLanguages(siteContent)
+  say.info(`Publishing to ${c.dim}${client.origin}${c.reset} …`)
+  let pubRes
   try {
-    res = await client.deploy(payload, { siteUuid: priorUuid || undefined })
+    pubRes = await client.publishSite(siteUuid, { runtimeVersion, ...(languages ? { languages } : {}) })
   } catch (err) {
     say.err(`Could not reach the backend at ${client.origin}: ${err.message}`)
     say.dim('Set the origin with --backend <url> or UNIWEB_REGISTER_URL.')
     process.exit(1)
   }
-  if (!res.ok) {
-    say.err(`Deploy rejected: HTTP ${res.status} ${res.statusText}`)
-    if (res.status === 401 || res.status === 403) {
+  if (!pubRes.ok) {
+    say.err(`Publish rejected: HTTP ${pubRes.status} ${pubRes.statusText}`)
+    if (pubRes.status === 401 || pubRes.status === 403) {
       say.dim("Credentials weren't accepted — run `uniweb login` (or pass --token <bearer>).")
     }
-    const body = await res.text().catch(() => '')
+    const body = await pubRes.text().catch(() => '')
     if (body) say.dim(body.slice(0, 800))
     process.exit(1)
   }
   let result
-  try { result = await res.json() } catch { result = {} }
-
-  const mintedUuid = result.site_uuid || priorUuid || null
+  try { result = await pubRes.json() } catch { result = {} }
   const serveUrl = absolutizeServeUrl(client.origin, result.url)
 
-  // Persist deploy memory + the minted uuid for the next round-trip. recordLastDeploy
-  // touches only lastDeploy.<target>, so siteUuid rides there safely.
+  // Persist deploy memory. One identity: site.yml::$uuid (the push uuid) — no separate
+  // deploy uuid. recordLastDeploy touches only lastDeploy.<target>.
   await persistLastDeploy(siteDir, {
     targetName: resolved.targetName,
     targetConfig: resolved.fromFile ? null : { host: 'uniweb' },
@@ -436,7 +450,7 @@ async function deployToUniwebBackend(siteDir, siteYml, { foundation, args, dryRu
       at: new Date().toISOString(),
       host: 'uniweb',
       backend: client.origin,
-      siteUuid: mintedUuid,
+      siteUuid,
       url: serveUrl,
       foundation: { ref: typeof foundation === 'string' ? foundation : foundation?.ref },
       runtime: runtimeVersion,
@@ -445,7 +459,7 @@ async function deployToUniwebBackend(siteDir, siteYml, { foundation, args, dryRu
   })
 
   console.log('')
-  say.ok(`Deployed ${c.bold}${mintedUuid || 'site'}${c.reset}`)
+  say.ok(`Deployed ${c.bold}${siteUuid}${c.reset}`)
   if (serveUrl) console.log(`  ${c.cyan}${serveUrl}${c.reset}`)
 }
 
@@ -457,12 +471,6 @@ function pickHighestRuntime(installed) {
   return [...installed].sort((a, b) => String(b).localeCompare(String(a), undefined, { numeric: true }))[0]
 }
 
-// The previously-minted delivery uuid for `targetName` (lastDeploy.<target>.siteUuid
-// in a loaded deploy.yml), or null on a first deploy / absent file.
-function readDeployedSiteUuid(deployYml, targetName) {
-  return deployYml?.lastDeploy?.[targetName]?.siteUuid || null
-}
-
 // The deploy response `url` is the serve path. When origin-relative (the self-serve
 // default, e.g. /gateway/site/<uuid>/) prefix the BackendClient origin so the printed
 // link is clickable; absolute URLs pass through unchanged.
@@ -472,15 +480,6 @@ function absolutizeServeUrl(origin, url) {
   return `${origin.replace(/\/$/, '')}${url.startsWith('/') ? '' : '/'}${url}`
 }
 
-// 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.
-function buildAssetUrl(origin, assetBase, id, ext) {
-  const base = /^https?:\/\//.test(assetBase) ? assetBase : `${origin}${assetBase}`
-  return `${base.replace(/\/$/, '')}/dist/${id}/base.${ext}`
-}
-
 // ─── Static-host deploy (S3+CloudFront, etc.) ─────────────────
 //
 // Distinct from the uniweb-edge flow above. Picked when the resolved
@@ -679,66 +678,3 @@ function extractLanguages(siteContent) {
   // Three accepted shapes: plain `'en'`, Editor `{ value, label }`, site.yml `{ code, label }`.
   return langs.map((l) => (typeof l === 'string' ? l : l?.value || l?.code)).filter(Boolean)
 }
-
-// Collect compiled collection JSON files from dist/data/ recursively.
-// Returns `{ '<relPath>': '<utf8-content>' }` keyed by the path under data/
-// so the worker can write each to `${sitePrefix}/data/<relPath>` in R2.
-// Empty object when the site has no `collection:` data sources.
-async function collectDataFiles(distDir) {
-  const dataDir = join(distDir, 'data')
-  if (!existsSync(dataDir)) return {}
-  const files = {}
-  const entries = await readdir(dataDir, { withFileTypes: true, recursive: true })
-  for (const entry of entries) {
-    if (!entry.isFile()) continue
-    if (!entry.name.endsWith('.json')) continue
-    const fullPath = join(entry.parentPath || entry.path, entry.name)
-    const relPath = relative(dataDir, fullPath)
-    files[relPath] = await readFile(fullPath, 'utf8')
-  }
-  return files
-}
-
-// Collect search index files from dist/_search/ recursively.
-// Returns `{ '<locale>/<name>.json': '<utf8-content>' }` so the worker can
-// write each to `${sitePrefix}/_search/<key>` in R2, gated by searchEnabled.
-// Empty object when the build emitted no search indexes.
-async function collectSearchFiles(distDir) {
-  const searchDir = join(distDir, '_search')
-  if (!existsSync(searchDir)) return {}
-  const files = {}
-  const entries = await readdir(searchDir, { withFileTypes: true, recursive: true })
-  for (const entry of entries) {
-    if (!entry.isFile()) continue
-    if (!entry.name.endsWith('.json')) continue
-    const fullPath = join(entry.parentPath || entry.path, entry.name)
-    const relPath = relative(searchDir, fullPath)
-    files[relPath] = await readFile(fullPath, 'utf8')
-  }
-  return files
-}
-
-/**
- * Resolve theme config.
- *
- * The build pipeline does not (today) emit a separate theme.json, so we read
- * the developer-authored theme.yml from the site root. The Worker's
- * `buildTheme()` tolerates an empty config — sites with no theme.yml still
- * publish, they just get default tokens.
- */
-async function readTheme(siteDir, siteContent) {
-  const themePath = join(siteDir, 'theme.yml')
-  if (existsSync(themePath)) {
-    try {
-      const parsed = yaml.load(await readFile(themePath, 'utf8'))
-      if (parsed && typeof parsed === 'object') return parsed
-    } catch {
-      // fall through to site-content.json fallback
-    }
-  }
-  // site-content sometimes carries a `theme` key produced by collectors.
-  if (siteContent?.theme && typeof siteContent.theme === 'object') {
-    return siteContent.theme
-  }
-  return {}
-}

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-18T03:42:23.549Z",
+  "generatedAt": "2026-06-23T17:13:47.118Z",
   "packages": {
     "@uniweb/build": {
-      "version": "0.14.16",
+      "version": "0.14.17",
       "path": "framework/build",
       "deps": [
         "@uniweb/content-reader",
@@ -99,7 +99,7 @@
       "deps": []
     },
     "@uniweb/unipress": {
-      "version": "0.4.22",
+      "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}`
+}