@uniweb/build 1.15.4 → 1.15.6

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.4",
3
+ "version": "1.15.6",
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.7",
60
- "@uniweb/content-reader": "~1.5.8",
61
- "@uniweb/theming": "~1.2.1",
62
- "@uniweb/content-writer": "~1.3.1",
59
+ "@uniweb/content-reader": "~1.5.9",
63
60
  "@uniweb/semantic-parser": "~1.13.2",
64
- "@uniweb/projections": "~1.2.11"
61
+ "@uniweb/schemas": "~1.6.8",
62
+ "@uniweb/projections": "~1.2.11",
63
+ "@uniweb/theming": "~1.2.1",
64
+ "@uniweb/content-writer": "~1.3.1"
65
65
  },
66
66
  "optionalDependencies": {
67
67
  "@uniweb/runtime": "~1.4.5"
package/src/prerender.js CHANGED
@@ -25,6 +25,7 @@ import {
25
25
  } from '@uniweb/core'
26
26
  import { isDynamicRoute, recordTitle, recordImage, routePatternToRegex, routeFieldOf } from '@uniweb/core/route-match'
27
27
  import DataStore from '@uniweb/core/datastore'
28
+ import { DEFAULT_ICON_BASE } from '@uniweb/core/icon-corpus'
28
29
  import { executeFetch, mergeDataIntoContent, toFetchList } from './site/data-fetcher.js'
29
30
  import { createFileTransport } from './site/file-transport.js'
30
31
  import { shouldSplitContent } from './site/split-content.js'
@@ -685,6 +686,81 @@ function dedupeByAddress(entries) {
685
686
  return out
686
687
  }
687
688
 
689
+ /**
690
+ * ⭐ THE ICON CORPUS, ASKED BY THE DATA STEP ONCE PER ICON AND NEVER WAITED FOR TWICE. The step asks
691
+ * for a page's icons on every page, skips the ones the graph holds and waits a moment for the rest
692
+ * (`loadPageData`, `icons: true`), so an icon that arrived is asked once. One that did not, a name
693
+ * the corpus lacks or a request the network drops, would be asked again by every page naming it,
694
+ * and a dropped one costs each of those pages the whole wait. So:
695
+ *
696
+ * - each icon address's answer is kept for the build, every locale's pages included, and a later
697
+ * page gets it at once, a failure as well;
698
+ * - a request from an earlier page still on its way when the next page starts says the corpus
699
+ * answers slower than the step waits, so the rest of the build asks it nothing and says so once.
700
+ * Those icons stay on the browser's path, as every such icon was before the step asked for them.
701
+ *
702
+ * Measured 2026-11-04 with every icon request dropped, each failing at Node's 10 s connect timeout:
703
+ * a project of 13 pages built in 44 s with 104 icon requests while the step asked for icons this
704
+ * way, and in 26 s with 52 since, where it took 23 s and 38 when the step asked for none; one of 288
705
+ * pages in 24 languages, 450 s and 3,540 requests, then 246 s and 272, where none took 245 s and
706
+ * 264. What is left is the site-wide prefetch's, which waits once for each language. Built on a
707
+ * working network, both drew every icon either way, in the same time.
708
+ *
709
+ * @param {string} base - the icon corpus the step asks, as `iconUrl` builds its addresses
710
+ * @param {Function} warn - told once, when the corpus stops being asked
711
+ */
712
+ function iconAsker(base, warn) {
713
+ const prefix = `${String(base).replace(/\/+$/, '')}/`
714
+ const answers = new Map()
715
+ // ⭐ What is still on its way is abandoned when the corpus stops being asked, and when the build
716
+ // is done: a request a page stopped waiting for otherwise holds the build open until the
717
+ // network gives up on it.
718
+ const abandon = new AbortController()
719
+ let onTheirWay = 0
720
+ let silent = false
721
+ const answered = (entry, url) => {
722
+ if (!entry.answer) throw new TypeError(`[prerender] no answer for ${url}`)
723
+ return new Response(entry.answer.body || null, { status: entry.answer.status })
724
+ }
725
+ return {
726
+ /** Abandons what is still on its way: the build has drawn its last page. */
727
+ done() {
728
+ abandon.abort()
729
+ },
730
+ /** The transport for one page's step, over the build's own (`createFileTransport`). */
731
+ forPage(transport) {
732
+ if (onTheirWay > 0 && !silent) {
733
+ silent = true
734
+ abandon.abort()
735
+ warn(`The icon corpus at ${base} is answering slower than a page waits; the rest of this build leaves the icons its pages name beyond their content for the browser to fetch.`)
736
+ }
737
+ return async function stepTransport(input, init) {
738
+ const url = typeof input === 'string' ? input : input?.url
739
+ if (typeof url !== 'string' || !url.startsWith(prefix)) return transport(input, init)
740
+ const known = answers.get(url)
741
+ if (known) {
742
+ if (known.answer === undefined) throw new TypeError(`[prerender] ${url} is still on its way`)
743
+ return answered(known, url)
744
+ }
745
+ if (silent) throw new TypeError(`[prerender] not asked, the icon corpus is not answering: ${url}`)
746
+ const entry = { answer: undefined }
747
+ answers.set(url, entry)
748
+ onTheirWay++
749
+ try {
750
+ const signal = init?.signal ? AbortSignal.any([init.signal, abandon.signal]) : abandon.signal
751
+ const response = await transport(input, { ...init, signal })
752
+ entry.answer = { status: response.status, body: response.ok ? await response.text() : null }
753
+ } catch {
754
+ entry.answer = null
755
+ } finally {
756
+ onTheirWay--
757
+ }
758
+ return answered(entry, url)
759
+ }
760
+ },
761
+ }
762
+ }
763
+
688
764
  /** The icons a page's HTML already carries in `__ICON_CACHE__`, by key; none when it carries none. */
689
765
  function embeddedIcons(html) {
690
766
  const script = html.match(/<script[^>]*id="__ICON_CACHE__"[^>]*>([\s\S]*?)<\/script>/)
@@ -886,6 +962,8 @@ export async function prerenderSite(siteDir, options = {}) {
886
962
  // Discover all locale content files
887
963
  // Said once more at the end: a build's log is long, and these lines are in the middle of it.
888
964
  const failedIcons = new Set()
965
+ // The data step's way to the icon corpus, for every locale (`iconAsker`): made with the first.
966
+ let icons = null
889
967
  const localeConfigs = await discoverLocaleContents(distDir, defaultSiteContent)
890
968
  if (localeConfigs.length > 1) {
891
969
  onProgress(`Found ${localeConfigs.length} locales: ${localeConfigs.map(l => l.locale).join(', ')}`)
@@ -1027,6 +1105,10 @@ export async function prerenderSite(siteDir, options = {}) {
1027
1105
 
1028
1106
  // Pre-render each page
1029
1107
  const website = uniweb.activeWebsite
1108
+ icons ??= iconAsker(website.config?.icons?.base || DEFAULT_ICON_BASE, (message) => {
1109
+ console.warn(`[prerender] ${message}`)
1110
+ onProgress(` ${message}`)
1111
+ })
1030
1112
 
1031
1113
  /**
1032
1114
  * ⭐ A PAGE RENDERS AGAINST WHAT IT CARRIES — the entries its HTML embeds, which are all the
@@ -1125,14 +1207,15 @@ export async function prerenderSite(siteDir, options = {}) {
1125
1207
  const asked = await loadPageData({
1126
1208
  website,
1127
1209
  route: page,
1128
- fetch: fileTransport,
1210
+ fetch: icons.forPage(fileTransport),
1129
1211
  prerender: 'author',
1130
1212
  cache: buildDataCache,
1131
1213
  // ⭐ The icons the site names for this page beyond the ones `prefetchIcons` already holds,
1132
1214
  // the image icons of the whole site's content: a link's icon, a param's, a tagged data
1133
- // block's, a record's. One the graph holds is not asked again, so a build fetches each
1134
- // icon once. ⛔ Until 2026-11-04 this said `false`, and every such icon was a blank box in
1135
- // the built page until the browser fetched it.
1215
+ // block's, a record's. One the graph holds is not asked again, and the transport keeps
1216
+ // the answer to every other (`iconAsker`), so a build asks for each icon once.
1217
+ // ⛔ Until 2026-11-04 this said `false`, and every such icon was a blank box in the built
1218
+ // page until the browser fetched it.
1136
1219
  icons: true,
1137
1220
  })
1138
1221
  // Filed under this page, the way a route-bound view always has been: `scopeFetchedData`
@@ -1314,6 +1397,8 @@ export async function prerenderSite(siteDir, options = {}) {
1314
1397
  onProgress,
1315
1398
  })
1316
1399
 
1400
+ // Every page is drawn: what the data step still waits on from the icon corpus is abandoned.
1401
+ icons?.done()
1317
1402
  onProgress(`\nPre-rendered ${renderedFiles.length} pages across ${localeConfigs.length} locale(s)`)
1318
1403
  if (failedIcons.size > 0) {
1319
1404
  console.warn(`[prerender] These icons could not be fetched and are missing from the pages: ${[...failedIcons].join(', ')}`)
@@ -26,6 +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
30
  import { basename, join, parse, relative, resolve, sep } from 'node:path'
30
31
  import { existsSync, statSync, realpathSync, readdirSync } from 'node:fs'
31
32
  import yaml from 'js-yaml'
@@ -555,7 +556,7 @@ async function readFolderConfig(dirPath, inheritedMode) {
555
556
  /**
556
557
  * A folder's content mode from its two config files — `readFolderConfig`'s rule, as a pure
557
558
  * function, so a synchronous reader applies the same one: the pull, which must know which pages
558
- * a folder's `.md` files are (`uwx/git-authored.js`).
559
+ * a folder's `.md` files are (`uwx/page-files.js`).
559
560
  *
560
561
  * - a `folder.yml` with keys → folder mode
561
562
  * - else a `page.yml` with keys → page mode
@@ -604,25 +605,8 @@ function mountHasContent(dirPath) {
604
605
  })
605
606
  }
606
607
 
607
- /**
608
- * The `pages/<segment>` keys in a site.yml `paths:` group, unvalidated.
609
- *
610
- * Split out from resolveMounts so the dev server can learn which directories a
611
- * site mounts without re-running resolveMounts' validation — that would repeat
612
- * its warnings on every startup, and the watcher only needs paths. Every reader —
613
- * the collector, the watcher, a pull (`uwx/git-authored.js`) and `uniweb status` among
614
- * them — shares this one definition of what a mount key looks like, so the prefix can never mean
615
- * one thing to one of them and another to the next.
616
- *
617
- * @param {Object} pathsConfig - The paths: object from site.yml
618
- * @returns {Array<[string, string]>} [routeSegment, relativePath] pairs
619
- */
620
- export function mountEntriesOf(pathsConfig) {
621
- if (!pathsConfig || typeof pathsConfig !== 'object') return []
622
- return Object.entries(pathsConfig)
623
- .filter(([key]) => key.startsWith('pages/'))
624
- .map(([key, value]) => [key.slice('pages/'.length), value])
625
- }
608
+ // The one definition of a mount key, a leaf (`./mount-entries.js`), re-exported for its readers here.
609
+ export { mountEntriesOf }
626
610
 
627
611
  /**
628
612
  * Extract page mounts from site.yml paths: config.
@@ -644,14 +628,14 @@ function resolveMounts(pathsConfig, sitePath, pagesPath, { strict = false } = {}
644
628
  if (!pathsConfig || typeof pathsConfig !== 'object') return null
645
629
 
646
630
  // Extract entries with "pages/" prefix (e.g., "pages/docs": "../../../docs")
647
- const mountEntries = mountEntriesOf(pathsConfig)
631
+ const mountEntries = mountDeclarationsOf(pathsConfig)
648
632
 
649
633
  if (mountEntries.length === 0) return null
650
634
 
651
635
  const resolved = new Map()
652
636
  const canonicalPagesPath = existsSync(pagesPath) ? realpathSync(pagesPath) : resolve(pagesPath)
653
637
 
654
- for (const [routeSegment, relativePath] of mountEntries) {
638
+ for (const { segment: routeSegment, path: relativePath, declared } of mountEntries) {
655
639
  // Validate route segment (simple name, no slashes, no special chars)
656
640
  if (!routeSegment || routeSegment.includes('/') || routeSegment.startsWith('.') || routeSegment.startsWith('_')) {
657
641
  throw new Error(
@@ -660,6 +644,27 @@ function resolveMounts(pathsConfig, sitePath, pagesPath, { strict = false } = {}
660
644
  )
661
645
  }
662
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
+ }
660
+ }
661
+ if (typeof relativePath !== 'string' || !relativePath) {
662
+ throw new Error(
663
+ `[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.`
665
+ )
666
+ }
667
+
663
668
  const absolutePath = resolve(sitePath, relativePath)
664
669
 
665
670
  // Check existence
@@ -3188,6 +3193,10 @@ export {
3188
3193
  resolveMounts,
3189
3194
  findSectionFile,
3190
3195
  processNesting,
3196
+ // The title a folder-mode `.md` page gives — its first heading, else its name — which a pull asks
3197
+ // before it writes one back (`uwx/page-files.js`).
3198
+ extractH1,
3199
+ prettifySlug,
3191
3200
  }
3192
3201
 
3193
3202
  export default collectSiteContent
@@ -14,6 +14,11 @@
14
14
  * The anchor is translated too. A link written for GitHub names GitHub's anchor for a heading, and a
15
15
  * page's heading has its own (`headingId`, `@uniweb/kit`): "it doesn't — matter" is
16
16
  * `it-doesnt--matter` on one and `it-doesn-t-matter` on the other.
17
+ *
18
+ * ⭐ AND A PULL PUTS EACH ONE BACK AS THE FILE WROTE IT (`fileLinksIn`). ⛔ Until 2026-11-04 a pull wrote
19
+ * the backend's page link into the file in its place, so every file of a docs folder linking another
20
+ * by file read as changed and came back with `/docs/...` links, which lead nowhere on GitHub: 68 of the
21
+ * framework's own docs, measured that day, the first time a pull wrote into a mounted docs folder.
17
22
  */
18
23
  import { realpathSync } from 'node:fs'
19
24
  import { dirname, relative, resolve } from 'node:path'
@@ -30,6 +35,11 @@ export function carrySectionFile(from, to) {
30
35
  if (FILES.has(from)) FILES.set(to, FILES.get(from))
31
36
  }
32
37
 
38
+ /** The file a section — or a record the push made from one — was read from, or null. */
39
+ export function sectionFileOf(section) {
40
+ return FILES.get(section) ?? null
41
+ }
42
+
33
43
  // A relative path to a markdown file: no scheme, no leading `/`, `#` or `?`.
34
44
  const FILE_LINK = /^(?![a-z][a-z0-9+.-]*:|[/#?])([^#?]+\.md)(?:#(.*))?$/i
35
45
 
@@ -97,6 +107,43 @@ function rewriteDoc(node, rewrite) {
97
107
  if (Array.isArray(node.content)) for (const child of node.content) rewriteDoc(child, rewrite)
98
108
  }
99
109
 
110
+ /**
111
+ * The pages a site's files became, for the links written as files: each file by its real path, with
112
+ * its page's route, its section's id where the page is of several files, and its headings' anchors.
113
+ *
114
+ * @param {Array<{ route: string, files: Array<{ file: string, id: string|null, content: object }> }>} pages
115
+ * @returns {Map<string, { route: string, section: string|null, anchors: Map<string, string> }>}
116
+ */
117
+ export function fileLinkTargets(pages) {
118
+ const files = new Map()
119
+ for (const { route, files: held } of pages) {
120
+ for (const { file, id, content } of held) {
121
+ // A page of several files: this file is a section of it, with an anchor of its own.
122
+ files.set(real(file), { route, section: held.length > 1 ? id || null : null, anchors: anchorsOf(content) })
123
+ }
124
+ }
125
+ return files
126
+ }
127
+
128
+ /**
129
+ * The page link a push writes for `href`, written in the file `from` — `{ href, missing }`, `missing`
130
+ * naming what it leads to that is not there (`'file'`, `'anchor'`) — or null for a link no file's.
131
+ *
132
+ * @param {string} href
133
+ * @param {string} from
134
+ * @param {Map} files - `fileLinkTargets`
135
+ * @returns {{ href: string, missing: 'file'|'anchor'|null }|null}
136
+ */
137
+ export function pageLinkFor(href, from, files) {
138
+ const link = FILE_LINK.exec(href)
139
+ if (!link) return null
140
+ const target = files.get(real(resolve(dirname(from), decode(link[1]))))
141
+ if (!target) return { href, missing: 'file' }
142
+ if (!link[2]) return { href: target.section ? `${target.route}#section-${target.section}` : target.route, missing: null }
143
+ const anchor = target.anchors.get(decode(link[2]))
144
+ return { href: `${target.route}#${anchor ?? link[2]}`, missing: anchor ? null : 'anchor' }
145
+ }
146
+
100
147
  /**
101
148
  * Rewrites every link written as a file, in the sections of a site's pages. Mutates the sections.
102
149
  *
@@ -105,39 +152,57 @@ function rewriteDoc(node, rewrite) {
105
152
  * @param {{ siteRoot: string, warn: (message: string) => void }} options
106
153
  */
107
154
  export function rewriteFileLinks(pages, { siteRoot, warn }) {
108
- const files = new Map()
109
- for (const { route, sections } of pages) {
110
- const held = []
111
- eachSection(sections, (section) => {
112
- if (FILES.has(section)) held.push(section)
113
- })
114
- for (const section of held) {
115
- files.set(real(FILES.get(section)), {
116
- route,
117
- // A page of several files: this file is a section of it, with an anchor of its own.
118
- section: held.length > 1 ? section.stableId || section.$id || null : null,
119
- anchors: anchorsOf(section.content),
155
+ const files = fileLinkTargets(
156
+ pages.map(({ route, sections }) => {
157
+ const held = []
158
+ eachSection(sections, (section) => {
159
+ if (FILES.has(section)) held.push({ file: FILES.get(section), id: section.stableId || section.$id || null, content: section.content })
120
160
  })
121
- }
122
- }
123
-
161
+ return { route, files: held }
162
+ })
163
+ )
124
164
  for (const { sections } of pages) {
125
165
  eachSection(sections, (section) => {
126
166
  const from = FILES.get(section)
127
167
  if (!from) return
128
168
  rewriteDoc(section.content, (href) => {
129
- const link = FILE_LINK.exec(href)
130
- if (!link) return href
131
- const target = files.get(real(resolve(dirname(from), decode(link[1]))))
132
- if (!target) {
133
- warn(`${relative(siteRoot, from)}: the link to ${href} names a file that is no page of this site, so it leads nowhere`)
134
- return href
135
- }
136
- if (!link[2]) return target.section ? `${target.route}#section-${target.section}` : target.route
137
- const anchor = target.anchors.get(decode(link[2]))
138
- if (!anchor) warn(`${relative(siteRoot, from)}: the link to ${href}: that page has no such heading`)
139
- return `${target.route}#${anchor ?? link[2]}`
169
+ const page = pageLinkFor(href, from, files)
170
+ if (page?.missing === 'file') warn(`${relative(siteRoot, from)}: the link to ${href} names a file that is no page of this site, so it leads nowhere`)
171
+ if (page?.missing === 'anchor') warn(`${relative(siteRoot, from)}: the link to ${href}: that page has no such heading`)
172
+ return page ? page.href : href
140
173
  })
141
174
  })
142
175
  }
143
176
  }
177
+
178
+ /**
179
+ * ⭐ A FILE'S LINKS AS A PUSH READS THEM, AND BACK, for a pull writing the backend's document into the
180
+ * file a section was read from (`uwx/project-writer.js`). `resolve` gives a node of the file the page
181
+ * links a push sends for its file links, so it compares with the backend's; `restore` writes each page
182
+ * link the file wrote as a file back in the file's own spelling — `../guide/deploying.md`, which works
183
+ * on GitHub and in an editor, never `/docs/guide/deploying`. A link the app added stays the app's.
184
+ *
185
+ * @param {string} from - the file
186
+ * @param {Map} files - `fileLinkTargets`
187
+ * @param {object|null} authored - the file's own document, as it reads
188
+ * @returns {{ resolve: (node: object) => object, restore: (node: object) => object }}
189
+ */
190
+ export function fileLinksIn(from, files, authored) {
191
+ const back = new Map()
192
+ if (authored) {
193
+ rewriteDoc(structuredClone(authored), (href) => {
194
+ const page = pageLinkFor(href, from, files)
195
+ if (page && page.href !== href && !back.has(page.href)) back.set(page.href, href)
196
+ return href
197
+ })
198
+ }
199
+ const mapped = (node, rewrite) => {
200
+ const copy = structuredClone(node)
201
+ rewriteDoc(copy, rewrite)
202
+ return copy
203
+ }
204
+ return {
205
+ resolve: (node) => mapped(node, (href) => pageLinkFor(href, from, files)?.href ?? href),
206
+ restore: (node) => (back.size ? mapped(node, (href) => back.get(href) ?? href) : node),
207
+ }
208
+ }
package/src/site/index.js CHANGED
@@ -15,6 +15,9 @@ 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'
18
21
  export { addVersion } from './add-version.js'
19
22
  // The favicon a build links when site.yml names none, for `uniweb doctor` (`./favicon.js`).
20
23
  export { findPublicFavicon } from './favicon.js'
@@ -0,0 +1,46 @@
1
+ /**
2
+ * The `pages/<segment>` keys in a site.yml `paths:` group, unvalidated.
3
+ *
4
+ * Split out from resolveMounts so the dev server can learn which directories a
5
+ * site mounts without re-running resolveMounts' validation — that would repeat
6
+ * its warnings on every startup, and the watcher only needs paths. Every reader —
7
+ * the collector, the watcher, a pull (`uwx/page-files.js`), the roots a push sends
8
+ * and a pull merges (`uwx/site-dirs.js`) and `uniweb status` among them — shares this
9
+ * one definition of what a mount key looks like, so the prefix can never mean one
10
+ * thing to one of them and another to the next.
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).
15
+ *
16
+ * A leaf, with no imports, so a module that must stay light can ask it.
17
+ *
18
+ * @param {Object} pathsConfig - The paths: object from site.yml
19
+ * @returns {Array<[string, string]>} [routeSegment, relativePath] pairs
20
+ */
21
+ 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
+ if (!pathsConfig || typeof pathsConfig !== 'object') return []
35
+ return Object.entries(pathsConfig)
36
+ .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
+ })
46
+ }
@@ -0,0 +1,85 @@
1
+ // ⭐ A PULL WRITES THE CHANGE, NOT A NEW RENDERING OF THE FILE.
2
+ // A changed body keeps the author's text for every top-level block the backend's document still holds,
3
+ // and takes the writer's form only for the blocks it changed, added or moved; a removed one goes.
4
+ //
5
+ // ⛔ Until 2026-11-04 a changed body was re-serialized whole. Measured that day over the 133 pages of
6
+ // three mounted docs folders: a one-word edit rewrote a median of 12 lines — every hard-wrapped
7
+ // paragraph joined, every table rule rewritten — in 115 of them.
8
+ //
9
+ // The blocks are the reader's (`markdownBlocks`, `@uniweb/content-reader`), so a block is what the
10
+ // author's text reads as, and a body the reader cannot split so, or whose splice does not read back to
11
+ // the document, is written whole as before.
12
+ //
13
+ // `links` reads a block as the push reads it, and writes a new one as the file writes its links
14
+ // (`site/file-links.js::fileLinksIn`): a block linking another file by its file is the block the
15
+ // backend holds with a page link, and keeps the author's link.
16
+
17
+ import { markdownBlocks } from '@uniweb/content-reader'
18
+ import { proseMirrorToMarkdown } from '@uniweb/content-writer'
19
+ import { canonicalJson, sameMarkdownDocument, withoutDefaults } from './same-content.js'
20
+
21
+ const keyOf = (node) => canonicalJson(withoutDefaults(node))
22
+
23
+ // The longest run of keys the two lists share, in order: each pair `[i, j]`, `a[i]` equal to `b[j]`.
24
+ function commonPairs(a, b) {
25
+ const n = a.length
26
+ const m = b.length
27
+ const dp = Array.from({ length: n + 1 }, () => new Uint32Array(m + 1))
28
+ for (let i = n - 1; i >= 0; i--) {
29
+ for (let j = m - 1; j >= 0; j--) dp[i][j] = a[i] === b[j] ? dp[i + 1][j + 1] + 1 : Math.max(dp[i + 1][j], dp[i][j + 1])
30
+ }
31
+ const pairs = []
32
+ for (let i = 0, j = 0; i < n && j < m; ) {
33
+ if (a[i] === b[j]) pairs.push([i++, j++])
34
+ else if (dp[i + 1][j] >= dp[i][j + 1]) i++
35
+ else j++
36
+ }
37
+ return pairs
38
+ }
39
+
40
+ /**
41
+ * The author's body with the backend's document written into it, block by block — or null when it
42
+ * cannot be said so, and the caller writes the document whole.
43
+ *
44
+ * @param {string} authored - the body as the file holds it, frontmatter apart
45
+ * @param {object} doc - the backend's ProseMirror document for it
46
+ * @param {{ links?: { resolve: Function, restore: Function }|null }} [opts]
47
+ * @returns {string|null} the new body, with no trailing whitespace
48
+ */
49
+ export function spliceBody(authored, doc, { links = null } = {}) {
50
+ const split = markdownBlocks(authored)
51
+ if (!split || !Array.isArray(doc?.content)) return null
52
+ // Each block that reads to one node is an item; one that reads to none (a link reference) rides
53
+ // with the item before it, kept where it was. A block of several nodes leaves nothing to align.
54
+ const items = []
55
+ let head = split.head
56
+ for (const block of split.blocks) {
57
+ if (block.nodes.length > 1) return null
58
+ if (block.nodes.length === 0) {
59
+ if (items.length) items[items.length - 1].after += block.text + block.after
60
+ else head += block.text + block.after
61
+ continue
62
+ }
63
+ items.push({ text: block.text, after: block.after, key: keyOf(links ? links.resolve(block.nodes[0]) : block.nodes[0]) })
64
+ }
65
+ const nodes = doc.content
66
+ const kept = new Map(commonPairs(items.map((i) => i.key), nodes.map(keyOf)).map(([i, j]) => [j, i]))
67
+ // The new body's pieces in the document's order: an item the change left as the author wrote it, or a
68
+ // run of nodes the writer writes.
69
+ const pieces = []
70
+ for (let j = 0; j < nodes.length; j++) {
71
+ if (kept.has(j)) pieces.push({ item: kept.get(j) })
72
+ else if (pieces.length && pieces[pieces.length - 1].nodes) pieces[pieces.length - 1].nodes.push(nodes[j])
73
+ else pieces.push({ nodes: [nodes[j]] })
74
+ }
75
+ let out = pieces[0]?.item === 0 ? head : ''
76
+ pieces.forEach((piece, k) => {
77
+ const written = links ? piece.nodes?.map((node) => links.restore(node)) : piece.nodes
78
+ out += written ? proseMirrorToMarkdown({ type: 'doc', content: written }).replace(/\s+$/, '') : items[piece.item].text
79
+ const next = pieces[k + 1]
80
+ // Two of the author's blocks still side by side keep what stood between them.
81
+ if (next) out += piece.item !== undefined && next.item === piece.item + 1 ? items[piece.item].after : '\n\n'
82
+ })
83
+ const body = out.replace(/^\n+/, '').replace(/\s+$/, '')
84
+ return sameMarkdownDocument(body, doc, { resolve: links?.resolve }) ? body : null
85
+ }
@@ -547,6 +547,10 @@ function lowerLeaf(field, resolve, optResolve, { multiple = false, path = '' } =
547
547
  if (field.label) out.label = field.label
548
548
  if (field.description) out.description = field.description
549
549
  if (field.required) out.required = true
550
+ // A value a site's visitor may fill, on any leaf kind, as authored [backend, 2026-11-04]. A type
551
+ // with one takes visitors' submissions; `@uniweb/schemas` refuses it where a registry would, and
552
+ // drops `false`, so only `true` is sent.
553
+ if (field.visitor_fills === true) out.visitor_fills = true
550
554
  // A field's rules, as written — `max_length`, `min`, `max`, `mime_types`, `max_size`,
551
555
  // `pattern` (`FIELD_RULES`): a registry keeps each as the field's own key and checks it on
552
556
  // every write. ⛔ Until 2026-10-15 the normalizer dropped them before this saw them.
@@ -77,9 +77,6 @@
77
77
  "og_title": [
78
78
  "site.yml::seo"
79
79
  ],
80
- "paths": [
81
- "site.yml::paths"
82
- ],
83
80
  "placeholders": [
84
81
  "site.yml::placeholders"
85
82
  ],
package/src/uwx/index.js CHANGED
@@ -89,6 +89,9 @@ export { dataBlockModels } from '../i18n/data-models.js'
89
89
  // The type a section that names none renders with — a push fills it in, and a pull, handed it up
90
90
  // front like the scope above, leaves it out of the section's file.
91
91
  export { siteDefaultSectionType } from '../site/queries-config.js'
92
+ // Every place a push reads the site's content from, mounts included — the one answer the CLI's
93
+ // committed-content check, a pull's merge and `uniweb status` read (`site-dirs.js`).
94
+ export { siteContentRoots } from './site-dirs.js'
92
95
  export {
93
96
  siteInfoToConfig,
94
97
  sectionRecordToFile,