@uniweb/build 0.24.2 → 0.24.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.24.2",
+  "version": "0.24.4",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -59,17 +59,17 @@
     "js-yaml": "^4.1.0",
     "sharp": "^0.35.3",
     "yaml": "^2.5.0",
-    "@uniweb/projections": "^0.3.3",
-    "@uniweb/semantic-parser": "^1.2.3",
+    "@uniweb/content-writer": "^0.3.3",
     "@uniweb/schemas": "^0.2.10",
+    "@uniweb/semantic-parser": "^1.2.3",
     "@uniweb/theming": "^0.1.15",
-    "@uniweb/content-writer": "^0.3.3"
+    "@uniweb/projections": "^0.3.3"
   },
   "optionalDependencies": {
-    "@uniweb/content-reader": "^1.2.3",
     "@uniweb/runtime": "^0.12.2",
+    "@uniweb/schemas": "^0.2.10",
     "@uniweb/semantic-parser": "^1.2.3",
-    "@uniweb/schemas": "^0.2.10"
+    "@uniweb/content-reader": "^1.2.3"
   },
   "peerDependencies": {
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0",

package/src/site/build-site-data.js

@@ -126,8 +126,9 @@ export async function buildSiteData({
   //    in the vite plugin path that's fine because vite copies
   //    `public/` into `dist/` at build time. The link-mode pipeline
   //    has no vite, so we mirror that copy ourselves into
-  //    `<distDir>/data/` — the path `uniweb deploy::collectDataFiles`
-  //    walks at upload time. Same output bytes, same paths, just
+  //    `<distDir>/data/` — the set the CLI's `site-data-upload` lane walks at
+  //    publish time. (This named `uniweb deploy::collectDataFiles` until
+  //    2026-08-18; no such function has existed for some time.) Same output bytes, same paths, just
   //    without the vite intermediary.
   if (siteContent.config?.collections) {
     const collectionsBase = siteContent.config?.paths?.collections

package/src/site/index.js

@@ -42,7 +42,7 @@ export {
   writeCollectionFiles,
   getCollectionLastModified
 } from './collection-processor.js'
-export { assembleDataBall, collectBallAssets, rewriteBallAssets } from './data-ball.js'
+export { collectSchemalessData, collectSchemalessDataAssets, rewriteSchemalessDataAssets } from './schemaless-data.js'
 export {
   parseFetchConfig,
   executeFetch,

package/src/site/{data-ball.js → schemaless-data.js}

@@ -1,19 +1,39 @@
 /**
- * Data ball — the static-delivery half of a composite `uniweb deploy`. A site's
- * collections partition by schema presence: a collection that resolves a data schema
- * syncs as folder entities; a SCHEMA-LESS collection has no entity model, so its built
- * `dist/data/<name>.json` (cascade + any `deferred:` per-record files) is delivered
- * statically. This bundles that schema-less subset of `dist/data/**` into one JSON doc
- * the deploy uploads as a single content-addressed asset; the backend unwraps it into
- * the `/data/*` bytes the gateway serves.
+ * Schema-less collection data — the set, and its local media.
  *
- *   { data: { "<relpath-under-data>": <json> } }   // schema-less collections only
+ * ⭐ **The name carries the scope on purpose.** This is NOT "the site's static
+ * data" in general. A site's collections partition by **schema presence**: one
+ * that resolves a data schema syncs as folder entities — content a backend
+ * genuinely consumes, queryable, editable, with a `brief:` for its lean shape.
+ * A **schema-less** collection has no entity model, so its compiled
+ * `dist/data/<name>.json` (plus any `deferred:` per-record files) is delivered
+ * as files instead. That fallback tier is all this module is about.
  *
- * **A search index used to ride here too, and deliberately no longer does** (2026-08-01).
- * Only a CLI deploy produced one — a CMS publish produced none — so a site's search
- * existed or vanished depending on who published it, which is the flicker rule exactly.
- * A host that wants search derives it from the content it already stores. See the note
- * at the removal point below, and `collab/context/site-derived-artifacts.md`.
+ *   { data: { "<relpath under dist/data>": <json> } }   // schema-less only
+ *
+ * ⇒ It is an **in-memory enumeration**, not an artifact. `collectSchemalessData`
+ * gathers the set; the CLI's `site-data-upload` lane PUTs each file to the
+ * target the backend returns, landing at its serving tail.
+ *
+ * ## ⛔ It used to be a "data ball", and that is retired (2026-08-18)
+ *
+ * This merged the whole set into ONE uploaded asset that the backend then had
+ * to fetch, parse and fan out. It was the **only aggregate the CLI produced** —
+ * media, foundation code and the runtime all upload one object per file — and
+ * the only place these bytes ever transited the backend. Nothing in the code or
+ * the docs ever justified the bundling.
+ *
+ * ⇒ **Do not reintroduce a bundle here.** One object per file is what the
+ * reader's static arm already assumes: a plain object GET on the verbatim tail,
+ * with nothing anywhere that unbundles. Full account, including the endpoint
+ * contract: `kb/framework/build/data-ball-retirement.md`.
+ *
+ * **A search index used to ride here too, and deliberately no longer does**
+ * (2026-08-01). Only a CLI deploy produced one — a CMS publish produced none —
+ * so a site's search existed or vanished depending on who published it, which
+ * is the artifact-flicker rule exactly. A host that wants search derives it from
+ * the content it already stores. See the note at the removal point below and
+ * `collab/context/site-derived-artifacts.md`.
  */
 
 import { existsSync } from 'node:fs'
@@ -56,7 +76,7 @@ function collectionOf(relPath) {
  *        `emitSyncPackages(...).schemaless`); only these contribute `data`.
  * @returns {Promise<{ data: Object }|null>} null when there is nothing to deliver.
  */
-export async function assembleDataBall(distDir, schemalessNames = []) {
+export async function collectSchemalessData(distDir, schemalessNames = []) {
   const schemaless = new Set(schemalessNames)
   const allData = await readJsonTree(join(distDir, DATA_DIR))
   const data = {}
@@ -128,7 +148,7 @@ export async function assembleDataBall(distDir, schemalessNames = []) {
  * @param {{data:object}|null} ball
  * @returns {string[]} deduped refs to upload
  */
-export function collectBallAssets(ball) {
+export function collectSchemalessDataAssets(ball) {
   const refs = new Set()
   const walk = (n) => {
     if (typeof n === 'string') {
@@ -150,7 +170,7 @@ export function collectBallAssets(ball) {
  * @param {Record<string,string>} map - ref → serve URL
  * @returns {{data:object}|null} a new ball, or the input when there's nothing to do
  */
-export function rewriteBallAssets(ball, map) {
+export function rewriteSchemalessDataAssets(ball, map) {
   if (!ball || !map || Object.keys(map).length === 0) return ball
   const walk = (n) => {
     if (typeof n === 'string') return map[n] || n

package/src/uwx/sync-package.js

@@ -237,11 +237,16 @@ function rewriteEntityAssets(node, map, ids) {
  *   siteContent: { buffer, entityCount, index, models }|null,
  *   collections: { buffer, entityCount, index, models }|null,
  *   hashes: Object<string,string>, warnings: string[], skipped: number,
- *   schemaless: Array<{name: string, model: string}>, localAssets: string[] }>}
+ *   schemaless: Array<{name: string, model: string}>, localAssets: string[],
+ *   applied: object }>}
  *   `schemaless` lists collections that resolved no data schema (soft-skipped from
  *   the sync) — the composite deploy delivers these statically via the data ball.
  *   `localAssets` lists the site-root local media refs (`/images/x.png`) the deploy
  *   must upload + rewrite to serve URLs; co-located refs are warned and skipped.
+ *   `applied` echoes the hash-affecting injections this emit actually used
+ *   (`assetRewrite` / `assetIds` / `injectInfo` / `injectExtensions`), ready to be
+ *   passed straight back as opts. A caller that banks the `hashes` must bank this
+ *   beside them, or an offline re-emit cannot reproduce the document they describe.
  *   Each lane is null when it has nothing to push. The collections `index` keeps a
  *   leading `{ kind: 'folder' }` placeholder (submission position 0 → the folder
  *   entity) so record back-fill stays positionally aligned; the folder itself has no
@@ -275,8 +280,10 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
   // stamped here — NOT authored in site.yml, so they ride the wire but never project
   // back on pull (the `info.assets` precedent). They are part of the hashed content,
   // so a changed bundle URL correctly re-fires the site-content lane.
-  if (siteDoc && opts.injectInfo && typeof opts.injectInfo === 'object') {
-    siteDoc.info = { ...siteDoc.info, ...opts.injectInfo }
+  const injectInfo =
+    opts.injectInfo && typeof opts.injectInfo === 'object' ? opts.injectInfo : null
+  if (siteDoc && injectInfo) {
+    siteDoc.info = { ...siteDoc.info, ...injectInfo }
   }
   // Same idea one level out: `extensions` is a sibling of `info`, not a field in
   // it, so a pinned extension ref cannot ride `injectInfo`. `publish` releases a
@@ -285,9 +292,13 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
   // for the same reason: delivery is version-pinned, so an unpinned local name on
   // the wire points at code the host cannot serve. Keyed by `$id` (the authored
   // declaration), so entries the publish didn't touch are left verbatim.
-  if (siteDoc && opts.injectExtensions && Array.isArray(siteDoc.extensions)) {
+  const injectExtensions =
+    opts.injectExtensions && typeof opts.injectExtensions === 'object'
+      ? opts.injectExtensions
+      : null
+  if (siteDoc && injectExtensions && Array.isArray(siteDoc.extensions)) {
     siteDoc.extensions = siteDoc.extensions.map((e) => {
-      const pinned = opts.injectExtensions[e?.$id]
+      const pinned = injectExtensions[e?.$id]
       if (!pinned) return e
       const { url: _dropped, ...rest } = e
       return { ...rest, ref: pinned }
@@ -402,9 +413,33 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
   // the content lane by its presence/absence.
   const siteContentUuid = siteDoc?.$uuid
 
+  // ⛔ EVERY INJECTION ABOVE IS PART OF THE HASHED DOCUMENT — so a reader that
+  // cannot reproduce them cannot compare against the hashes a push banked.
+  //
+  // `uniweb status` is exactly such a reader: it re-emits OFFLINE, and both an asset
+  // serve URL and a pinned foundation ref are things only a backend round-trip can
+  // produce. Left implicit, it reports every entity as changed FOREVER — measured
+  // 2026-08-19 on a site with one `/images/*.svg` reference, where push banked the
+  // rewritten hash, status re-hashed the authored one, and `changed` never dropped
+  // below 1 no matter how many times you pushed. `push.js` had already written the
+  // rule down for its own two emits ("or every entity reads as changed forever") and
+  // the third reader of the same cache never got it.
+  //
+  // ⭐ So the EMITTER reports what it applied, the pusher banks it beside the hashes,
+  // and the offline reader replays it. Reporting it here rather than having each
+  // caller remember to pass its own injections along is the whole point: what gets
+  // banked is then, by construction, what was hashed. A future injection is covered
+  // by adding one line here — not by finding every reader.
+  const applied = {
+    ...(assetRewrite ? { assetRewrite } : {}),
+    ...(assetIds ? { assetIds } : {}),
+    ...(injectInfo ? { injectInfo } : {}),
+    ...(injectExtensions ? { injectExtensions } : {})
+  }
+
   return {
     siteContent, collections, siteContentUuid, hashes, warnings, skipped,
-    schemaless: col.schemaless, localAssets,
+    schemaless: col.schemaless, localAssets, applied,
     // { stamped, unknown } when identity was applied; null when the caller passed
     // no map. `unknown > 0` with `stamped === 0` on a site that has been pushed
     // before is the index-loss signature the backend refuses — the caller reports it.