@uniweb/build 0.14.36 → 0.14.37

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.14.36",
+  "version": "0.14.37",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -59,12 +59,12 @@
     "js-yaml": "^4.1.0",
     "sharp": "^0.33.2",
     "yaml": "^2.5.0",
-    "@uniweb/content-writer": "0.2.7",
-    "@uniweb/theming": "0.1.9"
+    "@uniweb/theming": "0.1.9",
+    "@uniweb/content-writer": "0.2.7"
   },
   "optionalDependencies": {
     "@uniweb/content-reader": "1.1.14",
-    "@uniweb/runtime": "0.8.28",
+    "@uniweb/runtime": "0.8.29",
     "@uniweb/schemas": "0.2.4"
   },
   "peerDependencies": {
@@ -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.7.22"
+    "@uniweb/core": "0.7.23"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/i18n/extract.js

@@ -5,6 +5,7 @@
  * strings and building a manifest of translation units.
  */
 
+import { resolveDefaultLocale } from '@uniweb/core'
 import { computeHash, stripInlineTags } from './hash.js'
 
 /**
@@ -55,7 +56,7 @@ export function extractTranslatableContent(siteContent) {
 
   return {
     version: '1.0',
-    defaultLocale: siteContent.config?.defaultLanguage || 'en',
+    defaultLocale: resolveDefaultLocale(siteContent.config),
     extracted: new Date().toISOString(),
     units
   }

package/src/prerender.js

@@ -11,6 +11,7 @@ import { readFile, writeFile, mkdir } from 'node:fs/promises'
 import { existsSync, readdirSync, statSync } from 'node:fs'
 import { join, dirname, resolve } from 'node:path'
 import { pathToFileURL } from 'node:url'
+import { resolveDefaultLocale } from '@uniweb/core'
 import { executeFetch, mergeDataIntoContent } from './site/data-fetcher.js'
 import { shouldSplitContent } from './site/split-content.js'
 import { FONT_LINKS_MARKER } from './site/head-markers.js'
@@ -284,7 +285,7 @@ async function processSectionFetches(sections, fetchOptions, onProgress) {
  */
 async function discoverLocaleContents(distDir, defaultContent) {
   const locales = []
-  const defaultLocale = defaultContent.config?.defaultLanguage || 'en'
+  const defaultLocale = resolveDefaultLocale(defaultContent.config)
 
   // Add the default locale (root level)
   locales.push({
@@ -582,7 +583,7 @@ export async function prerenderSite(siteDir, options = {}) {
     // Execute data fetches (site, page, section levels)
     // For non-default locales, collection data is read from dist/{locale}/data/
     onProgress('Executing data fetches...')
-    const defaultLocale = defaultSiteContent.config?.defaultLanguage || 'en'
+    const defaultLocale = resolveDefaultLocale(defaultSiteContent.config)
     const { pageFetchedData, fetchedData } = await executeAllFetches(
       siteContent, siteDir, onProgress,
       { locale, defaultLocale, distDir }

package/src/resolve-data-schema.js

@@ -18,10 +18,12 @@
  *   '@uniweb/name'   → reserved: the platform system namespace, not a data
  *                      schema source (rejected, with a pointer to '@std').
  *
- * Alias routing (`schemas.config.js`): a foundation may map a scope to a
- * directory of schema files, so '@org/name' resolves to a bare folder anywhere
- * on disk — no package, no install. The alias takes precedence over the
- * '@org/schemas' package convention; see `loadSchemaAliases`.
+ * Alias routing (`schemas.config.js`): a foundation may route a scope to a
+ * directory of schema files ('@org' → a folder), so '@org/name' resolves to a
+ * bare folder anywhere on disk — no package, no install. It may also override a
+ * SINGLE schema to an exact file ('@org/name' → a file), which wins over the
+ * scope directory for that one name. Both take precedence over the '@org/schemas'
+ * package convention (file over directory over package); see `loadSchemaAliases`.
  *
  * The authoring format and its canonical type vocabulary are documented in
  * `data-schema-format.md`. This module validates that format and normalizes the
@@ -31,7 +33,7 @@
  */
 
 import { readFile } from 'node:fs/promises'
-import { existsSync, readdirSync } from 'node:fs'
+import { existsSync, readdirSync, statSync } from 'node:fs'
 import { join, resolve, isAbsolute, extname, basename } from 'node:path'
 import { pathToFileURL } from 'node:url'
 import { createRequire } from 'node:module'
@@ -155,20 +157,47 @@ export async function resolveSchemaRef(ref, { srcDir, aliases }) {
     )
   }
 
-  // Alias routing (schemas.config.js): a scope mapped to a directory resolves to
-  // a bare schema FILE in that directory — no package, no install, no node_modules.
-  // This lets a foundation point '@agency' at a shared schema folder anywhere on
-  // disk. Takes precedence over the package convention below; '@/' (self) and the
-  // reserved '@uniweb' scope are handled above and are never aliasable.
+  // Alias routing (schemas.config.js), most-specific first — no package, no
+  // install, no node_modules; '@/' (self) and the reserved '@uniweb' scope are
+  // handled above and are never aliasable.
+  //
+  // A per-schema alias ('@org/name' → a FILE) overrides one schema to an exact
+  // file. It's the explicit way to keep a shared scope routed to a catalog while
+  // swapping in one local definition — no symlink, no forked scope. It wins over
+  // the scope directory (checked next), which wins over the package (below).
+  const aliasedFile = aliases?.[`@${scope}/${name}`]
+  if (aliasedFile) {
+    const file = resolveAliasedSchemaFile(aliasedFile)
+    if (!file) {
+      throw new Error(
+        `Data schema '${ref}' is aliased to '${aliasedFile}' (via schemas.config.js), but no schema file ` +
+          `exists there. Point it at a ${SCHEMA_EXTENSIONS.join(' / ')} file.`
+      )
+    }
+    return validateAndNormalizeSchema(await loadSchemaFile(file), ref)
+  }
+
+  // A scope alias ('@org' → a DIR) resolves 'name' to a bare schema FILE in that
+  // directory. This lets a foundation point '@agency' at a shared schema folder
+  // anywhere on disk.
   const aliasDir = aliases?.[`@${scope}`]
   if (aliasDir) {
     const file = findSchemaFileInDir(aliasDir, name)
     if (!file) {
       const tried = SCHEMA_EXTENSIONS.map((e) => `${name}${e}`).join(', ')
-      throw new Error(
+      let msg =
         `Data schema '${ref}' not found in the directory '@${scope}' is aliased to ('${aliasDir}' ` +
-          `via schemas.config.js). Expected one of: ${tried}.`
-      )
+        `via schemas.config.js). Expected one of: ${tried}.`
+      // The confusing case: the '@org/schemas' package is ALSO installed. A routed
+      // scope never falls back to it (fail-loud beats silently loading a different
+      // definition), so say so rather than leave the developer wondering.
+      if (isScopePackageInstalled(scope, srcDir)) {
+        msg +=
+          ` Note: '${packageForScope(scope)}' is installed, but a routed scope takes precedence over the ` +
+          `package and does not fall back to it. Override this one schema with a '@${scope}/${name}' file alias, ` +
+          `or add '${name}' to the routed directory.`
+      }
+      throw new Error(msg)
     }
     return validateAndNormalizeSchema(await loadSchemaFile(file), ref)
   }
@@ -640,20 +669,23 @@ function findSchemaFileInDir(dir, name) {
 
 /**
  * Load a foundation's optional `schemas.config.js` and return a map of
- * `'@scope' → absolute directory`. The file default-exports a plain object
- * mapping a schema-ref scope to a directory of schema files:
+ * `'@key' → absolute path`. The file default-exports a plain object; each key is
+ * either a SCOPE (routing the whole scope to a directory of schema files) or a
+ * single SCHEMA (`@scope/name`, overriding that one schema to an exact file):
  *
  *   // <foundation>/schemas.config.js
  *   export default {
- *     '@agency': '../shared/agency-schemas',   // relative to the foundation
- *     '@brand':  process.env.BRAND_SCHEMAS,     // machine-specific, via env
+ *     '@agency':        '../shared/agency-schemas',   // scope → directory
+ *     '@agency/person': './schemas/agency-person.yml', // one schema → a file
+ *     '@brand':         process.env.BRAND_SCHEMAS,     // machine-specific, via env
  *   }
  *
  * It's plain JS (consistent with main.js / vite.config.js), so paths compute
  * natively — relative, absolute, env-based, or homedir — with no expansion DSL.
- * Relative paths resolve against the foundation source dir. A scope whose value
- * is null/undefined (e.g. an unset env var) is skipped — that scope falls back
- * to the '@org/schemas' package convention. Returns `{}` when the file is absent.
+ * Relative paths resolve against the foundation source dir. A key whose value is
+ * null/undefined (e.g. an unset env var) is skipped — that scope/schema falls
+ * back to the next source (scope directory, then the '@org/schemas' package).
+ * Returns `{}` when the file is absent.
  *
  * @param {string} srcDir - Foundation source root (where main.js lives).
  * @returns {Promise<Record<string, string>>}
@@ -670,23 +702,69 @@ async function loadSchemaAliases(srcDir) {
     throw new Error(`Failed to load schemas.config.js: ${err.message}`)
   }
   if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
-    throw new Error(`schemas.config.js must default-export a map of '@scope' → directory.`)
+    throw new Error(`schemas.config.js must default-export a map of '@scope' (or '@scope/name') → path.`)
   }
 
   const out = {}
   for (const [key, value] of Object.entries(raw)) {
     if (value == null) continue // unset (e.g. missing env var) → not aliased
     if (typeof value !== 'string') {
-      throw new Error(`schemas.config.js: alias '${key}' must be a directory path string, got ${typeof value}.`)
-    }
-    if (key[0] !== '@' || key === '@/' || key.includes('/')) {
-      throw new Error(`schemas.config.js: alias key '${key}' must be a scope like '@agency' (no slash, not '@/').`)
+      throw new Error(`schemas.config.js: alias '${key}' must be a path string, got ${typeof value}.`)
     }
+    validateAliasKey(key)
     out[key] = isAbsolute(value) ? value : resolve(srcDir, value)
   }
   return out
 }
 
+// A schemas.config.js key is either a scope ('@agency' → a directory of schema
+// files) or a single schema ('@agency/person' → one file). Reject '@/' (self —
+// put the file in the foundation's schemas/), the reserved '@uniweb' scope, and
+// anything malformed. The message keeps the "must be a scope like '@agency'"
+// phrasing so the guidance reads the same for the common no-'@' slip.
+function validateAliasKey(key) {
+  if (typeof key !== 'string' || key[0] !== '@') {
+    throw new Error(
+      `schemas.config.js: alias key '${key}' must be a scope like '@agency' (or a single schema like '@agency/person').`
+    )
+  }
+  const slash = key.indexOf('/')
+  const scope = slash === -1 ? key.slice(1) : key.slice(1, slash)
+  const name = slash === -1 ? '' : key.slice(slash + 1)
+  if (!scope) {
+    throw new Error(`schemas.config.js: alias key '${key}' must be a scope like '@agency' (not '@/…' — that's the foundation's own schemas/).`)
+  }
+  if (scope === RESERVED_SYSTEM_SCOPE) {
+    throw new Error(`schemas.config.js: '@${scope}' is reserved and cannot be aliased. Use '@std' for the standard schemas.`)
+  }
+  if (slash !== -1 && (!name || name.includes('/'))) {
+    throw new Error(`schemas.config.js: alias key '${key}' must be '@scope' or '@scope/name' (a single schema name).`)
+  }
+}
+
+// Resolve a per-schema alias VALUE (already an absolute path) to a loadable
+// schema file: the exact path if it names a file, else the path + each known
+// extension (so a '@acme/person' → '.../person' value finds 'person.yml'). A
+// directory is not a file — returns null so the caller errors clearly.
+function resolveAliasedSchemaFile(absPath) {
+  if (existsSync(absPath) && !statSync(absPath).isDirectory()) return absPath
+  for (const ext of SCHEMA_EXTENSIONS) {
+    if (existsSync(absPath + ext)) return absPath + ext
+  }
+  return null
+}
+
+// Is the scope's '@org/schemas' package resolvable from the foundation? Used only
+// to enrich a routed-scope "not found" error — never throws, never loads.
+function isScopePackageInstalled(scope, srcDir) {
+  try {
+    createRequire(join(srcDir, 'package.json')).resolve(packageForScope(scope))
+    return true
+  } catch {
+    return false
+  }
+}
+
 async function loadSchemaFile(filePath) {
   if (filePath.endsWith('.js')) {
     const mod = await import(pathToFileURL(filePath).href)

package/src/search/generate.js

@@ -5,6 +5,7 @@
  * for client-side search functionality.
  */
 
+import { resolveDefaultLocale } from '@uniweb/core'
 import { extractSearchContent } from './extract.js'
 
 /**
@@ -18,7 +19,7 @@ import { extractSearchContent } from './extract.js'
  */
 export function generateSearchIndex(siteContent, options = {}) {
   const {
-    locale = siteContent.config?.activeLocale || siteContent.config?.defaultLanguage || 'en',
+    locale = siteContent.config?.activeLocale || resolveDefaultLocale(siteContent.config),
     extract: extractOptions = {},
     search: searchConfig = {}
   } = options

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

@@ -21,6 +21,7 @@ import { writeFile, readFile, mkdir, cp } from 'node:fs/promises'
 import { existsSync } from 'node:fs'
 import { join, resolve } from 'node:path'
 
+import { resolveDefaultLocale } from '@uniweb/core'
 import { collectSiteContent } from './content-collector.js'
 import { processCollections, writeCollectionFiles } from './collection-processor.js'
 import { processAssets, rewriteSiteContentPaths } from './asset-processor.js'
@@ -197,8 +198,7 @@ export async function buildSiteData({
   //    declared the feature at all.
   const siteFeatures = finalContent.config?.features || []
   if (Array.isArray(siteFeatures) && siteFeatures.includes('search')) {
-    const defaultLocale =
-      finalContent.config?.defaultLanguage || finalContent.config?.activeLocale || 'en'
+    const defaultLocale = resolveDefaultLocale(finalContent.config)
     const searchDir = join(resolvedDistDir, '_search', defaultLocale)
     await mkdir(searchDir, { recursive: true })
 

package/src/site/content-collector.js

@@ -32,6 +32,7 @@ import { collectSectionIcons, mergeIconCollections, buildIconManifest } from './
 import { normalizeHideIn, dropUnpublishedPages } from './nav-visibility.js'
 import { parseFetchConfig, singularize } from './data-fetcher.js'
 import { buildTheme, extractFoundationVars } from '../theme/index.js'
+import { resolveDefaultLocale, resolvePublishableLocales, validateLanguageConfig } from '@uniweb/core'
 
 // Try to import content-reader, fall back to simplified parser
 let markdownToProseMirror
@@ -2204,21 +2205,59 @@ export async function collectSiteContent(sitePath, options = {}) {
   // keeps the canonical (folder-based) route. Strip the build-time `slug` from
   // pages afterward — the runtime hydrates the precomputed map, not per-page
   // slugs (see "Minimize Runtime Payload").
-  const defaultLocale =
-    siteConfig.defaultLanguage ||
-    (Array.isArray(siteConfig.languages) ? siteConfig.languages[0] : null) ||
-    'en'
+  const defaultLocale = resolveDefaultLocale(siteConfig)
+  const langValidation = validateLanguageConfig(siteConfig)
+  for (const { message } of langValidation.warnings) {
+    console.warn(`[content-collector] ${message}`)
+  }
+  // Publish filter (kb/framework/build/uwx-format.md → "Per-locale publish
+  // readiness"): on published build paths, only the publishable intersection
+  // (publishLanguages ∩ languages; absent field = all declared) ships — in
+  // the embedded languages list and in route translations. Dev keeps the
+  // full declared set so draft locales stay previewable, mirroring how
+  // `hidden` pages behave. Invalid publish configs (nothing publishable /
+  // default not publishable) hard-error the publish build, warn-only in dev.
+  const { publishable, explicit: hasPublishList } = resolvePublishableLocales(siteConfig)
+  if (dropUnpublished && langValidation.errors.length > 0) {
+    throw new Error(
+      `[content-collector] invalid language configuration:\n` +
+        langValidation.errors.map((e) => `  - ${e.message}`).join('\n')
+    )
+  }
+  const publishFilterActive = dropUnpublished && hasPublishList
+  const effectiveLanguages = Array.isArray(siteConfig.languages)
+    ? publishFilterActive
+      ? publishable
+      : siteConfig.languages
+    : null
   const routeTranslations = buildRouteTranslations(pages, {
     defaultLocale,
-    languages: Array.isArray(siteConfig.languages) ? siteConfig.languages : null,
+    languages: effectiveLanguages,
   })
   for (const page of pages) {
     if (page.slug) delete page.slug
   }
 
+  // `publishLanguages` is authoring/publish intent — it has no runtime
+  // consumer and never ships in a payload (the visitor runtime is
+  // list-unaware; the sync lane reads site.yml directly, not this output).
+  const { publishLanguages: _publishLanguages, ...runtimeSiteConfig } = siteConfig
+
   return {
     config: {
-      ...siteConfig,
+      ...runtimeSiteConfig,
+      // Embed the RESOLVED effective default (defaultLanguage || languages[0]
+      // || 'en') so every downstream reader — prerender, search, runtime,
+      // shell-mode consumers — sees an explicit value instead of re-deriving
+      // it (historically with inconsistent fallbacks). The backend projection
+      // normalizes identically on its lane (default_language || languages[0]).
+      defaultLanguage: defaultLocale,
+      // On publish builds the embedded languages list is the publishable
+      // intersection — a draft locale is indistinguishable from an
+      // undeclared one to visitors (no locale switcher entry).
+      ...(publishFilterActive && Array.isArray(siteConfig.languages)
+        ? { languages: publishable }
+        : {}),
       fetch: parseFetchConfig(siteConfig.fetch),
       ...(hasIntelligence && { intelligence: intelligenceConfig }),
       ...(routeTranslations

package/src/site/plugin.js

@@ -33,6 +33,7 @@
 import { resolve, join } from 'node:path'
 import { watch, existsSync } from 'node:fs'
 import { readFile, readdir } from 'node:fs/promises'
+import { resolveDefaultLocale } from '@uniweb/core'
 import { collectSiteContent } from './content-collector.js'
 import { processAssets, rewriteSiteContentPaths } from './asset-processor.js'
 import { processAdvancedAssets } from './advanced-processors.js'
@@ -204,6 +205,21 @@ function applyRouteTranslation(route, locale, routeTranslations) {
   return route
 }
 
+/**
+ * Restrict authored `seo.locales` hreflang entries to locales the payload
+ * actually serves. `config.languages` is the publishable intersection on
+ * production builds (the collector filters by publishLanguages), so draft
+ * locales never get advertised in sitemap/meta hreflang. The default-locale
+ * entry always survives (it's served at the root regardless).
+ */
+function filterSeoLocales(seoLocales, config) {
+  if (!Array.isArray(seoLocales) || seoLocales.length === 0) return seoLocales || []
+  const langs = Array.isArray(config?.languages) ? config.languages : null
+  if (!langs) return seoLocales
+  const served = new Set(langs)
+  return seoLocales.filter((l) => l.default || served.has(l.code))
+}
+
 /**
  * Generate sitemap.xml content
  */
@@ -299,7 +315,8 @@ function generateRobotsTxt(baseUrl, options = {}) {
  * Generate meta tags for SEO
  */
 function generateMetaTags(siteContent, seoOptions) {
-  const { baseUrl, defaultImage, twitterHandle, locales = [] } = seoOptions
+  const { baseUrl, defaultImage, twitterHandle } = seoOptions
+  const locales = filterSeoLocales(seoOptions.locales, siteContent.config)
   const siteConfig = siteContent.config || {}
   const tags = []
 
@@ -651,6 +668,11 @@ export function siteContentPlugin(options = {}) {
         collectionTranslations = {}
       } catch (err) {
         console.error('[site-content] Failed to collect content:', err.message)
+        // Production: a failed collect must fail the build — falling through
+        // would publish an empty site (and would swallow deliberate hard
+        // errors like an invalid publishLanguages config). Dev: keep the
+        // server up with empty content so the author can fix the file.
+        if (isProduction) throw err
         siteContent = { config: {}, theme: {}, pages: [] }
       }
     },
@@ -871,7 +893,7 @@ export function siteContentPlugin(options = {}) {
         // Serve sitemap.xml in dev mode
         if (req.url === '/sitemap.xml' && seoEnabled && siteContent?.pages) {
           res.setHeader('Content-Type', 'application/xml')
-          res.end(generateSitemap(siteContent.pages, seoOptions.baseUrl, seoOptions.locales, siteContent.config?.i18n?.routeTranslations))
+          res.end(generateSitemap(siteContent.pages, seoOptions.baseUrl, filterSeoLocales(seoOptions.locales, siteContent.config), siteContent.config?.i18n?.routeTranslations))
           return
         }
 
@@ -888,7 +910,7 @@ export function siteContentPlugin(options = {}) {
           const searchEnabled = searchPluginConfig.enabled !== false && isSearchEnabled(siteContent)
           if (searchEnabled) {
             const searchConfig = siteContent.config?.search || {}
-            const defaultLocale = siteContent.config?.defaultLanguage || 'en'
+            const defaultLocale = resolveDefaultLocale(siteContent.config)
             // Use requested locale from URL, fall back to active or default
             const requestedLocale = searchIndexMatch[1]
             const activeLocale = requestedLocale || siteContent.config?.activeLocale || defaultLocale
@@ -1170,7 +1192,7 @@ export function siteContentPlugin(options = {}) {
       // Generate SEO files if enabled
       if (seoEnabled && finalContent?.pages) {
         // Generate sitemap.xml
-        const sitemap = generateSitemap(finalContent.pages, seoOptions.baseUrl, seoOptions.locales, finalContent.config?.i18n?.routeTranslations)
+        const sitemap = generateSitemap(finalContent.pages, seoOptions.baseUrl, filterSeoLocales(seoOptions.locales, finalContent.config), finalContent.config?.i18n?.routeTranslations)
         this.emitFile({
           type: 'asset',
           fileName: 'sitemap.xml',
@@ -1192,7 +1214,7 @@ export function siteContentPlugin(options = {}) {
       const searchEnabled = searchPluginConfig.enabled !== false && isSearchEnabled(finalContent)
       if (searchEnabled) {
         const searchConfig = finalContent.config?.search || {}
-        const defaultLocale = finalContent.config?.defaultLanguage || 'en'
+        const defaultLocale = resolveDefaultLocale(finalContent.config)
         const activeLocale = finalContent.config?.activeLocale || defaultLocale
 
         // Generate search index for current locale

package/src/uwx/site-project.js

@@ -92,6 +92,9 @@ const INFO_TO_SITE_YML = {
   foundation: 'foundation',
   languages: 'languages',
   default_language: 'defaultLanguage',
+  // Publish intent — verbatim both ways, dangling codes included (they carry
+  // the preserved publish intent of a temporarily-undeclared language).
+  publish_languages: 'publishLanguages',
   base: 'base',
   favicon: 'favicon',
   fetcher: 'fetcher',

package/src/uwx/site.js

@@ -46,8 +46,8 @@ import {
   processMarkdownFile,
 } from '../site/content-collector.js'
 import { normalizeHideIn } from '../site/nav-visibility.js'
+import { resolveDefaultLocale, validateLanguageConfig } from '@uniweb/core'
 import { emitEntitySyncPackage } from './entity-document.js'
-import { LOCALIZED_FIELD_ASSUMPTION } from './localize.js'
 import { loadLocaleTranslations, localizeScalar, localizeScalarList, localizeContentDoc, localesDir, isLocalizedContent } from './locale-sync.js'
 import { unwrapLocalized } from './backfill.js'
 import { loadFreeformTranslation } from '../i18n/freeform.js'
@@ -503,15 +503,15 @@ function collectionsNested(declarations) {
  * @param {object} [opts]
  * @param {string} [opts.entityUuid] - override the entity `$uuid` (tests); default
  *        is `site.yml::$uuid` (absent on first sync — `$id`-only document).
- * @param {string} [opts.sourceLocale] - localized-field wrap locale (default "en").
+ * @param {string} [opts.sourceLocale] - localized-field wrap locale. Defaults to
+ *        the site's effective default locale (`defaultLanguage || languages[0] ||
+ *        'en'` — the shared `resolveDefaultLocale` rule), NOT a bare 'en'.
  * @returns {Promise<object>} the section-keyed `$`-document:
  *        `{ $uuid?, $id, $model, info, pages, layout_sections, extensions, collections }`
  */
 export async function siteProjectToDocument(siteRoot, opts = {}) {
-  const sourceLocale =
-    opts.sourceLocale || LOCALIZED_FIELD_ASSUMPTION.defaultSourceLocale
-
   const siteYml = await readYamlFile(join(siteRoot, 'site.yml'))
+  const sourceLocale = opts.sourceLocale || resolveDefaultLocale(siteYml)
   if (!siteYml.name) {
     throw new Error('uwx/site: site.yml::name is required')
   }
@@ -521,6 +521,20 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
         'it maps to the required @uniweb/site-content info.foundation'
     )
   }
+  // Language-config contract: warnings surface (dangling publish codes,
+  // legacy entry shapes); errors — nothing publishable / default not
+  // publishable — hard-error at push, same as the static build does at
+  // build/deploy (uwx-format.md → "Per-locale publish readiness").
+  const langValidation = validateLanguageConfig(siteYml)
+  for (const { message } of langValidation.warnings) {
+    console.warn(`uwx/site: ${message}`)
+  }
+  if (langValidation.errors.length > 0) {
+    throw new Error(
+      'uwx/site: invalid language configuration:\n' +
+        langValidation.errors.map((e) => `  - ${e.message}`).join('\n')
+    )
+  }
 
   const themeYml = await readYamlFile(join(siteRoot, 'theme.yml'))
   let headHtml
@@ -550,6 +564,12 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
   if (themeYml && Object.keys(themeYml).length > 0) info.theme = themeYml
   setIf(info, 'languages', siteYml.languages)
   setIf(info, 'default_language', siteYml.defaultLanguage)
+  // Publish intent (site.yml `publishLanguages:`) rides VERBATIM — dangling
+  // codes included. Sync carries the full working set; only *publish* filters
+  // (backend projection / static-build filter). The verbatim carry is what
+  // preserves a locale's publish intent across a remove + re-add in
+  // `languages:` (uwx-format.md → "Per-locale publish readiness").
+  setIf(info, 'publish_languages', siteYml.publishLanguages)
   // `foundation` (required) — the verbatim `site.yml::foundation` string
   // (registry ref / URL / local path), the round-trip source of truth.
   info.foundation = siteYml.foundation