@uniweb/build 0.25.2 → 0.25.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.25.2",
+  "version": "0.25.3",
   "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.4",
-    "@uniweb/schemas": "^0.2.10",
-    "@uniweb/theming": "^0.1.15",
     "@uniweb/semantic-parser": "^1.3.0",
-    "@uniweb/content-writer": "^0.3.4"
+    "@uniweb/theming": "^0.1.15",
+    "@uniweb/content-writer": "^0.3.4",
+    "@uniweb/projections": "^0.3.4",
+    "@uniweb/schemas": "^0.2.10"
   },
   "optionalDependencies": {
-    "@uniweb/schemas": "^0.2.10",
+    "@uniweb/semantic-parser": "^1.3.0",
     "@uniweb/content-reader": "^1.2.4",
-    "@uniweb/runtime": "^0.12.9",
-    "@uniweb/semantic-parser": "^1.3.0"
+    "@uniweb/schemas": "^0.2.10",
+    "@uniweb/runtime": "^0.12.9"
   },
   "peerDependencies": {
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0",
@@ -78,7 +78,7 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
     "vite-plugin-svgr": "^4.0.0",
-    "@uniweb/core": "^0.11.2"
+    "@uniweb/core": "^0.11.3"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/uwx/index.js

@@ -44,6 +44,7 @@ export {
   emitSiteSyncPackage,
   writeSiteEntityUuid,
   writeSiteOrg,
+  writeSiteBackend,
   extensionDeclaration,
   isExtensionUrl,
   isSiteRelativeExtensionUrl,

package/src/uwx/site.js

@@ -947,3 +947,42 @@ export function writeSiteEntityUuid(siteRoot, uuid) {
 export function writeSiteOrg(siteRoot, handle) {
   return upsertYamlScalar(join(siteRoot, 'site.yml'), '$org', handle)
 }
+
+/**
+ * Record the backend this project SYNCS WITH (`site.yml::$backend`), beside `$uuid`/`$org`.
+ *
+ * ⭐ It is not a tag on the site uuid — it is the project's **sync scope**. Four surfaces
+ * hold backend-minted identity, and this one fact is what makes all of them meaningful:
+ * `site.yml::$uuid`, every collection record's `$uuid` in its own source file,
+ * `assets.json`, and `.uniweb/sync-cache.json`. Change the backend and every one of them
+ * is foreign at once — which is why a mismatch is a stop, not a fallback
+ * (`assertSiteBackendScope` in the CLI).
+ *
+ * ⛔ **Written ONLY for a non-default backend.** The 98% case stays out of the file, and an
+ * absent value reads as the default — correct both for a project written before this key
+ * existed and for one synced against the default. Callers decide; this writer does not know
+ * the CLI's default. See `recordSiteBackend` (cli/src/backend/site-sync.js), which is where
+ * the "is it the default?" test lives.
+ *
+ * ⚠️ **The name is load-bearing. Five alternatives were considered and rejected (2026-08-24);
+ * do not re-propose one.** `origin` is wrong twice over — a site HAS an origin (its own
+ * served domain), and this lane is git-modeled, where `origin` names a remote rather than a
+ * URL. `remote` implies a multiplicity this design closes. `hosting` and `platform` name the
+ * hosting edge, which this package has no client for. `host` collides with
+ * `deploy.yml::targets.<n>.host` (the deploy adapter). A `uuid: <id>@<backend>` suffix was
+ * rejected too: it would make "this never reaches the backend" a discipline at every read
+ * site instead of a property, and `siteProjectToDocument` assigns `$uuid` straight onto the
+ * wire document.
+ *
+ * Safe as a plain YAML scalar: a URL's `:` is followed by `/` or a digit, never a space, so
+ * it needs no quoting (verified against js-yaml for apex, `localhost:8080` and host:port+path
+ * forms, 2026-08-24). This is the same class of hazard as `$org`'s leading `@`, which is
+ * stripped for exactly that reason — but it lands on the safe side.
+ *
+ * @param {string} siteRoot
+ * @param {string} origin - a bare origin, no trailing slash
+ * @returns {boolean} true if site.yml changed
+ */
+export function writeSiteBackend(siteRoot, origin) {
+  return upsertYamlScalar(join(siteRoot, 'site.yml'), '$backend', origin)
+}