@uniweb/build 1.20.10 → 1.22.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -13,6 +13,8 @@
13
13
  * all: { sales: edit } # a team, or members, to read or edit
14
14
  * publicQueries: # what visitors who are not signed in may read
15
15
  * '@/vehicle': { whole: true, where: { status: { in: [available, pending] } } }
16
+ * integrations: # what a new backend starts connected to, by a mapping
17
+ * meta-catalog: { label: Meta catalog, mapping: '@/vehicle-to-meta', channel: feed, trigger: on_fetch, enabled: true }
16
18
  * ```
17
19
  *
18
20
  * ⭐ IT IS THE `backend` SERVICE'S, KEPT IN A FILE OF ITS OWN. A push sends it in that service's
@@ -24,7 +26,8 @@
24
26
  * full name for any other, as `data:` and `queries.yml` name types — and a push names each in full
25
27
  * by the rule every ref it sends follows (`qualifyRef`, with the scope `siteSelfScope` reads). The
26
28
  * backend never resolves an `@/x`. A pull writes `@/x` back, and keeps a name the file already
27
- * spells another way when it names the same type.
29
+ * spells another way when it names the same type. An integration's `mapping:` — one of the
30
+ * foundation's mappings (`src/mappings/`) — is named the same way; nothing in its `filter` is.
28
31
  *
29
32
  * ⭐ ITS SHAPE IS THE BACKEND'S, AND THE BACKEND CHECKS IT AT EVERY DOOR THAT WRITES THE ROW. The
30
33
  * checks here come earlier — a build, a push, `uniweb doctor`, offline — and refuse no more than
@@ -87,11 +90,22 @@ function stable(value) {
87
90
  export function blueprintForWire(blueprint, scope) {
88
91
  const out = {}
89
92
  for (const [key, value] of Object.entries(blueprint)) {
90
- out[key] = TYPE_KEYS.includes(key) && isMap(value) ? qualifiedTypes(key, value, scope) : value
93
+ if (TYPE_KEYS.includes(key) && isMap(value)) out[key] = qualifiedTypes(key, value, scope)
94
+ else if (key === 'integrations' && isMap(value)) out[key] = mappingsNamed(value, (m) => qualifyRef(m, scope))
95
+ else out[key] = value
91
96
  }
92
97
  return out
93
98
  }
94
99
 
100
+ /** Each integration line with its `mapping:` renamed by `rename`; nothing else in the line moves. */
101
+ function mappingsNamed(integrations, rename) {
102
+ return Object.fromEntries(
103
+ Object.entries(integrations).map(([id, line]) =>
104
+ isMap(line) && typeof line.mapping === 'string' ? [id, { ...line, mapping: rename(line.mapping) }] : [id, line]
105
+ )
106
+ )
107
+ }
108
+
95
109
  /**
96
110
  * Whether two blueprints, each as a `backend` row holds it (`blueprintForWire`), say the same: keys in
97
111
  * any order, lists in theirs. `undefined` and `null` are no blueprint, the same as each other and
@@ -137,6 +151,10 @@ function qualifiedTypes(key, map, scope) {
137
151
  export function blueprintFromWire(wire, { scope = null, own = null, local = null } = {}) {
138
152
  const out = {}
139
153
  for (const [key, value] of Object.entries(isMap(wire) ? wire : {})) {
154
+ if (key === 'integrations' && isMap(value)) {
155
+ out[key] = mappingsNamed(value, (m) => mappingAsFileSpells(m, local?.integrations, scope))
156
+ continue
157
+ }
140
158
  if (!TYPE_KEYS.includes(key) || !isMap(value)) {
141
159
  out[key] = value
142
160
  continue
@@ -149,6 +167,21 @@ export function blueprintFromWire(wire, { scope = null, own = null, local = null
149
167
  return out
150
168
  }
151
169
 
170
+ /**
171
+ * A mapping's full name → as a pull writes it: as the file already spells it when it names the same
172
+ * one, else `@/x` when it is in the site's foundation's scope. A foundation registers only its own
173
+ * mappings, so every mapping in that scope is the foundation's.
174
+ */
175
+ function mappingAsFileSpells(full, localIntegrations, scope) {
176
+ if (isMap(localIntegrations)) {
177
+ for (const line of Object.values(localIntegrations)) {
178
+ if (isMap(line) && typeof line.mapping === 'string' && qualifyRef(line.mapping, scope) === full) return line.mapping
179
+ }
180
+ }
181
+ const org = bareOrg(scope)
182
+ return org && full.startsWith(`@${org}/`) ? `@/${full.slice(org.length + 2)}` : full
183
+ }
184
+
152
185
  /** Each type a file's key names, in full → as the file spells it. */
153
186
  function spellingsOf(map, scope) {
154
187
  const out = new Map()
@@ -247,7 +280,7 @@ function saysTheSame(local, wire, scope) {
247
280
  * @param {object|null} blueprint - a checked blueprint (`refuseUnreadableBlueprint`)
248
281
  * @param {object} p
249
282
  * @param {string|null} p.scope - the scope the site's `@/x` resolve into
250
- * @param {{ types: Set<string>|null }} p.declared - what `siteDeclaredTypes` read
283
+ * @param {{ types: Set<string>|null, mappings?: Set<string>|null }} p.declared - what `siteDeclaredTypes` read
251
284
  * @param {boolean} [p.sending] - whether a push is about to send it
252
285
  * @returns {string[]}
253
286
  */
@@ -276,6 +309,24 @@ export function blueprintWarnings(blueprint, { scope, declared, sending = false
276
309
  }
277
310
  }
278
311
  }
312
+ for (const [id, line] of Object.entries(isMap(blueprint.integrations) ? blueprint.integrations : {})) {
313
+ const mapping = isMap(line) ? line.mapping : null
314
+ if (typeof mapping !== 'string') continue
315
+ const at = `integrations.${id}.mapping`
316
+ if (!scoped && mapping.startsWith('@/') && sending) {
317
+ out.push(
318
+ `${BLUEPRINT_FILE}: \`${at}\` is the foundation's own mapping, and the foundation has no scope yet, ` +
319
+ "so a push sends it as written — the backend never resolves an `@/x`. A foundation's scope is part " +
320
+ "of its name — `name: '@org/<name>'` in its main.js, which `uniweb register` writes."
321
+ )
322
+ }
323
+ if (declared?.mappings && !declared.mappings.has(qualifyRef(mapping, scope))) {
324
+ out.push(
325
+ `${BLUEPRINT_FILE}: \`${at}\` names a mapping none of this site's foundations declares, so a backend ` +
326
+ `started from this site leaves the line out. Check the name against the foundation's src/mappings/.`
327
+ )
328
+ }
329
+ }
279
330
  return out
280
331
  }
281
332
 
@@ -294,7 +345,7 @@ export function blueprintWarnings(blueprint, { scope, declared, sending = false
294
345
  */
295
346
  export async function siteBlueprintWarnings(siteRoot, { scope = null, foundationDir, siteYml, primary, sending = false } = {}) {
296
347
  const blueprint = readBlueprint(siteRoot)
297
- if (!isMap(blueprint) || !TYPE_KEYS.some((key) => isMap(blueprint[key]) && Object.keys(blueprint[key]).length)) return []
348
+ if (!isMap(blueprint) || ![...TYPE_KEYS, 'integrations'].some((key) => isMap(blueprint[key]) && Object.keys(blueprint[key]).length)) return []
298
349
  const yml = siteYml ?? readSiteYml(siteRoot)
299
350
  const declared = await siteDeclaredTypes(siteRoot, yml, { scope, foundationDir, primary })
300
351
  return blueprintWarnings(blueprint, { scope, declared, sending })
@@ -324,10 +375,12 @@ function readSiteYml(siteRoot) {
324
375
  * @param {string} [opts.foundationDir] - the site's foundation, when a push was handed its folder
325
376
  * @param {object|null} [opts.primary] - the site's foundation's schema, already read by the caller
326
377
  * (the static build's `foundationSections`)
327
- * @returns {Promise<{ types: Set<string>|null, unread: string[] }>}
378
+ * @returns {Promise<{ types: Set<string>|null, mappings: Set<string>|null, unread: string[] }>} `mappings`:
379
+ * the mappings they define, in full, null when `types` is
328
380
  */
329
381
  export async function siteDeclaredTypes(siteRoot, siteYml, { scope = null, foundationDir, primary } = {}) {
330
382
  const types = new Set()
383
+ const mappings = new Set()
331
384
  const unread = []
332
385
  const dir = foundationDir ? resolve(foundationDir) : localFoundationDir(siteRoot, siteYml)
333
386
  if (!dir) {
@@ -335,7 +388,10 @@ export async function siteDeclaredTypes(siteRoot, siteYml, { scope = null, found
335
388
  } else {
336
389
  const schema = primary !== undefined && !foundationDir ? primary : await foundationSchema(dir)
337
390
  if (!schema) unread.push('its foundation could not be read')
338
- else for (const ref of Object.keys(schema.dataSchemas || {})) types.add(qualifyRef(ref, scope))
391
+ else {
392
+ for (const ref of Object.keys(schema.dataSchemas || {})) types.add(qualifyRef(ref, scope))
393
+ for (const ref of Object.keys(schema._mappings || {})) mappings.add(qualifyRef(ref, scope))
394
+ }
339
395
  }
340
396
  for (const entry of Array.isArray(siteYml?.extensions) ? siteYml.extensions : []) {
341
397
  const declared = typeof entry === 'string' ? entry : isMap(entry) ? entry.url : null
@@ -358,8 +414,9 @@ export async function siteDeclaredTypes(siteRoot, siteYml, { scope = null, found
358
414
  }
359
415
  types.add(qualifyRef(ref, extScope))
360
416
  }
417
+ for (const ref of Object.keys(schema._mappings || {})) mappings.add(qualifyRef(ref, extScope))
361
418
  }
362
- return { types: unread.length ? null : types, unread }
419
+ return { types: unread.length ? null : types, mappings: unread.length ? null : mappings, unread }
363
420
  }
364
421
 
365
422
  /** The site's foundation's folder, when it is in the project — else null (a catalog ref, a URL). */
@@ -404,9 +404,11 @@ export function localizeScalar(value, sourceLocale, translations, context = null
404
404
  * @returns {string|undefined}
405
405
  */
406
406
  export function translationFor(entry, context) {
407
- if (typeof entry === 'string') return entry
407
+ if (typeof entry === 'string') return context?.placeOnly ? undefined : entry
408
408
  if (!entry || typeof entry !== 'object') return undefined
409
409
  const override = context ? entry.overrides?.[contextKey(context)] : undefined
410
+ // ⭐ On a page the site doesn't translate, only an override naming this place (`translationContext`).
411
+ if (context?.placeOnly) return typeof override === 'string' ? override : undefined
410
412
  return typeof override === 'string' ? override : typeof entry.default === 'string' ? entry.default : undefined
411
413
  }
412
414
 
@@ -495,6 +497,8 @@ export function createTranslationCollector(sourceLocale, { siteRoot = null, lang
495
497
  const kept = {} // { place: { '@'?, languages? } }, what `readKept` gives back
496
498
  const keptRead = new Set() // the places read, whether or not they keep anything
497
499
  const marks = { cleared: {}, outdated: {} } // what `addStructuralMap` was told of each row beyond its value
500
+ // The places read on a page the site doesn't translate, which only an override says (`translationContext`).
501
+ marks.placeOnly = new Set()
498
502
 
499
503
  function keepMeta(place, at) {
500
504
  keptRead.add(place)
@@ -528,6 +532,7 @@ export function createTranslationCollector(sourceLocale, { siteRoot = null, lang
528
532
  // says it.
529
533
  function add(localizedValue, context = null, { plainText = false } = {}) {
530
534
  if (!isLocalizedMap(localizedValue)) return
535
+ if (context?.placeOnly) marks.placeOnly.add(contextKey(context))
531
536
  const source = localizedValue[sourceLocale]
532
537
  if (typeof source !== 'string' || source.length === 0) return
533
538
  const hash = computeHash(source)
@@ -558,6 +563,7 @@ export function createTranslationCollector(sourceLocale, { siteRoot = null, lang
558
563
  function addStructuralMap(locale, map, context = null, checks = null, notes = null) {
559
564
  if (locale === sourceLocale || !map || typeof map !== 'object' || Array.isArray(map) || !has(locale)) return
560
565
  const place = context ? contextKey(context) : ''
566
+ if (context?.placeOnly) marks.placeOnly.add(place)
561
567
  for (const [src, row] of Object.entries(notes?.cleared || {})) {
562
568
  ;((marks.cleared[locale] ||= {})[computeHash(src)] ||= {})[place] = row
563
569
  }
@@ -908,18 +914,22 @@ class SeenInContexts {
908
914
  // ⛔ Until 2026-10-17 values agreed only when spelled alike, and a pull rewrote an entry that says the
909
915
  // same thing another way: `[Faire un don](/contact)` to its label, a string a heading and a link
910
916
  // share into per-place overrides, a page title's `[Se connecter](/sign-in)` to its words.
911
- function reconcileTranslation(existing, seen, check = null) {
917
+ // ⭐ A PLACE ON A PAGE THE SITE DOESN'T TRANSLATE (`placeOnly`) IS SAID BY ITS OWN OVERRIDE ALONE, as a
918
+ // build and a push read it (`translationContext`): it never takes the default, nor decides it. So what an
919
+ // author translated there in the app comes back as an override for that place, and reaches no other.
920
+ function reconcileTranslation(existing, seen, check = null, placeOnly = null) {
912
921
  const own = existing && typeof existing === 'object' && existing.overrides && typeof existing.overrides === 'object' ? existing.overrides : {}
913
922
  const authoredDefault = typeof existing === 'string' ? existing : existing && typeof existing === 'object' ? existing.default : undefined
923
+ const only = (k) => k !== null && !!placeOnly?.has(k)
914
924
  // Each place read: its context's key (null where it has none), what it read, and what says that.
915
925
  const places = [
916
926
  ...(seen.plain !== undefined ? [[null, seen.plain, check?.plain ?? saysAsIs(seen.plain)]] : []),
917
927
  ...Object.entries(seen.values).map(([k, v]) => [k, v, check?.values?.[k] ?? saysAsIs(v)]),
918
928
  ]
919
- const at = (k) => (k !== null && k in own ? own[k] : authoredDefault)
929
+ const at = (k) => (k !== null && k in own ? own[k] : only(k) ? undefined : authoredDefault)
920
930
  if (existing !== undefined && places.length && places.every(([k, , says]) => says(at(k)))) return existing
921
931
  // The places the default speaks for: those with no override of the author's own.
922
- const free = places.filter(([k]) => k === null || !(k in own))
932
+ const free = places.filter(([k]) => k === null || (!(k in own) && !only(k)))
923
933
  let def = authoredDefault
924
934
  if (free.length) {
925
935
  let most = -1
@@ -928,15 +938,16 @@ function reconcileTranslation(existing, seen, check = null) {
928
938
  if (agree > most) [def, most] = [candidate, agree]
929
939
  }
930
940
  } else if (def === undefined) {
931
- def = places.find(([k]) => k !== null)?.[1]
941
+ def = places.find(([k]) => k !== null && !only(k))?.[1]
932
942
  }
933
943
  const overrides = { ...own }
934
944
  for (const [k, read, says] of places) {
935
945
  if (k === null) continue
936
- if (says(def)) delete overrides[k]
946
+ if (!only(k) && says(def)) delete overrides[k]
937
947
  else if (!(k in own && says(own[k]))) overrides[k] = read
938
948
  }
939
- return Object.keys(overrides).length ? { default: def, overrides } : def
949
+ if (!Object.keys(overrides).length) return def
950
+ return def === undefined ? { overrides } : { default: def, overrides }
940
951
  }
941
952
 
942
953
  /**
@@ -1067,13 +1078,17 @@ function jsonObjectText(entries) {
1067
1078
  *
1068
1079
  * @returns {string|object|undefined} undefined: no entry
1069
1080
  */
1070
- function settleEntry(existing, seen, check, cleared, outdated) {
1081
+ function settleEntry(existing, seen, check, cleared, outdated, placeOnly = null) {
1071
1082
  let own = existing
1072
1083
  if (own && typeof own === 'object' && 'outdated' in own) {
1073
1084
  const { outdated: _flag, ...rest } = own
1074
1085
  own = rest
1075
1086
  }
1076
- const rows = Object.entries(cleared || {})
1087
+ // ⭐ A row on a page the site doesn't translate holds its source whatever the entry's default says
1088
+ // (`translationContext`), so clearing it ends only an override naming its place, below.
1089
+ const only = (place) => !!place && !!placeOnly?.has(place)
1090
+ const rows = Object.entries(cleared || {}).filter(([place]) => !only(place))
1091
+ const placeOnlyRows = Object.entries(cleared || {}).filter(([place]) => only(place))
1077
1092
  const places = rows.map(([place]) => place).filter(Boolean)
1078
1093
  const reads = seen instanceof SeenInContexts ? seen : seen === undefined ? new SeenInContexts() : new SeenInContexts(seen)
1079
1094
  // Whether the author's entry, pushed to these rows, gives them what they hold: their source. That is
@@ -1081,9 +1096,10 @@ function settleEntry(existing, seen, check, cleared, outdated) {
1081
1096
  const ownSaysThem = (value) => typeof value === 'string' && rows.every(([, row]) => row.says(value))
1082
1097
  let entry
1083
1098
  if (reads.plain !== undefined || Object.keys(reads.values).length > 0) {
1084
- entry = reconcileTranslation(own, reads, check)
1099
+ entry = reconcileTranslation(own, reads, check, placeOnly)
1085
1100
  const readsElsewhere = typeof entry === 'string' ? entry : entry?.default
1086
- if (places.length && !ownSaysThem(readsElsewhere)) {
1101
+ // With no default, a row holding its source is said already: nothing gives it a translation.
1102
+ if (places.length && readsElsewhere !== undefined && !ownSaysThem(readsElsewhere)) {
1087
1103
  const overrides = { ...(entry && typeof entry === 'object' ? entry.overrides : {}) }
1088
1104
  for (const [place, row] of rows) if (place) overrides[place] = row.markdown
1089
1105
  entry = { default: readsElsewhere, overrides }
@@ -1096,6 +1112,13 @@ function settleEntry(existing, seen, check, cleared, outdated) {
1096
1112
  const defaultStays = typeof own.default === 'string' && ownSaysThem(own.default)
1097
1113
  entry = defaultStays || Object.keys(rest).length ? { ...(defaultStays ? { default: own.default } : {}), ...(Object.keys(rest).length ? { overrides: rest } : {}) } : undefined
1098
1114
  }
1115
+ for (const [place, row] of placeOnlyRows) {
1116
+ const override = entry && typeof entry === 'object' ? entry.overrides?.[place] : undefined
1117
+ if (typeof override !== 'string' || row.says(override)) continue
1118
+ const { [place]: _cleared, ...overrides } = entry.overrides
1119
+ const { overrides: _all, ...rest } = entry
1120
+ entry = Object.keys(overrides).length ? { ...rest, overrides } : Object.keys(rest).length ? rest : undefined
1121
+ }
1099
1122
  if (entry === undefined) return undefined
1100
1123
  if (outdated && Object.keys(outdated).length) {
1101
1124
  entry = { ...(typeof entry === 'string' ? { default: entry } : entry), outdated }
@@ -1174,7 +1197,7 @@ export function writeLocaleTranslations(siteRoot, byLocale, subdir = '', says =
1174
1197
  for (const key of new Set([...Object.keys(read), ...Object.keys(cleared)])) {
1175
1198
  // Nothing to say of a row that holds its source where the file has no entry for it, and no place reads one.
1176
1199
  if (!(key in read) && !(key in existing)) continue
1177
- entries[key] = settleEntry(existing[key], read[key], says?.[locale]?.[key], cleared[key], outdated[key])
1200
+ entries[key] = settleEntry(existing[key], read[key], says?.[locale]?.[key], cleared[key], outdated[key], marks?.placeOnly)
1178
1201
  }
1179
1202
  const fresh = Object.keys(entries).filter((key) => !(key in existing) && entries[key] !== undefined).sort()
1180
1203
  const same = (key) => (entries[key] === undefined ? !(key in existing) : canonicalJson(existing[key]) === canonicalJson(entries[key]))
@@ -11,7 +11,9 @@
11
11
  * entities:
12
12
  * - model: "@uniweb/data-schema" # one per data schema this foundation DEFINES
13
13
  * …the §3 declaration (from data-schema.js's lowering)…
14
- * - model: "@uniweb/foundation-schema" # the foundation (info/schema/i18n/data-schemas)
14
+ * - model: "@uniweb/mapping-schema" # one per mapping this foundation defines (src/mappings/)
15
+ * name, label?, description?, rules: { model, keys_from?, …the rest as written }
16
+ * - model: "@uniweb/foundation-schema" # the foundation (info/schema/i18n/data-schemas/mappings)
15
17
  *
16
18
  * `buildSchemaOnlyPackage` (below) assembles the foundation-LESS variant — only
17
19
  * `@uniweb/data-schema` entities, no foundation-schema — for a schemas-only
@@ -34,6 +36,7 @@ import { checkFoundationName, checkRegistrationScope, splitFoundationName } from
34
36
 
35
37
  const FOUNDATION_SCHEMA = '@uniweb/foundation-schema'
36
38
  const DATA_SCHEMA = '@uniweb/data-schema'
39
+ const MAPPING_SCHEMA = '@uniweb/mapping-schema'
37
40
 
38
41
  // @uniweb/build's own version, for the exporter envelope when the caller supplies
39
42
  // none. Safe fallback if package.json isn't reachable (e.g. bundled contexts).
@@ -81,16 +84,22 @@ export function buildRegistryPackage({ schema, foundationDir, scope, exporter, e
81
84
  registrationScope(self.name, scope)
82
85
  )
83
86
 
87
+ const mappingEntities = buildMappingEntities(schema._mappings || {}, scoped)
88
+
84
89
  const foundationEntity = {
85
90
  model: FOUNDATION_SCHEMA,
86
91
  info: buildInfo(self, org, digest, runtime),
87
92
  schema: buildSchemaBlob(schema, org),
88
93
  i18n: { locales: loadI18nLocales(foundationDir) },
89
94
  'data-schemas': { refs: buildRefs(dataSchemas, scoped) },
95
+ ...(mappingEntities.length && {
96
+ mappings: { refs: mappingEntities.map((e) => ({ name: e.name })).sort((a, b) => a.name.localeCompare(b.name)) },
97
+ }),
90
98
  }
91
99
 
92
- // Data schemas first so the foundation's refs always resolve (§5 step 5).
93
- return wrapEntities([...dataSchemaEntities, foundationEntity], exporter, exportedAt)
100
+ // Data schemas, then mappings, then the foundation: a backend installs them in the order they
101
+ // arrive, and each names only what came before it or is already registered.
102
+ return wrapEntities([...dataSchemaEntities, ...mappingEntities, foundationEntity], exporter, exportedAt)
94
103
  }
95
104
 
96
105
  /**
@@ -167,6 +176,47 @@ function buildDataSchemaEntities(dataSchemas, scope) {
167
176
  return { entities: referencedFirst(entities), scoped, org }
168
177
  }
169
178
 
179
+ /**
180
+ * One `@uniweb/mapping-schema` entity per mapping the foundation defines (`schema._mappings`,
181
+ * `foundation/mappings.js`): its identity flat, as a data schema's is, and the rest of the file under
182
+ * `rules` — the envelope's `model:` names the exchange type, so the mapping's own `model:` cannot sit
183
+ * beside it. `rules.model` and `rules.keys_from` are named in full; nothing else in `rules` is
184
+ * touched, since a backend judges it. A mapping another one names in `keys_from` comes first.
185
+ *
186
+ * @param {Object<string, object>} mappings - `{ '@/<name>': declaration }`
187
+ * @param {(ref: string) => string} scoped - `@/x` → the registration scope's name
188
+ * @returns {object[]}
189
+ */
190
+ function buildMappingEntities(mappings, scoped) {
191
+ const entities = Object.entries(mappings)
192
+ .filter(([ref]) => ref.startsWith('@/'))
193
+ .sort(([a], [b]) => a.localeCompare(b))
194
+ .map(([ref, decl]) => {
195
+ const { label, description, ...rules } = decl
196
+ if (typeof rules.model === 'string') rules.model = scoped(rules.model)
197
+ if (typeof rules.keys_from === 'string') rules.keys_from = scoped(rules.keys_from)
198
+ return {
199
+ model: MAPPING_SCHEMA,
200
+ name: scoped(ref),
201
+ ...(label !== undefined && { label }),
202
+ ...(description !== undefined && { description }),
203
+ rules,
204
+ }
205
+ })
206
+ const byName = new Map(entities.map((e) => [e.name, e]))
207
+ const ordered = []
208
+ const state = new Set()
209
+ const visit = (entity) => {
210
+ if (state.has(entity.name)) return // done, or on the walk now — a cycle keeps the walk's order
211
+ state.add(entity.name)
212
+ const from = entity.rules.keys_from
213
+ if (from !== entity.name && byName.has(from)) visit(byName.get(from))
214
+ ordered.push(entity)
215
+ }
216
+ for (const entity of entities) visit(entity)
217
+ return ordered
218
+ }
219
+
170
220
  /**
171
221
  * The data schemas in an order a backend can install one at a time: a schema another one in
172
222
  * the package references comes BEFORE it — alphabetical otherwise, so the order is stable.
@@ -258,7 +308,7 @@ function buildInfo(self, org, digest, runtime) {
258
308
  }
259
309
 
260
310
  // The foundation schema an editor reads: the whole renderable schema.json MINUS identity
261
- // and MINUS dataSchemas, shipped as one object the backend stores and serves, and never
311
+ // and MINUS dataSchemas and _mappings (each registered as its own entity), shipped as one object the backend stores and serves, and never
262
312
  // reads into (custodian).
263
313
  //
264
314
  // ⭐ IN ITS NORMALIZED FORM — `schemaFormat: 3` (`@uniweb/schemas/foundation`, ruled
@@ -271,7 +321,7 @@ function buildInfo(self, org, digest, runtime) {
271
321
  // It throws for a `data:` value that cannot be normalized — an inline field map that is
272
322
  // not a valid data schema — naming the component and the key; the build warns of it first.
273
323
  function buildSchemaBlob(schema, org) {
274
- const { dataSchemas: _ds, ...rest } = schema
324
+ const { dataSchemas: _ds, _mappings: _m, ...rest } = schema
275
325
  // Every key hoisted into `info` is stripped here, so the wire carries each
276
326
  // fact ONCE. Two copies of one fact is a drift liability, and the copy inside
277
327
  // an opaque blob is the one nobody would think to update.
@@ -57,7 +57,7 @@ import { buildRouteOf } from './site.js'
57
57
  import { ATOMIC_PARENT, knownMode } from './route-mode.js'
58
58
  import { fileLinkTargets } from '../site/file-links.js'
59
59
  import { DEFAULT_SECTION_TYPE } from '@uniweb/core/section-type'
60
- import { translationContext, SITE_META_CONTEXT } from '../i18n/extract.js'
60
+ import { translationContext, pageMetaContext, SITE_META_CONTEXT } from '../i18n/extract.js'
61
61
  import { authorableDeclaration, DECLARATION_KEYS } from '../site/fetch-shapes.js'
62
62
  import { createTranslationCollector, writeLocaleTranslations, writeFreeformTranslations, writeKept, unwrapLocalizedContent, isProseMirrorDoc } from './locale-sync.js'
63
63
  import { unwritableNodes } from '@uniweb/content-writer'
@@ -663,7 +663,7 @@ export function pageSectionsToFiles({ pageDir, pageSections, ctx, pageContext })
663
663
  freeformRelPath,
664
664
  freeformCandidates,
665
665
  writeId: fileSectionName(filePath) !== stableId,
666
- context: pageContext ? translationContext({ stableId }, pageContext.route) : null,
666
+ context: pageContext ? translationContext({ stableId }, pageContext.route, ctx?.exclude) : null,
667
667
  media: ctx?.media ?? null,
668
668
  sameFile: ctx?.sameFile ?? null,
669
669
  fileLinks: ctx?.fileLinks ?? null,
@@ -1138,7 +1138,7 @@ function writeMdPage({ record, place, route, ctx, report, pageContext, sourceLoc
1138
1138
  freeformRelPath: buildFreeformPath({ stableId }, pageContext),
1139
1139
  freeformCandidates: freeformPathsFor({ stableId }, pageContext),
1140
1140
  writeId: stableId !== name,
1141
- context: translationContext({ stableId }, pageContext.route),
1141
+ context: translationContext({ stableId }, pageContext.route, ctx?.exclude),
1142
1142
  media: ctx?.media ?? null,
1143
1143
  sameFile: ctx?.sameFile ?? null,
1144
1144
  fileLinks: ctx?.fileLinks ?? null,
@@ -1220,7 +1220,7 @@ function writePagesTree(pages, pagesDir, sourceLocale, report, ctx, routePrefix
1220
1220
  // source value goes inline into page.yml below (pageRecordToYml unwraps it). In the page's
1221
1221
  // context, as the build translates them (`<route>:_meta`), so an override for one page comes back.
1222
1222
  // Each a plain-text field: the push sends a translation's words (`site.js::localizePageMeta`).
1223
- const meta = { page: canon, section: '_meta' }
1223
+ const meta = pageMetaContext(canon, ctx.exclude)
1224
1224
  const text = { plainText: true }
1225
1225
  ctx.collector?.add(record.title, meta, text)
1226
1226
  ctx.collector?.add(record.label, meta, text)
@@ -2047,6 +2047,8 @@ export function siteContentDocumentToProject({ document, siteRoot, backend = nul
2047
2047
  const mountRoutes = followMountRoutes({ siteRoot, siteYml, pagesDir, document, backend, sourceLocale, prune, report })
2048
2048
  siteYml = mountRoutes.siteYml
2049
2049
  ctx.heldMounts = mountRoutes.held
2050
+ // The branches the site doesn't translate: a translation read there comes back for its place alone (`translationContext`).
2051
+ ctx.exclude = siteYml?.i18n?.exclude ?? null
2050
2052
  // A writable mount stays one under its new name.
2051
2053
  const writable = (writableMounts || []).map((segment) => mountRoutes.renamed.get(segment) ?? segment)
2052
2054
  // ⭐ WHERE EACH PAGE IS KEPT — found in the files by the build's rules (`page-files.js`), so a page
package/src/uwx/site.js CHANGED
@@ -82,7 +82,8 @@ import { carrySectionFile, rewriteFileLinks } from '../site/file-links.js'
82
82
  import { refuseBinding, refuseUnder, refuseOutsideLanguage, warnDuplicateBindings } from '../site/data-fetcher.js'
83
83
  import { readLayoutFolder, layoutAreaRoute } from '../site/layout-folder.js'
84
84
  import { normalizeHideIn } from '../site/nav-visibility.js'
85
- import { siteDefaultSectionType } from '../site/queries-config.js'
85
+ import { siteDefaultSectionType, foundationSchemaJson } from '../site/queries-config.js'
86
+ import { noteParamsNamedForContent } from '../site/params-named-for-content.js'
86
87
  import { resolveDefaultLocale, validateLanguageConfig, queryDataUrl } from '@uniweb/core'
87
88
  import { emitEntitySyncPackage } from './entity-document.js'
88
89
  import { locateSectionMedia, siteTree } from './located-media.js'
@@ -92,7 +93,7 @@ import { readKept, restoreKept, contextKey, loadLocaleTranslations, localizeScal
92
93
  import { unwrapLocalized } from './backfill.js'
93
94
  import { loadFreeformTranslation } from '../i18n/freeform.js'
94
95
  import { resolveLocaleList } from '../i18n/locales.js'
95
- import { translationContext, SITE_META_CONTEXT, blockElements, elementText } from '../i18n/extract.js'
96
+ import { translationContext, pageMetaContext, SITE_META_CONTEXT, blockElements, elementText } from '../i18n/extract.js'
96
97
  import { documentSourceLocale } from './source-locale.js'
97
98
  import { splitOpenGraph, openGraphValue, seoBesideOpenGraph } from './open-graph.js'
98
99
  import { isAuthoredPreview } from './authored-preview.js'
@@ -215,21 +216,22 @@ export function buildRouteOf(record, parentRoute, sourceLocale) {
215
216
  // either a STRUCTURAL map (from locales/{locale}.json, via localizeContentDoc) or,
216
217
  // when a FREE-FORM override file exists for that section+locale, the full body
217
218
  // (loadFreeformTranslation) — the override wins. Async because the free-form read
218
- // hits the filesystem.
219
- async function localizeContentTree(pages, layoutSections, sourceLocale, targetLocales, translations, siteRoot) {
219
+ // hits the filesystem. A page in a branch `exclude` names (the site's `i18n.exclude`) takes only a
220
+ // translation written for its place, as the build gives it (`translationContext`).
221
+ async function localizeContentTree(pages, layoutSections, sourceLocale, targetLocales, translations, siteRoot, exclude = null) {
220
222
  const freeformBase = localesDir(siteRoot)
221
223
  // What a pull kept for this push to send back (`readKept`).
222
224
  const kept = readKept(siteRoot)
223
225
  // What each section type declares its data blocks are, so a block is pushed as the build translates it.
224
226
  const dataModel = await dataBlockModels(siteRoot)
225
227
 
226
- const localizeSection = async (record, page) => {
228
+ const localizeSection = async (record, page, exclude = null) => {
227
229
  if (!record.content) return
228
230
  const stableId = record.stable_id || record.$id
229
231
  // Resolved in the section's context, as the build resolves it (`translationContext`): a
230
232
  // context-specific override applies here and nowhere else. ⛔ Until 2026-09-26 every section was
231
233
  // resolved with none, so an override never reached a backend.
232
- const context = translationContext({ stableId }, page?.route)
234
+ const context = translationContext({ stableId }, page?.route, exclude)
233
235
  let localized = localizeContentDoc(record.content, sourceLocale, targetLocales, translations, context, (tag) => dataModel(record.type, tag))
234
236
  const freeform = new Set()
235
237
  if (page) {
@@ -250,7 +252,7 @@ async function localizeContentTree(pages, layoutSections, sourceLocale, targetLo
250
252
 
251
253
  const visitSections = async (sections, page) => {
252
254
  for (const s of sections || []) {
253
- await localizeSection(s, page)
255
+ await localizeSection(s, page, exclude)
254
256
  if (Array.isArray(s.$children)) await visitSections(s.$children, page)
255
257
  }
256
258
  }
@@ -261,7 +263,7 @@ async function localizeContentTree(pages, layoutSections, sourceLocale, targetLo
261
263
  for (const p of pgs || []) {
262
264
  const route = buildRouteOf(p, parentRoute, sourceLocale)
263
265
  const page = { route, id: p.stable_id }
264
- localizePageMeta(p, route, sourceLocale, translations)
266
+ localizePageMeta(p, route, sourceLocale, translations, exclude)
265
267
  if (Array.isArray(p.page_sections)) await visitSections(p.page_sections, page)
266
268
  if (Array.isArray(p.$children)) await visitPages(p.$children, route)
267
269
  }
@@ -315,8 +317,8 @@ export function documentRows(doc, sourceLocale = documentSourceLocale(doc), only
315
317
  // override never reached a backend — nor, until the same day, an entry's default.
316
318
  // ⭐ Each is a plain-text slot, so a translation reaches it as text, as the build renders it
317
319
  // (`plainTextTargets`).
318
- function localizePageMeta(page, route, sourceLocale, translations) {
319
- const context = { page: route, section: '_meta' }
320
+ function localizePageMeta(page, route, sourceLocale, translations, exclude = null) {
321
+ const context = pageMetaContext(route, exclude)
320
322
  const again = (value) =>
321
323
  value && typeof value === 'object' && typeof value[sourceLocale] === 'string'
322
324
  ? plainTextTargets(localizeScalar(value[sourceLocale], sourceLocale, translations, context), sourceLocale)
@@ -604,9 +606,34 @@ function sectionToRecord(section, index) {
604
606
  async function readSectionFile(filePath, id, siteRoot, stableId, media) {
605
607
  const read = await processMarkdownFile(filePath, id, siteRoot, stableId)
606
608
  locateSectionMedia(read.assetCollection, { siteRoot, filePath, sink: media })
609
+ await noteSectionParams(read.section, filePath, siteRoot)
607
610
  return read
608
611
  }
609
612
 
613
+ // The site's foundation's section types, read once per site in a process: its built or registered
614
+ // `schema.json` (`foundationSchemaJson`), never its source, whose read reports the foundation's own
615
+ // `meta.js` — a push of the site is not the time for that.
616
+ const sectionTypesOfSite = new Map()
617
+ function sectionTypesOf(siteRoot) {
618
+ if (!sectionTypesOfSite.has(siteRoot)) {
619
+ const read = readYamlFile(join(siteRoot, 'site.yml'))
620
+ .then((yml) => foundationSchemaJson(siteRoot, yml))
621
+ .catch(() => null)
622
+ sectionTypesOfSite.set(siteRoot, read)
623
+ }
624
+ return sectionTypesOfSite.get(siteRoot)
625
+ }
626
+
627
+ // ⭐ What a section's frontmatter names like a field of its content, said on a push as the build says
628
+ // it (`../site/params-named-for-content.js`): a `title:` there is a param, never the section's title.
629
+ async function noteSectionParams(section, filePath, siteRoot) {
630
+ if (!section) return
631
+ noteParamsNamedForContent(section.params, section.type, await sectionTypesOf(siteRoot), {
632
+ file: filePath,
633
+ warn: (message) => console.warn(`[push] ${relative(siteRoot, filePath)}: ${message}`),
634
+ })
635
+ }
636
+
610
637
  // Resolve a section's logical name (`hero`, `card-a`) to its file in `mdFiles`, in the
611
638
  // normal build's order (`content-collector.js::findSectionFile`): `name.md`, then
612
639
  // `@name.md`, then the first file whose name is `name` once its `@` and `N-` prefixes
@@ -810,6 +837,7 @@ async function folderModePageRecords(ctx, dirPath, orderConfig, isRoot) {
810
837
  const filePath = join(dirPath, file)
811
838
  const { page, pageConfig, assetCollection } = await processFileAsPage(filePath, file, siteRoot, '/')
812
839
  locateSectionMedia(assetCollection, { siteRoot, filePath, sink: ctx.media })
840
+ await noteSectionParams(page.sections?.[0], filePath, siteRoot)
813
841
  const config = { ...pageConfig, title: page.title }
814
842
  if (page.hidden) config.hidden = true
815
843
  const data = buildPageData(config, {
@@ -1751,7 +1779,7 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
1751
1779
  // language count. Guarding this on `targetLocales.length` is what used to send
1752
1780
  // a bare doc from single-locale sites — see localizeContentDoc for why one
1753
1781
  // field with two shapes is a store that cannot validate its own declaration.
1754
- await localizeContentTree(pages, layoutSections, sourceLocale, targetLocales, translations, siteRoot)
1782
+ await localizeContentTree(pages, layoutSections, sourceLocale, targetLocales, translations, siteRoot, siteYml.i18n?.exclude)
1755
1783
 
1756
1784
  // ⭐ A link to a page is stored by the page's id where it has one (`page-refs.js`), so it
1757
1785
  // survives a rename in an editor, and a pull writes it back as the path a file shows.
@@ -85,7 +85,9 @@ export async function validateDataInputs({ siteRoot, foundationPath }) {
85
85
  if (!foundationPath) throw new Error('validateDataInputs: foundationPath is required')
86
86
 
87
87
  const srcDir = resolveFoundationSrcPath(foundationPath)
88
- const foundation = await buildSchema(srcDir)
88
+ // Not strict: validating a site's records reads its foundation's declarations, and warns of one
89
+ // the foundation's build stops on rather than refusing the site (`buildSchema`'s `strict`).
90
+ const foundation = await buildSchema(srcDir, undefined, null, { strict: false })
89
91
  const dataSchemas = foundation.dataSchemas || {}
90
92
  // The type each data key names — a records folder named for a typed key holds records of
91
93
  // that type when no data schema has its name (`uwx/data-key-types.js`).
@@ -602,8 +602,15 @@ export function foundationDevPlugin(options = {}) {
602
602
  if (reason) {
603
603
  console.log(`[foundation] ${reason}, regenerating entry...`)
604
604
  const entryPath = join(resolvedSrcDir, entryFileName)
605
- await generateEntryPoint(resolvedSrcDir, entryPath, { sectionPaths })
606
- server.ws.send({ type: 'full-reload' })
605
+ try {
606
+ await generateEntryPoint(resolvedSrcDir, entryPath, { sectionPaths })
607
+ server.ws.send({ type: 'full-reload' })
608
+ } catch (err) {
609
+ // The last good entry stays, and the page shows why: a `meta.js` that does not load, or a
610
+ // declaration the build cannot use, stops the build (schema.js), and the dev server lives on.
611
+ console.warn('[foundation] Failed to regenerate the entry:', err.message)
612
+ server.ws.send({ type: 'error', err: { message: err.message, stack: '' } })
613
+ }
607
614
  }
608
615
  },
609
616
  }