uniweb 1.13.3 → 1.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "1.13.3",
+  "version": "1.14.0",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -41,13 +41,13 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
-    "@uniweb/core": "~1.3.0",
+    "@uniweb/content-writer": "~1.3.0",
+    "@uniweb/core": "~1.3.1",
     "@uniweb/semantic-parser": "~1.12.2",
-    "@uniweb/schemas": "~1.5.0",
-    "@uniweb/content-writer": "~1.3.0"
+    "@uniweb/schemas": "~1.5.0"
   },
   "peerDependencies": {
-    "@uniweb/build": "~1.5.2",
+    "@uniweb/build": "~1.6.0",
     "@uniweb/content-reader": "~1.5.4",
     "@uniweb/semantic-parser": "~1.12.2"
   },

package/src/backend/service-request.js

@@ -7,8 +7,7 @@
  *   - ⭐ **The services** — `site.yml::services`, a map by service name *[Diego,
  *     2026-10-06]*. A push STATES them — the file's, and off for each held one it no
  *     longer lists — and the backend decides per service from the versions sent
- *     (`statedServices`, `@uniweb/build/uwx`; spec:
- *     kb/framework/reference/site-services-request.md). All this module does for them
+ *     (`statedServices`, `@uniweb/build/uwx`). All this module does for them
  *     is say what the file asks that will not be sent (`announceServices`).
  *   - **The language selection** — `site.yml::publishLanguages` — told apart from the
  *     status quo by a fingerprint banked in `deploy.yml` (`reconcile`, `bankLanguages`).

package/src/backend/site-sync.js

@@ -245,7 +245,7 @@ function writtenAsSent(sent, written) {
  * every item, not only units. The site-content entity sends every version this copy
  * holds, for items present and items the files dropped (`withBaseVersion`), and the
  * backend deletes only the items a push holds a version for, while the site left them
- * unchanged [Diego: "yes, apply it to pages too"; kb/framework/plans/services-exchange.md].
+ * unchanged [Diego: "yes, apply it to pages too"].
  * A version banked for an item this copy never saw would therefore delete it. The map
  * returned is the WHOLE set this copy now holds, in every Section but `secrets`
  * (`siteItemsByKey`), and it replaces the one held before:
@@ -510,8 +510,6 @@ export function keepModels(siteDir, backend, models) {
 // ⛔ **Keyed by backend ORIGIN.** Every map describes ONE backend: hashes are what we
 // last sent *to it*, base versions are the versions *it* had. Shared across backends
 // they report every entity as changed against the second one.
-//
-// Spec: kb/framework/reference/backend-cache-json.md
 function backendCachePath(siteDir) {
   return join(siteDir, '.uniweb', 'backend-cache.json')
 }
@@ -2100,8 +2098,7 @@ export async function rebankRecordHashes(siteDir, backend, keys) {
  * reply, never inferred from what we sent.
  *
  * The field is `template`, carrying `designated` or `undesignated`, and it is ABSENT
- * when the designation did not move (backend, collab framework↔backend #6, 2026-09-23;
- * kb/framework/reference/template-designation-on-push.md E6).
+ * when the designation did not move (backend, 2026-09-23).
  *
  * ⛔ TWO STATES, NOT THREE — and silence means "unchanged", never "failed". A push that
  * asks to designate where the backend will not is REFUSED WHOLE, and that refusal

package/src/commands/build.js

@@ -13,17 +13,24 @@
  *     Full vite + post-vite pipeline. Produces a static-host JS bundle
  *     (`dist/index.html`, `dist/entry.js`, `_importmap/*`, `_pages/*` for
  *     split mode, sitemap/robots/search-index, prerendered HTML when
- *     configured). Foundation is loaded by URL when site.yml's foundation
- *     is a registry ref; statically inlined when it's a workspace-local
- *     ref (the self-contained case).
+ *     configured). The foundation is statically inlined when site.yml names a
+ *     workspace-local one (the self-contained case), and loaded by URL when
+ *     it names a URL, or under VITE_FOUNDATION_MODE=runtime. A catalog ref
+ *     (`@org/name@version`) is refused (`detectFoundationType`).
  *
  *   --link (internal; called by `uniweb publish`)
- *     Data-only pipeline. No vite. Emits ONLY what Uniweb hosting
- *     needs: `dist/site-content.json` (with full sections),
- *     `dist/<lang>/site-content.json` per non-default locale,
- *     `dist/data/*.json` (collections), and `dist/assets/<media>` (images,
- *     fonts, video posters). The backend stitches runtime + foundation per
- *     request — the site's JS bundle would be dead weight.
+ *     Data-only pipeline. No vite, and no media processing. Emits
+ *     `dist/site-content.json` (with full sections),
+ *     `dist/<lang>/site-content.json` per non-default locale and
+ *     `dist/data/*.json` (queries). `publish` reads two things back — the
+ *     files of the queries that have no data schema, and the languages to
+ *     make live — sends the content over the sync wire, from source, and
+ *     uploads media from the site's own files. What it sends carries no JS,
+ *     so a bundle would be dead weight.
+ *
+ *     ⛔ *Until 2026-10-19 this said a registry ref was loaded by URL, that
+ *     --link emitted "ONLY what Uniweb hosting needs", and that "the backend
+ *     stitches runtime + foundation per request".*
  *
  * Bare `uniweb build` for a site defaults to --bundle (the historical
  * behavior). This is mostly useful for inspecting the build output during
@@ -565,32 +572,36 @@ function resolveFoundationDir(projectDir, siteConfig) {
 }
 
 /**
- * Build a site in link mode — data only, no vite.
+ * Build a site in link mode — data only, no vite. `uniweb publish` runs it.
  *
- * Emits exactly what `uniweb publish` ships to Uniweb hosting:
+ * Emits:
  *   dist/site-content.json (full sections inlined)
  *   dist/<lang>/site-content.json per non-default locale
  *   dist/data/<query>.json (+ a file per record, dist/data/<query>/<name>.json)
- *   dist/assets/<media> (processed images, video posters, PDF thumbnails)
  *
- * Does NOT emit HTML, JS, CSS, source maps, _importmap chunks, or
- * static-host extras (sitemap, robots, search-index, _pages/*) — none
- * of these are consumed on the link-mode deploy path. The worker
- * generates HTML at request time and re-derives split-content per-page
- * files from the full payload it receives.
+ * `publish` reads two things back: the files of the queries that have no data
+ * schema, which it uploads, and the languages to make live. The content goes
+ * over the sync wire, read from source, and the site's media is uploaded from
+ * the site's own files.
+ *
+ * Does NOT emit HTML, JS, CSS, source maps, _importmap chunks, processed media
+ * (dist/assets/), or static-host extras (sitemap, robots, search-index,
+ * _pages/*) — `publish` reads none of them. ⛔ *It processed media into
+ * dist/assets/ — WebP copies, video posters, PDF thumbnails — until 2026-10-19.*
  *
  * The `buildLocalizedContent` step is the same call bundle mode makes
  * post-vite, so multi-locale sites get identical per-locale outputs in
- * either mode. Collection translation (`buildLocalizedRecords`)
- * also runs here so deploy ships translated collection JSONs.
+ * either mode. Record translation (`buildLocalizedRecords`) also runs here,
+ * writing each locale's query files to dist/<lang>/data/.
+ *
+ * History: when `deploy` uploaded `dist/site-content.json` to a backend, it
+ * read the bundle pipeline's copy, which prerender rewrites into a lightweight
+ * manifest (sections stripped) when split-content is active — and the host
+ * that received it mis-detected split and served blank pages. Routing deploy
+ * through this path, which skips prerender and keeps full sections, fixed it.
  *
- * Bug surfaced + fixed by routing deploy through this path: the bundle
- * pipeline's prerender step rewrites `dist/site-content.json` into a
- * lightweight manifest (sections stripped) when split-content is active,
- * and deploy was reading that stripped version, causing the worker to
- * mis-detect split and serve blank pages. Link mode skips prerender
- * entirely; `dist/site-content.json` keeps full sections; the worker
- * splits correctly.
+ * ⛔ *Until 2026-10-19 this said it emitted "exactly what `uniweb publish`
+ * ships to Uniweb hosting", and described what the worker does with it.*
  */
 async function buildSiteLink(projectDir, options = {}) {
   const { siteConfig = null } = options
@@ -600,30 +611,29 @@ async function buildSiteLink(projectDir, options = {}) {
   const { buildSiteData } = await import('@uniweb/build/site')
   const distDir = join(projectDir, 'dist')
 
-  // Resolve the local foundation path so collectSiteContent can pick up
-  // theme variable defaults from `foundation.js::theme.vars`. When the
-  // foundation is purely a registry ref (no local sibling), this stays
+  // Resolve the local foundation path so collectSiteContent can pick up the
+  // defaults of the theme variables it declares (its `main.js` `vars`). When
+  // the foundation is purely a registry ref (no local sibling), this stays
   // null and theme defaults come from theme.yml only.
   const foundationDir = resolveFoundationDir(projectDir, siteConfig)
 
   // Link mode does NOT (re)build the foundation. It reads only the
-  // foundation's SOURCE config (foundation.js::theme.vars, passed as
-  // foundationPath below) for theme defaults, and ships NO foundation code —
-  // the backend serves the foundation from the registry by the `foundation:`
-  // ref. (Bundle mode is the one that needs a current dist/entry.js — see
-  // buildSite — so the ensureFoundationFresh cascade lives there, not here.)
+  // foundation's SOURCE declarations (passed as foundationPath below) for
+  // theme defaults, and ships NO foundation code — the site names its
+  // foundation by registered version. (Bundle mode is the one that needs a
+  // current dist/entry.js — see buildSite — so the ensureFoundationFresh
+  // cascade lives there, not here.)
 
   await buildSiteData({
     siteRoot: projectDir,
     distDir,
-    foundationPath: foundationDir,
-    assets: siteConfig?.build?.assets || {}
+    foundationPath: foundationDir
   })
   success(`Wrote ${join('dist', 'site-content.json')}`)
 
   // Per-locale variants — same call bundle mode makes post-vite. Both
-  // modes produce identical `dist/<lang>/site-content.json` outputs so
-  // the deploy CLI walks the same path shape regardless of mode.
+  // modes produce identical `dist/<lang>/site-content.json` outputs, and
+  // `publish` reads which languages were built from them.
   const i18nConfig = await loadI18nConfig(projectDir, siteConfig)
   if (i18nConfig && i18nConfig.locales.length > 0) {
     log('')
@@ -1092,12 +1102,10 @@ export async function build(args = []) {
       // For sites, read config to determine prerender default
       const siteConfig = readSiteConfig(projectDir)
 
-      // Link mode: data-only pipeline, no vite. The deployed Uniweb-edge
-      // site never consumes the JS bundle, so we skip producing it.
-      // Worker generates HTML at request time using its own runtime +
-      // the foundation served from the registry. See
-      // `framework/build/src/site/build-site-data.js` for what gets
-      // emitted (and what doesn't).
+      // Link mode: data-only pipeline, no vite — what `publish` sends a
+      // backend carries no JS, so no bundle is built. See `buildSiteLink`
+      // above, and `@uniweb/build`'s `src/site/build-site-data.js`, for what
+      // is emitted (and what isn't).
       if (linkFlag) {
         if (prerenderFlag) {
           error(

package/src/commands/doctor.js

@@ -89,7 +89,7 @@ function isFoundation(dir) {
  * ⛔ THE PATH IS `dist/meta/schema.json`, and it read `dist/schema.json` from
  * 2026-02-06 until 2026-09-15 — a file the build has never written. So this
  * returned `null` every time, and its one caller (the extension `vars`/layouts
- * warning, which `framework/CLAUDE.md` gotcha #18 says doctor performs) could
+ * warning) could
  * not fire at all.
  *
  * ⭐ THE CLASS IS WORTH MORE THAN THE BUG: a wrong PATH returns empty, it does

package/src/framework-index.json

@@ -1,12 +1,12 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-10-19T18:20:17.536Z",
+  "generatedAt": "2026-10-19T19:27:42.981Z",
   "packages": {
     "@uniweb/api": {
-      "version": "1.6.0"
+      "version": "1.6.1"
     },
     "@uniweb/build": {
-      "version": "1.5.2"
+      "version": "1.6.0"
     },
     "@uniweb/content-reader": {
       "version": "1.5.4"
@@ -15,7 +15,7 @@
       "version": "1.3.0"
     },
     "@uniweb/core": {
-      "version": "1.3.0"
+      "version": "1.3.1"
     },
     "@uniweb/frame-bridge": {
       "version": "1.0.2"
@@ -24,19 +24,19 @@
       "version": "1.0.4"
     },
     "@uniweb/kit": {
-      "version": "1.5.1"
+      "version": "1.5.2"
     },
     "@uniweb/loom": {
       "version": "1.1.0"
     },
     "@uniweb/press": {
-      "version": "1.1.2"
+      "version": "1.1.3"
     },
     "@uniweb/projections": {
       "version": "1.1.4"
     },
     "@uniweb/runtime": {
-      "version": "1.1.10"
+      "version": "1.1.11"
     },
     "@uniweb/scene": {
       "version": "1.0.1"
@@ -60,7 +60,7 @@
       "version": "1.2.0"
     },
     "@uniweb/unipress": {
-      "version": "1.1.9"
+      "version": "1.1.10"
     }
   },
   "templates": {

package/src/utils/dep-survey.js

@@ -37,7 +37,7 @@ export function stripVersionRange(spec) {
  * How far a bump moves, in the terms our versioning actually uses.
  *
  * ⭐ **The MINOR slot is the breaking one — in 1.x as in 0.x** *[ruled
- * 2026-10-11]*. `scripts/framework/publish.js` derives a package's bump from its own
+ * 2026-10-11]*. The framework's release derives a package's bump from its own
  * commits: a breaking marker means minor, everything else patch. So
  * `^0.14.1 → ^0.16.0` is two breaking releases and `^0.15.0 → ^0.15.2` is not —
  * and until 2026-09-02 `update` printed both as `behind`, in the same colour,

package/src/utils/json-file.js

@@ -5,9 +5,8 @@
  * `rename`, `add`). A naive `JSON.stringify(obj, null, 2)` reflows the
  * *entire* file whenever the project happened to use tabs or 4-space
  * indentation — turning a one-key version bump into a hundred-line diff
- * (and a needless merge-conflict surface). `framework/CLAUDE.md` calls
- * this out as an anti-pattern for human commits; the tooling shouldn't do
- * it either. These helpers detect the file's existing indentation and
+ * (and a needless merge-conflict surface). That is an anti-pattern in a
+ * human commit, and the tooling shouldn't do it either. These helpers detect the file's existing indentation and
  * trailing-newline convention and preserve both.
  */
 

package/src/utils/site-identity.js

@@ -4,8 +4,6 @@
  * ⭐ **`site.yml` holds nothing a backend minted, as of 2026-09-20.** It carried
  * `$uuid`, `$org` and `$backend`; all three moved to
  * `sync.json::backends.<origin>.site`, keyed by the backend that minted them.
- * Spec: `kb/framework/reference/sync-json.md`. Why:
- * `kb/framework/plans/backend-scoped-project-state.md`.
  *
  * ## ⛔ What is GONE, and why nothing replaces it
  *