@uniweb/build 1.15.6 → 1.16.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.
@@ -8,10 +8,10 @@
8
8
  // in the app was undone by the next push.
9
9
  //
10
10
  // The pages a pull leaves alone are now those it may not or cannot write:
11
- // · every page under a read-only `paths: { pages/<segment>: <dir> }` mount — any the site does not
12
- // declare `writable: true`, or whose folder the caller may not write (`writable`). Its files are
13
- // another repository's, or a folder outside the site; the local folder of that name holds only how
14
- // this site presents them, and a pull writing the mounted pages into it would grow a second copy;
11
+ // · every page under a `paths: { pages/<segment>: <dir> }` mount the caller may not write
12
+ // (`writable`) — for a pull, one it cannot merge into: a clone beside the site, a folder in no
13
+ // repository. The local folder of that name holds only how this site presents the mount's pages,
14
+ // and a pull writing them into it would grow a second copy there;
15
15
  // · a route the files give two pages for — a file and a folder of one name, `topics.md` beside
16
16
  // `topics/` — since a page in the document cannot say which of the two it is.
17
17
  // A pull deletes neither, nor a folder that holds one (`holds`): a pull never deletes what it does not
@@ -23,7 +23,7 @@
23
23
  //
24
24
  // A leaf, read synchronously as the pull projects (`site-project.js`), through the rules the push's
25
25
  // walk reads with — `folderContentMode`, `folderModePageFiles`, `parseNumericPrefix`,
26
- // `layerMountedFolder`, `mountDeclarationsOf` — so the pages it finds are the ones the push sends
26
+ // `layerMountedFolder`, `mountEntriesOf` — so the pages it finds are the ones the push sends
27
27
  // (`tests/uwx-page-files.test.js`).
28
28
 
29
29
  import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from 'node:fs'
@@ -32,7 +32,7 @@ import yaml from 'js-yaml'
32
32
  import { YAML_OPTIONS } from '../utils/yaml-schema.js'
33
33
  import { isIgnoredFolder } from '../utils/content-files.js'
34
34
  import { extractH1, folderContentMode, folderModePageFiles, layerMountedFolder, parseNumericPrefix, prettifySlug } from '../site/content-collector.js'
35
- import { mountDeclarationsOf } from '../site/mount-entries.js'
35
+ import { mountEntriesOf } from '../site/mount-entries.js'
36
36
  import { unwrapLocalized } from './backfill.js'
37
37
  import { isProseMirrorDoc } from './locale-sync.js'
38
38
 
@@ -99,7 +99,7 @@ const isDirectory = (p) => {
99
99
  * @param {{ seen?: Set<string>|null, siteRoot?: string|null, writable?: Iterable<string>|null }} [opts] -
100
100
  * `seen`, the routes of the pages this copy has seen the backend hold: a folder holding an `.md`
101
101
  * page it never saw is one a prune keeps (`holds`). `writable`, the segments of the mounts the
102
- * caller may write — each one the site declares `writable: true` is walked into, from `siteRoot`
102
+ * caller may write, each walked into from `siteRoot`
103
103
  * @returns {{
104
104
  * page: (route: string) => object|null,
105
105
  * levelMode: (dir: string) => 'pages'|'sections'|undefined,
@@ -110,17 +110,17 @@ const isDirectory = (p) => {
110
110
  * mount's segment and folder
111
111
  */
112
112
  export function sitePageFiles(siteYml, pagesDir, { seen = null, siteRoot = null, writable = null } = {}) {
113
- const declared = mountDeclarationsOf(siteYml?.paths)
114
- const mounted = new Set(declared.map((d) => d.segment))
115
- // ⭐ A mount is written only where the site declares it `writable: true` AND the caller may write
116
- // its folder — a pull decides that by the repository holding it, and any other caller writes none.
113
+ const declared = mountEntriesOf(siteYml?.paths)
114
+ const mounted = new Set(declared.map(([segment]) => segment))
115
+ // ⭐ A mount is written where the caller may write its folder — a pull decides that by the repository
116
+ // holding it — and any other caller writes none.
117
117
  const allowed = new Set(writable ?? [])
118
118
  const writableMounts = new Map()
119
- for (const d of declared) {
120
- if (!d.writable || !allowed.has(d.segment) || !siteRoot || typeof d.path !== 'string' || !d.path) continue
119
+ for (const [segment, folder] of declared) {
120
+ if (!allowed.has(segment) || !siteRoot || typeof folder !== 'string' || !folder) continue
121
121
  // The folder as the push reads it: through any link to it (`resolveMounts`).
122
- const dir = resolve(siteRoot, d.path)
123
- writableMounts.set(d.segment, existsSync(dir) ? realpathSync(dir) : dir)
122
+ const dir = resolve(siteRoot, folder)
123
+ writableMounts.set(segment, existsSync(dir) ? realpathSync(dir) : dir)
124
124
  }
125
125
  const places = new Map()
126
126
  const modes = new Map()
@@ -21,6 +21,7 @@ import { parseFrontmatter } from './entity-source.js'
21
21
  import { canonicalJson, sameMarkdownDocument } from './same-content.js'
22
22
  import { spliceBody } from './body-splice.js'
23
23
  import { fileLinksIn } from '../site/file-links.js'
24
+ import { parseNumericPrefix } from '../utils/numeric-prefix.js'
24
25
  import { renderEntityDocument } from './backfill.js'
25
26
  import { queriesYmlPath } from './queries-config.js'
26
27
  import { folderYmlPath } from '../site/records-config.js'
@@ -90,8 +91,9 @@ export function resolveSectionFile(dirPath, stableId) {
90
91
  let name = base.startsWith('@') ? base.slice(1) : base
91
92
  if (name.toLowerCase() === target) return join(dirPath, entry)
92
93
 
93
- const numMatch = name.match(/^\d+-(.+)$/)
94
- if (numMatch && numMatch[1].toLowerCase() === target) return join(dirPath, entry)
94
+ // Its name with the number that orders it dropped, by the one rule: `2.5-setup.md` is `setup`.
95
+ const numbered = parseNumericPrefix(name)
96
+ if (numbered.prefix && numbered.name.toLowerCase() === target) return join(dirPath, entry)
95
97
  }
96
98
  return null
97
99
  }
@@ -302,6 +304,15 @@ function writeYamlIfChanged(filePath, value, prior) {
302
304
 
303
305
  const isPlainObject = (v) => Boolean(v) && typeof v === 'object' && !Array.isArray(v)
304
306
 
307
+ /**
308
+ * Write `site.yml`'s `paths:` whole, its comments and layout kept; with no entry left it goes. A
309
+ * mounted route renamed or removed in the app renames or removes its key (`site-project.js`).
310
+ * @returns {'updated'|'unchanged'}
311
+ */
312
+ export function writeSitePaths(siteRoot, paths) {
313
+ return mergeYamlConfig(join(siteRoot, 'site.yml'), { paths: paths && Object.keys(paths).length ? paths : null }, { replace: ['paths'] })
314
+ }
315
+
305
316
  /**
306
317
  * Merge `config` into `site.yml` (shallow). Preserves keys not present in the
307
318
  * update (foundation, base, paths, …).
@@ -0,0 +1,18 @@
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.
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.
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`).
15
+ *
16
+ * A leaf, with no imports.
17
+ */
18
+ export const SINGLE_SECTION = 'single-section'
@@ -49,6 +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
53
 
53
54
  // A unit's own content, with the nested collections that are their own units
54
55
  // removed — so editing a section never also marks its page (or its parent
@@ -112,8 +113,12 @@ export function walkSiteUnits(doc, cb, sourceLocale = documentSourceLocale(doc))
112
113
  const dirName = pageDirName(record, sourceLocale)
113
114
  if (!dirName) continue
114
115
  const dir = `${parentDir}/${dirName}`
115
- cb(`${dir}/${record.mode === 'folder' ? 'folder.yml' : 'page.yml'}`, record, 'page')
116
- if (record.mode !== 'folder') walkSections(record.page_sections, dir)
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')
121
+ walkSections(record.page_sections, dir)
117
122
  walkPages(record.$children, dir)
118
123
  }
119
124
  }
@@ -35,7 +35,7 @@
35
35
 
36
36
  import { foldOpenGraph } from './open-graph.js'
37
37
  import { isAuthoredPreview } from './authored-preview.js'
38
- import { join, relative, extname, basename, dirname, parse } from 'node:path'
38
+ import { join, relative, extname, basename, dirname, parse, sep } from 'node:path'
39
39
  import { restoreAssetRefs } 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'
@@ -46,9 +46,11 @@ import { isMarkdownFile, isIgnoredFolder } from '../utils/content-files.js'
46
46
  import { createHash } from 'node:crypto'
47
47
  import yaml from 'js-yaml'
48
48
  import { YAML_OPTIONS } from '../utils/yaml-schema.js'
49
- import { writeSiteConfig, writeThemeFile, writeIfChanged, writeSectionFile, writeMergedYaml } from './project-writer.js'
49
+ import { writeSiteConfig, writeSitePaths, writeThemeFile, writeIfChanged, writeSectionFile, writeMergedYaml } from './project-writer.js'
50
+ import { mountEntriesOf } from '../site/mount-entries.js'
50
51
  import { declarationsToQueriesYml } from './records-project.js'
51
52
  import { buildRouteOf } from './site.js'
53
+ import { SINGLE_SECTION } from './route-mode.js'
52
54
  import { fileLinkTargets } from '../site/file-links.js'
53
55
  import { DEFAULT_SECTION_TYPE } from '@uniweb/core/section-type'
54
56
  import { translationContext, SITE_META_CONTEXT } from '../i18n/extract.js'
@@ -101,10 +103,18 @@ function renameInPlace(from, to, report) {
101
103
  // Place the item identified by `uuid` at `targetAbs`: if the index recorded it at
102
104
  // a different path, relocate it there first (git-mv-style), then record its new
103
105
  // path in the fresh index. No-op without a ctx (standalone callers / no uuid).
104
- function placeByUuid(ctx, uuid, targetAbs) {
106
+ //
107
+ // ⛔ Only a file to a file, and a folder to a folder: a page moved between a folder-mode `.md` file and
108
+ // a page folder changes its form, so it is written new where it lands and its old form pruned. Until
109
+ // 2026-11-04 the `.md` file was renamed to the page folder's path, and the pull stopped on it (ENOTDIR).
110
+ function placeByUuid(ctx, uuid, targetAbs, { folder = false } = {}) {
105
111
  if (!ctx || !uuid) return
106
112
  const oldRel = ctx.oldIndex[uuid]
107
- if (oldRel) renameInPlace(join(ctx.siteRoot, oldRel), targetAbs, ctx.report)
113
+ const from = oldRel ? join(ctx.siteRoot, oldRel) : null
114
+ if (from && existsSync(from)) {
115
+ if (statSync(from).isDirectory() === folder) renameInPlace(from, targetAbs, ctx.report)
116
+ else if (from !== targetAbs) ctx.formerly?.add(from) // its old form, for the prune to take
117
+ }
108
118
  ctx.newIndex[uuid] = relative(ctx.siteRoot, targetAbs)
109
119
  }
110
120
 
@@ -884,13 +894,13 @@ function nestSays(nest, list) {
884
894
  // now, which is also what the layout prune below already did.
885
895
 
886
896
  // Delete the section files in `pageDir` whose stableId isn't in `keep`.
887
- function pruneOrphanSectionFiles(pageDir, keep, report) {
897
+ function pruneOrphanSectionFiles(pageDir, keep, report, kept = null) {
888
898
  if (!existsSync(pageDir)) return
889
899
  for (const entry of readdirSync(pageDir)) {
890
900
  if (!isMarkdownFile(entry)) continue
891
901
  if (keep.has(basename(entry, extname(entry)))) continue
892
902
  const p = join(pageDir, entry)
893
- if (!statSync(p).isFile()) continue
903
+ if (kept?.has(p) || !statSync(p).isFile()) continue
894
904
  unlinkSync(p)
895
905
  report.deleted.push(p)
896
906
  }
@@ -908,9 +918,10 @@ function pruneOrphanPageFiles(levelDir, keep, report, routePrefix, ctx) {
908
918
  return
909
919
  }
910
920
  for (const { file, name } of folderModePageFiles(entries).files) {
911
- if (keep.has(file)) continue
921
+ if (keep.has(file) || ctx?.kept?.has(join(levelDir, file))) continue
912
922
  const route = routePrefix ? `${routePrefix}/${name}` : name
913
- if (!ctx?.seen?.has(route)) continue
923
+ // A page the app moved out of this level as a page folder is its old form, seen or not (`placeByUuid`).
924
+ if (!ctx?.seen?.has(route) && !ctx?.formerly?.has(join(levelDir, file))) continue
914
925
  const p = join(levelDir, file)
915
926
  if (!statSync(p).isFile()) continue
916
927
  unlinkSync(p)
@@ -956,17 +967,49 @@ function projectPages(pages, pagesDir, sourceLocale, report, prune, ctx) {
956
967
  // level cannot hold as a file is not written there (`cannot`): a page folder below it, with nothing in
957
968
  // its `page.yml`, is read in folder mode, its sections as pages. A folder-mode folder is a folder.
958
969
  // ⛔ Until 2026-11-04 every page went to its slug's folder: `pages/2-about/` came back as `about/`.
970
+ //
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`.
959
974
  function placeOf(ctx, record, route, levelDir, levelMode, sourceLocale) {
960
975
  const found = ctx.files?.page(route)
961
976
  if (found) return found
962
- if (levelMode === 'pages' && record.mode !== 'folder' && !record.is_dynamic) {
963
- const name = unwrapLocalized(record.slug, sourceLocale)
964
- const what = mdPageCannotHold(record, { name, sourceLocale })
965
- return what.length ? { kind: 'cannot', what } : { kind: 'md', file: join(levelDir, `${name}.md`), dir: levelDir }
977
+ 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' : record.mode !== SINGLE_SECTION) {
981
+ const name = unwrapLocalized(record.slug, sourceLocale)
982
+ const what = mdPageCannotHold(record, { name, sourceLocale })
983
+ return what.length ? { kind: 'cannot', what } : { kind: 'md', file: join(levelDir, `${name}.md`), dir: levelDir }
984
+ }
966
985
  }
967
986
  return { kind: 'folder', dir: join(levelDir, pageDirName(record, sourceLocale)) }
968
987
  }
969
988
 
989
+ // The form the files kept a route in before the app moved it, by the rename index this copy wrote: an
990
+ // `.md` page (`md`), or a folder read in folder mode (`pages`) or page mode (`sections`) where it was.
991
+ // Null for a route new to them. Read before the move (`placeByUuid`), which takes the old place away.
992
+ function oldForm(ctx, record) {
993
+ const rel = record?.$uuid ? ctx?.oldIndex?.[record.$uuid] : null
994
+ const old = rel ? join(ctx.siteRoot, rel) : null
995
+ if (!old || !existsSync(old)) return null
996
+ if (!statSync(old).isDirectory()) return 'md'
997
+ return folderModeOf(old, ctx.files?.levelMode(dirname(old)) ?? 'sections')
998
+ }
999
+
1000
+ // ⭐ A FOLDER'S FORM IS ITS FILES' WHERE THEY HOLD IT — folder mode (`pages`) or page mode (`sections`):
1001
+ // a mount's route by the mount, a folder the files hold by its own config, one the app moved by the form
1002
+ // it had. Only a route new to the files takes the form its `mode` asks for, a route the app made. ⛔ Until
1003
+ // 2026-11-04 every folder took its `mode`'s form, so a stored route in another spelling would have had
1004
+ // a `page.yml` written beside its `folder.yml`.
1005
+ function formOf(ctx, record, route, place, levelMode) {
1006
+ if (place.mount) return place.mount.mode
1007
+ if (ctx.files?.page(route) === place) return ctx.files.levelMode(place.dir) ?? folderModeOf(place.dir, levelMode)
1008
+ const was = oldForm(ctx, record)
1009
+ if (was === 'pages' || was === 'sections') return was
1010
+ return record.mode === SINGLE_SECTION ? 'pages' : 'sections'
1011
+ }
1012
+
970
1013
  // ⭐ A FOLDER-MODE `.md` PAGE, WRITTEN BACK IN PLACE: the file is the page and its one section, so the
971
1014
  // section is written into it as any section file is (`sectionRecordToFile`) — its text, its params —
972
1015
  // and its frontmatter's `hidden:` says the page's. One the file cannot hold (`mdPageCannotHold`) is
@@ -1027,16 +1070,14 @@ function writePagesTree(pages, pagesDir, sourceLocale, report, ctx, routePrefix
1027
1070
  const slug = unwrapLocalized(record.slug, sourceLocale) // localized {lang:value} → canonical
1028
1071
  const route = routePrefix ? `${routePrefix}/${slug}` : slug
1029
1072
  let place = placeOf(ctx, record, route, pagesDir, levelMode, sourceLocale)
1030
- // ⛔ A writable mount's route takes its form from its files: one the app made a page where they keep
1031
- // a folder, or the reverse, cannot be written — its pages are the shape that form gives them.
1032
- if (place.mount && record.mode !== (place.mount.mode === 'pages' ? 'folder' : 'page')) {
1033
- place = { kind: 'cannot', what: [record.mode === 'folder' ? 'a folder where its files keep a page' : 'a page where its files keep a folder'] }
1034
- }
1073
+ // A mount's own route the files cannot say where the app put it (`followMountRoutes`).
1074
+ if (ctx.heldMounts?.has(record.$uuid)) place = { kind: 'cannot', what: ['a mounted route where a mount cannot sit, or by a name another page holds'] }
1035
1075
  ctx.places?.set(record, place)
1036
1076
  // ⭐ A PAGE THE PULL MAY NOT OR CANNOT WRITE IS LEFT ALONE — a mount's, a route the files give two
1037
1077
  // pages for (`page-files.js`), a page its folder-mode level cannot hold as a file. Its children too:
1038
1078
  // a mount's are the mount's.
1039
1079
  if (place.kind === 'mounted' || place.kind === 'twice' || place.kind === 'cannot') {
1080
+ keepWhereTheFilesAre(ctx, subtreeUuids(record))
1040
1081
  report.leftAlone?.push(...subtreeRoutes(record, route, sourceLocale))
1041
1082
  // ⭐ Each with its items, for the pull to bank by its outcome: a mount's page lets the folder win, and
1042
1083
  // one the files cannot hold is held at the version this copy last agreed on.
@@ -1078,18 +1119,29 @@ function writePagesTree(pages, pagesDir, sourceLocale, report, ctx, routePrefix
1078
1119
  // ⭐ A writable mount's own route is where the site's `paths:` puts it, never where a rename index
1079
1120
  // last saw it: no move is made, and none recorded.
1080
1121
  const mount = place.mount ?? null
1122
+ // Its form, read before the move takes its old place away.
1123
+ const form = formOf(ctx, record, route, place, levelMode)
1124
+ ctx.forms?.set(record, form)
1081
1125
  // Relocate the whole page dir if this uuid moved to a new slug, then record it.
1082
- if (!mount) placeByUuid(ctx, record.$uuid, pageDir)
1126
+ if (!mount) placeByUuid(ctx, record.$uuid, pageDir, { folder: true })
1083
1127
 
1084
1128
  let sectionsArray = []
1085
1129
  let filesGiveOrder = false
1086
1130
  let filesGiveTopOrder = false
1087
- if (record.mode === 'page' && Array.isArray(record.page_sections)) {
1131
+ if (form === 'sections' && Array.isArray(record.page_sections)) {
1088
1132
  const r = pageSectionsToFiles({ pageDir, pageSections: record.page_sections, ctx, pageContext })
1089
1133
  sectionsArray = r.sections
1090
1134
  filesGiveOrder = r.filesGiveOrder
1091
1135
  filesGiveTopOrder = r.filesGiveTopOrder
1092
1136
  report.sections.push(...r.written)
1137
+ } else if (Array.isArray(record.page_sections) && record.page_sections.length) {
1138
+ // ⛔ A route of single-section pages holds no section of its own: its folder's `.md` files are its
1139
+ // pages. One the app gives it is held, and the route and its pages are written as they are. Until
1140
+ // 2026-11-04 it was dropped, and the next push removed it from the site.
1141
+ const uuids = record.page_sections.flatMap((s) => subtreeUuids(s))
1142
+ keepWhereTheFilesAre(ctx, uuids)
1143
+ report.held?.push({ route, uuids, what: ['a section, which a route of single-section pages holds none of'] })
1144
+ report.leftAlone?.push(route)
1093
1145
  }
1094
1146
 
1095
1147
  if (mount) {
@@ -1104,7 +1156,7 @@ function writePagesTree(pages, pagesDir, sourceLocale, report, ctx, routePrefix
1104
1156
  continue
1105
1157
  }
1106
1158
 
1107
- const ymlName = record.mode === 'folder' ? 'folder.yml' : 'page.yml'
1159
+ const ymlName = form === 'pages' ? 'folder.yml' : 'page.yml'
1108
1160
  const ymlPath = join(pageDir, ymlName)
1109
1161
  // Merge (not full-dump) so author-added keys survive a pull; the projector
1110
1162
  // owns only PAGE_YML_MANAGED_KEYS.
@@ -1113,8 +1165,10 @@ function writePagesTree(pages, pagesDir, sourceLocale, report, ctx, routePrefix
1113
1165
  const yml = pageRecordToYml(record, sectionsArray, sourceLocale, existing, { isRoot: !routePrefix, slug: pageSlug, filesGiveOrder, filesGiveTopOrder })
1114
1166
  // ⭐ A `page.yml` with nothing to say is not created: the build reads an empty one as none
1115
1167
  // (`content-collector.js::readFolderConfig`). ⛔ Until 2026-10-08 a pull wrote `{}` into every page
1116
- // whose folder had none. An empty `folder.yml` is written still — its presence is folder mode.
1117
- if (ymlName === 'page.yml' && Object.keys(yml).length === 0 && !existsSync(ymlPath)) {
1168
+ // whose folder had none. An empty `folder.yml` is written only where its presence is what puts the
1169
+ // folder in folder mode: not in a folder-mode level, where the folder is in folder mode without it.
1170
+ // ⛔ Until 2026-11-04 a pull of what was pushed wrote one into every such folder.
1171
+ if (Object.keys(yml).length === 0 && !existsSync(ymlPath) && (ymlName === 'page.yml' || levelMode === 'pages')) {
1118
1172
  writePagesTree(record.$children || [], pageDir, sourceLocale, report, ctx, route, parentOrderList(ymlPath), canon, folderModeOf(pageDir, levelMode))
1119
1173
  continue
1120
1174
  }
@@ -1141,6 +1195,111 @@ function subtreeUuids(record) {
1141
1195
  return out
1142
1196
  }
1143
1197
 
1198
+ // ⭐ WHAT A PULL LEAVES ALONE STAYS WHERE THE FILES KEEP IT. A page the app moved where the files cannot
1199
+ // hold it is not written there, so its files at the old place are the files' version of it, and the prune
1200
+ // must keep them: found by the rename index this copy wrote, else, for a page, by the route its sync state
1201
+ // last saw it at (`ctx.itemRoutes`). ⛔ Until 2026-11-04 the prune took them: a page of two sections moved
1202
+ // into a folder of single-section pages was held there and deleted where it was.
1203
+ function keepWhereTheFilesAre(ctx, uuids) {
1204
+ if (!ctx?.kept) return
1205
+ for (const uuid of uuids) {
1206
+ const old = ctx.oldIndex[uuid]
1207
+ if (old) {
1208
+ ctx.kept.add(join(ctx.siteRoot, old))
1209
+ ctx.newIndex[uuid] ??= old
1210
+ continue
1211
+ }
1212
+ const route = ctx.itemRoutes?.get(uuid)
1213
+ const place = route == null ? null : ctx.files?.page(route)
1214
+ if (place?.kind === 'md') ctx.kept.add(place.file)
1215
+ else if (place?.dir) ctx.kept.add(place.dir)
1216
+ }
1217
+ }
1218
+
1219
+ // Whether a folder is, or holds, a path the prune must keep (`keepWhereTheFilesAre`).
1220
+ function holdsKept(ctx, dir) {
1221
+ for (const path of ctx?.kept ?? []) if (path === dir || path.startsWith(dir + sep)) return true
1222
+ return false
1223
+ }
1224
+
1225
+ // Each page's route by its item, as this copy's sync state last saw it: `pages/<route>/page.yml` (or
1226
+ // `folder.yml`), a parametric segment by its name, as `seenPageRoutes` reads them.
1227
+ function itemRoutesOf(items) {
1228
+ const out = new Map()
1229
+ for (const [key, uuid] of Object.entries(items || {})) {
1230
+ const m = key.match(/^pages\/(.+)\/(?:page|folder)\.yml$/)
1231
+ if (m && typeof uuid === 'string') out.set(uuid, m[1].split('/').map((seg) => seg.match(/^\[(.+)\]$/)?.[1] ?? seg).join('/'))
1232
+ }
1233
+ return out
1234
+ }
1235
+
1236
+ // A mount's segment, as `resolveMounts` takes one: a simple name, with no dot or underscore before it.
1237
+ const MOUNT_SEGMENT = /^[^/._][^/]*$/
1238
+
1239
+ /**
1240
+ * ⭐ A MOUNT'S OWN ROUTE, RENAMED OR REMOVED IN THE APP, is said where the files say that route: its
1241
+ * key in `site.yml`'s `paths:`, and its local folder. Renamed, both follow; removed, the mount leaves
1242
+ * the site, its key and its local folder, where the pull prunes. The mounted folder is never touched:
1243
+ * nothing asked for its files to go, and `paths:` still points where it did. A route the files cannot
1244
+ * say — moved below another page, where a mount cannot sit, or renamed to a name another page holds —
1245
+ * is held whole. The route is known by its item, as the backend knows it (`sync.json`'s `items`), so
1246
+ * one this copy never saw is no mount's.
1247
+ * ⛔ Until 2026-11-04 a renamed one was written as a new page of the site's own: a copy of every
1248
+ * mounted page beside the mount, under the new name, which the next push sent too. A removed one was
1249
+ * left, and the next push put it back.
1250
+ *
1251
+ * @returns {{ siteYml: object, renamed: Map<string, string>, held: Set<string> }} the site config as it
1252
+ * now stands, each mount's segment renamed to its new one, and the items of the routes held
1253
+ */
1254
+ function followMountRoutes({ siteRoot, siteYml, pagesDir, document, backend, sourceLocale, prune, report }) {
1255
+ const out = { siteYml, renamed: new Map(), held: new Set() }
1256
+ const declared = mountEntriesOf(siteYml?.paths)
1257
+ const items = backend ? readBackendState(siteRoot, backend).items || {} : {}
1258
+ if (!declared.length || !Object.keys(items).length) return out
1259
+ const roots = document?.pages || []
1260
+ const slugOf = (record) => unwrapLocalized(record?.slug, sourceLocale)
1261
+ const anywhere = (records, uuid) => (records || []).some((r) => r?.$uuid === uuid || anywhere(r?.$children, uuid))
1262
+ let paths = { ...siteYml.paths }
1263
+ let changed = false
1264
+ for (const [segment] of declared) {
1265
+ if (roots.some((r) => slugOf(r) === segment)) continue // where it was
1266
+ const uuid = items[`pages/${segment}/folder.yml`] ?? items[`pages/${segment}/page.yml`]
1267
+ if (typeof uuid !== 'string') continue
1268
+ const record = roots.find((r) => r?.$uuid === uuid)
1269
+ const stub = join(pagesDir, segment)
1270
+ if (record) {
1271
+ const to = slugOf(record)
1272
+ if (typeof to !== 'string' || !MOUNT_SEGMENT.test(to) || `pages/${to}` in paths || existsSync(join(pagesDir, to))) {
1273
+ out.held.add(uuid)
1274
+ continue
1275
+ }
1276
+ // The key renamed where it stands, its value as written.
1277
+ paths = Object.fromEntries(Object.entries(paths).map(([key, value]) => [key === `pages/${segment}` ? `pages/${to}` : key, value]))
1278
+ if (existsSync(stub)) {
1279
+ renameSync(stub, join(pagesDir, to))
1280
+ report.renamed.push({ from: stub, to: join(pagesDir, to) })
1281
+ }
1282
+ out.renamed.set(segment, to)
1283
+ report.mountRoutes.push({ from: segment, to })
1284
+ changed = true
1285
+ } else if (anywhere(roots, uuid)) {
1286
+ out.held.add(uuid)
1287
+ } else if (prune) {
1288
+ delete paths[`pages/${segment}`]
1289
+ if (existsSync(stub)) {
1290
+ rmSync(stub, { recursive: true, force: true })
1291
+ report.deleted.push(stub)
1292
+ }
1293
+ report.mountRoutes.push({ from: segment, to: null })
1294
+ changed = true
1295
+ }
1296
+ }
1297
+ if (!changed) return out
1298
+ writeSitePaths(siteRoot, paths)
1299
+ out.siteYml = readAuthoredYaml(join(siteRoot, 'site.yml'))
1300
+ return out
1301
+ }
1302
+
1144
1303
  // ⭐ THE PAGES THE SITE'S FILES ARE, for the links a file writes as files (`site/file-links.js`): each page
1145
1304
  // of the document at the files the file map keeps it in — an `.md` page's own, a page folder's section
1146
1305
  // files as the writer finds them — so a pull reads a file's links as the push does, and writes them back
@@ -1157,7 +1316,7 @@ function pageFileTargets(ctx, pages, sourceLocale) {
1157
1316
  if (place?.kind === 'md' && record.page_sections?.length === 1) {
1158
1317
  const section = record.page_sections[0]
1159
1318
  files.push({ file: place.file, id: recordStableId(section), content: contentOf(section) })
1160
- } else if (place?.kind === 'folder' && record.mode === 'page') {
1319
+ } else if (place?.kind === 'folder' && (place.mount ? place.mount.mode : ctx.files.levelMode(place.dir)) === 'sections') {
1161
1320
  const bases = sectionFileBases(record.page_sections || [])
1162
1321
  const visit = (list, child) => {
1163
1322
  for (const section of list || []) {
@@ -1283,7 +1442,7 @@ function reconcileLevelOrder({ pages, pagesDir, sourceLocale, list, homepage = n
1283
1442
  return { md: false, dirName: place.mount.segment, name: place.mount.segment, readOrder: () => config.read().order, writeOrder: (n) => config.write({ order: n }) }
1284
1443
  }
1285
1444
  const dirName = place?.kind === 'folder' ? basename(place.dir) : pageDirName(r, sourceLocale)
1286
- const yml = join(pagesDir, dirName, r.mode === 'folder' ? 'folder.yml' : 'page.yml')
1445
+ const yml = join(pagesDir, dirName, ctx?.forms?.get(r) === 'pages' ? 'folder.yml' : 'page.yml')
1287
1446
  return { md: false, dirName, name: parseNumericPrefix(dirName).name, readOrder: () => readAuthoredYaml(yml)?.order, writeOrder: (n) => writeMergedYaml(yml, { order: n }, ['order']) }
1288
1447
  })
1289
1448
  if (level.length < 2) return
@@ -1389,15 +1548,22 @@ function prunePagesTree(pages, pagesDir, sourceLocale, report, ctx = null, route
1389
1548
  // Left alone by pass 1 — and an `.md` page has nothing below it — so nothing of it is pruned.
1390
1549
  if (place.kind !== 'folder') continue
1391
1550
  const pageDir = place.dir
1392
- if (record.mode === 'page') {
1551
+ if (ctx?.forms?.get(record) === 'sections') {
1393
1552
  // The files pass 1 wrote into — the author's own names among them — else the names it would give.
1394
1553
  const keep = ctx?.sectionFiles?.get(pageDir) || collectSectionFileBases(record.page_sections)
1395
- if (keep.size > 0) pruneOrphanSectionFiles(pageDir, keep, report)
1554
+ if (keep.size > 0) pruneOrphanSectionFiles(pageDir, keep, report, ctx?.kept)
1396
1555
  }
1397
1556
  // A writable mount's pages are in the mounted folder (`page-files.js`).
1398
1557
  if (place.mount) prunePagesTree(record.$children || [], place.mount.dir, sourceLocale, report, ctx, route, place.mount.childMode)
1399
1558
  else prunePagesTree(record.$children || [], pageDir, sourceLocale, report, ctx, route, folderModeOf(pageDir, levelMode))
1400
1559
  }
1560
+ // A page the app moved that changed form, as this level kept it (`placeByUuid`): it goes, even from a
1561
+ // level left with no page of its own, since the page itself was written where it lands.
1562
+ for (const p of ctx?.formerly ?? []) {
1563
+ if (dirname(p) !== pagesDir || !existsSync(p) || holdsKept(ctx, p) || ctx.files?.holds?.(p)) continue
1564
+ rmSync(p, { recursive: true, force: true })
1565
+ report.deleted.push(p)
1566
+ }
1401
1567
  if (incomingDirs.size === 0 && incomingFiles.size === 0) return
1402
1568
  if (levelMode === 'pages') pruneOrphanPageFiles(pagesDir, incomingFiles, report, routePrefix, ctx)
1403
1569
  // A mounted route's local folder is never an orphan, whatever the document holds: what it
@@ -1405,7 +1571,7 @@ function prunePagesTree(pages, pagesDir, sourceLocale, report, ctx = null, route
1405
1571
  if (!routePrefix) for (const segment of ctx?.files?.mounted ?? []) incomingDirs.add(segment)
1406
1572
  // ⛔ Nor is a folder that holds a folder-mode page, whatever the document holds: until 2026-11-04 a
1407
1573
  // document without that folder's own page removed it whole, its `.md` pages with it.
1408
- pruneOrphanPageDirs(pagesDir, incomingDirs, report, (dir) => Boolean(ctx?.files?.holds?.(dir)))
1574
+ pruneOrphanPageDirs(pagesDir, incomingDirs, report, (dir) => Boolean(ctx?.files?.holds?.(dir)) || holdsKept(ctx, dir))
1409
1575
  }
1410
1576
 
1411
1577
  /**
@@ -1685,16 +1851,16 @@ function seenPageRoutes(items) {
1685
1851
  * @param {string} [params.sectionType] - the type a section that names none renders with on this
1686
1852
  * site, which the push filled in and a section's file leaves out — `siteDefaultSectionType`,
1687
1853
  * read by the caller since it reads the foundation's source
1688
- * @param {string[]} [params.writableMounts] - the segments of the mounts the caller may write into. A
1689
- * mount is written only where the site declares it `writable: true` and it is named here — a
1690
- * pull names those the site's repository holds — so a caller that names none writes no mount
1854
+ * @param {string[]} [params.writableMounts] - the segments of the mounts the caller may write into: a
1855
+ * pull names each one it can merge into, a folder of the site's repository or of a submodule.
1856
+ * A caller that names none writes no mount
1691
1857
  * @returns {{ config: object, collections: object, locales: object, pages: string[], sections: string[], layout: string[], deleted: string[], renamed: object[] }}
1692
1858
  */
1693
1859
  export function siteContentDocumentToProject({ document, siteRoot, backend = null, sourceLocale = documentSourceLocale(document), prune = false, keepAuthoredFoundation = false, scope, dataModel = null, sectionType = DEFAULT_SECTION_TYPE, writableMounts = [] }) {
1694
1860
  // Before anything is written: a pull that would leave content out of the files stops here.
1695
1861
  refuseContentFilesCannotHold(document, sourceLocale)
1696
1862
 
1697
- const report = { config: null, collections: null, locales: null, assets: null, pages: [], sections: [], layout: [], deleted: [], renamed: [], leftAlone: [], held: [], mountedPages: [] }
1863
+ const report = { config: null, collections: null, locales: null, assets: null, pages: [], sections: [], layout: [], deleted: [], renamed: [], leftAlone: [], held: [], mountedPages: [], mountRoutes: [] }
1698
1864
 
1699
1865
  // Collects target-locale translations of localized scalars as they're projected;
1700
1866
  // flushed to locales/{locale}.json at the end (the manifest stays derivable).
@@ -1734,15 +1900,26 @@ export function siteContentDocumentToProject({ document, siteRoot, backend = nul
1734
1900
 
1735
1901
  // Where the tree goes is what this project's own `site.yml` says — the file the next push and the
1736
1902
  // build read, and one a document never writes `paths` into. See `siteContentDirs`.
1737
- const siteYml = readAuthoredYaml(join(siteRoot, 'site.yml'))
1903
+ let siteYml = readAuthoredYaml(join(siteRoot, 'site.yml'))
1738
1904
  const { pagesDir, layoutDir: layoutBaseDir } = siteContentDirs(siteRoot, siteYml)
1905
+ // A mount's own route renamed or removed in the app, said in `paths:` before any page is placed.
1906
+ const mountRoutes = followMountRoutes({ siteRoot, siteYml, pagesDir, document, backend, sourceLocale, prune, report })
1907
+ siteYml = mountRoutes.siteYml
1908
+ ctx.heldMounts = mountRoutes.held
1909
+ // A writable mount stays one under its new name.
1910
+ const writable = (writableMounts || []).map((segment) => mountRoutes.renamed.get(segment) ?? segment)
1739
1911
  // ⭐ WHERE EACH PAGE IS KEPT — found in the files by the build's rules (`page-files.js`), so a page
1740
1912
  // is written where it lives: a numbered folder, a folder-mode `.md` file, a writable mount's folder.
1741
1913
  // A read-only mount's pages, and a route the files give two pages for, are neither written nor
1742
1914
  // pruned. Each record's place, once decided, is the one every pass below reads (`places`).
1743
1915
  // The pages this copy has seen the backend hold, by route: a prune deletes an `.md` page only then.
1744
- ctx.seen = seenPageRoutes(backend ? readBackendState(siteRoot, backend).items : null)
1745
- ctx.files = sitePageFiles(siteYml, pagesDir, { seen: ctx.seen, siteRoot, writable: writableMounts })
1916
+ const items = backend ? readBackendState(siteRoot, backend).items : null
1917
+ ctx.seen = seenPageRoutes(items)
1918
+ ctx.itemRoutes = itemRoutesOf(items)
1919
+ ctx.kept = new Set()
1920
+ ctx.formerly = new Set()
1921
+ ctx.forms = new Map()
1922
+ ctx.files = sitePageFiles(siteYml, pagesDir, { seen: ctx.seen, siteRoot, writable })
1746
1923
  ctx.places = new Map()
1747
1924
  ctx.fileLinks = pageFileTargets(ctx, document?.pages, sourceLocale)
1748
1925
  // The tree a key names its file by: pages and layout wherever `paths:` puts them, and each mount
@@ -1761,7 +1938,7 @@ export function siteContentDocumentToProject({ document, siteRoot, backend = nul
1761
1938
  // A homepage marked `index: true` in its own config — where the push read it (`buildPageData`) —
1762
1939
  // is left marked there alone: a site.yml that names none is not given an `index:` it never had.
1763
1940
  const homePlace = ctx.places.get(home)
1764
- const homeConfig = homePlace?.mount ? mountRouteConfig(homePlace.mount).read() : homePlace?.kind === 'folder' ? readAuthoredYaml(join(homePlace.dir, home.mode === 'folder' ? 'folder.yml' : 'page.yml')) : null
1941
+ const homeConfig = homePlace?.mount ? mountRouteConfig(homePlace.mount).read() : homePlace?.kind === 'folder' ? readAuthoredYaml(join(homePlace.dir, ctx.forms.get(home) === 'pages' ? 'folder.yml' : 'page.yml')) : null
1765
1942
  const marksItself = homeConfig?.index === true
1766
1943
  if (root.homepage !== ctx.homepage && !(marksItself && root.homepage === undefined)) {
1767
1944
  const listed = Array.isArray(root.pages) ? parseWildcardArray(root.pages) : null