@uniweb/build 1.3.6 → 1.3.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "1.3.6",
+  "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-reader": "~1.4.0",
     "@uniweb/content-writer": "~1.1.2",
+    "@uniweb/content-reader": "~1.4.0",
     "@uniweb/projections": "~1.1.1",
+    "@uniweb/semantic-parser": "~1.8.1",
     "@uniweb/theming": "~1.2.0",
-    "@uniweb/schemas": "~1.3.0",
-    "@uniweb/semantic-parser": "~1.8.1"
+    "@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

@@ -79,7 +79,12 @@ export async function dataBlockModels(siteRoot, siteYml = 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 models.set(where, null)
+    } 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) => {
@@ -101,9 +106,10 @@ function warnUnreadable(siteRoot, where, reason, declaration) {
   if (warned.has(once)) return
   warned.add(once)
   const who = owner ? `the ${owner} section type` : 'the foundation (main.js)'
-  const fieldsCalledType = declaration && typeof declaration === 'object' && typeof declaration.type === 'string' && ('values' in declaration || 'fields' in declaration)
+  // ⚠️ `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' in declaration ? 'values' : 'fields'}: … } declares two fields, named "type" and "${'values' in declaration ? 'values' : 'fields'}" — name the block's fields instead ({ email: 'string', time: 'string' }).`
+    ? ` 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: { … } }."
       : ''

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.
  *
@@ -207,8 +210,7 @@ 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 — and `translatedInline`'s, for an element whose
- * source has no link.
+ * 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
@@ -220,11 +222,16 @@ export function toPlainText(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
@@ -387,19 +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.
  *
- * ⭐ And a link is the SOURCE's to have: a value that writes one, given to an element whose source
- * has none, gives it its words alone. One text is one unit wherever it appears (`hash.js`), so its
- * value serves a heading that says it and a link that says it alike — `Faculty of Science` in a
- * header, `[Faculty of Science](/)` in a list — and the link belongs to the place that has one.
- * Representation is the consumer's, as a title's is (`toPlainText`). ⛔ Until 2026-10-16 the value
- * was taken as written: `uniweb i18n init` seeds a unit with the markup of whichever occurrence
- * carries some, so an untouched seeded locale turned the heading into a link — and the parser,
- * which reads a heading made only of a link as a link, left its section without a title.
+ * 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`).
  *
- * A value that writes a link, given to an element whose source has one, 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`). Emphasis is the translator's: a value's bold or italic stays.
+ * ⭐ 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
@@ -408,36 +414,7 @@ function applyElementTranslation(node, context, translations, fallbackToSource)
 export function translatedInline(source, value) {
   const fragment = inlineMarkdownToFragment(value)
   if (!fragment) return null
-  const labels = asLinkLabels(source, fragment, value)
-  if (labels) return labels
-  return hasLink(source) ? fragment : withoutLinks(fragment)
-}
-
-// Whether inline content holds a link — on its text, or inside an inline wrapper.
-function hasLink(nodes) {
-  return (nodes || []).some((node) => Boolean(linkMarkOf(node)) || hasLink(node?.content))
-}
-
-// Inline content without its links: the words, and every other mark, kept — runs that end up
-// alike joined, as the reader would have written them.
-function withoutLinks(nodes) {
-  const out = []
-  for (const node of nodes) {
-    let next = node
-    if (node?.content) next = { ...node, content: withoutLinks(node.content) }
-    else if (linkMarkOf(node)) {
-      const { marks, ...rest } = node
-      const kept = marks.filter((mark) => mark.type !== 'link')
-      next = kept.length ? { ...rest, marks: kept } : rest
-    }
-    const last = out[out.length - 1]
-    if (last?.type === 'text' && next?.type === 'text' && JSON.stringify(last.marks || []) === JSON.stringify(next.marks || [])) {
-      out[out.length - 1] = { ...last, text: last.text + next.text }
-    } else {
-      out.push(next)
-    }
-  }
-  return out
+  return asLinkLabels(source, fragment, value) || fragment
 }
 
 /**
@@ -540,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) {
@@ -626,7 +605,7 @@ function translateDataBlocks(doc, context, translations, fallbackToSource, model
         const data = node.attrs?.data
         if (data && typeof data === 'object') {
           visitDataBlockStrings(data, (value) => {
-            const translated = asDataString(value, lookupTranslation(value, context, translations, fallbackToSource))
+            const translated = lookupTranslation(value, context, translations, fallbackToSource)
             if (translated !== value) changed = true
             return translated
           }, modelFor(node.attrs?.tag))
@@ -640,18 +619,6 @@ function translateDataBlocks(doc, context, translations, fallbackToSource, model
   return changed
 }
 
-/**
- * ⭐ A data block's string written as TEXT takes its translation as text — the rule an element
- * with no link follows (`translatedInline`), for a string a component renders as it is: the markup a
- * translation carries for a link elsewhere is not this string's. ⛔ Until 2026-10-16 it was taken
- * as written, and a label shared with a link rendered as `[Sign in](/sign-in)`. A string written
- * with markdown keeps its translation as written.
- */
-function asDataString(source, translated) {
-  if (typeof translated !== 'string' || translated === source) return translated
-  return toPlainText(source) === source ? toPlainText(translated) : translated
-}
-
 /**
  * Resolve ONE ProseMirror content doc for a single target locale: a deep clone of
  * the source doc with each whole-element translated (inline content replaced from

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

@@ -239,17 +239,6 @@ export function contextKey(context) {
   return context?.key ?? `${context?.page}:${context?.section}`
 }
 
-/**
- * Wrap a `multiple: true` + `localized: true` field (e.g. page `keywords` — "array
- * of localized strings") into per-locale form by localizing each element. Container
- * shape is preserved so the round-trip is a fixed point: an array authored as an
- * array stays an array of `{ <lang>: value }` maps; a bare scalar (the degenerate
- * single-value authoring) wraps as one localized scalar. null/undefined → undefined.
- *
- * @param {*} value
- * @param {string} sourceLocale
- * @param {object} [translations] - `{ locale: { hash: tgt } }` from loadLocaleTranslations
- */
 /**
  * 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
@@ -274,6 +263,17 @@ export function plainTextTargets(value, sourceLocale) {
   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
+ * shape is preserved so the round-trip is a fixed point: an array authored as an
+ * array stays an array of `{ <lang>: value }` maps; a bare scalar (the degenerate
+ * single-value authoring) wraps as one localized scalar. null/undefined → undefined.
+ *
+ * @param {*} value
+ * @param {string} sourceLocale
+ * @param {object} [translations] - `{ locale: { hash: tgt } }` from loadLocaleTranslations
+ */
 export function localizeScalarList(value, sourceLocale, translations, context = null) {
   if (value == null) return undefined
   if (!Array.isArray(value)) return localizeScalar(value, sourceLocale, translations, context)

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'
@@ -216,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))
       }
     }
@@ -452,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

package/src/uwx/records.js

@@ -59,7 +59,8 @@ 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'
@@ -823,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 })
@@ -973,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.
@@ -1278,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.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
@@ -1055,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.

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) {