@uniweb/build 1.10.14 → 1.11.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.
@@ -33,7 +33,9 @@ import { resolveDefaultLocale, resolveFetchConfigs, DATA_DIR } from '@uniweb/cor
33
33
  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
+ import { collectTranslatedAssets } from './assets.js'
36
37
  import { processAdvancedAssets } from './advanced-processors.js'
38
+ import { devMediaPaths } from './dev-media.js'
37
39
  import { processQueries, writeQueryFiles } from './query-processor.js'
38
40
  import { RECORDS_DIR, resolveRecordsDir } from './entity-pool.js'
39
41
  import { executeFetch, mergeDataIntoContent, toFetchList } from './data-fetcher.js'
@@ -237,6 +239,7 @@ async function processDevSectionFetches(sections, fetchOptions, resolve) {
237
239
  import { compiledData, recordProjections, routeOnDisk } from './record-projections.js'
238
240
  import { agentFiles, describeProjections, projectionFiles, searchFiles } from './projections.js'
239
241
  import { mergeTranslations } from '../i18n/merge.js'
242
+ import { localesToBuild } from '../i18n/locales.js'
240
243
  import { dataBlockModels, NO_DATA_MODELS } from '../i18n/data-models.js'
241
244
  import { refuseSearchOption } from './search-declared.js'
242
245
  import { mountDevApi } from '../dev/api-mount.js'
@@ -264,7 +267,6 @@ import { mountDevSubmit } from '../dev/submit-mount.js'
264
267
  * @param {number} [options.assets.quality=80] - WebP quality (1-100)
265
268
  * @param {string} [options.assets.outputDir='assets'] - Output subdirectory for processed assets
266
269
  * @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
270
  * @param {string} [options.foundationPath] - Path to foundation directory (for loading theme vars)
269
271
  */
270
272
  export function siteContentPlugin(options = {}) {
@@ -287,8 +289,7 @@ export function siteContentPlugin(options = {}) {
287
289
  convertToWebp: assetsConfig.convertToWebp !== false, // Default true
288
290
  quality: assetsConfig.quality || 80,
289
291
  outputDir: assetsConfig.outputDir || 'assets',
290
- videoPosters: assetsConfig.videoPosters !== false, // Default true
291
- pdfThumbnails: assetsConfig.pdfThumbnails !== false // Default true
292
+ videoPosters: assetsConfig.videoPosters !== false // Default true
292
293
  }
293
294
 
294
295
  /**
@@ -308,6 +309,18 @@ export function siteContentPlugin(options = {}) {
308
309
  return content
309
310
  }
310
311
 
312
+ /**
313
+ * Under `uniweb dev`, each local media reference rewritten to where the dev server serves its
314
+ * file (`./dev-media.js`), by the manifest and the rewrite a build uses — so dev shows the file
315
+ * a build ships. A build makes its own copies (`generateBundle`). The rewrite drops the
316
+ * manifest, as a build's does: no payload carries it.
317
+ */
318
+ const devMedia = (content) => {
319
+ if (isProduction || !content?.assets) return content
320
+ const mapping = devMediaPaths(content.assets, { root: viteRoot, publicDir: resolvedPublicDir, base: basePath })
321
+ return rewriteSiteContentPaths(content, mapping)
322
+ }
323
+
311
324
  // Warn once per build, not once per collection — the dev server re-collects
312
325
  // on every content change and would otherwise repeat this on every keystroke.
313
326
  let warnedAboutKnowledge = false
@@ -382,6 +395,7 @@ export function siteContentPlugin(options = {}) {
382
395
  let resolvedSitePath = null
383
396
  let resolvedPublicDir = null
384
397
  let resolvedOutDir = null
398
+ let viteRoot = null // Vite's config.root: the dev server serves a file under it by its path
385
399
  let isProduction = false
386
400
  let watcher = null
387
401
  let server = null
@@ -521,6 +535,34 @@ export function siteContentPlugin(options = {}) {
521
535
  })
522
536
  }
523
537
 
538
+ /**
539
+ * The files the languages this build makes pages in name and the site's own content does not
540
+ * (`collectTranslatedAssets`), each language's translations merged as its pages will be. The
541
+ * languages are `uniweb build`'s (`localesToBuild`), so a file is processed for exactly the pages
542
+ * that show it.
543
+ *
544
+ * @returns {Promise<{ assets: Object, languages: number }>} a manifest of those files, and how
545
+ * many languages the build makes besides its default
546
+ */
547
+ async function translatedAssets() {
548
+ const { readSiteConfig } = await import('./config.js')
549
+ const localesPath = join(resolvedSitePath, localesDir)
550
+ const { locales } = localesToBuild(readSiteConfig(resolvedSitePath), localesPath)
551
+ const languages = []
552
+ for (const locale of locales) {
553
+ const content = await getTranslatedContent(locale)
554
+ if (content) languages.push({ locale, content })
555
+ }
556
+ const { assets, unplaced } = collectTranslatedAssets(languages, siteContent.assets, resolvedSitePath, localesPath)
557
+ for (const { locale, ref } of unplaced) {
558
+ console.warn(
559
+ `[site-content] A ${locale} translation names ${ref}, and a translation sits in no folder for ` +
560
+ `a relative path to start from. Name the file from public/, as /<its path there>.`
561
+ )
562
+ }
563
+ return { assets, languages: locales.length }
564
+ }
565
+
524
566
  /**
525
567
  * The site's content in `locale`, as a page in that language gets it — or null when the site has
526
568
  * no translation for it (`getTranslatedContent`).
@@ -589,6 +631,7 @@ export function siteContentPlugin(options = {}) {
589
631
  resolvedSitePath = resolve(config.root, sitePath)
590
632
  resolvedPublicDir = config.publicDir || resolve(config.root, 'public')
591
633
  resolvedOutDir = resolve(config.root, config.build.outDir)
634
+ viteRoot = config.root
592
635
  isProduction = config.command === 'build'
593
636
  basePath = config.base || '/'
594
637
 
@@ -642,7 +685,7 @@ export function siteContentPlugin(options = {}) {
642
685
  // pages stay in the graph so in-progress drafts remain previewable.
643
686
  // strict on a production build: a mount that contributes no pages is a
644
687
  // 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 })))
688
+ siteContent = devMedia(locate(withDevServices(await collectForBundle(resolvedSitePath, { foundationPath, dropUnpublished: isProduction, base: basePath, strict: isProduction }))))
646
689
  dataModelPromise = null
647
690
  headHtml = await loadHeadHtml()
648
691
  console.log(`[site-content] Collected ${siteContent.pages?.length || 0} pages`)
@@ -789,7 +832,7 @@ export function siteContentPlugin(options = {}) {
789
832
  rebuildQueries = false
790
833
  console.log('[site-content] Content changed, rebuilding...')
791
834
  try {
792
- siteContent = locate(withDevServices(await collectForBundle(resolvedSitePath, { foundationPath, base: basePath })))
835
+ siteContent = devMedia(locate(withDevServices(await collectForBundle(resolvedSitePath, { foundationPath, base: basePath }))))
793
836
  dataModelPromise = null
794
837
  headHtml = await loadHeadHtml()
795
838
  if (materialize) {
@@ -1143,13 +1186,18 @@ export function siteContentPlugin(options = {}) {
1143
1186
 
1144
1187
  // Process assets in production builds
1145
1188
  if (isProduction && assetsOptions.process && siteContent?.assets) {
1146
- const assetCount = Object.keys(siteContent.assets).length
1189
+ // ⭐ With the files a translation names (`translatedAssets`): one step for both, so a
1190
+ // translated page shows the build's copy of its file as the default language's page does.
1191
+ const translated = await translatedAssets()
1192
+ const fromTranslations = Object.keys(translated.assets).length
1193
+ const manifest = { ...siteContent.assets, ...translated.assets }
1194
+ const assetCount = Object.keys(manifest).length
1147
1195
 
1148
1196
  if (assetCount > 0) {
1149
1197
  console.log(`[site-content] Processing ${assetCount} assets...`)
1150
1198
 
1151
1199
  // Process standard assets (images)
1152
- const { pathMapping, results, files } = await processAssets(siteContent.assets, {
1200
+ const { pathMapping, results, files } = await processAssets(manifest, {
1153
1201
  outputDir: resolvedOutDir,
1154
1202
  assetsSubdir: assetsOptions.outputDir,
1155
1203
  convertToWebp: assetsOptions.convertToWebp,
@@ -1157,26 +1205,20 @@ export function siteContentPlugin(options = {}) {
1157
1205
  basePath
1158
1206
  })
1159
1207
 
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(
1208
+ // A poster for each video its author gave none
1209
+ if (assetsOptions.videoPosters) {
1210
+ const { posterMapping, results: advResults } = await processAdvancedAssets(
1166
1211
  siteContent.assets,
1167
1212
  {
1168
1213
  outputDir: resolvedOutDir,
1169
1214
  assetsSubdir: assetsOptions.outputDir,
1170
1215
  videoPosters: assetsOptions.videoPosters,
1171
- pdfThumbnails: assetsOptions.pdfThumbnails,
1172
1216
  quality: assetsOptions.quality,
1173
1217
  basePath,
1174
- // Pass explicit poster/preview sets to skip auto-generation
1175
- hasExplicitPoster: siteContent.hasExplicitPoster || new Set(),
1176
- hasExplicitPreview: siteContent.hasExplicitPreview || new Set()
1218
+ // Pass the explicit poster set to skip auto-generation
1219
+ hasExplicitPoster: siteContent.hasExplicitPoster || new Set()
1177
1220
  }
1178
1221
  )
1179
- advancedResults = advResults
1180
1222
 
1181
1223
  // Log advanced processing results
1182
1224
  if (advResults.videos.processed > 0) {
@@ -1185,33 +1227,24 @@ export function siteContentPlugin(options = {}) {
1185
1227
  if (advResults.videos.explicit > 0) {
1186
1228
  console.log(`[site-content] Skipped ${advResults.videos.explicit} videos with explicit posters`)
1187
1229
  }
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
1230
 
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
-
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
- }
1231
+ // A video's generated poster goes on its node, as an authored one is
1232
+ // (`rewriteContentPaths`). ⛔ Until 2026-10-28 it went to a top-level `_assetMeta`
1233
+ // that nothing read, beside a placeholder card made for each PDF that no page used.
1234
+ finalContent = rewriteSiteContentPaths(siteContent, pathMapping, files, { posters: posterMapping })
1207
1235
  } else {
1208
1236
  // Rewrite paths in content
1209
1237
  finalContent = rewriteSiteContentPaths(siteContent, pathMapping, files)
1210
1238
  }
1211
1239
 
1240
+ // Where the build put each file, for the step that makes each other language's pages from
1241
+ // this payload, and takes it out (`i18n/index.js::buildLocalizedContent`).
1242
+ if (translated.languages > 0) finalContent.builtAssets = { paths: pathMapping, files }
1243
+
1212
1244
  // Log results
1213
1245
  const sizeKB = (results.totalSize / 1024).toFixed(1)
1214
1246
  console.log(`[site-content] Processed ${results.processed} assets (${results.converted} converted to WebP, ${sizeKB}KB total)`)
1247
+ if (fromTranslations > 0) console.log(`[site-content] ${fromTranslations} of them named by a translation`)
1215
1248
 
1216
1249
  if (results.failed > 0) {
1217
1250
  console.warn(`[site-content] ${results.failed} assets failed to process`)
@@ -1225,7 +1258,6 @@ export function siteContentPlugin(options = {}) {
1225
1258
 
1226
1259
  // Clean up internal properties that shouldn't be in the output (Sets don't serialize)
1227
1260
  delete finalContent.hasExplicitPoster
1228
- delete finalContent.hasExplicitPreview
1229
1261
 
1230
1262
  // Note: theme.css is kept here so prerender can inject it into HTML
1231
1263
  // 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
+ }
@@ -30,11 +30,14 @@
30
30
  //
31
31
  // Localized fields (`name`, `description`) are wired as `{ <locale>: value }`;
32
32
  // we unwrap to the source locale for the file surface (other locales stay in
33
- // the i18n pipeline). Absent `info` keys are left untouched on disk.
33
+ // the i18n pipeline). Absent `info` keys are left untouched on disk, except a
34
+ // `preview` that is no author's address (`siteInfoToConfig`).
34
35
 
35
36
  import { foldOpenGraph } from './open-graph.js'
37
+ import { isAuthoredPreview } from './authored-preview.js'
36
38
  import { join, relative, extname, basename, dirname } from 'node:path'
37
39
  import { restoreAssetRefs } from './asset-map.js'
40
+ import { siteFileKeys, siteTree, writtenRefs } from './located-media.js'
38
41
  import { readBackendState, updateBackendState } from './sync-store.js'
39
42
  import { servicesFromDocument, heldServices } from './services-request.js'
40
43
  import { readFileSync, existsSync, unlinkSync, renameSync, rmSync, readdirSync, statSync, mkdirSync } from 'node:fs'
@@ -142,14 +145,11 @@ const INFO_TO_SITE_YML = {
142
145
  // ⭐ `tags` — authored, non-localized tokens; the filter facet for a list of site
143
146
  // cards. Round-trips verbatim like any authored list.
144
147
  tags: 'tags',
145
- // ⭐ `preview` — the card image, verbatim: the app's timestamp, an author's URL, or
146
- // the path an author wrote for an image in the project, which `restoreAssetRefs`
147
- // has already put back by recognizing the serve URL the push recorded in
148
- // `sync.json`'s asset map (asset-map.js). [Diego, 2026-09-10]
149
- //
150
- // ⚠️ It was listed here as "DELIBERATELY ABSENT… BACKEND-STAMPED" until
151
- // 2026-09-10. Leaving an app-written field out of this map is what lets the next
152
- // push destroy it, since `info` is replaced whole.
148
+ // ⭐ `preview` — the card image, verbatim: an author's URL, or the path an author
149
+ // wrote for an image in the project, which `restoreAssetRefs` has already put back by
150
+ // recognizing the serve URL the push recorded in `sync.json`'s asset map
151
+ // (asset-map.js). A document that carries none removes the token an older pull wrote
152
+ // here for a card image the app generated (`siteInfoToConfig`).
153
153
  preview: 'preview',
154
154
  // ⛔ `url` is RETIRED (2026-09-17) and must not come back: where a site went live
155
155
  // is a deploy fact, which `publish` records in `deploy.yml`, not site config. A
@@ -211,7 +211,8 @@ function readAuthoredYaml(filePath) {
211
211
  /**
212
212
  * Project a site-content document's `info` (+ `extensions`) onto the site's
213
213
  * config files: `site.yml`, `theme.yml`, and `head.html`. Idempotent; only the
214
- * keys the document carries are written (absent keys are left as-is on disk).
214
+ * keys the document carries are written (absent keys are left as-is on disk), and
215
+ * a `preview` that is no author's address is removed when the document has none.
215
216
  *
216
217
  * @param {object} params
217
218
  * @param {object} params.document - the `@uniweb/site-content` `$`-document
@@ -247,6 +248,14 @@ export function siteInfoToConfig({ document, siteRoot, backend = null, sourceLoc
247
248
  if (infoKey === 'foundation' && keepAuthoredFoundation) continue
248
249
  if (info[infoKey] !== undefined) siteChanges[ymlKey] = info[infoKey]
249
250
  }
251
+ // ⭐ `preview` is an author's address or nothing. The token an older pull wrote here for a
252
+ // card image the app generated is removed once the document carries no `preview`, as it
253
+ // no longer does for such an image; an author's address stays as the absent-key rule keeps
254
+ // it. ⛔ Until 2026-10-29 the document carried the token, and this wrote it.
255
+ if (info.preview === undefined) {
256
+ const held = readAuthoredYaml(join(siteRoot, 'site.yml'))?.preview
257
+ if (held != null && !isAuthoredPreview(held)) siteChanges.preview = null
258
+ }
250
259
 
251
260
  // ⭐ `settings.fetch` → `site.yml::query` or `site.yml::fetch` — the key the file
252
261
  // already uses, else `query:` when the declaration is nothing but query names
@@ -389,14 +398,18 @@ export function siteInfoToConfig({ document, siteRoot, backend = null, sourceLoc
389
398
  * site (`siteDefaultSectionType`), which a file leaves out
390
399
  * @returns {'updated'|'unchanged'}
391
400
  */
392
- export function sectionRecordToFile({ filePath, record, sourceLocale = LOCALIZED_FIELD_ASSUMPTION.defaultSourceLocale, collector, freeformRelPath, freeformCandidates = null, writeId = true, context = null, dataModel = null, impliedType = DEFAULT_SECTION_TYPE }) {
401
+ export function sectionRecordToFile({ filePath, record, sourceLocale = LOCALIZED_FIELD_ASSUMPTION.defaultSourceLocale, collector, freeformRelPath, freeformCandidates = null, writeId = true, context = null, dataModel = null, impliedType = DEFAULT_SECTION_TYPE, media = null }) {
393
402
  // ⛔ A stored `preset` or `input` is not written back: neither has an effect, and the build
394
403
  // would only warn about it (2026-09-27).
395
404
  // ⛔ No `background` / `theme_override` / `insets` / `fetch`: the site-content Model dropped all
396
405
  // four from a section (2026-09-28), with a stored background, theme and data declaration copied
397
406
  // into `params`. Until then a field filled in where `params` lacked the key, and a stored
398
407
  // `insets[]` was re-inlined into the body. (A PAGE's `fetch` is its own field — `pageRecordToYml`.)
399
- const { type, stable_id, hidden, params, content } = record || {}
408
+ const { type, stable_id, hidden } = record || {}
409
+ // ⭐ A co-located file a push uploaded comes back as its key from the site root (`restoreAssetRefs`),
410
+ // and is written as the author wrote it: relative to this file (`located-media.js`, `media`).
411
+ const params = media ? writtenRefs(record?.params, { ...media, filePath }) : record?.params
412
+ const content = media ? writtenRefs(record?.content, { ...media, filePath }) : record?.content
400
413
 
401
414
  // A localized `content` field unwraps to the source-locale doc for the body; its
402
415
  // target-locale structural maps are captured into the locales/ collector, and any
@@ -554,6 +567,7 @@ export function pageSectionsToFiles({ pageDir, pageSections, ctx, pageContext })
554
567
  freeformCandidates,
555
568
  writeId: fileSectionName(filePath) !== stableId,
556
569
  context: pageContext ? translationContext({ stableId }, pageContext.route) : null,
570
+ media: ctx?.media ?? null,
557
571
  })
558
572
  written.push(filePath)
559
573
  if (!top) childFiles.push(basename(filePath))
@@ -1255,6 +1269,7 @@ function projectLayout(layoutSections, layoutBaseDir, report, prune, ctx) {
1255
1269
  freeformRelPath: stableId ? buildFreeformPath({ stableId }, page) : null,
1256
1270
  freeformCandidates: stableId ? freeformPathsFor({ stableId }, page) : null,
1257
1271
  context: translationContext({ stableId }, page.route),
1272
+ media: ctx?.media ?? null,
1258
1273
  })
1259
1274
  report.layout.push(filePath)
1260
1275
  written.push(filePath)
@@ -1363,10 +1378,11 @@ export function siteContentDocumentToProject({ document, siteRoot, backend = nul
1363
1378
  // not tied to one has no known assets and restores nothing. Every caller that
1364
1379
  // pulls has an origin; the ones that do not are projecting a document in the
1365
1380
  // abstract.
1366
- report.assets = restoreAssetRefs(
1367
- document,
1368
- backend ? readBackendState(siteRoot, backend).assets || {} : {}
1369
- )
1381
+ const assetMap = backend ? readBackendState(siteRoot, backend).assets || {} : {}
1382
+ report.assets = restoreAssetRefs(document, assetMap)
1383
+ // The keys among them that name a site file — a co-located file a push uploaded — for each
1384
+ // section's writer to make relative to its own file (`located-media.js`).
1385
+ const mediaKeys = siteFileKeys(assetMap)
1370
1386
 
1371
1387
  report.config = siteInfoToConfig({ document, siteRoot, backend, sourceLocale, collector, keepAuthoredFoundation })
1372
1388
  report.queries = declarationsToQueriesYml({ document, siteRoot, scope })
@@ -1375,7 +1391,7 @@ export function siteContentDocumentToProject({ document, siteRoot, backend = nul
1375
1391
  // rename detection, build a fresh one as we project, then persist it. Items not
1376
1392
  // re-projected (deleted) drop out naturally. `collector` rides along to capture
1377
1393
  // localized scalars during the page walk.
1378
- const ctx = { siteRoot, oldIndex: readPullIndex(siteRoot), newIndex: {}, report, collector, sourceLocale, sectionFiles: new Map(), dataModel, sectionType }
1394
+ const ctx = { siteRoot, oldIndex: readPullIndex(siteRoot), newIndex: {}, report, collector, sourceLocale, sectionFiles: new Map(), dataModel, sectionType, media: mediaKeys.size ? { siteRoot, keys: mediaKeys } : null }
1379
1395
  // Where the site keeps its localized URLs — `site.yml`'s map, when it has one (`pageSlugToYml`).
1380
1396
  const siteMap = readAuthoredYaml(join(siteRoot, 'site.yml'))?.i18n?.routeTranslations
1381
1397
  ctx.routes = { siteMap: isPlainRecord(siteMap) && Object.keys(siteMap).length ? siteMap : null, slugs: new Map() }
@@ -1385,6 +1401,9 @@ export function siteContentDocumentToProject({ document, siteRoot, backend = nul
1385
1401
  // next push and the build read. See `siteContentDirs`.
1386
1402
  const siteYml = readAuthoredYaml(join(siteRoot, 'site.yml'))
1387
1403
  const { pagesDir, layoutDir: layoutBaseDir } = siteContentDirs(siteRoot, siteYml)
1404
+ // The tree a key names its file by: pages and layout wherever `paths:` puts them. (A mount's pages
1405
+ // are never written, so the mounts need not join it.)
1406
+ if (ctx.media) ctx.media.tree = siteTree(siteRoot, { pagesDir, layoutDir: layoutBaseDir })
1388
1407
  // ⭐ The pages authored in files a pull cannot write back — a mount's, a folder-mode folder's
1389
1408
  // `.md` pages — are neither written nor pruned (`git-authored.js`).
1390
1409
  ctx.leave = gitAuthoredPages(siteYml, pagesDir)