@uniweb/build 0.44.2 → 0.44.4

package/README.md

@@ -324,11 +324,15 @@ After building, your foundation will contain:
 
 ```
 dist/
-├── foundation.js      # Bundled components (~6KB typical)
-├── foundation.js.map  # Source map
+├── entry.js           # The foundation — section types, layouts, declarations
+├── entry.js.map       # Source map
+├── entry-ssr.js       # Single-file twin of entry.js, for server-side prerender
+├── runtime-pin.json   # The @uniweb/runtime version it was built against
+├── *.js               # Code-split chunks, when the foundation has any
+├── assets/            # Styles and static assets
 └── meta/              # Editor metadata (not needed at runtime)
     ├── schema.json    # Full component metadata for editors
-    └── previews/      # Preset preview images
+    └── previews/      # Preset preview images, when presets declare them
         └── Hero/
             └── default.webp
 ```
@@ -357,9 +361,9 @@ The `_self` object contains foundation-level metadata:
 | `name` | `package.json` | Foundation package name |
 | `version` | `package.json` | Foundation version |
 | `description` | `package.json` | Foundation description |
-| `vars` | `foundation.js` | CSS custom properties sites can override |
+| `vars` | `main.js` | CSS custom properties sites can override |
 
-Identity fields (`name`, `version`, `description`) come from the foundation's `package.json`. Configuration fields (`vars`, etc.) come from `src/foundation.js`.
+Identity fields (`name`, `version`, `description`) come from the foundation's `package.json`. Configuration fields (`vars`, etc.) come from the foundation's `main.js`.
 
 ## API Reference
 
@@ -370,7 +374,7 @@ Identity fields (`name`, `version`, `description`) come from the foundation's `p
 | `discoverComponents(srcDir)` | Discover all section types (folders with meta.js) |
 | `loadComponentMeta(componentDir)` | Load meta file for a component |
 | `loadPackageJson(srcDir)` | Load identity from package.json |
-| `loadFoundationConfig(srcDir)` | Load foundation.js configuration |
+| `loadFoundationConfig(srcDir)` | Load the foundation's `main.js` declarations. A leftover `foundation.js` with no `main.js` beside it throws |
 | `buildSchema(srcDir)` | Build complete schema object |
 
 ### Entry Generation
@@ -387,7 +391,7 @@ The generated `_entry.generated.js` file exports:
 |--------|-------------|
 | `components` | Object map of component name → React component |
 | Named exports | Each component exported by name (e.g., `Hero`, `Features`) |
-| `capabilities` | Custom Layout and props from `src/foundation.js` (or `null`) |
+| `capabilities` | Custom Layout and props from `main.js` (or `null`) |
 | `meta` | Runtime metadata extracted from component `meta.js` files |
 
 #### Runtime Metadata (`meta` export)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.44.2",
+  "version": "0.44.4",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -57,15 +57,15 @@
     "js-yaml": "^4.1.0",
     "sharp": "^0.35.3",
     "yaml": "^2.5.0",
+    "@uniweb/content-writer": "^0.3.4",
     "@uniweb/projections": "^0.6.0",
+    "@uniweb/schemas": "^0.2.13",
     "@uniweb/semantic-parser": "^1.4.0",
     "@uniweb/theming": "^0.1.15",
-    "@uniweb/content-writer": "^0.3.4",
-    "@uniweb/schemas": "^0.2.13",
     "@uniweb/content-reader": "^1.2.4"
   },
   "optionalDependencies": {
-    "@uniweb/runtime": "^0.19.4"
+    "@uniweb/runtime": "^0.19.5"
   },
   "peerDependencies": {
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0",
@@ -74,7 +74,7 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
     "vite-plugin-svgr": "^4.0.0",
-    "@uniweb/core": "^0.24.3"
+    "@uniweb/core": "^0.24.4"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/schema.js

@@ -184,7 +184,11 @@ export async function loadPackageJson(srcDir) {
 }
 
 /**
- * Load foundation-level config file (main.js, fallback foundation.js)
+ * Load the foundation's declarations from `src/main.js`.
+ *
+ * ⛔ There is no `foundation.js` fallback — the legacy name was removed
+ * 2026-09-05. A leftover `foundation.js` with no `main.js` beside it is
+ * REFUSED rather than ignored; see `loadFoundationConfig`.
  *
  * Contains foundation-wide configuration:
  * - vars: CSS custom properties sites can override
@@ -340,7 +344,30 @@ export async function loadFoundationConfig(srcDir) {
       break
     }
   }
-  if (!filePath) return {}
+  if (!filePath) {
+    // ⛔ A LEFTOVER `foundation.js` IS NOT "NO CONFIG", AND MUST NOT READ AS ONE.
+    //
+    // The legacy name was removed 2026-09-05 (`FOUNDATION_FILE_NAMES` is
+    // `main.js` alone). This line used to return `{}` here regardless — so a
+    // project that kept the old name built "successfully" with every
+    // declaration silently gone: no `vars`, no `defaultLayout`, no
+    // `defaultSection`, no `props`. That is the exact outcome the guard below
+    // refuses on the import-failure path, reached through a door it did not
+    // cover. Found 2026-09-10 checking two downstream projects before an update;
+    // one would have lost its default layout and its output-format declarations.
+    //
+    // ⇒ Throw, like the guard below, rather than warn: a build log is where a
+    // warning goes to be missed, and the fix is a one-file rename.
+    const legacy = join(srcDir, 'foundation.js')
+    if (existsSync(legacy)) {
+      throw new Error(
+        `${legacy} is no longer read — rename it to main.js.\n` +
+          `  A foundation's declarations (vars, defaultLayout, defaultSection, props, name) live in\n` +
+          `  main.js. Left as foundation.js, the build would continue with none of them.`,
+      )
+    }
+    return {}
+  }
 
   let module
   try {

package/src/site/config.js

@@ -244,6 +244,7 @@ export async function defineSiteConfig(options = {}) {
         const agreement = checkFoundationResolution({
           name: foundationInfo.name,
           generatedInto: srcDir,
+          generatedEntry: entryPath,
           siteRoot,
         })
         if (!agreement.ok) console.warn(`\n${agreement.message}\n`)

package/src/site/content-collector.js

@@ -84,7 +84,7 @@ function warnRetiredFetcherKeys(fetcher) {
       `[uniweb] site.yml fetcher: ${retired.map((k) => `\`${k}\``).join(', ')} ` +
         `${retired.length === 1 ? 'is' : 'are'} retired and ignored. The default fetcher reads a ` +
         `site's own files and a host's records lane; a backend of your own is reached through a ` +
-        `foundation transport (docs: development/connecting-a-backend.md). Kept: ` +
+        `foundation transport (docs: development/data-sources.md). Kept: ` +
         `\`fetcher.transports\` and a transport's own binding config.`
     )
   }

package/src/utils/foundation-resolution-check.js

@@ -59,7 +59,7 @@
  * consulted. That is the step whose answer we need.
  */
 
-import { existsSync, realpathSync } from 'node:fs'
+import { existsSync, readFileSync, realpathSync } from 'node:fs'
 import { dirname, join, parse } from 'node:path'
 
 /**
@@ -85,6 +85,50 @@ export function findPackageDir(name, fromDir) {
   }
 }
 
+/**
+ * Does Vite's resolution of this package land on the very file we generated?
+ *
+ * ⭐ **This is the question the check exists to ask.** Comparing DIRECTORIES
+ * asked a different one and got it wrong for the most common layout there is: a
+ * package rooted at `foundations/<x>/`, its entry generated into
+ * `foundations/<x>/src/`, and `main` pointing there. That is two directories and
+ * ONE file. Measured 2026-09-10 against every site of a ten-site project: the
+ * directory check fired for six — five healthy `src/` layouts, and the single
+ * genuine case, a pnpm `file:` dependency copied into the store, buried among
+ * them. The entry comparison leaves exactly that one.
+ * A warning that fires on healthy projects is the failure this module's own
+ * header warns against.
+ *
+ * ⛔ **True only when the match is PROVEN** — both files exist and realpath to
+ * one place. Any failure to resolve returns false, so the caller reports the
+ * directory disagreement rather than silencing it: a copy with no entry, or one
+ * carrying a stale entry of its own, is still caught.
+ *
+ * Follows what Vite reads for a bare specifier: `exports['.']` (a string, or its
+ * `import`/`default` condition), else `main`, else `index.js`.
+ */
+function resolvesToSameEntry(generatedEntry, packageDir) {
+  let pkg
+  try {
+    pkg = JSON.parse(readFileSync(join(packageDir, 'package.json'), 'utf8'))
+  } catch {
+    return false
+  }
+  const pick = (v) =>
+    typeof v === 'string' ? v : v && typeof v === 'object' ? pick(v.import ?? v.default) : null
+  const exp = pkg.exports
+  let rel = null
+  if (typeof exp === 'string') rel = exp
+  else if (exp && typeof exp === 'object') rel = pick('.' in exp ? exp['.'] : exp)
+  rel ??= typeof pkg.main === 'string' ? pkg.main : null
+  rel ??= 'index.js'
+  try {
+    return realpathSync(generatedEntry) === realpathSync(join(packageDir, rel))
+  } catch {
+    return false
+  }
+}
+
 /**
  * Compare where we generated the foundation entry against where vite will look.
  *
@@ -100,9 +144,11 @@ export function findPackageDir(name, fromDir) {
  * @param {string} args.name - the foundation's declared name (the bare specifier)
  * @param {string} args.generatedInto - the directory we wrote `_entry.generated.js` to
  * @param {string} args.siteRoot - where vite resolves the bare specifier from
+ * @param {string} [args.generatedEntry] - the entry file we wrote; defaults to
+ *   `_entry.generated.js` inside `generatedInto`
  * @returns {{ ok: true } | { ok: false, ours: string, theirs: string, message: string }}
  */
-export function checkFoundationResolution({ name, generatedInto, siteRoot }) {
+export function checkFoundationResolution({ name, generatedInto, siteRoot, generatedEntry }) {
   const theirsRaw = findPackageDir(name, siteRoot)
   if (!theirsRaw) return { ok: true }
 
@@ -118,6 +164,13 @@ export function checkFoundationResolution({ name, generatedInto, siteRoot }) {
 
   if (ours === theirs) return { ok: true }
 
+  // Two directories are not two foundations. When the package Vite reaches
+  // resolves to the entry file we generated, the build reads what we wrote —
+  // the `src/` layout, where the entry sits one level below the package root.
+  if (resolvesToSameEntry(generatedEntry ?? join(generatedInto, '_entry.generated.js'), theirsRaw)) {
+    return { ok: true }
+  }
+
   return {
     ok: false,
     ours,

package/src/uwx/site.js

@@ -1212,16 +1212,18 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
   // a bug fix.
   //
   // ⭐ `api` is the one service a site does not AUTHOR. It is a real backend that is
-  // provisioned and paid for, so its address is the host's to supply — it arrives as
+  // provisioned, so its address is the host's to supply — it arrives as
   // `config.services.api` and `@uniweb/api` reads it there (`resolveBase`). An
-  // authored `api:` is the SITE tier, which outranks the host permanently.
+  // authored `api:` is the SITE tier: it yields to a host that offers the service,
+  // and is the answer wherever one does not.
   //
-  // ⇒ Carrying it would turn a local-dev override into a production one the moment
-  // someone pushed: the host would store `info.api` and serve it back as `config.api`,
-  // which wins over the address of the backend the site actually has. The vanish on
-  // this lane is the correct behaviour, not the bug the comments above describe —
-  // there, a dropped block leaves a site with NO endpoint; here it leaves the site
-  // with the RIGHT one.
+  // ⇒ Carrying it would turn a local-dev address into a production one the moment
+  // someone pushed: the host would store `settings.api` and serve it back as
+  // `config.api`, and a site with no `api` service of its own would draw sign-in
+  // against an address nobody answers — where the absence would have drawn
+  // nothing. The vanish on this lane is the correct behaviour, not the bug the
+  // comments above describe — there, a dropped block leaves a site with NO
+  // endpoint; here it leaves the site with the RIGHT answer.
   //
   // The provisioned record rides the `$services` section instead (see servicesNested).
   // ⭐ DESUGARED, like every other tier. `data:` is the shorthand for `fetch:`