@uniweb/build 1.11.0 → 1.11.2

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.11.0",
3
+ "version": "1.11.2",
4
4
  "description": "Build tooling for the Uniweb Component Web Platform",
5
5
  "type": "module",
6
6
  "exports": {
@@ -56,10 +56,10 @@
56
56
  "js-yaml": "^4.3.2",
57
57
  "sharp": "^0.35.5",
58
58
  "yaml": "^2.5.0",
59
- "@uniweb/schemas": "~1.6.5",
60
- "@uniweb/content-reader": "~1.5.7",
61
59
  "@uniweb/theming": "~1.2.1",
60
+ "@uniweb/schemas": "~1.6.6",
62
61
  "@uniweb/semantic-parser": "~1.13.0",
62
+ "@uniweb/content-reader": "~1.5.7",
63
63
  "@uniweb/content-writer": "~1.3.1",
64
64
  "@uniweb/projections": "~1.2.7"
65
65
  },
@@ -73,8 +73,8 @@
73
73
  "@tailwindcss/vite": "^4.0.0",
74
74
  "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
75
75
  "vite-plugin-svgr": "^4.0.0",
76
- "@uniweb/core": "~1.4.12",
77
- "@uniweb/runtime": "~1.2.13"
76
+ "@uniweb/runtime": "~1.2.13",
77
+ "@uniweb/core": "~1.4.12"
78
78
  },
79
79
  "peerDependenciesMeta": {
80
80
  "vite": {
package/src/i18n/index.js CHANGED
@@ -12,7 +12,7 @@ import { existsSync } from 'node:fs'
12
12
  import { join, dirname } from 'node:path'
13
13
 
14
14
  import { computeHash, normalizeText } from './hash.js'
15
- import { availableLocales, resolveLocaleList } from './locales.js'
15
+ import { availableLocales, resolveLocaleList, localesToBuild } from './locales.js'
16
16
  import { extractTranslatableContent } from './extract.js'
17
17
  import { dataBlockModels } from './data-models.js'
18
18
  import { syncManifests, formatSyncReport } from './sync.js'
@@ -82,6 +82,7 @@ export {
82
82
  // Locale resolution
83
83
  getAvailableLocales,
84
84
  resolveLocales,
85
+ localesToBuild,
85
86
 
86
87
  // Free-form translation functions
87
88
  loadFreeformTranslation,
@@ -444,15 +445,21 @@ export async function buildLocalizedContent(siteRoot, options = {}) {
444
445
  // What each section type declares its data blocks are, so a block translates what extraction offered.
445
446
  const dataModel = await dataBlockModels(siteRoot)
446
447
 
448
+ // ⭐ Where the bundle put each file a page names, a translation's among them (`site/plugin.js::
449
+ // generateBundle`, `collectTranslatedAssets`): a language's page shows the build's copy of the
450
+ // file its translation names, as the default language's page does. The bundle's note to this
451
+ // step, taken out of the payload here, since no page reads it.
452
+ const builtAssets = siteContent.builtAssets
453
+ delete siteContent.builtAssets
454
+
447
455
  // ⭐ The DEFAULT locale's payload needs the same stamp. It is not written in
448
456
  // this loop — it is the source this function reads — but a visitor landing on
449
457
  // `/` gets a Website built from it, and without the set that page loses its
450
458
  // language switcher while every translated page has one.
451
459
  const stampedLanguages = declaredLanguages(siteContent.config, defaultLocale, locales)
452
- if (JSON.stringify(siteContent.config?.languages) !== JSON.stringify(stampedLanguages)) {
453
- siteContent.config = { ...siteContent.config, languages: stampedLanguages }
454
- await writeFile(siteContentPath, JSON.stringify(siteContent, null, 2))
455
- }
460
+ const restamp = JSON.stringify(siteContent.config?.languages) !== JSON.stringify(stampedLanguages)
461
+ if (restamp) siteContent.config = { ...siteContent.config, languages: stampedLanguages }
462
+ if (restamp || builtAssets) await writeFile(siteContentPath, JSON.stringify(siteContent, null, 2))
456
463
 
457
464
  // The paths the site's source holds a section at, drafts included — read once, and only
458
465
  // when a translation translates nothing this build publishes (`warnAboutFreeformIssues`).
@@ -513,6 +520,8 @@ export async function buildLocalizedContent(siteRoot, options = {}) {
513
520
  })
514
521
  }
515
522
 
523
+ if (builtAssets) translated = await builtCopies(translated, builtAssets)
524
+
516
525
  // Mark the active locale in the translated content, and stamp the resolved
517
526
  // locale set so the runtime does not have to re-derive it — see
518
527
  // `declaredLanguages`.
@@ -537,6 +546,16 @@ export async function buildLocalizedContent(siteRoot, options = {}) {
537
546
  return outputs
538
547
  }
539
548
 
549
+ /**
550
+ * A language's content with each file its translations name pointed at the build's copy
551
+ * (`builtAssets`, `{ paths, files }` by the reference as written). The bundle's own rewrite, loaded
552
+ * only on the lane that processed media, which is the one that left the note.
553
+ */
554
+ async function builtCopies(content, builtAssets) {
555
+ const { rewriteSiteContentPaths } = await import('../site/asset-processor.js')
556
+ return rewriteSiteContentPaths(content, builtAssets.paths || {}, builtAssets.files || null)
557
+ }
558
+
540
559
  /**
541
560
  * Check for stale/orphaned free-form translations and emit warnings
542
561
  * @param {string} locale - Locale code
@@ -6,10 +6,11 @@
6
6
  // which has none — was pushed as a one-language site, and none of its translations left the
7
7
  // machine, while the build of the same site produced every one of them.
8
8
  //
9
- // A leaf, with nothing but `node:fs` beneath it, so the sync lane can use it without pulling in
10
- // the rest of the i18n module.
9
+ // A leaf, with nothing but `node:fs` and core's locale rules (a leaf too) beneath it, so the sync
10
+ // lane can use it without pulling in the rest of the i18n module.
11
11
 
12
12
  import { existsSync, readdirSync } from 'node:fs'
13
+ import { normalizeLanguageList, resolveDefaultLocale } from '@uniweb/core/locale-config'
13
14
 
14
15
  // Files in the locales directory that are not a locale's translations.
15
16
  export const RESERVED_LOCALE_FILES = new Set(['manifest.json', '_memory.json'])
@@ -49,3 +50,28 @@ export function resolveLocaleList(configLocales, localesPath) {
49
50
  }
50
51
  return availableLocales(localesPath)
51
52
  }
53
+
54
+ /**
55
+ * The languages a build makes pages in besides its default: the site's locales
56
+ * (`resolveLocaleList`), only those `publishLanguages:` lists when it lists any, never the default,
57
+ * which is the root tree. One rule for `uniweb build`, which makes each one's pages, and for the
58
+ * bundle, which processes the files their translations name (`site/plugin.js`), so the second
59
+ * never processes for a language the first does not make, nor misses one it does.
60
+ *
61
+ * @param {Object} siteConfig - `site.yml`, as written
62
+ * @param {string} localesPath - the locales directory
63
+ * @returns {{ locales: string[], skipped: string[], defaultLocale: string }} the languages a build
64
+ * makes, and those `publishLanguages:` leaves out
65
+ */
66
+ export function localesToBuild(siteConfig, localesPath) {
67
+ const config = siteConfig || {}
68
+ let locales = resolveLocaleList(config.languages, localesPath)
69
+ let skipped = []
70
+ if (config.publishLanguages != null) {
71
+ const publish = new Set(normalizeLanguageList(config.publishLanguages))
72
+ skipped = locales.filter((l) => !publish.has(l))
73
+ locales = locales.filter((l) => publish.has(l))
74
+ }
75
+ const defaultLocale = resolveDefaultLocale(config)
76
+ return { locales: locales.filter((l) => l !== defaultLocale), skipped, defaultLocale }
77
+ }
package/src/prerender.js CHANGED
@@ -721,6 +721,9 @@ export function injectBuildData(html, siteContent, { splitContent = false, curre
721
721
  // Inject site content as JSON for hydration
722
722
  // Strip CSS and font links from theme (both are already in <head>)
723
723
  let contentForJson = { ...siteContent }
724
+ // The bundle's note to the step that makes each other language's pages, which takes it out
725
+ // (`i18n/index.js::buildLocalizedContent`) — and no page's, if that step failed.
726
+ delete contentForJson.builtAssets
724
727
  if (contentForJson.theme?.css || contentForJson.theme?.links) {
725
728
  contentForJson.theme = { ...contentForJson.theme }
726
729
  delete contentForJson.theme.css
@@ -40,7 +40,7 @@ import { existsSync, readdirSync, statSync } from 'node:fs'
40
40
  import { join, resolve, isAbsolute, extname, basename } from 'node:path'
41
41
  import { dataRefOf } from '@uniweb/core/data-keys'
42
42
  import { SYSTEM_RECORD_SCHEMAS } from '@uniweb/schemas/system'
43
- import { assertOptionsTargets } from './uwx/data-schema.js'
43
+ import { assertOptionsTargets, assertI18nPaths } from './uwx/data-schema.js'
44
44
  import { pathToFileURL } from 'node:url'
45
45
  import { createRequire } from 'node:module'
46
46
  import yaml from 'js-yaml'
@@ -321,7 +321,9 @@ export async function buildDataSchemaMap(refs, { srcDir }) {
321
321
  }
322
322
  // A picklist names a section of the Model holding its choices — refused here, at the author's
323
323
  // screen, when it names none (`optionsSectionPath`), rather than when the schema is registered.
324
+ // So does a translation whose path names no label of its schema (`assertI18nPaths`).
324
325
  assertOptionsTargets(map)
326
+ assertI18nPaths(map)
325
327
  return map
326
328
  }
327
329
 
@@ -480,3 +480,73 @@ export function mergeAssetCollections(...collections) {
480
480
 
481
481
  return merged
482
482
  }
483
+
484
+ /**
485
+ * The files each language's pages name that the site's own content does not: what its
486
+ * translations brought, such as an image's file in that language or a free-form section's media.
487
+ *
488
+ * ⭐ A TRANSLATION'S FILE GOES THROUGH THE IMAGE STEP, AS THE CONTENT'S DOES (2026-10-28). A
489
+ * translation names an image's file in its language as `![alt](/x)` (`i18n/merge.js::
490
+ * translatedImage`), and a language's pages are made after the build has processed the site's
491
+ * media, from what it wrote. So a translated page showed that file as `public/` holds it, a PNG
492
+ * where the default language's page had the build's WebP. The bundle collects them here, from each
493
+ * language's merged content, and processes them with the site's own (`site/plugin.js::
494
+ * generateBundle`); a language's pages take the address the build gave each one
495
+ * (`i18n/index.js::buildLocalizedContent`).
496
+ *
497
+ * Only a `/x` names a file here. A translation is written in no folder, so a `./x` it holds has
498
+ * nowhere to resolve from: it comes back in `unplaced`, to be said, never guessed.
499
+ *
500
+ * @param {Array<{ locale: string, content: Object }>} languages - each language's content: its
501
+ * translations merged into the site's content as collected (`mergeTranslations`)
502
+ * @param {Object} known - the site's own manifest, by reference as written (`siteContent.assets`)
503
+ * @param {string} siteRoot - Site root directory
504
+ * @param {string} localesDir - the translations' folder; a refusal names `<locale>.json` in it
505
+ * @returns {{ assets: Object, unplaced: Array<{ locale: string, ref: string }> }} a manifest of the
506
+ * files, in `collectSectionAssets`'s shape, and each reference no folder places
507
+ * @throws {Error} `code: ASSETS_FOLDER_RETIRED` — a `/x` that only `assets/` holds
508
+ */
509
+ export function collectTranslatedAssets(languages, known, siteRoot, localesDir) {
510
+ const assets = {}
511
+ const unplaced = []
512
+ for (const { locale, content } of languages) {
513
+ const table = join(localesDir, `${locale}.json`)
514
+ const seen = new Set()
515
+ const visit = (ref) => {
516
+ if (typeof ref !== 'string' || !ref || isExternalUrl(ref)) return
517
+ if (known?.[ref] || assets[ref] || seen.has(ref)) return
518
+ seen.add(ref)
519
+ if (!ref.startsWith('/')) {
520
+ unplaced.push({ locale, ref })
521
+ return
522
+ }
523
+ const result = resolveAssetPath(ref, table, siteRoot)
524
+ if (result.external || !result.resolved) return
525
+ assets[ref] = {
526
+ original: ref,
527
+ resolved: result.resolved,
528
+ isImage: result.isImage,
529
+ isVideo: result.isVideo,
530
+ isPdf: result.isPdf
531
+ }
532
+ }
533
+ eachSectionDoc(content, (doc) => {
534
+ walkContentAssets(doc, (node) => visit(node.attrs.src))
535
+ walkDataBlockAssets(doc, (path) => visit(path))
536
+ })
537
+ }
538
+ return { assets, unplaced }
539
+ }
540
+
541
+ /** Each section's content in a site's content, as `rewriteSiteContentPaths` walks it: pages, layout areas, subsections. */
542
+ function eachSectionDoc(siteContent, visit) {
543
+ const section = (s) => {
544
+ if (s?.content) visit(s.content)
545
+ s?.subsections?.forEach(section)
546
+ }
547
+ const page = (p) => p?.sections?.forEach(section)
548
+ siteContent?.pages?.forEach(page)
549
+ for (const areas of Object.values(siteContent?.layouts || {})) {
550
+ for (const area of Object.values(areas || {})) page(area)
551
+ }
552
+ }
@@ -33,6 +33,7 @@ import { resolveDefaultLocale, resolveFetchConfigs, DATA_DIR } from '@uniweb/cor
33
33
  import { partitionKnowledgePages, INDEX_FILENAME } from '@uniweb/projections'
34
34
  import { collectSiteContent, mountEntriesOf } from './content-collector.js'
35
35
  import { processAssets, rewriteSiteContentPaths } from './asset-processor.js'
36
+ import { collectTranslatedAssets } from './assets.js'
36
37
  import { processAdvancedAssets } from './advanced-processors.js'
37
38
  import { devMediaPaths } from './dev-media.js'
38
39
  import { processQueries, writeQueryFiles } from './query-processor.js'
@@ -238,6 +239,7 @@ async function processDevSectionFetches(sections, fetchOptions, resolve) {
238
239
  import { compiledData, recordProjections, routeOnDisk } from './record-projections.js'
239
240
  import { agentFiles, describeProjections, projectionFiles, searchFiles } from './projections.js'
240
241
  import { mergeTranslations } from '../i18n/merge.js'
242
+ import { localesToBuild } from '../i18n/locales.js'
241
243
  import { dataBlockModels, NO_DATA_MODELS } from '../i18n/data-models.js'
242
244
  import { refuseSearchOption } from './search-declared.js'
243
245
  import { mountDevApi } from '../dev/api-mount.js'
@@ -533,6 +535,34 @@ export function siteContentPlugin(options = {}) {
533
535
  })
534
536
  }
535
537
 
538
+ /**
539
+ * The files the languages this build makes pages in name and the site's own content does not
540
+ * (`collectTranslatedAssets`), each language's translations merged as its pages will be. The
541
+ * languages are `uniweb build`'s (`localesToBuild`), so a file is processed for exactly the pages
542
+ * that show it.
543
+ *
544
+ * @returns {Promise<{ assets: Object, languages: number }>} a manifest of those files, and how
545
+ * many languages the build makes besides its default
546
+ */
547
+ async function translatedAssets() {
548
+ const { readSiteConfig } = await import('./config.js')
549
+ const localesPath = join(resolvedSitePath, localesDir)
550
+ const { locales } = localesToBuild(readSiteConfig(resolvedSitePath), localesPath)
551
+ const languages = []
552
+ for (const locale of locales) {
553
+ const content = await getTranslatedContent(locale)
554
+ if (content) languages.push({ locale, content })
555
+ }
556
+ const { assets, unplaced } = collectTranslatedAssets(languages, siteContent.assets, resolvedSitePath, localesPath)
557
+ for (const { locale, ref } of unplaced) {
558
+ console.warn(
559
+ `[site-content] A ${locale} translation names ${ref}, and a translation sits in no folder for ` +
560
+ `a relative path to start from. Name the file from public/, as /<its path there>.`
561
+ )
562
+ }
563
+ return { assets, languages: locales.length }
564
+ }
565
+
536
566
  /**
537
567
  * The site's content in `locale`, as a page in that language gets it — or null when the site has
538
568
  * no translation for it (`getTranslatedContent`).
@@ -1156,13 +1186,18 @@ export function siteContentPlugin(options = {}) {
1156
1186
 
1157
1187
  // Process assets in production builds
1158
1188
  if (isProduction && assetsOptions.process && siteContent?.assets) {
1159
- const assetCount = Object.keys(siteContent.assets).length
1189
+ // ⭐ With the files a translation names (`translatedAssets`): one step for both, so a
1190
+ // translated page shows the build's copy of its file as the default language's page does.
1191
+ const translated = await translatedAssets()
1192
+ const fromTranslations = Object.keys(translated.assets).length
1193
+ const manifest = { ...siteContent.assets, ...translated.assets }
1194
+ const assetCount = Object.keys(manifest).length
1160
1195
 
1161
1196
  if (assetCount > 0) {
1162
1197
  console.log(`[site-content] Processing ${assetCount} assets...`)
1163
1198
 
1164
1199
  // Process standard assets (images)
1165
- const { pathMapping, results, files } = await processAssets(siteContent.assets, {
1200
+ const { pathMapping, results, files } = await processAssets(manifest, {
1166
1201
  outputDir: resolvedOutDir,
1167
1202
  assetsSubdir: assetsOptions.outputDir,
1168
1203
  convertToWebp: assetsOptions.convertToWebp,
@@ -1202,9 +1237,14 @@ export function siteContentPlugin(options = {}) {
1202
1237
  finalContent = rewriteSiteContentPaths(siteContent, pathMapping, files)
1203
1238
  }
1204
1239
 
1240
+ // Where the build put each file, for the step that makes each other language's pages from
1241
+ // this payload, and takes it out (`i18n/index.js::buildLocalizedContent`).
1242
+ if (translated.languages > 0) finalContent.builtAssets = { paths: pathMapping, files }
1243
+
1205
1244
  // Log results
1206
1245
  const sizeKB = (results.totalSize / 1024).toFixed(1)
1207
1246
  console.log(`[site-content] Processed ${results.processed} assets (${results.converted} converted to WebP, ${sizeKB}KB total)`)
1247
+ if (fromTranslations > 0) console.log(`[site-content] ${fromTranslations} of them named by a translation`)
1208
1248
 
1209
1249
  if (results.failed > 0) {
1210
1250
  console.warn(`[site-content] ${results.failed} assets failed to process`)
@@ -119,7 +119,8 @@ export function isContentBodyField(field) {
119
119
  * register supplies it (`registry-package.js`), naming the section a short `'@/x'` means.
120
120
  * Falls back to `resolveName`, which resolves the scope and keeps the rest as written.
121
121
  * @returns {Object} the declaration (`{ name, label?, plural?, icon?, description?,
122
- * source_locale?, linkable?, grantable?, sections }`).
122
+ * source_locale?, linkable?, grantable?, sections, i18n }`) — `i18n` always, `{}`
123
+ * when the schema has no labels in other languages.
123
124
  */
124
125
  export function toDataSchemaDeclaration(normalized, { name, resolveName, resolveOptions } = {}) {
125
126
  if (!name) throw new Error('toDataSchemaDeclaration: a registry name is required')
@@ -191,9 +192,83 @@ export function toDataSchemaDeclaration(normalized, { name, resolveName, resolve
191
192
  if (normalized.grantable === false) decl.grantable = false
192
193
 
193
194
  decl.sections = sections
195
+
196
+ // `i18n` — the schema's labels in other languages — rides on every declaration, the whole
197
+ // set: `{}` when the schema has none. A registry leaves its stored translations alone when the
198
+ // key is absent, so a language taken out of the schema would never go. Each path must name a
199
+ // label of the sections above. Since 2026-10-28.
200
+ decl.i18n = lowerI18n(normalized.i18n, sections, name)
194
201
  return decl
195
202
  }
196
203
 
204
+ // --- i18n ----------------------------------------------------------------------
205
+
206
+ // A section of the lowered declaration by its full `/`-path from the root, or null.
207
+ function sectionAt(sections, path) {
208
+ const [first, ...rest] = path.split('/')
209
+ let section = sections[first]
210
+ for (const segment of rest) {
211
+ const child = section?.fields?.[segment]
212
+ section = child?.type === 'section' ? child : null
213
+ }
214
+ return section || null
215
+ }
216
+
217
+ // Every section's full `/`-path, depth first.
218
+ function sectionPaths(sections) {
219
+ const out = []
220
+ const visit = (path, section) => {
221
+ out.push(path)
222
+ for (const [key, field] of Object.entries(section?.fields || {})) {
223
+ if (field?.type === 'section') visit(`${path}/${key}`, field)
224
+ }
225
+ }
226
+ for (const [name, section] of Object.entries(sections || {})) visit(name, section)
227
+ return out
228
+ }
229
+
230
+ // Why a label path names no label of these sections, or null when it does.
231
+ function labelPathProblem(path, sections) {
232
+ if (/^model\.(?:label|plural|description)$/.test(path)) return null
233
+ const field = /^section\.(.+)\.field\.([^./]+)\.(?:label|description)$/.exec(path)
234
+ const section = field || /^section\.(.+)\.(?:label|description)$/.exec(path)
235
+ if (!section) return 'is not a label path'
236
+ const at = sectionAt(sections, section[1])
237
+ if (!at) {
238
+ const paths = sectionPaths(sections)
239
+ const full = paths.filter((p) => p.endsWith(`/${section[1]}`))
240
+ return full.length === 1
241
+ ? `names a nested section by its bare name — write its full path, '${full[0]}'`
242
+ : `names no section '${section[1]}' — this schema's are ${paths.map((p) => `'${p}'`).join(', ')}`
243
+ }
244
+ if (field && !at.fields?.[field[2]]) return `names no field '${field[2]}' in section '${section[1]}'`
245
+ return null
246
+ }
247
+
248
+ function lowerI18n(i18n, sections, name) {
249
+ const out = {}
250
+ for (const [language, labels] of Object.entries(i18n || {})) {
251
+ for (const path of Object.keys(labels || {})) {
252
+ const problem = labelPathProblem(path, sections)
253
+ if (problem) throw new Error(`Data schema '${name}': i18n '${language}': '${path}' ${problem}.`)
254
+ }
255
+ out[language] = { ...labels }
256
+ }
257
+ return out
258
+ }
259
+
260
+ /**
261
+ * Refuse an `i18n` path that names no label of its schema where schemas resolve — the foundation
262
+ * build and `uniweb validate` (`buildDataSchemaMap`) — rather than when the schema is registered.
263
+ *
264
+ * @param {Object<string, object>} dataSchemas - normalized schemas by ref
265
+ */
266
+ export function assertI18nPaths(dataSchemas) {
267
+ for (const [ref, schema] of Object.entries(dataSchemas || {})) {
268
+ if (schema?.i18n) toDataSchemaDeclaration(schema, { name: ref })
269
+ }
270
+ }
271
+
197
272
  // --- shapes ------------------------------------------------------------------
198
273
 
199
274
  // The `fields:` shorthand: a flat field set is ONE single section, named `brief` and
@@ -263,17 +338,25 @@ function lowerSection(def, resolve, optResolve, path = '') {
263
338
  if (def.nestable) out.self_nesting = true
264
339
  if (def.append_only) out.append_only = true
265
340
 
341
+ // Leaves and explicit child sections (sections-form, e.g. under a binder) share one ordered
342
+ // `fields:` namespace, a child as a `type: section` field. The two maps are lowered in the
343
+ // order the author wrote them, which the IR keeps (`@uniweb/schemas/format`), since a
344
+ // registry lists a definition's sections in the declared order. ⛔ Until 2026-10-28 every
345
+ // child section went after the leaves, wherever it was written.
266
346
  const fields = {}
267
- for (const [key, rawField] of Object.entries(def.fields || {})) {
268
- fields[key] = lowerField(rawField, resolve, optResolve, path ? `${path}/${key}` : key)
269
- }
270
- // Explicit child sections (sections-form, e.g. under a binder) → `type: section`
271
- // fields, in the same ordered namespace as the leaves.
272
- for (const [childName, childDef] of Object.entries(def.sections || {})) {
273
- const childPath = path ? `${path}/${childName}` : childName
274
- fields[childName] = {
275
- type: 'section',
276
- ...lowerSection(childDef, resolve, optResolve, childPath)
347
+ for (const part of Object.keys(def)) {
348
+ if (part === 'fields') {
349
+ for (const [key, rawField] of Object.entries(def.fields || {})) {
350
+ fields[key] = lowerField(rawField, resolve, optResolve, path ? `${path}/${key}` : key)
351
+ }
352
+ } else if (part === 'sections') {
353
+ for (const [childName, childDef] of Object.entries(def.sections || {})) {
354
+ const childPath = path ? `${path}/${childName}` : childName
355
+ fields[childName] = {
356
+ type: 'section',
357
+ ...lowerSection(childDef, resolve, optResolve, childPath)
358
+ }
359
+ }
277
360
  }
278
361
  }
279
362
  // A section with neither leaves nor sub-sections carries nothing, and is not a
@@ -4,10 +4,16 @@
4
4
  // ⛔ AN ITEM OF A LIST WITHOUT A `$uuid` IS A NEW ROW. A record's `many` sections are `multi`
5
5
  // sections on the backend, so a record re-sent with its list items uuid-less would insert them all
6
6
  // and delete every stored one. The backend refuses that, whole (`identity_required`, naming the
7
- // section) — measured 2026-09-25 on an edit of a talk whose `sessions` it held. A single section
8
- // needs nothing: its one item is matched by section. So every LIST of a record carries its items'
9
- // `$uuid`s once the backend holds them: a `many` section, a list nested in a section or in an
10
- // item, and a self-nesting list's `$children`, at every depth.
7
+ // section) — measured 2026-09-25 on an edit of a talk whose `sessions` it held. So every LIST of a
8
+ // record carries its items' `$uuid`s once the backend holds them: a `many` section, a list nested
9
+ // in a section or in an item, and a self-nesting list's `$children`, at every depth.
10
+ //
11
+ // ⭐ AND SO DOES A SINGLE SECTION UNDER A LIST. A single section with no list above it holds one
12
+ // item, matched by section, and needs nothing. Under a list it holds one item PER ITEM of the list
13
+ // (a degree's `thesis`), so a backend matches it by its `$uuid`, as a list element: sent without
14
+ // one, every push after the first is refused whole. It is banked at its place under its item
15
+ // (`degrees[0].thesis`), with no fingerprint, since its item's own match places it. ⛔ Until
16
+ // 2026-10-28 it was never banked, because a backend matched every single section by section.
11
17
  //
12
18
  // ⭐ BANKED PER RECORD, FROM WHAT WAS SENT AND WHAT CAME BACK. An item has no file and no name, so
13
19
  // nothing on disk can carry its identity — the fourth kind in the producer's ledger, beside
@@ -74,6 +80,18 @@ function eachList(def, value, prefix, visit) {
74
80
  }
75
81
  }
76
82
 
83
+ // Each single section of a container that the container holds a value for, by its path, and
84
+ // the single sections inside it: never into a list, whose items are visited as items. Called on
85
+ // an item of a list, so every section it visits has a list above it.
86
+ function eachSingle(def, value, prefix, visit) {
87
+ if (!isPlainObject(value)) return
88
+ for (const [key, field] of Object.entries(def?.fields || {})) {
89
+ if (field?.type !== 'section' || field.multiple === true || !isPlainObject(value[key])) continue
90
+ visit(`${prefix}${key}`, field, value[key])
91
+ eachSingle(field, value[key], `${prefix}${key}.`, visit)
92
+ }
93
+ }
94
+
77
95
  // Each list of a record document: its `many` sections, and the lists inside its single ones.
78
96
  function eachRecordList(declaration, document, visit) {
79
97
  for (const [name, def] of Object.entries(declaration?.sections || {})) {
@@ -95,18 +113,23 @@ function itemsOf(def, items) {
95
113
  nested[path] = itemsOf(d, list)
96
114
  })
97
115
  if (Object.keys(nested).length) node.c = nested
116
+ const singles = []
117
+ eachSingle(def, item, '', (path) => singles.push(path))
118
+ if (singles.length) node.s = singles
98
119
  return node
99
120
  })
100
121
  }
101
122
 
102
123
  /**
103
124
  * The lists of one record document, as sent: each list's items by path, each item its
104
- * fingerprint (`h`) and its own lists (`c`). What `harvestRecordItems` pairs with the
105
- * document the backend returns. Not stored — a bank is (`harvestRecordItems`).
125
+ * fingerprint (`h`), its own lists (`c`) and the paths of the single sections under it (`s`).
126
+ * What `harvestRecordItems` pairs with the document the backend returns. Not stored — a bank
127
+ * is (`harvestRecordItems`).
106
128
  *
107
129
  * @param {object} document - the record's `$`-document
108
130
  * @param {object} declaration - its data schema's declaration (`{ name, sections }`)
109
- * @returns {Object<string, Array<{ h: string, c?: object }>>} empty when the record has no list
131
+ * @returns {Object<string, Array<{ h: string, c?: object, s?: string[] }>>} empty when the
132
+ * record has no list
110
133
  */
111
134
  export function recordItemLists(document, declaration) {
112
135
  const lists = {}
@@ -136,6 +159,11 @@ function pairItems(ours, theirs, at, bank) {
136
159
  if (!uuid) return
137
160
  const place = `${at}[${k}]`
138
161
  bank[place] = exact ? `${uuid} ${ours[k].h}` : uuid
162
+ // A single section under the item, at its place under it: the uuid alone.
163
+ for (const path of ours[k]?.s || []) {
164
+ const single = uuidOf(valueAt(item, path))
165
+ if (single) bank[`${place}.${path}`] = single
166
+ }
139
167
  for (const [path, sub] of Object.entries(ours[k]?.c || {})) {
140
168
  const list = valueAt(item, path)
141
169
  if (Array.isArray(list)) pairItems(sub, list, `${place}.${path}`, bank)
@@ -164,18 +192,19 @@ export function harvestRecordItems(lists, returned) {
164
192
  // A list in the backend's document: an array of items that each carry a `$uuid`.
165
193
  const isStoredList = (v) => Array.isArray(v) && v.length > 0 && v.every((item) => uuidOf(item))
166
194
 
167
- function storedLists(container, prefix, bank) {
195
+ function storedLists(container, prefix, bank, underList = false) {
168
196
  for (const [key, value] of Object.entries(container || {})) {
169
197
  if (key.startsWith('$') && key !== '$children') continue
170
198
  if (isStoredList(value)) {
171
199
  value.forEach((item, k) => {
172
200
  const place = `${prefix}${key}[${k}]`
173
201
  bank[place] = item.$uuid
174
- storedLists(item, `${place}.`, bank)
202
+ storedLists(item, `${place}.`, bank, true)
175
203
  })
176
204
  } else if (uuidOf(value)) {
177
- // A section: its lists sit under its name.
178
- storedLists(value, `${prefix}${key}.`, bank)
205
+ // A section: its lists sit under its name. A single one under a list is banked too.
206
+ if (underList) bank[`${prefix}${key}`] = value.$uuid
207
+ storedLists(value, `${prefix}${key}.`, bank, underList)
179
208
  }
180
209
  }
181
210
  }
@@ -187,7 +216,8 @@ function storedLists(container, prefix, bank) {
187
216
  *
188
217
  * Read by shape: a list is an array whose every item carries a `$uuid`, and a section is an
189
218
  * object carrying one — a reference is a string or an `{ schema, entity }`, and a localized
190
- * value a `{ lang: … }` map, neither of which does.
219
+ * value a `{ lang: … }` map, neither of which does. A section under a list is banked at its
220
+ * place, as `harvestRecordItems` banks it.
191
221
  *
192
222
  * @param {object} returned - the backend's document for one record
193
223
  * @returns {Object<string, string>} place → `"<uuid>"`
@@ -240,8 +270,19 @@ function matchItems(prints, banked) {
240
270
  return assigned
241
271
  }
242
272
 
243
- function stampList(def, items, at, lists, counts, claimed) {
244
- const banked = (at !== null && lists.get(at)) || []
273
+ // The bank's single sections — a place that does not end in an index — place → uuid.
274
+ function bankedSingles(bank) {
275
+ const singles = new Map()
276
+ for (const [place, value] of Object.entries(bank || {})) {
277
+ if (/\]$/.test(place) || typeof value !== 'string') continue
278
+ const [u] = value.split(' ')
279
+ if (u) singles.set(place, u)
280
+ }
281
+ return singles
282
+ }
283
+
284
+ function stampList(def, items, at, banks, counts, claimed) {
285
+ const banked = (at !== null && banks.lists.get(at)) || []
245
286
  const assigned = matchItems(items.map((item) => fingerprint(def, item)), banked)
246
287
  items.forEach((item, i) => {
247
288
  const b = assigned[i]
@@ -252,11 +293,24 @@ function stampList(def, items, at, lists, counts, claimed) {
252
293
  } else {
253
294
  counts.unknown++
254
295
  }
255
- // An item's own lists are banked under the place of the item it matched — a new item's
256
- // nested items are new too.
296
+ // An item's own lists, and its single sections, are banked under the place of the item it
297
+ // matched — a new item's nested items are new too.
257
298
  const under = b && item.$uuid === b.u ? b.place : null
299
+ if (under !== null) {
300
+ eachSingle(def, item, '', (path, d, single) => {
301
+ const u = banks.singles.get(`${under}.${path}`)
302
+ if (u && !claimed.has(u)) {
303
+ single.$uuid = u
304
+ claimed.add(u)
305
+ counts.stamped++
306
+ } else {
307
+ // Under an item the backend holds, with no identity here: one the backend may hold.
308
+ counts.unbankedSingles++
309
+ }
310
+ })
311
+ }
258
312
  eachList(def, item, '', (path, d, list) =>
259
- stampList(d, list, under === null ? null : `${under}.${path}`, lists, counts, claimed)
313
+ stampList(d, list, under === null ? null : `${under}.${path}`, banks, counts, claimed)
260
314
  )
261
315
  })
262
316
  }
@@ -268,14 +322,17 @@ function stampList(def, items, at, lists, counts, claimed) {
268
322
  * @param {object} declaration - its data schema's declaration
269
323
  * @param {Object<string,string>} bank - this record's entry (`harvestRecordItems` /
270
324
  * `storedRecordItems`)
271
- * @returns {{ stamped: number, unknown: number }} items given a uuid, and items sent as new
325
+ * @returns {{ stamped: number, unknown: number, unbankedSingles: number }} items given a
326
+ * uuid; list items sent as new; and single sections under an item that kept its uuid but
327
+ * with none banked for them, which a backend may hold (a bank from before 2026-10-28 has
328
+ * none), so the caller can recover them
272
329
  */
273
330
  export function stampRecordItems(document, declaration, bank) {
274
- const counts = { stamped: 0, unknown: 0 }
331
+ const counts = { stamped: 0, unknown: 0, unbankedSingles: 0 }
275
332
  const claimed = new Set()
276
- const lists = bankedLists(bank)
333
+ const banks = { lists: bankedLists(bank), singles: bankedSingles(bank) }
277
334
  eachRecordList(declaration, document, (path, def, items) => {
278
- stampList(def, items, path, lists, counts, claimed)
335
+ stampList(def, items, path, banks, counts, claimed)
279
336
  })
280
337
  return counts
281
338
  }
@@ -554,6 +554,10 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
554
554
  const n = stampRecordItems(e.document, declaration, banked)
555
555
  recordItemIdentity.stamped += n.stamped
556
556
  recordItemIdentity.unknown += n.unknown
557
+ // A single section under an item the backend holds, banked nowhere — a bank from before such
558
+ // sections were banked (2026-10-28) — is recovered as an unbanked record's items are: sent
559
+ // without its `$uuid`, a push after the first is refused whole.
560
+ if (n.unbankedSingles > 0) unbankedIds.add(e.id)
557
561
  }
558
562
 
559
563
  const siteEntity = siteDoc