@uniweb/build 1.3.6 → 1.3.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "1.3.6",
+  "version": "1.3.8",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -59,9 +59,9 @@
     "@uniweb/content-reader": "~1.4.0",
     "@uniweb/content-writer": "~1.1.2",
     "@uniweb/projections": "~1.1.1",
-    "@uniweb/theming": "~1.2.0",
-    "@uniweb/schemas": "~1.3.0",
-    "@uniweb/semantic-parser": "~1.8.1"
+    "@uniweb/schemas": "~1.3.1",
+    "@uniweb/semantic-parser": "~1.8.1",
+    "@uniweb/theming": "~1.2.0"
   },
   "optionalDependencies": {
     "@uniweb/runtime": "~1.1.4"
@@ -73,8 +73,8 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
     "vite-plugin-svgr": "^4.0.0",
-    "@uniweb/runtime": "~1.1.4",
-    "@uniweb/core": "~1.2.2"
+    "@uniweb/core": "~1.2.2",
+    "@uniweb/runtime": "~1.1.4"
   },
   "peerDependenciesMeta": {
     "vite": {

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/site/entity-pool.js

@@ -53,8 +53,7 @@
 // there is no population to carry): a leftover `entities/` beside `records/` would
 // otherwise hold records nothing reads, silently.
 
-import { readdir } from 'node:fs/promises'
-import { existsSync, readFileSync, statSync } from 'node:fs'
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
 import { join, extname, basename, resolve } from 'node:path'
 import yaml from 'js-yaml'
 import { YAML_OPTIONS } from '../utils/yaml-schema.js'
@@ -263,6 +262,17 @@ export function poolPathReadings(dirs) {
  *   leaves the backend's folder alone for a site with no records directory.
  */
 export async function readEntityPool(siteRoot, opts = {}) {
+  return readEntityPoolSync(siteRoot, opts)
+}
+
+/**
+ * `readEntityPool`, for a caller that cannot wait — the pull's projection, which asks what a
+ * `folder.yml` already says (`records-project.js`). One walk, which the async form returns.
+ *
+ * @param {string} siteRoot
+ * @param {object} [opts] - as `readEntityPool`'s
+ */
+export function readEntityPoolSync(siteRoot, opts = {}) {
   let rel
   if (opts.dir) {
     rel = String(opts.dir).replace(/\/+$/, '')
@@ -280,10 +290,10 @@ export async function readEntityPool(siteRoot, opts = {}) {
   // A file record is named by its stem, so two files of one stem cannot both be one.
   const fileStems = new Map()
 
-  const walk = async (dir, dirs) => {
+  const walk = (dir, dirs) => {
     let listing
     try {
-      listing = await readdir(dir, { withFileTypes: true })
+      listing = readdirSync(dir, { withFileTypes: true })
     } catch {
       return
     }
@@ -304,7 +314,7 @@ export async function readEntityPool(siteRoot, opts = {}) {
           )
           continue
         }
-        await walk(full, [...dirs, e.name])
+        walk(full, [...dirs, e.name])
         continue
       }
       if (!e.isFile()) continue
@@ -356,7 +366,7 @@ export async function readEntityPool(siteRoot, opts = {}) {
     }
   }
 
-  await walk(base, [])
+  walk(base, [])
   return { entities, errors, exists: true, dir: rel }
 }
 

package/src/uwx/backfill.js

@@ -296,7 +296,13 @@ export function renderEntityDocument({ document, declaration, format, sourceLoca
   if (document?.$disabled === true) record.draft = true
 
   if (format === 'json') return JSON.stringify(record, null, 2) + '\n'
-  if (format === 'md') return `---\n${yaml.dump(record)}---\n${dec.body}`
+  if (format === 'md') {
+    // ⭐ Written as a section is (`project-writer.js::assembleSection`): a blank line after the front
+    // matter, and a final newline. ⛔ Until 2026-10-17 it had neither, so a pull that rewrote an
+    // edited record took both out of the author's file.
+    const body = String(dec.body ?? '').replace(/^(?:[ \t]*\n)+/, '').replace(/\s+$/, '')
+    return `---\n${yaml.dump(record)}---\n${body ? `\n${body}\n` : ''}`
+  }
   return yaml.dump(record) // yaml / yaml
 }
 

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/project-writer.js

@@ -418,14 +418,16 @@ function restates(authored, decl) {
  * (`records/`, or wherever `site.yml::paths.records` puts it), as a LIST.
  *
  * ⛔ A FULL WRITE, NOT A MERGE, and that is the one place this differs from every
- * other projected config. The file mirrors the folder's sub-folders: concrete refs
- * on both sides, nothing to invert, so a pull is a mirror rather than an update.
- * There is also nothing a shallow merge could mean here — the file is a sequence,
- * and merging two lists either duplicates entries or silently drops them.
+ * other projected config: the file is a sequence, and merging two lists either
+ * duplicates entries or silently drops them.
  *
- * The caller decides whether there is anything to write: a folder with no
- * sub-folders is no file at all (`folderToFolderYml` removes it), since missing and
- * empty mean the same. ⚠️ *Until 2026-09-21 this said an empty file was destructive
+ * The caller decides whether there is anything to write: a file that already says
+ * what the pulled folder says — its patterns included — is left alone
+ * (`records-project.js::organizesAlike`), and a folder with no sub-folders is no file
+ * at all (`folderToFolderYml` removes it), since missing and empty mean the same.
+ * ⛔ *Until 2026-10-17 this called the file a mirror — "concrete refs on both sides,
+ * nothing to invert" — and every pull wrote the folder's paths over a developer's
+ * patterns.* ⚠️ *Until 2026-09-21 this said an empty file was destructive
  * on the next push; that stopped being true when the directory, not this file,
  * became what decides which records the folder holds.*
  *

package/src/uwx/records-project.js

@@ -43,10 +43,12 @@ import { parseFrontmatter } from './entity-source.js'
 import { writeRecordFile, writeQueriesConfig, writeRecordsConfig } from './project-writer.js'
 import { foundationDataSchemas, foundationSchemaJson, QUERIES_YML_RELPATH } from './queries-config.js'
 import { dataKeyTypes } from './data-key-types.js'
-import { poolDirsForSchema, schemaForPoolDirs, resolveRecordsDir } from '../site/entity-pool.js'
-import { folderYmlPath } from '../site/records-config.js'
+import { poolDirsForSchema, schemaForPoolDirs, resolveRecordsDir, readEntityPoolSync } from '../site/entity-pool.js'
+import { folderYmlPath, resolveFolder } from '../site/records-config.js'
+import { canonicalJson } from './same-content.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 +218,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 +454,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
@@ -500,9 +502,14 @@ export function declarationsToQueriesYml({ document, siteRoot, scope, ...rest })
  * Project a pulled `@uniweb/folder` document back to `folder.yml` in the records
  * directory (`records/folder.yml`, or under `site.yml::paths.records`).
  *
- * ⭐ THE FOLDER ROUND-TRIPS TRIVIALLY, and that is by design rather than luck:
- * `folder.yml` holds concrete paths on both sides, so there is nothing to invert.
- * The old shape put QUERY MACROS in the folder — a virtual `folders:` tree naming
+ * ⭐ A FILE THAT SAYS WHAT THE PULLED FOLDER SAYS IS LEFT AS WRITTEN — its patterns
+ * (`member/*.md`), its comments, its order (`organizesAlike`). Otherwise the folder
+ * is written as the paths the backend's folder places, which is what it says.
+ * ⛔ *This read "the folder round-trips trivially: `folder.yml` holds concrete paths
+ * on both sides, so there is nothing to invert" until 2026-10-17 — read as "the file
+ * holds no patterns", which it does — and every pull with a folder wrote its paths
+ * over the developer's patterns: a record added afterwards fell outside them.* The
+ * old shape put QUERY MACROS in the folder — a virtual `folders:` tree naming
  * collections — and inverting a macro is not possible in general. Taking queries
  * out of the folder is what dissolved that.
  *
@@ -599,6 +606,16 @@ export function folderToFolderYml({ folderDoc, siteRoot, poolPathByUuid, sourceL
 
   const entries = walk(folderDoc.contents, false)
   if (unplaceable) return { status: 'skipped', entries: [], warnings, file }
+  if (existsSync(abs) && organizesAlike({ abs, entries, siteRoot, poolPathByUuid })) {
+    return { status: 'unchanged', entries, warnings, file }
+  }
+  // Said when it replaces a developer's pattern: a record they add from here is placed by nothing.
+  if (existsSync(abs) && holdsPattern(abs)) {
+    warnings.push(
+      `${file}: the folder no longer places its records as its patterns say, so it was written as their ` +
+        `paths. A record you add from here sits at the top of the folder until ${file} places it.`
+    )
+  }
   if (entries.length === 0) {
     if (!existsSync(abs)) return { status: 'unchanged', entries, warnings, file }
     unlinkSync(abs)
@@ -607,6 +624,67 @@ export function folderToFolderYml({ folderDoc, siteRoot, poolPathByUuid, sourceL
   return { status: writeRecordsConfig(siteRoot, entries), entries, warnings, file }
 }
 
+/**
+ * Does the `folder.yml` on disk say what the pulled folder says — read by the rule a push reads it
+ * by (`resolveFolder`), over the records directory as this pull left it?
+ *
+ * ⭐ About the records the backend's folder holds, every word: the folders, by name, label and tags,
+ * in order; and each record's folder, its tags and label, and its place among the others. Records
+ * the backend does not hold yet — a file the developer added and has not pushed — are theirs, so a
+ * pattern placing one is not a difference; nor is a folder holding only those. So `member/*.md` is
+ * kept while it places exactly the members the backend's folder has there, and goes on placing the
+ * next one the developer adds.
+ *
+ * @returns {boolean}
+ */
+function organizesAlike({ abs, entries, siteRoot, poolPathByUuid }) {
+  let authored
+  try {
+    authored = yaml.load(readFileSync(abs, 'utf8'), YAML_OPTIONS)
+  } catch {
+    return false
+  }
+  if (!Array.isArray(authored)) return false
+  const pool = readEntityPoolSync(siteRoot).entities
+  const pulled = new Set(poolPathByUuid.values())
+  const held = new Set(pool.filter((e) => pulled.has(e.poolPath)).map((e) => e.id))
+  const mine = resolveFolder(authored, pool)
+  const theirs = resolveFolder(entries, pool)
+  if (mine.errors.length || theirs.errors.length) return false
+  const theirFolders = new Set()
+  const said = (n) => ({ ...(n.label != null ? { label: n.label } : {}), ...(n.tags ? { tags: n.tags } : {}) })
+  // A tree as it reads for the held records. `keep(path, holds)` decides whether a folder stays.
+  const shape = (nodes, at, keep) =>
+    (nodes || []).flatMap((n) => {
+      if (n.kind === 'ref') return held.has(n.$entityId) ? [{ record: n.$entityId, ...said(n) }] : []
+      if (n.kind !== 'branch') return []
+      const path = [...at, n.name]
+      const records = shape(n.$children, path, keep)
+      return keep(path.join('/'), records.length > 0) ? [{ folder: n.name, ...said(n), records }] : []
+    })
+  // Every folder the backend has stays, empty or not; one of the file's stays when it holds a held
+  // record or the backend has it too — else it is the developer's, not pushed yet.
+  const theirShape = shape(theirs.nodes, [], (path) => (theirFolders.add(path), true))
+  const myShape = shape(mine.nodes, [], (path, holds) => holds || theirFolders.has(path))
+  return canonicalJson(myShape) === canonicalJson(theirShape)
+}
+
+// Does the `folder.yml` on disk place records by a pattern (`member/*.md`) anywhere?
+function holdsPattern(abs) {
+  let authored
+  try {
+    authored = yaml.load(readFileSync(abs, 'utf8'), YAML_OPTIONS)
+  } catch {
+    return false
+  }
+  const has = (entries) =>
+    (Array.isArray(entries) ? entries : []).some((entry) => {
+      const path = typeof entry === 'string' ? entry : entry?.path
+      return (typeof path === 'string' && /[*?]/.test(path)) || has(entry?.records)
+    })
+  return has(authored)
+}
+
 /**
  * Project a pulled folder + its record entities to `records/**` files.
  *

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