uniweb 0.48.5 → 0.49.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.48.5",
+  "version": "0.49.0",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -41,15 +41,15 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
-    "@uniweb/runtime": "^0.19.5",
-    "@uniweb/core": "^0.24.4",
-    "@uniweb/kit": "^0.18.2",
-    "@uniweb/semantic-parser": "^1.4.0"
+    "@uniweb/core": "^0.25.0",
+    "@uniweb/kit": "^0.18.3",
+    "@uniweb/semantic-parser": "^1.4.0",
+    "@uniweb/runtime": "^0.20.0"
   },
   "peerDependencies": {
-    "@uniweb/semantic-parser": "^1.4.0",
+    "@uniweb/build": "^0.45.0",
     "@uniweb/content-reader": "^1.2.4",
-    "@uniweb/build": "^0.44.4"
+    "@uniweb/semantic-parser": "^1.4.0"
   },
   "peerDependenciesMeta": {
     "@uniweb/build": {

package/partials/agents.md

@@ -857,7 +857,7 @@ A bare string is a path under `entities/`, naming one file or matching many.
     - article/2025-*.md
 ```
 
-A query then slices it with `where: { path: { under: 'archive' } }`. An entity belongs to one folder; if you want a computed subset, that is a query, not a second placement.
+A query reads one branch with `scope: archive` — the folder and everything inside it (the older `where: { path: { under: … } }` is refused by the build). An entity belongs to one folder; if you want a computed subset, that is a query, not a second placement.
 
 **`queries.yml` — how content is reached.** A bare map of name → query. A query names a schema and the published records of that schema are its rows:
 
@@ -897,9 +897,11 @@ pages/blog/
 
 `entities/article/design-tips.md` becomes `/blog/design-tips`. The section inside `[slug]/` needs no special markdown — the matched record is delivered to it. Generated pages are excluded from navigation menus.
 
+**Which query the URL narrows — the page's route query:** the `[slug]` page's own `data:`, else its parent page's (the usual shape, above), else `site.yml`'s; if none declares one, the query its sections all declare. The first query of that level wins. Every section the route query reaches gets the one record; a section declaring a *different* query of its own gets that query as declared. The folder name says what the URL segment matches: `[slug]` the record's handle (`$name`, which compiled records carry — equal to their `slug`), `[uuid]` its `$uuid`, any other `[name]` the record's own field of that name. A folder inside `[slug]/` (`[slug]/cv/` → `/blog/:slug/cv`) is a parametric page too, reading the record when `[slug]/page.yml` declares the query. `[dir]` and `[path]` are refused as folder names, and so is any folder inside `[...path]/`.
+
 > **The record arrives as a single-element array under the query key** — `content.data.recent[0]`, not `content.data.article`. The runtime never coerces it to an object and never synthesizes a singular key. See *Data* in Part 4.
 
-**Records with URLs of their own shape — `[...path]/`.** A folder named exactly `[...path]` (one fixed spelling) captures the rest of the URL: `/blog/my-post` and `/blog/rust/2025/my-post` both reach it. The capture yields three standard variables — `:path` (the whole capture), `:dir` (everything before the last segment), `:slug` (the last segment, the record's handle) — and the record is still delivered by `slug`, so the section reads `content.data.recent[0]` as before. A record's URL is its folder placement plus its slug (`- folder: rust/2025` in `records.yml` → `/blog/rust/2025/my-post`). A query may bind a part — `scope: :dir` exposes the folder branch, `where: { tag: :dir }` keeps it private — and an unbound variable drops its clause, so one saved query serves the list page and the detail page. Reference: `reference/dynamic-routes.md`.
+**Records with URLs of their own shape — `[...path]/`.** A folder named exactly `[...path]` (one fixed spelling) captures the rest of the URL: `/blog/my-post` and `/blog/rust/2025/my-post` both reach it. The capture yields three standard variables — `:path` (the whole capture), `:dir` (everything before the last segment), `:slug` (the last segment, the record's handle) — and the record is still delivered by its handle, so the section reads `content.data.recent[0]` as before. The same three variables exist under every parametric page: under `[slug]`, `:slug` and `:path` are the segment and `:dir` is empty. A record's URL is its folder placement plus its slug (`- folder: rust/2025` in `records.yml` → `/blog/rust/2025/my-post`). A query may bind a part — `scope: :dir` exposes the folder branch, `where: { tag: :dir }` keeps it private — and an unbound or empty variable drops its clause, so one saved query serves the list page and the parametric page, on a static site and a hosted one alike. Without `scope: :dir` the directory is decoration: the record is found by its handle wherever it sits. Reference: `reference/dynamic-routes.md`.
 
 **Two options for bigger sets:**
 
@@ -1773,7 +1775,7 @@ Content-less containers appear as group nodes (`hasContent: false`) — use `nav
 
 A component on a page with a `data:` or `fetch:` declaration automatically receives that data in `content.data.{key}` — no opt-in in `meta.js`.
 
-**Bound collections always arrive as arrays.** On a list page, `content.data.articles` is the full collection. On a template page (`[slug]/`), the matched record is delivered under the *same* key as a single-element array — the detail section reads `content.data.articles[0]`. When nothing matches, the key is `[]`. The runtime never coerces to a single object and never synthesizes a singular key.
+**Bound collections always arrive as arrays.** On a list page, `content.data.articles` is the full collection. On a parametric page (`[slug]/`), the matched record is delivered under the *same* key as a single-element array — the detail section reads `content.data.articles[0]`. When nothing matches, the key is `[]`. The runtime never coerces to a single object and never synthesizes a singular key.
 
 ```jsx
 function Article({ content, block }) {
@@ -2447,6 +2449,7 @@ uniweb add ci --target foundation # Publish a foundation for free at permanent v
                                   # (GitHub Pages → foundations/<name>/<version>/entry.js)
 
 uniweb push / pull / clone / status   # Git-style content sync with the Uniweb backend
+uniweb refresh / sync                 # Catch up (git + backend, never pushes) / catch up, then push
 uniweb push --org @acme               # First push/publish of a site: who owns it (see below)
 uniweb register [--scope @org]        # Register a foundation + its data schemas to the registry
 uniweb login / logout                 # Start or clear the backend session the verbs above reuse
@@ -2516,7 +2519,7 @@ Foundations have their own free path too: `uniweb add ci --target foundation` pu
 - **Git is the reviewed, durable record** — you `pull` content back, read it with `git diff`, and commit.
 - **Authors never push or pull.** For them, content simply updates, whether the change came from another author or from a developer's CLI.
 
-**Conflicts behave like a collaborative document, not like git.** A developer's push arrives the way a live collaborator's edit would. Different sections never conflict, and different params of the same section never conflict — last edit wins. The app warns only when two content edits target the same section at the same time.
+**Nobody's work is overwritten without asking.** `uniweb push` is refused if the site changed on the backend since your last pull — usually an author editing in the app — and reports what changed; nothing is written. Edits to different sections never collide. `uniweb pull` overwrites rather than merges, so it refuses while you have uncommitted changes. The recovery for both is `uniweb pull --merge` (or `uniweb refresh`, which runs `git pull` first): changes to different parts of a file combine silently, and a genuine overlap leaves conflict markers and a non-zero exit — so `uniweb pull --merge && uniweb push` never ships markers. `--force` is the deliberate overwrite (on `push` it replaces the backend's changes, on `pull` it discards yours); don't use it to get past a refusal. `uniweb sync` is `refresh` then `push`; neither publishes.
 
 **The Cloud also provides a real backend for structured data:** a database for every registered data schema, and a CMS that edits both static page content and dynamic data entities typed by those schemas. That's the piece that makes it viable for teams and client work — the client manages records, not markdown files.
 

package/src/backend/asset-download.js

@@ -34,7 +34,11 @@
 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'
+import {
+  readAssetMap,
+  updateAssetMap,
+  servedFingerprint
+} from '@uniweb/build/uwx'
 
 /**
  * Collect every `{ id, ext, url }` an entity document references.
@@ -43,7 +47,7 @@ import { readAssetMap, updateAssetMap } from '@uniweb/build/uwx'
  * 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) {
+export function collectAssetRefs(document, map = {}) {
   const found = new Map() // id → { id, ext, url }
   const visit = (node) => {
     if (Array.isArray(node)) return node.forEach(visit)
@@ -59,6 +63,28 @@ export function collectAssetRefs(document) {
     for (const v of Object.values(node)) visit(v)
   }
   visit(document)
+  // A BARE-STRING reference (`info.preview`, `seo.image`, a section param) has no
+  // object to carry identity beside it. The map recognizes it by the fingerprint the
+  // push recorded for its serve URL — see `servedFingerprint` in @uniweb/build/uwx.
+  const byServed = new Map()
+  for (const v of Object.values(map || {})) {
+    if (v?.served && v.id && !byServed.has(v.served)) byServed.set(v.served, v)
+  }
+  if (byServed.size) {
+    const visitStrings = (node) => {
+      if (typeof node === 'string') {
+        if (!node.startsWith('/') && !/^https?:\/\//i.test(node)) return
+        const entry = byServed.get(servedFingerprint(node))
+        if (entry && !found.has(entry.id))
+          found.set(entry.id, { id: entry.id, ext: entry.ext || '', url: node })
+        return
+      }
+      if (Array.isArray(node)) return node.forEach(visitStrings)
+      if (node && typeof node === 'object')
+        for (const v of Object.values(node)) visitStrings(v)
+    }
+    visitStrings(document)
+  }
   return [...found.values()]
 }
 
@@ -89,11 +115,12 @@ export async function downloadMissingAssets({
   warn = () => {}
 }) {
   const doFetch = fetchImpl || ((u) => globalThis.fetch(u))
-  const refs = collectAssetRefs(document)
+  // Read first: a bare-string reference is only recognizable through the map.
+  const map = readAssetMap(siteDir)
+  const refs = collectAssetRefs(document, map)
   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)
 

package/src/backend/site-media.js

@@ -16,6 +16,7 @@ import { createHash } from 'node:crypto'
 import { existsSync, readFileSync } from 'node:fs'
 import { basename } from 'node:path'
 import { resolveAssetPath } from '@uniweb/build/site'
+import { servedFingerprint } from '@uniweb/build/uwx'
 import { contentTypeFor } from '../utils/code-upload.js'
 import { humanBytes } from '../utils/bytes.js'
 
@@ -79,7 +80,17 @@ export async function uploadSiteMedia(
   for (const ref of refs) {
     const entry = result.assetsByLocalUrl[ref]
     if (!entry) continue
-    if (entry.id) ids[ref] = { id: entry.id, ext: entry.ext || '' }
+    // `served` — a fingerprint of the address, never the address. It is how a pull
+    // recognizes this asset where the reference is a bare string with no room for an
+    // id beside it (`info.preview`, `seo.image`, a section param); `assets.json`'s
+    // header says why a hash and not the URL.
+    if (entry.id) {
+      ids[ref] = {
+        id: entry.id,
+        ext: entry.ext || '',
+        ...(entry.serveUrl ? { served: servedFingerprint(entry.serveUrl) } : {})
+      }
+    }
     // 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,

package/src/backend/site-sync.js

@@ -29,7 +29,8 @@ import {
   collectUnitUuids,
   collectFolderItemUuids,
   collectQueryUuids,
-  readAssetMap
+  readAssetMap,
+  removeYamlScalar
 } from '@uniweb/build/uwx'
 
 // First entity `$`-document out of a `.uwx` we produced or the backend served.
@@ -323,6 +324,51 @@ export function clearRemoteSyncStateIfUnbound(siteDir) {
   return stale
 }
 
+/**
+ * Drop the `site.yml` values that describe ONE PARTICULAR backend site, when this
+ * project is bound to none (no `$uuid`) — a brand-new site, or the state our own
+ * "clear `$uuid` to re-publish as a new site" recovery puts you in:
+ *
+ *   · `$url` — where the PREVIOUS site was live. The new one is not live anywhere
+ *     yet; its first publish records its own.
+ *   · `preview` in the APP's form — a timestamp naming the previous site's generated
+ *     card image, which is keyed by that site's uuid and would dangle on this one.
+ *
+ * ⛔ An AUTHOR's preview is theirs and stays: a URL, or a path to an image in the
+ * project, is as good for the new site as for the old.
+ *
+ * The site.yml sibling of `clearRemoteSyncStateIfUnbound`, called beside it for the
+ * same reason — before the create mints a uuid and makes the project look bound.
+ *
+ * @param {string} siteDir
+ * @returns {string[]} the keys removed
+ */
+export function dropSiteBoundValues(siteDir) {
+  const file = join(siteDir, 'site.yml')
+  let y
+  try {
+    y = yaml.load(readFileSync(file, 'utf8'))
+  } catch {
+    return []
+  }
+  if (!y || typeof y !== 'object' || typeof y.$uuid === 'string') return []
+  const dropped = []
+  if (y.$url !== undefined && removeYamlScalar(file, '$url')) dropped.push('$url')
+  if (
+    y.preview !== undefined &&
+    !isAuthoredPreview(y.preview) &&
+    removeYamlScalar(file, 'preview')
+  ) {
+    dropped.push('preview')
+  }
+  return dropped
+}
+
+// An author's preview is an address — a URL, or a site-root / relative path. Anything
+// else is the app's generated-image token.
+const isAuthoredPreview = (v) =>
+  typeof v === 'string' && (/^https?:\/\//i.test(v) || /^\.{0,2}\//.test(v))
+
 export function readSyncCache(siteDir) {
   return readMap(siteDir, 'hashes')
 }

package/src/commands/publish.js

@@ -87,6 +87,7 @@ import {
   readFolderItemUuids,
   ensureSiteExists,
   clearRemoteSyncStateIfUnbound,
+  dropSiteBoundValues,
   pushSyncPackages,
   resolveSiteOrgForCreate
 } from '../backend/site-sync.js'
@@ -578,6 +579,12 @@ export async function publish(args = []) {
       `Cleared stale sync state from a previous site (${droppedState.join(', ')}).`
     )
   }
+  const droppedValues = dropSiteBoundValues(siteDir)
+  if (droppedValues.length) {
+    say.dim(
+      `Dropped the previous site's ${droppedValues.join(' and ')} from site.yml.`
+    )
+  }
 
   // 3b. Make sure the SITE EXISTS before a single byte is uploaded.
   //
@@ -1106,6 +1113,11 @@ export async function publish(args = []) {
     say.dim(`  site.yml lists ${unserved.join(', ')}, and ${unserved.length === 1 ? 'it was' : 'they were'} not published.`)
   }
   if (serveUrl) console.log(`  ${c.cyan}${serveUrl}${c.reset}`)
+  // ⛔ No site.yml write for where it went live. The backend records the reply's
+  // `url` on `info.url` at every publish, and pull brings it into `site.yml::$url`
+  // like any other key. A copy written here was a second writer that had to match
+  // the backend's byte for byte (the address printed above is made absolute, so it
+  // did not), and it left site.yml modified — which a plain `pull` refuses over.
   if (result.deploy_uuid) say.dim(`deploy: ${result.deploy_uuid}`)
   return { exitCode: 0 }
 }

package/src/commands/push.js

@@ -89,6 +89,7 @@ import {
   ensureItemUuids,
   ensureSiteExists,
   clearRemoteSyncStateIfUnbound,
+  dropSiteBoundValues,
   pushSyncPackages,
   resolveSiteOrgForCreate
 } from '../backend/site-sync.js'
@@ -303,6 +304,10 @@ export async function push(args = [], deps = {}) {
         `Cleared stale sync state from a previous site (${dropped.join(', ')}).`
       )
     }
+    const stale = dropSiteBoundValues(siteDir)
+    if (stale.length) {
+      note(`Dropped the previous site's ${stale.join(' and ')} from site.yml.`)
+    }
   }
   const priorHashes = readSyncCache(siteDir)
   // Per-item identity, without which the backend reads every record as new and

package/src/framework-index.json

@@ -1,16 +1,16 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-09-10T16:24:13.926Z",
+  "generatedAt": "2026-09-11T18:41:11.718Z",
   "packages": {
     "@uniweb/api": {
-      "version": "0.3.1",
+      "version": "0.3.2",
       "path": "framework/api",
       "deps": [
         "@uniweb/core"
       ]
     },
     "@uniweb/build": {
-      "version": "0.44.4",
+      "version": "0.45.0",
       "path": "framework/build",
       "deps": [
         "@uniweb/content-reader",
@@ -34,7 +34,7 @@
       "deps": []
     },
     "@uniweb/core": {
-      "version": "0.24.4",
+      "version": "0.25.0",
       "path": "framework/core",
       "deps": [
         "@uniweb/semantic-parser",
@@ -47,14 +47,14 @@
       "deps": []
     },
     "@uniweb/icons": {
-      "version": "0.4.15",
+      "version": "0.4.16",
       "path": "framework/icons",
       "deps": [
         "@uniweb/core"
       ]
     },
     "@uniweb/kit": {
-      "version": "0.18.2",
+      "version": "0.18.3",
       "path": "framework/kit",
       "deps": [
         "@uniweb/core",
@@ -74,7 +74,7 @@
       "deps": []
     },
     "@uniweb/projections": {
-      "version": "0.6.0",
+      "version": "0.6.1",
       "path": "framework/projections",
       "deps": [
         "@uniweb/content-writer",
@@ -82,7 +82,7 @@
       ]
     },
     "@uniweb/runtime": {
-      "version": "0.19.5",
+      "version": "0.20.0",
       "path": "framework/runtime",
       "deps": [
         "@uniweb/core",
@@ -110,7 +110,7 @@
       "deps": []
     },
     "@uniweb/templates": {
-      "version": "0.12.4",
+      "version": "0.12.5",
       "path": "framework/templates",
       "deps": []
     },