@uniweb/build 1.15.6 → 1.16.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@uniweb/build",
3
- "version": "1.15.6",
3
+ "version": "1.16.1",
4
4
  "description": "Build tooling for the Uniweb Component Web Platform",
5
5
  "type": "module",
6
6
  "exports": {
@@ -58,10 +58,10 @@
58
58
  "yaml": "^2.5.0",
59
59
  "@uniweb/content-reader": "~1.5.9",
60
60
  "@uniweb/semantic-parser": "~1.13.2",
61
- "@uniweb/schemas": "~1.6.8",
62
- "@uniweb/projections": "~1.2.11",
61
+ "@uniweb/schemas": "~1.6.10",
63
62
  "@uniweb/theming": "~1.2.1",
64
- "@uniweb/content-writer": "~1.3.1"
63
+ "@uniweb/content-writer": "~1.3.1",
64
+ "@uniweb/projections": "~1.2.11"
65
65
  },
66
66
  "optionalDependencies": {
67
67
  "@uniweb/runtime": "~1.4.5"
@@ -73,8 +73,8 @@
73
73
  "@tailwindcss/vite": "^4.0.0",
74
74
  "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
75
75
  "vite-plugin-svgr": "^4.0.0",
76
- "@uniweb/runtime": "~1.4.5",
77
- "@uniweb/core": "~1.6.4"
76
+ "@uniweb/core": "~1.6.4",
77
+ "@uniweb/runtime": "~1.4.5"
78
78
  },
79
79
  "peerDependenciesMeta": {
80
80
  "vite": {
@@ -11,6 +11,9 @@
11
11
  */
12
12
 
13
13
  export { collectSiteContent, pageSectionFiles } from '../site/content-collector.js'
14
+ // The one rule for a leading number that orders a name (`1-hero`, `2.5-x`, `404`), for a headless
15
+ // caller that lists a folder as the collector reads it (`@uniweb/unipress`'s `materialize.js`).
16
+ export { parseNumericPrefix, compareByNumericPrefix } from '../utils/numeric-prefix.js'
14
17
 
15
18
  // Query + fetch resolution. Pure functions on the clean dep
16
19
  // chain — re-exported here so headless callers (unipress, sidecars)
package/src/schema.js CHANGED
@@ -17,7 +17,7 @@ import { isFontVar } from '@uniweb/theming'
17
17
  import { join, dirname, extname, basename, relative, resolve } from 'node:path'
18
18
  import { pathToFileURL } from 'node:url'
19
19
  import { jsxInJsMessage } from './jsx-extension.js'
20
- import { describeChildren, describeVisuals, lowerChildren } from '@uniweb/schemas/component'
20
+ import { areaNames, describeChildren, describePlacement, describeVisuals, lowerChildren } from '@uniweb/schemas/component'
21
21
  import { describeContent, lowerData } from '@uniweb/schemas/content'
22
22
  import { normalizeData, schemaDeclarationOf } from '@uniweb/schemas/foundation'
23
23
  import { rootListSection } from '@uniweb/schemas/conform'
@@ -653,6 +653,7 @@ function buildComponentEntry(name, relativePath, meta) {
653
653
  if (meta.data !== undefined) entry.data = lowerData(meta.data)
654
654
  refuseDataDeclarations(`${name} (meta.js)`, entry.data)
655
655
  refuseStickyDeclaration(`${name} (meta.js)`, meta.sticky)
656
+ refuseAreaDeclaration(`${name} (meta.js)`, meta.area)
656
657
 
657
658
  const problems = [...content.problems, ...describeChildren(meta).problems]
658
659
  if (problems.length > 0) loweringProblems.set(entry, problems)
@@ -676,6 +677,51 @@ function refuseStickyDeclaration(owner, sticky) {
676
677
  }
677
678
  }
678
679
 
680
+ /**
681
+ * Refuse a section type's `area:` that `areaNames` cannot read — anything but `true`, `false`, an
682
+ * area's name or a list of names. A refusal, not a warning: an editor reads such a value as no
683
+ * area, and would offer the type among a page's sections, the opposite of what was meant.
684
+ *
685
+ * @param {string} owner - who declares it, for the message
686
+ * @param {*} area - the `area:` value, as written
687
+ */
688
+ function refuseAreaDeclaration(owner, area) {
689
+ try {
690
+ areaNames(area)
691
+ } catch (err) {
692
+ throw new Error(`[uniweb] ${owner}: ${err.message}`)
693
+ }
694
+ }
695
+
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.
703
+ *
704
+ * @param {Object} components - discovered section types, by name
705
+ * @param {Object} [layouts] - discovered layouts, by name
706
+ * @param {Object} [options]
707
+ * @param {boolean} [options.isExtension]
708
+ */
709
+ export function reportAreaNames(components, layouts = {}, { isExtension = false } = {}) {
710
+ 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))
713
+ for (const [name, entry] of Object.entries(components)) {
714
+ for (const area of describePlacement(entry).areas || []) {
715
+ if (drawn.has(area)) continue
716
+ 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 ` +
719
+ `area it names. Name one of those, or add "${area}" to the areas: of the layout that draws it.`
720
+ )
721
+ }
722
+ }
723
+ }
724
+
679
725
  /**
680
726
  * Refuse a `data:` key typed by a schema that is not written as one: the retired `/*` suffix, a
681
727
  * property of the long form other than `schema`, `single` and `whole`, or a flag that is not a
@@ -1284,6 +1330,7 @@ export async function buildSchema(srcDir, sectionPaths, derivedSupports = null)
1284
1330
 
1285
1331
  // Determine extension role
1286
1332
  const isExtension = !!foundationConfig.extension
1333
+ reportAreaNames(components, layouts, { isExtension })
1287
1334
 
1288
1335
  // Warn if extension declares things it shouldn't
1289
1336
  if (isExtension) {
@@ -20,19 +20,51 @@
20
20
  * Nothing is written until the whole copy is planned, so a refusal leaves no trace.
21
21
  */
22
22
 
23
- import { existsSync, statSync } from 'node:fs'
23
+ import { existsSync, readdirSync, statSync } from 'node:fs'
24
24
  import { copyFile, mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises'
25
25
  import { dirname, join, posix, resolve, relative } from 'node:path'
26
26
  import yaml from 'js-yaml'
27
27
  import { isVersionFolder } from '@uniweb/projections/versions'
28
28
  import { YAML_OPTIONS } from '../utils/yaml-schema.js'
29
29
  import { collectSiteContent, mountEntriesOf, readFolderConfig, readYamlFile, rootOrderConfig } from './content-collector.js'
30
+ import { parseNumericPrefix } from '../utils/numeric-prefix.js'
30
31
 
31
32
  const routeKey = (route) => String(route).replace(/^\/+/, '').replace(/\/+$/, '')
32
33
  const CONFIG_FILES = new Set(['page.yml', 'folder.yml'])
33
34
  // What of the docs folder's own config still describes the copy. The rest names the folder itself.
34
35
  const CARRIED_KEYS = ['pages', 'sections', 'nest', 'redirect']
35
36
 
37
+ // A page's name in a route: its folder's or file's, less the number that orders it (`2-guide` is `guide`).
38
+ const pageNameOf = (entry) => parseNumericPrefix(entry).name || entry
39
+
40
+ /**
41
+ * The folder holding a route's pages, as a path under `pages/` — each segment the folder whose page
42
+ * name it is, a mount's key where the first one is a mount — or null where no folder holds it.
43
+ */
44
+ function folderOfRoute(segments, { pagesDir, mounts }) {
45
+ const named = (dir, segment) => {
46
+ try {
47
+ return readdirSync(dir, { withFileTypes: true }).find((e) => e.isDirectory() && (e.name === segment || pageNameOf(e.name) === segment))?.name ?? null
48
+ } catch {
49
+ return null
50
+ }
51
+ }
52
+ const out = []
53
+ let dir = pagesDir
54
+ for (const [i, segment] of segments.entries()) {
55
+ if (i === 0 && mounts.has(segment)) {
56
+ out.push(segment)
57
+ dir = mounts.get(segment)
58
+ continue
59
+ }
60
+ const hit = named(dir, segment)
61
+ if (!hit) return null
62
+ out.push(hit)
63
+ dir = join(dir, hit)
64
+ }
65
+ return out.join('/')
66
+ }
67
+
36
68
  /**
37
69
  * The folder holding the docs, as a path under `pages/`.
38
70
  *
@@ -52,8 +84,11 @@ function findFolder(named, { pages, pagesDir, mounts, homepage }) {
52
84
  const segments = route.split('/').filter(Boolean)
53
85
  const at = segments.findIndex(isVersionFolder)
54
86
  if (at === -1) continue
55
- const above = segments.slice(0, at).join('/')
56
- holding.add(!above && homepage && existsSync(join(pagesDir, homepage, segments[0])) ? homepage : above)
87
+ const above = segments.slice(0, at)
88
+ // A homepage's own pages sit at the root, so a version there is in the homepage's folder.
89
+ const inHomepage = !above.length && homepage && folderOfRoute([homepage, segments[0]], { pagesDir, mounts })
90
+ const folder = inHomepage ? folderOfRoute([homepage], { pagesDir, mounts }) : folderOfRoute(above, { pagesDir, mounts })
91
+ holding.add(folder ?? (inHomepage ? homepage : above.join('/')))
57
92
  }
58
93
  if (holding.size === 1) return [...holding][0]
59
94
  if (holding.size > 1) {
@@ -246,15 +281,17 @@ export async function addVersion(siteRoot, { name, folder: named, label, keepInS
246
281
  throw new Error(`pages/${posix.join(folder, name)} already exists. To freeze the docs again, name a new version.`)
247
282
  }
248
283
 
249
- // Where the folder's pages are. A folder promoted to the homepage puts its pages at the root.
250
- const isHomepage = segments[0] === homepage
251
- const scope = `/${(isHomepage ? segments.slice(1) : segments).join('/')}`
284
+ // Where the folder's pages are, by their names as pages. A folder promoted to the homepage puts its
285
+ // pages at the root.
286
+ const routeSegments = segments.map(pageNameOf)
287
+ const isHomepage = routeSegments[0] === homepage
288
+ const scope = `/${(isHomepage ? routeSegments.slice(1) : routeSegments).join('/')}`
252
289
  const prefix = scope === '/' ? '' : scope
253
290
  const versionRoute = `${prefix}/${name}`
254
291
  const names = new Set(
255
292
  (await readdir(dir, { withFileTypes: true }))
256
293
  .filter((entry) => entry.isDirectory() || entry.name.endsWith('.md'))
257
- .map((entry) => entry.name.replace(/^\d+(\.\d+)*-/, '').replace(/\.md$/, ''))
294
+ .map((entry) => pageNameOf(entry.name.replace(/\.md$/, '')))
258
295
  .filter((entry) => !isVersionFolder(entry) && !(folder === '' && entry === '404'))
259
296
  )
260
297
 
@@ -26,7 +26,7 @@ import { isSectionKey } from '@uniweb/schemas/section'
26
26
  import { parseNumericPrefix, compareByNumericPrefix } from '../utils/numeric-prefix.js'
27
27
  import { isMarkdownFile, isIgnoredFolder } from '../utils/content-files.js'
28
28
  import { readLayoutFolder, DEFAULT_LAYOUT, layoutAreaRoute } from './layout-folder.js'
29
- import { mountEntriesOf, mountDeclarationsOf } from './mount-entries.js'
29
+ import { mountEntriesOf } from './mount-entries.js'
30
30
  import { basename, join, parse, relative, resolve, sep } from 'node:path'
31
31
  import { existsSync, statSync, realpathSync, readdirSync } from 'node:fs'
32
32
  import yaml from 'js-yaml'
@@ -628,14 +628,14 @@ function resolveMounts(pathsConfig, sitePath, pagesPath, { strict = false } = {}
628
628
  if (!pathsConfig || typeof pathsConfig !== 'object') return null
629
629
 
630
630
  // Extract entries with "pages/" prefix (e.g., "pages/docs": "../../../docs")
631
- const mountEntries = mountDeclarationsOf(pathsConfig)
631
+ const mountEntries = mountEntriesOf(pathsConfig)
632
632
 
633
633
  if (mountEntries.length === 0) return null
634
634
 
635
635
  const resolved = new Map()
636
636
  const canonicalPagesPath = existsSync(pagesPath) ? realpathSync(pagesPath) : resolve(pagesPath)
637
637
 
638
- for (const { segment: routeSegment, path: relativePath, declared } of mountEntries) {
638
+ for (const [routeSegment, relativePath] of mountEntries) {
639
639
  // Validate route segment (simple name, no slashes, no special chars)
640
640
  if (!routeSegment || routeSegment.includes('/') || routeSegment.startsWith('.') || routeSegment.startsWith('_')) {
641
641
  throw new Error(
@@ -644,24 +644,19 @@ function resolveMounts(pathsConfig, sitePath, pagesPath, { strict = false } = {}
644
644
  )
645
645
  }
646
646
 
647
- // ⭐ The object form says more of the mount: its `path`, and whether a pull may write into it. Any
648
- // other key is refused, so a misspelt `writable` is not a mount that reads as read-only.
649
- if (declared && typeof declared === 'object' && !Array.isArray(declared)) {
650
- const unknown = Object.keys(declared).filter((k) => k !== 'path' && k !== 'writable')
651
- if (unknown.length) {
652
- throw new Error(
653
- `[content-collector] The mount "pages/${routeSegment}" in site.yml paths has ${unknown.map((k) => `\`${k}\``).join(', ')}, which a mount does not take.\n` +
654
- ` A mount takes \`path:\`, its folder, and \`writable: true\` to let a pull write into it.`
655
- )
656
- }
657
- if (declared.writable !== undefined && typeof declared.writable !== 'boolean') {
658
- throw new Error(`[content-collector] The mount "pages/${routeSegment}" in site.yml paths says \`writable: ${JSON.stringify(declared.writable)}\`; it takes true or false.`)
659
- }
647
+ // ⛔ A mount is its folder. `{ path, writable }` was its form for part of 2026-11-04; whether a pull
648
+ // writes into a mount is no setting now, so the object is refused, saying what replaced it.
649
+ if (relativePath !== null && typeof relativePath === 'object' && !Array.isArray(relativePath)) {
650
+ const named = typeof relativePath.path === 'string' && relativePath.path ? relativePath.path : '../docs'
651
+ throw new Error(
652
+ `[content-collector] The mount "pages/${routeSegment}" in site.yml paths is an object. A mount is its folder: \`pages/${routeSegment}: ${named}\`.\n` +
653
+ ` \`writable\` is retired: a pull writes the app's edits into a mounted folder wherever it can merge them — a folder of the site's repository, or of a submodule — and holds them where it cannot.`
654
+ )
660
655
  }
661
656
  if (typeof relativePath !== 'string' || !relativePath) {
662
657
  throw new Error(
663
658
  `[content-collector] The mount "pages/${routeSegment}" in site.yml paths names no folder.\n` +
664
- ` Give it one: \`pages/${routeSegment}: ../docs\`, or \`path: ../docs\` in its object.`
659
+ ` Give it one: \`pages/${routeSegment}: ../docs\`.`
665
660
  )
666
661
  }
667
662
 
@@ -777,6 +772,30 @@ export function layerMountedFolder(name, local, mounted, contentMode) {
777
772
  return { dirConfig, dirMode, childMode }
778
773
  }
779
774
 
775
+ /**
776
+ * ⛔ A page with a `page.yml` of its own inside folder mode stops a site's build, and with it a push: in
777
+ * folder mode each page is one `.md` file holding one section, so a page whose parent is in folder mode is
778
+ * always that, and the app offers no second section there. A document's content (`document.yml`) is in
779
+ * folder mode by default, and a chapter of several sections is a `page.yml` there, so this is a site's
780
+ * rule only. A page of several sections, or a parametric one,
781
+ * goes outside the folder. ⭐ One rule for the build's walk (`collectPagesRecursive`) and the push's
782
+ * (`uwx/site.js::orderedSubfolders`), so a site that cannot build cannot sync either [Diego, 2026-11-04:
783
+ * "we can agree with framework to forbid the case … We have never seen a need for it"]. ⛔ Until then a
784
+ * `page.yml` there switched its folder back to page mode.
785
+ *
786
+ * @param {string} contentMode - the mode of the level the folder is on
787
+ * @param {string} dirMode - the folder's own, from `layerMountedFolder`
788
+ * @param {string} where - the folder, as the message names it
789
+ */
790
+ export function refusePageInFolderMode(contentMode, dirMode, where) {
791
+ if (contentMode !== 'pages' || dirMode !== 'sections') return
792
+ throw new Error(
793
+ `[uniweb] pages: \`${where}\` has a page.yml of its own inside folder mode, where each page is one \`.md\` ` +
794
+ `file holding one section — a folder.yml above it puts it there. Make it one \`.md\` file, or move it out ` +
795
+ `of the folder. A folder that holds no \`.md\` page of its own can take a page.yml instead of its folder.yml.`
796
+ )
797
+ }
798
+
780
799
  /**
781
800
  * A folder-mode folder's `.md` pages, in the order the build lists them: by filename (numeric
782
801
  * prefix first), then by the folder's own `pages:`. Each name is the page's slug — the filename
@@ -854,10 +873,11 @@ function extractH1(proseMirrorDoc) {
854
873
 
855
874
  /**
856
875
  * Prettify a slug into a human-readable title.
857
- * Strips numeric prefixes, replaces hyphens with spaces, title-cases.
876
+ * Strips a numeric prefix (`parseNumericPrefix`, the one rule), replaces hyphens with spaces, title-cases.
877
+ * ⛔ Until 2026-11-04 it stripped by a rule of its own, so `2.5-setup` was titled "5 Setup".
858
878
  */
859
879
  function prettifySlug(slug) {
860
- const stripped = slug.replace(/^\d+[-.]?\s*/, '')
880
+ const stripped = parseNumericPrefix(slug).name
861
881
  return stripped
862
882
  .split('-')
863
883
  .map(word => word.charAt(0).toUpperCase() + word.slice(1))
@@ -1972,22 +1992,14 @@ function determineIndexPage(orderConfig, availableFolders) {
1972
1992
  const declared = homepageOf(orderConfig)
1973
1993
  if (declared !== undefined) return declared
1974
1994
 
1975
- // 3. Fallback: lowest order value, or first alphabetically
1995
+ // 3. Fallback: the page that comes first, in the order the level's menu lists them (`compareFolders`):
1996
+ // lowest `order:`, then a folder's number, then its name.
1976
1997
  // IMPORTANT: Dynamic route folders (e.g., [slug]) can never be index pages
1977
1998
  // They are templates for dynamic content, not actual navigable pages
1978
1999
  const staticFolders = availableFolders.filter(f => !isDynamicRoute(f.name))
1979
2000
  if (staticFolders.length === 0) return null
1980
2001
 
1981
- const sorted = [...staticFolders].sort((a, b) => {
1982
- // Sort by order (lower first), then alphabetically
1983
- // Pages without explicit order come after ordered pages
1984
- const orderA = a.order ?? Infinity
1985
- const orderB = b.order ?? Infinity
1986
- if (orderA !== orderB) return orderA - orderB
1987
- return versionFoldersLast(a.name, b.name) || a.name.localeCompare(b.name)
1988
- })
1989
-
1990
- return sorted[0].name
2002
+ return [...staticFolders].sort(compareFolders)[0].name
1991
2003
  }
1992
2004
 
1993
2005
  /**
@@ -2017,7 +2029,7 @@ function notePagesOfHomepage(pages) {
2017
2029
  * page at its own address, while a push kept the folder as a container at `/`, leading to it.
2018
2030
  * @returns {Promise<Object>} { pages, assetCollection, iconCollection, notFound }
2019
2031
  */
2020
- async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig = {}, parentFetch = null, contentMode = 'sections', mounts = null, parentLayout = null, isSiteRoot = false) {
2032
+ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig = {}, parentFetch = null, contentMode = 'sections', mounts = null, parentLayout = null, isSiteRoot = false, isSite = true) {
2021
2033
  const entries = await readdir(dirPath)
2022
2034
  const pages = []
2023
2035
  let assetCollection = {
@@ -2058,12 +2070,17 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
2058
2070
  const mounted = mountPath ? await readFolderConfig(mountPath, 'pages') : null
2059
2071
  const local = localPath ? await readFolderConfig(localPath, contentMode) : null
2060
2072
  const { dirConfig, dirMode, childMode } = layerMountedFolder(name, local, mounted, contentMode)
2073
+ if (isSite) refusePageInFolderMode(contentMode, dirMode, relative(siteRoot, localPath ?? mountPath))
2061
2074
  if (mountPath && localPath) await warnOfLocalFoldersUnderAMount(localPath, name)
2062
2075
 
2063
2076
  const folderLayout = normalizeLayoutConfig(dirConfig.layout)
2064
2077
 
2065
2078
  pageFolders.push({
2066
- name,
2079
+ // ⭐ ITS NAME AS A PAGE: the folder's, less the number that orders it — `2-about/` is `/about`, as
2080
+ // `1-install.md` is `/install` — on every lane [Diego, 2026-11-04: "The build should drop the number
2081
+ // too"]. ⛔ Until then the build served `2-about/` at `/2-about` while a push sent it as `about`.
2082
+ name: isDynamicRoute(name) ? name : parseNumericPrefix(name).name,
2083
+ dirName: name,
2067
2084
  path: localPath ?? mountPath,
2068
2085
  order: typeof dirConfig.order === 'number' ? dirConfig.order : undefined,
2069
2086
  dirConfig,
@@ -2077,14 +2094,9 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
2077
2094
  })
2078
2095
  }
2079
2096
 
2080
- // Sort page folders by order (ascending), then alphabetically
2081
- // Pages without explicit order come after ordered pages (order ?? Infinity)
2082
- pageFolders.sort((a, b) => {
2083
- const orderA = a.order ?? Infinity
2084
- const orderB = b.order ?? Infinity
2085
- if (orderA !== orderB) return orderA - orderB
2086
- return versionFoldersLast(a.name, b.name) || a.name.localeCompare(b.name)
2087
- })
2097
+ // A level's folders in the order every lane reads them in (`compareFolders`): `order:`, then the
2098
+ // number a folder's name starts with, then its name.
2099
+ pageFolders.sort(compareFolders)
2088
2100
 
2089
2101
  // Apply ordering: pages: (wildcard-aware) > order: [array] (backward compat) > default
2090
2102
  let orderedFolders
@@ -2156,8 +2168,8 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
2156
2168
  continue
2157
2169
  }
2158
2170
 
2159
- const { name: entry, path: entryPath, dirConfig, dirMode, childMode, childOrderConfig, childLayout } = child
2160
- assertRouteFolder(entry, parentRoute)
2171
+ const { name: entry, dirName, path: entryPath, dirConfig, dirMode, childMode, childOrderConfig, childLayout } = child
2172
+ assertRouteFolder(dirName, parentRoute)
2161
2173
  const isIndex = entry === indexName
2162
2174
  const effectiveLayout = mergeLayoutConfig(parentLayout, childLayout)
2163
2175
 
@@ -2191,11 +2203,11 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
2191
2203
  // Recurse into subdirectories (page mode). When the children come from
2192
2204
  // a mount, they are walked in the mount's own mode — it is the mount's
2193
2205
  // tree, and its root config is what declared how its content is shaped.
2194
- const childDirPath = mounts?.get(entry) || entryPath
2206
+ const childDirPath = mounts?.get(dirName) || entryPath
2195
2207
  const childParentRoute = isIndex ? parentRoute : page.route
2196
2208
  const childFetch = page.fetch || parentFetch
2197
2209
  const childContentMode = childMode
2198
- const subResult = await collectPagesRecursive(childDirPath, childParentRoute, siteRoot, childOrderConfig, childFetch, childContentMode, null, effectiveLayout)
2210
+ const subResult = await collectPagesRecursive(childDirPath, childParentRoute, siteRoot, childOrderConfig, childFetch, childContentMode, null, effectiveLayout, false, isSite)
2199
2211
  pages.push(...subResult.pages)
2200
2212
  assetCollection = mergeAssetCollections(assetCollection, subResult.assetCollection)
2201
2213
  iconCollection = mergeIconCollections(iconCollection, subResult.iconCollection)
@@ -2244,9 +2256,9 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
2244
2256
  pages.push(containerPage)
2245
2257
 
2246
2258
  // Recurse in folder mode — pass container's own fetch config (or fall back to parent's)
2247
- const childDirPath = mounts?.get(entry) || entryPath
2259
+ const childDirPath = mounts?.get(dirName) || entryPath
2248
2260
  const containerFetch = containerPage.fetch || parentFetch
2249
- const subResult = await collectPagesRecursive(childDirPath, containerRoute, siteRoot, childOrderConfig, containerFetch, childMode, null, effectiveLayout)
2261
+ const subResult = await collectPagesRecursive(childDirPath, containerRoute, siteRoot, childOrderConfig, containerFetch, childMode, null, effectiveLayout, false, isSite)
2250
2262
  pages.push(...subResult.pages)
2251
2263
  assetCollection = mergeAssetCollections(assetCollection, subResult.assetCollection)
2252
2264
  iconCollection = mergeIconCollections(iconCollection, subResult.iconCollection)
@@ -2286,8 +2298,8 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
2286
2298
 
2287
2299
  // Second pass: process each page folder
2288
2300
  for (const folder of orderedFolders) {
2289
- const { name: entry, path: entryPath, dirConfig, dirMode, childMode, childOrderConfig, childLayout } = folder
2290
- assertRouteFolder(entry, parentRoute)
2301
+ const { name: entry, dirName, path: entryPath, dirConfig, dirMode, childMode, childOrderConfig, childLayout } = folder
2302
+ assertRouteFolder(dirName, parentRoute)
2291
2303
  const isIndex = entry === indexPageName
2292
2304
  const effectiveLayout = mergeLayoutConfig(parentLayout, childLayout)
2293
2305
 
@@ -2341,9 +2353,9 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
2341
2353
 
2342
2354
  // The container's own fetch config, or the parent's — as the folder-mode
2343
2355
  // container above passes it.
2344
- const childDirPath = mounts?.get(entry) || entryPath
2356
+ const childDirPath = mounts?.get(dirName) || entryPath
2345
2357
  const containerFetch = containerPage.fetch || parentFetch
2346
- const subResult = await collectPagesRecursive(childDirPath, containerRoute, siteRoot, childOrderConfig, containerFetch, childMode, null, effectiveLayout)
2358
+ const subResult = await collectPagesRecursive(childDirPath, containerRoute, siteRoot, childOrderConfig, containerFetch, childMode, null, effectiveLayout, false, isSite)
2347
2359
  pages.push(...subResult.pages)
2348
2360
  assetCollection = mergeAssetCollections(assetCollection, subResult.assetCollection)
2349
2361
  iconCollection = mergeIconCollections(iconCollection, subResult.iconCollection)
@@ -2377,13 +2389,13 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
2377
2389
  // walked in the mount's own mode — its root config declared how its
2378
2390
  // content is shaped, and this local stub holds none of that content.
2379
2391
  {
2380
- const childDirPath = mounts?.get(entry) || entryPath
2392
+ const childDirPath = mounts?.get(dirName) || entryPath
2381
2393
  const childParentRoute = isIndex
2382
2394
  ? (hasExplicitOrder ? parentRoute : (page.sourcePath || page.route))
2383
2395
  : page.route
2384
2396
  const childFetch = page.fetch || parentFetch
2385
2397
  const childContentMode = childMode
2386
- const subResult = await collectPagesRecursive(childDirPath, childParentRoute, siteRoot, childOrderConfig, childFetch, childContentMode, null, effectiveLayout)
2398
+ const subResult = await collectPagesRecursive(childDirPath, childParentRoute, siteRoot, childOrderConfig, childFetch, childContentMode, null, effectiveLayout, false, isSite)
2387
2399
  pages.push(...subResult.pages)
2388
2400
  assetCollection = mergeAssetCollections(assetCollection, subResult.assetCollection)
2389
2401
  iconCollection = mergeIconCollections(iconCollection, subResult.iconCollection)
@@ -2756,7 +2768,7 @@ export async function collectSiteContent(sitePath, options = {}) {
2756
2768
 
2757
2769
  // Recursively collect all pages
2758
2770
  let { pages, assetCollection, iconCollection, notFound } =
2759
- await collectPagesRecursive(pagesPath, '/', sitePath, siteOrderConfig, null, rootContentMode, mounts, siteLayout, true)
2771
+ await collectPagesRecursive(pagesPath, '/', sitePath, siteOrderConfig, null, rootContentMode, mounts, siteLayout, true, profile === CONTENT_PROFILES['site.yml'])
2760
2772
 
2761
2773
  // The layout sections' assets and icons, beside the pages'.
2762
2774
  assetCollection = mergeAssetCollections(assetCollection, layoutAssets)
@@ -3145,26 +3157,29 @@ function buildRouteTranslations(pages, { defaultLocale = 'en', languages = null
3145
3157
  }
3146
3158
 
3147
3159
  /**
3148
- * One level's pages in the order a push walks them, and a pull reproduces: explicit `order:`, then
3149
- * numeric-prefix filename order, then the parent config's `pages:` list. Shared by the push's walk
3150
- * (`uwx/site.js::orderedSubfolders`) and the pull (`uwx/site-project.js`), so the two cannot
3151
- * disagree on what a level's order is.
3160
+ * Two of a level's page folders, in the order every lane reads them: explicit `order:`, then version
3161
+ * folders after the rest, then the number a folder's name starts with, then its name. The build's walk
3162
+ * (`collectPagesRecursive`) sorts with it, and `orderFolders` below.
3152
3163
  *
3153
- * ⚠️ The build's own page-folder sort (`collectPagesRecursive`) is not this function: it compares
3154
- * folder names whole, as strings. The two differ only for numbered page folders — see the note at
3155
- * `orderedSubfolders`.
3164
+ * @param {{ dirName: string, order?: number }} a
3165
+ * @param {{ dirName: string, order?: number }} b
3166
+ */
3167
+ function compareFolders(a, b) {
3168
+ return (a.order ?? Infinity) - (b.order ?? Infinity) || versionFoldersLast(a.dirName, b.dirName) || compareFilenames(a.dirName, b.dirName)
3169
+ }
3170
+
3171
+ /**
3172
+ * One level's pages in the order a push walks them, and a pull reproduces: `compareFolders`, then the
3173
+ * parent config's `pages:` list — the order the build gives them too. Shared by the push's walk
3174
+ * (`uwx/site.js::orderedSubfolders`) and the pull (`uwx/site-project.js`), so no two lanes can
3175
+ * disagree on what a level's order is.
3156
3176
  *
3157
3177
  * @param {Array<{ dirName: string, name: string, order?: number }>} folders
3158
3178
  * @param {Array} [parentPages] - the parent config's `pages:`
3159
3179
  * @returns {Array} the folders, ordered
3160
3180
  */
3161
3181
  function orderFolders(folders, parentPages) {
3162
- const sorted = [...folders].sort(
3163
- (a, b) =>
3164
- (a.order ?? Infinity) - (b.order ?? Infinity) ||
3165
- versionFoldersLast(a.dirName, b.dirName) ||
3166
- compareFilenames(a.dirName, b.dirName)
3167
- )
3182
+ const sorted = [...folders].sort(compareFolders)
3168
3183
  const parsed = Array.isArray(parentPages) ? parseWildcardArray(parentPages) : null
3169
3184
  return parsed && parsed.mode !== 'all' ? applyWildcardOrder(sorted, parsed) : sorted
3170
3185
  }
package/src/site/index.js CHANGED
@@ -15,9 +15,6 @@ export { DEV_PORT_ENV, DEV_RECORD_ENV, runningDevServer, stopDevServer } from '.
15
15
  // Where a statically built site lives, as its deploy target or author states it (`./site-address.js`).
16
16
  export { ORIGIN_ENV, refuseUnreadableAddress } from './site-address.js'
17
17
  export { collectSiteContent, mountEntriesOf } from './content-collector.js'
18
- // Each mount with what its declaration says — whether a pull may write into it among it — for the
19
- // CLI, which decides which ones a pull can (`./mount-entries.js`).
20
- export { mountDeclarationsOf } from './mount-entries.js'
21
18
  export { addVersion } from './add-version.js'
22
19
  // The favicon a build links when site.yml names none, for `uniweb doctor` (`./favicon.js`).
23
20
  export { findPublicFavicon } from './favicon.js'
@@ -9,38 +9,21 @@
9
9
  * one definition of what a mount key looks like, so the prefix can never mean one
10
10
  * thing to one of them and another to the next.
11
11
  *
12
- * A mount is a folder, `pages/docs: ../docs`, or an object saying more of it,
13
- * `pages/docs: { path: ../docs, writable: true }`: each reader here is handed the
14
- * folder, and `mountDeclarationsOf` the rest (`resolveMounts` refuses a malformed one).
12
+ * A mount is its folder, `pages/docs: ../docs`, and nothing else. ⭐ Whether a pull writes
13
+ * the app's edits into it is no setting: it does wherever it can merge them, a folder of
14
+ * the site's repository or of a submodule, and holds them where it cannot (the CLI's
15
+ * `utils/site-roots.js`) [Diego, 2026-11-04]. ⛔ An object, `{ path, writable }`, was a
16
+ * mount's form for part of that day; `resolveMounts` refuses it, saying so. Each value is
17
+ * handed over as written, so a reader never takes such an object for no mount at all.
15
18
  *
16
19
  * A leaf, with no imports, so a module that must stay light can ask it.
17
20
  *
18
21
  * @param {Object} pathsConfig - The paths: object from site.yml
19
- * @returns {Array<[string, string]>} [routeSegment, relativePath] pairs
22
+ * @returns {Array<[string, *]>} [routeSegment, folder] pairs — a folder is a string
20
23
  */
21
24
  export function mountEntriesOf(pathsConfig) {
22
- return mountDeclarationsOf(pathsConfig).map(({ segment, path }) => [segment, path])
23
- }
24
-
25
- /**
26
- * Each mount with what its declaration says: its route `segment`, its folder's `path`, and whether
27
- * a pull may write into it (`writable`) — ⭐ a pull writes a mounted folder only where the site says
28
- * so; the string form only reads.
29
- *
30
- * @param {Object} pathsConfig - The paths: object from site.yml
31
- * @returns {Array<{ segment: string, path: string, writable: boolean, declared: unknown }>}
32
- */
33
- export function mountDeclarationsOf(pathsConfig) {
34
25
  if (!pathsConfig || typeof pathsConfig !== 'object') return []
35
26
  return Object.entries(pathsConfig)
36
27
  .filter(([key]) => key.startsWith('pages/'))
37
- .map(([key, value]) => {
38
- const object = value !== null && typeof value === 'object' && !Array.isArray(value)
39
- return {
40
- segment: key.slice('pages/'.length),
41
- path: object ? value.path : value,
42
- writable: object && value.writable === true,
43
- declared: value,
44
- }
45
- })
28
+ .map(([key, value]) => [key.slice('pages/'.length), value])
46
29
  }
@@ -12,7 +12,11 @@
12
12
  /**
13
13
  * Split a leading numeric prefix off a filename stem.
14
14
  *
15
- * Dots are sub-levels, so `1`, `1.5`, `2` order as you would read them.
15
+ * ⭐ A NUMBER ORDERS ONLY WHERE A DASH FOLLOWS IT, `1-hero`, or where it is the whole name, `404`,
16
+ * as the docs teach it [Diego, 2026-11-04: "tighten the rule"]. Dots are sub-levels, so `1`, `1.5`,
17
+ * `2` order as you would read them, and `2.5-x` slots between. ⛔ Until 2026-11-04 the dash was
18
+ * optional, so `3d-printing` read as 3 and `d-printing`, `100days` as `days`: every lane that drops
19
+ * the number dropped a name's own digits, and `05b-books.md` was a section called `b-books`.
16
20
  *
17
21
  * ⛔ THE RECORDS LANE USES THIS FOR ORDERING ONLY — it does NOT strip the prefix
18
22
  * from a record's slug. A record's slug is its filename stem, whole. An earlier
@@ -30,9 +34,9 @@
30
34
  * @returns {{ prefix: string|null, name: string }}
31
35
  */
32
36
  export function parseNumericPrefix(filename) {
33
- const match = filename.match(/^(\d+(?:\.\d+)*)-?(.*)$/)
37
+ const match = filename.match(/^(\d+(?:\.\d+)*)(?:-(.+))?$/)
34
38
  if (match) {
35
- return { prefix: match[1], name: match[2] || match[1] }
39
+ return { prefix: match[1], name: match[2] ?? match[1] }
36
40
  }
37
41
  return { prefix: null, name: filename }
38
42
  }