@uniweb/build 0.26.0 → 0.27.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -59,15 +59,15 @@
     "js-yaml": "^4.1.0",
     "sharp": "^0.35.3",
     "yaml": "^2.5.0",
+    "@uniweb/schemas": "^0.2.11",
     "@uniweb/theming": "^0.1.15",
-    "@uniweb/schemas": "^0.2.10",
     "@uniweb/semantic-parser": "^1.3.1",
-    "@uniweb/projections": "^0.3.5",
+    "@uniweb/projections": "^0.3.7",
     "@uniweb/content-writer": "^0.3.4"
   },
   "optionalDependencies": {
-    "@uniweb/runtime": "^0.12.10",
-    "@uniweb/schemas": "^0.2.10",
+    "@uniweb/runtime": "^0.13.0",
+    "@uniweb/schemas": "^0.2.11",
     "@uniweb/semantic-parser": "^1.3.1",
     "@uniweb/content-reader": "^1.2.4"
   },
@@ -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.12.0"
+    "@uniweb/core": "^0.13.0"
   },
   "peerDependenciesMeta": {
     "vite": {

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

@@ -72,9 +72,16 @@ import {
  *   - `sitemap.xml`, `robots.txt` — static-host bundle territory. Note these
  *     are simply absent from Uniweb-hosted sites today: nothing in platform
  *     generates them, at publish time or at request time.
- *   - `search-index.json` — the single-file bundle-mode form. Link mode emits
- *     the split `_search/{locale}/*.json` files instead (step 5 below), gated
- *     by `features: [search]`; those are what the hosting worker serves.
+ *   - ANY search index — neither the single-file `search-index.json` nor the
+ *     split `_search/{locale}/*.json`. This lane emitted both until
+ *     2026-08-01 and emits neither now; see step 5 for why. A host that
+ *     stores the content derives search from it.
+ *
+ *     ⚠️ This entry claimed the opposite until 2026-08-26 — that link mode
+ *     emitted the split files "instead", and named a consumer for them. It
+ *     described an emission its own step 5 had already removed, in the
+ *     paragraph a reader consults BEFORE the code, and it was read as
+ *     evidence by a downstream consumer.
  *
  * @param {Object} params
  * @param {string} params.siteRoot - Absolute path to the site directory.

package/src/site/collection-processor.js

@@ -4,10 +4,28 @@
  * Processes content collections from markdown and YAML files into JSON data.
  * Collections are defined in site.yml and processed at build time.
  *
+ * ⛔ A COLLECTION `.md` IS NOT A PAGE-SECTION `.md`. Same extension, unrelated
+ * meanings, and the sync-side reader states this too
+ * (`build/src/uwx/collection-source.js`) because getting it backwards produces
+ * confident nonsense:
+ *
+ *   - collection record — frontmatter is structured DATA whose shape is the
+ *     collection's data schema; the body is the value of ONE declared field
+ *     (the Model's content body field). Not "metadata".
+ *   - page section — frontmatter is foundation/runtime CONFIG (`type:`, params,
+ *     `theme:`); the body is authored content with no schema behind it.
+ *
+ * ⭐ And `.md` is the HYBRID case, not the general one. It exists for records
+ * that are part data and part prose — a blog article. YAML and JSON records are
+ * data only, have no body, and express nesting and arrays natively; they are the
+ * plain case rather than the exception. Reasoning about collections from the
+ * markdown shape alone imports a body and a content field that most records
+ * do not have.
+ *
  * Features:
  * - Discovers markdown (.md), data (.yml/.yaml), JSON (.json), and BibTeX (.bib)
  *   files in collection folders
- * - Parses frontmatter for metadata (markdown), full YAML or JSON (data items),
+ * - Parses frontmatter for record data (markdown), full YAML or JSON (data items),
  *   or BibTeX → CSL-JSON (bibliography items)
  * - Pure-data formats (YAML, JSON, BibTeX) accept either one record per file
  *   (mapping at the top, slug from filename) or many records per file (array
@@ -574,6 +592,63 @@ async function processContentItem(dir, filename, config, siteRoot, basePath) {
   }
 }
 
+/**
+ * Every source file in a collection, as paths relative to the collection root —
+ * `hello.md`, `2024/spring.md`, `2024/q1/notes.yml`.
+ *
+ * Nesting is how an author gives a collection an internal structure, and it is
+ * what the `path` field and the `under` predicate address. Before this walk the
+ * scan was a flat `readdir`, so a record in a subdirectory was not ignored with
+ * a warning — it was invisible, and the site simply rendered without it.
+ *
+ * `_`-prefixed and dot-prefixed names are skipped at every level, files and
+ * directories alike: `_drafts/` stays out of the build the same way `_draft.md`
+ * always has. That is also the escape hatch for a subdirectory that holds
+ * something other than records.
+ */
+async function collectSourceFiles(dir, rel = '') {
+  const entries = await readdir(dir, { withFileTypes: true })
+  const out = []
+  for (const entry of entries) {
+    if (entry.name.startsWith('_') || entry.name.startsWith('.')) continue
+    const relPath = rel ? `${rel}/${entry.name}` : entry.name
+    if (entry.isDirectory()) {
+      out.push(...(await collectSourceFiles(join(dir, entry.name), relPath)))
+    } else if (/\.(md|ya?ml|json|bib)$/i.test(entry.name)) {
+      out.push(relPath)
+    }
+  }
+  return out
+}
+
+/**
+ * A slug identifies one record within its collection — it is what a `[slug]`
+ * route matches and what a per-record file is named. Two files in different
+ * branches can now share a stem (`2024/notes.md`, `2025/notes.md`), which makes
+ * a previously theoretical collision reachable in ordinary authoring.
+ *
+ * The build does not rename or drop either record: the cascade keeps both, and
+ * whichever sorts last wins the route and the per-record file. That is a real
+ * ambiguity only the author can resolve, so it is reported rather than repaired.
+ */
+function warnDuplicateSlugs(items, collectionName) {
+  const seen = new Map()
+  for (const item of items) {
+    if (!item || item.slug === undefined) continue
+    const slug = String(item.slug)
+    const where = item.path ? `${item.path}/` : ''
+    if (seen.has(slug)) {
+      console.warn(
+        `[collection-processor] Collection "${collectionName}" has more than one record with ` +
+          `slug "${slug}" (${seen.get(slug)}${slug}, ${where}${slug}). Its detail route and ` +
+          `per-record file resolve to only one of them — give them distinct slugs.`
+      )
+      continue
+    }
+    seen.set(slug, where)
+  }
+}
+
 /**
  * Collect and process all items in a collection folder
  *
@@ -591,11 +666,7 @@ async function collectItems(siteDir, config, collectionsBase, basePath) {
     return []
   }
 
-  const files = await readdir(collectionDir)
-  const itemFiles = files.filter(f =>
-    !f.startsWith('_') &&
-    (f.endsWith('.md') || f.endsWith('.yml') || f.endsWith('.yaml') || f.endsWith('.json') || f.endsWith('.bib'))
-  )
+  const itemFiles = await collectSourceFiles(collectionDir)
 
   // Process all collection files (markdown → content items, YAML/JSON → data
   // items, BibTeX → CSL-JSON bibliography items).
@@ -614,6 +685,16 @@ async function collectItems(siteDir, config, collectionsBase, basePath) {
     })
   )
 
+  // Stamp each record's position inside the collection BEFORE flattening, while
+  // a result is still aligned with the file it came from. A file's own array
+  // entries (array-form YAML/JSON, every .bib entry) all share its directory.
+  items = items.map((result, i) => {
+    const dir = dirname(itemFiles[i])
+    const path = dir === '.' ? '' : dir
+    if (Array.isArray(result)) return result.map((item) => item && { ...item, path })
+    return result && { ...result, path }
+  })
+
   // Flatten one level: array-form YAML/JSON files and every .bib file
   // contribute their entries individually.
   items = items.flat()
@@ -621,6 +702,8 @@ async function collectItems(siteDir, config, collectionsBase, basePath) {
   // Filter out nulls (unpublished items)
   items = items.filter(Boolean)
 
+  warnDuplicateSlugs(items, config.name)
+
   // Add routes to items if collection has a route configured
   if (config.route) {
     const baseRoute = config.route.replace(/\/$/, '') // Remove trailing slash

package/src/site/collections-config.js

@@ -0,0 +1,260 @@
+// A site's collection declarations — the ONE resolution, for every lane.
+//
+// ⛔ THIS LIVED IN `uwx/` AND THE SITE BUILD COULD NOT SEE IT, so the site build
+// used `site.yml::collections` directly and the two disagreed. Measured before the
+// move: a collection declared only in `collections/collections.yml` resolved here
+// and was INVISIBLE to the build — no `dist/data/<name>.json`, so `data: <name>`
+// delivered nothing while sync pushed it fine. Declared in both files, the build
+// took `site.yml`'s values and sync took `collections.yml`'s, so an author writing
+// `sort: date desc` here got `date asc` baked into the static file.
+//
+// The broken case was the one the public docs recommend. See
+// `kb/framework/plans/one-collections-config.md`.
+//
+// Resolve a site's collection configuration from the (optional, local-first)
+// `collections/collections.yml`, layered over the legacy `site.yml::collections`
+// and the zero-config subfolder-name convention.
+//
+// `collections.yml` is the co-located home for FILE-BASED collection declarations
+// (it sits with the data it describes). It is useful with NO backend at all — it
+// maps each subfolder to a data schema, declares query/display config, and can lay
+// out a VIRTUAL folder organization decoupled from the on-disk layout. (Sync holds no
+// folder uuid here — the backend owns the site's `@uniweb/folder`, keyed by the
+// site-content uuid.)
+//
+// Precedence (per-collection, per-key): collections.yml  >  site.yml::collections.
+// `site.yml::collections` stays valid for remote `url:` sources and back-compat.
+// When neither declares a schema, the subfolder-name convention fills it
+// (`articles` → `@/article`). Absent the file entirely, behavior is unchanged.
+
+import { join } from 'node:path'
+import { existsSync, readFileSync } from 'node:fs'
+import { briefFields, flatRecordFields } from '@uniweb/schemas/conform'
+import { detectFoundationType } from './foundation-ref.js'
+import { readFile } from 'node:fs/promises'
+import yaml from 'js-yaml'
+
+// Read its own YAML rather than importing the site build's helper. That import
+// pointed the wrong way — a config resolver reaching into the collector that
+// consumes it — and became a cycle the moment the site build started calling
+// this. Four lines beats a dependency between two modules that should not know
+// about each other.
+async function readYamlFile(filePath) {
+  if (!existsSync(filePath)) return {}
+  try {
+    return yaml.load(await readFile(filePath, 'utf8')) || {}
+  } catch {
+    return {}
+  }
+}
+
+export const COLLECTIONS_YML_RELPATH = 'collections/collections.yml'
+
+// The default data-schema ref for a collection that declares none: the collection's
+// OWN NAME, unchanged. `@/` is the self scope — the local foundation's `schemas/` —
+// so this stays backend-independent.
+//
+// ⛔ IT USED TO APPLY AN ENGLISH SINGULAR RULE to every language. Measured:
+// `news` → `@/new`, `series` → `@/sery`, `analyses` → `@/analys`. Right for regular
+// English plurals, right-by-accident elsewhere (`noticias` → `noticia`), and inert
+// for languages with no plural marker.
+//
+// ⚠️ The failure was SILENT, which is why the rule was removed rather than improved.
+// A default that does not resolve is not an error — the collection soft-skips to
+// delivery-only — so a `news` collection simply never synced as entities, and
+// nothing said the cause was a guess about English morphology.
+//
+// A more complete rule would move that boundary, not remove it: every irregular
+// list belongs to one language, and a site names its collections in its own.
+// Identity has no boundary to get wrong, and an author wanting a different schema
+// name writes `schema:`, which is one line and says what it means.
+//
+// Exported so the inverse (projection) can drop a `schema:` that merely restates
+// this default, keeping a projected collections.yml as terse as the author left it.
+export function defaultSchema(name) {
+  return `@/${name}`
+}
+
+// Normalize one site.yml::collections entry (string shorthand or object) to the
+// internal decl shape. Paths here are already site-root-relative (legacy contract).
+function normalizeSiteDecl(name, decl) {
+  if (typeof decl === 'string') return { name, path: decl }
+  const d = decl && typeof decl === 'object' ? decl : {}
+  return { name, ...d }
+}
+
+// Normalize one collections.yml::collections entry. Its `path:` is relative to the
+// collections/ directory (default = the collection name); we lift it to a
+// site-root-relative path so downstream readers resolve it uniformly.
+function normalizeYmlDecl(name, decl) {
+  const d = decl && typeof decl === 'object' ? decl : {}
+  const rel = typeof d.path === 'string' ? d.path : name
+  return { name, ...d, path: `collections/${rel}` }
+}
+
+/**
+ * Resolve the merged collection configuration for a site.
+ *
+ * @param {string} siteRoot - directory containing site.yml + collections/
+ * @param {object} [opts]
+ * @param {object} [opts.siteYml] - an already-read site.yml (avoids a re-read)
+ * @returns {Promise<{
+ *   folderSync: boolean,            // collections.yml `sync` (whole-folder opt-out)
+ *   hasCollectionsYml: boolean,
+ *   declarations: object,           // { name: decl }  — merged, schema-defaulted
+ *   folders: Array|null,            // collections.yml `folders` (virtual org) or null
+ * }>}
+ */
+export async function resolveCollectionsConfig(siteRoot, opts = {}) {
+  const siteYml = opts.siteYml || (await readYamlFile(join(siteRoot, 'site.yml')))
+  const ymlPath = join(siteRoot, COLLECTIONS_YML_RELPATH)
+  const hasCollectionsYml = existsSync(ymlPath)
+  const colYml = hasCollectionsYml ? await readYamlFile(ymlPath) : {}
+
+  const declarations = {}
+
+  // Legacy site.yml::collections first (lower precedence).
+  const siteCols = siteYml?.collections
+  if (siteCols && typeof siteCols === 'object' && !Array.isArray(siteCols)) {
+    for (const [name, decl] of Object.entries(siteCols)) {
+      declarations[name] = normalizeSiteDecl(name, decl)
+    }
+  }
+
+  // collections.yml::collections overlay (higher precedence; per-key merge).
+  const ymlCols = colYml?.collections
+  if (ymlCols && typeof ymlCols === 'object' && !Array.isArray(ymlCols)) {
+    for (const [name, decl] of Object.entries(ymlCols)) {
+      const incoming = normalizeYmlDecl(name, decl)
+      declarations[name] = { ...(declarations[name] || {}), ...incoming, name }
+    }
+  }
+
+  // Schema default (subfolder-name convention) + `model:`→`schema:` synonym.
+  // `schemaExplicit` records whether the author asked for this schema: an explicit
+  // schema that fails to resolve is a hard error; a convention-defaulted one that
+  // fails to resolve soft-skips (so a delivery-only collection never breaks sync).
+  for (const decl of Object.values(declarations)) {
+    if (decl.schema) {
+      decl.schemaExplicit = true
+    } else if (decl.model) {
+      decl.schema = decl.model // migration synonym
+      decl.schemaExplicit = true
+    } else if (decl.path || !decl.url) {
+      decl.schema = defaultSchema(decl.name) // subfolder-name convention
+      decl.schemaExplicit = false
+    }
+  }
+
+  await deriveDeferredFromSchemas(siteRoot, siteYml, declarations)
+
+  const folderSync = colYml?.sync !== false
+  return {
+    folderSync,
+    hasCollectionsYml,
+    declarations,
+    folders: Array.isArray(colYml?.folders) ? colYml.folders : null,
+  }
+}
+
+/**
+ * The declarations as `config.collections` should carry them.
+ *
+ * `schemaExplicit` records whether the AUTHOR asked for a schema or the
+ * subfolder-name convention supplied one. That decides how a failed resolution
+ * behaves during sync — hard error vs soft skip — and is nobody's business
+ * downstream. It is stripped here rather than at each consumer, so the payload
+ * has one shape and no consumer has to know the field existed.
+ *
+ * Returns undefined for a site with no collections, so `config.collections`
+ * stays absent rather than becoming an empty object — an empty object reads as
+ * "declared, and empty" to anything checking for presence.
+ */
+export function toConfigCollections(declarations) {
+  const names = Object.keys(declarations || {})
+  if (names.length === 0) return undefined
+  const out = {}
+  for (const name of names) {
+    const { schemaExplicit, ...rest } = declarations[name]
+    out[name] = rest
+  }
+  return out
+}
+
+
+/**
+ * Fill in `deferred:` from each collection's own data schema.
+ *
+ * ⭐ A schema's **brief** section already states what a record's summary is — the
+ * card, the row, the thing a list shows. Everything else is wanted only when one
+ * record is the focus. That is exactly what `deferred:` says, so an author with a
+ * schema should not have to say it twice, in a second vocabulary, with nothing
+ * checking the two against each other.
+ *
+ * ⇒ `deferred` = the schema's flat-record fields MINUS its brief fields.
+ *
+ * Derived from the SCHEMA, never from a record. That is what keeps the
+ * build-derived keys safe without a reserved list: `slug`, `route`, `path`,
+ * `excerpt`, `image` and `lastModified` are not schema fields, so they are never
+ * in the difference and never stripped. `content` is not exempt — it is
+ * schema-governed, and usually the heavy field the split exists for.
+ *
+ * ⛔ Silent on every path that cannot answer, because none of them is an error:
+ *
+ *   - an author-declared `deferred:` wins outright — this never overrides one;
+ *   - no local foundation (a linked or cataloged one), or it is unbuilt → nothing
+ *     to read, and a site must still build;
+ *   - the schema is not in the foundation's built map → the same soft-skip the
+ *     sync lane already applies. `dist/meta/schema.json` carries the schemas
+ *     COMPONENTS reference, so a collection whose schema no component binds is
+ *     simply not there;
+ *   - the schema states no brief (`briefFields` → null, e.g. a root list) → there
+ *     is no lean shape to honour, so records stay whole.
+ *
+ * The last two are why this reads the built artifact rather than resolving
+ * schemas itself: it is the same input the sync lane uses, so both lanes agree
+ * about which schemas exist.
+ */
+async function deriveDeferredFromSchemas(siteRoot, siteYml, declarations) {
+  const pending = Object.values(declarations).filter(
+    (d) => d.schema && !Array.isArray(d.deferred)
+  )
+  if (pending.length === 0) return
+
+  const dataSchemas = loadFoundationDataSchemas(siteRoot, siteYml)
+  if (!dataSchemas) return
+
+  for (const decl of pending) {
+    const schema = dataSchemas[decl.schema]
+    if (!schema) continue
+    const brief = briefFields(schema)
+    if (!brief) continue
+    const all = Object.keys(flatRecordFields(schema) || {})
+    const heavy = all.filter((f) => !brief.has(f))
+    if (heavy.length) decl.deferred = heavy
+  }
+}
+
+/** The foundation's built data-schema map, or null when there is nothing to read. */
+function loadFoundationDataSchemas(siteRoot, siteYml) {
+  if (!siteYml?.foundation) return null
+  let info
+  try {
+    info = detectFoundationType(siteYml.foundation, siteRoot)
+  } catch {
+    return null // a declaration this resolver refuses is not this function's error
+  }
+  if (info?.type !== 'local' || !info.path) return null
+  const schemaPath = join(info.path, 'dist', 'meta', 'schema.json')
+  if (!existsSync(schemaPath)) return null
+  try {
+    return JSON.parse(readFileSync(schemaPath, 'utf8'))?.dataSchemas || null
+  } catch {
+    return null
+  }
+}
+
+/** Path to the collections.yml file (whether or not it exists yet). */
+export function collectionsYmlPath(siteRoot) {
+  return join(siteRoot, COLLECTIONS_YML_RELPATH)
+}

package/src/site/config.js

@@ -31,6 +31,7 @@ import {
 import { importMapPlugin } from '../import-map-plugin.js'
 import { resolveModuleUrl, resolveExtensionUrls } from './extension-urls.js'
 import { resolveFoundationSrcPath } from '../utils/foundation-source-root.js'
+import { detectFoundationType } from './foundation-ref.js'
 
 /**
  * Normalize a base path for Vite compatibility
@@ -60,180 +61,11 @@ function normalizeBasePath(raw) {
   return path
 }
 
-/**
- * Detect foundation type from the foundation config value
- *
- * Foundations are runtime federated modules, never npm packages — there is
- * no fall-through to `node_modules`. A foundation reference resolves to one
- * of two types:
- *
- *   - `'local'` — workspace-local source (sibling directory, file: dep, or
- *     `../../foundations/<name>/`). The build inlines or runtime-links it
- *     depending on the operating mode.
- *   - `'url'`  — loaded by URL at runtime. Two URL shapes:
- *       - `@org/name@ver`   → catalog ref (resolves against the registry CDN)
- *       - `https://...`    → arbitrary URL
- *
- * Versionless registry refs (`@org/name`) are rejected with a specific error —
- * they were a silent fall-through before. Versionless names that don't match
- * any local resolution path are also rejected, with guidance toward the right
- * shape.
- *
- * @param {string|Object} foundation - Foundation config from site.yml
- * @param {string} siteRoot - Path to site directory
- * @returns {{ type: 'local'|'url', name?: string, url?: string, cssUrl?: string, path?: string }}
- * @throws {Error} when the declaration shape is invalid (versionless registry
- *   ref, unknown name with no local match, etc.)
- */
-export function detectFoundationType(foundation, siteRoot) {
-  // Object form with explicit URL
-  if (foundation && typeof foundation === 'object') {
-    if (foundation.url) {
-      return {
-        type: 'url',
-        url: foundation.url,
-        cssUrl: foundation.css || foundation.cssUrl || null
-      }
-    }
-    // Object form with name
-    foundation = foundation.name || 'foundation'
-  }
-
-  // String form
-  const name = foundation || 'foundation'
-
-  // Check if it's a URL
-  if (name.startsWith('http://') || name.startsWith('https://')) {
-    // Try to infer CSS URL from JS URL
-    const cssUrl = name.replace(/\.js$/, '.css').replace(/foundation\.js/, 'assets/style.css')
-    return {
-      type: 'url',
-      url: name,
-      cssUrl
-    }
-  }
-
-  // Catalog registry ref: `@org/name@version`.
-  //
-  // A build does NOT turn this into a URL. Where a foundation is served is the
-  // host's to say — a serve location is READ (from backend discovery, or from an
-  // upload plan's `serve_base`), never reconstructed. `@uniweb/cli`'s
-  // DISCOVERY_DEFAULTS carries no serve-root default for exactly this reason.
-  // A build is offline and backend-optional by design, so it has nothing to ask.
-  //
-  // A ref names a foundation in the Uniweb platform's catalog, and `uniweb
-  // publish` — the verb reserved for that target — has the platform resolve it,
-  // running no vite build. That is one hosting target among many. The others
-  // reach a host through `uniweb deploy --host=<adapter>` or `uniweb export`,
-  // and both need a concrete URL, which the site declares: the runtime accepts
-  // any URL, from any host.
-  //
-  // Until 2026-08-04 this returned `{base}/foundations/{ns}/{name}/{ver}/foundation.js`
-  // against a hardcoded host, overridable only through an env var that did not
-  // match the documented backend selection — so `--backend`, `uniweb login
-  // --backend` and the documented env var all left it pinned — and the artifact
-  // names were the pre-`entry.js` ones the build stopped emitting.
-  const orgScopedMatch = /^@([a-z0-9_-]+)\/([a-z0-9_-]+)@(.+)$/.exec(name)
-  if (orgScopedMatch) {
-    throw new Error(
-      [
-        `Foundation "${name}" is a catalog ref, and a build cannot resolve it to a URL.`,
-        `Where a foundation is served is the host's to declare, so the build does not guess it.`,
-        ``,
-        `  • Deploying to another host (\`uniweb deploy --host=<adapter>\`), or taking`,
-        `    the build anywhere (\`uniweb export\`)? Declare the served URL in site.yml —`,
-        `    the runtime accepts any URL, from any host:`,
-        ``,
-        `      foundation: https://<host>/<path>/entry.js`,
-        ``,
-        `    or the object form when the stylesheet sits elsewhere:`,
-        ``,
-        `      foundation: { url: 'https://…/entry.js', cssUrl: 'https://…/assets/style.css' }`,
-        ``,
-        `  • Iterating locally?`,
-        `    Reference the workspace foundation by package name.`,
-        ``,
-        `  • Targeting the Uniweb platform?`,
-        `    \`uniweb publish\` has the platform resolve the ref — no build-time URL needed.`
-      ].join('\n')
-    )
-  }
-
-  // Versionless scoped names (`@org/name`) are valid as *handles* — they
-  // resolve through the local checks below (file: dep,
-  // workspace sibling) when the developer is iterating locally on a
-  // foundation that will eventually be published as `@org/name@ver`.
-  // Tianyu's uniweb.io site uses this shape:
-  //   site.yml:     foundation: '@uniweb/io'
-  //   package.json: "@uniweb/io": "file:../../foundations/io"
-  // The file: dep check below picks it up. If no local resolution exists
-  // either, the function throws below with a "missing version" hint.
-
-  // Check if it's a local workspace sibling (directory name matches package name)
-  const localPath = resolve(siteRoot, '..', name)
-  if (existsSync(localPath)) {
-    return {
-      type: 'local',
-      name,
-      path: localPath
-    }
-  }
-
-  // Check if it's a file: dependency (co-located projects where dir name ≠ package name)
-  // e.g. "marketing-foundation": "file:../foundation" in marketing/site/package.json
-  try {
-    const pkg = JSON.parse(readFileSync(resolve(siteRoot, 'package.json'), 'utf8'))
-    const dep = pkg.dependencies?.[name]
-    if (dep && dep.startsWith('file:')) {
-      const filePath = resolve(siteRoot, dep.slice(5))
-      if (existsSync(filePath)) {
-        return {
-          type: 'local',
-          name,
-          path: filePath
-        }
-      }
-    }
-  } catch {}
-
-  // Check in foundations/ directory (for multi-site projects)
-  const foundationsPath = resolve(siteRoot, '..', '..', 'foundations', name)
-  if (existsSync(foundationsPath)) {
-    return {
-      type: 'local',
-      name,
-      path: foundationsPath
-    }
-  }
-
-  // Versionless scoped name that didn't resolve locally — likely a typo
-  // or a missing file: dep. Give a specific hint distinguishing the two
-  // common causes (forgot @version vs. forgot to wire the file: dep).
-  if (/^@[a-z0-9_-]+\//.test(name)) {
-    throw new Error(
-      `site.yml foundation: '${name}' did not resolve to a local source and no version was specified.\n` +
-      `If this is a workspace-local foundation, add it to the site's package.json:\n` +
-      `  "dependencies": { "${name}": "file:../path/to/foundation" }\n` +
-      `If this is a published catalog ref, include the version: '${name}@<version>' (e.g. '${name}@0.1.2').`
-    )
-  }
-
-  // Foundations are not npm packages. If we get here, the declaration
-  // didn't match a workspace sibling, a `file:` dep, a foundations/ entry,
-  // a registry ref, or a URL — none of the supported shapes. Fail with
-  // guidance rather than fall through to a node_modules lookup that will
-  // produce a confusing error later in the build.
-  throw new Error(
-    `site.yml foundation: '${name}' did not resolve.\n` +
-    `Foundations must be one of:\n` +
-    `  - a workspace-local sibling (a directory next to the site, named '${name}')\n` +
-    `  - a 'file:' dep in the site's package.json\n` +
-    `  - a directory in '../../foundations/${name}'\n` +
-    `  - a versioned registry ref: '@org/${name}@<version>'\n` +
-    `  - a full URL: 'https://...'\n` +
-    `Foundations are runtime federated modules, not npm packages — there is no fall-through to node_modules.`
-  )
-}
+// `detectFoundationType` moved to its own leaf so lanes that must not pull Vite
+// can resolve a foundation declaration too — see that file's header. Imported as
+// well as re-exported: this module calls it, and a bare re-export creates no local
+// binding.
+export { detectFoundationType }
 
 /**
  * Read and parse site.yml configuration

package/src/site/content-collector.js

@@ -24,6 +24,7 @@
  */
 
 import { readFile, readdir, stat } from 'node:fs/promises'
+import { resolveCollectionsConfig, toConfigCollections } from './collections-config.js'
 import { join, parse, resolve, sep } from 'node:path'
 import { existsSync, statSync, realpathSync, readdirSync } from 'node:fs'
 import yaml from 'js-yaml'
@@ -2172,6 +2173,17 @@ export async function collectSiteContent(sitePath, options = {}) {
   // Read site config and raw theme config
   const siteConfig = await readYamlFile(join(sitePath, configFile))
 
+  // Collections are declared in TWO files — `site.yml::collections` and
+  // `collections/collections.yml`, the latter winning per key — and resolving
+  // them is one question with one answer. This used to read `site.yml` alone
+  // while the sync lane merged both, so a collection declared only in
+  // `collections.yml` was invisible here: never compiled, `data: <name>`
+  // delivering nothing, while sync pushed it fine.
+  const collections = toConfigCollections(
+    (await resolveCollectionsConfig(sitePath, { siteYml: siteConfig })).declarations
+  )
+  if (collections) siteConfig.collections = collections
+
   // Record the RESOLVED base (--base > UNIWEB_BASE > site.yml::base) on the
   // config so every consumer reads one value. Prerender sets website.basePath
   // from `config.base` alone — it has no access to Vite's BASE_URL — so a base