@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.
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({