@uniweb/build 1.10.14 → 1.11.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.
@@ -1203,7 +1203,7 @@ async function processMarkdownFile(filePath, id, siteRoot, defaultStableId = nul
1203
1203
  const assetCollection = collectSectionAssets(section, filePath, siteRoot)
1204
1204
 
1205
1205
  // Collect icons referenced in this section
1206
- const iconCollection = collectSectionIcons(section, filePath)
1206
+ const iconCollection = collectSectionIcons(section)
1207
1207
 
1208
1208
  return { section, assetCollection, iconCollection }
1209
1209
  }
@@ -1228,7 +1228,7 @@ async function processMarkdownFile(filePath, id, siteRoot, defaultStableId = nul
1228
1228
  */
1229
1229
  async function processNesting(sections, nestConfig, pagePath, siteRoot, cachedFiles) {
1230
1230
  const result = {
1231
- assetCollection: { assets: {}, hasExplicitPoster: new Set(), hasExplicitPreview: new Set() },
1231
+ assetCollection: { assets: {}, hasExplicitPoster: new Set() },
1232
1232
  iconCollection: { icons: new Set(), bySource: new Map() },
1233
1233
  lastModified: null,
1234
1234
  attachedChildren: new Set(),
@@ -1305,8 +1305,7 @@ async function processExplicitSections(sectionsConfig, pagePath, siteRoot, paren
1305
1305
  const sections = []
1306
1306
  let assetCollection = {
1307
1307
  assets: {},
1308
- hasExplicitPoster: new Set(),
1309
- hasExplicitPreview: new Set()
1308
+ hasExplicitPoster: new Set()
1310
1309
  }
1311
1310
  let iconCollection = {
1312
1311
  icons: new Set(),
@@ -1464,7 +1463,7 @@ async function processPage(pagePath, pageName, siteRoot, { isIndex = false, pare
1464
1463
  redirect: target,
1465
1464
  sections: []
1466
1465
  },
1467
- assetCollection: { assets: {}, hasExplicitPoster: new Set(), hasExplicitPreview: new Set() },
1466
+ assetCollection: { assets: {}, hasExplicitPoster: new Set() },
1468
1467
  iconCollection: { icons: new Set(), bySource: new Map() }
1469
1468
  }
1470
1469
  }
@@ -1490,7 +1489,7 @@ async function processPage(pagePath, pageName, siteRoot, { isIndex = false, pare
1490
1489
  rewrite: pageConfig.rewrite,
1491
1490
  sections: []
1492
1491
  },
1493
- assetCollection: { assets: {}, hasExplicitPoster: new Set(), hasExplicitPreview: new Set() },
1492
+ assetCollection: { assets: {}, hasExplicitPoster: new Set() },
1494
1493
  iconCollection: { icons: new Set(), bySource: new Map() }
1495
1494
  }
1496
1495
  }
@@ -1498,8 +1497,7 @@ async function processPage(pagePath, pageName, siteRoot, { isIndex = false, pare
1498
1497
  let hierarchicalSections = []
1499
1498
  let pageAssetCollection = {
1500
1499
  assets: {},
1501
- hasExplicitPoster: new Set(),
1502
- hasExplicitPreview: new Set()
1500
+ hasExplicitPoster: new Set()
1503
1501
  }
1504
1502
  let pageIconCollection = {
1505
1503
  icons: new Set(),
@@ -1939,8 +1937,7 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
1939
1937
  const pages = []
1940
1938
  let assetCollection = {
1941
1939
  assets: {},
1942
- hasExplicitPoster: new Set(),
1943
- hasExplicitPreview: new Set()
1940
+ hasExplicitPoster: new Set()
1944
1941
  }
1945
1942
  let iconCollection = {
1946
1943
  icons: new Set(),
@@ -2465,7 +2462,7 @@ export async function loadFoundationInfo(foundationPath) {
2465
2462
  * @returns {Promise<{ layouts: Object|null, assetCollection: Object, iconCollection: Object }>}
2466
2463
  */
2467
2464
  async function collectLayouts(layoutDir, siteRoot) {
2468
- let assetCollection = { assets: {}, hasExplicitPoster: new Set(), hasExplicitPreview: new Set() }
2465
+ let assetCollection = { assets: {}, hasExplicitPoster: new Set() }
2469
2466
  let iconCollection = { icons: new Set(), bySource: new Map() }
2470
2467
 
2471
2468
  const areas = await readLayoutFolder(layoutDir, { siteRoot })
@@ -2808,9 +2805,9 @@ export async function collectSiteContent(sitePath, options = {}) {
2808
2805
 
2809
2806
  // Log asset summary
2810
2807
  const assetCount = Object.keys(assetCollection.assets).length
2811
- const explicitCount = assetCollection.hasExplicitPoster.size + assetCollection.hasExplicitPreview.size
2808
+ const explicitCount = assetCollection.hasExplicitPoster.size
2812
2809
  if (assetCount > 0) {
2813
- console.log(`[content-collector] Found ${assetCount} asset references${explicitCount > 0 ? ` (${explicitCount} with explicit poster/preview)` : ''}`)
2810
+ console.log(`[content-collector] Found ${assetCount} asset references${explicitCount > 0 ? ` (${explicitCount} with an explicit poster)` : ''}`)
2814
2811
  }
2815
2812
 
2816
2813
  // Build icon manifest from collected icons
@@ -2969,7 +2966,6 @@ export async function collectSiteContent(sitePath, options = {}) {
2969
2966
  versionedScopes: versionedScopesObj,
2970
2967
  assets: assetCollection.assets,
2971
2968
  hasExplicitPoster: assetCollection.hasExplicitPoster,
2972
- hasExplicitPreview: assetCollection.hasExplicitPreview,
2973
2969
  // Icon manifest for preloading
2974
2970
  icons: iconManifest
2975
2971
  }
@@ -0,0 +1,49 @@
1
+ /**
2
+ * WHERE `uniweb dev` SERVES EACH MEDIA FILE A SITE NAMES — so dev shows the file a build ships.
3
+ *
4
+ * A build resolves each local media reference (`resolveAssetPath`, `./assets.js`) and rewrites it
5
+ * to the copy it makes (`processAssets`, `rewriteSiteContentPaths`). Dev ran neither, so a
6
+ * reference stayed as written and only one into `public/` reached its file: a co-located
7
+ * `./photo.png` was read against the page's URL, and answered with the site's HTML and a 200
8
+ * (measured 2026-10-28).
9
+ *
10
+ * So dev rewrites each reference the collector resolved — the same manifest, the same rewrite — to
11
+ * where the dev server serves its file: one in `public/` at the site's base, one under the root by
12
+ * its path from the root, and any other (a mounted folder's) through Vite's `/@fs/`.
13
+ */
14
+
15
+ import { existsSync } from 'node:fs'
16
+ import { isAbsolute, relative, sep } from 'node:path'
17
+ import { pathToFileURL } from 'node:url'
18
+
19
+ /**
20
+ * @param {Object} assets - the collector's manifest: each reference as written → `{ resolved }`
21
+ * @param {{ root: string, publicDir?: string|null, base?: string }} server - the dev server's
22
+ * root and public directory, and the site's base
23
+ * @returns {Object} each reference whose file exists → the address that serves it
24
+ */
25
+ export function devMediaPaths(assets, { root, publicDir = null, base = '/' }) {
26
+ const prefix = base.endsWith('/') ? base : `${base}/`
27
+ const mapping = {}
28
+ for (const [ref, entry] of Object.entries(assets || {})) {
29
+ const file = entry?.resolved
30
+ if (typeof file !== 'string' || !existsSync(file)) continue
31
+ const address = addressOf(file, { root, publicDir, prefix })
32
+ if (address !== ref) mapping[ref] = address
33
+ }
34
+ return mapping
35
+ }
36
+
37
+ function addressOf(file, { root, publicDir, prefix }) {
38
+ for (const dir of [publicDir, root]) {
39
+ const below = dir ? pathBelow(dir, file) : null
40
+ if (below) return prefix + below.split(sep).map(encodeURIComponent).join('/')
41
+ }
42
+ return `${prefix}@fs${pathToFileURL(file).pathname}`
43
+ }
44
+
45
+ /** `file`'s path below `dir`, or null when it is not inside it. */
46
+ function pathBelow(dir, file) {
47
+ const rel = relative(dir, file)
48
+ return rel && !isAbsolute(rel) && rel.split(sep)[0] !== '..' ? rel : null
49
+ }
package/src/site/icons.js CHANGED
@@ -86,33 +86,27 @@ export function walkContentIcons(doc, visitor) {
86
86
  /**
87
87
  * Collect all icon references from a section's content
88
88
  *
89
+ * ⛔ Until 2026-10-28 this also recorded the file each icon came from, and the
90
+ * manifest carried that map as `bySource`: the build machine's absolute paths, in
91
+ * every page's payload, read by nothing.
92
+ *
89
93
  * @param {Object} section - Section object with content
90
- * @param {string} sourcePath - Path to source file (for bySource tracking)
91
94
  * @returns {Object} Icon collection result
92
95
  * - icons: Set of normalized icon references (e.g., "lu:house")
93
- * - bySource: Map of icon references to source files
94
96
  */
95
- export function collectSectionIcons(section, sourcePath) {
97
+ export function collectSectionIcons(section) {
96
98
  const icons = new Set()
97
- const bySource = new Map()
98
99
 
99
100
  if (section.content) {
100
101
  walkContentIcons(section.content, (library, name) => {
101
102
  const normalizedLibrary = normalizeLibrary(library)
102
103
  if (!normalizedLibrary) return
103
104
 
104
- const iconRef = `${normalizedLibrary}:${name}`
105
- icons.add(iconRef)
106
-
107
- // Track which files use this icon
108
- if (!bySource.has(iconRef)) {
109
- bySource.set(iconRef, [])
110
- }
111
- bySource.get(iconRef).push(sourcePath)
105
+ icons.add(`${normalizedLibrary}:${name}`)
112
106
  })
113
107
  }
114
108
 
115
- return { icons, bySource }
109
+ return { icons }
116
110
  }
117
111
 
118
112
  /**
@@ -123,27 +117,13 @@ export function collectSectionIcons(section, sourcePath) {
123
117
  */
124
118
  export function mergeIconCollections(...collections) {
125
119
  const merged = {
126
- icons: new Set(),
127
- bySource: new Map()
120
+ icons: new Set()
128
121
  }
129
122
 
130
123
  for (const collection of collections) {
131
- if (!collection) continue
132
-
133
- // Merge icons set
134
- if (collection.icons) {
124
+ if (collection?.icons) {
135
125
  collection.icons.forEach(icon => merged.icons.add(icon))
136
126
  }
137
-
138
- // Merge bySource map
139
- if (collection.bySource) {
140
- for (const [iconRef, sources] of collection.bySource) {
141
- if (!merged.bySource.has(iconRef)) {
142
- merged.bySource.set(iconRef, [])
143
- }
144
- merged.bySource.get(iconRef).push(...sources)
145
- }
146
- }
147
127
  }
148
128
 
149
129
  return merged
@@ -156,7 +136,7 @@ export function mergeIconCollections(...collections) {
156
136
  * @returns {Object} Icon manifest for site-content.json
157
137
  */
158
138
  export function buildIconManifest(iconCollection) {
159
- const { icons, bySource } = iconCollection
139
+ const { icons } = iconCollection
160
140
 
161
141
  // Get unique families used
162
142
  const families = new Set()
@@ -165,16 +145,9 @@ export function buildIconManifest(iconCollection) {
165
145
  families.add(family)
166
146
  }
167
147
 
168
- // Convert bySource Map to plain object for JSON serialization
169
- const bySourceObj = {}
170
- for (const [iconRef, sources] of bySource) {
171
- bySourceObj[iconRef] = [...new Set(sources)] // dedupe sources
172
- }
173
-
174
148
  return {
175
149
  used: [...icons].sort(),
176
150
  families: [...families].sort(),
177
- bySource: bySourceObj,
178
151
  count: icons.size
179
152
  }
180
153
  }
@@ -34,6 +34,7 @@ import { partitionKnowledgePages, INDEX_FILENAME } from '@uniweb/projections'
34
34
  import { collectSiteContent, mountEntriesOf } from './content-collector.js'
35
35
  import { processAssets, rewriteSiteContentPaths } from './asset-processor.js'
36
36
  import { processAdvancedAssets } from './advanced-processors.js'
37
+ import { devMediaPaths } from './dev-media.js'
37
38
  import { processQueries, writeQueryFiles } from './query-processor.js'
38
39
  import { RECORDS_DIR, resolveRecordsDir } from './entity-pool.js'
39
40
  import { executeFetch, mergeDataIntoContent, toFetchList } from './data-fetcher.js'
@@ -264,7 +265,6 @@ import { mountDevSubmit } from '../dev/submit-mount.js'
264
265
  * @param {number} [options.assets.quality=80] - WebP quality (1-100)
265
266
  * @param {string} [options.assets.outputDir='assets'] - Output subdirectory for processed assets
266
267
  * @param {boolean} [options.assets.videoPosters=true] - Extract poster frames from videos (requires ffmpeg)
267
- * @param {boolean} [options.assets.pdfThumbnails=true] - Generate thumbnails for PDFs (requires pdf-lib)
268
268
  * @param {string} [options.foundationPath] - Path to foundation directory (for loading theme vars)
269
269
  */
270
270
  export function siteContentPlugin(options = {}) {
@@ -287,8 +287,7 @@ export function siteContentPlugin(options = {}) {
287
287
  convertToWebp: assetsConfig.convertToWebp !== false, // Default true
288
288
  quality: assetsConfig.quality || 80,
289
289
  outputDir: assetsConfig.outputDir || 'assets',
290
- videoPosters: assetsConfig.videoPosters !== false, // Default true
291
- pdfThumbnails: assetsConfig.pdfThumbnails !== false // Default true
290
+ videoPosters: assetsConfig.videoPosters !== false // Default true
292
291
  }
293
292
 
294
293
  /**
@@ -308,6 +307,18 @@ export function siteContentPlugin(options = {}) {
308
307
  return content
309
308
  }
310
309
 
310
+ /**
311
+ * Under `uniweb dev`, each local media reference rewritten to where the dev server serves its
312
+ * file (`./dev-media.js`), by the manifest and the rewrite a build uses — so dev shows the file
313
+ * a build ships. A build makes its own copies (`generateBundle`). The rewrite drops the
314
+ * manifest, as a build's does: no payload carries it.
315
+ */
316
+ const devMedia = (content) => {
317
+ if (isProduction || !content?.assets) return content
318
+ const mapping = devMediaPaths(content.assets, { root: viteRoot, publicDir: resolvedPublicDir, base: basePath })
319
+ return rewriteSiteContentPaths(content, mapping)
320
+ }
321
+
311
322
  // Warn once per build, not once per collection — the dev server re-collects
312
323
  // on every content change and would otherwise repeat this on every keystroke.
313
324
  let warnedAboutKnowledge = false
@@ -382,6 +393,7 @@ export function siteContentPlugin(options = {}) {
382
393
  let resolvedSitePath = null
383
394
  let resolvedPublicDir = null
384
395
  let resolvedOutDir = null
396
+ let viteRoot = null // Vite's config.root: the dev server serves a file under it by its path
385
397
  let isProduction = false
386
398
  let watcher = null
387
399
  let server = null
@@ -589,6 +601,7 @@ export function siteContentPlugin(options = {}) {
589
601
  resolvedSitePath = resolve(config.root, sitePath)
590
602
  resolvedPublicDir = config.publicDir || resolve(config.root, 'public')
591
603
  resolvedOutDir = resolve(config.root, config.build.outDir)
604
+ viteRoot = config.root
592
605
  isProduction = config.command === 'build'
593
606
  basePath = config.base || '/'
594
607
 
@@ -642,7 +655,7 @@ export function siteContentPlugin(options = {}) {
642
655
  // pages stay in the graph so in-progress drafts remain previewable.
643
656
  // strict on a production build: a mount that contributes no pages is a
644
657
  // warning while you author and a broken deploy once you ship.
645
- siteContent = locate(withDevServices(await collectForBundle(resolvedSitePath, { foundationPath, dropUnpublished: isProduction, base: basePath, strict: isProduction })))
658
+ siteContent = devMedia(locate(withDevServices(await collectForBundle(resolvedSitePath, { foundationPath, dropUnpublished: isProduction, base: basePath, strict: isProduction }))))
646
659
  dataModelPromise = null
647
660
  headHtml = await loadHeadHtml()
648
661
  console.log(`[site-content] Collected ${siteContent.pages?.length || 0} pages`)
@@ -789,7 +802,7 @@ export function siteContentPlugin(options = {}) {
789
802
  rebuildQueries = false
790
803
  console.log('[site-content] Content changed, rebuilding...')
791
804
  try {
792
- siteContent = locate(withDevServices(await collectForBundle(resolvedSitePath, { foundationPath, base: basePath })))
805
+ siteContent = devMedia(locate(withDevServices(await collectForBundle(resolvedSitePath, { foundationPath, base: basePath }))))
793
806
  dataModelPromise = null
794
807
  headHtml = await loadHeadHtml()
795
808
  if (materialize) {
@@ -1157,26 +1170,20 @@ export function siteContentPlugin(options = {}) {
1157
1170
  basePath
1158
1171
  })
1159
1172
 
1160
- // Process advanced assets (videos, PDFs)
1161
- const advancedEnabled = assetsOptions.videoPosters || assetsOptions.pdfThumbnails
1162
- let advancedResults = null
1163
-
1164
- if (advancedEnabled) {
1165
- const { posterMapping, thumbnailMapping, results: advResults } = await processAdvancedAssets(
1173
+ // A poster for each video its author gave none
1174
+ if (assetsOptions.videoPosters) {
1175
+ const { posterMapping, results: advResults } = await processAdvancedAssets(
1166
1176
  siteContent.assets,
1167
1177
  {
1168
1178
  outputDir: resolvedOutDir,
1169
1179
  assetsSubdir: assetsOptions.outputDir,
1170
1180
  videoPosters: assetsOptions.videoPosters,
1171
- pdfThumbnails: assetsOptions.pdfThumbnails,
1172
1181
  quality: assetsOptions.quality,
1173
1182
  basePath,
1174
- // Pass explicit poster/preview sets to skip auto-generation
1175
- hasExplicitPoster: siteContent.hasExplicitPoster || new Set(),
1176
- hasExplicitPreview: siteContent.hasExplicitPreview || new Set()
1183
+ // Pass the explicit poster set to skip auto-generation
1184
+ hasExplicitPoster: siteContent.hasExplicitPoster || new Set()
1177
1185
  }
1178
1186
  )
1179
- advancedResults = advResults
1180
1187
 
1181
1188
  // Log advanced processing results
1182
1189
  if (advResults.videos.processed > 0) {
@@ -1185,25 +1192,11 @@ export function siteContentPlugin(options = {}) {
1185
1192
  if (advResults.videos.explicit > 0) {
1186
1193
  console.log(`[site-content] Skipped ${advResults.videos.explicit} videos with explicit posters`)
1187
1194
  }
1188
- if (advResults.pdfs.processed > 0) {
1189
- console.log(`[site-content] Generated ${advResults.pdfs.processed} PDF thumbnails`)
1190
- }
1191
- if (advResults.pdfs.explicit > 0) {
1192
- console.log(`[site-content] Skipped ${advResults.pdfs.explicit} PDFs with explicit previews`)
1193
- }
1194
-
1195
- // Merge poster and thumbnail mappings into the path mapping
1196
- // Videos: add a .poster property to the content (not replace the src)
1197
- // PDFs: add a .thumbnail property to the content
1198
- finalContent = rewriteSiteContentPaths(siteContent, pathMapping, files)
1199
1195
 
1200
- // Add poster and thumbnail metadata to the site content
1201
- if (Object.keys(posterMapping).length > 0 || Object.keys(thumbnailMapping).length > 0) {
1202
- finalContent._assetMeta = {
1203
- posters: posterMapping,
1204
- thumbnails: thumbnailMapping
1205
- }
1206
- }
1196
+ // A video's generated poster goes on its node, as an authored one is
1197
+ // (`rewriteContentPaths`). ⛔ Until 2026-10-28 it went to a top-level `_assetMeta`
1198
+ // that nothing read, beside a placeholder card made for each PDF that no page used.
1199
+ finalContent = rewriteSiteContentPaths(siteContent, pathMapping, files, { posters: posterMapping })
1207
1200
  } else {
1208
1201
  // Rewrite paths in content
1209
1202
  finalContent = rewriteSiteContentPaths(siteContent, pathMapping, files)
@@ -1225,7 +1218,6 @@ export function siteContentPlugin(options = {}) {
1225
1218
 
1226
1219
  // Clean up internal properties that shouldn't be in the output (Sets don't serialize)
1227
1220
  delete finalContent.hasExplicitPoster
1228
- delete finalContent.hasExplicitPreview
1229
1221
 
1230
1222
  // Note: theme.css is kept here so prerender can inject it into HTML
1231
1223
  // Prerender will strip it from the JSON it injects into each page
@@ -0,0 +1,24 @@
1
+ /**
2
+ * `site.yml::preview` — the site's card image — is an author's address: a URL, or a
3
+ * path to an image in the project. This is the one test that says whether a value
4
+ * is one.
5
+ *
6
+ * Anything else is not the author's. The app once recorded a card image it generated
7
+ * as a token in this field, so a site.yml from an older pull may still hold one: the
8
+ * push leaves such a value out (`site.js`), a pull removes it (`site-project.js`), and
9
+ * `uniweb snapshot` replaces it.
10
+ *
11
+ * It recognizes the author's shapes rather than the token's, so it does not depend on
12
+ * the token's format: a URL, a path starting `/`, `./` or `../`, or a relative path to
13
+ * an image file (`images/card.png`).
14
+ */
15
+
16
+ const IMAGE_FILE = /\.(avif|gif|jpe?g|png|svg|webp)$/i
17
+
18
+ /**
19
+ * @param {unknown} value
20
+ * @returns {boolean} true when `value` is an author's address
21
+ */
22
+ export const isAuthoredPreview = (value) =>
23
+ typeof value === 'string' &&
24
+ (/^https?:\/\//i.test(value) || /^\.{0,2}\//.test(value) || IMAGE_FILE.test(value.trim()))
package/src/uwx/index.js CHANGED
@@ -198,6 +198,9 @@ export {
198
198
  writeThemeFile,
199
199
  writeRecordFile,
200
200
  } from './project-writer.js'
201
+ // Whether `site.yml::preview` is an author's address — the one test the push, the pull and
202
+ // `uniweb snapshot` share.
203
+ export { isAuthoredPreview } from './authored-preview.js'
201
204
 
202
205
  // Registry-publish (names-only) — the document `uniweb register` submits, and the
203
206
  // schema → @uniweb/data-schema declaration lowering it bundles. `buildRegistryPackage`
@@ -22,9 +22,10 @@ import yaml from 'js-yaml'
22
22
  import { YAML_OPTIONS } from '../utils/yaml-schema.js'
23
23
  import { proseMirrorToMarkdown, serializeInlineContent } from '@uniweb/content-writer'
24
24
  import { computeHash } from '../i18n/hash.js'
25
- import { blockElements, elementText, dataBlockNodes } from '../i18n/extract.js'
25
+ import { blockElements, elementText, dataBlockNodes, imageNodes, imageMarkup, TRANSLATED_IMAGE_ATTRS } from '../i18n/extract.js'
26
26
  import { visitDataBlockStrings } from '../i18n/data-strings.js'
27
- import { resolveDocForLocale, translatedInline, linkLabels, toPlainText } from '../i18n/merge.js'
27
+ import { resolveDocForLocale, translatedInline, translatedImage, linkLabels, toPlainText } from '../i18n/merge.js'
28
+ import { ASSET_SLOTS } from '@uniweb/semantic-parser'
28
29
  import { computeSourceHash, manifestText } from '../i18n/freeform-manifest.js'
29
30
  import { sameMarkdownDocument, canonicalJson } from './same-content.js'
30
31
  import { parseFrontmatter } from '../utils/frontmatter.js'
@@ -426,7 +427,60 @@ function deriveStructuralMap(sourceDoc, targetDoc, modelFor = () => null, checks
426
427
  // a mark we can't serialize → don't risk a lossy map; store as free-form
427
428
  return null
428
429
  }
429
- return addDataBlockStrings(map, sourceDoc, targetDoc, modelFor, checks)
430
+ const withData = addDataBlockStrings(map, sourceDoc, targetDoc, modelFor, checks)
431
+ return withData && addImageTranslations(withData, sourceDoc, targetDoc, checks)
432
+ }
433
+
434
+ // ⭐ AN IMAGE's translation, read pairwise — what a translation may give it (`merge.js::translateImages`):
435
+ // its words alone when only its alt text changed, else the image as inline markdown (`imageMarkup`),
436
+ // never the identity a push stamps beside a URL. Keyed by its source alt text, as extraction keys it.
437
+ // A target whose images differ in anything else — their number, a role, a size — or that changed an
438
+ // image with no alt text cannot be said per image, and the whole translation is free-form.
439
+ // ⛔ Until 2026-10-28 an image was not read here, and its translation was not sent either.
440
+ function addImageTranslations(map, sourceDoc, targetDoc, checks = null) {
441
+ const src = imageNodes(sourceDoc)
442
+ const tgt = imageNodes(targetDoc)
443
+ if (src.length !== tgt.length) return null
444
+ for (let i = 0; i < src.length; i++) {
445
+ const s = src[i].attrs || {}
446
+ const t = tgt[i].attrs || {}
447
+ if (canonicalJson(untranslated(s)) !== canonicalJson(untranslated(t))) return null
448
+ const changed = TRANSLATED_IMAGE_ATTRS.filter((attr) => (s[attr] ?? null) !== (t[attr] ?? null))
449
+ if (!changed.length) continue
450
+ const key = typeof s.alt === 'string' ? s.alt.trim() : ''
451
+ if (!key) return null
452
+ const words = typeof t.alt === 'string' ? t.alt.trim() : ''
453
+ const value = changed.every((attr) => attr === 'alt') ? words : imageMarkup(tgt[i])
454
+ if (!value) return null
455
+ // A text element of the same words read its own translation: the image's says them too when its
456
+ // words match, and a text element reads an image value as its words (`merge.js::translatedInline`).
457
+ if (map[key] !== undefined && map[key] !== value && toPlainText(map[key]).trim() !== words) return null
458
+ map[key] = value
459
+ if (checks) checks[key] = saysImage(s, t)
460
+ }
461
+ return map
462
+ }
463
+
464
+ // What a translation may not change about an image: everything but its words and files, and the
465
+ // identity a push stamps beside each URL.
466
+ const IMAGE_IDENTITY = new Set(ASSET_SLOTS.flatMap((slot) => [slot.id, slot.ext]))
467
+ function untranslated(attrs) {
468
+ const out = {}
469
+ for (const [key, value] of Object.entries(attrs)) {
470
+ if (TRANSLATED_IMAGE_ATTRS.includes(key) || IMAGE_IDENTITY.has(key)) continue
471
+ if (value != null) out[key] = value
472
+ }
473
+ return out
474
+ }
475
+
476
+ // Whether a value, pushed onto the source image, gives it what the pull read.
477
+ function saysImage(source, read) {
478
+ return (value) => {
479
+ if (typeof value !== 'string') return false
480
+ const given = translatedImage(value)
481
+ if (!given) return false
482
+ return TRANSLATED_IMAGE_ATTRS.every((attr) => (given[attr] ?? source[attr] ?? null) === (read[attr] ?? null))
483
+ }
430
484
  }
431
485
 
432
486
  // ⭐ WHAT SAYS A TRANSLATION, WHERE A PULL READ IT — the push's own rule for that place. A pull reads
@@ -0,0 +1,150 @@
1
+ /**
2
+ * MEDIA BESIDE A PAGE, ON THE SYNC LANE — how a push uploads a co-located file (`./team.jpg`) and
3
+ * a pull writes its reference back.
4
+ *
5
+ * A `/x` reference names one file wherever it is written, so a push uploads it under that name and
6
+ * `sync.json`'s asset map remembers its identity by it. `./team.jpg` names a different file beside
7
+ * every page, so the push keys it by the file's path in the site's tree — `pages/home/team.jpg` —
8
+ * as a file record is keyed (`file-records.js`). The tree is the site's folder with its `paths:` laid
9
+ * over it (`siteTree`): a folder mounted at `pages/docs` holds `pages/docs/…`, wherever it is on disk,
10
+ * and a pages folder `paths:` moves elsewhere still holds `pages/…`. The key goes into the upload and into `sync.json`,
11
+ * and into a document only where the emit was handed the upload that names it, which swaps it for
12
+ * the served URL in the same pass (`rewriteEntityAssets`): a document no upload went with keeps the
13
+ * reference as written. A pull writes the author's reference back, relative to the file the
14
+ * section is written to (`writtenRefs`).
15
+ *
16
+ * ⛔ Until 2026-10-28 a push uploaded only `/x` media and skipped a co-located file with a warning,
17
+ * so a site that showed its media under `uniweb dev` and in a static build lost it when published.
18
+ *
19
+ * ⚠️ A file outside both the site's folder and every folder its `paths:` names has no such key, and
20
+ * stays warned and skipped. Two files with the same bytes are one asset, so a pull may write either
21
+ * one's path.
22
+ */
23
+
24
+ import { existsSync } from 'node:fs'
25
+ import { dirname, isAbsolute, join, relative, sep } from 'node:path'
26
+
27
+ /**
28
+ * The site's tree, as its `paths:` lay it out: each folder mounted at `pages/<segment>`, the pages
29
+ * folder and the layout folder, by the path they hold in the site — `[path in the tree, folder]`.
30
+ * The site's own folder holds everything else.
31
+ *
32
+ * @param {string} siteRoot
33
+ * @param {{ pagesDir?: string, layoutDir?: string, mounts?: Map<string,string>|null }} dirs -
34
+ * `site-dirs.js::siteContentDirs`'s folders, and the build's mounts (route segment → folder)
35
+ * @returns {Array<[string, string]>}
36
+ */
37
+ export function siteTree(siteRoot, { pagesDir, layoutDir, mounts = null } = {}) {
38
+ const tree = []
39
+ for (const [segment, dir] of mounts || []) tree.push([`pages/${segment}`, dir])
40
+ if (pagesDir) tree.push(['pages', pagesDir])
41
+ if (layoutDir) tree.push(['layout', layoutDir])
42
+ return tree
43
+ }
44
+
45
+ /**
46
+ * The key a push uploads a site's file under: its path in the site's tree — in the most specific
47
+ * folder of `tree` that holds it, else in the site's own folder — or null for a file in neither.
48
+ *
49
+ * @param {string} siteRoot
50
+ * @param {string} file - absolute
51
+ * @param {Array<[string, string]>} [tree] - `siteTree`
52
+ * @returns {string|null} `pages/home/team.jpg`
53
+ */
54
+ export function siteFileKey(siteRoot, file, tree = []) {
55
+ const holders = [...tree].sort((a, b) => b[1].length - a[1].length)
56
+ for (const [prefix, dir] of holders) {
57
+ const rel = pathBelow(dir, file)
58
+ if (rel) return `${prefix}/${rel}`
59
+ }
60
+ return pathBelow(siteRoot, file)
61
+ }
62
+
63
+ /** The file a key names — the inverse of `siteFileKey`. */
64
+ export function siteFileOf(siteRoot, key, tree = []) {
65
+ const prefixes = [...tree].sort((a, b) => b[0].length - a[0].length)
66
+ for (const [prefix, dir] of prefixes) {
67
+ if (key.startsWith(`${prefix}/`)) return join(dir, key.slice(prefix.length + 1))
68
+ }
69
+ return join(siteRoot, key)
70
+ }
71
+
72
+ /** `file`'s path below `dir`, `/`-separated, or null when it is not inside it. */
73
+ function pathBelow(dir, file) {
74
+ const rel = relative(dir, file)
75
+ if (!rel || isAbsolute(rel) || rel.split(sep)[0] === '..') return null
76
+ return rel.split(sep).join('/')
77
+ }
78
+
79
+ /**
80
+ * Collects what a push makes of a site's co-located media: each file to upload, by its key, and
81
+ * one warning for each reference it cannot upload.
82
+ *
83
+ * @param {Object<string,string>|null} [uploaded] - the emit's upload map (`assetRewrite`): a
84
+ * reference whose key it names is replaced by the key, for the rewrite to swap
85
+ */
86
+ export function locatedMediaSink(uploaded = null) {
87
+ // `tree` is the site's, set where its folders are known (`site.js::siteProjectToDocument`).
88
+ return { uploaded, tree: [], files: new Map(), refs: new Set(), warned: new Set(), warnings: [] }
89
+ }
90
+
91
+ /**
92
+ * A section's co-located media, as a push takes it.
93
+ *
94
+ * @param {{ uses?: Array<{ ref: string, resolved: string, set: Function }> }} assetCollection -
95
+ * what the build's collection resolved, with a setter for where each reference is written
96
+ * (`site/assets.js::collectSectionAssets`)
97
+ * @param {{ siteRoot: string, filePath: string, sink: ReturnType<typeof locatedMediaSink> }} where
98
+ */
99
+ export function locateSectionMedia(assetCollection, { siteRoot, filePath, sink }) {
100
+ if (!sink) return
101
+ const named = siteFileKey(siteRoot, filePath, sink.tree) || relative(siteRoot, filePath).split(sep).join('/')
102
+ for (const use of assetCollection?.uses || []) {
103
+ const key = siteFileKey(siteRoot, use.resolved, sink.tree)
104
+ if (!key || !existsSync(use.resolved)) {
105
+ if (!sink.warned.has(use.ref)) {
106
+ sink.warned.add(use.ref)
107
+ sink.warnings.push(
108
+ key
109
+ ? `local-media: ${use.ref} (in ${named}) names no file — not uploaded`
110
+ : `local-media: ${use.ref} (in ${named}) is outside the site and the folders it mounts, so a push ` +
111
+ `does not upload it — put it in public/ and write it as /${use.ref.split('/').pop()}`
112
+ )
113
+ }
114
+ continue
115
+ }
116
+ sink.files.set(key, use.resolved)
117
+ sink.refs.add(use.ref)
118
+ if (sink.uploaded?.[key]) use.set(key)
119
+ }
120
+ }
121
+
122
+ /**
123
+ * A section's references as a pull writes them: each key the restore put back that names a site
124
+ * file (`keys` — `sync.json`'s keys that are not a `/x` path) made relative to the file the section
125
+ * is written to. Anything else is returned as it is. Never mutates `value`.
126
+ *
127
+ * @param {*} value - a section's content or params
128
+ * @param {{ siteRoot: string, filePath: string, keys: Set<string>, tree?: Array<[string, string]> }} where
129
+ * @returns {*}
130
+ */
131
+ export function writtenRefs(value, { siteRoot, filePath, keys, tree = [] }) {
132
+ if (!keys?.size) return value
133
+ const fromDir = dirname(filePath)
134
+ const ref = (key) => {
135
+ const rel = relative(fromDir, siteFileOf(siteRoot, key, tree)).split(sep).join('/')
136
+ return rel.startsWith('../') ? rel : `./${rel}`
137
+ }
138
+ const map = (v) => {
139
+ if (typeof v === 'string') return keys.has(v) ? ref(v) : v
140
+ if (Array.isArray(v)) return v.map(map)
141
+ if (v && typeof v === 'object') return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, map(x)]))
142
+ return v
143
+ }
144
+ return map(value)
145
+ }
146
+
147
+ /** `sync.json`'s asset keys that name a site file — every key that is not a `/x` path. */
148
+ export function siteFileKeys(assetMap) {
149
+ return new Set(Object.keys(assetMap || {}).filter((k) => !k.startsWith('/')))
150
+ }