@uniweb/build 1.20.10 → 1.21.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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@uniweb/build",
3
- "version": "1.20.10",
3
+ "version": "1.21.0",
4
4
  "description": "Build tooling for the Uniweb Component Web Platform",
5
5
  "type": "module",
6
6
  "exports": {
@@ -58,14 +58,14 @@
58
58
  "sharp": "^0.35.5",
59
59
  "yaml": "^2.5.0",
60
60
  "@uniweb/content-reader": "~1.5.9",
61
- "@uniweb/projections": "~1.2.16",
62
- "@uniweb/schemas": "~1.7.1",
63
- "@uniweb/semantic-parser": "~1.13.3",
64
61
  "@uniweb/content-writer": "~1.3.1",
65
- "@uniweb/theming": "~1.3.2"
62
+ "@uniweb/semantic-parser": "~1.13.3",
63
+ "@uniweb/schemas": "~1.7.1",
64
+ "@uniweb/theming": "~1.3.2",
65
+ "@uniweb/projections": "~1.2.17"
66
66
  },
67
67
  "optionalDependencies": {
68
- "@uniweb/runtime": "~1.5.9"
68
+ "@uniweb/runtime": "~1.6.0"
69
69
  },
70
70
  "peerDependencies": {
71
71
  "vite": "^5.0.0 || ^6.0.0 || ^7.0.0",
@@ -75,7 +75,7 @@
75
75
  "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
76
76
  "vite-plugin-svgr": "^4.0.0",
77
77
  "@uniweb/core": "~1.6.12",
78
- "@uniweb/runtime": "~1.5.9"
78
+ "@uniweb/runtime": "~1.6.0"
79
79
  },
80
80
  "peerDependenciesMeta": {
81
81
  "vite": {
@@ -0,0 +1,149 @@
1
+ /**
2
+ * A foundation's mappings — `src/mappings/<name>.yml`, one per file: how a vendor's file translates
3
+ * to and from one of the foundation's types (a catalog CSV ⇄ `@/vehicle`, a lead's XML ⇄ `@/lead`).
4
+ *
5
+ * ```yaml
6
+ * # src/mappings/vehicle-to-meta.yml
7
+ * label: Meta catalog
8
+ * model: '@/vehicle' # the type, named as a data schema names one
9
+ * direction: out
10
+ * shape: list
11
+ * format: { type: csv }
12
+ * key: id
13
+ * keys_from: '@/dms-inventory' # optional: another mapping
14
+ * fields:
15
+ * - { title: listing.title }
16
+ * ```
17
+ *
18
+ * ⭐ THE FOLDER IS THE DECLARATION, as `schemas/` is for data schemas (`ownSchemaFiles`): a file is
19
+ * a mapping by being there, its name is the file's, a name with a leading `_` is left out, and
20
+ * `.js .json .yml .yaml` all count.
21
+ *
22
+ * ⭐ THE BACKEND JUDGES THE RULES. A mapping is registered with its foundation (`registry-package.js`,
23
+ * `@uniweb/mapping-schema`) and a backend checks it there. The build refuses only what can't be
24
+ * registered at all, so the author learns of it at the build and not at `register`:
25
+ *
26
+ * - a file that is not a map, or a `label`/`description` that is not text;
27
+ * - a `model` that is missing or names no type, or an `@/x` the foundation doesn't define;
28
+ * - a `keys_from` that names no mapping, or an `@/x` that isn't one of the foundation's.
29
+ *
30
+ * Mappings are editor-time only: they ride in `schema.json` as `_mappings` and never reach a page.
31
+ *
32
+ * @module
33
+ */
34
+
35
+ import { existsSync, readdirSync } from 'node:fs'
36
+ import { readFile } from 'node:fs/promises'
37
+ import { join, extname, basename } from 'node:path'
38
+ import { pathToFileURL } from 'node:url'
39
+ import yaml from 'js-yaml'
40
+ import { SCHEMA_EXTENSIONS, parseSchemaRef } from '@uniweb/schemas/format'
41
+ import { YAML_OPTIONS } from '../utils/yaml-schema.js'
42
+
43
+ /** The folder, under a foundation's source root. */
44
+ export const MAPPINGS_DIR = 'mappings'
45
+
46
+ const isMap = (v) => v !== null && typeof v === 'object' && !Array.isArray(v)
47
+
48
+ /**
49
+ * The mapping files a foundation defines, by name, sorted.
50
+ *
51
+ * @param {string} srcDir - the foundation's source root
52
+ * @returns {{ name: string, file: string }[]}
53
+ */
54
+ export function ownMappingFiles(srcDir) {
55
+ const dir = join(srcDir, MAPPINGS_DIR)
56
+ if (!existsSync(dir)) return []
57
+ return readdirSync(dir)
58
+ .sort()
59
+ .filter((file) => SCHEMA_EXTENSIONS.includes(extname(file)) && !file.startsWith('_'))
60
+ .map((file) => ({ name: basename(file, extname(file)), file: join(dir, file) }))
61
+ }
62
+
63
+ async function loadMappingFile(file) {
64
+ if (file.endsWith('.js')) return (await import(pathToFileURL(file).href)).default
65
+ const text = await readFile(file, 'utf8')
66
+ return file.endsWith('.json') ? JSON.parse(text) : yaml.load(text, YAML_OPTIONS)
67
+ }
68
+
69
+ /**
70
+ * Read and check every mapping a foundation defines.
71
+ *
72
+ * @param {string} srcDir - the foundation's source root
73
+ * @param {object} [opts]
74
+ * @param {Iterable<string>} [opts.ownTypes] - the `@/x` data schemas the foundation defines
75
+ * @returns {Promise<Object<string, object>>} `{ '@/<name>': declaration }` as written (`@/x` unqualified)
76
+ * @throws {Error} naming every mapping that cannot be registered, and why
77
+ */
78
+ export async function buildMappingMap(srcDir, { ownTypes = [] } = {}) {
79
+ const files = ownMappingFiles(srcDir)
80
+ if (!files.length) return {}
81
+ const types = new Set(ownTypes)
82
+ const names = new Set(files.map(({ name }) => `@/${name}`))
83
+ const map = {}
84
+ const found = []
85
+ for (const { name, file } of files) {
86
+ const at = `src/${MAPPINGS_DIR}/${basename(file)}`
87
+ let decl
88
+ try {
89
+ decl = await loadMappingFile(file)
90
+ } catch (err) {
91
+ found.push(`${at}: ${String(err?.message || err).split('\n')[0]}`)
92
+ continue
93
+ }
94
+ const problems = mappingProblems(decl, { types, names })
95
+ if (problems.length) found.push(...problems.map((p) => `${at}: ${p}`))
96
+ else map[`@/${name}`] = decl
97
+ }
98
+ if (found.length) {
99
+ throw new Error(
100
+ found.length === 1
101
+ ? `[uniweb] ${found[0]}`
102
+ : `[uniweb] mappings that cannot be registered:\n${found.map((f) => ` - ${f}`).join('\n')}`
103
+ )
104
+ }
105
+ return map
106
+ }
107
+
108
+ /**
109
+ * What stops one mapping from registering — `[]` when nothing does.
110
+ *
111
+ * @param {*} decl - the file, as read
112
+ * @param {{ types: Set<string>, names: Set<string> }} own - the foundation's `@/x` types and mappings
113
+ * @returns {string[]}
114
+ */
115
+ export function mappingProblems(decl, { types, names }) {
116
+ if (!isMap(decl)) return ['a mapping is a map — `model:`, `direction:`, `fields:` and the rest.']
117
+ const found = []
118
+ for (const key of ['label', 'description']) {
119
+ if (key in decl && (typeof decl[key] !== 'string' || !decl[key].trim())) {
120
+ found.push(`\`${key}\` is text.`)
121
+ }
122
+ }
123
+ if (!('model' in decl)) {
124
+ found.push("`model` is missing: name the type the mapping translates, `model: '@/vehicle'`.")
125
+ } else {
126
+ const problem = refProblem('model', decl.model, 'type')
127
+ if (problem) found.push(problem)
128
+ else if (decl.model.startsWith('@/') && !types.has(decl.model)) {
129
+ found.push(`\`model\` is \`${decl.model}\`, which is not one of the foundation's types (src/schemas/).`)
130
+ }
131
+ }
132
+ if ('keys_from' in decl) {
133
+ const problem = refProblem('keys_from', decl.keys_from, 'mapping')
134
+ if (problem) found.push(problem)
135
+ else if (decl.keys_from.startsWith('@/') && !names.has(decl.keys_from)) {
136
+ found.push(`\`keys_from\` is \`${decl.keys_from}\`, which is not one of the foundation's mappings (src/${MAPPINGS_DIR}/).`)
137
+ }
138
+ }
139
+ return found
140
+ }
141
+
142
+ function refProblem(key, ref, what) {
143
+ try {
144
+ parseSchemaRef(ref)
145
+ return null
146
+ } catch {
147
+ return `\`${key}\` names no ${what}: one of the foundation's own is \`'@/<name>'\`, any other is named in full, \`'@scope/<name>'\`.`
148
+ }
149
+ }
@@ -9,6 +9,7 @@ import { resolveDefaultLocale } from '@uniweb/core'
9
9
  import { computeHash, stripInlineTags } from './hash.js'
10
10
  import { visitDataBlockStrings } from './data-strings.js'
11
11
  import { serializeInlineContent } from '@uniweb/content-writer'
12
+ import { isInExcludedBranch } from '@uniweb/projections'
12
13
 
13
14
  /**
14
15
  * Extract all translatable units from site content
@@ -22,11 +23,19 @@ import { serializeInlineContent } from '@uniweb/content-writer'
22
23
  export function extractTranslatableContent(siteContent, { dataModel = null } = {}) {
23
24
  const units = {}
24
25
 
26
+ // ⭐ `i18n.exclude` — branches the site doesn't translate, such as a mounted repo's docs it shows in
27
+ // their own language: their pages give no strings, so `init`, `status` and the rest, which read the
28
+ // manifest, leave them alone. Routes as `agents.exclude` takes them (`isInExcludedBranch`). Their
29
+ // pages show the source in every language, but for a string the site translates elsewhere, since a
30
+ // translation is the text's wherever it appears.
31
+ const exclude = siteContent.config?.i18n?.exclude
32
+
25
33
  // The site's own Open Graph title and description (`site.yml` `seo:`), in the site's context.
26
34
  extractFromSiteMeta(siteContent.config, units)
27
35
 
28
36
  for (const page of siteContent.pages || []) {
29
37
  const pageRoute = page.route || '/'
38
+ if (isInExcludedBranch(pageRoute, exclude)) continue
30
39
 
31
40
  // Extract page metadata (title, description, keywords from page.yml)
32
41
  extractFromPageMeta(page, pageRoute, units)
@@ -38,7 +47,7 @@ export function extractTranslatableContent(siteContent, { dataModel = null } = {
38
47
  }
39
48
 
40
49
  // Extract from 404 page (stored as top-level notFound)
41
- if (siteContent.notFound) {
50
+ if (siteContent.notFound && !isInExcludedBranch(siteContent.notFound.route || '/404', exclude)) {
42
51
  const notFoundPage = siteContent.notFound
43
52
  const pageRoute = notFoundPage.route || '/404'
44
53
  extractFromPageMeta(notFoundPage, pageRoute, units)
package/src/i18n/index.js CHANGED
@@ -256,6 +256,21 @@ export async function extractRecordManifest(siteRoot, options = {}) {
256
256
  * @param {Object} options - Options
257
257
  * @returns {Object} Status per locale
258
258
  */
259
+ /**
260
+ * A language's words for a text, from its entry: the string, or an entry's `default`; an entry
261
+ * that gives only context-specific `overrides` gives words too. '' for none.
262
+ *
263
+ * @param {*} entry
264
+ * @returns {string}
265
+ */
266
+ function entryWords(entry) {
267
+ if (typeof entry === 'string') return entry
268
+ if (!entry || typeof entry !== 'object') return ''
269
+ if (typeof entry.default === 'string' && entry.default.trim()) return entry.default
270
+ const overrides = entry.overrides && typeof entry.overrides === 'object' ? Object.values(entry.overrides) : []
271
+ return overrides.find((value) => typeof value === 'string' && value.trim()) || ''
272
+ }
273
+
259
274
  export async function getTranslationStatus(siteRoot, options = {}) {
260
275
  const {
261
276
  localesDir = DEFAULTS.localesDir,
@@ -296,16 +311,22 @@ export async function getTranslationStatus(siteRoot, options = {}) {
296
311
  let translated = 0
297
312
  let missing = 0
298
313
  let outdated = 0
314
+ let unchanged = 0
299
315
 
300
- for (const hash of Object.keys(manifest.units)) {
316
+ for (const [hash, unit] of Object.entries(manifest.units)) {
301
317
  // An entry flagged `outdated` still renders, and is not this text's translation.
302
318
  if (Object.keys(standingFlags(translations[hash], translations, locale, kept)).length) {
303
319
  outdated++
304
- } else if (translatedHashes.has(hash)) {
305
- translated++
306
- } else {
307
- missing++
320
+ continue
308
321
  }
322
+ const words = translatedHashes.has(hash) ? entryWords(translations[hash]) : null
323
+ // ⭐ An empty entry is none: the build shows the source for it. And an entry that is the
324
+ // source's own text is what `uniweb i18n init` writes, so it is counted apart, not as a
325
+ // translation, whether the language says it the same way or nobody has translated it yet.
326
+ // ⛔ Until 2026-11-11 any entry counted, so a file `init` had just made read as all done.
327
+ if (words === null || !words.trim()) missing++
328
+ else if (words === unit.source || words === unit.markup) unchanged++
329
+ else translated++
309
330
  }
310
331
 
311
332
  status[locale] = {
@@ -313,6 +334,7 @@ export async function getTranslationStatus(siteRoot, options = {}) {
313
334
  translated,
314
335
  missing,
315
336
  ...(outdated ? { outdated } : {}),
337
+ ...(unchanged ? { unchanged } : {}),
316
338
  coverage: totalUnits > 0 ? Math.round((translated / totalUnits) * 100) : 100
317
339
  }
318
340
  }
@@ -677,6 +699,9 @@ export function formatTranslationStatus(status) {
677
699
  if (info.outdated > 0) {
678
700
  lines.push(` ${info.outdated} outdated: the old translation still shows, and its source has changed`)
679
701
  }
702
+ if (info.unchanged > 0) {
703
+ lines.push(` ${info.unchanged} the same as the source: what \`uniweb i18n init\` wrote, or words that stay the same in ${locale}`)
704
+ }
680
705
  }
681
706
  }
682
707
 
package/src/prerender.js CHANGED
@@ -839,17 +839,21 @@ export function injectBuildData(html, siteContent, { splitContent = false, curre
839
839
  }
840
840
  }
841
841
 
842
+ // ⭐ Replacer functions, here and for the icons below: in a replacement string `$$`, `$&`, `` $` ``
843
+ // and `$'` are patterns, and this is the site's own text. ⛔ Until 2026-11-11 a page saying `$$x$$`
844
+ // embedded `$x$`, which the browser's render then drew. The shell this replaces escapes every `<`
845
+ // too (`jsonForScript`), so the first `</script>` after it is its own.
842
846
  const contentScript = `<script id="__SITE_CONTENT__" type="application/json">${jsonForScript(contentForJson)}</script>`
843
847
  if (result.includes('__SITE_CONTENT__')) {
844
848
  // Replace existing site content with updated version (includes expanded dynamic routes)
845
849
  result = result.replace(
846
850
  /<script[^>]*id="__SITE_CONTENT__"[^>]*>[\s\S]*?<\/script>/,
847
- contentScript
851
+ () => contentScript
848
852
  )
849
853
  } else {
850
854
  result = result.replace(
851
855
  '</head>',
852
- ` ${contentScript}\n </head>`
856
+ () => ` ${contentScript}\n </head>`
853
857
  )
854
858
  }
855
859
 
@@ -866,12 +870,12 @@ export function injectBuildData(html, siteContent, { splitContent = false, curre
866
870
  if (result.includes('__ICON_CACHE__')) {
867
871
  result = result.replace(
868
872
  /<script[^>]*id="__ICON_CACHE__"[^>]*>[\s\S]*?<\/script>/,
869
- iconScript
873
+ () => iconScript
870
874
  )
871
875
  } else {
872
876
  result = result.replace(
873
877
  '</head>',
874
- ` ${iconScript}\n </head>`
878
+ () => ` ${iconScript}\n </head>`
875
879
  )
876
880
  }
877
881
  }
package/src/schema.js CHANGED
@@ -23,6 +23,7 @@ import { normalizeData, schemaDeclarationOf } from '@uniweb/schemas/foundation'
23
23
  import { rootListSection } from '@uniweb/schemas/conform'
24
24
  import { SECTION_PARAMS, SECTION_KEYS, stickyDeclaration, underHeaderDeclaration, heightDeclaration } from '@uniweb/schemas/section'
25
25
  import { collectSchemaRefs, buildDataSchemaMap, ownSchemaRefs } from './resolve-data-schema.js'
26
+ import { buildMappingMap } from './foundation/mappings.js'
26
27
  import {
27
28
  composeSupports,
28
29
  deriveRecordsSupport,
@@ -1342,6 +1343,10 @@ export async function buildSchema(srcDir, sectionPaths, derivedSupports = null)
1342
1343
  { srcDir },
1343
1344
  )
1344
1345
 
1346
+ // The mappings it defines — every file in its `mappings/` folder (`foundation/mappings.js`),
1347
+ // registered beside its data schemas. Editor-time: `_mappings`, never on a page.
1348
+ const mappings = await buildMappingMap(srcDir, { ownTypes: ownSchemaRefs(srcDir) })
1349
+
1345
1350
  // Discover layouts from src/layouts/
1346
1351
  const layouts = await discoverLayoutsInPath(srcDir)
1347
1352
  // The layout a page that names none renders with — the entry gets the same answer
@@ -1423,6 +1428,7 @@ export async function buildSchema(srcDir, sectionPaths, derivedSupports = null)
1423
1428
  },
1424
1429
  // Layout metadata (full, for editor)
1425
1430
  ...(Object.keys(dataSchemas).length > 0 && { dataSchemas }),
1431
+ ...(Object.keys(mappings).length > 0 && { _mappings: mappings }),
1426
1432
  ...(Object.keys(layouts).length > 0 && { _layouts: layouts }),
1427
1433
  ...components,
1428
1434
  }
@@ -53,6 +53,7 @@ import { refuseUnreadableAddress } from './site-address.js'
53
53
  import { warnOutsideVocabulary } from './vocabulary-warnings.js'
54
54
  import { warnPlacementsNotOffered } from './placement-warnings.js'
55
55
  import { atomicPageConfig, isAtomicPageKey, warnPageKeysNamingParams } from './page-settings.js'
56
+ import { noteParamsNamedForContent } from './params-named-for-content.js'
56
57
  import { markdownToProseMirror } from '@uniweb/content-reader'
57
58
 
58
59
  /**
@@ -1307,8 +1308,12 @@ async function processMarkdownFile(filePath, id, siteRoot, defaultStableId = nul
1307
1308
  const warnHere = (message) => console.warn(`[content-collector] ${relative(siteRoot, filePath)}: ${message}`)
1308
1309
  const proseMirrorContent = markdownToProseMirror(markdown, { onWarning: warnHere })
1309
1310
  warnOutsideVocabulary(proseMirrorContent, warnHere)
1310
- warnPlacementsNotOffered(proseMirrorContent, type || null, sectionTypes, warnHere)
1311
- if (pageConfig) warnPageKeysNamingParams(pageConfig, type || null, sectionTypes, warnHere)
1311
+ // ⭐ The foundation's section types only for a file of the site being collected: the push reads its
1312
+ // files through this function too, after a collect of another site may have left that one's here.
1313
+ const typesHere = collectRoot === siteRoot ? sectionTypes : null
1314
+ warnPlacementsNotOffered(proseMirrorContent, type || null, typesHere, warnHere)
1315
+ if (pageConfig) warnPageKeysNamingParams(pageConfig, type || null, typesHere, warnHere)
1316
+ noteParamsNamedForContent({ ...params, ...props }, type || null, typesHere, { file: filePath, warn: warnHere })
1312
1317
 
1313
1318
  // `query: team` → `fetch: { query: team }`; a list, one config per name, each under
1314
1319
  // its own `as` — the one helper every level uses. Unrelated to a section type's
@@ -0,0 +1,82 @@
1
+ /**
2
+ * Say, with the file in hand, each param a section's frontmatter names like a field of its content —
3
+ * `title:`, `items:` — when its section type declares no param of that name.
4
+ *
5
+ * ⭐ A section's frontmatter reaches its component as `params`, and its body as `content`, and
6
+ * neither is copied into the other (`@uniweb/runtime`, `BlockRenderer.jsx`). So a `title:` in the
7
+ * frontmatter never titles the section: the title is the body's heading. ⛔ Until 2026-11-11 the
8
+ * runtime spread every param over `content` too, so a `title:` there replaced the heading, and a
9
+ * site written for that loses its title without a word — this is the word.
10
+ *
11
+ * A param its type declares is one its component reads, and is not said: the name is the
12
+ * developer's to choose. A type this foundation doesn't have, or a foundation not at hand, says
13
+ * nothing either. A note, never a failure, since the page renders. Said once per file and key in a
14
+ * process: `uniweb dev` collects the site again on every edit, and a push builds its document more
15
+ * than once.
16
+ */
17
+
18
+ /**
19
+ * The fields of a section's content its body gives: what the content parser returns
20
+ * (`@uniweb/semantic-parser`), less `raw`, which no author writes, and `data`, which a frontmatter
21
+ * refuses (`SECTION_KEYS`, `@uniweb/schemas/section`). `math` and `tables` arrive only when the body
22
+ * has one. `tests/params-named-for-content.test.js` holds it to the parser.
23
+ */
24
+ export const BODY_FIELDS = Object.freeze([
25
+ 'title', 'pretitle', 'subtitle', 'paragraphs', 'links', 'images', 'icons', 'videos', 'documents',
26
+ 'insets', 'media', 'lists', 'quotes', 'snippets', 'headings', 'items', 'sequence', 'math', 'tables',
27
+ ])
28
+
29
+ const FIELDS = new Set(BODY_FIELDS)
30
+
31
+ /** How the body gives each field of the headline, for the note to say. */
32
+ const HEADLINE = {
33
+ title: (v) => `its heading: write \`# ${v}\` at the top of the body`,
34
+ subtitle: (v) => `a heading straight after the title, one level smaller: \`## ${v}\``,
35
+ pretitle: (v) => `the label line above the title: \`#> ${v}\``,
36
+ }
37
+
38
+ const said = new Set()
39
+
40
+ /**
41
+ * The params a section's frontmatter names like a field of its content that its section type
42
+ * declares no param of, or `[]` when the type, or the foundation, is not at hand.
43
+ *
44
+ * @param {object} params - the section's params, as stored
45
+ * @param {string|null} type - the section's `type:`; with none, the foundation's `defaultSection`
46
+ * @param {Object|null} sectionTypes - the foundation's schema, each section type's entry by name
47
+ * @returns {{ key: string, type: string }[]}
48
+ */
49
+ export function paramsNamedForContent(params, type, sectionTypes) {
50
+ if (!params || typeof params !== 'object') return []
51
+ const name = type || sectionTypes?._self?.defaultSection || null
52
+ const entry = name && !name.startsWith('_') ? sectionTypes?.[name] : null
53
+ if (!entry || typeof entry !== 'object') return []
54
+ const declared = entry.params && typeof entry.params === 'object' ? entry.params : {}
55
+ return Object.keys(params)
56
+ .filter((key) => FIELDS.has(key) && !Object.prototype.hasOwnProperty.call(declared, key))
57
+ .map((key) => ({ key, type: name }))
58
+ }
59
+
60
+ /**
61
+ * Say each of `paramsNamedForContent`, once per file and key in this process.
62
+ *
63
+ * @param {object} params - the section's params, as stored
64
+ * @param {string|null} type - the section's `type:`
65
+ * @param {Object|null} sectionTypes - the foundation's schema, each section type's entry by name
66
+ * @param {{ file: string, warn: (message: string) => void }} where - the section's file, and how to
67
+ * print one message, prefixed with it
68
+ */
69
+ export function noteParamsNamedForContent(params, type, sectionTypes, { file, warn }) {
70
+ for (const { key, type: name } of paramsNamedForContent(params, type, sectionTypes)) {
71
+ const once = `${file}\u0000${key}`
72
+ if (said.has(once)) continue
73
+ said.add(once)
74
+ const value = params[key]
75
+ const shown = typeof value === 'string' && value.trim() && !value.includes('\n') ? value.trim() : '…'
76
+ const how = HEADLINE[key]
77
+ warn(
78
+ `\`${key}:\` is a param, and ${name} declares no \`${key}\` param, so it doesn't set the section's ` +
79
+ (how ? `${key} (\`content.${key}\`), which is ${how(shown)}.` : `\`content.${key}\`, which comes from the body.`)
80
+ )
81
+ }
82
+ }
@@ -245,6 +245,16 @@ import { refuseSearchOption } from './search-declared.js'
245
245
  import { mountDevApi } from '../dev/api-mount.js'
246
246
  import { mountDevSubmit } from '../dev/submit-mount.js'
247
247
 
248
+ /**
249
+ * The pre-paint appearance script for a shell, the runtime's own (`@uniweb/runtime/ssr`, which a
250
+ * prerendered page's seam writes too), or '' for a site with no dark scheme. Loaded once.
251
+ */
252
+ let bootScriptOf = null
253
+ async function appearanceBootScript(appearance) {
254
+ bootScriptOf ||= import('@uniweb/runtime/ssr').then((runtime) => runtime.renderAppearanceBootScript)
255
+ return (await bootScriptOf)(appearance)
256
+ }
257
+
248
258
  /**
249
259
  * Create the site content plugin
250
260
  *
@@ -1155,6 +1165,14 @@ export function siteContentPlugin(options = {}) {
1155
1165
  headInjection += ` <style id="uniweb-theme">\n${contentToInject.theme.css}\n </style>\n`
1156
1166
  }
1157
1167
 
1168
+ // ⭐ THE PRE-PAINT APPEARANCE SCRIPT, so a page the browser renders itself — every page under
1169
+ // `uniweb dev`, and a build that doesn't prerender — shows the site's look before the bundle
1170
+ // boots. A prerendered page keeps this one: its render adds none where the shell has it
1171
+ // (`injectPageContent`). ⛔ Until 2026-11-11 only a prerendered page had it, so a dark site
1172
+ // under `uniweb dev` painted light for about 0.4 s on every load.
1173
+ const bootScript = await appearanceBootScript(contentToInject.theme?.appearance)
1174
+ if (bootScript) headInjection += ` ${bootScript}\n`
1175
+
1158
1176
  // ⛔ No page's head tags — canonical, Open Graph, hreflang — go into the shell, which every
1159
1177
  // page is rendered into: the prerender writes each page's own (`injectPageContent`), and the
1160
1178
  // browser keeps them (`useHeadMeta`). Until 2026-10-25 the home page's were written here.
@@ -1196,7 +1214,8 @@ export function siteContentPlugin(options = {}) {
1196
1214
  if (!headInjection) return result
1197
1215
 
1198
1216
  // Insert before </head>
1199
- return result.replace('</head>', headInjection + ' </head>')
1217
+ // A replacer function: `$$` or `$&` in the content, the theme or head.html is text, not a pattern.
1218
+ return result.replace('</head>', () => headInjection + ' </head>')
1200
1219
  },
1201
1220
 
1202
1221
  async generateBundle() {
@@ -23,7 +23,7 @@ import { YAML_OPTIONS } from '../utils/yaml-schema.js'
23
23
  export const BLUEPRINT_FILE = 'blueprint.yml'
24
24
 
25
25
  /** What the file holds, in the order a pull writes it. */
26
- export const BLUEPRINT_KEYS = Object.freeze(['signup', 'teams', 'access', 'publicQueries'])
26
+ export const BLUEPRINT_KEYS = Object.freeze(['signup', 'teams', 'access', 'publicQueries', 'integrations'])
27
27
 
28
28
  /** The two keys whose entries are types. */
29
29
  export const TYPE_KEYS = Object.freeze(['access', 'publicQueries'])
@@ -34,6 +34,23 @@ const ACCESS_KEYS = Object.freeze(['add', 'all'])
34
34
  const QUERY_KEYS = Object.freeze(['whole', 'where', 'sort', 'limit'])
35
35
  const TEAM_KEYS = Object.freeze(['label'])
36
36
 
37
+ /**
38
+ * An integration line, as a backend takes it. Refused here exactly as a backend refuses them, and no
39
+ * more: a line this takes, a backend takes.
40
+ */
41
+ const INTEGRATION_KEYS = Object.freeze(['label', 'mapping', 'channel', 'trigger', 'filter', 'enabled'])
42
+ const CHANNELS = Object.freeze(['file', 'feed', 'email', 'http'])
43
+ const TRIGGERS = Object.freeze(['manual', 'on_fetch', 'on_create', 'on_match'])
44
+ /** Each channel → the triggers it pairs with. */
45
+ const PAIRS = Object.freeze({
46
+ file: ['manual'],
47
+ feed: ['on_fetch'],
48
+ email: ['on_create', 'on_match', 'manual'],
49
+ http: ['on_create', 'on_match', 'manual'],
50
+ })
51
+ /** The channels a line may switch on with `enabled: true`. */
52
+ const ENABLEABLE = Object.freeze(['file', 'feed'])
53
+
37
54
  /** In `all`, every member of the home org: the one name there that is not a team. */
38
55
  const MEMBERS = 'members'
39
56
 
@@ -133,6 +150,7 @@ export function blueprintProblems(blueprint) {
133
150
  if (teams !== undefined) found.push(...teamProblems(teams))
134
151
  if (blueprint.access !== undefined) found.push(...accessProblems(blueprint.access, teamIds))
135
152
  if (blueprint.publicQueries !== undefined) found.push(...publicQueryProblems(blueprint.publicQueries))
153
+ if (blueprint.integrations !== undefined) found.push(...integrationProblems(blueprint.integrations))
136
154
  return found
137
155
  }
138
156
 
@@ -269,6 +287,79 @@ function publicQueryProblems(queries) {
269
287
  return found
270
288
  }
271
289
 
290
+ function integrationProblems(integrations) {
291
+ if (!isMap(integrations)) {
292
+ return [
293
+ `\`integrations\` is a map of integrations by id — \`integrations: { meta-catalog: { mapping: '@/vehicle-to-meta', channel: feed, trigger: on_fetch } }\` — not ${described(integrations)}.`,
294
+ ]
295
+ }
296
+ const found = []
297
+ for (const [id, line] of Object.entries(integrations)) {
298
+ const at = `integrations.${id}`
299
+ if (!TEAM_ID.test(id)) {
300
+ found.push(`\`${at}\`: an integration's id is lowercase letters, digits and dashes — its name goes in its \`label\`.`)
301
+ continue
302
+ }
303
+ if (!isMap(line)) {
304
+ found.push(`\`${at}\` is a map of ${listed(INTEGRATION_KEYS)} — not ${described(line)}.`)
305
+ continue
306
+ }
307
+ for (const key of Object.keys(line)) {
308
+ if (!INTEGRATION_KEYS.includes(key)) {
309
+ found.push(
310
+ `\`${at}.${key}\` is not one of an integration's keys, which are ${listed(INTEGRATION_KEYS)}. ` +
311
+ 'An address, a URL or a key is the owner\'s to give in the admin app, never the file\'s.'
312
+ )
313
+ }
314
+ }
315
+ if ('label' in line && (typeof line.label !== 'string' || !line.label.trim())) {
316
+ found.push(`\`${at}.label\` is the integration's name — not ${described(line.label)}.`)
317
+ }
318
+ if (!('mapping' in line)) {
319
+ found.push(`\`${at}\` names no \`mapping\`: one of the foundation's own is \`mapping: '@/<name>'\`.`)
320
+ } else {
321
+ const name = refNameProblem(`${at}.mapping`, line.mapping, 'mapping')
322
+ if (name) found.push(name)
323
+ }
324
+ const channelOk = CHANNELS.includes(line.channel)
325
+ const triggerOk = TRIGGERS.includes(line.trigger)
326
+ if (!channelOk) found.push(`\`${at}.channel\` is one of ${listed(CHANNELS)} — not ${described(line.channel)}.`)
327
+ if (!triggerOk) found.push(`\`${at}.trigger\` is one of ${listed(TRIGGERS)} — not ${described(line.trigger)}.`)
328
+ if (channelOk && triggerOk && !PAIRS[line.channel].includes(line.trigger)) {
329
+ found.push(`\`${at}\`: a \`${line.channel}\` integration's trigger is one of ${listed(PAIRS[line.channel])} — not \`${line.trigger}\`.`)
330
+ }
331
+ if ('filter' in line && !isMap(line.filter)) {
332
+ found.push(`\`${at}.filter\` is a map — \`filter: { where: { status: sold } }\` — not ${described(line.filter)}.`)
333
+ }
334
+ if ('enabled' in line) {
335
+ if (line.enabled !== true) {
336
+ found.push(
337
+ typeof line.enabled === 'string' && SWITCH_WORDS.test(line.enabled.trim())
338
+ ? `\`${at}.enabled\` is the text \`${line.enabled}\` — YAML reads yes, no, on and off as words. Write \`enabled: true\`, or leave it out.`
339
+ : `\`${at}.enabled\` is \`true\`, or left out — not ${described(line.enabled)}.`
340
+ )
341
+ } else if (channelOk && !ENABLEABLE.includes(line.channel)) {
342
+ found.push(
343
+ `\`${at}.enabled\`: a \`${line.channel}\` integration is switched on by its owner in the admin app, ` +
344
+ 'once its address is given. Leave `enabled` out.'
345
+ )
346
+ }
347
+ }
348
+ }
349
+ return found
350
+ }
351
+
352
+ /** A name that must be `@/x` or `@scope/x`, or null. */
353
+ function refNameProblem(at, ref, what) {
354
+ try {
355
+ parseSchemaRef(ref)
356
+ return null
357
+ } catch {
358
+ const bare = String(ref).replace(/^@?\/?/, '')
359
+ return `\`${at}\` names no ${what}: one of the foundation's own is \`'@/${bare}'\`, and any other is named in full, \`'@scope/${bare}'\`.`
360
+ }
361
+ }
362
+
272
363
  /** A type's name is `@/x` or `@scope/x` (`parseSchemaRef`), or null. */
273
364
  function typeNameProblem(at, type) {
274
365
  try {
@@ -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). */
@@ -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.
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'
@@ -604,9 +605,34 @@ function sectionToRecord(section, index) {
604
605
  async function readSectionFile(filePath, id, siteRoot, stableId, media) {
605
606
  const read = await processMarkdownFile(filePath, id, siteRoot, stableId)
606
607
  locateSectionMedia(read.assetCollection, { siteRoot, filePath, sink: media })
608
+ await noteSectionParams(read.section, filePath, siteRoot)
607
609
  return read
608
610
  }
609
611
 
612
+ // The site's foundation's section types, read once per site in a process: its built or registered
613
+ // `schema.json` (`foundationSchemaJson`), never its source, whose read reports the foundation's own
614
+ // `meta.js` — a push of the site is not the time for that.
615
+ const sectionTypesOfSite = new Map()
616
+ function sectionTypesOf(siteRoot) {
617
+ if (!sectionTypesOfSite.has(siteRoot)) {
618
+ const read = readYamlFile(join(siteRoot, 'site.yml'))
619
+ .then((yml) => foundationSchemaJson(siteRoot, yml))
620
+ .catch(() => null)
621
+ sectionTypesOfSite.set(siteRoot, read)
622
+ }
623
+ return sectionTypesOfSite.get(siteRoot)
624
+ }
625
+
626
+ // ⭐ What a section's frontmatter names like a field of its content, said on a push as the build says
627
+ // it (`../site/params-named-for-content.js`): a `title:` there is a param, never the section's title.
628
+ async function noteSectionParams(section, filePath, siteRoot) {
629
+ if (!section) return
630
+ noteParamsNamedForContent(section.params, section.type, await sectionTypesOf(siteRoot), {
631
+ file: filePath,
632
+ warn: (message) => console.warn(`[push] ${relative(siteRoot, filePath)}: ${message}`),
633
+ })
634
+ }
635
+
610
636
  // Resolve a section's logical name (`hero`, `card-a`) to its file in `mdFiles`, in the
611
637
  // normal build's order (`content-collector.js::findSectionFile`): `name.md`, then
612
638
  // `@name.md`, then the first file whose name is `name` once its `@` and `N-` prefixes
@@ -810,6 +836,7 @@ async function folderModePageRecords(ctx, dirPath, orderConfig, isRoot) {
810
836
  const filePath = join(dirPath, file)
811
837
  const { page, pageConfig, assetCollection } = await processFileAsPage(filePath, file, siteRoot, '/')
812
838
  locateSectionMedia(assetCollection, { siteRoot, filePath, sink: ctx.media })
839
+ await noteSectionParams(page.sections?.[0], filePath, siteRoot)
813
840
  const config = { ...pageConfig, title: page.title }
814
841
  if (page.hidden) config.hidden = true
815
842
  const data = buildPageData(config, {