uniweb 0.48.4 → 0.48.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.48.4",
+  "version": "0.48.6",
   "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/core": "^0.24.3",
-    "@uniweb/kit": "^0.18.1",
-    "@uniweb/runtime": "^0.19.4",
-    "@uniweb/semantic-parser": "^1.4.0"
+    "@uniweb/core": "^0.24.4",
+    "@uniweb/kit": "^0.18.2",
+    "@uniweb/semantic-parser": "^1.4.0",
+    "@uniweb/runtime": "^0.19.5"
   },
   "peerDependencies": {
+    "@uniweb/build": "^0.44.5",
     "@uniweb/content-reader": "^1.2.4",
-    "@uniweb/semantic-parser": "^1.4.0",
-    "@uniweb/build": "^0.44.3"
+    "@uniweb/semantic-parser": "^1.4.0"
   },
   "peerDependenciesMeta": {
     "@uniweb/build": {

package/partials/agents.md

@@ -86,7 +86,7 @@ Documentation paths in this guide are given bare — `development/creating-compo
 | Theming and styling | `authoring/theming.md` |
 | Authoring collections | `authoring/collections.md` |
 | Where-object predicate format | `authoring/predicates.md` |
-| Connecting a backend / custom transports | `development/connecting-a-backend.md` |
+| Data sources / custom transports | `development/data-sources.md` |
 | Building components | `development/creating-components.md` |
 | Schemas in practice | `development/schemas-in-practice.md` |
 | Workspace layouts and their wiring | `development/project-structures.md` |
@@ -1843,7 +1843,7 @@ fetcher:
 
 **Failures are visible, not empty:** a fetch that failed leaves its key ABSENT from `content.data` and names the message on `block.dataError[key]`; it is never delivered as `[]`, which means "no records". The page still renders — a section reads `dataError` to tell the two apart.
 
-When a plain `url:` is enough and when a transport is the answer: `development/connecting-a-backend.md`.
+When a plain `url:` is enough and when a transport is the answer: `development/data-sources.md`.
 
 Full model: `reference/data-fetching.md`. Where-object format with examples: `authoring/predicates.md`.
 
@@ -1895,16 +1895,18 @@ section type, same arrangement as `fetcher:` and `search:`.
 
 A form gets its destination from the first of these that applies:
 
-1. **`submit:` in `site.yml`** — an endpoint you name yourself.
-2. **One the host supplies** — `services.submit` in the served payload. A site
-   published to Uniweb Cloud gets submission handling from the platform, so it
-   normally needs **no `submit:` at all**.
+1. **One the host supplies** — `services.submit` in the served payload. Where the
+   host handles submissions, that is the destination and nothing in `site.yml`
+   overrides it — so a site published to Uniweb Cloud normally needs **no
+   `submit:` at all**.
+2. **`submit:` in `site.yml`** — an endpoint you name yourself, for a host that
+   does not handle submissions, or a static site.
 3. **Neither** — there is no destination, and the form says so instead of
    guessing at one.
 
 That is the general arrangement, not a forms-only one. A host declares
 everything it offers under `services`, keyed by name, and every service resolves
-by the same rule — your declaration, then the host's, then neither.
+by the same rule — the host's offer, then your declaration, then neither.
 
 ⭐ **Before you render UI for a service, ask whether the site has it** — one predicate per service,
 no arguments: `isSearchEnabled()`, `isSubmitEnabled()`, `isApiEnabled()`, `isAssistantEnabled()`,
@@ -2097,7 +2099,7 @@ tracking:
 ```
 
 A host may also supply one under `services.tracking`, and the usual precedence
-applies: yours wins, then the host's, then neither.
+applies: the host's, then yours, then neither.
 
 ⚠️ **The endpoint has to accept the framework's own format** — a batched
 `{ "events": [ … ] }` POST, documented in `reference/site-configuration.md`. It
@@ -2166,17 +2168,18 @@ tracking:
 ⭐ **`emit` needs no endpoint of its own.** Where a host provides one, the site
 declares only what it wants sent and the address comes from the host. The two
 are read key by key, so naming `emit` alone overrides nothing else the host
-declared. And declaring your own `endpoint:` always wins, so a site pointing at
-its own collector keeps working on any host, including none.
+declared. An `endpoint:` of your own is used wherever the host supplies no
+collector — on a host without one, and on none — and where the host supplies
+one, the host's is used.
 
-`minimal` is `page_view` alone. `standard` is the default when you supply your
-own `endpoint:`. `all` is a standing yes, so an event added in a later framework
+`minimal` is `page_view` alone. `standard` is the default when the collector is
+your own. `all` is a standing yes, so an event added in a later framework
 release is included without you changing anything — which is exactly why
 `standard` exists as well: it is a curated set that a release cannot grow behind
 your back.
 
 ⭐ **Saying nothing means two different things, and which one depends on who
-supplies the address.** A site with its own `endpoint:` gets `standard`. A site
+supplies the address.** A site sending to its own `endpoint:` gets `standard`. A site
 on a **host-supplied** collector gets **whatever that host declares it
 collects** — it has no address of its own, so the arrangement is that the host
 does analytics for it, and the set grows when the host starts collecting
@@ -2324,10 +2327,10 @@ For cases the factory doesn't cover, write handlers directly using `Loom`, `inst
 ## Part 4b — When the site is also an app
 
 Everything above is a site: content the author writes, built into pages. Some sites
-also have **their own backend** — accounts, per-visitor data, records their members
-create and edit. That is `@uniweb/api`.
+also have **an `api` service** — accounts, per-visitor data, records their members
+create and edit. `@uniweb/api` is its client.
 
-⛔ **Only reach for this when the site actually has one.** A site with no backend is
+⛔ **Only reach for this when the site actually has one.** A site without one is
 the normal case, and a foundation that assumes one breaks on every other site it is
 used with.
 
@@ -2344,7 +2347,7 @@ import { useSession, SignedIn, SignedOut } from '@uniweb/api'
 if (!isApiEnabled()) return <StaticVersion />   // synchronous — nothing to await
 ```
 
-⛔ **When there is no backend, draw nothing** — not a disabled control, and not an
+⛔ **When the site has no `api` service, draw nothing** — not a disabled control, and not an
 explanation. Same rule as `services` in Part 4: which capabilities a site's operator
 set up is none of a visitor's business, and "sign-in unavailable" reads as breakage
 when it is simply a feature this site does not have. Render the version of your
@@ -2357,8 +2360,8 @@ const { status, records } = useRecords({ schema: '@/session' })
 ```
 
 ⭐ **`absent` and an empty `ready` are different answers, and confusing them is the
-mistake to avoid.** `absent` = there is no live source (no backend, or nobody signed
-in) → render the site's authored content. `ready` with `records: []` = the backend
+mistake to avoid.** `absent` = there is no live source (no `api` service, or nobody signed
+in) → render the site's authored content. `ready` with `records: []` = the service
 answered and there is nothing there → render your empty state. Showing "nothing yet"
 for the first tells a visitor their content is gone when it was never requested.
 
@@ -2444,6 +2447,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
@@ -2513,7 +2517,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-10T14:59:00.380Z",
+  "generatedAt": "2026-09-10T23:52:15.147Z",
   "packages": {
     "@uniweb/api": {
-      "version": "0.3.0",
+      "version": "0.3.1",
       "path": "framework/api",
       "deps": [
         "@uniweb/core"
       ]
     },
     "@uniweb/build": {
-      "version": "0.44.3",
+      "version": "0.44.5",
       "path": "framework/build",
       "deps": [
         "@uniweb/content-reader",
@@ -34,7 +34,7 @@
       "deps": []
     },
     "@uniweb/core": {
-      "version": "0.24.3",
+      "version": "0.24.4",
       "path": "framework/core",
       "deps": [
         "@uniweb/semantic-parser",
@@ -54,7 +54,7 @@
       ]
     },
     "@uniweb/kit": {
-      "version": "0.18.1",
+      "version": "0.18.2",
       "path": "framework/kit",
       "deps": [
         "@uniweb/core",
@@ -82,7 +82,7 @@
       ]
     },
     "@uniweb/runtime": {
-      "version": "0.19.4",
+      "version": "0.19.5",
       "path": "framework/runtime",
       "deps": [
         "@uniweb/core",
@@ -110,7 +110,7 @@
       "deps": []
     },
     "@uniweb/templates": {
-      "version": "0.12.3",
+      "version": "0.12.5",
       "path": "framework/templates",
       "deps": []
     },