uniweb 0.79.0 → 0.79.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.79.0",
+  "version": "0.79.2",
   "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/core": "^0.35.0",
+    "@uniweb/schemas": "^0.9.3",
+    "@uniweb/kit": "^0.19.11",
     "@uniweb/runtime": "^0.28.3",
-    "@uniweb/schemas": "^0.9.1",
     "@uniweb/content-writer": "^0.3.4",
-    "@uniweb/kit": "^0.19.11",
-    "@uniweb/core": "^0.35.0",
     "@uniweb/semantic-parser": "^1.4.1"
   },
   "peerDependencies": {
+    "@uniweb/build": "^0.73.2",
     "@uniweb/content-reader": "^1.2.7",
-    "@uniweb/semantic-parser": "^1.4.1",
-    "@uniweb/build": "^0.73.0"
+    "@uniweb/semantic-parser": "^1.4.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.
 
@@ -1037,9 +1041,17 @@ function MyComponent({ content, params, block }) {
 }
 ```
 
-Frontmatter becomes `params`, minus the keys the framework takes for itself: `type`, `id`, `hidden`, `query`, `fetch` (a `data:` key is refused — it was `query:`'s old name; `preset:` and `input:` are ignored with a warning). `props:` is the one that isn't dropped but merged *into* params.
+**Frontmatter becomes `params` — except the names framework keeps for itself.** Every section can be given these, whatever its type, and none of them reaches your component as a param. So **never declare one in `meta.js` `params:`** — a component that does never receives what an author writes.
+
+| in a section's frontmatter | what it is | a component reads it from |
+|---|---|---|
+| `type`, `id`, `hidden` | the section itself — its section type, its id, and a draft (`hidden: true`: left out of a published build, kept by `uniweb dev`) | — |
+| `query`, `fetch` | the section's data | `content.data`, under the keys its `meta.js` `data:` declares |
+| `theme`, `background`, `grid`, `vars` | the section's settings, which framework applies — the color context and the background around your component, the section's theme and your component's CSS variables in the page stylesheet, the child layout | `block`, when the component needs one for its own logic: `useColorContext(block)` for the context (a light vs. dark logo, say), `<SectionBackground block={block} />` to draw the background itself, `<ChildGrid from={block} />` for the grid |
+| `props` | params written as one map | `params` — its keys are merged in, one by one |
+| `data`, `preset`, `input` | nothing: `data:` is refused (it was `query:`'s old name); `preset:` and `input:` are ignored with a warning | — |
 
-**The section's own settings are not params either.** `theme`, `background`, `grid` and `vars` are framework's: it applies them — the color context and the background around your component, the section's theme and your component's CSS variables in the page stylesheet, the child layout through `ChildGrid` — so your component never receives them in `params`, and the build warns on a param declared with one of those names. When a component needs one for its own logic, it reads it from `block`: `useColorContext(block)` for the context (a light vs. dark logo, say), `<SectionBackground block={block} />` to draw the background itself, `<ChildGrid from={block} />` for the grid. Every other key is a param, declared or not; components ignore the ones they don't use.
+The build warns when `params:` declares any of them. A preset may still set `theme` or `background` — a preset's params are written into the section's frontmatter when an author starts a section from it, so `dark: { label: 'Dark', params: { theme: 'dark' } }` is a dark section. Every other key is a param, declared or not; components ignore the ones they don't use.
 
 ### Rendering content with Kit
 
@@ -2411,7 +2423,7 @@ For cases the factory doesn't cover, write handlers directly using `Loom`, `inst
 
 > **`instantiateContent` resolves `{placeholders}` in text nodes only** — not in link `href`s or other node/mark attributes. So `[{email}](mailto:{email})` fills the visible label but leaves the `mailto:` URL literal. For dynamic URLs, emit the value as plain text and let the component linkify it, or build the href in the handler yourself.
 
-**Reserved frontmatter:** `source` and `where` are convention-level reserved fields — they flow to both `block.properties` (for handler access) and `params` (visible to components), consistent with `background` and `theme`. Components can ignore them. List them in `meta.js` params with descriptions so the editor and schema recognize them.
+**`source` and `where` are ordinary params** that the Loom handler reads — they reach both `block.properties` (for handler access) and `params` (visible to components). Components can ignore them. List them in `meta.js` params with descriptions so the editor and schema recognize them. (Unlike `theme` and `background`, which are the section's own settings and never reach `params` — see the table under *Frontmatter becomes `params`*.)
 <!-- /template:loom -->
 
 ---

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-28T15:44:24.405Z",
+  "generatedAt": "2026-09-28T23:00:27.056Z",
   "packages": {
     "@uniweb/api": {
       "version": "0.6.8",
@@ -10,7 +10,7 @@
       ]
     },
     "@uniweb/build": {
-      "version": "0.73.0",
+      "version": "0.73.2",
       "path": "framework/build",
       "deps": [
         "@uniweb/content-reader",
@@ -97,7 +97,7 @@
       "deps": []
     },
     "@uniweb/schemas": {
-      "version": "0.9.1",
+      "version": "0.9.3",
       "path": "framework/schemas",
       "deps": []
     },

package/templates/foundation/package.json.hbs

@@ -14,7 +14,16 @@
     "#components/*": "./components/*",
     "#utils/*": "./utils/*"
   },
-  "files": ["dist", "sections", "components", "layouts", "utils", "main.js", "styles.css", "_entry.generated.js"],
+  "files": [
+    "dist",
+    "sections",
+    "components",
+    "layouts",
+    "utils",
+    "main.js",
+    "styles.css",
+    "_entry.generated.js"
+  ],
   "scripts": {
     "dev": "vite",
     "build": "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/