uniweb 0.67.0 → 0.69.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.67.0",
+  "version": "0.69.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/content-writer": "^0.3.4",
+    "@uniweb/runtime": "^0.27.4",
     "@uniweb/core": "^0.29.8",
     "@uniweb/kit": "^0.19.4",
-    "@uniweb/schemas": "^0.6.0",
-    "@uniweb/runtime": "^0.27.4",
-    "@uniweb/semantic-parser": "^1.4.1"
+    "@uniweb/semantic-parser": "^1.4.1",
+    "@uniweb/schemas": "^0.7.0",
+    "@uniweb/content-writer": "^0.3.4"
   },
   "peerDependencies": {
-    "@uniweb/build": "^0.61.0",
+    "@uniweb/build": "^0.63.0",
     "@uniweb/content-reader": "^1.2.5",
     "@uniweb/semantic-parser": "^1.4.1"
   },

package/partials/agents.md

@@ -879,6 +879,25 @@ Keep those folders flat: `records/article/design-tips.md` works; `records/articl
 
 Item frontmatter conventionally uses `title`, `date`, `tags`, `image`, `description`, `author` — plus any fields your content needs (`price`, `role`, `order`). Images can sit beside the item file and be referenced with `./`. **`draft: true` keeps a record off the live site without deleting it**: it is still a record, in `records/`, and `pnpm dev` shows it so you can preview it, but a build for hosting leaves it out, and a backend you `uniweb push` it to keeps it in the site's folder without delivering it. (`published: false`, an older spelling, is refused.)
 
+**A record's file follows its data schema's sections.** A schema with one section (the `fields:` form) is written flat, as above. A schema with more than one is written **by section** — each field under its section's name — and a field left at the top stops the build and a push, naming where it goes. `@std/article` has two, its card `article` and `article_body`:
+
+```markdown
+<!-- records/std/article/hello.md -->
+---
+article:
+  title: Hello
+  date: 2026-05-01
+article_body:
+  author: Ada
+---
+
+The body — the value of the schema's content field, `article_body.content`.
+```
+
+**A component receives it differently from how the file writes it**, the same way on a static site and a hosted one: the brief's fields at the top (`article.title`), every other section under its name (`article.article_body.content`, `article.article_body.author`), and `$name`, the handle. Lists carry the brief alone unless the query says otherwise (`deferred:`, below). Full rules: `reference/entity-content.md`.
+
+**A reference names the record it points at.** A `{ ref: '@/speaker' }` field is written as that record's name — `speaker: ada` for `records/speaker/ada.yml` (its file's name, or its `slug:`) — and a `many` one as a list of names. A component receives `{ entity, brief }`: the record reduced to its brief, so `talk.speaker.brief.name`. `uniweb validate` and a push report a name that matches no record; a push sends each reference to the record it names (in the same push when that record is new too), and a pull writes the name back.
+
 **`records/folder.yml` — optional, and only for folders.** It is the one file in `records/` that is not a record, it moves with the directory (`paths.records`), and like a pages folder's `folder.yml` it describes the folder it sits in. Every record sits at the top of the site's records folder unless `folder.yml` places it in a sub-folder. Add one only when a query needs to ask for a *slice* of the records rather than all of them — most sites never do:
 
 ```yaml
@@ -946,7 +965,7 @@ pages/blog/
 
 **Two options for bigger sets:**
 
-`deferred: [body]` strips heavy fields from the list payload — cards stay light, while a `[slug]` page still receives the full record automatically and other components fetch the whole record on demand with `useWholeRecord`. File-based records emit per-record files at `/data/<name>/<slug>.json` and need no configuration; an external query names its one-record request with `record:` instead (*Fetching from other sources* in Part 4).
+`deferred: [body]` strips heavy fields from the list payload — cards stay light, while a `[slug]` page still receives the full record automatically and other components fetch the whole record on demand with `useWholeRecord`. It names keys of the record as a component receives it — a field, or a section's name — and a schema with more than one section implies it: every section but the brief (`[article_body]` for `@std/article`), so it is rarely written. File-based records emit per-record files at `/data/<name>/<slug>.json` and need no configuration; an external query names its one-record request with `record:` instead (*Fetching from other sources* in Part 4).
 
 `queryable:` declares which fields a reader may filter on, with enough metadata for the foundation to render controls:
 
@@ -1866,7 +1885,7 @@ fetch:
   limit: 3
 ```
 
-**Lean lists with `deferred:`.** A query over records with heavy fields (article bodies, large nested arrays) can declare `deferred: [body]`. The list payload omits those fields; per-record full files are emitted at `/data/<name>/<slug>.json`. (An external query declares no `deferred:` — its whole record comes from `record:`, below.) On a parametric page the record's full data is delivered automatically; elsewhere components fetch the whole record on demand with `useWholeRecord(record, { query })`. The hook is safe to call on any query: when the query has no separate source for the whole record it returns the record you passed in, because nothing was stripped from it.
+**Lean lists with `deferred:`.** A query over records with heavy fields (article bodies, large nested arrays) can declare `deferred: [body]` — keys of the record as a component receives it, a section's name included; a schema with more than one section implies every section but its brief. The list payload omits those fields; per-record full files are emitted at `/data/<name>/<slug>.json`. (An external query declares no `deferred:` — its whole record comes from `record:`, below.) On a parametric page the record's full data is delivered automatically; elsewhere components fetch the whole record on demand with `useWholeRecord(record, { query })`. The hook is safe to call on any query: when the query has no separate source for the whole record it returns the record you passed in, because nothing was stripped from it.
 
 **Component-side fetching.** When a component genuinely needs to fetch on its own (a search box, "load more", a lazy popover), use the kit hooks — `useFetched`, `useCacheEntry`, `useWholeRecord`. They share the framework's cache and dispatcher with declarative fetches; same-key requests dedupe automatically.
 

package/src/backend/site-sync.js

@@ -1187,7 +1187,8 @@ export async function probeUnpushed(siteDir, { backend = null, sendAll = false }
   // passed in — true before 2026-09-22, and read as a reason to pass it.
   const pkg = await comparisonEmit(siteDir, { backend, priorHashes, sendAll })
   const changed =
-    (pkg.siteContent?.entityCount || 0) + (pkg.records?.entityCount || 0)
+    (pkg.siteContent?.entityCount || 0) +
+    (pkg.records?.entityCount || 0)
   return { changed, unchanged: pkg.skipped || 0, warnings: pkg.warnings || [] }
 }
 
@@ -1266,6 +1267,28 @@ export async function rebankSyncHashes(siteDir, backend = null) {
   return Object.keys(pkg.hashes || {}).length
 }
 
+/**
+ * Re-bank the hashes of the records a push sent naming a record it created — `keys`,
+ * the emit's `namesNew` — as the next push will hash them.
+ *
+ * ⭐ Such a record names its new record by `$ref`, and the backend stores the uuid it
+ * mints. The next push names it by that uuid: the same reference, and another hash — so
+ * the hash the push banked describes a document no later emit builds, and the next push
+ * would send every one of these records again. Re-sending is not harmless: a record's
+ * list-section items go without the identity a re-send needs (`identity_required`).
+ *
+ * ⚖️ Only these keys, over the hashes the push just banked: the site-content lane and
+ * the folder are banked as that push sent them, and a caller's own emit options (a
+ * publish that does not declare services) are not the comparison emit's.
+ */
+export async function rebankRecordHashes(siteDir, backend, keys) {
+  if (!keys?.length) return
+  const pkg = await comparisonEmit(siteDir, { backend, sendAll: true })
+  const hashes = { ...readSyncCache(siteDir, backend) }
+  for (const key of keys) if (pkg.hashes?.[key]) hashes[key] = pkg.hashes[key]
+  writeSyncCache(siteDir, backend, hashes, readAppliedInjections(siteDir, backend))
+}
+
 /**
  * What a push did with the site's `template:` intent — read from the backend's own
  * reply, never inferred from what we sent.
@@ -1770,6 +1793,15 @@ export async function pushSyncPackages({
   // Entities absent from finalized[] (skipped, or not editable) keep their cached
   // value — absence is not invalidation.
   writeSyncCache(siteDir, client.origin, hashes, applied)
+  // A record that named a record this push created is banked as the next push will send
+  // it — by that record's uuid, which the back-fill above just recorded.
+  if (records && pkg.namesNew?.length) {
+    try {
+      await rebankRecordHashes(siteDir, client.origin, pkg.namesNew)
+    } catch (err) {
+      note(`! Could not re-bank ${pkg.namesNew.length} record(s) that name a new record: ${err.message}. The next push sends them again.`)
+    }
+  }
   mergeHarvested()
   // Re-base the page attribution: our emitted document and the backend's post-write
   // copy of it are the two sides' new agreed state. Only when the site-content lane

package/src/commands/publish.js

@@ -767,12 +767,6 @@ export async function publish(args = []) {
   //    (It stamped `info.data_bundle` until 2026-08-18; the ball is gone and
   //    collection data now lands at its serving tail, so nothing records it.)
   const priorHashes = readSyncCache(siteDir, client.origin)
-  // publish rides the same gated push as `uniweb push`: if an app author has
-  // edited since this clone last synced, the push is refused rather than
-  // overwriting them, and nothing goes live. `--force` drops the precondition.
-  const baseVersions = args.includes('--force')
-    ? null
-    : readBaseVersions(siteDir, client.origin)
   // Per-item identity, recovered from the backend when this clone has never seen it.
   // Without it the backend re-mints every page and section row (see readItemUuids).
   const itemUuids = await ensureItemUuids({
@@ -948,6 +942,10 @@ export async function publish(args = []) {
     say.dim('Services unchanged.')
   }
 
+  // publish rides the same gated push as `uniweb push`: if an app author has
+  // edited since this clone last synced, the push is refused rather than
+  // overwriting them, and nothing goes live. `--force` drops the precondition.
+  const forced = args.includes('--force')
   let pkg
   try {
     pkg = await emitSyncPackages(siteDir, {
@@ -959,9 +957,12 @@ export async function publish(args = []) {
       resolveModel,
       priorHashes,
       itemUuids,
-      ...(baseVersions
-        ? { baseVersions, itemBaseVersions: readItemBaseVersions(siteDir, client.origin) }
-        : {}),
+      ...(forced
+        ? {}
+        : {
+            baseVersions: readBaseVersions(siteDir, client.origin),
+            itemBaseVersions: readItemBaseVersions(siteDir, client.origin)
+          }),
       ...(Object.keys(injectInfo).length ? { injectInfo } : {}),
       ...(Object.keys(ext.pins).length ? { injectExtensions: ext.pins } : {}),
       ...(assetRewrite ? { assetRewrite } : {}),

package/src/framework-index.json

@@ -1,16 +1,16 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-09-24T19:00:27.393Z",
+  "generatedAt": "2026-09-25T11:51:15.075Z",
   "packages": {
     "@uniweb/api": {
-      "version": "0.6.1",
+      "version": "0.6.2",
       "path": "framework/api",
       "deps": [
         "@uniweb/core"
       ]
     },
     "@uniweb/build": {
-      "version": "0.61.0",
+      "version": "0.63.0",
       "path": "framework/build",
       "deps": [
         "@uniweb/content-reader",
@@ -96,7 +96,7 @@
       "deps": []
     },
     "@uniweb/schemas": {
-      "version": "0.6.0",
+      "version": "0.7.0",
       "path": "framework/schemas",
       "deps": []
     },
@@ -116,7 +116,7 @@
       "deps": []
     },
     "@uniweb/templates": {
-      "version": "0.16.3",
+      "version": "0.17.0",
       "path": "framework/templates",
       "deps": []
     },
@@ -126,7 +126,7 @@
       "deps": []
     },
     "@uniweb/unipress": {
-      "version": "0.10.4",
+      "version": "0.10.6",
       "path": "framework/unipress",
       "deps": [
         "@uniweb/build",