uniweb 0.25.0 → 0.25.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.25.0",
+  "version": "0.25.1",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -41,14 +41,15 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
-    "@uniweb/core": "^0.10.0",
-    "@uniweb/kit": "^0.12.2",
-    "@uniweb/runtime": "^0.12.0"
+    "@uniweb/semantic-parser": "^1.2.3",
+    "@uniweb/kit": "^0.12.3",
+    "@uniweb/runtime": "^0.12.1",
+    "@uniweb/core": "^0.10.1"
   },
   "peerDependencies": {
-    "@uniweb/build": "^0.24.0",
-    "@uniweb/semantic-parser": "^1.2.2",
-    "@uniweb/content-reader": "^1.2.2"
+    "@uniweb/build": "^0.24.1",
+    "@uniweb/content-reader": "^1.2.3",
+    "@uniweb/semantic-parser": "^1.2.3"
   },
   "peerDependenciesMeta": {
     "@uniweb/build": {

package/src/backend/asset-download.js

@@ -0,0 +1,144 @@
+/**
+ * Fetch the asset bytes a site project does not have locally.
+ *
+ * `pull` and `clone` bring content down; this brings the media with it, so a
+ * teammate who clones gets a project that renders instead of one full of images
+ * pointing at a host they may not even be able to reach.
+ *
+ * ## Where an asset lands, and why there are two answers
+ *
+ * - **The map knows it** (`assets.json`) — the file goes back to the path its
+ *   author wrote. That is the whole reason the map is committed: a fresh clone
+ *   restores `public/images/hero.png`, not a hash.
+ * - **The map does not know it** — this project has never held these bytes:
+ *   authored in the app, or pushed from a machine whose map entry has not
+ *   arrived. There is no local path to guess, so it lands at a **generic,
+ *   content-addressed** one (`/assets/{id}.{ext}`) and the map gains the entry.
+ *   From then on it is a known asset like any other.
+ *
+ * ## ⛔ The URL is READ from the content, never composed
+ *
+ * Identity rides beside the reference (`sync-package.js` stamps `assetId` next
+ * to the serve URL), so the address is already on the node. Composing one would
+ * mean holding the host's route layout — the coupling deleting `buildAssetUrl`
+ * removed from this CLI, and the reason `assets.json` stores no URL either. An
+ * id with no URL beside it is skipped, not guessed at.
+ *
+ * ## ⛔ A failed download is a WARNING, never a failed pull
+ *
+ * The content still carries the URL, so a site whose bytes did not arrive still
+ * renders — from the host, as it did before. Making the pull fail would turn a
+ * degraded outcome into no outcome, and the degraded one is genuinely usable.
+ */
+
+import { mkdirSync, existsSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { ASSET_SLOTS } from '@uniweb/semantic-parser'
+import { readAssetMap, updateAssetMap } from '@uniweb/build/uwx'
+
+/**
+ * Collect every `{ id, ext, url }` an entity document references.
+ *
+ * Reads the same shape `rewriteEntityAssets` writes — identity on the object
+ * carrying the reference — so a ProseMirror image node's attrs and a section
+ * background's media object are both found by one walk.
+ */
+export function collectAssetRefs(document) {
+  const found = new Map() // id → { id, ext, url }
+  const visit = (node) => {
+    if (Array.isArray(node)) return node.forEach(visit)
+    if (!node || typeof node !== 'object') return
+    for (const slot of ASSET_SLOTS) {
+      const id = typeof node[slot.id] === 'string' ? node[slot.id] : null
+      if (!id || found.has(id)) continue
+      const url = slot.urls
+        .map((k) => (typeof node[k] === 'string' ? node[k] : null))
+        .find(Boolean)
+      found.set(id, { id, ext: node[slot.ext] || '', url })
+    }
+    for (const v of Object.values(node)) visit(v)
+  }
+  visit(document)
+  return [...found.values()]
+}
+
+/** Where a site-root ref lives on disk. `resolveAssetPath` looks in public/ first. */
+const diskPathFor = (siteDir, ref) => join(siteDir, 'public', ref)
+
+/** The generic landing path for an asset this project has never held. */
+export const genericRefFor = (id, ext) => `/assets/${id}${ext ? `.${ext}` : ''}`
+
+/**
+ * Download the assets `document` references that are not already on disk.
+ *
+ * @param {object} opts
+ * @param {object} opts.document  - the site-content document (not mutated)
+ * @param {string} opts.siteDir   - the site root
+ * @param {string} opts.origin    - backend origin, to resolve an origin-relative URL
+ * @param {typeof fetch} [opts.fetchImpl]
+ * @param {(m: string) => void} [opts.onProgress]
+ * @param {(m: string) => void} [opts.warn]
+ * @returns {Promise<{ downloaded: string[], present: string[], failed: string[], skipped: string[] }>}
+ */
+export async function downloadMissingAssets({
+  document,
+  siteDir,
+  origin,
+  fetchImpl,
+  onProgress = () => {},
+  warn = () => {}
+}) {
+  const doFetch = fetchImpl || ((u) => globalThis.fetch(u))
+  const refs = collectAssetRefs(document)
+  const out = { downloaded: [], present: [], failed: [], skipped: [] }
+  if (!refs.length) return out
+
+  const map = readAssetMap(siteDir)
+  const byId = new Map()
+  for (const [ref, v] of Object.entries(map)) if (v?.id) byId.set(v.id, ref)
+
+  const learned = {}
+
+  for (const { id, ext, url } of refs) {
+    const known = byId.get(id)
+    const ref = known || genericRefFor(id, ext)
+    const disk = diskPathFor(siteDir, ref)
+
+    if (existsSync(disk)) {
+      out.present.push(ref)
+      // Still record identity for a generic ref we already hold but never mapped.
+      if (!known) learned[ref] = { id, ext }
+      continue
+    }
+    if (!url) {
+      // Identity with no address beside it. Composing one would mean holding the
+      // host's route layout; skipping is the honest answer.
+      warn(`asset ${id}: no URL in content to fetch from (skipped)`)
+      out.skipped.push(ref)
+      continue
+    }
+
+    try {
+      const res = await doFetch(new URL(url, origin).href)
+      if (!res.ok) {
+        warn(`asset ${id}: HTTP ${res.status} (kept the URL in content)`)
+        out.failed.push(ref)
+        continue
+      }
+      const bytes = Buffer.from(await res.arrayBuffer())
+      mkdirSync(dirname(disk), { recursive: true })
+      writeFileSync(disk, bytes)
+      onProgress(`↓ ${ref}`)
+      out.downloaded.push(ref)
+      if (!known) learned[ref] = { id, ext }
+    } catch (err) {
+      warn(`asset ${id}: ${err.message} (kept the URL in content)`)
+      out.failed.push(ref)
+    }
+  }
+
+  // Newly-landed assets become known ones, so the next pull restores them to
+  // this path rather than fetching them again to a second location.
+  if (Object.keys(learned).length) updateAssetMap(siteDir, learned)
+  return out
+}

package/src/backend/client.js

@@ -85,16 +85,20 @@ export function resolveBackendOrigin(flag, { siteBackend } = {}) {
 /**
  * The fallback capability doc when `GET /dev/config` is absent or unreachable
  * (an older backend, or no backend at all). Keeps the client non-breaking: the
- * bases mirror a self-serve dev backend, `assetBase` falls back to the historical
- * production CDN host so published-site asset resolution is unchanged, and
- * `runtime.installed` is empty so runtime resolution requires an explicit pin.
+ * bases mirror a self-serve dev backend, and `runtime.installed` is empty so
+ * runtime resolution requires an explicit pin.
  */
 export const DISCOVERY_DEFAULTS = {
-  // No serve-root default. Serve locations are read from discovery or from an
-  // upload plan's `serve_base`; nothing here reconstructs one, so a default
-  // would be a route name with no consumer. (A `gatewayBase` entry lived here
-  // unread until 2026-07-29.)
-  assetBase: 'https://assets.uniweb.app/',
+  // ⛔ No serve-root default, and no `assetBase`. Serve locations are read from
+  // discovery or from a per-response field (an upload plan's `serve_base`, an
+  // asset entry's `serve_url`); nothing here reconstructs one, so a default is a
+  // route name with no consumer. (A `gatewayBase` entry lived here unread until
+  // 2026-07-29.)
+  //
+  // `assetBase: 'https://assets.uniweb.app/'` sat here until 2026-08-17 — one
+  // production host, hardcoded, applied to EVERY deployment the CLI can be
+  // pointed at. It was only ever read to compose an asset URL, which the plan
+  // already returns as `serve_url`; both the reader and the composer are gone.
   auth: { loginPath: '/dev/auth/login', required: true },
   delivery: { deploy: true, publish: true, broker: 'self-serve' },
   assets: { supported: false },
@@ -220,7 +224,6 @@ export class BackendClient {
    * lifetime; a missing route or any transport/parse error falls back to
    * DISCOVERY_DEFAULTS (non-breaking — an older backend still works). Lets the
    * CLI hardcode nothing about a backend but its origin and discover the rest:
-   * `assetBase` (the asset root — relative ⇒ relative-to-origin),
    * `auth`, `delivery` (deploy/publish? broker), `assets` (lane built yet?),
    * `runtime.installed` (the default-runtime source replacing the old /runtime/latest).
    * @returns {Promise<object>}
@@ -509,7 +512,7 @@ export class BackendClient {
   }
 
   /**
-   * ASSUMED endpoint (not built yet — kb/framework/build/payment-handoff-plan.md).
+   * ASSUMED endpoint (not built yet).
    * GET /dev/site/{uuid}/can-go-live — the pre-go-live payment gate:
    *   { ok: true }                                          // already paid → proceed
    *   { payment_required: true, checkout_url, wait_token? } // open the URL, settle, retry
@@ -533,8 +536,8 @@ export class BackendClient {
   /**
    * Deliver a site's processed assets (plan → PUT-per-file) to the backend's
    * content-addressed store. Thin pass-through to utils/asset-upload.js with this
-   * client's origin + token; returns the `localUrl → { id, ext }` rewrite map the
-   * deploy step turns into durable `{assetBase}dist/{id}/base.{ext}` serve URLs.
+   * client's origin + token; returns the `localUrl → { id, ext, serveUrl }` rewrite
+   * map the deploy step reads `serveUrl` from verbatim (never composing one).
    * @param {object} opts - { distDir, files?, onProgress? }
    */
   async uploadSiteAssets(opts) {

package/src/backend/data-bundle.js

@@ -9,13 +9,15 @@
  * 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.
+ *
+ * The returned URL is the plan entry's `serve_url`, read verbatim. See the note at
+ * the return for why the origin-relative form is safe to store.
  */
 
 import { createHash } from 'node:crypto'
-import { buildAssetUrl } from '../utils/asset-upload.js'
 
 /**
- * @param {object} client - BackendClient (origin + uploadSiteAssets + discover)
+ * @param {object} client - BackendClient (origin + uploadSiteAssets)
  * @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`)
@@ -50,6 +52,34 @@ export async function uploadDataBundle(
   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)
+  // The backend's canonical serve URL, READ — never composed. Same rule and the
+  // same code path as `site-media.js`; until 2026-08-17 this composed from a
+  // discovered `assetBase` unconditionally, which made it the one place a
+  // discovery failure could bake the historical production CDN host into content
+  // we push.
+  //
+  // Storing it verbatim is safe even though `serve_url` is ORIGIN-RELATIVE in the
+  // backend's `direct` mode — the only mode any deployment has ever run.
+  // `info.data_bundle` is never fetched over HTTP: the backend resolves it to a
+  // blob-store key, discarding everything before the final `dist/`, so absolute
+  // and relative forms resolve to the same key (pinned both ways on their side).
+  //
+  // ⚠️ That argument is scoped to a serve URL CONTAINING `dist/`, and the scope is
+  // load-bearing rather than incidental: the key is recovered by splitting on that
+  // segment, so a serve URL without one cannot be resolved to a key at all — the
+  // failure is on the READING side, and this push looks entirely successful.
+  // Reported by the backend 2026-08-17 as a defect on their side, not yet fixed;
+  // not verified here, and not ours to fix. It is unreached only because no
+  // deployment yet mints URLs of the other shape. ⇒ We keep reading `serve_url`
+  // verbatim — composing one would be the worse answer, and it is the very coupling
+  // deleted above. What we must NOT do is infer from "this has always worked" that
+  // any serve URL round-trips; that holds for the shape, not for the field.
+  //
+  // Absent is an error, not a cue to invent a location: an unaddressable bundle
+  // must stop the publish, never ship a URL nobody claimed. (Confirmed with the
+  // backend 2026-08-17; `serve_url` is contractually on every plan entry.)
+  if (!entry.serveUrl)
+    throw new Error('data-bundle upload returned no serve_url')
+
+  return entry.serveUrl
 }

package/src/backend/site-media.js

@@ -7,7 +7,7 @@
  * `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).
+ * `serve_url`, read verbatim — origin-relative forms included; nothing here composes one.
  * 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).
  */
@@ -16,18 +16,18 @@ 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 {object} client - BackendClient (uploadSiteAssets). No `discover` — this
+ *        lane stopped consulting the capability doc when `assetBase` was removed.
  * @param {string} siteDir - the site root (site-root refs resolve under public/)
  * @param {string[]} refs - site-root local asset refs (`/images/x.png`)
  * @param {{ siteUuid?: string|null, onProgress?: (m: string) => void, warn?: (m: string) => void }} [opts]
  *   `siteUuid` is the owner the uploaded bytes are charged to. Callers create the
  *   site before uploading precisely so this is set — an unowned upload is charged
  *   and cannot be freed, because freeing means deleting the owning entity.
- * @returns {Promise<{ map: Record<string,string>, missing: string[], failed: Array<{path:string,status:number,detail?:string}> }>}
+ * @returns {Promise<{ map: Record<string,string>, ids: Record<string,{id:string,ext:string}>, missing: string[], failed: Array<{path:string,status:number,detail?:string}> }>}
  *   `map` is ref → serve URL for refs that resolved AND uploaded. The two failure
  *   kinds are reported SEPARATELY because callers must treat them differently:
  *   `missing` is a ref with no file under the site — an authoring mistake, already
@@ -41,7 +41,7 @@ export async function uploadSiteMedia(
   refs,
   { siteUuid = null, onProgress, warn } = {}
 ) {
-  if (!refs?.length) return { map: {}, missing: [], failed: [] }
+  if (!refs?.length) return { map: {}, ids: {}, missing: [], failed: [] }
 
   const files = []
   const missing = []
@@ -62,23 +62,46 @@ export async function uploadSiteMedia(
       diskPath: resolved
     })
   }
-  if (!files.length) return { map: {}, missing, failed: [] }
+  if (!files.length) return { map: {}, ids: {}, missing, failed: [] }
 
   const result = await client.uploadSiteAssets({ files, siteUuid, onProgress })
-  const failed = result.failed || []
+  const failed = [...(result.failed || [])]
   for (const f of failed)
     warn?.(`local-media: upload failed for ${f.path} (HTTP ${f.status})`)
 
-  const config = await client.discover()
   const map = {}
+  // The identity half, for `assets.json`. The plan returns an authoritative
+  // `id`+`ext` for every entry INCLUDING a `present: true` dedup skip, so a
+  // re-push of unchanged media still records identity without moving bytes —
+  // which is what makes the committed map cheap to keep accurate.
+  const ids = {}
   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)
+    if (!entry) continue
+    if (entry.id) ids[ref] = { id: entry.id, ext: entry.ext || '' }
+    // The backend's canonical serve URL, READ — never composed. An entry without
+    // one is an asset we cannot address, and inventing a location for it is the
+    // exact failure this lane exists to avoid: a guessed host is SILENTLY wrong,
+    // where a missing one is visibly missing. So it joins `failed` and publish
+    // refuses, rather than shipping content pointing somewhere nobody claimed.
+    //
+    // `serve_url` is part of the asset-plan contract: on EVERY entry, both
+    // lanes, including entries reported as already `present`. Reconstruction
+    // from a discovered `assetBase` was removed once the backend covered that
+    // with a test of its own; it was the last hardcoded cross-deployment
+    // constant in the CLI. (Confirmed 2026-08-17.)
+    if (!entry.serveUrl) {
+      warn?.(`local-media: ${ref} — the asset plan returned no serve_url`)
+      failed.push({
+        path: ref,
+        status: 0,
+        detail: 'asset plan entry carried no serve_url'
+      })
+      continue
+    }
+    map[ref] = entry.serveUrl
   }
-  return { map, missing, failed }
+  return { map, ids, missing, failed }
 }
 
 // ─── Asset-plan refusals ──────────────────────────────────────────────────────

package/src/commands/clone.js

@@ -2,7 +2,7 @@
  * uniweb clone <site-uuid> — materialize a backend site as a local file project.
  *
  * The "git clone" of the site-content remote model (see
- * kb/framework/plans/site-content-remote-model.md): the backend is the remote, a
+ * the site-content remote model): the backend is the remote, a
  * file project is a working clone. `clone` is the create-side sibling of
  * `uniweb pull`/`uniweb push` — it bootstraps a brand-new project from a site that
  * already lives in the backend (typically authored in the visual app).

package/src/commands/publish.js

@@ -81,6 +81,7 @@ import {
 } from '../backend/site-sync.js'
 import { uploadDataBundle } from '../backend/data-bundle.js'
 import { uploadSiteMedia, describeAssetRefusal } from '../backend/site-media.js'
+import { updateAssetMap, ASSET_MAP_FILE } from '@uniweb/build/uwx'
 import {
   bringFoundationAlong,
   bringExtensionsAlong
@@ -273,10 +274,32 @@ export async function publish(args = []) {
   // X, and the next publish would restate a *different* version the producer
   // computed locally, silently undoing it.
   //
-  // Silence is not a request to change the runtime, so the backend resolves it:
-  // the site's CURRENT resolved runtime → UNIWEBD_DEFAULT_RUNTIME → (self-serve)
-  // highest installed → 400. That keeps a propagated site where the walk put it,
-  // and it is the authority's answer rather than ours.
+  // The deeper reason, upstream of ownership: a link-mode site is CODELESS. It
+  // ships no JS, so it has nothing that binds to a runtime version and cannot
+  // break when the runtime moves. Asking it to name one is not a hard question,
+  // it is a malformed one. The party that binds is the FOUNDATION, whose build
+  // externalizes react / react-dom / jsx-runtime / @uniweb/core — which is why
+  // the compatibility floor rides on the foundation (`info.runtime`, set by
+  // `register`) and not here. See
+  // the site/foundation/runtime model, § "who gets to say
+  // whether a site accepts a newer runtime".
+  //
+  // Silence is therefore not a request to change the runtime, and the backend
+  // resolves it: an explicit pin → the site's CURRENT resolved runtime →
+  // UNIWEBD_DEFAULT_RUNTIME → (self-serve) highest installed.
+  //
+  // ⚠️ THAT LAST SENTENCE IS A CLAIM ABOUT ANOTHER LANE, and it was FALSE when it
+  // was first written here — `/dev/site/publish` required `?runtime=` with no
+  // fallback at all, so an unpinned publish 400'd and no scaffolded project could
+  // publish. It read as true because the `/api` lane did have the fallback, and
+  // the backend's own doc justified the omission with "the CLI always pins from
+  // site.yml" — which was equally false, since no template ships a `runtime:` key.
+  // Two complementary assumptions, each load-bearing for the other lane, neither
+  // ever checked. Found by driving the CLI against a live backend, which is the
+  // only vantage point from which either assumption is visible.
+  // ✅ Now the shipped contract, agreed with the backend and verified end to end
+  // with the workaround removed (2026-08-16). Re-verify against the backend
+  // rather than trusting this comment if it starts mattering again.
   //
   // ⚠️ Do NOT reintroduce a local fallback. Sending our own guess when the site
   // did not ask is what makes an unpinned republish regress. (The pinned path is
@@ -505,11 +528,12 @@ export async function publish(args = []) {
   // 4b. Upload ALL local media (entity refs + ball refs) on one asset lane →
   //     the ref→serveUrl map; rewrite the entity content AND the ball with it.
   let assetRewrite = null
+  let assetIds = null
   const mediaRefs = [...new Set([...localAssets, ...ballAssets])]
   if (mediaRefs.length) {
     say.info('Uploading media…')
     try {
-      const { map, failed } = await uploadSiteMedia(
+      const { map, ids, failed } = await uploadSiteMedia(
         client,
         siteDir,
         mediaRefs,
@@ -529,6 +553,15 @@ export async function publish(args = []) {
         return { exitCode: 1 }
       }
       if (Object.keys(map).length) assetRewrite = map
+      if (Object.keys(ids).length) assetIds = ids
+      // Identity into the COMMITTED map — see backend/asset-map.js. Merge, not
+      // replace: this publish carries only the refs its content touched.
+      const rec = updateAssetMap(siteDir, ids)
+      if (rec.written) {
+        say.dim(
+          `${ASSET_MAP_FILE}   : ${rec.added.length} added, ${rec.changed.length} changed — commit it`
+        )
+      }
       if (ballAssets.length) ball = rewriteBallAssets(ball, map)
       say.dim(
         `Media          : ${Object.keys(map).length}/${mediaRefs.length} ref(s) → serve URL`
@@ -615,7 +648,8 @@ export async function publish(args = []) {
       ...(Object.keys(ext.pins).length
         ? { injectExtensions: ext.pins }
         : {}),
-      ...(assetRewrite ? { assetRewrite } : {})
+      ...(assetRewrite ? { assetRewrite } : {}),
+      ...(assetIds ? { assetIds } : {})
     })
   } catch (err) {
     say.err(`Could not build the sync package: ${err.message}`)

package/src/commands/pull.js

@@ -68,6 +68,7 @@ import { createHash } from 'node:crypto'
 import { createInterface } from 'node:readline/promises'
 import { join, dirname, relative } from 'node:path'
 import yaml from 'js-yaml'
+import { downloadMissingAssets } from '../backend/asset-download.js'
 import {
   siteContentDocumentToProject,
   collectionsToProject,
@@ -127,6 +128,29 @@ function flagValue(args, name) {
   return null
 }
 
+// Whether this pull should fetch the asset bytes it does not have.
+//
+// Two levers, and they are deliberately not the same kind of thing:
+//   - `site.yml::assets.download: false` — the PROJECT's standing choice. "We do
+//     not keep the bytes here" is usually a property of a repo, not of a run, and
+//     a property of a repo belongs in a file every clone reads.
+//   - `--no-assets` — the RUN's override, for CI and one-off checkouts, where the
+//     project's answer is right and this invocation is the exception.
+//
+// The flag can only turn fetching OFF. A project that declared `download: false`
+// meant it, and a flag that could silently re-enable it would make the declared
+// setting advisory.
+function shouldFetchAssets(args, siteDir) {
+  if (args.includes('--no-assets')) return false
+  try {
+    const cfg = yaml.load(readFileSync(join(siteDir, 'site.yml'), 'utf8'))
+    if (cfg?.assets?.download === false) return false
+  } catch {
+    /* no site.yml, or unreadable — fetching is the default */
+  }
+  return true
+}
+
 // Read a top-level `$uuid:` scalar from a YAML file, or null.
 function readYamlUuid(filePath) {
   try {
@@ -494,6 +518,7 @@ export async function pull(args = [], deps = {}) {
   const mergeMode = args.includes('--merge')
 
   const siteDir = await resolveSiteDir(args, 'pull')
+  const fetchAssets = shouldFetchAssets(args, siteDir)
 
   // Don't overwrite work that isn't saved anywhere. Pull reconciles the working
   // tree to the backend — it rewrites section bodies from the fetched document and
@@ -640,6 +665,33 @@ export async function pull(args = [], deps = {}) {
       // Per-item identity for the next push. Without it the backend reads our
       // records as new and re-mints every page and section row.
       writeItemUuids(siteDir, collectUnitUuids(siteDoc))
+      // Bring the media down BEFORE projecting: a newly-landed asset gains a map
+      // entry, and the projection reads that map to put authored paths back. Run
+      // after, and this pull's new assets would project as URLs and only restore
+      // on the NEXT pull — a lag nobody would attribute to ordering.
+      //
+      // Declining is a project-level choice (`site.yml::assets.download: false`)
+      // with a per-run override (`--no-assets`), because "we do not want the
+      // bytes" is usually a property of the project and only sometimes of the
+      // invocation (CI). Either way the content keeps its URL and still renders.
+      if (fetchAssets) {
+        const dl = await downloadMissingAssets({
+          document: siteDoc,
+          siteDir,
+          origin: client.origin,
+          onProgress: (m) => note(`  ${m}`),
+          warn: (m) => note(`! ${m}`)
+        })
+        if (dl.downloaded.length) {
+          note(`Assets        : ${dl.downloaded.length} downloaded`)
+        }
+        if (dl.failed.length) {
+          note(
+            `Assets        : ${dl.failed.length} could not be fetched — content keeps their URL`
+          )
+        }
+      }
+
       const report = siteContentDocumentToProject({
         document: siteDoc,
         siteRoot: siteDir,

package/src/commands/push.js

@@ -64,6 +64,7 @@ import { writeFileSync } from 'node:fs'
 import { resolve } from 'node:path'
 import { emitSyncPackages } from '@uniweb/build/uwx'
 import { uploadSiteMedia, describeAssetRefusal } from '../backend/site-media.js'
+import { updateAssetMap, ASSET_MAP_FILE } from '@uniweb/build/uwx'
 import { BackendClient } from '../backend/client.js'
 import { resolveSiteDir, resolveSiteBackend } from './deploy.js'
 import { warnIfContentDoesNotConform } from '../utils/conformance.js'
@@ -246,6 +247,7 @@ export async function push(args = [], deps = {}) {
   // stores hashes of the REWRITTEN content, so the emit compared against it must
   // rewrite too, or every entity reads as changed forever.
   let assetRewrite = null
+  let assetIds = null
   if (!output && !dryRun) {
     let mediaRefs = []
     try {
@@ -276,7 +278,7 @@ export async function push(args = [], deps = {}) {
       }
       info('Uploading media…')
       try {
-        const { map, failed } = await uploadSiteMedia(
+        const { map, ids, failed } = await uploadSiteMedia(
           client,
           siteDir,
           mediaRefs,
@@ -299,9 +301,18 @@ export async function push(args = [], deps = {}) {
           return { exitCode: 1 }
         }
         if (Object.keys(map).length) assetRewrite = map
+        if (Object.keys(ids).length) assetIds = ids
         note(
           `${Object.keys(map).length}/${mediaRefs.length} media ref(s) → serve URL`
         )
+        // Record identity in the COMMITTED map. Merge, never replace: this push
+        // carries only the refs its content touched.
+        const rec = updateAssetMap(siteDir, ids)
+        if (rec.written) {
+          note(
+            `${ASSET_MAP_FILE}: ${rec.added.length} added, ${rec.changed.length} changed — commit it`
+          )
+        }
       } catch (err) {
         // Typed plan refusals get their own account. Note the storage one must not
         // be phrased from what moved — see describeAssetRefusal's rule 1; a push can
@@ -341,7 +352,8 @@ export async function push(args = [], deps = {}) {
             baseVersions: readBaseVersions(siteDir),
             itemBaseVersions: readItemBaseVersions(siteDir)
           }),
-      ...(assetRewrite ? { assetRewrite } : {})
+      ...(assetRewrite ? { assetRewrite } : {}),
+      ...(assetIds ? { assetIds } : {})
     })
   } catch (err) {
     error(`Could not build the sync package: ${err.message}`)

package/src/commands/register.js

@@ -57,7 +57,13 @@
 //     (legacy deploy-runtime had `--propagate` too). Implement once the backend
 //     has a version-update/propagation policy; until then every register is silent.
 
-import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import {
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  readdirSync,
+  statSync
+} from 'node:fs'
 import { execSync } from 'node:child_process'
 import { resolve, join } from 'node:path'
 import { buildRegistryPackage, buildSchemaOnlyPackage } from '@uniweb/build/uwx'
@@ -204,18 +210,82 @@ async function resolveFoundationDir(args) {
   process.exit(1)
 }
 
+// Directories that are never foundation source. `dist` is the output we compare
+// against; the rest are tooling. Dotted entries are skipped wholesale.
+const NON_SOURCE_DIRS = new Set(['dist', 'node_modules'])
+
+/**
+ * The newest mtime under `dir`, skipping build output and tooling. `0` when the
+ * tree is unreadable — which reads as "no source is newer", i.e. it degrades to
+ * the pre-existing behaviour rather than forcing a build on an fs error.
+ *
+ * @param {string} dir
+ * @returns {number} epoch ms
+ */
+function newestSourceMtime(dir) {
+  let newest = 0
+  const walk = (d) => {
+    let entries
+    try {
+      entries = readdirSync(d, { withFileTypes: true })
+    } catch {
+      return
+    }
+    for (const e of entries) {
+      if (e.name.startsWith('.') || NON_SOURCE_DIRS.has(e.name)) continue
+      const p = join(d, e.name)
+      if (e.isDirectory()) {
+        walk(p)
+        continue
+      }
+      try {
+        const m = statSync(p).mtimeMs
+        if (m > newest) newest = m
+      } catch {
+        /* unreadable file — ignore */
+      }
+    }
+  }
+  walk(dir)
+  return newest
+}
+
 /**
  * Does the foundation's `dist/` need a (re)build before we can register it?
  *
- * Mirrors `uniweb publish`'s build-if-stale so `register` is a full drop-in
- * for the foundation-publish flow. Two staleness signals:
+ * Three staleness signals:
  *   - MISSING: no `dist/entry.js` (or the legacy `dist/foundation.js`), or no
  *     `dist/meta/schema.json` — nothing built yet.
- *   - STALE: the version baked into `dist/meta/schema.json::_self.version`
+ *   - STALE VERSION: the version baked into `dist/meta/schema.json::_self.version`
  *     differs from `package.json::version` — a version bump without a rebuild,
  *     so the artifact encodes the OLD version while the register intends the
  *     NEW one (we'd otherwise submit a schema whose version disagrees with the
  *     code we deliver).
+ *   - STALE SOURCE: a source file is newer than `dist/entry.js`.
+ *
+ * ⛔ **The source signal was missing until 2026-08-16, and its absence shipped the
+ * PREVIOUS bundle silently.** Edit a component's rendered output, re-run
+ * `register` with a `dist/` present, and the version signal says fresh (nothing
+ * bumped), the artifact signal says fresh (files exist) — so the old bytes upload
+ * and the content digest legitimately does not move. The developer's freshness
+ * indicator reports "unchanged" and it is telling the truth about an input that
+ * never changed. Found by end-to-end testing against a live backend, which is
+ * the only place the two halves meet: a unit test on this predicate agrees with
+ * it, and the digest agrees with the bytes.
+ *
+ * ⚠️ **This header used to claim it "mirrors `uniweb publish`'s build-if-stale".
+ * It does not, and that sentence is why nobody looked.** `publish` does not do
+ * build-if-stale at all — `backend/foundation-bring-along.js` builds
+ * UNCONDITIONALLY before digesting, precisely so the digest reflects current
+ * source. So publish was already correct and register was not, while a docblock
+ * asserted they matched.
+ *
+ * ⛔ **And do NOT "fix" this by building unconditionally to match publish.**
+ * `publish` builds and then shells out to THIS command
+ * (`foundation-bring-along.js` → `execFileSync(cliBin, ['register', …])`), so an
+ * unconditional build here makes every publish build twice. The mtime signal is
+ * what keeps both paths right: publish's fresh `dist/` is newer than its source,
+ * so this correctly skips.
  *
  * Returns `{ needs: false }` or `{ needs: true, reason }`.
  *
@@ -262,6 +332,26 @@ export function foundationNeedsBuild(targetDir) {
   } catch {
     return { needs: true, reason: 'dist/meta/schema.json could not be parsed' }
   }
+  // STALE SOURCE — the signal whose absence shipped the previous bundle. Compared
+  // against the built entry rather than the schema: the schema is emitted by a
+  // later plugin hook, so it is always the newer of the two and using it would
+  // widen the window in which an edit reads as already-built.
+  //
+  // Ties count as fresh (`>`, not `>=`). A build writes its output after reading
+  // its input, so equal mtimes mean a same-millisecond build, not a missed edit —
+  // and on a fresh clone, where whole trees share a timestamp, `>=` would rebuild
+  // every foundation once for nothing.
+  try {
+    const entryPath = existsSync(join(distDir, 'entry.js'))
+      ? join(distDir, 'entry.js')
+      : join(distDir, 'foundation.js')
+    const builtAt = statSync(entryPath).mtimeMs
+    if (newestSourceMtime(targetDir) > builtAt)
+      return { needs: true, reason: 'a source file is newer than dist/entry.js' }
+  } catch {
+    // Can't compare — leave the other signals to decide rather than forcing a
+    // build on an fs error.
+  }
   return { needs: false }
 }
 
@@ -364,7 +454,17 @@ async function runRegister(args = []) {
       try {
         execSync('npx uniweb build --target foundation', {
           cwd: targetDir,
-          stdio: 'inherit'
+          // ⛔ `inherit` wires the DELEGATE's stdout to ours, so under --json the
+          // builder's progress lands on stdout ahead of the JSON line and
+          // `JSON.parse(stdout)` throws — on exactly the cold path a fresh
+          // checkout always takes. register's own output is already redirected to
+          // stderr (see `log` above); this child is the one stream it did not own,
+          // so --json was porcelain only when a build was NOT needed.
+          //
+          // fd 2 is our stderr: progress stays visible, stdout stays parseable.
+          // Found by a harness that had to work around it by taking the last
+          // JSON line off stdout.
+          stdio: jsonMode ? ['inherit', 2, 'inherit'] : 'inherit'
         })
       } catch (err) {
         error(`Build failed: ${err.message}`)

package/src/framework-index.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-08-16T13:24:21.340Z",
+  "generatedAt": "2026-08-18T13:23:47.915Z",
   "packages": {
     "@uniweb/build": {
-      "version": "0.24.0",
+      "version": "0.24.1",
       "path": "framework/build",
       "deps": [
         "@uniweb/content-reader",
@@ -14,11 +14,12 @@
         "@uniweb/schemas",
         "@uniweb/schemas",
         "@uniweb/semantic-parser",
+        "@uniweb/semantic-parser",
         "@uniweb/theming"
       ]
     },
     "@uniweb/content-reader": {
-      "version": "1.2.2",
+      "version": "1.2.3",
       "path": "framework/content-reader",
       "deps": []
     },
@@ -28,7 +29,7 @@
       "deps": []
     },
     "@uniweb/core": {
-      "version": "0.10.0",
+      "version": "0.10.1",
       "path": "framework/core",
       "deps": [
         "@uniweb/semantic-parser",
@@ -41,12 +42,14 @@
       "deps": []
     },
     "@uniweb/icons": {
-      "version": "0.4.0",
+      "version": "0.4.1",
       "path": "framework/icons",
-      "deps": []
+      "deps": [
+        "@uniweb/core"
+      ]
     },
     "@uniweb/kit": {
-      "version": "0.12.2",
+      "version": "0.12.3",
       "path": "framework/kit",
       "deps": [
         "@uniweb/core",
@@ -73,7 +76,7 @@
       ]
     },
     "@uniweb/runtime": {
-      "version": "0.12.0",
+      "version": "0.12.1",
       "path": "framework/runtime",
       "deps": [
         "@uniweb/core",
@@ -96,7 +99,7 @@
       "deps": []
     },
     "@uniweb/semantic-parser": {
-      "version": "1.2.2",
+      "version": "1.2.3",
       "path": "framework/semantic-parser",
       "deps": []
     },

package/src/utils/asset-upload.js

@@ -77,8 +77,8 @@ export function collectSiteAssets(distDir) {
  *
  * `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`.
+ * verbatim — origin-relative forms included. Nothing composes one: see the note at
+ * the foot of this file for why the reconstruction helper was removed.
  *
  * 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
@@ -231,14 +231,17 @@ export async function uploadSiteAssets({
   return { mode, uploaded, skipped, failed, assetsByLocalUrl }
 }
 
-// Build a durable asset serve URL from /dev/config's assetBase. Origin-relative
-// → prepend the backend origin; absolute (a CDN host) → used verbatim. Shape:
-// {assetBase}dist/{id}/base.{ext} — basename literally `base`, {ext} the source
-// extension the plan echoed. The root itself is never assumed: it is whatever
-// discovery returned.
-export function buildAssetUrl(origin, assetBase, id, ext) {
-  const base = /^https?:\/\//.test(assetBase)
-    ? assetBase
-    : `${origin}${assetBase}`
-  return `${base.replace(/\/$/, '')}/dist/${id}/base.${ext}`
-}
+// ⛔ `buildAssetUrl(origin, assetBase, id, ext)` was removed 2026-08-17. Do not
+// bring it back.
+//
+// It composed `{assetBase}dist/{id}/base.{ext}` — i.e. it encoded the BACKEND's
+// path layout inside a published CLI, on a release cadence the backend cannot
+// move, defaulting to one hardcoded production host for every deployment. Read
+// the plan entry's `serve_url` instead. It is part of the asset-plan contract:
+// present on EVERY entry, on both the direct and presigned lanes, including
+// entries the plan reports as already `present` — the backend covers that with a
+// test of its own (confirmed 2026-08-17).
+//
+// An entry without one is UNADDRESSABLE — fail, never guess. A composed location
+// is silently wrong wherever the deployment does not match the guess; a missing
+// one is visibly missing.

package/src/utils/flag-guard.js

@@ -69,13 +69,14 @@ const VERBS = {
   ],
   pull: [
     '--backend', '--content-only', '--dry-run', '--force', '--merge',
+    '--no-assets',
     '--no-collections', '--no-delete', '--no-prune', '--registry', '--token',
     // via backend/site-sync.js (the owner resolver) and utils/conformance.js
     '--yes', '--org', '--as-org', '--no-validate', ...VIA_DEPLOY
   ],
   clone: [
-    '--backend', '--content-only', '--no-collections', '--path', '--project',
-    '--registry', '--token', '--org', '--as-org'
+    '--backend', '--content-only', '--no-assets', '--no-collections', '--path',
+    '--project', '--registry', '--token', '--org', '--as-org'
   ],
   register: [
     '--backend', '--dry-run', '--json', '--output', '-o', '--registry',

package/src/utils/install-integrity.js

@@ -5,7 +5,7 @@
  * A site's `package.json`, its `file:` dependency on the foundation, and its
  * `node_modules` are not part of the site as an artifact; they are the project
  * shape the CLI hangs tooling on (see the three-ingredient model,
- * kb/framework/architecture/site-foundation-runtime-model.md, Part 1). Treating
+ * the site/foundation/runtime model). Treating
  * that scaffolding as part of the site is where most of the confusion in this
  * area comes from, so: nothing here says anything about what a foundation *is*,
  * how it is distributed, or how it reaches a host.

package/templates/workspace/_gitignore

@@ -8,10 +8,6 @@ dist/
 # Generated entry (regenerated by `uniweb build`; never committed)
 _entry.generated.js
 
-# Local mock-cloud state (when running `uniweb publish --local` or
-# the unicloud dev server inside this workspace)
-.unicloud/
-
 # Environment
 .env
 .env.local