@uniweb/build 0.31.0 → 0.33.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.31.0",
+  "version": "0.33.0",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -60,14 +60,14 @@
     "sharp": "^0.35.3",
     "yaml": "^2.5.0",
     "@uniweb/schemas": "^0.2.13",
+    "@uniweb/projections": "^0.5.4",
     "@uniweb/theming": "^0.1.15",
-    "@uniweb/semantic-parser": "^1.4.0",
     "@uniweb/content-reader": "^1.2.4",
-    "@uniweb/projections": "^0.5.3",
+    "@uniweb/semantic-parser": "^1.4.0",
     "@uniweb/content-writer": "^0.3.4"
   },
   "optionalDependencies": {
-    "@uniweb/runtime": "^0.13.4"
+    "@uniweb/runtime": "^0.13.5"
   },
   "peerDependencies": {
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0",
@@ -76,7 +76,7 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
     "vite-plugin-svgr": "^4.0.0",
-    "@uniweb/core": "^0.15.0"
+    "@uniweb/core": "^0.16.0"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/i18n/freeform.js

@@ -23,6 +23,7 @@ import { existsSync } from 'node:fs'
 import { join, relative, dirname } from 'node:path'
 import yaml from 'js-yaml'
 import { poolDirsForSchema, ENTITIES_DIR } from '../site/entity-pool.js'
+import { parseFrontmatter } from '../utils/frontmatter.js'
 
 // Try to import content-reader for markdown → ProseMirror conversion
 let markdownToProseMirror
@@ -42,29 +43,6 @@ try {
   })
 }
 
-/**
- * Parse YAML frontmatter from markdown content
- * @param {string} content - Raw markdown content
- * @returns {{ frontmatter: Object, body: string }}
- */
-function parseFrontmatter(content) {
-  if (!content.trim().startsWith('---')) {
-    return { frontmatter: {}, body: content }
-  }
-
-  const parts = content.split('---\n')
-  if (parts.length < 3) {
-    return { frontmatter: {}, body: content }
-  }
-
-  try {
-    const frontmatter = yaml.load(parts[1]) || {}
-    const body = parts.slice(2).join('---\n')
-    return { frontmatter, body }
-  } catch {
-    return { frontmatter: {}, body: content }
-  }
-}
 
 /**
  * Normalize route for filesystem path
@@ -120,7 +98,7 @@ export async function loadFreeformTranslation(section, page, locale, localesDir)
 
     try {
       const content = await readFile(filePath, 'utf-8')
-      const { frontmatter, body } = parseFrontmatter(content)
+      const { frontmatter, body } = parseFrontmatter(content, filePath)
 
       // Convert markdown body to ProseMirror
       const proseMirrorContent = markdownToProseMirror(body)
@@ -174,7 +152,7 @@ export async function loadFreeformRecord(item, schema, locale, localesDir) {
 
   try {
     const content = await readFile(filePath, 'utf-8')
-    const { frontmatter, body } = parseFrontmatter(content)
+    const { frontmatter, body } = parseFrontmatter(content, filePath)
 
     // Convert markdown body to ProseMirror (if body exists)
     const proseMirrorContent = body.trim() ? markdownToProseMirror(body) : null

package/src/site/config.js

@@ -320,7 +320,31 @@ export async function defineSiteConfig(options = {}) {
     // Point #foundation at a virtual noop module.
     alias['#foundation'] = '\0__foundation-noop__'
   } else if (foundationInfo.type !== 'url') {
-    // Bundled mode: #foundation points to the actual package
+    // Bundled mode: #foundation points to the actual package.
+    //
+    // ⛔ **A BARE SPECIFIER, NOT `foundationInfo.path` — and the obvious
+    // "improvement" is measured and wrong.** We hold the resolved path right
+    // here, and handing vite the *name* instead is what lets its node_modules
+    // lookup disagree with ours (the whole reason
+    // `uniweb:ensure-foundation-entry` now runs `checkFoundationResolution`).
+    // Collapsing the two by aliasing to the path looks like it deletes that bug
+    // class. It does not:
+    //
+    //   A vite alias is PREFIX replacement, so `#foundation/styles` — which the
+    //   site's own `entry.js` imports — becomes `<path>/styles`, a filesystem
+    //   path. That bypasses the foundation's `exports` map, and the map is where
+    //   `./styles` → `./styles.css` lives (along with `./dist` and
+    //   `./dist/styles`). Measured 2026-09-01 on a stock marketing scaffold:
+    //   `[vite:load-fallback] Could not load <path>/src/styles (imported by
+    //   entry.js): ENOENT`. A HEALTHY project fails to build.
+    //
+    // Splitting it — exact `#foundation` → path, `#foundation/*` → name — is
+    // worse still: on a diverged tree the entry would come from one directory
+    // and the stylesheet from another, which is a state neither consistent
+    // option can reach.
+    //
+    // ⇒ **The name is load-bearing because the exports map is.** Detecting the
+    // disagreement is the correct shape; eliminating it costs the exports map.
     alias['#foundation'] = foundationInfo.name
   }
 

package/src/site/content-collector.js

@@ -36,6 +36,7 @@ import { parseFetchConfig } from './data-fetcher.js'
 import { resolveExtensionUrls } from './extension-urls.js'
 import { buildTheme, extractFoundationVars } from '../theme/index.js'
 import { resolveDefaultLocale, resolvePublishableLocales, validateLanguageConfig } from '@uniweb/core'
+import { parseFrontmatter } from '../utils/frontmatter.js'
 
 // Try to import content-reader, fall back to simplified parser
 let markdownToProseMirror
@@ -159,13 +160,44 @@ function buildVersionMetadata(detectedVersions, pageConfig = {}) {
 }
 
 /**
- * Parse YAML string using js-yaml
+ * Malformed YAML met during the current collect.
+ *
+ * ⛔ **A PARSE FAILURE USED TO BE A `console.warn` AND AN EMPTY OBJECT**, and
+ * this function reads `site.yml`, `page.yml`, `folder.yml`, `theme.yml` and
+ * every section's frontmatter — i.e. every configuration surface an author
+ * writes. So a single typo silently discarded that file's entire contribution:
+ * page order, nesting, `sections:`, `data:` declarations, theme. **The build
+ * succeeded and shipped a site missing what the author asked for**, with one
+ * line on stderr that named no file.
+ *
+ * ⭐ **Collected rather than thrown at the point of failure, on purpose.**
+ * Throwing from `parseYaml` would end the collect at the FIRST bad file, so an
+ * author with three typos fixes one, rebuilds, and learns about the next.
+ * Accumulating lets `collectSiteContent` report every one at once and then
+ * decide, which is also where the `strict` flag already lives.
+ *
+ * ⚠️ **Module-scoped, so it assumes one collect at a time in a process.** True
+ * of the production path (`build-site-data.js` runs one) and harmless in dev,
+ * where the outcome is a warning either way and an interleaved rebuild can only
+ * mis-attribute a message. Do not read this as a general-purpose registry.
+ */
+let yamlFailures = []
+
+/**
+ * Parse YAML, recording a failure against the file it came from.
+ *
+ * @param {string} yamlString
+ * @param {string} source - path or label of the file this text came from. It is
+ *   the whole point of the record: the old message named nothing, so an author
+ *   with a typo learned only that *some* YAML somewhere was bad.
+ * @returns {Object} the parsed value, or `{}` when it could not be parsed
  */
-function parseYaml(yamlString) {
+function parseYaml(yamlString, source = '<unknown>') {
   try {
     return yaml.load(yamlString) || {}
   } catch (err) {
-    console.warn('[content-collector] YAML parse error:', err.message)
+    yamlFailures.push({ source, message: err.message })
+    console.warn(`[content-collector] YAML parse error in ${source}: ${err.message}`)
     return {}
   }
 }
@@ -176,7 +208,7 @@ function parseYaml(yamlString) {
 async function readYamlFile(filePath) {
   try {
     const content = await readFile(filePath, 'utf8')
-    return parseYaml(content)
+    return parseYaml(content, filePath)
   } catch (err) {
     if (err.code === 'ENOENT') return {}
     throw err
@@ -802,13 +834,22 @@ async function processMarkdownFile(filePath, id, siteRoot, defaultStableId = nul
   let frontMatter = {}
   let markdown = content
 
-  // Extract frontmatter
-  if (content.trim().startsWith('---')) {
-    const parts = content.split('---\n')
-    if (parts.length >= 3) {
-      frontMatter = parseYaml(parts[1])
-      markdown = parts.slice(2).join('---\n')
-    }
+  // Extract frontmatter through the ONE splitter (`utils/frontmatter.js`),
+  // rather than re-implementing the `---\n` split for a fourth time.
+  //
+  // ⭐ **The catch is the point, not a workaround.** That function always
+  // throws, and its header says a caller wanting tolerance should say so with a
+  // `try` — explicit and local, instead of a helper that swallowed on behalf of
+  // everyone. This IS that caller: a collect accumulates failures so it can
+  // report every bad file at once and let `strict` decide, which is a policy
+  // only the collect can hold.
+  try {
+    const parsed = parseFrontmatter(content, filePath)
+    frontMatter = parsed.frontmatter
+    markdown = parsed.body
+  } catch (err) {
+    yamlFailures.push({ source: filePath, message: err.message })
+    console.warn(`[content-collector] ${err.message}`)
   }
 
   const { type, component, preset, input, props, fetch, data, id: frontmatterId, ...params } = frontMatter
@@ -1966,48 +2007,60 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
 export async function loadFoundationInfo(foundationPath) {
   if (!foundationPath) return { vars: {}, layoutNames: new Set() }
 
-  // Try dist/meta/schema.json first (built foundation), then root schema.json
-  const distSchemaPath = join(foundationPath, 'dist', 'meta', 'schema.json')
-  const rootSchemaPath = join(foundationPath, 'schema.json')
-
-  const schemaPath = existsSync(distSchemaPath)
-    ? distSchemaPath
-    : existsSync(rootSchemaPath)
-      ? rootSchemaPath
-      : null
-
-  if (schemaPath) {
-    try {
-      const schemaContent = await readFile(schemaPath, 'utf8')
-      const schema = JSON.parse(schemaContent)
-      // Foundation config is in _self, support both 'vars' (new) and 'themeVars' (legacy)
-      const vars = schema._self?.vars || schema._self?.themeVars || schema.themeVars || {}
-      // Layout names from _layouts (keys are layout component names)
-      const layoutNames = new Set(schema._layouts ? Object.keys(schema._layouts) : [])
-      return { vars, layoutNames }
-    } catch (err) {
-      console.warn('[content-collector] Failed to load foundation schema:', err.message)
-      // Fall through to the source-config fallback below.
-    }
+  // ⛔ **NOT `dist/meta/schema.json`.** That file is the EDITOR's artifact — the
+  // rich per-section declaration a visual editor needs to render parameter forms
+  // and component pickers — and it is not a source of truth for a site build.
+  // The architecture is explicit that the declaration is emitted in two shapes
+  // for two audiences (`kb/framework/architecture/site-foundation-runtime-model.md`
+  // § The two-audience schema): the lean runtime half ships INSIDE `dist/entry.js`
+  // as `capabilities`, and the rich half is for authoring tools only.
+  //
+  // Reading the editor's copy here was wrong twice over. It made a site build
+  // depend on the foundation having been BUILT, and it read a derived artifact
+  // when the source it derives from is right there — `generate-entry.js` calls
+  // these same two functions (`:197` for vars, `:287` for layouts) to produce the
+  // very `schema.json` this used to read back.
+  //
+  // ⭐ **And it made dev and build classify layouts differently.** The old
+  // fallback returned an EMPTY layout set whenever no built schema existed —
+  // "the normal state for `uniweb dev`" — and `collectLayouts` treats a
+  // `layout/<Name>/` directory as a named layout only when `<Name>` is in that
+  // set, otherwise as a folder-form area of the DEFAULT layout. So the same site
+  // rendered `layout/Wide/` as the Wide layout after a build and as a default
+  // area called "Wide" in dev. Measured 2026-09-02 before this change:
+  //   built   layouts ["default","Wide"], default areas ["footer","header"]
+  //   dev     layouts ["default"],        default areas ["Wide","footer","header"]
+  // Reading from source removes the asymmetry: there is one answer, and it does
+  // not depend on whether `dist/` happens to exist.
+  const { resolveFoundationSrcPath } = await import('../utils/foundation-source-root.js')
+  const { loadFoundationConfig, discoverLayoutsInPath } = await import('../schema.js')
+  const srcDir = resolveFoundationSrcPath(foundationPath)
+
+  // Two independent reads, so a failure in one does not cost the other. The
+  // previous single try/catch lost the layouts when only the config was broken.
+  let vars = {}
+  try {
+    const config = await loadFoundationConfig(srcDir)
+    vars = config?.vars || {}
+  } catch (err) {
+    console.warn(
+      `[content-collector] Could not read the foundation's declared theme vars from ${srcDir}: ${err.message}\n` +
+        `[content-collector]   Continuing WITHOUT them — the wrapped error above is about loading that config, not about this build stopping.\n` +
+        `[content-collector]   Every foundation theme var is therefore undefined, and sections styled with var(--…) will render with collapsed spacing.`
+    )
   }
 
-  // No built schema.json — the normal state for `uniweb dev` on a bundled-mode
-  // site that was never built (dev doesn't build the foundation to dist/). Read
-  // the foundation's declared vars straight from its source config
-  // (main.js / foundation.js) so theme tokens like --section-padding-y are
-  // defined; without them, components using py-[var(--section-padding-y)] render
-  // with collapsed section spacing. Layouts aren't resolved from source (they
-  // need component discovery), but they aren't needed to build the theme CSS.
+  let layoutNames = new Set()
   try {
-    const { resolveFoundationSrcPath } = await import('../utils/foundation-source-root.js')
-    const { loadFoundationConfig } = await import('../schema.js')
-    const srcDir = resolveFoundationSrcPath(foundationPath)
-    const config = await loadFoundationConfig(srcDir)
-    return { vars: config?.vars || {}, layoutNames: new Set() }
+    layoutNames = new Set(Object.keys(await discoverLayoutsInPath(srcDir)))
   } catch (err) {
-    console.warn('[content-collector] Failed to load foundation source config:', err.message)
-    return { vars: {}, layoutNames: new Set() }
+    console.warn(
+      `[content-collector] Could not discover the foundation's layouts in ${srcDir}: ${err.message}\n` +
+        `[content-collector]   Continuing WITHOUT them — a site \`layout/<Name>/\` directory will be collected as an area of the default layout rather than as that named layout.`
+    )
   }
+
+  return { vars, layoutNames }
 }
 
 /**
@@ -2151,6 +2204,11 @@ async function collectLayouts(layoutDir, siteRoot, layoutNames = new Set()) {
 export async function collectSiteContent(sitePath, options = {}) {
   const { foundationPath, configFile = 'site.yml', profile: profileName, dropUnpublished = false, base = '/', strict = false } = options
 
+  // Fresh accounting per collect — see `yamlFailures`. A dev rebuild runs this
+  // function again, so without the reset a typo fixed three saves ago would
+  // still be counted.
+  yamlFailures = []
+
   // Read site config and raw theme config
   const siteConfig = await readYamlFile(join(sitePath, configFile))
 
@@ -2407,6 +2465,43 @@ export async function collectSiteContent(sitePath, options = {}) {
     if (key.startsWith('$')) delete runtimeSiteConfig[key]
   }
 
+  // ⛔ **A BUILD does not ship a site whose config failed to parse.**
+  // `strict` is already this codebase's word for it — `build-site-data.js` sets
+  // it, and `plugin.js` passes `strict: isProduction` — so the decision lands
+  // where the flag already is, rather than in `parseYaml`, which cannot know.
+  //
+  // ⚠️ **`isProduction` is a misnomer worth not repeating: it is
+  // `config.command === 'build'`** (`plugin.js:788`), i.e. a vite BUILD rather
+  // than a dev server. It says nothing about deployment environments, which
+  // backend a site talks to, or `NODE_ENV`. Both build lanes get it — `export`
+  // and `deploy --host` through vite, `publish` through `build-site-data.js` —
+  // and only `uniweb dev` does not.
+  //
+  // ⭐ Every bad file at once, not the first. Ending the collect at the first
+  // failure would make an author with three typos fix one, rebuild, and meet the
+  // next; the list is the difference between one round trip and three.
+  //
+  // ⚖️ **The dev server deliberately continues.** The author is mid-keystroke
+  // and a half-typed `page.yml` must not blank their running site — they have
+  // the per-file warning above, and the next save fixes it. The asymmetry is the
+  // same one `plugin.js` already draws around the collect as a whole; this puts
+  // the author's own files on the same footing as the machinery around them.
+  // ⚠️ De-duplicated by source: several call sites legitimately read the same
+  // file (a directory's `page.yml` is read once as its own config and again when
+  // its parent resolves nesting), so the raw list counts one typo twice and
+  // "2 files" would be a lie about the author's tree.
+  const distinctFailures = [...new Map(yamlFailures.map((f) => [f.source, f])).values()]
+  if (distinctFailures.length > 0 && strict) {
+    const lines = distinctFailures.map((f) => `  ${f.source}\n    ${f.message}`)
+    throw new Error(
+      `${distinctFailures.length} file${distinctFailures.length === 1 ? '' : 's'} could not be parsed as YAML:\n` +
+        `${lines.join('\n')}\n\n` +
+        `  Each one contributed NOTHING to this build — page order, nesting,\n` +
+        `  sections:, data: and theme settings in these files were dropped.\n` +
+        `  Fix them and rebuild; the dev server reports the same files without failing.`
+    )
+  }
+
   return {
     config: {
       ...runtimeSiteConfig,

package/src/site/query-processor.js

@@ -59,6 +59,7 @@ import { applyWhere, applyFilter, applySort } from './data-fetcher.js'
 import { resolveAssetPath, walkContentAssets, isLocalAssetPath } from './assets.js'
 import { readEntityPool, groupPoolBySchema, ENTITIES_DIR } from './entity-pool.js'
 import { readRecordsConfig, resolveFolder, FOLDER_MISSING } from './records-config.js'
+import { parseFrontmatter } from '../utils/frontmatter.js'
 
 // Try to import content-reader for markdown parsing
 let markdownToProseMirror
@@ -168,67 +169,6 @@ function parseQueryConfig(name, config) {
   }
 }
 
-/**
- * Parse YAML frontmatter from markdown content.
- *
- * Two cases, and keeping them apart is the whole point:
- *
- *   NO frontmatter — the file does not open with `---`, or never closes the
- *   block. Legitimate: a record can be pure body. Returns {}.
- *
- *   DECLARED frontmatter that does not parse — an error, because every field
- *   is gone at once. Not just the one with the typo: title, slug, date, image,
- *   category, all of it. The record still builds, still ships, and lands at a
- *   filename-derived slug with no title and no cover.
- *
- * ⛔ THIS USED TO WARN AND CONTINUE, and the warning could not be found.
- * Measured 2026-08-24 on a real post: an unquoted colon inside a description
- * ("...on a website framework: everything hard about docs...") voided six
- * fields and moved the page from /blog/docs-sites to /blog/11_docs_sites. The
- * only trace was
- *
- *   [query-processor] YAML parse error: bad indentation of a mapping entry (4:72)
- *
- * on line 16 of 857 lines of build output, naming no file, nine lines above
- * "Processed articles: 6 items" — a success line that reads as everything
- * being fine. The build exited 0 and the broken record shipped.
- *
- * A parse error now names the file and says what it costs, because "which of
- * my 200 records is (4:72) in?" is the question the old message left you with.
- *
- * @param {string} raw - Raw file content
- * @param {string} [filepath] - Path to the file, for the error message
- * @returns {{ frontmatter: Object, body: string }}
- */
-function parseFrontmatter(raw, filepath) {
-  if (!raw.trim().startsWith('---')) {
-    return { frontmatter: {}, body: raw }
-  }
-
-  const parts = raw.split('---\n')
-  if (parts.length < 3) {
-    return { frontmatter: {}, body: raw }
-  }
-
-  try {
-    const frontmatter = yaml.load(parts[1]) || {}
-    const body = parts.slice(2).join('---\n')
-    return { frontmatter, body }
-  } catch (err) {
-    const where = filepath ? `${filepath}: ` : ''
-    throw new Error(
-      `${where}frontmatter is not valid YAML — ${err.message}\n` +
-        `  The file opens with \`---\`, so it is declaring frontmatter. Since the block does not\n` +
-        `  parse, EVERY field in it is lost — title, slug, date, image, category — and the record\n` +
-        `  would build as an untitled entry at a slug derived from its filename.\n` +
-        `  A common cause is an unquoted value containing a colon followed by a space:\n` +
-        `    description: Building on a framework: everything hard is a website problem\n` +
-        `  Quote the value and it parses:\n` +
-        `    description: "Building on a framework: everything hard is a website problem"`,
-      { cause: err },
-    )
-  }
-}
 
 /**
  * Extract plain text from ProseMirror content

package/src/utils/frontmatter.js

@@ -0,0 +1,85 @@
+/**
+ * Splitting YAML frontmatter from a markdown body. **The one implementation.**
+ *
+ * ## Why this file exists
+ *
+ * There were three, and they disagreed about the only thing that matters — what
+ * happens when the YAML does not parse. The success paths were character-for-
+ * character identical:
+ *
+ *   `site/query-processor.js`  threw, named the file, said what was lost, and
+ *                              gave the most common cause with its fix
+ *   `uwx/entity-source.js`     `catch {}` — silent, and returned `body: raw`
+ *   `i18n/freeform.js`         `catch {}` — silent
+ *
+ * ⛔ **The silent two were on the paths where it costs most.** `entity-source`
+ * feeds the sync lane, so a typo'd colon pushed to a backend with the record's
+ * frontmatter dropped *and* the broken block embedded in the body — because
+ * `body: raw` returns the text including the `---` fence. And `project-writer`'s
+ * `writeSectionFile` reads through it before writing back: with `frontmatter`
+ * empty, the `key in frontmatter` guard that protects a developer's reserved
+ * keys cannot fire, so a pull clobbers them and writes the broken block into the
+ * content. A malformed file was being converted into a corrupted one.
+ *
+ * ## It always throws, and that is the whole design
+ *
+ * A caller that genuinely wants tolerance says so with a `try`, which is
+ * explicit and local — `uwx/records-project.js`'s `readFileUuid` already does
+ * exactly that, because "this file does not parse" and "this file is not the one
+ * I am looking for" are the same answer to a best-effort probe. Every other
+ * caller was tolerant by accident.
+ *
+ * ## ⚠️ js-yaml, deliberately — do not "upgrade" this to `yaml`
+ *
+ * `@uniweb/build` carries both. The `yaml` package's Document API preserves
+ * comments through a round trip and is used in exactly one place —
+ * `site/deploy-config-writer.js` — because that file WRITES BACK to a config a
+ * human maintains and must not eat their comments. It is slower and its API is
+ * larger, so everything that only READS uses `js-yaml`. This is a read path.
+ */
+
+import yaml from 'js-yaml'
+
+/**
+ * Split YAML frontmatter from a markdown body.
+ *
+ * A file with no frontmatter yields an empty mapping and the whole text as
+ * body — that is not an error, it is a markdown file.
+ *
+ * @param {string} raw - the file's full text
+ * @param {string} [filepath] - where it came from. Optional only because a
+ *   caller may genuinely not have one; pass it whenever you do, since the file
+ *   name is the difference between a fixable error and a hunt.
+ * @returns {{ frontmatter: object, body: string }}
+ * @throws {Error} when a `---` block is present and does not parse as YAML
+ */
+export function parseFrontmatter(raw, filepath) {
+  const text = raw ?? ''
+  if (!text.trimStart().startsWith('---')) {
+    return { frontmatter: {}, body: text }
+  }
+
+  const parts = text.split('---\n')
+  if (parts.length < 3) {
+    return { frontmatter: {}, body: text }
+  }
+
+  try {
+    const frontmatter = yaml.load(parts[1]) || {}
+    const body = parts.slice(2).join('---\n')
+    return { frontmatter, body }
+  } catch (err) {
+    const where = filepath ? `${filepath}: ` : ''
+    throw new Error(
+      `${where}frontmatter is not valid YAML — ${err.message}\n` +
+        `  The file opens with \`---\`, so it is declaring frontmatter. Since the block does not\n` +
+        `  parse, EVERY field in it is lost — title, slug, date, image, category — and the record\n` +
+        `  would build as an untitled entry at a slug derived from its filename.\n` +
+        `  A common cause is an unquoted value containing a colon followed by a space:\n` +
+        `    description: Building on a framework: everything hard is a website problem\n` +
+        `  Quote the value and it parses:\n` +
+        `    description: "Building on a framework: everything hard is a website problem"`,
+      { cause: err },
+    )
+  }
+}

package/src/uwx/backfill.js

@@ -94,7 +94,7 @@ export function backfillUuid(filePath, uuid) {
     }
     next = yaml.dump(withUuidFirst(obj && typeof obj === 'object' ? obj : {}, uuid))
   } else if (ext === '.md') {
-    const { frontmatter, body } = parseFrontmatter(text)
+    const { frontmatter, body } = parseFrontmatter(text, filePath)
     next = `---\n${yaml.dump(withUuidFirst(frontmatter, uuid))}---\n${body}`
   } else {
     return { status: 'deferred', message: `${ext || '(no extension)'} back-fill is not yet implemented` }

package/src/uwx/entity-source.js

@@ -27,31 +27,19 @@ import { parseBibtex } from '@citestyle/bibtex'
 
 const SOURCE_EXTENSIONS = new Set(['.md', '.yml', '.yaml', '.json', '.bib'])
 
-/**
- * Split YAML frontmatter from a markdown body. Mirrors the collection
- * processor's split (`---\n` delimited) so a record read here re-renders to the
- * same shape the back-fill writer produces. A file with no frontmatter yields an
- * empty mapping and the whole text as body.
- *
- * @param {string} raw
- * @returns {{ frontmatter: object, body: string }}
- */
-export function parseFrontmatter(raw) {
-  if (!raw.trimStart().startsWith('---')) {
-    return { frontmatter: {}, body: raw }
-  }
-  const parts = raw.split('---\n')
-  if (parts.length < 3) {
-    return { frontmatter: {}, body: raw }
-  }
-  try {
-    const frontmatter = yaml.load(parts[1]) || {}
-    const body = parts.slice(2).join('---\n')
-    return { frontmatter, body }
-  } catch {
-    return { frontmatter: {}, body: raw }
-  }
-}
+// ⭐ `parseFrontmatter` is re-exported, not reimplemented. This file had its own
+// copy whose `catch {}` returned `{ frontmatter: {}, body: raw }` — silent, and
+// with the unparsed `---` block left in the BODY, so a typo on this lane pushed
+// a record to a backend with its fields dropped and its own broken frontmatter
+// embedded as content. The shared version throws and names the file; a caller
+// that wants tolerance says so with a `try` (see `records-project.js`'s
+// `readFileUuid`, which correctly treats "does not parse" as "not a match").
+// ⛔ Imported AND re-exported: this module calls `parseFrontmatter` itself
+// (below), and a bare `export … from` creates NO local binding — the same
+// trap `core/src/index.js` carries a note about. It fails at runtime, not at
+// import time, so the suite is what catches it.
+import { parseFrontmatter } from '../utils/frontmatter.js'
+export { parseFrontmatter }
 
 // Format key from a file extension. Single source of the format vocabulary the
 // reader emits and the writer dispatches on.
@@ -86,7 +74,7 @@ async function readOneFile(filepath) {
   const raw = await readFile(filepath, 'utf-8')
 
   if (format === 'md') {
-    const { frontmatter, body } = parseFrontmatter(raw)
+    const { frontmatter, body } = parseFrontmatter(raw, filepath)
     const slug = frontmatter.slug || slugFromName
     return [{ slug, format, data: frontmatter, body, sourceFile: filepath, multiRecord: false }]
   }

package/src/uwx/project-writer.js

@@ -165,7 +165,7 @@ export function writeSectionFile({ filePath, content, params, reserved = DEFAULT
   } catch {
     // new file
   }
-  const { frontmatter, body: existingBody } = parseFrontmatter(existing)
+  const { frontmatter, body: existingBody } = parseFrontmatter(existing, filePath)
 
   const nextFrontmatter = { ...frontmatter }
   if (params) {

package/src/uwx/records-project.js

@@ -63,7 +63,7 @@ function readFileUuid(filePath, format) {
     return null
   }
   try {
-    if (format === 'md') return parseFrontmatter(raw).frontmatter?.$uuid ?? null
+    if (format === 'md') return parseFrontmatter(raw, filePath).frontmatter?.$uuid ?? null
     const parsed = format === 'json' ? JSON.parse(raw) : yaml.load(raw)
     if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null
     return parsed.$uuid ?? null