@uniweb/build 1.3.5 → 1.3.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "1.3.5",
+  "version": "1.3.7",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -56,12 +56,12 @@
     "js-yaml": "^4.1.0",
     "sharp": "^0.35.3",
     "yaml": "^2.5.0",
+    "@uniweb/content-writer": "~1.1.2",
     "@uniweb/content-reader": "~1.4.0",
     "@uniweb/projections": "~1.1.1",
-    "@uniweb/content-writer": "~1.1.2",
-    "@uniweb/schemas": "~1.3.0",
     "@uniweb/semantic-parser": "~1.8.1",
-    "@uniweb/theming": "~1.2.0"
+    "@uniweb/theming": "~1.2.0",
+    "@uniweb/schemas": "~1.3.1"
   },
   "optionalDependencies": {
     "@uniweb/runtime": "~1.1.4"

package/src/dev/plugin.js

@@ -26,7 +26,7 @@ import { readFile } from 'node:fs/promises'
 import { existsSync, readdirSync } from 'node:fs'
 import { build } from 'vite'
 import { resolveFoundationSrcPath } from '../utils/foundation-source-root.js'
-import { DEV_REBUILD_MARKER } from '../vite-foundation-plugin.js'
+import { DEV_REBUILD_MARKER } from '../foundation/dev-rebuild.js'
 import { shouldRegenerateForFile } from '../generate-entry.js'
 
 /** Directories that never hold foundation source and must never be walked. */

package/src/foundation/config.js

@@ -27,6 +27,7 @@ import { resolve } from 'node:path'
 import { foundationPlugin } from '../vite-foundation-plugin.js'
 import { jsxExtensionGuard } from '../jsx-extension.js'
 import { nodeEnvDefine } from './node-env.js'
+import { foundationScopeDefine } from './scope-define.js'
 import { resolveFoundationSrcDir } from '../utils/foundation-source-root.js'
 // The ONE definition. This list used to be re-typed here, and again in
 // vite-foundation-plugin.js — three hand-synced copies of "what a foundation
@@ -114,6 +115,8 @@ export async function defineFoundationConfig(options = {}) {
     // JSX compiles only in .jsx files: a .js file holding it fails with that said.
     jsxExtensionGuard(),
     nodeEnvDefine(),
+    // `__FOUNDATION_SCOPE__` — the scope the foundation's own `@/x` names (`scope-define.js`).
+    foundationScopeDefine({ foundationDir: foundationRoot }),
     tailwind && tailwindcss(),
     react(),
     svgr(),

package/src/foundation/dev-rebuild.js

@@ -0,0 +1,31 @@
+/**
+ * Marks a foundation build as a DEV-server rebuild — a leaf, so the foundation
+ * build plugin (`vite-foundation-plugin.js`), the dev server that injects the
+ * marker (`dev/plugin.js`) and the scope define (`scope-define.js`) share it.
+ *
+ * The dev server runs a real Vite `build()` of the foundation on every watched
+ * change (`dev/plugin.js`), so `command`, `mode` and `isProduction` cannot tell
+ * a dev rebuild from a shipping build — all of them say "build". An injected
+ * marker plugin can, and it survives the foundation's own `vite.config.js`
+ * being merged in, which a plugin *option* would not (the dev server does not
+ * construct the foundation plugin — the foundation's config file does).
+ *
+ * Used to skip the `entry-ssr.js` sub-build in dev: it is a second full Vite
+ * pass per save, and nothing in the dev loop reads it (dev never ships, and the
+ * SSR lanes that run locally — SSG prerender and unipress — load `entry.js`).
+ * And to build the foundation as a working copy, as `uniweb dev` serves it in
+ * bundled mode: its `@/x` stays as written (`scope-define.js`).
+ */
+export const DEV_REBUILD_MARKER = 'uniweb:dev-foundation-rebuild'
+
+/**
+ * Whether a Vite config carries the marker — read in a `config` hook, where
+ * `plugins` is still the array as written (nested, with falsy entries), or
+ * once resolved.
+ *
+ * @param {{ plugins?: unknown[] }} config
+ * @returns {boolean}
+ */
+export function hasDevRebuildMarker(config) {
+  return (config?.plugins || []).flat(Infinity).some((p) => p?.name === DEV_REBUILD_MARKER)
+}

package/src/foundation/scope-define.js

@@ -0,0 +1,84 @@
+/**
+ * `__FOUNDATION_SCOPE__` — the scope a foundation's own `@/x` names, stamped
+ * into its bundle.
+ *
+ * A foundation names its own types `@/x` wherever it names one, and a call to
+ * the site's backend is one of those places (`useRecords({ schema: '@/track' })`,
+ * `@uniweb/api`). A backend holds the type under the name `register` stored it
+ * under, `@<scope>/x`, so the call must say the scope — the one in the
+ * foundation's name (`foundation-name.js`), which only its build knows. The
+ * bundle reads it from this constant and names the type with `qualifyRef`
+ * (`@uniweb/schemas/refs`), the rule `register` and a push use.
+ *
+ * Three values, and each says something:
+ *
+ *   '@acme'    a build of `@acme/marketing` that ships — `uniweb build`, and
+ *              `register`, which builds through it: `@/x` is sent as `@acme/x`.
+ *   null       the foundation as a working copy — served by `uniweb dev`, or
+ *              rebuilt by it on each save — or a name with no scope yet: `@/x`
+ *              is sent as written, which is how a local mock holds the
+ *              foundation's own types.
+ *   undefined  not a Uniweb build: `@uniweb/api` refuses `@/x` rather than guess.
+ *
+ * ⭐ Real-backend testing is a job for a built foundation [Diego, 2026-10-17].
+ * A dev rebuild never ships: it empties `dist/` and writes no `entry-ssr.js`,
+ * so `register` builds again before it uploads (`foundationNeedsBuild`).
+ *
+ * An author's own `define` for the key wins: it is left untouched.
+ */
+
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { loadFoundationConfig } from '../schema.js'
+import { foundationNameOf, splitFoundationName } from '../foundation-name.js'
+import { resolveFoundationSrcDir } from '../utils/foundation-source-root.js'
+import { hasDevRebuildMarker } from './dev-rebuild.js'
+
+export const FOUNDATION_SCOPE_KEY = '__FOUNDATION_SCOPE__'
+
+/**
+ * The define, for a build of the foundation at `foundationDir` — its own, its
+ * SSR twin's, or a site's that bundles it.
+ *
+ * @param {{ foundationDir?: string }} [options] - default: the Vite root
+ * @returns {import('vite').Plugin}
+ */
+export function foundationScopeDefine({ foundationDir } = {}) {
+  return {
+    name: 'uniweb:foundation-scope',
+    async config(config, { command }) {
+      if (config.define && FOUNDATION_SCOPE_KEY in config.define) return
+      const workingCopy = command === 'serve' || hasDevRebuildMarker(config)
+      const scope = workingCopy ? null : await foundationScope(foundationDir ?? config.root ?? process.cwd())
+      return { define: { [FOUNDATION_SCOPE_KEY]: JSON.stringify(scope) } }
+    },
+  }
+}
+
+/**
+ * The scope in a foundation's name — `@acme` for `@acme/marketing`, null for a
+ * bare name — read as the build reads the name (`buildSchema`): `main.js`'s
+ * `name`, else `package.json`'s (`foundationNameOf`). A `main.js` that does not
+ * load stops the build here, as it stops the schema.
+ *
+ * ⛔ Not `readFoundationName`, which refuses a leftover `uniweb.scope` or
+ * `uniweb.id` for `register`: a build does not register, and warns about them
+ * instead (`loadPackageJson`) — the scope in the name is what registers.
+ *
+ * @param {string} foundationDir
+ * @returns {Promise<string|null>}
+ */
+export async function foundationScope(foundationDir) {
+  const srcDir = join(foundationDir, resolveFoundationSrcDir(foundationDir))
+  const config = await loadFoundationConfig(srcDir)
+  const { name } = foundationNameOf({ config, pkg: readPackage(foundationDir) })
+  return splitFoundationName(name).scope
+}
+
+function readPackage(foundationDir) {
+  try {
+    return JSON.parse(readFileSync(join(foundationDir, 'package.json'), 'utf8')) || {}
+  } catch {
+    return {}
+  }
+}

package/src/i18n/data-models.js

@@ -11,6 +11,12 @@
  * normalizer (`@uniweb/schemas/foundation::normalizeData`); a ref resolves as a query's records
  * resolve theirs (`resolveRecordSchemas`). A key with no shape, or a ref that does not resolve, has
  * no model, and its blocks keep the heuristic.
+ *
+ * ⛔ A key that DOES declare a shape, which the translation step cannot read, is said aloud
+ * (`warnUnreadable`): its blocks fall back to the heuristic, which never offers a field named
+ * `email`, `time`, `href` and the like. ⛔ Until 2026-10-16 that fall was silent — measured on a
+ * block of contact labels declared `{ type: 'object', values: { type: 'string' } }`, whose `email`
+ * and `time` labels were never offered for translation.
  */
 import { normalizeData } from '@uniweb/schemas/foundation'
 import { foundationSections, resolveRecordSchemas } from '../site/queries-config.js'
@@ -27,6 +33,9 @@ export const NO_DATA_MODELS = () => null
  * @returns {Promise<(type: string, tag: string) => object|null>}
  */
 export async function dataBlockModels(siteRoot, siteYml = null) {
+  // Each key's declaration as written, to say what was meant when its shape cannot be read.
+  const raw = new Map()
+  const warn = (where, reason) => warnUnreadable(siteRoot, where, reason, raw.get(where))
   let sections
   try {
     sections = await foundationSections(siteRoot, siteYml)
@@ -39,7 +48,10 @@ export async function dataBlockModels(siteRoot, siteYml = null) {
   const declared = new Map()
   const declare = (owner, data) => {
     const normalized = normalizeData(data, { strict: false })
-    for (const [key, decl] of Object.entries(normalized || {})) declared.set(at(owner, key), decl)
+    for (const [key, decl] of Object.entries(normalized || {})) {
+      declared.set(at(owner, key), decl)
+      raw.set(at(owner, key), data?.[key])
+    }
   }
   for (const [name, entry] of Object.entries(sections)) {
     if (!entry || typeof entry !== 'object' || name === 'dataSchemas' || name === '_layouts') continue
@@ -62,9 +74,17 @@ export async function dataBlockModels(siteRoot, siteYml = null) {
   for (const [where, decl] of declared) {
     if (decl.kind === 'schema') models.set(where, modelOf(resolved[decl.schema] || null, decl.schema))
     else if (decl.kind === 'fields') {
-      const { kind: _kind, problems: _problems, ...schema } = decl
-      models.set(where, modelOf(schema, '@/inline'))
-    } else models.set(where, null)
+      const { kind: _kind, problems, ...schema } = decl
+      let lowering = null
+      const model = modelOf(schema, '@/inline', (err) => (lowering = err))
+      if (problems?.length || !model) warn(where, problems?.length ? problems.join('; ') : lowering?.message || 'it lowers to no model')
+      models.set(where, model)
+    } else {
+      // A declaration the normalizer could not take at all — a retired `'@x/y/*'` ref, a value that
+      // is no shape — is a shape declared and not read, as much as a field map that fails.
+      if (decl?.problems?.length) warn(where, decl.problems.join('; '))
+      models.set(where, null)
+    }
   }
 
   return (type, tag) => {
@@ -75,3 +95,25 @@ export async function dataBlockModels(siteRoot, siteYml = null) {
 }
 
 const at = (owner, key) => `${owner}\u0000${key}`
+
+// Each unreadable shape once per site per process: extraction, the build, a push and a pull all
+// read the same declarations.
+const warned = new Set()
+
+function warnUnreadable(siteRoot, where, reason, declaration) {
+  const [owner, key] = where.split('\u0000')
+  const once = `${siteRoot}\u0000${where}\u0000${reason}`
+  if (warned.has(once)) return
+  warned.add(once)
+  const who = owner ? `the ${owner} section type` : 'the foundation (main.js)'
+  // ⚠️ `values` only: `{ type: 'object', fields: { … } }` is the whole-schema form, read as its fields.
+  const fieldsCalledType = declaration && typeof declaration === 'object' && typeof declaration.type === 'string' && 'values' in declaration && !('fields' in declaration)
+  const hint = fieldsCalledType
+    ? ` A data key is declared as its block's fields: { type: '${declaration.type}', values: … } declares two fields, named "type" and "values" — name the block's fields instead ({ email: 'string', time: 'string' }).`
+    : /open map/.test(reason)
+      ? " An open map is read when its values are records: values: { type: 'object', fields: { … } }."
+      : ''
+  console.warn(
+    `Warning: ${who} declares data key "${key}" with a shape the translation step cannot read (${reason}), so its blocks' strings are guessed — a field named email, time, href or the like is never offered for translation.${hint}`
+  )
+}

package/src/i18n/extract.js

@@ -480,6 +480,11 @@ function addUnit(units, source, field, context, markup = null) {
     // Two elements can share a key and differ in markup ("Learn more" plain in one
     // place, linked in another). The first occurrence wins the field and the order,
     // but a later one may be the only carrier of markup, so fill it rather than drop it.
+    // ⭐ And say that the places disagree (`markupVaries`): one value serves them all, so
+    // `uniweb i18n init` starts such a unit with its plain words, which a plain place takes as
+    // they are and a link takes as its label (`merge.js::translatedInline`). ⛔ Until 2026-10-16
+    // nothing said so, and init seeded the markup everywhere — a header's heading became a link.
+    if ((markup || null) !== (units[hash].markup || null)) units[hash].markupVaries = true
     if (markup && !units[hash].markup) units[hash].markup = markup
     const existingContexts = units[hash].contexts
     const contextKey = `${context.page}:${context.section}`

package/src/i18n/merge.js

@@ -183,6 +183,9 @@ async function mergeTranslationsAsync(siteContent, translations, options) {
   return translated
 }
 
+// The blocks that hold words, which `toPlainText` reads as one run each.
+const TEXT_BLOCKS = new Set(['paragraph', 'heading', 'codeBlock'])
+
 /**
  * ⭐ A TRANSLATION VALUE IS INLINE MARKDOWN, AND A PLAIN-TEXT SLOT RENDERS ITS TEXT.
  *
@@ -208,18 +211,27 @@ async function mergeTranslationsAsync(siteContent, translations, options) {
  * ⛔ Do not add the field or the role to the hash. Genuine wording divergence by
  * context is what `overrides` is for (`lookupTranslation`); representation
  * divergence is this function's job.
+ *
+ * ⭐ One rule for both lanes: a push sends a plain-text slot's translations through it too
+ * (`uwx/locale-sync.js::plainTextTargets`). ⛔ Until 2026-10-16 only the build did, so a host
+ * was handed `[Sign in](/sign-in)` as a page's French title.
  */
-function toPlainText(value) {
+export function toPlainText(value) {
   if (typeof value !== 'string' || !value.includes('[') && !value.includes('*') && !value.includes('`') && !value.includes('_')) {
     return value
   }
   try {
     const doc = markdownToProseMirror(value)
-    const collect = (nodes) =>
+    // A block's words run together; blocks are apart. ⛔ Until 2026-10-16 every level joined with
+    // nothing, so a value of two paragraphs read as one word at the seam ("…17hFermé…").
+    const inline = (nodes) =>
+      (nodes || []).map((n) => (n.type === 'text' ? n.text || '' : n.type === 'hardBreak' ? ' ' : inline(n.content))).join('')
+    const blocks = (nodes) =>
       (nodes || [])
-        .map((n) => (n.type === 'text' ? n.text || '' : n.type === 'hardBreak' ? ' ' : collect(n.content)))
-        .join('')
-    const text = collect(doc?.content).trim()
+        .map((n) => (TEXT_BLOCKS.has(n.type) ? inline(n.content) : n.type === 'text' ? n.text || '' : blocks(n.content)))
+        .filter((t) => t.trim())
+        .join(' ')
+    const text = blocks(doc?.content).trim()
     return text || value
   } catch {
     return value
@@ -239,7 +251,8 @@ function translateSiteMeta(config, translations, fallbackToSource) {
   if (!seo || typeof seo !== 'object') return
   for (const key of ['ogTitle', 'ogDescription']) {
     if (typeof seo[key] === 'string' && seo[key]) {
-      seo[key] = lookupTranslation(seo[key], SITE_META_CONTEXT, translations, fallbackToSource)
+      // A plain-text slot, as a page's are (`translatePageMeta`). ⛔ Not flattened until 2026-10-16.
+      seo[key] = toPlainText(lookupTranslation(seo[key], SITE_META_CONTEXT, translations, fallbackToSource))
     }
   }
 }
@@ -381,9 +394,18 @@ function applyElementTranslation(node, context, translations, fallbackToSource)
  * its link: the button became a plain paragraph, or vanished from a section that renders only
  * links. Locale files keyed before whole-element keying hold exactly such labels.
  *
- * A value that writes a link is taken as written, re-targeted or not. So is a plain value for an
- * element that mixes words and links, since which words were linked cannot be known;
- * `uniweb i18n status` reports that loss (`translationKeepsMarkup`).
+ * A value that writes a link is taken as written, re-targeted or not — and so where the source
+ * has none: an author may add a link in one language in the app, and a push carries back what a
+ * pull wrote. So is a plain value for an element that mixes words and links, since which words
+ * were linked cannot be known; `uniweb i18n status` reports that loss (`translationKeepsMarkup`).
+ *
+ * ⭐ One text is one unit wherever it appears (`hash.js`), so a heading that says `Faculty of
+ * Science` and a link that says it share a value. Its places disagreeing on markup is the seed's to
+ * handle, not this function's: extraction marks such a unit (`markupVaries`, `extract.js`), and
+ * `uniweb i18n init` starts it with its plain words — which the heading takes as they are and the
+ * link takes as its label. ⛔ @uniweb/build 1.3.6 (2026-10-16) instead dropped a value's link from
+ * any element whose source had none: it fixed the seeded heading, and lost a link an author had
+ * added on the next push. Reverted the same day.
  *
  * @param {Array} source - the element's source inline content
  * @param {string} value - the translation, inline markdown
@@ -495,8 +517,10 @@ export function linkLabels(source, target) {
   return labels.length === links.length ? labels : null
 }
 
+// A link's mark — `link`, or `button`, which is a link drawn as a button (`[Go](/x){button}`).
+// ⛔ Until 2026-10-16 only `link`: a `{button}` translated by its label alone lost the button.
 function linkMarkOf(node) {
-  return node?.type === 'text' ? node.marks?.find((mark) => mark.type === 'link') || null : null
+  return node?.type === 'text' ? node.marks?.find((mark) => mark.type === 'link' || mark.type === 'button') || null : null
 }
 
 function sameMark(a, b) {

package/src/i18n/records.js

@@ -187,11 +187,12 @@ function isFieldTranslatable(fieldDef) {
  * @param {string} ref - the ref it was resolved from
  * @returns {Object|null} the lowered declaration, or null when there is none
  */
-export function modelOf(schema, ref) {
+export function modelOf(schema, ref, onError = null) {
   if (!schema) return null
   try {
     return toDataSchemaDeclaration(schema, { name: ref || '@/record', resolveName: (r) => r })
-  } catch {
+  } catch (err) {
+    onError?.(err) // a caller that can say why — `data-models.js`, for a declared block shape
     return null // a schema a push refuses is refused there, and the build keeps its heuristic
   }
 }

package/src/site/config.js

@@ -31,6 +31,7 @@ import {
 } from '../generate-entry.js'
 import { importMapPlugin } from '../import-map-plugin.js'
 import { jsxExtensionGuard } from '../jsx-extension.js'
+import { foundationScopeDefine } from '../foundation/scope-define.js'
 import { resolveModuleUrl, resolveExtensionUrls } from './extension-urls.js'
 import { resolveFoundationSrcPath } from '../utils/foundation-source-root.js'
 import { checkFoundationResolution } from '../utils/foundation-resolution-check.js'
@@ -333,6 +334,11 @@ export async function defineSiteConfig(options = {}) {
       foundationPath: foundationInfo.path // For loading foundation theme vars
     }),
 
+    // A bundled foundation is compiled here, so its `__FOUNDATION_SCOPE__` is set here: its
+    // scope in a build, null under `uniweb dev` (`foundation/scope-define.js`). A foundation
+    // loaded by URL carries its own, set by its build.
+    !isRuntimeMode && foundationInfo.path && foundationScopeDefine({ foundationDir: foundationInfo.path }),
+
     // Foundation dev server (only in runtime mode with local foundation)
     isRuntimeMode &&
       foundationInfo.type === 'local' &&

package/src/uwx/data-schema.js

@@ -22,6 +22,7 @@
  */
 
 import { parseOptionsRef, FIELD_RULES } from '@uniweb/schemas/format'
+import { qualifyRef } from '@uniweb/schemas/refs'
 
 // Text kinds carry per-locale values when localized.
 const TEXT_KINDS = new Set(['string', 'text'])
@@ -690,9 +691,5 @@ function sectionAttrsFromField(field) {
 function defaultResolver(ownName) {
   const slash = ownName.indexOf('/')
   const org = ownName[0] === '@' && slash > 1 ? ownName.slice(1, slash) : ''
-  return (ref) => {
-    if (typeof ref !== 'string') return ref
-    if (ref.startsWith('@/')) return `@${org}/${ref.slice(2)}`
-    return ref
-  }
+  return (ref) => qualifyRef(ref, org)
 }

package/src/uwx/locale-sync.js

@@ -24,7 +24,7 @@ import { proseMirrorToMarkdown, serializeInlineContent } from '@uniweb/content-w
 import { computeHash } from '../i18n/hash.js'
 import { blockElements, elementText, dataBlockNodes } from '../i18n/extract.js'
 import { visitDataBlockStrings } from '../i18n/data-strings.js'
-import { resolveDocForLocale, translatedInline, linkLabels } from '../i18n/merge.js'
+import { resolveDocForLocale, translatedInline, linkLabels, toPlainText } from '../i18n/merge.js'
 import { computeSourceHash } from '../i18n/freeform-manifest.js'
 import { sameMarkdownDocument, canonicalJson } from './same-content.js'
 import { parseFrontmatter } from '../utils/frontmatter.js'
@@ -239,6 +239,30 @@ export function contextKey(context) {
   return context?.key ?? `${context?.page}:${context?.section}`
 }
 
+/**
+ * A localized PLAIN-TEXT value — a page's title, label, description, keywords and Open Graph
+ * texts, and the site's — with each translation as text, as the build renders it
+ * (`i18n/merge.js::toPlainText`). The source stays as the author wrote it, as the build leaves it.
+ * ⛔ Until 2026-10-16 a push sent a translation's markdown as it was, so a unit shared by a page's
+ * title and a link to the page reached a host as `[Sign in](/sign-in)`.
+ *
+ * @param {object|Array|undefined} value - a `{ locale: text }` map, or a list of them
+ * @param {string} sourceLocale
+ */
+export function plainTextTargets(value, sourceLocale) {
+  if (Array.isArray(value)) return value.map((item) => plainTextTargets(item, sourceLocale))
+  if (!value || typeof value !== 'object') return value
+  let out = value
+  for (const [locale, text] of Object.entries(value)) {
+    if (locale === sourceLocale || typeof text !== 'string') continue
+    const plain = toPlainText(text)
+    if (plain === text) continue
+    if (out === value) out = { ...value }
+    out[locale] = plain
+  }
+  return out
+}
+
 /**
  * Wrap a `multiple: true` + `localized: true` field (e.g. page `keywords` — "array
  * of localized strings") into per-locale form by localizing each element. Container

package/src/uwx/records-project.js

@@ -46,7 +46,8 @@ import { dataKeyTypes } from './data-key-types.js'
 import { poolDirsForSchema, schemaForPoolDirs, resolveRecordsDir } from '../site/entity-pool.js'
 import { folderYmlPath } from '../site/records-config.js'
 import { contentBodyTarget } from './record-layout.js'
-import { unresolveSelfScope, resolveSelfScope, ownSchemaNames, refuseOrgOption } from './self-scope.js'
+import { qualifyRef } from '@uniweb/schemas/refs'
+import { unresolveSelfScope, ownSchemaNames, refuseOrgOption } from './self-scope.js'
 import { parseCatalogRef } from '../site/foundation-ref.js'
 import { renderEntityDocument } from './backfill.js'
 import { labelForFile } from '../site/entry-label.js'
@@ -54,6 +55,7 @@ import { LINK_MODEL, writeLinkRecords } from './link-records.js'
 import { FILE_MODEL, filesToPull } from './file-records.js'
 import { parseBibtex } from '@citestyle/bibtex'
 import { createTranslationCollector, writeLocaleTranslations, writeFreeformTranslations } from './locale-sync.js'
+import { siteSourceLocale } from './source-locale.js'
 import { buildFreeformRecordPath } from '../i18n/freeform.js'
 
 // Single-record source extensions we scan + place (BibTeX is multi-record → out).
@@ -215,13 +217,13 @@ function recordDirsReadingAs(recordsRoot, model, scope, { own = null, keyTypes =
     const at = [first]
     const keyType = !own?.has(first) ? keyTypes?.get(first) : null
     if (
-      resolveSelfScope(schemaForPoolDirs(at), scope) === model ||
-      (keyType && resolveSelfScope(keyType, scope) === model)
+      qualifyRef(schemaForPoolDirs(at), scope) === model ||
+      (keyType && qualifyRef(keyType, scope) === model)
     ) {
       dirs.push(join(recordsRoot, first))
     }
     for (const second of visible(join(recordsRoot, first))) {
-      if (resolveSelfScope(schemaForPoolDirs([first, second]), scope) === model) {
+      if (qualifyRef(schemaForPoolDirs([first, second]), scope) === model) {
         dirs.push(join(recordsRoot, first, second))
       }
     }
@@ -451,7 +453,7 @@ function typedQueryFolders(siteRoot, recordsRoot, scope, own, keyTypes) {
   for (const [name, schema] of authoredQuerySchemas(siteRoot, siteYml)) {
     if (schema !== null || own?.has(name)) continue
     const type = keyTypes.get(name)
-    const model = type ? resolveSelfScope(type, scope) : null
+    const model = type ? qualifyRef(type, scope) : null
     if (model && !out.has(model)) out.set(model, join(recordsRoot, name))
   }
   return out
@@ -527,7 +529,7 @@ export function declarationsToQueriesYml({ document, siteRoot, scope, ...rest })
  * @returns {{ status: 'updated'|'unchanged'|'removed'|'skipped', entries: Array, warnings: string[], file: string }}
  *   `file` is where the organization lives, as the author would write it
  */
-export function folderToFolderYml({ folderDoc, siteRoot, poolPathByUuid, sourceLocale = 'en' }) {
+export function folderToFolderYml({ folderDoc, siteRoot, poolPathByUuid, sourceLocale = siteSourceLocale(siteRoot) }) {
   const warnings = []
   const { abs, rel: file } = folderYmlPath(siteRoot)
   if (!folderDoc) return { status: 'skipped', entries: [], warnings, file }
@@ -625,7 +627,9 @@ export function folderToFolderYml({ folderDoc, siteRoot, poolPathByUuid, sourceL
  * @returns {{ updated: string[], placed: string[], unchanged: string[], skipped: object[], warnings: string[], locales: object }}
  */
 export function recordsToProject({ folderDoc, recordDocs = [], siteRoot, opts = {} }) {
-  const { resolveDeclaration, sourceLocale = 'en' } = opts
+  // The site's language, as its `site.yml` says it — written by the pull of the site's content, which
+  // runs first (`./source-locale.js`).
+  const { resolveDeclaration, sourceLocale = siteSourceLocale(siteRoot) } = opts
   refuseOrgOption(opts, 'recordsToProject')
   // The scope the push qualified `@/x` with — the site's foundation's — so a
   // `@scope/x` model is placed back where the author wrote it. ⛔ It was the site

package/src/uwx/records.js

@@ -59,11 +59,13 @@ import {
 import { toDataSchemaDeclaration, isProseMirrorField, isMarkupTextField, isOpenMapSection, openMapEntries } from './data-schema.js'
 import { recordFileLayout, contentBodyTarget } from './record-layout.js'
 import { emitEntitySyncPackage } from './entity-document.js'
-import { resolveSelfScope, siteSelfScope, refuseOrgOption } from './self-scope.js'
+import { qualifyRef } from '@uniweb/schemas/refs'
+import { siteSelfScope, refuseOrgOption } from './self-scope.js'
 import { sha256Hex, toJsonBuffer } from './manifest.js'
 import { isUuid } from './uuid.js'
 import { markdownToProseMirror } from '@uniweb/content-reader'
 import { LOCALIZED_FIELD_ASSUMPTION } from './localize.js'
+import { siteSourceLocale } from './source-locale.js'
 import { localizeScalar, localizeScalarList, localizeContentDoc, loadLocaleTranslations, discoverLocales, discoverFreeformLocales, localesDir, isLocalizedContent } from './locale-sync.js'
 import { loadFreeformRecord } from '../i18n/freeform.js'
 import { isDraftRecord } from '../site/record-draft.js'
@@ -822,10 +824,7 @@ function resolveDeclaration(schema, modelName) {
   const dataSchemas = schema?.dataSchemas || {}
   const m = /^@([^/]+)\/(.+)$/.exec(modelName)
   const org = m ? m[1] : null
-  const resolveName = (ref) =>
-    typeof ref === 'string' && ref.startsWith('@/') && org
-      ? `@${org}/${ref.slice(2)}`
-      : ref
+  const resolveName = (ref) => qualifyRef(ref, org)
   for (const [ref, normalized] of Object.entries(dataSchemas)) {
     if (resolveName(ref) === modelName) {
       return toDataSchemaDeclaration(normalized, { name: modelName, resolveName })
@@ -972,7 +971,7 @@ export async function buildRecordEntities(siteRoot, opts = {}) {
     opts.scope !== undefined ? opts.scope : await siteSelfScope(siteRoot, { foundationDir: opts.foundationDir })
   const warnedUnscoped = new Set()
   const modelFor = (schema, where) => {
-    const modelName = resolveSelfScope(schema, scope)
+    const modelName = qualifyRef(schema, scope)
     // Unresolvable `@/` — the foundation has no scope yet. Ship it rather than
     // throwing (a `status` probe on a never-registered foundation must still count),
     // but say so: the backend's refusal names a missing Model and cannot name this cause.
@@ -1031,7 +1030,7 @@ export async function buildRecordEntities(siteRoot, opts = {}) {
   }
 
   const sourceLocale =
-    opts.sourceLocale || LOCALIZED_FIELD_ASSUMPTION.defaultSourceLocale
+    opts.sourceLocale || siteSourceLocale(siteRoot)
 
   // Target locales for wrapping localized record fields per-locale: those with a
   // structural-translation file (locales/records/{locale}.json) UNIONED with
@@ -1277,8 +1276,8 @@ export async function buildRecordEntities(siteRoot, opts = {}) {
       ? !unresolved.has(schema)
       : Boolean((await declarationFor(modelFor(schema, `query "${name}"`))) || (await typedFor(schema))))
     if (!resolved) {
-      if (decl.schemaExplicit) throw unresolvedExplicit(resolveSelfScope(schema, scope), name)
-      schemaless.push({ name, model: resolveSelfScope(schema, scope) })
+      if (decl.schemaExplicit) throw unresolvedExplicit(qualifyRef(schema, scope), name)
+      schemaless.push({ name, model: qualifyRef(schema, scope) })
       continue
     }
     if (!hasRecords) {

package/src/uwx/registry-package.js

@@ -28,6 +28,7 @@ import { join } from 'node:path'
 
 import { normalizeFoundationSchema } from '@uniweb/schemas/foundation'
 import { parseOptionsRef } from '@uniweb/schemas/format'
+import { qualifyRef } from '@uniweb/schemas/refs'
 import { toDataSchemaDeclaration, optionsSectionPath } from './data-schema.js'
 import { checkFoundationName, splitFoundationName } from '../foundation-name.js'
 
@@ -146,8 +147,7 @@ function buildDataSchemaEntities(dataSchemas, scope) {
   // `scope` ('@acme' or 'acme') resolves a defined schema's own `@/x` name to a
   // concrete `@acme/x`. With no scope, `@/x` passes through (local preview).
   const org = scope ? String(scope).replace(/^@/, '').replace(/\/.*$/, '') : null
-  const scoped = (ref) =>
-    org && typeof ref === 'string' && ref.startsWith('@/') ? `@${org}/${ref.slice(2)}` : ref
+  const scoped = (ref) => qualifyRef(ref, org)
 
   const resolveOptions = makeOptionsResolver(dataSchemas, scoped)
   const entities = Object.entries(dataSchemas)

package/src/uwx/self-scope.js

@@ -7,7 +7,9 @@
 // the entity store at restore, and a records service answering a hosted page's
 // query.
 //
-// ⭐ ONE RULE FOR EVERY PATH THAT SHIPS A REF FROM ONE PUBLISH, and its inverse:
+// ⭐ ONE RULE FOR EVERY PATH THAT SHIPS A REF FROM ONE PUBLISH — `qualifyRef`
+// (`@uniweb/schemas/refs`, the rule `register` and a foundation's own calls to its
+// backend use too) with the scope `siteSelfScope` reads — and its inverse here:
 //
 //   - a record's `$schema`            `records.js::buildRecordEntities`
 //   - a query's `schema`              `site.js::queriesNested` (the `queries` Section)
@@ -51,24 +53,8 @@ export function bareOrg(scope) {
 }
 
 /**
- * `@/x` → `@<scope>/x`. Any other ref (`@std/x`, `@acme/x`) passes through, and so
- * does `@/x` when no scope is known — callers that ship an unresolved alias say so
- * themselves (`buildRecordEntities` warns per query).
- *
- * @param {unknown} ref
- * @param {unknown} scope - the site's foundation's scope (`siteSelfScope`)
- * @returns {unknown}
- */
-export function resolveSelfScope(ref, scope) {
-  const handle = bareOrg(scope)
-  return typeof ref === 'string' && ref.startsWith('@/') && handle
-    ? `@${handle}/${ref.slice(2)}`
-    : ref
-}
-
-/**
- * The inverse, for a pull: `@<scope>/x` → `@/x` — when `x` is one of the foundation's
- * OWN data schemas.
+ * The inverse of `qualifyRef`, for a pull: `@<scope>/x` → `@/x` — when `x` is one
+ * of the foundation's OWN data schemas.
  *
  * ⛔ WITHOUT THIS THE ROUND TRIP IS NOT A FIXED POINT, and the failure is silent
  * on both ends. A record authored under `records/article/` comes back as

package/src/uwx/site-diff.js

@@ -48,7 +48,7 @@
 
 import { entityContentHash } from './records.js'
 import { sectionFileBase, pageDirName, layoutSectionPaths } from './site-project.js'
-import { LOCALIZED_FIELD_ASSUMPTION } from './localize.js'
+import { documentSourceLocale } from './source-locale.js'
 
 // A unit's own content, with the nested collections that are their own units
 // removed — so editing a section never also marks its page (or its parent
@@ -70,7 +70,7 @@ const ownContent = (record, ...childKeys) => {
  *
  * @returns {Map<string, object>} path → the unit's own record
  */
-export function collectSiteUnits(doc, sourceLocale = LOCALIZED_FIELD_ASSUMPTION.defaultSourceLocale) {
+export function collectSiteUnits(doc, sourceLocale = documentSourceLocale(doc)) {
   const units = new Map()
   walkSiteUnits(doc, (path, record, kind) => {
     units.set(
@@ -93,7 +93,7 @@ export function collectSiteUnits(doc, sourceLocale = LOCALIZED_FIELD_ASSUMPTION.
  *
  * @param {(path: string, record: object, kind: 'info'|'page'|'section') => void} cb
  */
-export function walkSiteUnits(doc, cb, sourceLocale = LOCALIZED_FIELD_ASSUMPTION.defaultSourceLocale) {
+export function walkSiteUnits(doc, cb, sourceLocale = documentSourceLocale(doc)) {
   const walkSections = (sections, dir) => {
     for (const record of sections || []) {
       // The projector's own file rule — including an app-created section named from its
@@ -353,7 +353,7 @@ const KEYED_SECTIONS = {
  *
  * @returns {Map<string, { uuid: string|null, record: object }>}
  */
-export function siteItemsByKey(doc, sourceLocale = LOCALIZED_FIELD_ASSUMPTION.defaultSourceLocale) {
+export function siteItemsByKey(doc, sourceLocale = documentSourceLocale(doc)) {
   const out = new Map()
   const uuidOf = (record) => (typeof record?.$uuid === 'string' && record.$uuid ? record.$uuid : null)
   const units = collectSiteUnits(doc, sourceLocale)

package/src/uwx/site-project.js

@@ -52,6 +52,7 @@ import { unwritableNodes } from '@uniweb/content-writer'
 import { buildFreeformPath, freeformPathsFor } from '../i18n/freeform.js'
 import { unwrapLocalized, unwrapLocalizedList } from './backfill.js'
 import { LOCALIZED_FIELD_ASSUMPTION } from './localize.js'
+import { documentSourceLocale } from './source-locale.js'
 import { siteContentDirs } from './site-dirs.js'
 import { layoutAreaRoute, readLayoutFolderSync, DEFAULT_LAYOUT } from '../site/layout-folder.js'
 import { layoutNameKey } from '@uniweb/core/layout-name'
@@ -215,7 +216,7 @@ function readAuthoredYaml(filePath) {
  * @returns {{ siteConfig: string, theme?: string, headHtml?: string }} per-file
  *          write status ('updated' | 'unchanged')
  */
-export function siteInfoToConfig({ document, siteRoot, backend = null, sourceLocale = LOCALIZED_FIELD_ASSUMPTION.defaultSourceLocale, collector, keepAuthoredFoundation = false }) {
+export function siteInfoToConfig({ document, siteRoot, backend = null, sourceLocale = documentSourceLocale(document), collector, keepAuthoredFoundation = false }) {
   const info = document?.info || {}
   const settingsSection = document?.settings || {}
 
@@ -1272,7 +1273,8 @@ function refuseContentFilesCannotHold(document, sourceLocale) {
  * @param {object} params
  * @param {object} params.document - the `@uniweb/site-content` `$`-document
  * @param {string} params.siteRoot
- * @param {string} [params.sourceLocale]
+ * @param {string} [params.sourceLocale] - the language the document is written in; by default its
+ *        own `settings`, by the rule its push wrapped it with (`documentSourceLocale`)
  * @param {boolean} [params.prune=false] - delete orphaned pages/sections/layout
  *        files that have no corresponding incoming item (git-pull-like). Off by
  *        default; `uniweb pull` opts in. Guarded against wiping a level on an
@@ -1282,7 +1284,7 @@ function refuseContentFilesCannotHold(document, sourceLocale) {
  *        `declarationsToQueriesYml`, whose default it overrides.
  * @returns {{ config: object, collections: object, locales: object, pages: string[], sections: string[], layout: string[], deleted: string[], renamed: object[] }}
  */
-export function siteContentDocumentToProject({ document, siteRoot, backend = null, sourceLocale = LOCALIZED_FIELD_ASSUMPTION.defaultSourceLocale, prune = false, keepAuthoredFoundation = false, scope, dataModel = null }) {
+export function siteContentDocumentToProject({ document, siteRoot, backend = null, sourceLocale = documentSourceLocale(document), prune = false, keepAuthoredFoundation = false, scope, dataModel = null }) {
   // Before anything is written: a pull that would leave content out of the files stops here.
   refuseContentFilesCannotHold(document, sourceLocale)
 

package/src/uwx/site.js

@@ -73,7 +73,7 @@ import { readLayoutFolder, layoutAreaRoute } from '../site/layout-folder.js'
 import { normalizeHideIn } from '../site/nav-visibility.js'
 import { resolveDefaultLocale, validateLanguageConfig, queryDataUrl } from '@uniweb/core'
 import { emitEntitySyncPackage } from './entity-document.js'
-import { loadLocaleTranslations, localizeScalar, localizeScalarList, localizeContentDoc, localesDir, isLocalizedContent } from './locale-sync.js'
+import { loadLocaleTranslations, localizeScalar, localizeScalarList, localizeContentDoc, localesDir, isLocalizedContent, plainTextTargets } from './locale-sync.js'
 import { unwrapLocalized } from './backfill.js'
 import { loadFreeformTranslation } from '../i18n/freeform.js'
 import { resolveLocaleList } from '../i18n/locales.js'
@@ -87,7 +87,8 @@ import {
   refuseUnreadableServices
 } from './services-request.js'
 import { resolveQueriesConfig } from './queries-config.js'
-import { resolveSelfScope, siteSelfScope, refuseOrgOption } from './self-scope.js'
+import { qualifyRef } from '@uniweb/schemas/refs'
+import { siteSelfScope, refuseOrgOption } from './self-scope.js'
 import { siteContentDirs } from './site-dirs.js'
 
 const SITE_ENTITY_KEY = 'site-content' // one content entity per site project
@@ -264,11 +265,13 @@ async function localizeContentTree(pages, layoutSections, sourceLocale, targetLo
 // build translates them (`i18n/merge.js::translatePageMeta`, `<route>:_meta`): an override for one
 // page applies there and nowhere else. ⛔ Until 2026-09-26 they were resolved with no page, so an
 // override never reached a backend — nor, until the same day, an entry's default.
+// ⭐ Each is a plain-text slot, so a translation reaches it as text, as the build renders it
+// (`plainTextTargets`).
 function localizePageMeta(page, route, sourceLocale, translations) {
   const context = { page: route, section: '_meta' }
   const again = (value) =>
     value && typeof value === 'object' && typeof value[sourceLocale] === 'string'
-      ? localizeScalar(value[sourceLocale], sourceLocale, translations, context)
+      ? plainTextTargets(localizeScalar(value[sourceLocale], sourceLocale, translations, context), sourceLocale)
       : value
   for (const key of ['title', 'label', 'description', 'og_title', 'og_description']) {
     if (page[key] !== undefined) page[key] = again(page[key])
@@ -1053,7 +1056,7 @@ function queriesNested(declarations, uuids = null, scope = null, keyTyped = null
     // and a store that checks a query's `schema` against the site's declared types refused the
     // whole content push for it. An explicit `schema:` that does not resolve never reaches here:
     // the records lane refuses it.
-    if (!schemaless?.has(name)) setIf(data, 'schema', resolveSelfScope(schema, scope))
+    if (!schemaless?.has(name)) setIf(data, 'schema', qualifyRef(schema, scope))
     // ⭐ …AND SAYS SO, so a pull can tell the author's form (`team:`, no schema) from an explicit
     // one — sent only where the deployment's `queries` Section declares the key (`GET /dev/config`
     // → `siteContent.queryFields`), since one that does not refuses a push carrying it.
@@ -1306,14 +1309,15 @@ function settingsNested(siteYml, { headHtml, themeYml, sourceLocale, translation
   // The site's Open Graph title and description per language, where the deployment's `settings`
   // takes them (`uwx/open-graph.js`), in the site's context (`SITE_META_CONTEXT`).
   // (Each read inline from `siteYml.seo`, so the emit surface names its source.)
-  setIf(settings, 'og_title', openGraphValue(siteYml.seo, 'og_title', settingsFields, sourceLocale, translations, SITE_META_CONTEXT))
-  setIf(settings, 'og_description', openGraphValue(siteYml.seo, 'og_description', settingsFields, sourceLocale, translations, SITE_META_CONTEXT))
+  // Plain-text slots, each translation as text (`plainTextTargets`).
+  setIf(settings, 'og_title', plainTextTargets(openGraphValue(siteYml.seo, 'og_title', settingsFields, sourceLocale, translations, SITE_META_CONTEXT), sourceLocale))
+  setIf(settings, 'og_description', plainTextTargets(openGraphValue(siteYml.seo, 'og_description', settingsFields, sourceLocale, translations, SITE_META_CONTEXT), sourceLocale))
   setIf(settings, 'seo', seoBesideOpenGraph(siteYml.seo, settingsFields))
   // ⭐ `keywords` IS seo by function — it renders into `<meta name="keywords">`
   // (`runtime/src/ssr-renderer.js`). It is top-level in site.yml for authoring
   // convenience, not because it is a different kind of thing. Localized, so it
   // carries the translation collector with it.
-  setIf(settings, 'keywords', localizeScalarList(siteYml.keywords, sourceLocale, translations))
+  setIf(settings, 'keywords', plainTextTargets(localizeScalarList(siteYml.keywords, sourceLocale, translations), sourceLocale))
 
   // ⛔ NO SERVICE IS HERE. A service's address and options ride its row in the
   // `services` Section, whole (`requestedServices`) [Diego, 2026-10-06: "If it's on and
@@ -1431,7 +1435,7 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
   // a localized `{lang:value}` map. Genuine content fields (`description` below, page
   // title/slug/label/keywords, the body) stay localized. (uwx-format.md → identity-label names.)
   info.name = siteYml.name
-  setIf(info, 'description', localizeScalar(siteYml.description, sourceLocale, translations))
+  setIf(info, 'description', plainTextTargets(localizeScalar(siteYml.description, sourceLocale, translations), sourceLocale))
   // 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

package/src/uwx/source-locale.js

@@ -0,0 +1,57 @@
+/**
+ * ⭐ THE LANGUAGE A SITE IS WRITTEN IN — the locale every localized value of it is keyed by on the
+ * sync wire, its source. One rule for both directions, `resolveDefaultLocale`
+ * (`@uniweb/core/locale-config`): `defaultLanguage`, else the first of `languages`, else `en`.
+ *
+ * - From the files, `site.yml` (`siteSourceLocale`): what a push wraps pages, records and folder
+ *   labels under.
+ * - From a document, its `settings` (`documentSourceLocale`): what a pull unwraps them by, and what
+ *   keys a document's units. A push sends `default_language` when the site names one, and its
+ *   `languages` source first (`uwx/site.js`), so the rule over a document gives back the language
+ *   the push wrapped it in.
+ *
+ * ⛔ Until 2026-10-16 only the page push asked the site. The record push and every pull assumed
+ * `en`, which every site measured until then happened to be written in: a French site with an
+ * English translation came back from a pull in English, its own text filed as a translation of it;
+ * a French-only clone came back with empty sections; and its records were pushed labelled English,
+ * their English translations left out.
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import yaml from 'js-yaml'
+import { resolveDefaultLocale } from '@uniweb/core/locale-config'
+import { YAML_OPTIONS } from '../utils/yaml-schema.js'
+
+/**
+ * The language a site's files are written in — `site.yml`'s, by the shared rule.
+ *
+ * @param {string} siteRoot - the directory holding `site.yml`
+ * @returns {string}
+ */
+export function siteSourceLocale(siteRoot) {
+  const path = join(siteRoot, 'site.yml')
+  let siteYml = null
+  if (existsSync(path)) {
+    try {
+      siteYml = yaml.load(readFileSync(path, 'utf8'), YAML_OPTIONS)
+    } catch {
+      siteYml = null // an unreadable site.yml is reported by whoever reads it for more
+    }
+  }
+  return resolveDefaultLocale(siteYml && typeof siteYml === 'object' ? siteYml : {})
+}
+
+/**
+ * The language a `@uniweb/site-content` document's localized values are keyed by — its
+ * `settings`, by the shared rule.
+ *
+ * @param {object} document - the site-content `$`-document
+ * @returns {string}
+ */
+export function documentSourceLocale(document) {
+  const settings = document?.settings
+  return resolveDefaultLocale({
+    defaultLanguage: settings?.default_language,
+    languages: settings?.languages,
+  })
+}

package/src/uwx/sync-package.js

@@ -25,6 +25,7 @@ import { ASSET_SLOTS } from '@uniweb/semantic-parser'
 import { fileRecordUploads } from './file-records.js'
 import { buildFolderEntity } from './folder.js'
 import { siteProjectToDocument } from './site.js'
+import { siteSourceLocale } from './source-locale.js'
 import { siteSelfScope, refuseOrgOption } from './self-scope.js'
 import { stampUnitUuids, collectUnitUuids } from './site-diff.js'
 import { emitEntitySyncPackage } from './entity-document.js'
@@ -299,7 +300,10 @@ function rewriteEntityAssets(node, map, ids, noStamp = null) {
  */
 export async function emitSyncPackages(siteRoot, opts = {}) {
   const includeSite = opts.includeSite !== false
-  const sourceLocale = opts.sourceLocale
+  // ⭐ ONE LANGUAGE FOR THE WHOLE EMIT — the site's (`./source-locale.js`): its pages, its records,
+  // its folder's labels and the paths its units are keyed by. ⛔ Until 2026-10-16 only the pages asked
+  // the site; the rest assumed `en`.
+  const sourceLocale = opts.sourceLocale || siteSourceLocale(siteRoot)
   const priorHashes = opts.priorHashes || {}
   const sendAll = !!opts.sendAll
   const stamp = withBaseVersion(opts.baseVersions || {}, opts.itemBaseVersions || {})

package/src/vite-foundation-plugin.js

@@ -18,6 +18,8 @@ import { DEFAULT_EXTERNALS } from './import-map-plugin.js'
 import { deriveSupports } from './foundation/derive-supports.js'
 import { proseWithoutStyles, PROSE_WITHOUT_STYLES_WARNING } from './foundation/prose-styles.js'
 import { nodeEnvDefine } from './foundation/node-env.js'
+import { foundationScopeDefine } from './foundation/scope-define.js'
+import { DEV_REBUILD_MARKER, hasDevRebuildMarker } from './foundation/dev-rebuild.js'
 
 // Foundations already told that their prose has no stylesheet — once per process, so a dev
 // server's rebuild on every save does not repeat it.
@@ -348,7 +350,7 @@ async function buildEntrySSR(foundationRoot, entrySourcePath, outDir) {
     }
     const react = (await import('@vitejs/plugin-react')).default
     const svgr = (await import('vite-plugin-svgr')).default
-    plugins.push(react(), svgr(), nodeEnvDefine())
+    plugins.push(react(), svgr(), nodeEnvDefine(), foundationScopeDefine({ foundationDir: foundationRoot }))
 
     await viteBuild({
       root: foundationRoot,
@@ -389,21 +391,8 @@ async function buildEntrySSR(foundationRoot, entrySourcePath, outDir) {
   }
 }
 
-/**
- * Marks a foundation build as a DEV-server rebuild.
- *
- * The dev server runs a real Vite `build()` of the foundation on every watched
- * change (`dev/plugin.js`), so `command`, `mode` and `isProduction` cannot tell
- * a dev rebuild from a shipping build — all of them say "build". An injected
- * marker plugin can, and it survives the foundation's own `vite.config.js`
- * being merged in, which a plugin *option* would not (the dev server does not
- * construct the foundation plugin — the foundation's config file does).
- *
- * Used to skip the `entry-ssr.js` sub-build in dev: it is a second full Vite
- * pass per save, and nothing in the dev loop reads it (dev never ships, and the
- * SSR lanes that run locally — SSG prerender and unipress — load `entry.js`).
- */
-export const DEV_REBUILD_MARKER = 'uniweb:dev-foundation-rebuild'
+// The dev-rebuild marker lives in a leaf (`foundation/dev-rebuild.js`); exported here as before.
+export { DEV_REBUILD_MARKER }
 
 /**
  * Vite plugin for foundation builds
@@ -440,7 +429,7 @@ export function foundationBuildPlugin(options = {}) {
       resolvedOutDir = config.build.outDir
       resolvedRoot = config.root
       isProduction = config.mode === 'production'
-      isDevRebuild = (config.plugins || []).some((p) => p?.name === DEV_REBUILD_MARKER)
+      isDevRebuild = hasDevRebuildMarker(config)
     },
 
     async writeBundle(_options, bundle) {