@uniweb/build 1.16.2 → 1.17.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@uniweb/build",
3
- "version": "1.16.2",
3
+ "version": "1.17.0",
4
4
  "description": "Build tooling for the Uniweb Component Web Platform",
5
5
  "type": "module",
6
6
  "exports": {
@@ -56,12 +56,12 @@
56
56
  "js-yaml": "^4.3.2",
57
57
  "sharp": "^0.35.5",
58
58
  "yaml": "^2.5.0",
59
- "@uniweb/schemas": "~1.6.10",
60
59
  "@uniweb/content-reader": "~1.5.9",
61
- "@uniweb/theming": "~1.2.1",
62
- "@uniweb/content-writer": "~1.3.1",
60
+ "@uniweb/schemas": "~1.6.10",
63
61
  "@uniweb/semantic-parser": "~1.13.2",
64
- "@uniweb/projections": "~1.2.11"
62
+ "@uniweb/theming": "~1.2.1",
63
+ "@uniweb/projections": "~1.2.11",
64
+ "@uniweb/content-writer": "~1.3.1"
65
65
  },
66
66
  "optionalDependencies": {
67
67
  "@uniweb/runtime": "~1.4.5"
package/src/schema.js CHANGED
@@ -694,28 +694,39 @@ function refuseAreaDeclaration(owner, area) {
694
694
  }
695
695
 
696
696
  /**
697
- * Warn about a section type whose `area:` names an area none of this foundation's layouts draws:
698
- * an editor offers a type for the areas it names, and no page would have that one. What a layout
699
- * draws is what its `meta.js` declares in `areas:`. Nothing is said for an extension, whose host's
700
- * layouts it cannot see, for a foundation with no layouts, or when any layout declares no `areas`,
701
- * since that one could draw any. A warning, never a refusal: the type still renders wherever an
702
- * author places it.
697
+ * The areas the runtime's built-in layout draws (`runtime/src/default-layout.js`): a page renders with it
698
+ * when it names no layout and the foundation has no default one. Any other area is passed in and not drawn.
699
+ */
700
+ const BUILT_IN_LAYOUT_AREAS = ['header', 'footer']
701
+
702
+ /**
703
+ * Warn about a section type whose `area:` names an area no layout of this foundation draws: an editor
704
+ * offers a type for the areas it names, and no page would have that one. What a layout draws is what its
705
+ * `meta.js` declares in `areas:`. When the foundation has no default layout (`resolveDefaultLayout`), a
706
+ * page that names none renders with the built-in one, which draws the header and the footer, so those
707
+ * count too, and a foundation with no layouts has those alone. Nothing is said for an extension, whose
708
+ * host's layouts it cannot see, or when any layout declares no `areas`, since that one could draw any.
709
+ * A warning, never a refusal: the type still renders wherever an author places it.
710
+ * ⛔ Until 2026-11-05 the built-in layout was left out: a foundation with no layouts was never warned,
711
+ * a typo such as `area: 'heder'` included, and one whose layouts declare no header was warned for it.
703
712
  *
704
713
  * @param {Object} components - discovered section types, by name
705
714
  * @param {Object} [layouts] - discovered layouts, by name
706
715
  * @param {Object} [options]
707
716
  * @param {boolean} [options.isExtension]
717
+ * @param {string|null} [options.defaultLayout] - the layout a page that names none renders with, null for
718
+ * the built-in one
708
719
  */
709
- export function reportAreaNames(components, layouts = {}, { isExtension = false } = {}) {
720
+ export function reportAreaNames(components, layouts = {}, { isExtension = false, defaultLayout = null } = {}) {
710
721
  const all = Object.values(layouts || {})
711
- if (isExtension || all.length === 0 || all.some((layout) => !Array.isArray(layout?.areas))) return
712
- const drawn = new Set(all.flatMap((layout) => layout.areas))
722
+ if (isExtension || all.some((layout) => !Array.isArray(layout?.areas))) return
723
+ const drawn = new Set([...all.flatMap((layout) => layout.areas), ...(defaultLayout ? [] : BUILT_IN_LAYOUT_AREAS)])
713
724
  for (const [name, entry] of Object.entries(components)) {
714
725
  for (const area of describePlacement(entry).areas || []) {
715
726
  if (drawn.has(area)) continue
716
727
  console.warn(
717
- `Warning: ${name} (meta.js): area names "${area}", which none of this foundation's layouts draws ` +
718
- `(they declare ${[...drawn].join(', ')}). An editor offers the type only where an author fills an ` +
728
+ `Warning: ${name} (meta.js): area names "${area}", which no layout of this foundation draws ` +
729
+ `(they draw ${[...drawn].join(', ')}). An editor offers the type only where an author fills an ` +
719
730
  `area it names. Name one of those, or add "${area}" to the areas: of the layout that draws it.`
720
731
  )
721
732
  }
@@ -1330,7 +1341,7 @@ export async function buildSchema(srcDir, sectionPaths, derivedSupports = null)
1330
1341
 
1331
1342
  // Determine extension role
1332
1343
  const isExtension = !!foundationConfig.extension
1333
- reportAreaNames(components, layouts, { isExtension })
1344
+ reportAreaNames(components, layouts, { isExtension, defaultLayout })
1334
1345
 
1335
1346
  // Warn if extension declares things it shouldn't
1336
1347
  if (isExtension) {
@@ -1,6 +1,6 @@
1
1
  /**
2
2
  * ⭐ WHAT A PUSH LEAVES OUT: a page or a section a pull HELD. The app changed it in a way its files
3
- * cannot say — a second section in a folder of single-section pages, a setting an `.md` page has no
3
+ * cannot say — a second section on an atomic page, a setting an `.md` page has no
4
4
  * place for, a move to where a page cannot sit — so the pull wrote nothing for it, and the site keeps
5
5
  * the app's version (`site-project.js`, `report.held`).
6
6
  *
@@ -58,21 +58,36 @@ export function heldUnitsOf({ hashes = {}, uuids = {}, held = [] } = {}) {
58
58
  * @param {Object<string,string>} p.held - what the pull recorded (`heldUnitsOf`)
59
59
  * @param {object} [p.plain] - the same document before any media was rewritten; `doc` when absent
60
60
  * @param {string} [p.sourceLocale]
61
- * @returns {{ left: string[], changed: string[] }} the paths taken out, or the paths that changed
61
+ * @returns {{ left: string[], changed: string[], uuids: string[] }} the paths taken out, or the paths
62
+ * that changed; and the `$uuid` of every item taken out, nested ones included, which the push sends
63
+ * no version for
62
64
  */
63
65
  export function leaveHeldOut(doc, { held = {}, plain = null, sourceLocale } = {}) {
64
66
  const paths = Object.keys(held)
65
- if (!doc || !paths.length) return { left: [], changed: [] }
67
+ if (!doc || !paths.length) return { left: [], changed: [], uuids: [] }
66
68
  const now = computeUnitHashes(plain ?? doc, sourceLocale)
67
69
  const changed = new Set(paths.filter((path) => now[path] !== held[path]))
68
70
  const pages = paths.filter(isPageUnit).map(belowPage)
69
71
  for (const path of Object.keys(now)) if (!(path in held) && pages.some((p) => path.startsWith(p))) changed.add(path)
70
- if (changed.size) return { left: [], changed: [...changed].sort() }
72
+ if (changed.size) return { left: [], changed: [...changed].sort(), uuids: [] }
71
73
 
72
74
  const drop = new Set()
73
75
  walkSiteUnits(doc, (path, record) => {
74
76
  if (path in held) drop.add(record)
75
77
  }, sourceLocale)
78
+ // ⭐ WHAT IS TAKEN OUT IS SENT NO VERSION. The site-content entity sends every version this copy
79
+ // holds, and a version for an item the document leaves out makes leaving it out a deletion
80
+ // (`withBaseVersion`, `sync-package.js`). So every item taken out is named, the sections and child
81
+ // pages below a held page included, for the push to send none. ⛔ Until 2026-11-05 none was named:
82
+ // a forced push banked a version for each held page it sent, and the next push left the page out
83
+ // and sent that version, which deletes it.
84
+ const uuids = new Set()
85
+ const under = (record) => {
86
+ if (record?.$uuid) uuids.add(record.$uuid)
87
+ for (const s of record?.page_sections || []) under(s)
88
+ for (const c of record?.$children || []) under(c)
89
+ }
90
+ for (const record of drop) under(record)
76
91
  const keep = (list) => list.filter((r) => !drop.has(r))
77
92
  const sections = (list) => {
78
93
  for (const s of list || []) {
@@ -90,5 +105,5 @@ export function leaveHeldOut(doc, { held = {}, plain = null, sourceLocale } = {}
90
105
  }
91
106
  if (Array.isArray(doc.pages)) doc.pages = keep(doc.pages)
92
107
  walk(doc.pages)
93
- return { left: paths.sort(), changed: [] }
108
+ return { left: paths.sort(), changed: [], uuids: [...uuids].sort() }
94
109
  }
@@ -1,18 +1,27 @@
1
1
  /**
2
- * A route's `mode` on the site-content document: what its pages may hold, which the app honours, and
3
- * not how the files hold them.
2
+ * A page's `mode` on the site-content document: what the page itself is, which the app honours, read from
3
+ * the page and never from its parent [Diego, 2026-11-05]:
4
4
  *
5
- * - `single-section`: each page under the route holds one section and no page of its own, as a folder
6
- * in folder mode keeps them, one `.md` file each. A route under it that holds no section is
7
- * `single-section` too, and the route holds no section of its own, except a page above a mounted
8
- * folder of `.md` pages.
9
- * - `page`: any other route.
5
+ * - `atomic`: a page that holds exactly one section and no child page, as the files hold it, one `.md`
6
+ * file in folder mode;
7
+ * - `atomic-parent`: a page with no section whose child pages are atomic pages or atomic-parents, as the
8
+ * files hold it, a directory in folder mode — its own `folder.yml`, or below one;
9
+ * - `regular`: every other page, a page with no section yet included.
10
10
  *
11
- * A push writes each route's own value, so nothing says "inherit" (`site.js::walkPagesNested`). A pull
12
- * reads it only for a route its files do not hold yet; a route they hold takes its form from them
13
- * (`site-project.js`). `folder` is the old spelling, which a stored document carries until its site's
14
- * next push: only a unit's identity reads it (`site-diff.js::walkSiteUnits`).
11
+ * A push writes each page's own value from where its files keep it (`site.js::walkPagesNested`). A pull
12
+ * places a page the files don't hold yet by it, and follows the app's switch of an empty page between
13
+ * `atomic-parent` and `regular` (`site-project.js`). A value it doesn't know reads as `regular`.
14
+ * ⛔ Until 2026-11-05 the value was the parent's: `single-section` on a page whose child pages were in
15
+ * folder mode, and `page` on every other, the pages under it included.
15
16
  *
16
17
  * A leaf, with no imports.
17
18
  */
18
- export const SINGLE_SECTION = 'single-section'
19
+ export const REGULAR = 'regular'
20
+ export const ATOMIC = 'atomic'
21
+ export const ATOMIC_PARENT = 'atomic-parent'
22
+
23
+ /** The page's own mode, or null for a value this framework doesn't know, which reads as `regular`. */
24
+ export function knownMode(record) {
25
+ const mode = record?.mode
26
+ return mode === REGULAR || mode === ATOMIC || mode === ATOMIC_PARENT ? mode : null
27
+ }
@@ -49,7 +49,7 @@
49
49
  import { entityContentHash } from './records.js'
50
50
  import { sectionFileBases, pageDirName, layoutSectionPaths } from './site-project.js'
51
51
  import { documentSourceLocale } from './source-locale.js'
52
- import { SINGLE_SECTION } from './route-mode.js'
52
+ import { ATOMIC_PARENT } from './route-mode.js'
53
53
 
54
54
  // A unit's own content, with the nested collections that are their own units
55
55
  // removed — so editing a section never also marks its page (or its parent
@@ -113,11 +113,10 @@ export function walkSiteUnits(doc, cb, sourceLocale = documentSourceLocale(doc))
113
113
  const dirName = pageDirName(record, sourceLocale)
114
114
  if (!dirName) continue
115
115
  const dir = `${parentDir}/${dirName}`
116
- // A route of single-section pages is its `folder.yml`, in either spelling: `folder` is the one a
117
- // push wrote until 2026-11-04, which a stored document carries until its site's next push, and a
118
- // unit keyed otherwise would read as one the app changed. Delete `folder` here once no synced site's
119
- // document carries it.
120
- cb(`${dir}/${record.mode === SINGLE_SECTION || record.mode === 'folder' ? 'folder.yml' : 'page.yml'}`, record, 'page')
116
+ // An atomic-parent is its `folder.yml`; every other page its `page.yml`, an atomic page's `.md` file
117
+ // included, as these keys have always named them. ⛔ Until 2026-11-05 the parent's `single-section`,
118
+ // or `folder` before it, named the `folder.yml`.
119
+ cb(`${dir}/${record.mode === ATOMIC_PARENT ? 'folder.yml' : 'page.yml'}`, record, 'page')
121
120
  walkSections(record.page_sections, dir)
122
121
  walkPages(record.$children, dir)
123
122
  }
@@ -50,7 +50,7 @@ import { writeSiteConfig, writeSitePaths, writeThemeFile, writeIfChanged, writeS
50
50
  import { mountEntriesOf } from '../site/mount-entries.js'
51
51
  import { declarationsToQueriesYml } from './records-project.js'
52
52
  import { buildRouteOf } from './site.js'
53
- import { SINGLE_SECTION } from './route-mode.js'
53
+ import { ATOMIC_PARENT, knownMode } from './route-mode.js'
54
54
  import { fileLinkTargets } from '../site/file-links.js'
55
55
  import { DEFAULT_SECTION_TYPE } from '@uniweb/core/section-type'
56
56
  import { translationContext, SITE_META_CONTEXT } from '../i18n/extract.js'
@@ -968,16 +968,18 @@ function projectPages(pages, pagesDir, sourceLocale, report, prune, ctx) {
968
968
  // its `page.yml`, is read in folder mode, its sections as pages. A folder-mode folder is a folder.
969
969
  // ⛔ Until 2026-11-04 every page went to its slug's folder: `pages/2-about/` came back as `about/`.
970
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`.
971
+ // In a folder-mode level a page is a directory only when it is an atomic-parent: by its own mode, or,
972
+ // where its mode is none this framework knows, by the form the files kept it in where the app moved it
973
+ // from (`oldForm`). Any other page is an `.md` file there when it can be one. A page folder is no form
974
+ // there: a parametric page, or a page its file cannot hold, is `cannot`.
974
975
  function placeOf(ctx, record, route, levelDir, levelMode, sourceLocale) {
975
976
  const found = ctx.files?.page(route)
976
977
  if (found) return found
977
978
  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) {
979
+ if (record.is_dynamic) return { kind: 'cannot', what: ['a parametric page, which an atomic-parent holds none of'] }
980
+ const mode = knownMode(record)
981
+ const parent = mode ? mode === ATOMIC_PARENT : oldForm(ctx, record) === 'pages'
982
+ if (!parent) {
981
983
  const name = unwrapLocalized(record.slug, sourceLocale)
982
984
  const what = mdPageCannotHold(record, { name, sourceLocale })
983
985
  return what.length ? { kind: 'cannot', what } : { kind: 'md', file: join(levelDir, `${name}.md`), dir: levelDir }
@@ -990,24 +992,59 @@ function placeOf(ctx, record, route, levelDir, levelMode, sourceLocale) {
990
992
  // `.md` page (`md`), or a folder read in folder mode (`pages`) or page mode (`sections`) where it was.
991
993
  // Null for a route new to them. Read before the move (`placeByUuid`), which takes the old place away.
992
994
  function oldForm(ctx, record) {
993
- const rel = record?.$uuid ? ctx?.oldIndex?.[record.$uuid] : null
994
- const old = rel ? join(ctx.siteRoot, rel) : null
995
+ const old = oldPlace(ctx, record?.$uuid)
995
996
  if (!old || !existsSync(old)) return null
996
997
  if (!statSync(old).isDirectory()) return 'md'
997
998
  return folderModeOf(old, ctx.files?.levelMode(dirname(old)) ?? 'sections')
998
999
  }
999
1000
 
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`.
1001
+ // Where the files kept an item before the app moved it: by the rename index this copy wrote, else, for
1002
+ // a page, at the route this copy's sync state last saw it at (`ctx.itemRoutes`). ⭐ A pull in a repository
1003
+ // has no rename index, so the route is all it goes by. ⛔ Until 2026-11-05 `oldForm` read the index alone,
1004
+ // and in a repository a moved route took the form of its `mode`.
1005
+ function oldPlace(ctx, uuid) {
1006
+ const rel = uuid ? ctx?.oldIndex?.[uuid] : null
1007
+ if (rel) return join(ctx.siteRoot, rel)
1008
+ const route = uuid ? ctx?.itemRoutes?.get(uuid) : null
1009
+ const place = route == null ? null : ctx?.files?.page(route)
1010
+ return place?.kind === 'md' ? place.file : place?.dir ?? null
1011
+ }
1012
+
1013
+ // ⭐ A DIRECTORY'S FORM — folder mode (`pages`) or page mode (`sections`) — by the page's own mode: an
1014
+ // atomic-parent's is folder mode, any other page's page mode (`route-mode.js`). Where the files hold the
1015
+ // page, their form stands, but for the switch the app makes on an empty page, between atomic-parent and
1016
+ // regular: there is nothing to convert, so the page's config follows. A mount's
1017
+ // route is the mount's. Where its mode is none this framework knows, a page the app moved keeps the form
1018
+ // the files kept it in where it was, and a page new to them is regular.
1019
+ // ⛔ Until 2026-11-05 the form came from the files alone wherever they held the page, and a mode was read
1020
+ // only for a page new to them, as `single-section` on its parent.
1005
1021
  function formOf(ctx, record, route, place, levelMode) {
1006
1022
  if (place.mount) return place.mount.mode
1007
- if (ctx.files?.page(route) === place) return ctx.files.levelMode(place.dir) ?? folderModeOf(place.dir, levelMode)
1023
+ const mode = knownMode(record)
1024
+ const asked = mode === ATOMIC_PARENT ? 'pages' : mode ? 'sections' : null
1025
+ if (ctx.files?.page(route) === place) {
1026
+ const held = ctx.files.levelMode(place.dir) ?? folderModeOf(place.dir, levelMode)
1027
+ // A regular page has no place inside folder mode (`refusePageInFolderMode`), so there the files stand.
1028
+ const fits = asked === 'pages' || levelMode !== 'pages'
1029
+ return asked && asked !== held && fits && isEmptyPage(record, place.dir) ? asked : held
1030
+ }
1031
+ if (asked) return asked
1008
1032
  const was = oldForm(ctx, record)
1009
1033
  if (was === 'pages' || was === 'sections') return was
1010
- return record.mode === SINGLE_SECTION ? 'pages' : 'sections'
1034
+ return 'sections'
1035
+ }
1036
+
1037
+ // A page with no section and no child page, on the site and in the files: the only one the app switches
1038
+ // between atomic-parent and regular, and the only one a pull changes the form of in place.
1039
+ function isEmptyPage(record, dir) {
1040
+ if ((record?.page_sections || []).length || (record?.$children || []).length) return false
1041
+ let entries
1042
+ try {
1043
+ entries = readdirSync(dir, { withFileTypes: true })
1044
+ } catch {
1045
+ return false
1046
+ }
1047
+ return !entries.some((e) => (e.isFile() && isMarkdownFile(e.name)) || (e.isDirectory() && !isIgnoredFolder(e.name)))
1011
1048
  }
1012
1049
 
1013
1050
  // ⭐ A FOLDER-MODE `.md` PAGE, WRITTEN BACK IN PLACE: the file is the page and its one section, so the
@@ -1135,12 +1172,12 @@ function writePagesTree(pages, pagesDir, sourceLocale, report, ctx, routePrefix
1135
1172
  filesGiveTopOrder = r.filesGiveTopOrder
1136
1173
  report.sections.push(...r.written)
1137
1174
  } 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.
1175
+ // ⛔ An atomic-parent holds no section: its directory's `.md` files are its child pages. One the app
1176
+ // gives it is held, and the page and its child pages are written as they are. Until 2026-11-04 it was
1177
+ // dropped, and the next push removed it from the site.
1141
1178
  const uuids = record.page_sections.flatMap((s) => subtreeUuids(s))
1142
1179
  keepWhereTheFilesAre(ctx, uuids)
1143
- report.held?.push({ route, uuids, what: ['a section, which a route of single-section pages holds none of'] })
1180
+ report.held?.push({ route, uuids, what: ['a section, which an atomic-parent holds none of'] })
1144
1181
  report.leftAlone?.push(route)
1145
1182
  }
1146
1183
 
@@ -1158,6 +1195,13 @@ function writePagesTree(pages, pagesDir, sourceLocale, report, ctx, routePrefix
1158
1195
 
1159
1196
  const ymlName = form === 'pages' ? 'folder.yml' : 'page.yml'
1160
1197
  const ymlPath = join(pageDir, ymlName)
1198
+ // ⭐ THE APP'S SWITCH ON AN EMPTY PAGE (`formOf`): its config file takes the other name, as the author
1199
+ // wrote it, so the directory is read in the form the app made it — folder mode for an atomic-parent.
1200
+ const oldYmlPath = join(pageDir, ymlName === 'folder.yml' ? 'page.yml' : 'folder.yml')
1201
+ if (existsSync(oldYmlPath) && !existsSync(ymlPath)) {
1202
+ renameSync(oldYmlPath, ymlPath)
1203
+ report.deleted.push(oldYmlPath)
1204
+ }
1161
1205
  // Merge (not full-dump) so author-added keys survive a pull; the projector
1162
1206
  // owns only PAGE_YML_MANAGED_KEYS.
1163
1207
  const existing = readAuthoredYaml(ymlPath)
@@ -1199,7 +1243,7 @@ function subtreeUuids(record) {
1199
1243
  // hold it is not written there, so its files at the old place are the files' version of it, and the prune
1200
1244
  // must keep them: found by the rename index this copy wrote, else, for a page, by the route its sync state
1201
1245
  // 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.
1246
+ // into an atomic-parent was held there and deleted where it was.
1203
1247
  function keepWhereTheFilesAre(ctx, uuids) {
1204
1248
  if (!ctx?.kept) return
1205
1249
  for (const uuid of uuids) {
@@ -1854,9 +1898,13 @@ function seenPageRoutes(items) {
1854
1898
  * @param {string[]} [params.writableMounts] - the segments of the mounts the caller may write into: a
1855
1899
  * pull names each one it can merge into, a folder of the site's repository or of a submodule.
1856
1900
  * A caller that names none writes no mount
1901
+ * @param {Object<string,string>} [params.priorItems] - this copy's item identity (unit path → `$uuid`)
1902
+ * as it stood before the pull merged the pulled document's in: where each page was. A pull
1903
+ * passes it; without it the backend's state is read, which after that merge names a moved
1904
+ * page at both its routes
1857
1905
  * @returns {{ config: object, collections: object, locales: object, pages: string[], sections: string[], layout: string[], deleted: string[], renamed: object[] }}
1858
1906
  */
1859
- export function siteContentDocumentToProject({ document, siteRoot, backend = null, sourceLocale = documentSourceLocale(document), prune = false, keepAuthoredFoundation = false, scope, dataModel = null, sectionType = DEFAULT_SECTION_TYPE, writableMounts = [] }) {
1907
+ export function siteContentDocumentToProject({ document, siteRoot, backend = null, sourceLocale = documentSourceLocale(document), prune = false, keepAuthoredFoundation = false, scope, dataModel = null, sectionType = DEFAULT_SECTION_TYPE, writableMounts = [], priorItems = null }) {
1860
1908
  // Before anything is written: a pull that would leave content out of the files stops here.
1861
1909
  refuseContentFilesCannotHold(document, sourceLocale)
1862
1910
 
@@ -1913,7 +1961,11 @@ export function siteContentDocumentToProject({ document, siteRoot, backend = nul
1913
1961
  // A read-only mount's pages, and a route the files give two pages for, are neither written nor
1914
1962
  // pruned. Each record's place, once decided, is the one every pass below reads (`places`).
1915
1963
  // 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
1964
+ // ⭐ AS THEY STOOD BEFORE THIS PULL (`priorItems`): in a repository the pull runs where there is no
1965
+ // rename index, so where a page was is read from these alone. ⛔ Until 2026-11-05 they were read
1966
+ // after the pull had merged the pulled document's in, so a page the app moved had both routes, and
1967
+ // the one kept was whichever sorted last: a held page's files were pruned from where they were.
1968
+ const items = priorItems ?? (backend ? readBackendState(siteRoot, backend).items : null)
1917
1969
  ctx.seen = seenPageRoutes(items)
1918
1970
  ctx.itemRoutes = itemRoutesOf(items)
1919
1971
  ctx.kept = new Set()
package/src/uwx/site.js CHANGED
@@ -47,7 +47,7 @@
47
47
 
48
48
  import { readdir, readFile } from 'node:fs/promises'
49
49
  import { dataBlockModels } from '../i18n/data-models.js'
50
- import { SINGLE_SECTION } from './route-mode.js'
50
+ import { ATOMIC, ATOMIC_PARENT, REGULAR } from './route-mode.js'
51
51
  import { existsSync } from 'node:fs'
52
52
  import { join, parse, relative } from 'node:path'
53
53
  import {
@@ -811,7 +811,8 @@ async function folderModePageRecords(ctx, dirPath, orderConfig, isRoot) {
811
811
  const data = buildPageData(config, {
812
812
  where: relative(siteRoot, filePath),
813
813
  slug: name,
814
- mode: 'page',
814
+ // One `.md` file in folder mode: a page of exactly one section and no child page (`route-mode.js`).
815
+ mode: ATOMIC,
815
816
  isDynamic: false,
816
817
  isRoot,
817
818
  siteIndex,
@@ -853,11 +854,12 @@ async function walkPagesNested(ctx, dirPath, parentSlugPath, inheritedMode, pare
853
854
  // ONE page whose sections were its `.md` files while the build rendered each as a
854
855
  // page of its own. Nothing warned, and a pull then wrote a `page.yml` into the
855
856
  // folder, converting the author's own site to the wrong shape.
856
- // ⭐ WHAT ITS PAGES MAY HOLD, not how the files hold them: `single-section` where they are a folder-mode
857
- // folder's `.md` files, one section each, else `page`. The mode its PAGES are read in (`childMode`), so
858
- // a page above a mounted folder of `.md` pages says it too, with its own sections. The app reads it to
859
- // offer no second section there. ⛔ Until 2026-11-04 it was the folder's own mode, spelled `folder`.
860
- const mode = f.childMode === 'pages' ? SINGLE_SECTION : 'page'
857
+ // ⭐ THE PAGE'S OWN MODE (`route-mode.js`): `atomic-parent` for a directory in folder mode, which holds
858
+ // no section and whose child pages are its `.md` files and directories; else `regular` — a page above
859
+ // a mounted folder of `.md` pages included, since it holds sections of its own. Its `.md` pages are
860
+ // `atomic` (`folderModePageRecords`). ⛔ Until 2026-11-05 this was what its pages may hold, read from the
861
+ // mode they are read in (`childMode`): `single-section` here, and `page` on the pages under it.
862
+ const mode = f.internalMode === 'pages' ? ATOMIC_PARENT : REGULAR
861
863
  const slugPath = parentSlugPath ? `${parentSlugPath}/${slug}` : slug
862
864
 
863
865
  const data = buildPageData(f.config, {
@@ -56,7 +56,8 @@ const withBaseVersion = (baseVersions, itemBaseVersions, { every = false } = {})
56
56
  // present AND for items the files dropped. A push deletes only the items it holds a
57
57
  // version for, and only while the site left them unchanged — so a dropped item's
58
58
  // version is what makes leaving it out a deletion, and without it the item is kept
59
- // [Diego, 2026-10-07; backend's gate]. The
59
+ // [Diego, 2026-10-07; backend's gate]. One exception: an item a pull held and the push leaves out
60
+ // (`leaveHeldOut`), whose version the site-content lane drops, since its being left out keeps it. The
60
61
  // caller holds a version only for an item it has seen (`heldTokens`, cli), so none is
61
62
  // ever sent for an item the backend holds and this copy does not.
62
63
  // ⛔ Until then this narrowed to the units the document carried: a dropped page was
@@ -577,7 +578,7 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
577
578
  // hands a pull to record. A walk of its own, made only when a pull held something.
578
579
  const heldUnits = opts.heldUnits && typeof opts.heldUnits === 'object' && Object.keys(opts.heldUnits).length ? opts.heldUnits : null
579
580
  const plain = siteDoc && (heldUnits || opts.unitHashes) ? await siteProjectToDocument(siteRoot, { ...docOpts, media: null }) : null
580
- const held = heldUnits ? leaveHeldOut(siteDoc, { held: heldUnits, plain, sourceLocale }) : { left: [], changed: [] }
581
+ const held = heldUnits ? leaveHeldOut(siteDoc, { held: heldUnits, plain, sourceLocale }) : { left: [], changed: [], uuids: [] }
581
582
  let unitHashes = null
582
583
  let unitUuids = null
583
584
  if (plain && opts.unitHashes) {
@@ -665,7 +666,17 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
665
666
  // --- site-content lane -------------------------------------------------------
666
667
  let siteContent = null
667
668
  if (siteEntity && changed(siteEntity)) {
668
- siteContent = { ...emitLane([stampSite(siteEntity)], exporter, exportedAt), index: [{ kind: 'site' }] }
669
+ // ⭐ NO VERSION FOR WHAT A PULL HELD AND THIS PUSH LEAVES OUT (`leaveHeldOut`'s `uuids`): with one,
670
+ // leaving it out is a deletion, the opposite of keeping the app's version.
671
+ const leftOut = new Set(held.uuids || [])
672
+ const stamp = leftOut.size
673
+ ? withBaseVersion(
674
+ opts.baseVersions || {},
675
+ Object.fromEntries(Object.entries(opts.itemBaseVersions || {}).filter(([uuid]) => !leftOut.has(uuid))),
676
+ { every: true }
677
+ )
678
+ : stampSite
679
+ siteContent = { ...emitLane([stamp(siteEntity)], exporter, exportedAt), index: [{ kind: 'site' }] }
669
680
  }
670
681
 
671
682
  // The site's current uuid (from site.yml): the verb keys the folder push route on