@uniweb/build 0.25.0 → 0.25.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.25.0",
+  "version": "0.25.2",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -59,17 +59,17 @@
     "js-yaml": "^4.1.0",
     "sharp": "^0.35.3",
     "yaml": "^2.5.0",
-    "@uniweb/theming": "^0.1.15",
     "@uniweb/projections": "^0.3.4",
     "@uniweb/schemas": "^0.2.10",
-    "@uniweb/semantic-parser": "^1.2.3",
-    "@uniweb/content-writer": "^0.3.3"
+    "@uniweb/theming": "^0.1.15",
+    "@uniweb/semantic-parser": "^1.3.0",
+    "@uniweb/content-writer": "^0.3.4"
   },
   "optionalDependencies": {
-    "@uniweb/content-reader": "^1.2.3",
     "@uniweb/schemas": "^0.2.10",
-    "@uniweb/runtime": "^0.12.6",
-    "@uniweb/semantic-parser": "^1.2.3"
+    "@uniweb/content-reader": "^1.2.4",
+    "@uniweb/runtime": "^0.12.9",
+    "@uniweb/semantic-parser": "^1.3.0"
   },
   "peerDependencies": {
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0",
@@ -78,7 +78,7 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
     "vite-plugin-svgr": "^4.0.0",
-    "@uniweb/core": "^0.11.0"
+    "@uniweb/core": "^0.11.2"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/schema.js

@@ -10,7 +10,7 @@
  * - Additional paths (via config): meta.js required for addressability
  */
 
-import { readdir, readFile } from 'node:fs/promises'
+import { readdir, readFile, rm } from 'node:fs/promises'
 import { existsSync } from 'node:fs'
 import { isFontVar } from '@uniweb/theming'
 import { join, dirname, extname, basename } from 'node:path'
@@ -156,6 +156,24 @@ const DEFAULT_ONLY_CAPABILITIES = [
  * every `[#id]` rendered as its own literal text — indistinguishable from a
  * foundation that had never opted in. Found only by reading generate-entry.js.
  *
+ * ⚠️ THAT DIAGNOSIS WAS CORRECT AND INCOMPLETE, and the rest took three weeks
+ * to find (2026-08-23). The same commit that moved those keys onto the default
+ * export also added `import … from '@uniweb/kit/xref'`, whose graph reaches
+ * `Ref.jsx`. `loadFoundationConfig` could not parse that, so the config never
+ * loaded at all — the identical symptom, from an unrelated cause, arriving on
+ * the same day the correct fix was applied. The fix looked inert because it
+ * was: where the keys sat could not matter while nothing was read.
+ *
+ * ⛔ AND IT DISABLED THIS WARNING. `warnMisplacedCapabilities` runs AFTER the
+ * import; a config that throws never reaches it. The guard added to catch that
+ * incident was, from that day, unable to fire on the project it was written
+ * for. A check downstream of the thing most likely to fail is not a check.
+ *
+ * To tell the two apart: a misplaced named export loses only that capability.
+ * A config that fails to load loses everything the file declares — `vars`
+ * included, so the site also renders with no theme variables at all. If the
+ * theme is gone too, stop looking at export placement.
+ *
  * A warning rather than an error: a foundation may legitimately export a name
  * that collides for its own use, and failing someone's build over a naming
  * coincidence is worse than telling them what we ignored.
@@ -177,6 +195,70 @@ function warnMisplacedCapabilities(module, filePath) {
   )
 }
 
+/**
+ * Import a foundation config, transpiling it when Node alone cannot.
+ *
+ * ⛔ A foundation config routinely imports JSX, and Node cannot parse it.
+ * `defaultInsets` and `xref` take REACT COMPONENTS — that is what they are
+ * for — so `main.js` legitimately reads:
+ *
+ *     import { buildXrefRegistry, Ref } from '@uniweb/kit/xref'
+ *
+ * kit ships source, so that resolves to `Ref.jsx` and a bare `import()`
+ * throws `Unknown file extension ".jsx"`. The config is fine; the loader was
+ * the problem.
+ *
+ * Fast path first: a plain `import()`, which is free and covers the common
+ * case of a config that is pure data. Only when Node rejects the SYNTAX do we
+ * pay for a bundle — the same fallback shape Vite uses for `vite.config.ts`.
+ *
+ * React stays external because Node imports it happily and it is the bulk of
+ * the graph; everything else is inlined so no `.jsx` survives to be resolved
+ * at run time. The temp file is written beside the config so bare specifiers
+ * still resolve from the project's own `node_modules`.
+ */
+async function importFoundationConfig(filePath) {
+  const href = pathToFileURL(filePath).href
+  try {
+    return await import(href)
+  } catch (error) {
+    if (!isUnparseableByNode(error)) throw error
+
+    const esbuild = (await import('esbuild')).default ?? (await import('esbuild'))
+    const outfile = join(
+      dirname(filePath),
+      `.${basename(filePath)}.uniweb-config.${process.pid}.mjs`,
+    )
+    try {
+      await esbuild.build({
+        entryPoints: [filePath],
+        outfile,
+        bundle: true,
+        format: 'esm',
+        platform: 'node',
+        jsx: 'automatic',
+        // Node can load these as-is, and they dominate the graph.
+        external: ['react', 'react/*', 'react-dom', 'react-dom/*'],
+        logLevel: 'silent',
+      })
+      return await import(pathToFileURL(outfile).href)
+    } finally {
+      await rm(outfile, { force: true }).catch(() => {})
+    }
+  }
+}
+
+/**
+ * Does this error mean "Node cannot read this file", as opposed to "the
+ * config threw"? Only the former is worth re-trying through a bundler —
+ * re-running a config that threw on its own would just throw again.
+ */
+function isUnparseableByNode(error) {
+  if (error instanceof SyntaxError) return true
+  const code = error?.code
+  return code === 'ERR_UNKNOWN_FILE_EXTENSION' || code === 'ERR_UNSUPPORTED_DIR_IMPORT'
+}
+
 export async function loadFoundationConfig(srcDir) {
   let filePath = null
   for (const name of FOUNDATION_FILE_NAMES) {
@@ -188,18 +270,32 @@ export async function loadFoundationConfig(srcDir) {
   }
   if (!filePath) return {}
 
+  let module
   try {
-    const module = await import(pathToFileURL(filePath).href)
-    warnMisplacedCapabilities(module, filePath)
-    // Support both default export and named exports
-    return {
-      ...module.default,
-      vars: inferFontVarTypes(module.vars || module.default?.vars),
-      defaultLayout: module.default?.defaultLayout,
-    }
+    module = await importFoundationConfig(filePath)
   } catch (error) {
-    console.warn(`Warning: Failed to load foundation config ${filePath}:`, error.message)
-    return {}
+    // ⛔ NEVER degrade to `{}` here. Everything a foundation declares — `vars`,
+    // `xref`, `defaultInsets`, `name` — arrives through this one call, so an
+    // empty return silently produces a foundation with NO THEME VARIABLES. The
+    // symptom is a site whose `px-[var(--section-padding-x)]` resolves to 0 and
+    // whose `max-w-[var(--width-content)]` resolves to `none`: content sprawls
+    // edge to edge and every layout token is gone, with nothing in the output
+    // naming a cause. Measured 2026-08-23 on a real site that had been shipping
+    // that way for three weeks behind a single `console.warn`.
+    throw new Error(
+      `Failed to load foundation config ${filePath}: ${error.message}\n` +
+        `  Everything the foundation declares (vars, xref, defaultInsets, name) comes from this file,\n` +
+        `  so the build cannot continue without it — a partial load would emit a site with no theme variables.`,
+      { cause: error },
+    )
+  }
+
+  warnMisplacedCapabilities(module, filePath)
+  // Support both default export and named exports
+  return {
+    ...module.default,
+    vars: inferFontVarTypes(module.vars || module.default?.vars),
+    defaultLayout: module.default?.defaultLayout,
   }
 }
 

package/src/site/collection-processor.js

@@ -134,12 +134,38 @@ function parseCollectionConfig(name, config) {
 }
 
 /**
- * Parse YAML frontmatter from markdown content
+ * 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
+ *
+ *   [collection-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) {
+function parseFrontmatter(raw, filepath) {
   if (!raw.trim().startsWith('---')) {
     return { frontmatter: {}, body: raw }
   }
@@ -154,8 +180,18 @@ function parseFrontmatter(raw) {
     const body = parts.slice(2).join('---\n')
     return { frontmatter, body }
   } catch (err) {
-    console.warn('[collection-processor] YAML parse error:', err.message)
-    return { frontmatter: {}, body: raw }
+    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 },
+    )
   }
 }
 
@@ -508,7 +544,7 @@ async function processContentItem(dir, filename, config, siteRoot, basePath) {
   const slug = basename(filename, extname(filename))
 
   // Parse frontmatter and body
-  const { frontmatter, body } = parseFrontmatter(raw)
+  const { frontmatter, body } = parseFrontmatter(raw, filepath)
 
   // Skip unpublished items by default
   if (frontmatter.published === false) {

package/src/site/deploy-config-writer.js

@@ -26,10 +26,31 @@ import { existsSync } from 'node:fs'
 import { join } from 'node:path'
 import { Document, parseDocument, isMap } from 'yaml'
 
+// The header every generated deploy.yml carries. It has to answer the question
+// a reader has while looking AT the file — who wrote this, and may I edit it —
+// because that is where the question gets asked, not in the docs.
+//
+// The previous wording opened "operational config ... edit `targets:` freely",
+// which reads as a file you are expected to author with one auto-managed block
+// inside it. It cost a real reader an afternoon: they went looking for what to
+// write under `targets:` for a site that had never deployed, when the answer is
+// that the first deploy writes it.
 const SCAFFOLD_HEADER = [
-  ' deploy.yml — operational config and last-deploy memory for this site.',
-  ' Safe to commit. The `lastDeploy:` block is auto-managed by `uniweb deploy`;',
-  ' edit `targets:` freely.',
+  ' deploy.yml — written by `uniweb deploy` / `uniweb publish`.',
+  '',
+  ' You do not create this file. The first successful deploy does, recording the',
+  ' target you picked and what happened. Later deploys rewrite only `lastDeploy:`',
+  ' and leave the rest — including your comments — alone.',
+  '',
+  ' Safe to commit; no credentials live here. Host credentials come from the',
+  ' environment.',
+  '',
+  '   default:     which target is used when none is named',
+  '   targets:     where this site ships. Edit to change the destination, or add',
+  '                a target and pick it with `--target <name>`',
+  '   autoSave:    `lastDeploy` to keep the record below, `off` to stop writing it',
+  '   lastDeploy:  what the last deploy did. A record, not a setting — nothing',
+  '                reads it back, so a stale one is safe to delete',
 ].join('\n')
 
 /**