@uniweb/build 1.15.5 → 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.
@@ -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 } 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,12 @@ 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'
54
+ import { fileLinkTargets } from '../site/file-links.js'
52
55
  import { DEFAULT_SECTION_TYPE } from '@uniweb/core/section-type'
53
56
  import { translationContext, SITE_META_CONTEXT } from '../i18n/extract.js'
54
57
  import { authorableDeclaration, DECLARATION_KEYS } from '../site/fetch-shapes.js'
@@ -59,10 +62,10 @@ import { unwrapLocalized, unwrapLocalizedList } from './backfill.js'
59
62
  import { LOCALIZED_FIELD_ASSUMPTION } from './localize.js'
60
63
  import { documentLanguages, documentSourceLocale } from './source-locale.js'
61
64
  import { siteContentDirs } from './site-dirs.js'
62
- import { gitAuthoredPages } from './git-authored.js'
65
+ import { sitePageFiles, mdPageCannotHold, folderModeOf } from './page-files.js'
63
66
  import { layoutAreaRoute, readLayoutFolderSync, DEFAULT_LAYOUT } from '../site/layout-folder.js'
64
67
  import { layoutNameKey } from '@uniweb/core/layout-name'
65
- import { orderFolders, rootOrderConfig, parseNumericPrefix, parseWildcardArray, composeLocalizedRoute, stripAtPrefix, compareFilenames } from '../site/content-collector.js'
68
+ import { orderFolders, rootOrderConfig, parseNumericPrefix, parseWildcardArray, composeLocalizedRoute, stripAtPrefix, compareFilenames, folderModePageFiles, folderModeChildren } from '../site/content-collector.js'
66
69
  import { parseFrontmatter } from '../utils/frontmatter.js'
67
70
 
68
71
  // The pull-side identity index: a per-clone, GITIGNORED `uuid → relative path`
@@ -100,10 +103,18 @@ function renameInPlace(from, to, report) {
100
103
  // Place the item identified by `uuid` at `targetAbs`: if the index recorded it at
101
104
  // a different path, relocate it there first (git-mv-style), then record its new
102
105
  // path in the fresh index. No-op without a ctx (standalone callers / no uuid).
103
- 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 } = {}) {
104
111
  if (!ctx || !uuid) return
105
112
  const oldRel = ctx.oldIndex[uuid]
106
- 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
+ }
107
118
  ctx.newIndex[uuid] = relative(ctx.siteRoot, targetAbs)
108
119
  }
109
120
 
@@ -183,7 +194,9 @@ const SETTINGS_TO_SITE_YML = {
183
194
  base: 'base',
184
195
  fetcher: 'fetcher',
185
196
  build: 'build',
186
- paths: 'paths',
197
+ // ⛔ Not `paths`: where this project keeps its files is its own `site.yml`'s to say, never a
198
+ // document's. Mapped until 2026-11-04, a clone took another copy's `paths.pages`, wrote its pages
199
+ // there — outside itself — and pruned what it found.
187
200
  seo: 'seo',
188
201
  layout: 'layout',
189
202
  // ⛔ `search` / `submit` / `assistant` / `tracking` are not here: each service rides
@@ -399,7 +412,7 @@ export function siteInfoToConfig({ document, siteRoot, backend = null, sourceLoc
399
412
  * site (`siteDefaultSectionType`), which a file leaves out
400
413
  * @returns {'updated'|'unchanged'}
401
414
  */
402
- 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 }) {
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 }) {
403
416
  // ⛔ A stored `preset` or `input` is not written back: neither has an effect, and the build
404
417
  // would only warn about it (2026-09-27).
405
418
  // ⛔ No `background` / `theme_override` / `insets` / `fetch`: the site-content Model dropped all
@@ -445,6 +458,8 @@ export function sectionRecordToFile({ filePath, record, sourceLocale = LOCALIZED
445
458
  params: frontmatter,
446
459
  declaration: paramFetch ?? null,
447
460
  implied: { type: impliedType },
461
+ // The links the file writes as files, as the push reads them (`pageFileTargets`).
462
+ fileLinks,
448
463
  })
449
464
  }
450
465
 
@@ -592,6 +607,7 @@ export function pageSectionsToFiles({ pageDir, pageSections, ctx, pageContext })
592
607
  writeId: fileSectionName(filePath) !== stableId,
593
608
  context: pageContext ? translationContext({ stableId }, pageContext.route) : null,
594
609
  media: ctx?.media ?? null,
610
+ fileLinks: ctx?.fileLinks ?? null,
595
611
  })
596
612
  written.push(filePath)
597
613
  if (!top) childFiles.push(basename(filePath))
@@ -681,6 +697,76 @@ const PAGE_YML_MANAGED_KEYS = new Set([
681
697
  // backend stays in the file.
682
698
  const PAGE_YML_KEPT_KEYS = new Set(['slug'])
683
699
 
700
+ // ⭐ A WRITABLE MOUNT'S OWN ROUTE IS SAID IN TWO FILES, layered as the push reads them
701
+ // (`layerMountedFolder`): the mounted folder's config says what its content is, the site's stub how
702
+ // this site presents it, and the stub's wins where both say one. A pull writes each setting the app
703
+ // changed in the file that says it — the stub's, where both do — and one neither says by what it is:
704
+ // one of these in the mounted folder, any other in the stub. A setting the app removed goes from each
705
+ // file that says it, and the title a route takes from its segment when no file gives one is not a
706
+ // setting, so it is never written.
707
+ const MOUNT_CONTENT_KEYS = new Set(['title', 'description', 'pages', 'sections', 'nest'])
708
+
709
+ /**
710
+ * A writable mount's own route config (`mount`, `page-files.js`), read as the push layers it and
711
+ * written key by key in the file that says each one.
712
+ *
713
+ * ⛔ A file is made only where making it moves nothing: in the mode the route is read in, and never a
714
+ * stub for a route in page mode that has none — its sections are in the mounted folder, and a stub
715
+ * would be where the build reads them from. There the mounted folder's config, the route's only one,
716
+ * takes every setting.
717
+ *
718
+ * @param {object} mount
719
+ * @returns {{ read: () => object, write: (patch: object) => string[] }} `write` takes each key to set,
720
+ * or `undefined` to remove it, and returns the files it changed
721
+ */
722
+ function mountRouteConfig(mount) {
723
+ const fileIn = (dir, read, mode) => join(dir, read && read.source !== 'inherited' ? read.source : mode === 'pages' ? 'folder.yml' : 'page.yml')
724
+ const stubFile = fileIn(mount.stubDir, mount.stub, mount.mode)
725
+ const mountedFile = fileIn(mount.dir, mount.mounted, mount.mounted.mode)
726
+ const stubMayBe = Boolean(mount.stub) || mount.mode === 'pages'
727
+ const said = () => ({ stub: (mount.stub || stubMayBe ? readAuthoredYaml(stubFile) : null) || {}, mounted: readAuthoredYaml(mountedFile) || {} })
728
+ return {
729
+ read() {
730
+ const { stub, mounted } = said()
731
+ return { title: mounted.title || mount.segment, ...mounted, ...stub }
732
+ },
733
+ write(patch) {
734
+ const { stub, mounted } = said()
735
+ const to = { stub: {}, mounted: {} }
736
+ const off = { stub: [], mounted: [] }
737
+ for (const [key, value] of Object.entries(patch)) {
738
+ if (value === undefined) {
739
+ if (key in stub) off.stub.push(key)
740
+ if (key in mounted) off.mounted.push(key)
741
+ continue
742
+ }
743
+ const where = key in stub ? 'stub' : key in mounted || MOUNT_CONTENT_KEYS.has(key) || !stubMayBe ? 'mounted' : 'stub'
744
+ to[where][key] = value
745
+ }
746
+ const wrote = []
747
+ for (const [where, file] of [['stub', stubFile], ['mounted', mountedFile]]) {
748
+ const keys = [...Object.keys(to[where]), ...off[where]]
749
+ if (keys.length && writeMergedYaml(file, to[where], keys) === 'updated') wrote.push(file)
750
+ }
751
+ return wrote
752
+ },
753
+ }
754
+ }
755
+
756
+ // What of a page's config the app changed, against what the files say (`existing`): each managed or
757
+ // kept key whose value differs, and each managed key the record no longer carries, as `undefined`.
758
+ function changedSettings(existing, next) {
759
+ const patch = {}
760
+ for (const key of new Set([...PAGE_YML_MANAGED_KEYS, ...PAGE_YML_KEPT_KEYS, ...Object.keys(next)])) {
761
+ const was = existing?.[key]
762
+ const now = next[key]
763
+ if (now === undefined) {
764
+ if (was !== undefined && PAGE_YML_MANAGED_KEYS.has(key)) patch[key] = undefined
765
+ } else if (stableJson(was) !== stableJson(now)) patch[key] = now
766
+ }
767
+ return patch
768
+ }
769
+
684
770
  // Inverse of site.js buildPageData → the `page.yml` / `folder.yml` object.
685
771
  // `mode`/`is_dynamic`/`param_name` are NOT keys here — they shape the directory
686
772
  // (name, page.yml vs folder.yml, `[param]/`), not the config body. `slug`'s source
@@ -808,25 +894,49 @@ function nestSays(nest, list) {
808
894
  // now, which is also what the layout prune below already did.
809
895
 
810
896
  // Delete the section files in `pageDir` whose stableId isn't in `keep`.
811
- function pruneOrphanSectionFiles(pageDir, keep, report) {
897
+ function pruneOrphanSectionFiles(pageDir, keep, report, kept = null) {
812
898
  if (!existsSync(pageDir)) return
813
899
  for (const entry of readdirSync(pageDir)) {
814
900
  if (!isMarkdownFile(entry)) continue
815
901
  if (keep.has(basename(entry, extname(entry)))) continue
816
902
  const p = join(pageDir, entry)
903
+ if (kept?.has(p) || !statSync(p).isFile()) continue
904
+ unlinkSync(p)
905
+ report.deleted.push(p)
906
+ }
907
+ }
908
+
909
+ // Delete a folder-mode level's `.md` pages that no incoming page is — each its own file — and only one
910
+ // this copy has seen the backend hold (`ctx.seen`, its unit in `sync.json`'s `items`). ⛔ A push before
911
+ // 2026-10-23 sent no folder-mode page, so a backend can lack one the files have always held: read as
912
+ // the app's deletion, it would go. A page folder, and a file the build reads as no page, are not this.
913
+ function pruneOrphanPageFiles(levelDir, keep, report, routePrefix, ctx) {
914
+ let entries
915
+ try {
916
+ entries = readdirSync(levelDir)
917
+ } catch {
918
+ return
919
+ }
920
+ for (const { file, name } of folderModePageFiles(entries).files) {
921
+ if (keep.has(file) || ctx?.kept?.has(join(levelDir, file))) continue
922
+ const route = routePrefix ? `${routePrefix}/${name}` : name
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
925
+ const p = join(levelDir, file)
817
926
  if (!statSync(p).isFile()) continue
818
927
  unlinkSync(p)
819
928
  report.deleted.push(p)
820
929
  }
821
930
  }
822
931
 
823
- // Delete the page directories in `pagesDir` whose name isn't an incoming page dir.
824
- function pruneOrphanPageDirs(pagesDir, keepDirs, report) {
932
+ // Delete the page directories in `pagesDir` whose name isn't an incoming page dir — never one that
933
+ // holds a page a prune must not take (`holds`, `page-files.js`), which would go with it.
934
+ function pruneOrphanPageDirs(pagesDir, keepDirs, report, holds = () => false) {
825
935
  if (!existsSync(pagesDir)) return
826
936
  for (const entry of readdirSync(pagesDir)) {
827
937
  if (isIgnoredFolder(entry) || keepDirs.has(entry)) continue
828
938
  const p = join(pagesDir, entry)
829
- if (!statSync(p).isDirectory()) continue
939
+ if (!statSync(p).isDirectory() || holds(p)) continue
830
940
  rmSync(p, { recursive: true, force: true })
831
941
  report.deleted.push(p)
832
942
  }
@@ -845,8 +955,95 @@ function pruneOrphanPageDirs(pagesDir, keepDirs, report) {
845
955
  // incoming level never nukes an existing one (a malformed/partial payload can't
846
956
  // wipe it).
847
957
  function projectPages(pages, pagesDir, sourceLocale, report, prune, ctx) {
848
- writePagesTree(pages, pagesDir, sourceLocale, report, ctx, '', rootOrderList(ctx.siteRoot, pagesDir))
849
- if (prune) prunePagesTree(pages, pagesDir, sourceLocale, report, ctx)
958
+ // The mode the build reads the pages directory in: `pages/folder.yml` puts the whole site in folder mode.
959
+ const rootMode = ctx.files?.levelMode(pagesDir) ?? folderModeOf(pagesDir, 'sections')
960
+ writePagesTree(pages, pagesDir, sourceLocale, report, ctx, '', rootOrderList(ctx.siteRoot, pagesDir), '/', rootMode)
961
+ if (prune) prunePagesTree(pages, pagesDir, sourceLocale, report, ctx, '', rootMode)
962
+ }
963
+
964
+ // ⭐ WHERE A PAGE GOES: where the files keep it (`page-files.js`) — a numbered folder, a folder-mode
965
+ // `.md` file — else where the project's rules place a new one beside its siblings: in a folder-mode
966
+ // level an `.md` file when it can be one, else a page folder named by its slug. ⛔ A page a folder-mode
967
+ // level cannot hold as a file is not written there (`cannot`): a page folder below it, with nothing in
968
+ // its `page.yml`, is read in folder mode, its sections as pages. A folder-mode folder is a folder.
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`.
974
+ function placeOf(ctx, record, route, levelDir, levelMode, sourceLocale) {
975
+ const found = ctx.files?.page(route)
976
+ if (found) return found
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
+ }
985
+ }
986
+ return { kind: 'folder', dir: join(levelDir, pageDirName(record, sourceLocale)) }
987
+ }
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
+
1013
+ // ⭐ A FOLDER-MODE `.md` PAGE, WRITTEN BACK IN PLACE: the file is the page and its one section, so the
1014
+ // section is written into it as any section file is (`sectionRecordToFile`) — its text, its params —
1015
+ // and its frontmatter's `hidden:` says the page's. One the file cannot hold (`mdPageCannotHold`) is
1016
+ // left as written, and said. ⛔ Until 2026-11-04 a pull left every such page alone, so an edit made to
1017
+ // one in the app was undone by the next push. Returns whether it was written.
1018
+ function writeMdPage({ record, place, route, ctx, report, pageContext, sourceLocale }) {
1019
+ const own = parse(place.file).name
1020
+ const name = parseNumericPrefix(own).name || own
1021
+ const what = mdPageCannotHold(record, { name, sourceLocale })
1022
+ if (what.length) {
1023
+ report.leftAlone?.push(route)
1024
+ report.held?.push({ route, uuids: subtreeUuids(record), what })
1025
+ return false
1026
+ }
1027
+ const section = record.page_sections[0]
1028
+ const stableId = recordStableId(section) || name
1029
+ // A page renamed in the app moves its file, as a page folder moves (`placeByUuid`).
1030
+ placeByUuid(ctx, record.$uuid, place.file)
1031
+ sectionRecordToFile({
1032
+ filePath: place.file,
1033
+ record: { ...section, hidden: record.hidden === true },
1034
+ sourceLocale: ctx?.sourceLocale,
1035
+ collector: ctx?.collector,
1036
+ dataModel: ctx?.dataModel,
1037
+ impliedType: ctx?.sectionType,
1038
+ freeformRelPath: buildFreeformPath({ stableId }, pageContext),
1039
+ freeformCandidates: freeformPathsFor({ stableId }, pageContext),
1040
+ writeId: stableId !== name,
1041
+ context: translationContext({ stableId }, pageContext.route),
1042
+ media: ctx?.media ?? null,
1043
+ fileLinks: ctx?.fileLinks ?? null,
1044
+ })
1045
+ report.sections.push(place.file)
1046
+ return true
850
1047
  }
851
1048
 
852
1049
  // The directory name for a page record (slug, or `[param]/` for a dynamic page).
@@ -867,24 +1064,32 @@ export function pageDirName(record, sourceLocale) {
867
1064
  // section files, recursing into children. No deletes happen here. `routePrefix`
868
1065
  // accumulates the slug-path route (for the free-form translation path; matches the
869
1066
  // producer's slugPath, normalizeRouteForPath strips any leading slash on both).
870
- function writePagesTree(pages, pagesDir, sourceLocale, report, ctx, routePrefix = '', list = null, canonParent = '/') {
1067
+ function writePagesTree(pages, pagesDir, sourceLocale, report, ctx, routePrefix = '', list = null, canonParent = '/', levelMode = 'sections') {
871
1068
  let leftAlone = false
872
1069
  for (const record of pages || []) {
873
1070
  const slug = unwrapLocalized(record.slug, sourceLocale) // localized {lang:value} → canonical
874
1071
  const route = routePrefix ? `${routePrefix}/${slug}` : slug
875
- // ⭐ A PAGE AUTHORED IN A FILE THE PULL CANNOT WRITE BACK IS LEFT ALONE — a mount's, or a
876
- // folder-mode `.md` page (`git-authored.js`). Its children too: a mount's are the mount's.
877
- if (ctx.leave?.has(route)) {
1072
+ let place = placeOf(ctx, record, route, pagesDir, levelMode, sourceLocale)
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'] }
1075
+ ctx.places?.set(record, place)
1076
+ // ⭐ A PAGE THE PULL MAY NOT OR CANNOT WRITE IS LEFT ALONE — a mount's, a route the files give two
1077
+ // pages for (`page-files.js`), a page its folder-mode level cannot hold as a file. Its children too:
1078
+ // a mount's are the mount's.
1079
+ if (place.kind === 'mounted' || place.kind === 'twice' || place.kind === 'cannot') {
1080
+ keepWhereTheFilesAre(ctx, subtreeUuids(record))
878
1081
  report.leftAlone?.push(...subtreeRoutes(record, route, sourceLocale))
1082
+ // ⭐ Each with its items, for the pull to bank by its outcome: a mount's page lets the folder win, and
1083
+ // one the files cannot hold is held at the version this copy last agreed on.
1084
+ // A mount's are named page by page, each with its own items, so a pull can say which the app changed.
1085
+ if (place.kind === 'mounted') report.mountedPages?.push(...subtreePages(record, route, sourceLocale))
1086
+ else report.held?.push({ route, uuids: subtreeUuids(record), what: place.kind === 'twice' ? ['two pages on one route'] : place.what })
879
1087
  leftAlone = true
880
1088
  continue
881
1089
  }
882
1090
  // The route the build gives the page (`buildRouteOf`, the push's rule): an index page takes its
883
1091
  // parent's, a parametric one is `:<param>`.
884
1092
  const canon = buildRouteOf(record, canonParent, sourceLocale)
885
- const pageDir = join(pagesDir, pageDirName(record, sourceLocale))
886
- // Relocate the whole page dir if this uuid moved to a new slug, then record it.
887
- placeByUuid(ctx, record.$uuid, pageDir)
888
1093
 
889
1094
  // Capture target-locale translations of the page's localized scalars; the
890
1095
  // source value goes inline into page.yml below (pageRecordToYml unwraps it). In the page's
@@ -906,18 +1111,52 @@ function writePagesTree(pages, pagesDir, sourceLocale, report, ctx, routePrefix
906
1111
  // homepage the build reads at `/`.
907
1112
  const pageContext = { route: canon, id: record.stable_id }
908
1113
 
1114
+ if (place.kind === 'md') {
1115
+ if (!writeMdPage({ record, place, route, ctx, report, pageContext, sourceLocale })) leftAlone = true
1116
+ continue
1117
+ }
1118
+ const pageDir = place.dir
1119
+ // ⭐ A writable mount's own route is where the site's `paths:` puts it, never where a rename index
1120
+ // last saw it: no move is made, and none recorded.
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)
1125
+ // Relocate the whole page dir if this uuid moved to a new slug, then record it.
1126
+ if (!mount) placeByUuid(ctx, record.$uuid, pageDir, { folder: true })
1127
+
909
1128
  let sectionsArray = []
910
1129
  let filesGiveOrder = false
911
1130
  let filesGiveTopOrder = false
912
- if (record.mode === 'page' && Array.isArray(record.page_sections)) {
1131
+ if (form === 'sections' && Array.isArray(record.page_sections)) {
913
1132
  const r = pageSectionsToFiles({ pageDir, pageSections: record.page_sections, ctx, pageContext })
914
1133
  sectionsArray = r.sections
915
1134
  filesGiveOrder = r.filesGiveOrder
916
1135
  filesGiveTopOrder = r.filesGiveTopOrder
917
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)
918
1145
  }
919
1146
 
920
- const ymlName = record.mode === 'folder' ? 'folder.yml' : 'page.yml'
1147
+ if (mount) {
1148
+ const config = mountRouteConfig(mount)
1149
+ const existing = config.read()
1150
+ const pageSlug = pageSlugToYml(record, canon, existing, sourceLocale, ctx)
1151
+ const yml = pageRecordToYml(record, sectionsArray, sourceLocale, existing, { isRoot: true, slug: pageSlug, filesGiveOrder, filesGiveTopOrder })
1152
+ report.pages.push(...config.write(changedSettings(existing, yml)))
1153
+ // Its pages are the mounted folder's, read in the mode the route gives them.
1154
+ const list = { pages: config.read().pages, write: (next) => config.write({ pages: next }) }
1155
+ writePagesTree(record.$children || [], mount.dir, sourceLocale, report, ctx, route, list, canon, mount.childMode)
1156
+ continue
1157
+ }
1158
+
1159
+ const ymlName = form === 'pages' ? 'folder.yml' : 'page.yml'
921
1160
  const ymlPath = join(pageDir, ymlName)
922
1161
  // Merge (not full-dump) so author-added keys survive a pull; the projector
923
1162
  // owns only PAGE_YML_MANAGED_KEYS.
@@ -926,19 +1165,186 @@ function writePagesTree(pages, pagesDir, sourceLocale, report, ctx, routePrefix
926
1165
  const yml = pageRecordToYml(record, sectionsArray, sourceLocale, existing, { isRoot: !routePrefix, slug: pageSlug, filesGiveOrder, filesGiveTopOrder })
927
1166
  // ⭐ A `page.yml` with nothing to say is not created: the build reads an empty one as none
928
1167
  // (`content-collector.js::readFolderConfig`). ⛔ Until 2026-10-08 a pull wrote `{}` into every page
929
- // whose folder had none. An empty `folder.yml` is written still — its presence is folder mode.
930
- if (ymlName === 'page.yml' && Object.keys(yml).length === 0 && !existsSync(ymlPath)) {
931
- writePagesTree(record.$children || [], pageDir, sourceLocale, report, ctx, route, parentOrderList(ymlPath), canon)
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')) {
1172
+ writePagesTree(record.$children || [], pageDir, sourceLocale, report, ctx, route, parentOrderList(ymlPath), canon, folderModeOf(pageDir, levelMode))
932
1173
  continue
933
1174
  }
934
1175
  writeMergedYaml(ymlPath, yml, PAGE_YML_MANAGED_KEYS)
935
1176
  report.pages.push(ymlPath)
936
1177
 
937
- writePagesTree(record.$children || [], pageDir, sourceLocale, report, ctx, route, parentOrderList(ymlPath), canon)
1178
+ // Its children are read in the mode the build reads its folder in now, its config just written.
1179
+ writePagesTree(record.$children || [], pageDir, sourceLocale, report, ctx, route, parentOrderList(ymlPath), canon, folderModeOf(pageDir, levelMode))
938
1180
  }
939
1181
  // A level holding a page left alone keeps the order its files give: reconciling it would write an
940
1182
  // `order:` into a page folder that does not exist, or rewrite a `pages:` list the author keeps.
941
- if (!leftAlone) reconcileLevelOrder({ pages, pagesDir, sourceLocale, list, homepage: routePrefix ? null : ctx.homepage })
1183
+ if (!leftAlone) reconcileLevelOrder({ pages, pagesDir, sourceLocale, list, homepage: routePrefix ? null : ctx.homepage, ctx, levelMode })
1184
+ }
1185
+
1186
+ // The items of a page and everything below it — its own, its sections', its pages' — by `$uuid`.
1187
+ function subtreeUuids(record) {
1188
+ const out = []
1189
+ const walk = (r) => {
1190
+ if (typeof r?.$uuid === 'string') out.push(r.$uuid)
1191
+ for (const s of r?.page_sections || []) walk(s)
1192
+ for (const c of r?.$children || []) walk(c)
1193
+ }
1194
+ walk(record)
1195
+ return out
1196
+ }
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
+
1303
+ // ⭐ THE PAGES THE SITE'S FILES ARE, for the links a file writes as files (`site/file-links.js`): each page
1304
+ // of the document at the files the file map keeps it in — an `.md` page's own, a page folder's section
1305
+ // files as the writer finds them — so a pull reads a file's links as the push does, and writes them back
1306
+ // as the file wrote them.
1307
+ function pageFileTargets(ctx, pages, sourceLocale) {
1308
+ const out = []
1309
+ const contentOf = (section) => (isProseMirrorDoc(section?.content) ? section.content : unwrapLocalized(section?.content, sourceLocale))
1310
+ const walk = (records, prefix, parentCanon) => {
1311
+ for (const record of records || []) {
1312
+ const route = prefix ? `${prefix}/${unwrapLocalized(record.slug, sourceLocale)}` : unwrapLocalized(record.slug, sourceLocale)
1313
+ const canon = buildRouteOf(record, parentCanon, sourceLocale)
1314
+ const place = ctx.files?.page(route)
1315
+ const files = []
1316
+ if (place?.kind === 'md' && record.page_sections?.length === 1) {
1317
+ const section = record.page_sections[0]
1318
+ files.push({ file: place.file, id: recordStableId(section), content: contentOf(section) })
1319
+ } else if (place?.kind === 'folder' && (place.mount ? place.mount.mode : ctx.files.levelMode(place.dir)) === 'sections') {
1320
+ const bases = sectionFileBases(record.page_sections || [])
1321
+ const visit = (list, child) => {
1322
+ for (const section of list || []) {
1323
+ const file = existingSectionFile(place.dir, bases.get(section), recordStableId(section), { child })
1324
+ if (file) files.push({ file, id: recordStableId(section), content: contentOf(section) })
1325
+ visit(section?.$children, true)
1326
+ }
1327
+ }
1328
+ visit(record.page_sections, false)
1329
+ }
1330
+ if (files.length) out.push({ route: canon, files })
1331
+ walk(record.$children, route, canon)
1332
+ }
1333
+ }
1334
+ walk(pages, '', '/')
1335
+ return fileLinkTargets(out)
1336
+ }
1337
+
1338
+ // Each page of a subtree by its route, with its own items: the page's, and its sections' with theirs.
1339
+ function subtreePages(record, route, sourceLocale) {
1340
+ const out = []
1341
+ const sectionUuids = (s) => [s?.$uuid, ...(s?.$children || []).flatMap(sectionUuids)]
1342
+ const walk = (r, at) => {
1343
+ out.push({ route: at, uuids: [r.$uuid, ...(r.page_sections || []).flatMap(sectionUuids)].filter((u) => typeof u === 'string') })
1344
+ for (const child of r.$children || []) walk(child, `${at}/${unwrapLocalized(child.slug, sourceLocale)}`)
1345
+ }
1346
+ walk(record, route)
1347
+ return out
942
1348
  }
943
1349
 
944
1350
  // A page's route and each of its descendants', as `writePagesTree` composes them.
@@ -1022,15 +1428,28 @@ const stableJson = (value) =>
1022
1428
  // the rest after them by filename (`orderFolders`), so the pages at the END that are already in
1023
1429
  // filename order, and carry no `order:`, need none — the way `international` numbers four pages and
1024
1430
  // leaves `404` and `home` to follow. ⛔ The first version of this numbered every page of the level.
1025
- function reconcileLevelOrder({ pages, pagesDir, sourceLocale, list, homepage = null }) {
1431
+ function reconcileLevelOrder({ pages, pagesDir, sourceLocale, list, homepage = null, ctx = null, levelMode = 'sections' }) {
1432
+ // Each page by the entry the files keep it as (`places`): `2-about`, `1-install.md`, a writable
1433
+ // mount's route by its segment — each with how its `order:` is read and written.
1026
1434
  const level = (pages || []).map((r) => {
1027
- const dirName = pageDirName(r, sourceLocale)
1028
- return { dirName, yml: join(pagesDir, dirName, r.mode === 'folder' ? 'folder.yml' : 'page.yml') }
1435
+ const place = ctx?.places?.get(r)
1436
+ if (place?.kind === 'md') {
1437
+ const own = parse(place.file).name
1438
+ return { md: true, dirName: basename(place.file), name: parseNumericPrefix(own).name || own }
1439
+ }
1440
+ if (place?.mount) {
1441
+ const config = mountRouteConfig(place.mount)
1442
+ return { md: false, dirName: place.mount.segment, name: place.mount.segment, readOrder: () => config.read().order, writeOrder: (n) => config.write({ order: n }) }
1443
+ }
1444
+ const dirName = place?.kind === 'folder' ? basename(place.dir) : pageDirName(r, sourceLocale)
1445
+ const yml = join(pagesDir, dirName, ctx?.forms?.get(r) === 'pages' ? 'folder.yml' : 'page.yml')
1446
+ return { md: false, dirName, name: parseNumericPrefix(dirName).name, readOrder: () => readAuthoredYaml(yml)?.order, writeOrder: (n) => writeMergedYaml(yml, { order: n }, ['order']) }
1029
1447
  })
1030
1448
  if (level.length < 2) return
1031
- const folders = level.map(({ dirName, yml }) => {
1032
- const order = readAuthoredYaml(yml)?.order
1033
- return { dirName, name: parseNumericPrefix(dirName).name, order: typeof order === 'number' ? order : undefined }
1449
+ if (levelMode === 'pages') return reconcileFolderModeOrder({ level, pagesDir, list, homepage })
1450
+ const folders = level.map(({ dirName, name, readOrder }) => {
1451
+ const order = readOrder()
1452
+ return { dirName, name, order: typeof order === 'number' ? order : undefined }
1034
1453
  })
1035
1454
  const ordered = orderFolders(folders, list?.pages).map((f) => f.dirName)
1036
1455
  if (ordered.join('\n') === level.map((l) => l.dirName).join('\n')) return
@@ -1053,7 +1472,37 @@ function reconcileLevelOrder({ pages, pagesDir, sourceLocale, list, homepage = n
1053
1472
  if (byName.join('\n') !== candidate.map((f) => f.dirName).join('\n')) break
1054
1473
  tail--
1055
1474
  }
1056
- level.slice(0, tail).forEach(({ yml }, i) => writeMergedYaml(yml, { order: i + 1 }, ['order']))
1475
+ level.slice(0, tail).forEach(({ writeOrder }, i) => writeOrder(i + 1))
1476
+ }
1477
+
1478
+ // ⭐ A FOLDER-MODE LEVEL'S ORDER IS ONE LIST over its `.md` pages and its folders, as the build orders
1479
+ // them (`folderModeChildren`): when the files no longer give the backend's order, the level's `pages:`
1480
+ // says it, in its own config. A page's `order:` cannot — an `.md` page has no config to hold one — and
1481
+ // renaming numbered files would move every page's file for one change.
1482
+ function reconcileFolderModeOrder({ level, pagesDir, list, homepage }) {
1483
+ let entries = []
1484
+ try {
1485
+ entries = readdirSync(pagesDir)
1486
+ } catch {
1487
+ return
1488
+ }
1489
+ const config = { pages: list?.pages }
1490
+ const mine = new Set(level.filter((l) => l.md).map((l) => l.dirName))
1491
+ const files = folderModePageFiles(entries, config).files.filter((f) => mine.has(f.file)).map((f) => ({ name: f.name, entry: f.file }))
1492
+ const folders = orderFolders(
1493
+ level.filter((l) => !l.md).map(({ dirName, name, readOrder }) => {
1494
+ const order = readOrder()
1495
+ return { dirName, name, order: typeof order === 'number' ? order : undefined, entry: dirName }
1496
+ }),
1497
+ list?.pages
1498
+ )
1499
+ const given = folderModeChildren(files, folders, config).map((c) => c.entry)
1500
+ if (given.join('\n') === level.map((l) => l.dirName).join('\n')) return
1501
+ const names = level.map((l) => l.name)
1502
+ const parsed = Array.isArray(list?.pages) ? parseWildcardArray(list.pages) : null
1503
+ // A root list's first entry is the homepage (`reconcileLevelOrder`), so one that does not open with it opens with `...`.
1504
+ if (homepage && names[0] !== homepage) list?.write(['...', ...names])
1505
+ else list?.write(parsed?.mode === 'strict' ? names : [...names, '...'])
1057
1506
  }
1058
1507
 
1059
1508
  // The `pages:` list a level is ordered by, and how to rewrite it. The root's is the site config's,
@@ -1083,27 +1532,46 @@ function collectSectionFileBases(pageSections) {
1083
1532
 
1084
1533
  // Pass 2 — prune orphan section files (per page dir) and orphan page dirs (per
1085
1534
  // level), AFTER every relocation in pass 1. Guarded against wiping an empty level.
1086
- function prunePagesTree(pages, pagesDir, sourceLocale, report, ctx = null, routePrefix = '') {
1535
+ function prunePagesTree(pages, pagesDir, sourceLocale, report, ctx = null, routePrefix = '', levelMode = 'sections') {
1536
+ // Each incoming page by the entry the files keep it as (`places`): a folder's name, an `.md` page's file.
1087
1537
  const incomingDirs = new Set()
1538
+ const incomingFiles = new Set()
1088
1539
  for (const record of pages || []) {
1089
- incomingDirs.add(pageDirName(record, sourceLocale))
1090
1540
  const slug = unwrapLocalized(record.slug, sourceLocale)
1091
1541
  const route = routePrefix ? `${routePrefix}/${slug}` : slug
1092
- // Left alone by pass 1, so nothing of it is pruned either (`git-authored.js`).
1093
- if (ctx?.leave?.has(route)) continue
1094
- const pageDir = join(pagesDir, pageDirName(record, sourceLocale))
1095
- if (record.mode === 'page') {
1542
+ const place = ctx?.places?.get(record) ?? { kind: 'folder', dir: join(pagesDir, pageDirName(record, sourceLocale)) }
1543
+ if (place.kind === 'md') incomingFiles.add(basename(place.file))
1544
+ else if (place.kind === 'twice') {
1545
+ incomingDirs.add(basename(place.dir))
1546
+ incomingFiles.add(basename(place.file))
1547
+ } else incomingDirs.add(place.mount ? place.mount.segment : place.kind === 'folder' ? basename(place.dir) : pageDirName(record, sourceLocale))
1548
+ // Left alone by pass 1 — and an `.md` page has nothing below it — so nothing of it is pruned.
1549
+ if (place.kind !== 'folder') continue
1550
+ const pageDir = place.dir
1551
+ if (ctx?.forms?.get(record) === 'sections') {
1096
1552
  // The files pass 1 wrote into — the author's own names among them — else the names it would give.
1097
1553
  const keep = ctx?.sectionFiles?.get(pageDir) || collectSectionFileBases(record.page_sections)
1098
- if (keep.size > 0) pruneOrphanSectionFiles(pageDir, keep, report)
1554
+ if (keep.size > 0) pruneOrphanSectionFiles(pageDir, keep, report, ctx?.kept)
1099
1555
  }
1100
- prunePagesTree(record.$children || [], pageDir, sourceLocale, report, ctx, route)
1556
+ // A writable mount's pages are in the mounted folder (`page-files.js`).
1557
+ if (place.mount) prunePagesTree(record.$children || [], place.mount.dir, sourceLocale, report, ctx, route, place.mount.childMode)
1558
+ else prunePagesTree(record.$children || [], pageDir, sourceLocale, report, ctx, route, folderModeOf(pageDir, levelMode))
1101
1559
  }
1102
- if (incomingDirs.size === 0) return
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
+ }
1567
+ if (incomingDirs.size === 0 && incomingFiles.size === 0) return
1568
+ if (levelMode === 'pages') pruneOrphanPageFiles(pagesDir, incomingFiles, report, routePrefix, ctx)
1103
1569
  // A mounted route's local folder is never an orphan, whatever the document holds: what it
1104
- // presents is another repository's (`git-authored.js`).
1105
- if (!routePrefix) for (const segment of ctx?.leave?.mounted ?? []) incomingDirs.add(segment)
1106
- pruneOrphanPageDirs(pagesDir, incomingDirs, report)
1570
+ // presents is another repository's (`page-files.js`).
1571
+ if (!routePrefix) for (const segment of ctx?.files?.mounted ?? []) incomingDirs.add(segment)
1572
+ // ⛔ Nor is a folder that holds a folder-mode page, whatever the document holds: until 2026-11-04 a
1573
+ // document without that folder's own page removed it whole, its `.md` pages with it.
1574
+ pruneOrphanPageDirs(pagesDir, incomingDirs, report, (dir) => Boolean(ctx?.files?.holds?.(dir)) || holdsKept(ctx, dir))
1107
1575
  }
1108
1576
 
1109
1577
  /**
@@ -1345,6 +1813,18 @@ function refuseContentFilesCannotHold(document, sourceLocale) {
1345
1813
  )
1346
1814
  }
1347
1815
 
1816
+ // The routes of the pages a copy's `sync.json` names for a backend — each page unit, `pages/<route>/page.yml`
1817
+ // or `folder.yml`, a parametric folder's segment by its parameter (`[slug]` → `slug`), as `page-files.js`
1818
+ // names routes.
1819
+ function seenPageRoutes(items) {
1820
+ const out = new Set()
1821
+ for (const key of Object.keys(items || {})) {
1822
+ const m = key.match(/^pages\/(.+)\/(?:page|folder)\.yml$/)
1823
+ if (m) out.add(m[1].split('/').map((seg) => seg.match(/^\[(.+)\]$/)?.[1] ?? seg).join('/'))
1824
+ }
1825
+ return out
1826
+ }
1827
+
1348
1828
  /**
1349
1829
  * Project a whole `@uniweb/site-content` document to a site's files: `info` →
1350
1830
  * config (siteInfoToConfig), `collections[]` declarations →
@@ -1371,13 +1851,16 @@ function refuseContentFilesCannotHold(document, sourceLocale) {
1371
1851
  * @param {string} [params.sectionType] - the type a section that names none renders with on this
1372
1852
  * site, which the push filled in and a section's file leaves out — `siteDefaultSectionType`,
1373
1853
  * read by the caller since it reads the foundation's source
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
1374
1857
  * @returns {{ config: object, collections: object, locales: object, pages: string[], sections: string[], layout: string[], deleted: string[], renamed: object[] }}
1375
1858
  */
1376
- export function siteContentDocumentToProject({ document, siteRoot, backend = null, sourceLocale = documentSourceLocale(document), prune = false, keepAuthoredFoundation = false, scope, dataModel = null, sectionType = DEFAULT_SECTION_TYPE }) {
1859
+ export function siteContentDocumentToProject({ document, siteRoot, backend = null, sourceLocale = documentSourceLocale(document), prune = false, keepAuthoredFoundation = false, scope, dataModel = null, sectionType = DEFAULT_SECTION_TYPE, writableMounts = [] }) {
1377
1860
  // Before anything is written: a pull that would leave content out of the files stops here.
1378
1861
  refuseContentFilesCannotHold(document, sourceLocale)
1379
1862
 
1380
- const report = { config: null, collections: null, locales: null, assets: null, pages: [], sections: [], layout: [], deleted: [], renamed: [], leftAlone: [] }
1863
+ const report = { config: null, collections: null, locales: null, assets: null, pages: [], sections: [], layout: [], deleted: [], renamed: [], leftAlone: [], held: [], mountedPages: [], mountRoutes: [] }
1381
1864
 
1382
1865
  // Collects target-locale translations of localized scalars as they're projected;
1383
1866
  // flushed to locales/{locale}.json at the end (the manifest stays derivable).
@@ -1415,17 +1898,33 @@ export function siteContentDocumentToProject({ document, siteRoot, backend = nul
1415
1898
  const siteMap = readAuthoredYaml(join(siteRoot, 'site.yml'))?.i18n?.routeTranslations
1416
1899
  ctx.routes = { siteMap: isPlainRecord(siteMap) && Object.keys(siteMap).length ? siteMap : null, slugs: new Map() }
1417
1900
 
1418
- // Where the tree goes is what `site.yml` says NOW — `siteInfoToConfig` above has
1419
- // written the document's `settings.paths` into it — because that is the file the
1420
- // next push and the build read. See `siteContentDirs`.
1421
- const siteYml = readAuthoredYaml(join(siteRoot, 'site.yml'))
1901
+ // Where the tree goes is what this project's own `site.yml` says — the file the next push and the
1902
+ // build read, and one a document never writes `paths` into. See `siteContentDirs`.
1903
+ let siteYml = readAuthoredYaml(join(siteRoot, 'site.yml'))
1422
1904
  const { pagesDir, layoutDir: layoutBaseDir } = siteContentDirs(siteRoot, siteYml)
1423
- // The tree a key names its file by: pages and layout wherever `paths:` puts them. (A mount's pages
1424
- // are never written, so the mounts need not join it.)
1425
- if (ctx.media) ctx.media.tree = siteTree(siteRoot, { pagesDir, layoutDir: layoutBaseDir })
1426
- // ⭐ The pages authored in files a pull cannot write back — a mount's, a folder-mode folder's
1427
- // `.md` pages — are neither written nor pruned (`git-authored.js`).
1428
- ctx.leave = gitAuthoredPages(siteYml, pagesDir)
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)
1911
+ // ⭐ WHERE EACH PAGE IS KEPT — found in the files by the build's rules (`page-files.js`), so a page
1912
+ // is written where it lives: a numbered folder, a folder-mode `.md` file, a writable mount's folder.
1913
+ // A read-only mount's pages, and a route the files give two pages for, are neither written nor
1914
+ // pruned. Each record's place, once decided, is the one every pass below reads (`places`).
1915
+ // The pages this copy has seen the backend hold, by route: a prune deletes an `.md` page only then.
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 })
1923
+ ctx.places = new Map()
1924
+ ctx.fileLinks = pageFileTargets(ctx, document?.pages, sourceLocale)
1925
+ // The tree a key names its file by: pages and layout wherever `paths:` puts them, and each mount
1926
+ // the pull writes into. (A read-only mount's pages are never written.)
1927
+ if (ctx.media) ctx.media.tree = siteTree(siteRoot, { pagesDir, layoutDir: layoutBaseDir, mounts: ctx.files.writable })
1429
1928
  // The root page the backend marks as the homepage, by the directory it is written to.
1430
1929
  const home = (document?.pages || []).find((p) => p?.is_index)
1431
1930
  ctx.homepage = home ? pageDirName(home, sourceLocale) : null
@@ -1438,7 +1937,9 @@ export function siteContentDocumentToProject({ document, siteRoot, backend = nul
1438
1937
  const root = rootOrderList(siteRoot, pagesDir)
1439
1938
  // A homepage marked `index: true` in its own config — where the push read it (`buildPageData`) —
1440
1939
  // is left marked there alone: a site.yml that names none is not given an `index:` it never had.
1441
- const marksItself = readAuthoredYaml(join(pagesDir, ctx.homepage, home.mode === 'folder' ? 'folder.yml' : 'page.yml'))?.index === true
1940
+ const homePlace = ctx.places.get(home)
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
1942
+ const marksItself = homeConfig?.index === true
1442
1943
  if (root.homepage !== ctx.homepage && !(marksItself && root.homepage === undefined)) {
1443
1944
  const listed = Array.isArray(root.pages) ? parseWildcardArray(root.pages) : null
1444
1945
  // A list that names the homepage first beats `index:`, so it opens with `...` instead.