uniweb 0.78.0 → 0.79.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.78.0",
+  "version": "0.79.1",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -41,17 +41,17 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
-    "@uniweb/runtime": "^0.28.3",
     "@uniweb/kit": "^0.19.11",
+    "@uniweb/schemas": "^0.9.2",
     "@uniweb/core": "^0.35.0",
+    "@uniweb/runtime": "^0.28.3",
     "@uniweb/content-writer": "^0.3.4",
-    "@uniweb/semantic-parser": "^1.4.1",
-    "@uniweb/schemas": "^0.9.1"
+    "@uniweb/semantic-parser": "^1.4.1"
   },
   "peerDependencies": {
     "@uniweb/content-reader": "^1.2.7",
     "@uniweb/semantic-parser": "^1.4.1",
-    "@uniweb/build": "^0.72.0"
+    "@uniweb/build": "^0.73.1"
   },
   "peerDependenciesMeta": {
     "@uniweb/build": {

package/partials/agents.md

@@ -866,6 +866,10 @@ site/
 
 Keep those folders flat: `records/article/design-tips.md` works; `records/article/2025/design-tips.md` is read as the `2025` schema of an `article` org, which is not what you meant. Organise in `records/folder.yml` instead. A file whose name starts with `_` is not a record — somewhere to keep work in progress.
 
+**Links are records too — `@uniweb/link`.** A file in `records/uniweb/link/` holding `url:` and nothing else is a link record (one per file; no body, no other fields). Its display text and tags go on its `records/folder.yml` entry (`- path: uniweb/link/launch-video.yml` with `label:` / `tags:`), like any record's. Select links with a query `schema: '@uniweb/link'` and declare them in `meta.js` as `data: { videos: '@uniweb/link' }`; each arrives as `{ url, $name, $label, $tags }`. A link's `url` is absolute (`https://…`), and `uniweb push` refuses a relative one and a `draft: true` link.
+
+**Files are records too — `@uniweb/file`.** The file itself is the record: any file dropped into `records/uniweb/file/` (a PDF, a spreadsheet, any type) is a record named by its file name without the extension; nothing in it is read. Its label and tags go on its `records/folder.yml` entry (`- path: uniweb/file/brochure.pdf`). Query with `schema: '@uniweb/file'`, declare with `data: { downloads: '@uniweb/file' }`; each arrives as `{ file: { url, name, mime, size }, $name, $label, $tags }` — link to `file.url`. `uniweb push` uploads the file with the site's media; a pull fetches it back. Two files of one name with different extensions clash — rename one. On a site that goes to a backend, a component must declare the type (`@uniweb/link` or `@uniweb/file`) for a query over it to be accepted.
+
 **Four formats, one shape.** All of these produce the same records at runtime:
 
 | Format | Best for | Notes |
@@ -907,7 +911,7 @@ The body — the value of the schema's content field, `body.content`.
     - article/2025-*.md
 ```
 
-A path under a folder is relative to `records/`, naming one file or matching many. A record's entry can instead be `{ path, tags, label }` — what the folder says about the record: a component receives them beside it as `$tags` (in the order written) and `$label`, and a query reads them like any key (`where: { $tags: featured }`); such an entry may sit at the top level, where a bare path is refused. A folder takes `tags:` too. A query reads one folder with `scope: archive` — the folder and everything inside it. A record sits in one folder; if you want a computed subset, that is a query, not a second placement. Structure is for querying, not for navigation — and `folder.yml` never lists a record at the top level (the build refuses it: every file in `records/` is a record already).
+A path under a folder is relative to `records/`, naming one file or matching many. A record's entry can instead be `{ path, tags, label }` — what the folder says about the record: a component receives them beside it as `$tags` (in the order written) and `$label`, and a query reads them like any key (`where: { $tags: featured }`); such an entry may sit at the top level, where a bare path is refused. A `label` — a record entry's or a folder's — is one text in the site's language, or one per language (`label: { en: Launch video, fr: Vidéo de lancement }`); `$label` is the page's language, else its base language, else the site's. A folder takes `tags:` too. A query reads one folder with `scope: archive` — the folder and everything inside it. A record sits in one folder; if you want a computed subset, that is a query, not a second placement. Structure is for querying, not for navigation — and `folder.yml` never lists a record at the top level (the build refuses it: every file in `records/` is a record already).
 
 ⚠️ **With a backend, `records/` is what `uniweb push` sends** — every record in it. A site with no `records/` at all leaves the backend's records alone; an *empty* `records/` removes them, and the CLI asks before it does. Records pushed to a backend are served once the site is published.
 

package/src/backend/asset-download.js

@@ -171,3 +171,52 @@ export async function downloadMissingAssets({
     updateBackendMap(siteDir, origin, 'assets', learned, carryServed)
   return out
 }
+
+/**
+ * Fetch the files a pull's file records name (`@uniweb/file`) to where each lands in
+ * `records/uniweb/file/` — the list `recordsToProject` returns as `fileDownloads` — and record each
+ * one's asset under its key (`sync.json` `assets`), as a push records the upload, so the next pull
+ * knows the bytes on disk are that asset and fetches nothing.
+ *
+ * @param {object} opts
+ * @param {Array<{ url: string, path: string, ref: string, assetId?: string, assetExt?: string }>} opts.downloads
+ * @param {string} opts.siteDir
+ * @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[], failed: string[] }>} paths
+ */
+export async function downloadFileRecords({
+  downloads = [],
+  siteDir,
+  origin,
+  fetchImpl,
+  onProgress = () => {},
+  warn = () => {}
+}) {
+  const doFetch = fetchImpl || ((u) => globalThis.fetch(u))
+  const out = { downloaded: [], failed: [] }
+  const learned = {}
+  for (const d of downloads) {
+    try {
+      const res = await doFetch(new URL(d.url, origin).href)
+      if (!res.ok) {
+        warn(`file ${d.ref}: HTTP ${res.status} — not fetched`)
+        out.failed.push(d.path)
+        continue
+      }
+      const bytes = Buffer.from(await res.arrayBuffer())
+      mkdirSync(dirname(d.path), { recursive: true })
+      writeFileSync(d.path, bytes)
+      onProgress(`↓ ${d.ref}`)
+      out.downloaded.push(d.path)
+      if (d.assetId) learned[d.ref] = { id: d.assetId, ext: d.assetExt || '' }
+    } catch (err) {
+      warn(`file ${d.ref}: ${err.message} — not fetched`)
+      out.failed.push(d.path)
+    }
+  }
+  if (Object.keys(learned).length) updateBackendMap(siteDir, origin, 'assets', learned, carryServed)
+  return out
+}

package/src/backend/site-media.js

@@ -24,7 +24,8 @@ import { humanBytes } from '../utils/bytes.js'
  * @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 {Array<string|{ ref: string, path: string, contentType?: string }>} refs - site-root local
+ *        asset refs (`/images/x.png`), or files already located (a file record's)
  * @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
@@ -47,8 +48,15 @@ export async function uploadSiteMedia(
 
   const files = []
   const missing = []
-  for (const ref of refs) {
-    const { resolved } = resolveAssetPath(ref, siteDir, siteDir)
+  // ⭐ A ref is a site-root media path (`/images/x.png`), resolved under the site — or a file the
+  // caller already located, `{ ref, path, contentType }`: a file record's file and its preview, which
+  // live in the records directory and declare their own type (`@uniweb/file`, 2026-09-28).
+  const keys = []
+  for (const item of refs) {
+    const ref = typeof item === 'string' ? item : item?.ref
+    if (typeof ref !== 'string' || !ref) continue
+    keys.push(ref)
+    const resolved = typeof item === 'string' ? resolveAssetPath(ref, siteDir, siteDir).resolved : item.path
     if (!resolved || !existsSync(resolved)) {
       warn?.(`local-media: ${ref} not found under the site (skipped)`)
       missing.push(ref)
@@ -57,7 +65,7 @@ export async function uploadSiteMedia(
     const bytes = readFileSync(resolved)
     files.push({
       path: ref.replace(/^\/+/, ''), // bookkeeping key into the plan (must be unique)
-      content_type: contentTypeFor(basename(resolved)),
+      content_type: (typeof item === 'object' && item.contentType) || contentTypeFor(basename(resolved)),
       size: bytes.length,
       sha256: createHash('sha256').update(bytes).digest('hex'),
       localUrl: ref, // the rewrite key — the original content ref
@@ -77,7 +85,7 @@ export async function uploadSiteMedia(
   // 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) {
+  for (const ref of keys) {
     const entry = result.assetsByLocalUrl[ref]
     if (!entry) continue
     // `served` — a fingerprint of the address, never the address. It is how a pull

package/src/backend/site-sync.js

@@ -49,7 +49,10 @@ import {
   matchStoredRecords,
   parseCatalogRef,
   readRegisteredFoundation,
-  writeRegisteredFoundation
+  writeRegisteredFoundation,
+  backfillLinkUuids,
+  LINK_MODEL,
+  bankedFileUuids
 } from '@uniweb/build/uwx'
 
 // First entity `$`-document out of a `.uwx` we produced or the backend served.
@@ -1419,7 +1422,9 @@ export async function recoverUnbankedIdentity({ client, siteDir, pkg, note }) {
   }
   // The records the package sends, and the folder placing them. The emit reads the `records`
   // map from sync.json itself, so it needs no option — only the build again.
-  if (await recoverRecordsIdentity({ client, siteDir, index: pkg?.records?.index, note })) {
+  // Link records are matched as records are — by Model and name (`@uniweb/link`, `link-records.js`).
+  const links = (pkg?.records?.links || []).map((l) => ({ ownId: l.ownId, model: LINK_MODEL, slug: l.slug }))
+  if (await recoverRecordsIdentity({ client, siteDir, index: [...(pkg?.records?.index || []), ...links], note })) {
     again = {
       ...again,
       folderItemUuids: readFolderItemUuids(siteDir, client.origin),
@@ -1754,7 +1759,7 @@ export async function pushSyncPackages({
       // Two unrelated conflicts share HTTP 409, so branch on the machine-readable
       // `reason` — never on `detail`, which is prose the backend may reword.
       let problem = null
-      if ((res.status === 409 || res.status === 400) && body) {
+      if ((res.status === 409 || res.status === 400 || res.status === 422) && body) {
         try {
           problem = JSON.parse(body)
         } catch {
@@ -1934,6 +1939,15 @@ export async function pushSyncPackages({
           `  deleted there  →  uniweb forget --backend ${client.origin}, then push again: it creates a NEW site`
         )
         note('Deleting this folder removes only your local copy, either way.')
+      } else if (problem?.reason === 'template_records_not_copyable' && Array.isArray(problem.records)) {
+        // ⭐ A push asking to designate the site a template is refused whole when a record in its
+        // folder cannot be copied into the sites made from it — each named, with a `detail` written
+        // to be shown. Until 2026-09-28 this printed the raw problem document, cut at 800 characters.
+        note(problem.title || 'These records cannot be copied into a template:')
+        for (const r of problem.records) {
+          note(`  ${r?.name ?? '(unnamed)'} — ${r?.detail || r?.reason || 'no reason given'}`)
+        }
+        return null
       } else if (res.status === 409 && (problem?.title || problem?.detail)) {
         // ⛔ A 409 names its own cause — a reference the store refuses, a rule of the record's type,
         // an append-only section — so it is shown as the backend put it, not explained by us. Until
@@ -2240,6 +2254,20 @@ export async function pushSyncPackages({
       const placements = collectFolderItemUuids(folderDoc)
       if (Object.keys(placements).length)
         writeFolderItemUuids(siteDir, client.origin, placements)
+      // ⭐ A LINK RECORD'S IDENTITY is its folder entry's `$uuid`, banked as a record's is: into
+      // its file the first time, then mapped per backend (`link-records.js`, 2026-09-28).
+      if (records.links?.length) {
+        const lb = backfillLinkUuids({ links: records.links, folderDoc })
+        if (Object.keys(lb.mapped).length) updateBackendMap(siteDir, client.origin, 'records', lb.mapped)
+        for (const w of lb.warnings) note(`! ${w}`)
+        if (lb.updated.length) wrote.push(`wrote ${lb.updated.length} link file(s)`)
+      }
+      // ⭐ …and a FILE RECORD's: a file cannot carry it, so it is banked per backend by the file's
+      // path (`sync.json` `files`; `file-records.js`, 2026-09-28).
+      if (records.files?.length) {
+        const fb = bankedFileUuids({ files: records.files, folderDoc })
+        if (Object.keys(fb).length) updateBackendMap(siteDir, client.origin, 'files', fb)
+      }
     }
     finalizedTotal += finalized.length
   }

package/src/commands/publish.js

@@ -656,7 +656,8 @@ export async function publish(args = []) {
   //     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])]
+  // …and each file record's file (`@uniweb/file` — `{ ref, path, contentType }`, already located).
+  const mediaRefs = [...new Set([...localAssets, ...ballAssets]), ...(probe.localFiles || [])]
   if (mediaRefs.length) {
     say.info('Uploading media…')
     try {

package/src/commands/pull.js

@@ -69,7 +69,7 @@ import { createHash } from 'node:crypto'
 import { createInterface } from 'node:readline/promises'
 import { join, dirname, relative, resolve } from 'node:path'
 import yaml from 'js-yaml'
-import { downloadMissingAssets } from '../backend/asset-download.js'
+import { downloadMissingAssets, downloadFileRecords } from '../backend/asset-download.js'
 import {
   readBackendState,
   siteContentDocumentToProject,
@@ -1068,6 +1068,25 @@ export async function pull(args = [], deps = {}) {
         removed.push(resolve(siteDir, report.recordsFile))
       }
       records += report.placed.length + report.updated.length
+      // ⭐ A FILE RECORD'S BYTES (`@uniweb/file`, 2026-09-28): fetched to where `folder.yml` now
+      // places each one, as media are fetched. A file that did not arrive is a record not taken —
+      // reported, and the pull fails below as it does for any, so the next one fetches it again.
+      if (report.fileDownloads?.length) {
+        const got = await downloadFileRecords({
+          downloads: report.fileDownloads,
+          siteDir,
+          origin: client.origin,
+          onProgress: (m) => note(`  ${m}`),
+          warn: (m) => note(`! ${m}`)
+        })
+        records += got.downloaded.length
+        wrote.push(...got.downloaded)
+        if (got.failed.length) {
+          report.skipped.push(
+            ...got.failed.map((path) => ({ slug: relative(siteDir, path), reason: 'its file could not be fetched' }))
+          )
+        }
+      }
       // ⛔ A PULL THAT DID NOT PLACE A RECORD HAS NOT TAKEN THE BACKEND'S RECORDS.
       // Until 2026-09-23 each skip was a dim note, the pull said "✓ Pulled … 0
       // record(s)" and exited 0, and it banked the lane's ETag and tokens. So the next

package/src/commands/push.js

@@ -409,7 +409,8 @@ export async function push(args = [], deps = {}) {
         ...(foundationDir ? { foundationDir } : {}),
         resolveModel: makeModelResolver({ client, offline: false, siteDir })
       })
-      mediaRefs = probe.localAssets || []
+      // Site-root media, and each file record's file (`@uniweb/file` — `{ ref, path, contentType }`).
+      mediaRefs = [...(probe.localAssets || []), ...(probe.localFiles || [])]
       refusals = probe.refusals || []
     } catch (err) {
       error(`Could not scan the site for local media: ${err.message}`)

package/src/framework-index.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-09-28T12:54:31.686Z",
+  "generatedAt": "2026-09-28T21:05:39.664Z",
   "packages": {
     "@uniweb/api": {
       "version": "0.6.8",
@@ -10,7 +10,7 @@
       ]
     },
     "@uniweb/build": {
-      "version": "0.72.0",
+      "version": "0.73.1",
       "path": "framework/build",
       "deps": [
         "@uniweb/content-reader",
@@ -97,7 +97,7 @@
       "deps": []
     },
     "@uniweb/schemas": {
-      "version": "0.9.1",
+      "version": "0.9.2",
       "path": "framework/schemas",
       "deps": []
     },
@@ -127,7 +127,7 @@
       "deps": []
     },
     "@uniweb/unipress": {
-      "version": "0.10.15",
+      "version": "0.10.16",
       "path": "framework/unipress",
       "deps": [
         "@uniweb/build",

package/templates/site/_gitignore

@@ -4,7 +4,9 @@ dist
 .DS_Store
 *.local
 
-# Compiled collections. Generated from collections/ on every build — it lands
-# in the source tree rather than dist/, so without this it looks permanent,
-# gets committed, and then looks like something you may edit. It isn't.
+# Generated from records/ on every build — compiled queries in public/data/, and
+# each record's files, published in public/records/. Both land in the source tree
+# rather than dist/, so without this they look permanent, get committed, and then
+# look like something you may edit. They aren't: records live in records/.
 public/data/
+public/records/