@uniweb/build 1.16.3 → 1.17.1

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.16.3",
3
+ "version": "1.17.1",
4
4
  "description": "Build tooling for the Uniweb Component Web Platform",
5
5
  "type": "module",
6
6
  "exports": {
@@ -56,11 +56,11 @@
56
56
  "js-yaml": "^4.3.2",
57
57
  "sharp": "^0.35.5",
58
58
  "yaml": "^2.5.0",
59
- "@uniweb/content-reader": "~1.5.9",
60
59
  "@uniweb/content-writer": "~1.3.1",
60
+ "@uniweb/content-reader": "~1.5.9",
61
+ "@uniweb/semantic-parser": "~1.13.2",
61
62
  "@uniweb/schemas": "~1.6.10",
62
63
  "@uniweb/projections": "~1.2.11",
63
- "@uniweb/semantic-parser": "~1.13.2",
64
64
  "@uniweb/theming": "~1.2.1"
65
65
  },
66
66
  "optionalDependencies": {
@@ -1,5 +1,5 @@
1
1
  /**
2
- * Asset reference helpers — two pure functions, no file.
2
+ * Asset reference helpers — pure functions, no file.
3
3
  *
4
4
  * ⚠️ **The MAP moved to `sync.json` on 2026-09-20** (`sync-store.js`,
5
5
  * `backends.<origin>.assets`). It lived here as `assets.json`, a single flat
@@ -23,12 +23,18 @@
23
23
  * ⭐ **`restoreAssetRefs` no-ops on an empty map**, which is what makes the store's
24
24
  * `backend` parameter honest: a projection not tied to a backend has no known
25
25
  * assets, so it restores nothing rather than guessing.
26
+ * - **`sameStoredFile`** / **`keepAuthoredRefs`** — keep the author's path where the
27
+ * files already name one of the same bytes. A backend keeps a file by its content, so
28
+ * two such files are one asset, and `restoreAssetRefs` can give each reference only
29
+ * the first of their paths.
26
30
  *
27
31
  * @module
28
32
  */
29
33
 
30
34
  import { createHash } from 'node:crypto'
35
+ import { dirname, resolve } from 'node:path'
31
36
  import { ASSET_SLOTS } from '@uniweb/semantic-parser'
37
+ import { siteFileKey } from './located-media.js'
32
38
 
33
39
  /**
34
40
  * The fingerprint the asset map in `sync.json` keeps of the URL a host serves an
@@ -148,3 +154,62 @@ export function restoreAssetRefs(document, map) {
148
154
 
149
155
  // Only a string that could be a served address is worth hashing.
150
156
  const looksLikeAddress = (v) => v.startsWith('/') || /^https?:\/\//i.test(v)
157
+
158
+ /**
159
+ * Whether two references name the same stored file: the same string, or two references the map gives
160
+ * one asset id. A backend keeps a file by its bytes, so two files with the same bytes are one asset, with
161
+ * one id and one served address. A stored reference to it says nothing of which path it came from, and
162
+ * `restoreAssetRefs` gives it the first path the map lists.
163
+ *
164
+ * A relative reference is read from the file it is written in (`fromFile`), as the push keyed it
165
+ * (`located-media.js::siteFileKey`).
166
+ *
167
+ * ⛔ Measured 2026-11-05 on a docs site whose French screenshot was the English one's bytes: the French
168
+ * translation's image came back as the English path, so the pull wrote the translation as its words
169
+ * alone, and took that as the app's change.
170
+ *
171
+ * @param {Record<string, { id: string }>} map - `sync.json`'s assets for the backend
172
+ * @param {{ siteRoot?: string|null, tree?: () => Array<[string, string]> }} [opts] - for a relative
173
+ * reference: the site's folder, and its tree (`located-media.js::siteTree`)
174
+ * @returns {(a: string, b: string, fromFile?: string|null) => boolean}
175
+ */
176
+ export function sameStoredFile(map, { siteRoot = null, tree = () => [] } = {}) {
177
+ const idOf = (ref, fromFile) => {
178
+ if (typeof ref !== 'string' || !ref) return null
179
+ const own = map?.[ref]?.id
180
+ if (own) return own
181
+ if (!siteRoot || !fromFile || ref.startsWith('/') || /^[a-z][a-z0-9+.-]*:/i.test(ref)) return null
182
+ const key = siteFileKey(siteRoot, resolve(dirname(fromFile), ref), tree())
183
+ return (key && map?.[key]?.id) || null
184
+ }
185
+ return (a, b, fromFile = null) => {
186
+ if (a === b) return true
187
+ const id = idOf(a, fromFile)
188
+ return !!id && id === idOf(b, fromFile)
189
+ }
190
+ }
191
+
192
+ /**
193
+ * A value a pull writes over an authored one, with each reference that names the same stored file as
194
+ * the authored value at the same place given back as the author wrote it (`sameStoredFile`). Nothing
195
+ * else changes, so a file the app changed to another asset is written.
196
+ *
197
+ * @param {*} incoming - what the pull writes: a document, frontmatter, a config
198
+ * @param {*} authored - what the file says now, in the same shape
199
+ * @param {(a: string, b: string) => boolean} same
200
+ * @returns {*} `incoming`, or a copy with those references kept
201
+ */
202
+ export function keepAuthoredRefs(incoming, authored, same) {
203
+ if (typeof incoming === 'string') {
204
+ return typeof authored === 'string' && incoming !== authored && same(incoming, authored) ? authored : incoming
205
+ }
206
+ if (Array.isArray(incoming)) {
207
+ return Array.isArray(authored) ? incoming.map((v, i) => keepAuthoredRefs(v, authored[i], same)) : incoming
208
+ }
209
+ if (incoming && typeof incoming === 'object' && authored && typeof authored === 'object' && !Array.isArray(authored)) {
210
+ const out = {}
211
+ for (const [key, value] of Object.entries(incoming)) out[key] = keepAuthoredRefs(value, authored[key], same)
212
+ return out
213
+ }
214
+ return incoming
215
+ }
@@ -1,6 +1,6 @@
1
1
  /**
2
2
  * ⭐ WHAT A PUSH LEAVES OUT: a page or a section a pull HELD. The app changed it in a way its files
3
- * cannot say — a second section in a folder of single-section pages, a setting an `.md` page has no
3
+ * cannot say — a second section on an atomic page, a setting an `.md` page has no
4
4
  * place for, a move to where a page cannot sit — so the pull wrote nothing for it, and the site keeps
5
5
  * the app's version (`site-project.js`, `report.held`).
6
6
  *
@@ -485,8 +485,11 @@ export function isLocalizedContent(value) {
485
485
  * With `languages` (`documentLanguages`), a value in any other language is left out of the
486
486
  * translation files, and the language is named in `outside` for the caller to report. A whole document
487
487
  * in one is kept (`keepLanguage`, `readKept`), so a push sends it back.
488
+ *
489
+ * With `sameFile` (`asset-map.js::sameStoredFile`), an image an author's entry names by a file of the
490
+ * same bytes as the one the pull read says the same thing, and the entry is kept (`saysImage`).
488
491
  */
489
- export function createTranslationCollector(sourceLocale, { siteRoot = null, languages = null } = {}) {
492
+ export function createTranslationCollector(sourceLocale, { siteRoot = null, languages = null, sameFile = null } = {}) {
490
493
  const byLocale = {} // { locale: { hash: target } }
491
494
  const outside = new Set() // the languages read that the site does not have
492
495
  const kept = {} // { place: { '@'?, languages? } }, what `readKept` gives back
@@ -601,7 +604,7 @@ export function createTranslationCollector(sourceLocale, { siteRoot = null, lang
601
604
  return null
602
605
  }
603
606
 
604
- return { add, addStructuralMap, noteFreeform, keptFreeform, keepMeta, keepLanguage, has, byLocale, says, marks, freeformPending, outside, kept, keptRead }
607
+ return { add, addStructuralMap, noteFreeform, keptFreeform, keepMeta, keepLanguage, has, byLocale, says, marks, freeformPending, outside, kept, keptRead, sameFile }
605
608
  }
606
609
 
607
610
  /**
@@ -625,7 +628,7 @@ export function createTranslationCollector(sourceLocale, { siteRoot = null, lang
625
628
  * ⭐ TWO ROWS OF ONE SOURCE TEXT THAT READ DIFFERENTLY cannot be said by one entry, so the target is
626
629
  * free-form. ⛔ Until 2026-10-31 the last one won: `(zh_A, zh_B)` became `(zh_B, zh_B)` on the next push.
627
630
  */
628
- function deriveStructuralMap(sourceDoc, targetDoc, modelFor = () => null, checks = {}, notes = { cleared: {}, outdated: {} }, olderSource = () => null) {
631
+ function deriveStructuralMap(sourceDoc, targetDoc, modelFor = () => null, checks = {}, notes = { cleared: {}, outdated: {} }, olderSource = () => null, sameFile = null) {
629
632
  if (!isProseMirrorDoc(sourceDoc) || !isProseMirrorDoc(targetDoc)) return null
630
633
  const src = blockElements(sourceDoc)
631
634
  const tgt = blockElements(targetDoc)
@@ -657,7 +660,7 @@ function deriveStructuralMap(sourceDoc, targetDoc, modelFor = () => null, checks
657
660
  return null
658
661
  }
659
662
  const withData = addDataBlockStrings(map, sourceDoc, targetDoc, modelFor, checks)
660
- return withData && addImageTranslations(withData, sourceDoc, targetDoc, checks)
663
+ return withData && addImageTranslations(withData, sourceDoc, targetDoc, checks, sameFile)
661
664
  }
662
665
 
663
666
  // ⭐ AN IMAGE's translation, read pairwise — what a translation may give it (`merge.js::translateImages`):
@@ -666,7 +669,7 @@ function deriveStructuralMap(sourceDoc, targetDoc, modelFor = () => null, checks
666
669
  // A target whose images differ in anything else — their number, a role, a size — or that changed an
667
670
  // image with no alt text cannot be said per image, and the whole translation is free-form.
668
671
  // ⛔ Until 2026-10-28 an image was not read here, and its translation was not sent either.
669
- function addImageTranslations(map, sourceDoc, targetDoc, checks = null) {
672
+ function addImageTranslations(map, sourceDoc, targetDoc, checks = null, sameFile = null) {
670
673
  const src = imageNodes(sourceDoc)
671
674
  const tgt = imageNodes(targetDoc)
672
675
  if (src.length !== tgt.length) return null
@@ -685,7 +688,7 @@ function addImageTranslations(map, sourceDoc, targetDoc, checks = null) {
685
688
  // words match, and a text element reads an image value as its words (`merge.js::translatedInline`).
686
689
  if (map[key] !== undefined && map[key] !== value && toPlainText(map[key]).trim() !== words) return null
687
690
  map[key] = value
688
- if (checks) checks[key] = saysImage(s, t)
691
+ if (checks) checks[key] = saysImage(s, t, sameFile)
689
692
  }
690
693
  return map
691
694
  }
@@ -702,13 +705,22 @@ function untranslated(attrs) {
702
705
  return out
703
706
  }
704
707
 
705
- // Whether a value, pushed onto the source image, gives it what the pull read.
706
- function saysImage(source, read) {
708
+ // Whether a value, pushed onto the source image, gives it what the pull read. ⭐ A file of the same
709
+ // bytes as the one read is that file (`sameFile`, `asset-map.js::sameStoredFile`): a backend keeps both
710
+ // as one asset, and the pull reads it back as the first path it knows. ⛔ Until 2026-11-06 a file was
711
+ // its path, and an entry naming its language's copy of the source's image was replaced by its words.
712
+ const IMAGE_FILES = new Set(['src', 'poster', 'preview'])
713
+ function saysImage(source, read, sameFile = null) {
707
714
  return (value) => {
708
715
  if (typeof value !== 'string') return false
709
716
  const given = translatedImage(value)
710
717
  if (!given) return false
711
- return TRANSLATED_IMAGE_ATTRS.every((attr) => (given[attr] ?? source[attr] ?? null) === (read[attr] ?? null))
718
+ return TRANSLATED_IMAGE_ATTRS.every((attr) => {
719
+ const said = given[attr] ?? source[attr] ?? null
720
+ const got = read[attr] ?? null
721
+ if (said === got) return true
722
+ return !!sameFile && IMAGE_FILES.has(attr) && typeof said === 'string' && typeof got === 'string' && sameFile(said, got)
723
+ })
712
724
  }
713
725
  }
714
726
 
@@ -846,7 +858,7 @@ export function unwrapLocalizedContent(content, sourceLocale, collector, freefor
846
858
  const kept = collector?.keptFreeform?.(locale, freeformCandidates || freeformRelPath) || null
847
859
  const checks = {}
848
860
  const notes = { cleared: {}, outdated: {} }
849
- const map = kept ? null : deriveStructuralMap(source, value, modelFor, checks, notes, olderSourceOf(content['@'], locale))
861
+ const map = kept ? null : deriveStructuralMap(source, value, modelFor, checks, notes, olderSourceOf(content['@'], locale), collector?.sameFile ?? null)
850
862
  if (map) collector?.addStructuralMap?.(locale, map, context, checks, notes)
851
863
  else collector?.noteFreeform?.(locale, value, source, kept || freeformRelPath)
852
864
  } else {
@@ -17,8 +17,9 @@
17
17
  * so a site that showed its media under `uniweb dev` and in a static build lost it when published.
18
18
  *
19
19
  * ⚠️ A file outside both the site's folder and every folder its `paths:` names has no such key, and
20
- * stays warned and skipped. Two files with the same bytes are one asset, so a pull may write either
21
- * one's path.
20
+ * stays warned and skipped. Two files with the same bytes are one asset. A pull keeps the path a
21
+ * section, its translations and `site.yml` already name (`asset-map.js::sameStoredFile`). A reference
22
+ * new to the files, and a record's, takes the first path `sync.json` lists.
22
23
  */
23
24
 
24
25
  import { existsSync } from 'node:fs'
@@ -20,6 +20,7 @@ import { markdownToProseMirror } from '@uniweb/content-reader'
20
20
  import { parseFrontmatter } from './entity-source.js'
21
21
  import { canonicalJson, sameMarkdownDocument } from './same-content.js'
22
22
  import { spliceBody } from './body-splice.js'
23
+ import { keepAuthoredRefs } from './asset-map.js'
23
24
  import { fileLinksIn } from '../site/file-links.js'
24
25
  import { parseNumericPrefix } from '../utils/numeric-prefix.js'
25
26
  import { renderEntityDocument } from './backfill.js'
@@ -184,9 +185,11 @@ function readsTo(body) {
184
185
  * @param {Set<string>} [opts.reserved] - keys preserved when already present
185
186
  * @param {object} [opts.implied] - `{ key: value }` a file means by leaving `key` out; an incoming
186
187
  * value equal to it is not written into an existing file that leaves the key out
188
+ * @param {(a: string, b: string) => boolean} [opts.sameFile] - whether two references name the same
189
+ * stored file, read from this file (`asset-map.js::sameStoredFile`)
187
190
  * @returns {'updated'|'unchanged'}
188
191
  */
189
- export function writeSectionFile({ filePath, content, params, declaration, reserved = DEFAULT_RESERVED_FRONTMATTER, implied = null, fileLinks = null }) {
192
+ export function writeSectionFile({ filePath, content, params, declaration, reserved = DEFAULT_RESERVED_FRONTMATTER, implied = null, fileLinks = null, sameFile = null }) {
190
193
  let existing = ''
191
194
  try {
192
195
  existing = readFileSync(filePath, 'utf8')
@@ -194,6 +197,13 @@ export function writeSectionFile({ filePath, content, params, declaration, reser
194
197
  // new file
195
198
  }
196
199
  const { frontmatter, body: existingBody } = parseFrontmatter(existing, filePath)
200
+ // ⭐ A FILE OF THE SAME BYTES AS ONE THIS FILE NAMES IS THAT FILE (`sameFile`, `asset-map.js::sameStoredFile`):
201
+ // a backend keeps both as one asset, and the pull reads it back as the first path it knows, so the
202
+ // file keeps its own. ⛔ Until 2026-11-06 a pull wrote that first path over the author's.
203
+ if (sameFile && existing) {
204
+ if (params) params = keepAuthoredRefs(params, frontmatter, sameFile)
205
+ if (content && existingBody) content = keepAuthoredRefs(content, authoredDocument(existingBody), sameFile)
206
+ }
197
207
 
198
208
  const nextFrontmatter = { ...frontmatter }
199
209
  if (params) {
@@ -244,6 +254,15 @@ export function writeSectionFile({ filePath, content, params, declaration, reser
244
254
  }
245
255
 
246
256
 
257
+ // A body as the push reads it, or null where it cannot be read.
258
+ function authoredDocument(body) {
259
+ try {
260
+ return markdownToProseMirror(body)
261
+ } catch {
262
+ return null
263
+ }
264
+ }
265
+
247
266
  // Shallow-merge `changes` into a YAML config file and write idempotently. A key
248
267
  // whose value is null/undefined is deleted; an object value is shallow-merged one
249
268
  // level deep (so partial `theme` / `build` updates don't drop sibling keys) unless
@@ -1,18 +1,27 @@
1
1
  /**
2
- * A route's `mode` on the site-content document: what its pages may hold, which the app honours, and
3
- * not how the files hold them.
2
+ * A page's `mode` on the site-content document: what the page itself is, which the app honours, read from
3
+ * the page and never from its parent [Diego, 2026-11-05]:
4
4
  *
5
- * - `single-section`: each page under the route holds one section and no page of its own, as a folder
6
- * in folder mode keeps them, one `.md` file each. A route under it that holds no section is
7
- * `single-section` too, and the route holds no section of its own, except a page above a mounted
8
- * folder of `.md` pages.
9
- * - `page`: any other route.
5
+ * - `atomic`: a page that holds exactly one section and no child page, as the files hold it, one `.md`
6
+ * file in folder mode;
7
+ * - `atomic-parent`: a page with no section whose child pages are atomic pages or atomic-parents, as the
8
+ * files hold it, a directory in folder mode — its own `folder.yml`, or below one;
9
+ * - `regular`: every other page, a page with no section yet included.
10
10
  *
11
- * A push writes each route's own value, so nothing says "inherit" (`site.js::walkPagesNested`). A pull
12
- * reads it only for a route its files do not hold yet; a route they hold takes its form from them
13
- * (`site-project.js`). `folder` is the old spelling, which a stored document carries until its site's
14
- * next push: only a unit's identity reads it (`site-diff.js::walkSiteUnits`).
11
+ * A push writes each page's own value from where its files keep it (`site.js::walkPagesNested`). A pull
12
+ * places a page the files don't hold yet by it, and follows the app's switch of an empty page between
13
+ * `atomic-parent` and `regular` (`site-project.js`). A value it doesn't know reads as `regular`.
14
+ * ⛔ Until 2026-11-05 the value was the parent's: `single-section` on a page whose child pages were in
15
+ * folder mode, and `page` on every other, the pages under it included.
15
16
  *
16
17
  * A leaf, with no imports.
17
18
  */
18
- export const SINGLE_SECTION = 'single-section'
19
+ export const REGULAR = 'regular'
20
+ export const ATOMIC = 'atomic'
21
+ export const ATOMIC_PARENT = 'atomic-parent'
22
+
23
+ /** The page's own mode, or null for a value this framework doesn't know, which reads as `regular`. */
24
+ export function knownMode(record) {
25
+ const mode = record?.mode
26
+ return mode === REGULAR || mode === ATOMIC || mode === ATOMIC_PARENT ? mode : null
27
+ }
@@ -49,7 +49,7 @@
49
49
  import { entityContentHash } from './records.js'
50
50
  import { sectionFileBases, pageDirName, layoutSectionPaths } from './site-project.js'
51
51
  import { documentSourceLocale } from './source-locale.js'
52
- import { SINGLE_SECTION } from './route-mode.js'
52
+ import { ATOMIC_PARENT } from './route-mode.js'
53
53
 
54
54
  // A unit's own content, with the nested collections that are their own units
55
55
  // removed — so editing a section never also marks its page (or its parent
@@ -113,11 +113,10 @@ export function walkSiteUnits(doc, cb, sourceLocale = documentSourceLocale(doc))
113
113
  const dirName = pageDirName(record, sourceLocale)
114
114
  if (!dirName) continue
115
115
  const dir = `${parentDir}/${dirName}`
116
- // A route of single-section pages is its `folder.yml`, in either spelling: `folder` is the one a
117
- // push wrote until 2026-11-04, which a stored document carries until its site's next push, and a
118
- // unit keyed otherwise would read as one the app changed. Delete `folder` here once no synced site's
119
- // document carries it.
120
- cb(`${dir}/${record.mode === SINGLE_SECTION || record.mode === 'folder' ? 'folder.yml' : 'page.yml'}`, record, 'page')
116
+ // An atomic-parent is its `folder.yml`; every other page its `page.yml`, an atomic page's `.md` file
117
+ // included, as these keys have always named them. ⛔ Until 2026-11-05 the parent's `single-section`,
118
+ // or `folder` before it, named the `folder.yml`.
119
+ cb(`${dir}/${record.mode === ATOMIC_PARENT ? 'folder.yml' : 'page.yml'}`, record, 'page')
121
120
  walkSections(record.page_sections, dir)
122
121
  walkPages(record.$children, dir)
123
122
  }
@@ -36,7 +36,7 @@
36
36
  import { foldOpenGraph } from './open-graph.js'
37
37
  import { isAuthoredPreview } from './authored-preview.js'
38
38
  import { join, relative, extname, basename, dirname, parse, sep } from 'node:path'
39
- import { restoreAssetRefs } from './asset-map.js'
39
+ import { restoreAssetRefs, sameStoredFile, keepAuthoredRefs } from './asset-map.js'
40
40
  import { mapPageRefs, pageRefIndex, pageRefPages, writtenPageRef } from './page-refs.js'
41
41
  import { siteFileKeys, siteTree, writtenRefs } from './located-media.js'
42
42
  import { readBackendState, updateBackendState } from './sync-store.js'
@@ -50,7 +50,7 @@ import { writeSiteConfig, writeSitePaths, writeThemeFile, writeIfChanged, writeS
50
50
  import { mountEntriesOf } from '../site/mount-entries.js'
51
51
  import { declarationsToQueriesYml } from './records-project.js'
52
52
  import { buildRouteOf } from './site.js'
53
- import { SINGLE_SECTION } from './route-mode.js'
53
+ import { ATOMIC_PARENT, knownMode } from './route-mode.js'
54
54
  import { fileLinkTargets } from '../site/file-links.js'
55
55
  import { DEFAULT_SECTION_TYPE } from '@uniweb/core/section-type'
56
56
  import { translationContext, SITE_META_CONTEXT } from '../i18n/extract.js'
@@ -236,7 +236,7 @@ function readAuthoredYaml(filePath) {
236
236
  * @returns {{ siteConfig: string, theme?: string, headHtml?: string }} per-file
237
237
  * write status ('updated' | 'unchanged')
238
238
  */
239
- export function siteInfoToConfig({ document, siteRoot, backend = null, sourceLocale = documentSourceLocale(document), collector, keepAuthoredFoundation = false }) {
239
+ export function siteInfoToConfig({ document, siteRoot, backend = null, sourceLocale = documentSourceLocale(document), collector, keepAuthoredFoundation = false, sameFile = null }) {
240
240
  const info = document?.info || {}
241
241
  const settingsSection = document?.settings || {}
242
242
 
@@ -363,7 +363,12 @@ export function siteInfoToConfig({ document, siteRoot, backend = null, sourceLoc
363
363
  // back where the translation files the pull wrote made the same one, so a clone of a site that
364
364
  // declared `languages: [en, fr]` had no `languages:` at all — and followed its translation files
365
365
  // where the site it came from had a fixed list.
366
- const result = { siteConfig: writeSiteConfig(siteRoot, siteChanges) }
366
+ // ⭐ A file of the same bytes as one `site.yml` names is that file (`asset-map.js::sameStoredFile`): a
367
+ // favicon, a preview, a share image stays as the author wrote it.
368
+ const siteYmlPath = join(siteRoot, 'site.yml')
369
+ const authoredSite = sameFile ? readAuthoredYaml(siteYmlPath) : null
370
+ const written = authoredSite ? keepAuthoredRefs(siteChanges, authoredSite, (a, b) => sameFile(a, b, siteYmlPath)) : siteChanges
371
+ const result = { siteConfig: writeSiteConfig(siteRoot, written) }
367
372
 
368
373
  // theme (whole object) → theme.yml.
369
374
  if (settingsSection.theme && typeof settingsSection.theme === 'object') {
@@ -412,7 +417,7 @@ export function siteInfoToConfig({ document, siteRoot, backend = null, sourceLoc
412
417
  * site (`siteDefaultSectionType`), which a file leaves out
413
418
  * @returns {'updated'|'unchanged'}
414
419
  */
415
- export function sectionRecordToFile({ filePath, record, sourceLocale = LOCALIZED_FIELD_ASSUMPTION.defaultSourceLocale, collector, freeformRelPath, freeformCandidates = null, writeId = true, context = null, dataModel = null, impliedType = DEFAULT_SECTION_TYPE, media = null, fileLinks = null }) {
420
+ export function sectionRecordToFile({ filePath, record, sourceLocale = LOCALIZED_FIELD_ASSUMPTION.defaultSourceLocale, collector, freeformRelPath, freeformCandidates = null, writeId = true, context = null, dataModel = null, impliedType = DEFAULT_SECTION_TYPE, media = null, fileLinks = null, sameFile = null }) {
416
421
  // ⛔ A stored `preset` or `input` is not written back: neither has an effect, and the build
417
422
  // would only warn about it (2026-09-27).
418
423
  // ⛔ No `background` / `theme_override` / `insets` / `fetch`: the site-content Model dropped all
@@ -460,6 +465,8 @@ export function sectionRecordToFile({ filePath, record, sourceLocale = LOCALIZED
460
465
  implied: { type: impliedType },
461
466
  // The links the file writes as files, as the push reads them (`pageFileTargets`).
462
467
  fileLinks,
468
+ // A file of the same bytes as one this file names is that file (`asset-map.js::sameStoredFile`).
469
+ sameFile: sameFile ? (a, b) => sameFile(a, b, filePath) : null,
463
470
  })
464
471
  }
465
472
 
@@ -607,6 +614,7 @@ export function pageSectionsToFiles({ pageDir, pageSections, ctx, pageContext })
607
614
  writeId: fileSectionName(filePath) !== stableId,
608
615
  context: pageContext ? translationContext({ stableId }, pageContext.route) : null,
609
616
  media: ctx?.media ?? null,
617
+ sameFile: ctx?.sameFile ?? null,
610
618
  fileLinks: ctx?.fileLinks ?? null,
611
619
  })
612
620
  written.push(filePath)
@@ -968,16 +976,18 @@ function projectPages(pages, pagesDir, sourceLocale, report, prune, ctx) {
968
976
  // its `page.yml`, is read in folder mode, its sections as pages. A folder-mode folder is a folder.
969
977
  // ⛔ Until 2026-11-04 every page went to its slug's folder: `pages/2-about/` came back as `about/`.
970
978
  //
971
- // In a folder-mode level a route is a folder only where the files keep one in folder mode, where it is
972
- // or where the app moved it from (`oldForm`), or, new to them, where its `mode` is `single-section`. A
973
- // page folder is no form there: a parametric page, or a page its file cannot hold, is `cannot`.
979
+ // In a folder-mode level a page is a directory only when it is an atomic-parent: by its own mode, or,
980
+ // where its mode is none this framework knows, by the form the files kept it in where the app moved it
981
+ // from (`oldForm`). Any other page is an `.md` file there when it can be one. A page folder is no form
982
+ // there: a parametric page, or a page its file cannot hold, is `cannot`.
974
983
  function placeOf(ctx, record, route, levelDir, levelMode, sourceLocale) {
975
984
  const found = ctx.files?.page(route)
976
985
  if (found) return found
977
986
  if (levelMode === 'pages') {
978
- if (record.is_dynamic) return { kind: 'cannot', what: ['a parametric page, which a route of single-section pages holds none of'] }
979
- const was = oldForm(ctx, record)
980
- if (was ? was !== 'pages' : !isSingleSection(record)) {
987
+ if (record.is_dynamic) return { kind: 'cannot', what: ['a parametric page, which an atomic-parent holds none of'] }
988
+ const mode = knownMode(record)
989
+ const parent = mode ? mode === ATOMIC_PARENT : oldForm(ctx, record) === 'pages'
990
+ if (!parent) {
981
991
  const name = unwrapLocalized(record.slug, sourceLocale)
982
992
  const what = mdPageCannotHold(record, { name, sourceLocale })
983
993
  return what.length ? { kind: 'cannot', what } : { kind: 'md', file: join(levelDir, `${name}.md`), dir: levelDir }
@@ -1008,23 +1018,41 @@ function oldPlace(ctx, uuid) {
1008
1018
  return place?.kind === 'md' ? place.file : place?.dir ?? null
1009
1019
  }
1010
1020
 
1011
- // ⭐ A route whose pages are single-section, in either spelling: `folder` is the one a push wrote until
1012
- // 2026-11-04, which a stored document carries until its site's next push. A route new to the files takes
1013
- // its form from this — in a fresh clone, every route. ⛔ Until 2026-11-05 only `single-section` read so,
1014
- // and a clone of a site last pushed before then wrote its single-section routes in page mode.
1015
- const isSingleSection = (record) => record?.mode === SINGLE_SECTION || record?.mode === 'folder'
1016
-
1017
- // ⭐ A FOLDER'S FORM IS ITS FILES' WHERE THEY HOLD IT — folder mode (`pages`) or page mode (`sections`):
1018
- // a mount's route by the mount, a folder the files hold by its own config, one the app moved by the form
1019
- // it had. Only a route new to the files takes the form its `mode` asks for, a route the app made. ⛔ Until
1020
- // 2026-11-04 every folder took its `mode`'s form, so a stored route in another spelling would have had
1021
- // a `page.yml` written beside its `folder.yml`.
1021
+ // ⭐ A DIRECTORY'S FORM — folder mode (`pages`) or page mode (`sections`) — by the page's own mode: an
1022
+ // atomic-parent's is folder mode, any other page's page mode (`route-mode.js`). Where the files hold the
1023
+ // page, their form stands, but for the switch the app makes on an empty page, between atomic-parent and
1024
+ // regular: there is nothing to convert, so the page's config follows. A mount's
1025
+ // route is the mount's. Where its mode is none this framework knows, a page the app moved keeps the form
1026
+ // the files kept it in where it was, and a page new to them is regular.
1027
+ // ⛔ Until 2026-11-05 the form came from the files alone wherever they held the page, and a mode was read
1028
+ // only for a page new to them, as `single-section` on its parent.
1022
1029
  function formOf(ctx, record, route, place, levelMode) {
1023
1030
  if (place.mount) return place.mount.mode
1024
- if (ctx.files?.page(route) === place) return ctx.files.levelMode(place.dir) ?? folderModeOf(place.dir, levelMode)
1031
+ const mode = knownMode(record)
1032
+ const asked = mode === ATOMIC_PARENT ? 'pages' : mode ? 'sections' : null
1033
+ if (ctx.files?.page(route) === place) {
1034
+ const held = ctx.files.levelMode(place.dir) ?? folderModeOf(place.dir, levelMode)
1035
+ // A regular page has no place inside folder mode (`refusePageInFolderMode`), so there the files stand.
1036
+ const fits = asked === 'pages' || levelMode !== 'pages'
1037
+ return asked && asked !== held && fits && isEmptyPage(record, place.dir) ? asked : held
1038
+ }
1039
+ if (asked) return asked
1025
1040
  const was = oldForm(ctx, record)
1026
1041
  if (was === 'pages' || was === 'sections') return was
1027
- return isSingleSection(record) ? 'pages' : 'sections'
1042
+ return 'sections'
1043
+ }
1044
+
1045
+ // A page with no section and no child page, on the site and in the files: the only one the app switches
1046
+ // between atomic-parent and regular, and the only one a pull changes the form of in place.
1047
+ function isEmptyPage(record, dir) {
1048
+ if ((record?.page_sections || []).length || (record?.$children || []).length) return false
1049
+ let entries
1050
+ try {
1051
+ entries = readdirSync(dir, { withFileTypes: true })
1052
+ } catch {
1053
+ return false
1054
+ }
1055
+ return !entries.some((e) => (e.isFile() && isMarkdownFile(e.name)) || (e.isDirectory() && !isIgnoredFolder(e.name)))
1028
1056
  }
1029
1057
 
1030
1058
  // ⭐ A FOLDER-MODE `.md` PAGE, WRITTEN BACK IN PLACE: the file is the page and its one section, so the
@@ -1057,6 +1085,7 @@ function writeMdPage({ record, place, route, ctx, report, pageContext, sourceLoc
1057
1085
  writeId: stableId !== name,
1058
1086
  context: translationContext({ stableId }, pageContext.route),
1059
1087
  media: ctx?.media ?? null,
1088
+ sameFile: ctx?.sameFile ?? null,
1060
1089
  fileLinks: ctx?.fileLinks ?? null,
1061
1090
  })
1062
1091
  report.sections.push(place.file)
@@ -1152,12 +1181,12 @@ function writePagesTree(pages, pagesDir, sourceLocale, report, ctx, routePrefix
1152
1181
  filesGiveTopOrder = r.filesGiveTopOrder
1153
1182
  report.sections.push(...r.written)
1154
1183
  } else if (Array.isArray(record.page_sections) && record.page_sections.length) {
1155
- // ⛔ A route of single-section pages holds no section of its own: its folder's `.md` files are its
1156
- // pages. One the app gives it is held, and the route and its pages are written as they are. Until
1157
- // 2026-11-04 it was dropped, and the next push removed it from the site.
1184
+ // ⛔ An atomic-parent holds no section: its directory's `.md` files are its child pages. One the app
1185
+ // gives it is held, and the page and its child pages are written as they are. Until 2026-11-04 it was
1186
+ // dropped, and the next push removed it from the site.
1158
1187
  const uuids = record.page_sections.flatMap((s) => subtreeUuids(s))
1159
1188
  keepWhereTheFilesAre(ctx, uuids)
1160
- report.held?.push({ route, uuids, what: ['a section, which a route of single-section pages holds none of'] })
1189
+ report.held?.push({ route, uuids, what: ['a section, which an atomic-parent holds none of'] })
1161
1190
  report.leftAlone?.push(route)
1162
1191
  }
1163
1192
 
@@ -1175,6 +1204,13 @@ function writePagesTree(pages, pagesDir, sourceLocale, report, ctx, routePrefix
1175
1204
 
1176
1205
  const ymlName = form === 'pages' ? 'folder.yml' : 'page.yml'
1177
1206
  const ymlPath = join(pageDir, ymlName)
1207
+ // ⭐ THE APP'S SWITCH ON AN EMPTY PAGE (`formOf`): its config file takes the other name, as the author
1208
+ // wrote it, so the directory is read in the form the app made it — folder mode for an atomic-parent.
1209
+ const oldYmlPath = join(pageDir, ymlName === 'folder.yml' ? 'page.yml' : 'folder.yml')
1210
+ if (existsSync(oldYmlPath) && !existsSync(ymlPath)) {
1211
+ renameSync(oldYmlPath, ymlPath)
1212
+ report.deleted.push(oldYmlPath)
1213
+ }
1178
1214
  // Merge (not full-dump) so author-added keys survive a pull; the projector
1179
1215
  // owns only PAGE_YML_MANAGED_KEYS.
1180
1216
  const existing = readAuthoredYaml(ymlPath)
@@ -1216,7 +1252,7 @@ function subtreeUuids(record) {
1216
1252
  // hold it is not written there, so its files at the old place are the files' version of it, and the prune
1217
1253
  // must keep them: found by the rename index this copy wrote, else, for a page, by the route its sync state
1218
1254
  // last saw it at (`ctx.itemRoutes`). ⛔ Until 2026-11-04 the prune took them: a page of two sections moved
1219
- // into a folder of single-section pages was held there and deleted where it was.
1255
+ // into an atomic-parent was held there and deleted where it was.
1220
1256
  function keepWhereTheFilesAre(ctx, uuids) {
1221
1257
  if (!ctx?.kept) return
1222
1258
  for (const uuid of uuids) {
@@ -1770,6 +1806,7 @@ function projectLayout(layoutSections, layoutBaseDir, report, prune, ctx) {
1770
1806
  freeformCandidates: stableId ? freeformPathsFor({ stableId }, page) : null,
1771
1807
  context: translationContext({ stableId }, page.route),
1772
1808
  media: ctx?.media ?? null,
1809
+ sameFile: ctx?.sameFile ?? null,
1773
1810
  })
1774
1811
  report.layout.push(filePath)
1775
1812
  written.push(filePath)
@@ -1883,10 +1920,6 @@ export function siteContentDocumentToProject({ document, siteRoot, backend = nul
1883
1920
 
1884
1921
  const report = { config: null, collections: null, locales: null, assets: null, pages: [], sections: [], layout: [], deleted: [], renamed: [], leftAlone: [], held: [], mountedPages: [], mountRoutes: [] }
1885
1922
 
1886
- // Collects target-locale translations of localized scalars as they're projected;
1887
- // flushed to locales/{locale}.json at the end (the manifest stays derivable).
1888
- const collector = createTranslationCollector(sourceLocale, { siteRoot, languages: documentLanguages(document, sourceLocale) })
1889
-
1890
1923
  // Put the author's own asset paths back before anything is serialized. Stored
1891
1924
  // content carries an id and a serve URL; only the committed map knows the ref
1892
1925
  // the author wrote. Without this a push/pull cycle rewrites every image in a
@@ -1897,7 +1930,14 @@ export function siteContentDocumentToProject({ document, siteRoot, backend = nul
1897
1930
  // not tied to one has no known assets and restores nothing. Every caller that
1898
1931
  // pulls has an origin; the ones that do not are projecting a document in the
1899
1932
  // abstract.
1933
+ // ⭐ Two files of the same bytes are one asset, so `restoreAssetRefs` gives every reference to it the
1934
+ // first of their paths, and each writer keeps the one the files name (`sameStoredFile`).
1900
1935
  const assetMap = backend ? readBackendState(siteRoot, backend).assets || {} : {}
1936
+
1937
+ // Collects target-locale translations of localized scalars as they're projected;
1938
+ // flushed to locales/{locale}.json at the end (the manifest stays derivable).
1939
+ const collector = createTranslationCollector(sourceLocale, { siteRoot, languages: documentLanguages(document, sourceLocale), sameFile: sameStoredFile(assetMap) })
1940
+
1901
1941
  report.assets = restoreAssetRefs(document, assetMap)
1902
1942
  // ⭐ And each stored link to a page as the page's path (`page-refs.js`): what a file shows, where
1903
1943
  // the store keeps the id an editor links by.
@@ -1907,7 +1947,7 @@ export function siteContentDocumentToProject({ document, siteRoot, backend = nul
1907
1947
  // section's writer to make relative to its own file (`located-media.js`).
1908
1948
  const mediaKeys = siteFileKeys(assetMap)
1909
1949
 
1910
- report.config = siteInfoToConfig({ document, siteRoot, backend, sourceLocale, collector, keepAuthoredFoundation })
1950
+ report.config = siteInfoToConfig({ document, siteRoot, backend, sourceLocale, collector, keepAuthoredFoundation, sameFile: sameStoredFile(assetMap, { siteRoot }) })
1911
1951
  report.queries = declarationsToQueriesYml({ document, siteRoot, scope })
1912
1952
 
1913
1953
  // The uuid identity index (gitignored `.uniweb/`): read the prior map to anchor
@@ -1915,6 +1955,7 @@ export function siteContentDocumentToProject({ document, siteRoot, backend = nul
1915
1955
  // re-projected (deleted) drop out naturally. `collector` rides along to capture
1916
1956
  // localized scalars during the page walk.
1917
1957
  const ctx = { siteRoot, oldIndex: readPullIndex(siteRoot), newIndex: {}, report, collector, sourceLocale, sectionFiles: new Map(), dataModel, sectionType, media: mediaKeys.size ? { siteRoot, keys: mediaKeys } : null }
1958
+ ctx.sameFile = sameStoredFile(assetMap, { siteRoot, tree: () => ctx.media?.tree ?? [] })
1918
1959
  // Where the site keeps its localized URLs — `site.yml`'s map, when it has one (`pageSlugToYml`).
1919
1960
  const siteMap = readAuthoredYaml(join(siteRoot, 'site.yml'))?.i18n?.routeTranslations
1920
1961
  ctx.routes = { siteMap: isPlainRecord(siteMap) && Object.keys(siteMap).length ? siteMap : null, slugs: new Map() }
package/src/uwx/site.js CHANGED
@@ -47,7 +47,7 @@
47
47
 
48
48
  import { readdir, readFile } from 'node:fs/promises'
49
49
  import { dataBlockModels } from '../i18n/data-models.js'
50
- import { SINGLE_SECTION } from './route-mode.js'
50
+ import { ATOMIC, ATOMIC_PARENT, REGULAR } from './route-mode.js'
51
51
  import { existsSync } from 'node:fs'
52
52
  import { join, parse, relative } from 'node:path'
53
53
  import {
@@ -811,7 +811,8 @@ async function folderModePageRecords(ctx, dirPath, orderConfig, isRoot) {
811
811
  const data = buildPageData(config, {
812
812
  where: relative(siteRoot, filePath),
813
813
  slug: name,
814
- mode: 'page',
814
+ // One `.md` file in folder mode: a page of exactly one section and no child page (`route-mode.js`).
815
+ mode: ATOMIC,
815
816
  isDynamic: false,
816
817
  isRoot,
817
818
  siteIndex,
@@ -853,11 +854,12 @@ async function walkPagesNested(ctx, dirPath, parentSlugPath, inheritedMode, pare
853
854
  // ONE page whose sections were its `.md` files while the build rendered each as a
854
855
  // page of its own. Nothing warned, and a pull then wrote a `page.yml` into the
855
856
  // folder, converting the author's own site to the wrong shape.
856
- // ⭐ WHAT ITS PAGES MAY HOLD, not how the files hold them: `single-section` where they are a folder-mode
857
- // folder's `.md` files, one section each, else `page`. The mode its PAGES are read in (`childMode`), so
858
- // a page above a mounted folder of `.md` pages says it too, with its own sections. The app reads it to
859
- // offer no second section there. ⛔ Until 2026-11-04 it was the folder's own mode, spelled `folder`.
860
- const mode = f.childMode === 'pages' ? SINGLE_SECTION : 'page'
857
+ // ⭐ THE PAGE'S OWN MODE (`route-mode.js`): `atomic-parent` for a directory in folder mode, which holds
858
+ // no section and whose child pages are its `.md` files and directories; else `regular` — a page above
859
+ // a mounted folder of `.md` pages included, since it holds sections of its own. Its `.md` pages are
860
+ // `atomic` (`folderModePageRecords`). ⛔ Until 2026-11-05 this was what its pages may hold, read from the
861
+ // mode they are read in (`childMode`): `single-section` here, and `page` on the pages under it.
862
+ const mode = f.internalMode === 'pages' ? ATOMIC_PARENT : REGULAR
861
863
  const slugPath = parentSlugPath ? `${parentSlugPath}/${slug}` : slug
862
864
 
863
865
  const data = buildPageData(f.config, {