uniweb 0.67.0 → 0.68.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.67.0",
+  "version": "0.68.0",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -43,13 +43,13 @@
     "tar": "^7.0.0",
     "@uniweb/content-writer": "^0.3.4",
     "@uniweb/core": "^0.29.8",
-    "@uniweb/kit": "^0.19.4",
-    "@uniweb/schemas": "^0.6.0",
     "@uniweb/runtime": "^0.27.4",
+    "@uniweb/kit": "^0.19.4",
+    "@uniweb/schemas": "^0.7.0",
     "@uniweb/semantic-parser": "^1.4.1"
   },
   "peerDependencies": {
-    "@uniweb/build": "^0.61.0",
+    "@uniweb/build": "^0.62.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 (a second pass 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

@@ -1186,8 +1186,12 @@ export async function probeUnpushed(siteDir, { backend = null, sendAll = false }
   // ⚠️ Until 2026-09-23 this said the site's recorded ORG resolves it and must be
   // passed in — true before 2026-09-22, and read as a reason to pass it.
   const pkg = await comparisonEmit(siteDir, { backend, priorHashes, sendAll })
+  // A record held back for a reference (`pushInPasses`) is not in either lane, and is
+  // still unpushed.
   const changed =
-    (pkg.siteContent?.entityCount || 0) + (pkg.records?.entityCount || 0)
+    (pkg.siteContent?.entityCount || 0) +
+    (pkg.records?.entityCount || 0) +
+    (pkg.waiting || []).filter((w) => w.held).length
   return { changed, unchanged: pkg.skipped || 0, warnings: pkg.warnings || [] }
 }
 
@@ -1846,3 +1850,78 @@ export async function pushSyncPackages({
   }
   return { exitCode: 0, boundSiteUuid, finalizedTotal, wrote }
 }
+
+/**
+ * Push, then push again while records WAIT for a reference's record — the verbs' way to
+ * send a package (`push`, `publish`).
+ *
+ * ⭐ A reference is sent as the uuid the backend minted for the record it names, so a
+ * record that points at one created by the same push cannot be completed in that push
+ * (`@uniweb/build`'s `emitSyncPackages` → `waiting`). The first pass creates what it can —
+ * records whose waiting references are not required go without them — and each further
+ * pass, emitted afresh from the state the last one banked, sends what has become
+ * nameable. A chain of required references takes one pass per link; two records that
+ * each require the other can never be completed, and the push stops, naming them.
+ *
+ * @param {object} params
+ * @param {object} params.pkg - the first pass's package (`emitSyncPackages`)
+ * @param {() => Promise<object>} params.reemit - the next pass's package, emitted afresh
+ * @param {Function} [params.push] - sends one package; `pushSyncPackages` (a test's seam)
+ * @returns {Promise<{ exitCode: number, boundSiteUuid?: string, finalizedTotal: number, wrote: string[], passes: number }>}
+ */
+export async function pushInPasses({ client, siteDir, pkg, report, reemit, maxPasses = 12, push = pushSyncPackages }) {
+  const { note, error } = report
+  let current = pkg
+  let passes = 1
+  let result = await push({ client, siteDir, pkg: current, report })
+  let finalizedTotal = result.finalizedTotal || 0
+  const wrote = [...(result.wrote || [])]
+  while (result.exitCode === 0 && current.waiting?.length) {
+    const n = current.waiting.length
+    note(
+      `${n} record${n === 1 ? '' : 's'} name${n === 1 ? 's' : ''} a record this push created — ` +
+        `pushing again to complete ${n === 1 ? 'its references' : 'their references'}.`
+    )
+    let next
+    try {
+      next = await reemit()
+    } catch (err) {
+      error(`Could not build the next pass: ${err.message}`)
+      return { ...result, exitCode: 1, finalizedTotal, wrote, passes }
+    }
+    if (refuseUnsendableRecords(next.refusals, report)) {
+      return { ...result, exitCode: 1, finalizedTotal, wrote, passes }
+    }
+    // Nothing became nameable: every record still waiting waits on one that waits too.
+    if (waitingKey(next.waiting) === waitingKey(current.waiting) || passes >= maxPasses) {
+      error(
+        'These records could not be completed — each requires a reference to a record that ' +
+          'is itself waiting to be created:'
+      )
+      for (const w of next.waiting || []) {
+        const refs = w.pending.map((p) => `${p.path} → "${p.name}"`).join(', ')
+        note(`  ${w.id} (${w.model}): ${refs}`)
+      }
+      note(
+        'Push one of them without that reference first — or make it optional in the schema — ' +
+          'then add it back and push again.'
+      )
+      return { ...result, exitCode: 1, finalizedTotal, wrote, passes }
+    }
+    current = next
+    passes++
+    result = await push({ client, siteDir, pkg: current, report })
+    finalizedTotal += result.finalizedTotal || 0
+    for (const w of result.wrote || []) if (!wrote.includes(w)) wrote.push(w)
+  }
+  return { ...result, finalizedTotal, wrote, passes }
+}
+
+// Which records wait, and on what — two passes that leave it the same made no progress.
+function waitingKey(waiting) {
+  return JSON.stringify(
+    (waiting || [])
+      .map((w) => [w.model, w.id, w.pending.map((p) => `${p.path}:${p.name}`).sort()])
+      .sort()
+  )
+}

package/src/commands/publish.js

@@ -90,7 +90,8 @@ import {
   refuseUnsendableRecords,
   clearRemoteSyncStateIfUnbound,
   dropSiteBoundValues,
-  pushSyncPackages
+  readItemUuids,
+  pushInPasses
 } from '../backend/site-sync.js'
 import { resolveWorkspace, describeWorkspace, SOURCE_LABEL } from '../backend/workspace.js'
 import { uploadSiteMedia, describeAssetRefusal } from '../backend/site-media.js'
@@ -767,12 +768,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,9 +943,14 @@ export async function publish(args = []) {
     say.dim('Services unchanged.')
   }
 
-  let pkg
-  try {
-    pkg = await emitSyncPackages(siteDir, {
+  // The emit's options, read afresh for each pass (`pushInPasses`): a pass banks
+  // hashes, identity and base versions that the next one must build on.
+  //
+  // 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')
+  const emitOptions = ({ priorHashes, itemUuids }) => ({
       backend: client.origin,
       ...(declaration.declare ? {} : { declareServices: false }),
       // Placement identity for the folder — see writeFolderItemUuids.
@@ -959,14 +959,20 @@ 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 } : {}),
       ...(assetIds ? { assetIds } : {})
-    })
+  })
+  let pkg
+  try {
+    pkg = await emitSyncPackages(siteDir, emitOptions({ priorHashes, itemUuids }))
   } catch (err) {
     say.err(`Could not build the sync package: ${err.message}`)
     return { exitCode: 1 }
@@ -981,11 +987,19 @@ export async function publish(args = []) {
     error: (m) => say.err(m),
     dim: (s) => `${c.dim}${s}${c.reset}`
   }
-  const pushResult = await pushSyncPackages({
+  const pushResult = await pushInPasses({
     client,
     siteDir,
     pkg,
-    report
+    report,
+    reemit: () =>
+      emitSyncPackages(
+        siteDir,
+        emitOptions({
+          priorHashes: readSyncCache(siteDir, client.origin),
+          itemUuids: readItemUuids(siteDir, client.origin)
+        })
+      )
   })
   if (pushResult.exitCode !== 0) return { exitCode: pushResult.exitCode }
   const siteUuid = pushResult.boundSiteUuid

package/src/commands/push.js

@@ -87,7 +87,7 @@ import {
   ensureSiteExists,
   clearRemoteSyncStateIfUnbound,
   dropSiteBoundValues,
-  pushSyncPackages
+  pushInPasses
 } from '../backend/site-sync.js'
 import { resolveWorkspace, describeWorkspace, SOURCE_LABEL } from '../backend/workspace.js'
 
@@ -496,9 +496,9 @@ export async function push(args = [], deps = {}) {
     output || dryRun
       ? readItemUuids(siteDir, client.origin)
       : await ensureItemUuids({ client, siteDir, note })
-  let pkg
-  try {
-    pkg = await emitSyncPackages(siteDir, {
+  // The emit's options, read afresh for each pass (`pushInPasses`): a pass banks
+  // hashes, identity and base versions that the next one must build on.
+  const emitOptions = ({ priorHashes, sendAll, itemUuids }) => ({
       backend: client.origin,
       // Placement identity for the folder — see writeFolderItemUuids.
       folderItemUuids: readFolderItemUuids(siteDir, client.origin),
@@ -529,7 +529,10 @@ export async function push(args = [], deps = {}) {
           }),
       ...(assetRewrite ? { assetRewrite } : {}),
       ...(assetIds ? { assetIds } : {})
-    })
+  })
+  let pkg
+  try {
+    pkg = await emitSyncPackages(siteDir, emitOptions({ priorHashes, sendAll, itemUuids }))
   } catch (err) {
     error(`Could not build the sync package: ${err.message}`)
     return { exitCode: 2 }
@@ -595,8 +598,9 @@ export async function push(args = [], deps = {}) {
   }
 
   // Submit both lanes, back-fill the minted uuids, and persist the send-only-changed
-  // cache. Shared with `uniweb publish` via ../backend/site-sync.js.
-  const result = await pushSyncPackages({
+  // cache — again for any record whose reference names a record this push created.
+  // Shared with `uniweb publish` via ../backend/site-sync.js.
+  const result = await pushInPasses({
     client,
     siteDir,
     pkg,
@@ -605,7 +609,16 @@ export async function push(args = [], deps = {}) {
       note,
       error,
       dim: (s) => `${colors.dim}${s}${colors.reset}`
-    }
+    },
+    reemit: () =>
+      emitSyncPackages(
+        siteDir,
+        emitOptions({
+          priorHashes: readSyncCache(siteDir, client.origin),
+          sendAll: false,
+          itemUuids: readItemUuids(siteDir, client.origin)
+        })
+      )
   })
   if (result.exitCode !== 0) return { exitCode: result.exitCode }
   success(

package/src/framework-index.json

@@ -1,16 +1,16 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-09-24T19:00:27.393Z",
+  "generatedAt": "2026-09-24T21:52:18.260Z",
   "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.62.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.5",
       "path": "framework/unipress",
       "deps": [
         "@uniweb/build",