@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.
@@ -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)
package/src/uwx/site.js CHANGED
@@ -79,12 +79,14 @@ import { normalizeHideIn } from '../site/nav-visibility.js'
79
79
  import { siteDefaultSectionType } from '../site/queries-config.js'
80
80
  import { resolveDefaultLocale, validateLanguageConfig, queryDataUrl } from '@uniweb/core'
81
81
  import { emitEntitySyncPackage } from './entity-document.js'
82
+ import { locateSectionMedia, siteTree } from './located-media.js'
82
83
  import { loadLocaleTranslations, localizeScalar, localizeScalarList, localizeContentDoc, localesDir, isLocalizedContent, plainTextTargets } from './locale-sync.js'
83
84
  import { unwrapLocalized } from './backfill.js'
84
85
  import { loadFreeformTranslation } from '../i18n/freeform.js'
85
86
  import { resolveLocaleList } from '../i18n/locales.js'
86
87
  import { translationContext, SITE_META_CONTEXT } from '../i18n/extract.js'
87
88
  import { splitOpenGraph, openGraphValue, seoBesideOpenGraph } from './open-graph.js'
89
+ import { isAuthoredPreview } from './authored-preview.js'
88
90
  import { updateBackendState, readBackendState } from './sync-store.js'
89
91
  import {
90
92
  readServicesRequest,
@@ -104,17 +106,6 @@ function setIf(obj, key, value) {
104
106
  if (value !== undefined) obj[key] = value
105
107
  }
106
108
 
107
- // A YAML scalar the author may have written unquoted: `20260910` loads as a number.
108
- // Carry it as the string it stands for; anything else that is not a string is not a
109
- // value a string field can hold. (`2026-09-10` loads as the string it is written as —
110
- // the build's YAML resolves no timestamps, `utils/yaml-schema.js` — so no Date arrives:
111
- // it was carried re-rendered by `toISOString()` until 2026-09-14.)
112
- function scalarString(value) {
113
- if (typeof value === 'string') return value
114
- if (typeof value === 'number') return String(value)
115
- return undefined
116
- }
117
-
118
109
  // page_sections and layout_sections share this content shape.
119
110
  // processMarkdownFile takes only type/hidden/props/fetch/query/data/id out of the
120
111
  // frontmatter (and drops preset/input), so `background:` and `theme:` stay
@@ -555,6 +546,14 @@ function sectionToRecord(section, index) {
555
546
  return rec
556
547
  }
557
548
 
549
+ // A section's file, read the build's way — and on a push, its co-located media located
550
+ // (`./located-media.js`) before a record is made of it, since the setters write into the section.
551
+ async function readSectionFile(filePath, id, siteRoot, stableId, media) {
552
+ const read = await processMarkdownFile(filePath, id, siteRoot, stableId)
553
+ locateSectionMedia(read.assetCollection, { siteRoot, filePath, sink: media })
554
+ return read
555
+ }
556
+
558
557
  // Resolve a section's logical name (`hero`, `card-a`) to its file in `mdFiles`, in the
559
558
  // normal build's order (`content-collector.js::findSectionFile`): `name.md`, then
560
559
  // `@name.md`, then the first file whose name is `name` once its `@` and `N-` prefixes
@@ -612,7 +611,7 @@ function isExplicitWithRest(sectionsConfig) {
612
611
  // a section name (string) or `{ name: [children…] }`, resolved to its file by
613
612
  // name (bare / `@` / numeric-prefix tolerant) and recursed. Order and nesting
614
613
  // come from the array, not the directory.
615
- async function collectPageSectionsExplicit(pageDir, siteRoot, sectionsConfig, { appendRest = false, nest = null } = {}) {
614
+ async function collectPageSectionsExplicit(pageDir, siteRoot, sectionsConfig, { appendRest = false, nest = null, media = null } = {}) {
616
615
  const mdFiles = (await readdir(pageDir)).filter(isMarkdownFile).sort(compareFilenames)
617
616
  const seen = new Set()
618
617
 
@@ -622,7 +621,7 @@ async function collectPageSectionsExplicit(pageDir, siteRoot, sectionsConfig, {
622
621
  const file = findSectionFileName(mdFiles, name)
623
622
  if (!file || seen.has(file)) return null // missing / already used → skip
624
623
  seen.add(file)
625
- const { section } = await processMarkdownFile(join(pageDir, file), String(seen.size), siteRoot, name)
624
+ const { section } = await readSectionFile(join(pageDir, file), String(seen.size), siteRoot, name, media)
626
625
  section.subsections = []
627
626
  if (Array.isArray(children)) {
628
627
  for (const child of children) {
@@ -649,7 +648,7 @@ async function collectPageSectionsExplicit(pageDir, siteRoot, sectionsConfig, {
649
648
  if (isChildSection(file) || seen.has(file)) continue
650
649
  seen.add(file)
651
650
  const stableDefault = parseNumericPrefix(stripAtPrefix(parse(file).name)).name
652
- const { section } = await processMarkdownFile(join(pageDir, file), String(seen.size), siteRoot, stableDefault)
651
+ const { section } = await readSectionFile(join(pageDir, file), String(seen.size), siteRoot, stableDefault, media)
653
652
  section.subsections = []
654
653
  sections.push(section)
655
654
  }
@@ -670,7 +669,7 @@ async function collectPageSectionsExplicit(pageDir, siteRoot, sectionsConfig, {
670
669
  for (const childName of childNames) {
671
670
  const file = findSectionFileName(mdFiles, childName)
672
671
  if (!file) continue
673
- const { section } = await processMarkdownFile(join(pageDir, file), String(parent.subsections.length + 1), siteRoot, childName)
672
+ const { section } = await readSectionFile(join(pageDir, file), String(parent.subsections.length + 1), siteRoot, childName, media)
674
673
  section.subsections = []
675
674
  parent.subsections.push(section)
676
675
  }
@@ -679,12 +678,12 @@ async function collectPageSectionsExplicit(pageDir, siteRoot, sectionsConfig, {
679
678
  return sections.map((s, i) => sectionToRecord(s, i))
680
679
  }
681
680
 
682
- async function collectPageSectionsNested(pageDir, siteRoot, pageConfig) {
681
+ async function collectPageSectionsNested(pageDir, siteRoot, pageConfig, media = null) {
683
682
  if (isFullyExplicitSections(pageConfig?.sections)) {
684
- return collectPageSectionsExplicit(pageDir, siteRoot, pageConfig.sections, { nest: pageConfig.nest })
683
+ return collectPageSectionsExplicit(pageDir, siteRoot, pageConfig.sections, { nest: pageConfig.nest, media })
685
684
  }
686
685
  if (isExplicitWithRest(pageConfig?.sections)) {
687
- return collectPageSectionsExplicit(pageDir, siteRoot, pageConfig.sections, { appendRest: true, nest: pageConfig.nest })
686
+ return collectPageSectionsExplicit(pageDir, siteRoot, pageConfig.sections, { appendRest: true, nest: pageConfig.nest, media })
688
687
  }
689
688
  const mdFiles = (await readdir(pageDir)).filter(isMarkdownFile).sort(compareFilenames)
690
689
  const nest = pageConfig?.nest && typeof pageConfig.nest === 'object' ? pageConfig.nest : {}
@@ -694,11 +693,12 @@ async function collectPageSectionsNested(pageDir, siteRoot, pageConfig) {
694
693
  // `.subsections`. `seen` guards against a cycle in a hand-written `nest:`.
695
694
  const buildSection = async (file, seen) => {
696
695
  const stableDefault = parseNumericPrefix(stripAtPrefix(parse(file).name)).name
697
- const { section } = await processMarkdownFile(
696
+ const { section } = await readSectionFile(
698
697
  join(pageDir, file),
699
698
  String(seen.size),
700
699
  siteRoot,
701
- stableDefault
700
+ stableDefault,
701
+ media
702
702
  )
703
703
  const childNames = Array.isArray(nest[section.stableId]) ? nest[section.stableId] : []
704
704
  section.subsections = []
@@ -731,7 +731,7 @@ async function collectPageSectionsNested(pageDir, siteRoot, pageConfig) {
731
731
  if (!isChildSection(file) || seen.has(file)) continue
732
732
  seen.add(file)
733
733
  const stableDefault = parseNumericPrefix(stripAtPrefix(parse(file).name)).name
734
- const { section } = await processMarkdownFile(join(pageDir, file), String(seen.size), siteRoot, stableDefault)
734
+ const { section } = await readSectionFile(join(pageDir, file), String(seen.size), siteRoot, stableDefault, media)
735
735
  section.subsections = []
736
736
  sections.push(section)
737
737
  }
@@ -750,7 +750,8 @@ async function folderModePageRecords(ctx, dirPath, orderConfig, isRoot) {
750
750
  const records = []
751
751
  for (const { file, name } of files) {
752
752
  const filePath = join(dirPath, file)
753
- const { page } = await processFileAsPage(filePath, file, siteRoot, '/')
753
+ const { page, assetCollection } = await processFileAsPage(filePath, file, siteRoot, '/')
754
+ locateSectionMedia(assetCollection, { siteRoot, filePath, sink: ctx.media })
754
755
  const config = { title: page.title }
755
756
  if (page.hidden) config.hidden = true
756
757
  const data = buildPageData(config, {
@@ -827,7 +828,7 @@ async function walkPagesNested(ctx, dirPath, parentSlugPath, inheritedMode, pare
827
828
 
828
829
  // A folder-mode folder has no sections: its `.md` files are pages, sent among its children.
829
830
  if (mode === 'page') {
830
- const sections = await collectPageSectionsNested(f.path, siteRoot, f.config)
831
+ const sections = await collectPageSectionsNested(f.path, siteRoot, f.config, ctx.media)
831
832
  if (sections.length > 0) record.page_sections = sections
832
833
  }
833
834
 
@@ -847,7 +848,7 @@ async function walkPagesNested(ctx, dirPath, parentSlugPath, inheritedMode, pare
847
848
  // until 2026-09-13: this walk called every folder a named layout and read only the
848
849
  // files directly inside it, while the build called a folder an area of the default
849
850
  // layout unless the foundation declared a layout by that name.
850
- async function collectLayoutNested(layoutDir, siteRoot) {
851
+ async function collectLayoutNested(layoutDir, siteRoot, media = null) {
851
852
  const areas = await readLayoutFolder(layoutDir, { siteRoot })
852
853
  const items = []
853
854
  let order = 0
@@ -857,7 +858,7 @@ async function collectLayoutNested(layoutDir, siteRoot) {
857
858
  // section of a multi-section area is named the way a page's section is.
858
859
  const { name } = parse(file)
859
860
  const fallback = area.form === 'file' ? area.area : (parseNumericPrefix(name).name || name)
860
- const { section } = await processMarkdownFile(join(area.dir, file), String(order + 1), siteRoot, fallback)
861
+ const { section } = await readSectionFile(join(area.dir, file), String(order + 1), siteRoot, fallback, media)
861
862
  const stable = section.stableId || String(order)
862
863
  items.push(withIdentity(stable, { layout_name: area.layout, area: area.area, ...mapSectionData(section) }))
863
864
  order++
@@ -1432,6 +1433,9 @@ function touchIconValue(named, settingsFields) {
1432
1433
  * known, `@/x` ships as written.
1433
1434
  * @param {string[]} [opts.schemaless] - the queries whose records resolved no data schema
1434
1435
  * (the records lane's `schemaless`): their declarations name no `schema`.
1436
+ * @param {object} [opts.media] - a push's sink for the sections' co-located media
1437
+ * (`located-media.js::locatedMediaSink`): each file to upload, and — where its upload
1438
+ * map names the file — the reference replaced by the file's key. Absent, nothing is located.
1435
1439
  * @returns {Promise<object>} the section-keyed `$`-document:
1436
1440
  * `{ $uuid?, $id, $schema, info, settings?, pages, layout_sections, extensions,
1437
1441
  * queries, services?, secrets? }`
@@ -1590,20 +1594,17 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
1590
1594
  // over an already-fetched list and never asks the database, while a DB-filterable
1591
1595
  // facet is separately useful — only the second needs a predicable brief field.
1592
1596
  setIf(info, 'tags', siteYml.tags)
1593
- // ⭐ `preview` — the site card's image. ONE field, TWO writers, and it round-trips
1594
- // whichever wrote it [Diego, 2026-09-10]:
1595
- // · the APP, when it generates a card image — a timestamp, carried verbatim;
1596
- // · an AUTHOR, deliberately — typically a template site's custom image: a URL, or
1597
- // a site-root path to an image in the project, which push uploads like any
1598
- // content image and sends as its serve URL, and which pull puts back as the
1599
- // path the author wrote (`restoreAssetRefs` recognizes the URL by the
1600
- // fingerprint recorded for it in `sync.json`'s asset map).
1601
- // The app leaves an author's value alone.
1597
+ // ⭐ `preview` — the site card's image, as an AUTHOR set it, typically a template site's
1598
+ // own picture: a URL, or a site-root path to an image in the project, which push uploads
1599
+ // like any content image and sends as its serve URL, and which pull puts back as the path
1600
+ // the author wrote (`restoreAssetRefs` recognizes the URL by the fingerprint recorded for it
1601
+ // in `sync.json`'s asset map).
1602
1602
  //
1603
- // ⚠️ Until 2026-09-10 framework emitted no preview, on the premise that the host
1604
- // stamps it. Nothing did, and leaving an app-written field off an allowlist
1605
- // destroys it on every push, because `info` is replaced whole.
1606
- setIf(info, 'preview', scalarString(siteYml.preview))
1603
+ // ⛔ Nothing else is sent (`isAuthoredPreview`). A card image the app generates is kept
1604
+ // apart from the site's content, so the token an older pull wrote here for one is no
1605
+ // author's value, and a pull removes it (`site-project.js`). Until 2026-10-29 the token
1606
+ // was carried verbatim: it was the only way to keep it, since `info` is replaced whole.
1607
+ setIf(info, 'preview', isAuthoredPreview(siteYml.preview) ? siteYml.preview : undefined)
1607
1608
  // ⛔ `url` IS RETIRED (2026-09-17) — do not reintroduce it, in either direction.
1608
1609
  // It carried where the site went live, read from `site.yml::$url` (which pull
1609
1610
  // wrote), so a site card could link to it. That is a fact about a DEPLOY, not
@@ -1615,9 +1616,11 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
1615
1616
 
1616
1617
  // `siteIndex` — the homepage — joins below, once the pages directory's own config is read.
1617
1618
  // …and the keys this deployment's page takes (`siteContent.pageFields`), for its Open Graph texts.
1618
- const ctx = { siteRoot, sourceLocale, translations, pageFields: opts.pageFields }
1619
+ const ctx = { siteRoot, sourceLocale, translations, pageFields: opts.pageFields, media: opts.media || null }
1619
1620
  // The same two directories the pull writes back to — see `siteContentDirs`.
1620
1621
  const { pagesDir: pagesPath, layoutDir } = siteContentDirs(siteRoot, siteYml)
1622
+ // The tree a push keys the site's media by (`located-media.js::siteTree`) — its mounts join it below.
1623
+ if (ctx.media) ctx.media.tree = siteTree(siteRoot, { pagesDir: pagesPath, layoutDir })
1621
1624
  let pages = []
1622
1625
  if (existsSync(pagesPath)) {
1623
1626
  // ⭐ SUB-MOUNTS, AS THE BUILD READS THEM — `paths: { pages/<segment>: <dir> }`, through its own
@@ -1625,6 +1628,7 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
1625
1628
  // submodule never fetched) stops the push. A push replaces the site's whole page tree, so a
1626
1629
  // mount read as empty would remove every page it holds from a published site.
1627
1630
  const mounts = resolveMounts(siteYml.paths, siteRoot, pagesPath, { strict: true })
1631
+ if (ctx.media) ctx.media.tree = siteTree(siteRoot, { pagesDir: pagesPath, layoutDir, mounts })
1628
1632
  // The root has a mode too, read as the build reads it (`rootContentMode`): `pages/folder.yml`
1629
1633
  // puts the whole site in folder mode, its `.md` files pages and every folder with no config of
1630
1634
  // its own in folder mode too.
@@ -1638,7 +1642,7 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
1638
1642
  localizeRouteSlugs(pages, siteYml, sourceLocale)
1639
1643
  }
1640
1644
 
1641
- const layoutSections = await collectLayoutNested(layoutDir, siteRoot)
1645
+ const layoutSections = await collectLayoutNested(layoutDir, siteRoot, opts.media || null)
1642
1646
  // Before anything reads a section's type — localizing a data block asks it for the block's model.
1643
1647
  const sectionType = await siteDefaultSectionType(siteRoot, siteYml)
1644
1648
  fillPageSectionTypes(pages, sectionType)
@@ -23,6 +23,7 @@ import { buildRecordEntities, entityContentHash } from './records.js'
23
23
  import { recordItemLists, hasListItems, stampRecordItems } from './record-items.js'
24
24
  import { ASSET_SLOTS } from '@uniweb/semantic-parser'
25
25
  import { fileRecordUploads } from './file-records.js'
26
+ import { locatedMediaSink } from './located-media.js'
26
27
  import { buildFolderEntity } from './folder.js'
27
28
  import { siteProjectToDocument } from './site.js'
28
29
  import { siteSourceLocale } from './source-locale.js'
@@ -290,7 +291,9 @@ function rewriteEntityAssets(node, map, ids, bare = null) {
290
291
  * `schemaless` lists queries that resolved no data schema (soft-skipped from
291
292
  * the sync) — the composite deploy delivers these statically via the data ball.
292
293
  * `localAssets` lists the site-root local media refs (`/images/x.png`) the deploy
293
- * must upload + rewrite to serve URLs; co-located refs are warned and skipped.
294
+ * must upload + rewrite to serve URLs. A section's co-located files ride `localFiles`,
295
+ * under their keys from the site root (`located-media.js`); any other co-located ref is
296
+ * warned and skipped.
294
297
  * `applied` echoes the hash-affecting injections this emit actually used
295
298
  * (`assetRewrite` / `assetIds` / `injectInfo` / `injectExtensions`), ready to be
296
299
  * passed straight back as opts. A caller that banks the `hashes` must bank this
@@ -373,10 +376,18 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
373
376
  // an expected path.
374
377
  if (folder?.warnings?.length) warnings.push(...folder.warnings)
375
378
 
379
+ // ⭐ A section's co-located media (`./team.jpg`), located where its file is read: each file rides
380
+ // `localFiles` under its key from the site root, and the emit handed the upload that names it writes
381
+ // the key where the reference was, for the rewrite below to swap (`located-media.js`).
382
+ const media = includeSite
383
+ ? locatedMediaSink(opts.assetRewrite && typeof opts.assetRewrite === 'object' ? opts.assetRewrite : null)
384
+ : null
385
+
376
386
  // `queryUuids` — identity for the `queries` section, keyed by query
377
387
  // NAME because a declaration has no file of its own (see queriesNested).
378
388
  const siteDoc = includeSite
379
389
  ? await siteProjectToDocument(siteRoot, {
390
+ media,
380
391
  sourceLocale,
381
392
  // Whose $uuid belongs on this wire document — see siteProjectToDocument.
382
393
  ...(opts.backend ? { backend: opts.backend } : {}),
@@ -480,14 +491,18 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
480
491
  if (folder) rewriteEntityAssets(folder.document, assetRewrite, assetIds)
481
492
  }
482
493
  // Collect the site-root local refs the deploy must upload (`/images/x.png`).
483
- // Co-located refs (`./x`, `../x`) need the source `.md` location to resolve — the
484
- // entity doesn't carry it — so warn once each and skip (v1: use a site-root path).
494
+ // A section's co-located refs (`./x`, `../x`) were taken where their files were read
495
+ // (`media`, above): uploaded under their keys, or warned about there. Any other — a
496
+ // record's, `site.yml`'s — needs a location the entity does not carry, so it is warned
497
+ // once and skipped. ⛔ Until 2026-10-28 a section's were skipped too.
498
+ if (media) warnings.push(...media.warnings)
485
499
  const localAssetSet = new Set()
486
500
  const colocatedSeen = new Set()
487
- const collectFrom = (doc) =>
501
+ const collectFrom = (doc, taken = null) =>
488
502
  doc &&
489
503
  walkEntityAssets(doc, (ref) => {
490
504
  if (ref.startsWith('/')) localAssetSet.add(ref)
505
+ else if (taken && (taken.refs.has(ref) || taken.warned.has(ref))) return
491
506
  else if (!colocatedSeen.has(ref)) {
492
507
  colocatedSeen.add(ref)
493
508
  warnings.push(
@@ -496,7 +511,7 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
496
511
  )
497
512
  }
498
513
  })
499
- collectFrom(siteDoc)
514
+ collectFrom(siteDoc, media)
500
515
  for (const e of col.entities) collectFrom(e.document)
501
516
  // ⭐ The site's favicon, whatever its type. `.ico` is not media to the walker
502
517
  // (`isLocalAssetPath`), but a host serves the favicon its page shell links only from
@@ -656,8 +671,9 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
656
671
  refusals,
657
672
  schemaless: col.schemaless, localAssets, applied,
658
673
  // The files a push uploads for its file records, each `{ ref, path, contentType }` — the file, and
659
- // a PDF's preview. Uploaded through the media lane; `ref` is the key the second emit rewrites.
660
- localFiles,
674
+ // a PDF's preview — and for its sections' co-located media, each `{ ref, path }`. Uploaded through
675
+ // the media lane; `ref` is the key the second emit rewrites.
676
+ localFiles: [...localFiles, ...[...(media?.files || [])].map(([ref, path]) => ({ ref, path }))],
661
677
  // { stamped, unknown } when identity was applied; null when the caller passed
662
678
  // no map. `unknown > 0` with `stamped === 0` on a site that has been pushed
663
679
  // before is the index-loss signature the backend refuses — the caller reports it.
@@ -172,7 +172,16 @@ export async function validateDataInputs({ siteRoot, foundationPath }) {
172
172
  // keys on a page with no data at all is ordinary and silent. What is not ordinary is
173
173
  // a page that fetched something and a section on it that receives none of it —
174
174
  // there the author demonstrably intended data to arrive and the names did not meet.
175
- const declaredNames = declared.map(([key]) => key)
175
+ //
176
+ // ⛔ A CONCEPT BLOCK'S KEY IS NOT ONE A FETCH FILLS. `'md:prompt'` in `data:` reads a
177
+ // ```md:prompt fence written in the section, and nothing else delivers it, so a section with
178
+ // no such fence is ordinary — the describer lists it as `{ key, kind: 'concept' }`
179
+ // (`@uniweb/schemas/content`). ⛔ Until 2026-10-28 it was counted here, and a page whose
180
+ // query fed another section reported it as data that failed to arrive.
181
+ const concepts = new Set(
182
+ (foundation[type]?.content || []).filter((e) => e?.kind === 'concept').map((e) => e.key)
183
+ )
184
+ const declaredNames = declared.map(([key]) => key).filter((key) => !concepts.has(key))
176
185
  if (declaredNames.length > 0 && inputs.length > 0 && fills.size === 0 && !declaredNames.some((k) => held.includes(k))) {
177
186
  const delivered = inputs.map((i) => i.as).filter(Boolean)
178
187
  setupErrors.push({