uniweb 1.21.23 → 1.22.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "1.21.23",
+  "version": "1.22.1",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -41,15 +41,15 @@
     "js-yaml": "^4.3.2",
     "prompts": "^2.4.2",
     "tar": "^7.5.21",
-    "@uniweb/content-writer": "~1.3.1",
     "@uniweb/core": "~1.4.12",
+    "@uniweb/semantic-parser": "~1.13.0",
     "@uniweb/schemas": "~1.6.5",
-    "@uniweb/semantic-parser": "~1.13.0"
+    "@uniweb/content-writer": "~1.3.1"
   },
   "peerDependencies": {
-    "@uniweb/build": "~1.10.14",
+    "@uniweb/semantic-parser": "~1.13.0",
     "@uniweb/content-reader": "~1.5.7",
-    "@uniweb/semantic-parser": "~1.13.0"
+    "@uniweb/build": "~1.11.1"
   },
   "peerDependenciesMeta": {
     "@uniweb/build": {

package/partials/agents.md

@@ -544,7 +544,9 @@ Optional attributes: `{size=20}`, `{color=red}`. Custom SVGs: `![Logo](./logo.sv
 ![alt](./img.jpg){href=/products}       <!-- Clickable media: href + target ride along -->
 ```
 
-Sizing and loading ride on the image: `{width=800 height=600 loading=lazy fit=cover position=center}`, and its credit as `{author="Jane Doe"}`. A video adds `{poster=./thumb.jpg autoplay muted loop controls}`; a `{role=pdf}` document adds `{preview=./cover.jpg author=… description=…}` and arrives in `content.documents` — `{ url, name, mime, size?, alt, caption, … }` — declare it in `content:` as `documents`.
+Sizing and loading ride on the image: `{width=800 height=600 loading=lazy fit=cover position=center}`, and its credit as `{author="Jane Doe"}`. A video adds `{poster=./thumb.jpg autoplay muted loop controls}`; a `{role=pdf}` document adds `{preview=./cover.jpg author=… description=…}` and arrives in `content.documents` — `{ url, name, mime, size?, alt, caption, … }` — declare it in `content:` as `documents`. Name a video's poster: a static build makes one from the video only when none is named and ffmpeg is installed, and `uniweb publish` sends only the poster you name.
+
+**Where media lives.** `./x` names a file beside the page, `/x` a file in `public/`, and both reach a static build and a site published with Uniweb. Keep a page's media beside it, and keep in `public/` what needs a fixed address: the favicon, fonts, a file other sites link to. A static build copies `public/` whole and adds its own copy of each file a page names there, so a video only a page shows is in `dist/` twice from `public/` and once from beside the page. `uniweb push` uploads a file beside a page wherever the page is, in a folder `paths:` mounts too; a file outside the site and the folders it mounts is not uploaded, so put that in `public/`. A site has no `assets/` folder for media: a build stops on a `/x` only `assets/` holds.
 
 **Placement — where a block sits in a section rendered in order.** `{placement=left}` (or `right`, `wide`, `full`) on an image or a video; a table takes it on its **caption line**, the paragraph after the table, after a blank line — `: Plans and prices {placement=wide #tbl-plans}`, which also gives the table a caption and a cross-reference id. It is the author's intent, not a size: kit's `<Render>`, `<Prose>` and `<Article>` lay all four out (`data-placement`, styled by `prose-tokens.css`), and any other component ignores it. A section type says which it honours in `meta.js` — `sequence: { label, placement: true }` — and the build warns when a file asks for one its type does not offer.
 
@@ -2877,8 +2879,8 @@ Foundations have their own free path too: `uniweb add ci --target foundation` pu
 **Three facts about a site, and they are independent — `uniweb status` opens with all three:**
 
 - **Synced** — the project has a site on a backend, so authors can edit it in the Uniweb app. `sync.json` names it on each backend: `https://uniweb.app` by default, or a server of your own (`uniweb login --server <url>`).
-- **Published** — that backend serves it live: Uniweb Cloud, on `https://uniweb.app`. A published site is a synced site; a synced site need not be published — it can sit in the app as a draft.
-- **Deployed** — a build of it is on another host, such as GitHub Pages or S3: by CI on every push (`uniweb add ci`), or by hand (`uniweb deploy`). `deploy.yml` lists those hosts, and a bare `uniweb deploy` goes to its default target.
+- **Published** — that backend serves it live: Uniweb Cloud, on `https://uniweb.app`. A published site is a synced site; a synced site need not be published — it can sit in the app as a draft. A publish is recorded in `deploy.yml` too, under a `host: uniweb` target: `deploys.<target>.url` is the address that publish delivered to. Where visitors go now (a custom domain, while one is active) is the backend's answer, and `uniweb status` shows it.
+- **Deployed** — a build of it is on another host, such as GitHub Pages or S3: by CI on every push (`uniweb add ci`), or by hand (`uniweb deploy`). `deploy.yml` lists those hosts beside the one a publish records, and a bare `uniweb deploy` goes to its default target.
 
 A site can be in more than one place — usually while it moves from one host to another. Before you ship, read where it is: `publish` makes a change live on Uniweb Cloud, `git push` on a CI-deployed host, and `uniweb deploy --target <name>` on one deployed by hand — and each of these is the person's to decide. `uniweb status` also lists the services the live site has (`services:` in `site.yml` is the request, never proof of what the site has).
 
@@ -3074,6 +3076,8 @@ These are **body only — no frontmatter**; params and config still come from th
 
 **A tagged data block translates by the shape its key declares** in the component's `meta.js` `data:` — a data schema or an inline field map: its text fields, never an enum, a URL or a `translatable: false` field. A key declared `{}` leaves its blocks to a heuristic that offers any string whose field name and value don't look structural, so a `style: display-black` naming one of your component's looks gets translated too. Declare the shape of every block a translator will see — `{ name: 'string', style: { type: 'string', enum: [...] } }`.
 
+**An image translates by its alt text.** Words alone give it its alt text in that language and keep its file. A translation that is an image also names the file that language shows: `"2d093636": "![La superposition](/docs-media/fr/overview.png)"`. Name it with a `/` path, a file in `public/`, and a build processes it as it does the page's own images; a `./` path has no page's folder to start from, and the build reports it. A caption or a video's `poster` can be given the same way. An image with no alt text has nothing to translate, so give every image one.
+
 **Records translate in the same `extract` run**, into their own manifest at `locales/records/manifest.json` — keyed by the RECORD, so a record translated once is found by every query that returns it. A record whose query has a data schema translates exactly the fields the schema says are text — never an enum, a URL, a date, a number, a file, a reference or a `translatable: false` field — which are the fields a push carries in each language; mark a string that is a code or a key `translatable: false` and no translator is asked for it. An excerpt the build derives is re-derived from each language's body.
 
 **Component side.** Nothing to do: `content.title` arrives in the active language. The one thing a foundation builds is a switcher.

package/src/backend/site-media.js

@@ -5,7 +5,8 @@
  *
  * Input is the site-root asset refs the producer surfaced in
  * `emitSyncPackages().localAssets` (`/images/hero.png`); `resolveAssetPath` finds the
- * file under the site's `public/` (or `assets/`). A ref whose file is missing is
+ * file under the site's `public/`, and refuses one only `assets/` holds, a folder retired
+ * 2026-10-28. A ref whose file is missing is
  * skipped (warned), never a broken serve URL. The serve URL is the backend's canonical
  * `serve_url`, read verbatim — origin-relative forms included; nothing here composes one.
  * Content-addressed like every asset: identical bytes → same id → a re-deploy of
@@ -49,8 +50,9 @@ export async function uploadSiteMedia(
   const files = []
   const missing = []
   // ⭐ 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).
+  // 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), and a
+  // section's co-located file, keyed by its path from the site root (`uwx/located-media.js`, 2026-10-28).
   const keys = []
   for (const item of refs) {
     const ref = typeof item === 'string' ? item : item?.ref

package/src/backend/site-sync.js

@@ -29,7 +29,6 @@ import {
 } from '../utils/sync-point.js'
 import { siteContentRoots } from '../utils/git.js'
 import { humanBytes } from '../utils/bytes.js'
-import { isAuthoredPreview } from '../utils/preview.js'
 import {
   describeRequestError,
   describeWorkspace,
@@ -56,7 +55,6 @@ import {
   updateBackendMap,
   clearBackendSections,
   normalizeBackendOrigin,
-  writeSiteConfig,
   harvestRecordItems,
   storedRecordItems,
   reprintRecordItems,
@@ -734,51 +732,6 @@ export function clearRemoteSyncStateIfUnbound(siteDir, backend) {
   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. Today that is
- * one value: `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.
- *
- * (`$url`, where the previous site was live, was dropped here too until it was
- * retired on 2026-09-17. A leftover line is inert — nothing reads or sends it.)
- *
- * 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, backend) {
-  const file = join(siteDir, 'site.yml')
-  let y
-  try {
-    y = yaml.load(readFileSync(file, 'utf8'))
-  } catch {
-    return []
-  }
-  // ⛔ "Bound" is a question about THIS backend, answered by sync.json. This read
-  // `site.yml::$uuid` until 2026-09-20 and kept doing so after step 4 moved the key —
-  // so every project read as unbound and every push stripped a bound site's
-  // generated preview. A write, from a stale read, with nothing to notice it.
-  if (!y || typeof y !== 'object') return []
-  if (readBackendState(siteDir, backend).site?.uuid) return []
-  const dropped = []
-  if (
-    y.preview !== undefined &&
-    !isAuthoredPreview(y.preview) &&
-    writeSiteConfig(siteDir, { preview: null }) === 'updated'
-  ) {
-    dropped.push('preview')
-  }
-  return dropped
-}
-
 export function readSyncCache(siteDir, backend) {
   return readMap(siteDir, backend, 'hashes')
 }

package/src/commands/build.js

@@ -69,10 +69,6 @@ import {
   isExtensionPackage,
   detectFoundationType
 } from '@uniweb/build'
-import {
-  resolveDefaultLocale,
-  normalizeLanguageList
-} from '@uniweb/core/locale-config'
 import { readSiteConfig } from '@uniweb/build/site'
 import { workspacePackages } from '../utils/workspace-packages.js'
 
@@ -424,34 +420,25 @@ async function loadI18nConfig(projectDir, siteConfig = null) {
   const localesDir = config.i18n?.localesDir || 'locales'
   const localesPath = join(projectDir, localesDir)
 
-  // Resolve locales (undefined/'*' → all available, array → specific)
-  const { resolveLocales } = await import('@uniweb/build/i18n')
-  let locales = await resolveLocales(config.languages, localesPath)
-
-  // Publish filter: build outputs are visitor artifacts. With an explicit
-  // `publishLanguages:`, only listed locales get dist/{locale}/ content,
-  // per-locale HTML, hreflang, and translated collections. Draft locales
-  // stay previewable in dev, which doesn't run this path. Intersecting the
-  // DISK-resolved list here also covers wildcard (`languages: '*'`) sites.
-  if (config.publishLanguages != null) {
-    const publishSet = new Set(normalizeLanguageList(config.publishLanguages))
-    const dropped = locales.filter((l) => !publishSet.has(l))
-    locales = locales.filter((l) => publishSet.has(l))
-    if (dropped.length > 0) {
-      info(
-        `Skipping non-publishable locale(s): ${dropped.join(', ')} (not in publishLanguages)`
-      )
-    }
+  // The site's locales (undefined/'*' → all available, array → specific), with
+  // two filters, by the rule the bundle uses to decide whose files to process
+  // (`localesToBuild`):
+  // - Publish: build outputs are visitor artifacts. With an explicit
+  //   `publishLanguages:`, only listed locales get dist/{locale}/ content,
+  //   per-locale HTML, hreflang, and translated collections. Draft locales
+  //   stay previewable in dev, which doesn't run this path. Intersecting the
+  //   DISK-resolved list also covers wildcard (`languages: '*'`) sites.
+  // - ⛔ The default locale is the root tree, not `dist/<default>/`. An explicit
+  //   `languages: [en, fr]` resolves verbatim — default included — so the DECLARED
+  //   form (the one the contract tells authors to use) minted a duplicate copy of
+  //   every page, while the wildcard form did not. Dropping it keeps content,
+  //   per-locale HTML and translated records agreeing on one set.
+  const { localesToBuild } = await import('@uniweb/build/i18n')
+  const { locales, skipped, defaultLocale } = localesToBuild(config, localesPath)
+  if (skipped.length > 0) {
+    info(`Skipping non-publishable locale(s): ${skipped.join(', ')} (not in publishLanguages)`)
   }
 
-  // ⛔ The default locale is the root tree, not `dist/<default>/`. An explicit
-  // `languages: [en, fr]` resolves verbatim — default included — so the DECLARED
-  // form (the one the contract tells authors to use) minted a duplicate copy of
-  // every page, while the wildcard form did not. Dropping it here keeps content,
-  // per-locale HTML and translated records agreeing on one set.
-  const defaultLocale = resolveDefaultLocale(config)
-  locales = locales.filter((l) => l !== defaultLocale)
-
   if (locales.length === 0) return null
 
   return {

package/src/commands/doctor.js

@@ -1112,9 +1112,16 @@ const DESCRIPTION_SHOWN = 160
 /** A path into the site's own files (`/images/card.jpg`), not an address of its own. */
 const isSitePath = (v) => typeof v === 'string' && v.startsWith('/') && !v.startsWith('//')
 
-/** `/x` → the file under the site's public/ or assets/ that serves it, or null when there is none. */
+/** `/x` → the file under the site's public/ that serves it, or null when there is none. */
 function siteFile(sitePath, ref) {
-  const { resolved } = resolveAssetPath(ref, join(sitePath, 'site.yml'), sitePath)
+  let resolved
+  try {
+    ;({ resolved } = resolveAssetPath(ref, join(sitePath, 'site.yml'), sitePath))
+  } catch (err) {
+    // A file in assets/, which no longer serves a `/x` — the build says how to move it.
+    if (err?.code === 'ASSETS_FOLDER_RETIRED') return null
+    throw err
+  }
   return resolved && existsSync(resolved) ? resolved : null
 }
 
@@ -1195,8 +1202,8 @@ export async function checkLinkPreviews({ sitePath, siteName, issues }) {
     const file = siteFile(sitePath, image)
     if (!file) {
       const id = 'share-image-missing'
-      issues.push({ id, type: 'warn', site: siteName, message: `${image}, the image a link to ${shownOn} shows, is not in public/ or assets/` })
-      warn(`[${id}] ${image} is not in public/ or assets/ — a link to ${shownOn} shows no image`)
+      issues.push({ id, type: 'warn', site: siteName, message: `${image}, the image a link to ${shownOn} shows, is not in public/` })
+      warn(`[${id}] ${image} is not in public/ — a link to ${shownOn} shows no image`)
       continue
     }
     readImageSize ??= (await import('@uniweb/build/images')).readImageSize
@@ -1276,8 +1283,8 @@ export async function checkFavicon({ sitePath, siteName, siteYml, issues, should
   if (named) {
     if (!isSitePath(named) || siteFile(sitePath, named)) return
     const id = 'favicon-missing'
-    issues.push({ id, type: 'warn', site: siteName, message: `favicon: ${named} is not in public/ or assets/` })
-    warn(`[${id}] favicon: ${named} is not in public/ or assets/ — every page links an icon that is not there`)
+    issues.push({ id, type: 'warn', site: siteName, message: `favicon: ${named} is not in public/` })
+    warn(`[${id}] favicon: ${named} is not in public/ — every page links an icon that is not there`)
     return
   }
 
@@ -1359,8 +1366,8 @@ export async function checkTouchIcon({ sitePath, siteName, siteYml, issues, shou
   const file = siteFile(sitePath, named)
   if (!file) {
     const id = 'touch-icon-missing'
-    issues.push({ id, type: 'warn', site: siteName, message: `touchIcon: ${named} is not in public/ or assets/` })
-    warn(`[${id}] touchIcon: ${named} is not in public/ or assets/ — every page links an icon that is not there`)
+    issues.push({ id, type: 'warn', site: siteName, message: `touchIcon: ${named} is not in public/` })
+    warn(`[${id}] touchIcon: ${named} is not in public/ — every page links an icon that is not there`)
     return
   }
   const { readImageSize, isImageOpaque } = await import('@uniweb/build/images')

package/src/commands/publish.js

@@ -110,7 +110,6 @@ import {
   unsettledFiles,
   commitWriteBacks,
   reportWriteBacks,
-  dropSiteBoundValues,
   pushSyncPackages,
   readSiteWorkspace
 } from '../backend/site-sync.js'
@@ -672,12 +671,6 @@ export async function publish(args = []) {
       `Cleared stale sync state from a previous site (${droppedState.join(', ')}).`
     )
   }
-  const droppedValues = dropSiteBoundValues(siteDir, client.origin)
-  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.
   //
   //     Uploaded bytes are metered against an owning entity and reclaimed by

package/src/commands/push.js

@@ -26,7 +26,8 @@
  * `uniweb login && uniweb push`. Run from a site, or a workspace with one site.
  *
  * Usage:
- *   uniweb push                          Build, push both lanes, back-fill $uuid
+ *   uniweb push                          Bring the foundation along, push both lanes,
+ *                                        back-fill $uuid
  *   uniweb push --org @org               Work in @org for this push, instead of the
  *   uniweb push --personal               workspace chosen at `uniweb login` (or your
  *                                        personal workspace). A site this push creates
@@ -97,7 +98,6 @@ import {
   refuseUnsendableRecords,
   ensureSiteExists,
   clearRemoteSyncStateIfUnbound,
-  dropSiteBoundValues,
   untakenBase,
   unsettledFiles,
   commitWriteBacks,
@@ -367,10 +367,6 @@ export async function push(args = [], deps = {}) {
         `Cleared stale sync state from a previous site (${dropped.join(', ')}).`
       )
     }
-    const stale = dropSiteBoundValues(siteDir, client.origin)
-    if (stale.length) {
-      note(`Dropped the previous site's ${stale.join(' and ')} from site.yml.`)
-    }
   }
   const priorHashes = readSyncCache(siteDir, client.origin)
   // Per-item identity, without which the backend reads every record as new and

package/src/commands/snapshot.js

@@ -23,8 +23,9 @@
  * A site keeps its chosen look in `site/snapshot.yml` (utils/snapshot-settings.js):
  * the command's defaults for that site, which flags override and `--save` writes.
  *
- * `preview:` is written only when site.yml has none, or holds the app's generated
- * token. An address the author wrote is never replaced.
+ * `preview:` is written only when site.yml has none, or holds something that is no
+ * author's address — the token an older pull wrote there for a card image the app
+ * generated. An address the author wrote is never replaced.
  */
 
 import { spawn } from 'node:child_process'
@@ -33,13 +34,12 @@ import { createRequire } from 'node:module'
 import { isAbsolute, join, relative, resolve, sep } from 'node:path'
 import { pathToFileURL } from 'node:url'
 import yaml from 'js-yaml'
-import { writeSiteConfig } from '@uniweb/build/uwx'
+import { isAuthoredPreview, writeSiteConfig } from '@uniweb/build/uwx'
 
 import { didYouMean } from '../utils/args.js'
 import { humanBytes } from '../utils/bytes.js'
 import { discoverSites } from '../utils/discover.js'
 import { detectWorkspacePm } from '../utils/pm.js'
-import { isAuthoredPreview } from '../utils/preview.js'
 import {
   SETTINGS_FILE,
   SettingsError,
@@ -447,7 +447,7 @@ export async function snapshot(args = []) {
       if (setPreview()) console.log(`  site.yml: ${CYAN}preview: ${value}${RESET}`)
       break
     case 'replace':
-      if (setPreview()) console.log(`  site.yml: ${CYAN}preview: ${value}${RESET} ${DIM}(replaces the app-generated preview)${RESET}`)
+      if (setPreview()) console.log(`  site.yml: ${CYAN}preview: ${value}${RESET} ${DIM}(replaces ${current}, which is not an image address)${RESET}`)
       break
     case 'unchanged':
       console.log(`  ${DIM}site.yml already has preview: ${value}${RESET}`)

package/src/framework-index.json

@@ -1,12 +1,12 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-10-28T14:10:12.997Z",
+  "generatedAt": "2026-10-29T02:26:03.448Z",
   "packages": {
     "@uniweb/api": {
-      "version": "1.6.4"
+      "version": "1.6.5"
     },
     "@uniweb/build": {
-      "version": "1.10.14"
+      "version": "1.11.1"
     },
     "@uniweb/content-reader": {
       "version": "1.5.7"
@@ -36,7 +36,7 @@
       "version": "1.2.7"
     },
     "@uniweb/runtime": {
-      "version": "1.2.12"
+      "version": "1.2.13"
     },
     "@uniweb/scene": {
       "version": "1.0.1"
@@ -60,7 +60,7 @@
       "version": "1.2.1"
     },
     "@uniweb/unipress": {
-      "version": "1.1.16"
+      "version": "1.1.17"
     }
   },
   "templates": {

package/src/index.js

@@ -1607,8 +1607,8 @@ ${colors.bright}Usage:${colors.reset}
 
 Opens the site in a headless Chrome, captures it, and composes the captures into
 one image: by default ${colors.bright}site/public/preview.webp${colors.reset}, recorded as ${colors.cyan}preview:${colors.reset} in site.yml
-when site.yml has none, or only the app's generated one. A URL or image path you
-wrote is never replaced.
+when site.yml has none, or what it has is not an image address. A URL or image path
+you wrote is never replaced.
 
 A page that scrolls gets the ${colors.bright}split${colors.reset} layout: the first view in a browser window,
 beside a long strip of the page. A page that does not scroll as a page (a docs

package/src/utils/preview.js

@@ -1,20 +0,0 @@
-/**
- * `site.yml::preview` — the site's card image — has two writers: an author, who
- * writes an address (a URL, or a path to an image in the project), and the app,
- * which writes a token naming an image it generated. This is the one test that
- * tells them apart.
- *
- * It recognizes the author's shapes rather than the app's, so it does not depend
- * on the token's format: a URL, a path starting `/`, `./` or `../`, or a relative
- * path to an image file (`images/card.png`).
- */
-
-const IMAGE_FILE = /\.(avif|gif|jpe?g|png|svg|webp)$/i
-
-/**
- * @param {unknown} value
- * @returns {boolean} true when `value` is an author's address rather than the app's token
- */
-export const isAuthoredPreview = (value) =>
-  typeof value === 'string' &&
-  (/^https?:\/\//i.test(value) || /^\.{0,2}\//.test(value) || IMAGE_FILE.test(value.trim()))