uniweb 0.56.12 → 0.58.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.56.12",
+  "version": "0.58.0",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -43,13 +43,13 @@
     "tar": "^7.0.0",
     "@uniweb/content-writer": "^0.3.4",
     "@uniweb/core": "^0.29.4",
-    "@uniweb/runtime": "^0.26.4",
-    "@uniweb/semantic-parser": "^1.4.1",
+    "@uniweb/runtime": "^0.26.5",
     "@uniweb/kit": "^0.19.3",
-    "@uniweb/schemas": "^0.3.3"
+    "@uniweb/schemas": "^0.3.3",
+    "@uniweb/semantic-parser": "^1.4.1"
   },
   "peerDependencies": {
-    "@uniweb/build": "^0.52.7",
+    "@uniweb/build": "^0.54.0",
     "@uniweb/content-reader": "^1.2.5",
     "@uniweb/semantic-parser": "^1.4.1"
   },

package/partials/agents.md

@@ -694,7 +694,7 @@ end the list with `...`.**
 
 **Configuration cascades: `page.yml` → `folder.yml` → `site.yml` → foundation defaults.** Each level inherits from the one above and overrides specific values, the way CSS specificity works. This is what makes bulk assignment natural — put `layout: marketing` in a `folder.yml` and every page in that folder inherits it, while one page can still override with its own `page.yml`. Reach for `folder.yml` before editing the same key into a dozen `page.yml` files.
 
-**Route mapping:** folder structure maps 1:1 to routes. Every folder keeps its natural route — `pages:` controls **order only**, not which child "becomes" the parent. The only exception is the site root, where `index:` (or first in `pages:`) sets `/`.
+**Route mapping:** folder structure maps 1:1 to routes. Every folder keeps its natural route — `pages:` controls **order only**, not which child "becomes" the parent. The only exception is the site root, where `index:` (or first in `pages:`) sets `/` — declared in `site.yml`, or in the pages directory's own `folder.yml` / `page.yml` (how a content repo carries its order), with `site.yml` winning.
 
 **Content-less containers:** folders with `page.yml` but no markdown are structural groups (`hasContent: false`). Visiting one auto-redirects to the first descendant with content — this is what supports courses → modules → lessons at any depth.
 
@@ -1344,6 +1344,16 @@ Components use **semantic CSS tokens** instead of hardcoded colors. The runtime
 
 **Palette shades** are also available — `text-primary-600`, `bg-neutral-100`, `border-accent-300` — 11 shades (50–950) per palette color (primary, secondary, accent, neutral). See `theme-tokens.css` for the complete mapping.
 
+> **Debugging a token that "does nothing": don't probe it in the browser.** Tailwind v4 is JIT — it emits only the classes it finds in *scanned source*. So a class you assign from JavaScript, to a `<div>` you created in the console, **has never been scanned and can never resolve**, whatever the token. A comparison against a deliberately bogus class agrees with you either way, because both are ungenerated, and classes that happen to appear in source elsewhere look like they "pass" — so the probe confirms whichever answer you started with.
+>
+> **Ask the build instead.** The one command that splits the question:
+>
+> ```bash
+> grep -o '\.text-link{[^}]*}' dist/assets/*.css
+> ```
+>
+> A rule prints → the utility exists, and something at runtime is overriding it. Nothing prints → Tailwind never generated it, and there are only two reasons: your `styles.css` doesn't `@import "@uniweb/kit/theme-tokens.css"` (or declares its own `@theme inline` that omits the token), or your `@source` globs don't cover the file the class is written in. Either way, write the class into a real source file first — a token that's only ever composed at runtime is invisible to the scanner by design.
+
 **Authors control context** via `theme: dark` in frontmatter, alternating `light` (default), `medium`, and `dark` across sections for visual rhythm. **The three presets aren't the limit** — the object form overrides any token per section:
 
 ```yaml

package/src/commands/add.js

@@ -355,6 +355,13 @@ async function addFoundation(rootDir, projectName, opts, pm = 'pnpm') {
   // both. Format validation runs on the derived package name below, not
   // on the raw input — slashes in the input are intentional path syntax.
   const placement = resolvePlacement(rootDir, name, opts, FOUNDATION_KIND)
+  if (placement.outsideRoot) {
+    error(`--path must name a folder inside the workspace: ${placement.outsideRoot}`)
+    log('')
+    log(`The workspace root is ${colors.bright}${rootDir}${colors.reset}.`)
+    log(`A package outside it cannot be a workspace member.`)
+    process.exit(1)
+  }
   const { relativePath } = placement
   let { packageName } = placement
   const fullPath = join(rootDir, relativePath)
@@ -470,6 +477,13 @@ async function addSite(rootDir, projectName, opts, pm = 'pnpm') {
 
   // Resolve placement first (path + package name); see notes in addFoundation.
   const placement = resolvePlacement(rootDir, name, opts, SITE_KIND)
+  if (placement.outsideRoot) {
+    error(`--path must name a folder inside the workspace: ${placement.outsideRoot}`)
+    log('')
+    log(`The workspace root is ${colors.bright}${rootDir}${colors.reset}.`)
+    log(`A package outside it cannot be a workspace member.`)
+    process.exit(1)
+  }
   const { relativePath } = placement
   let siteName = placement.packageName
   const fullPath = join(rootDir, relativePath)

package/src/commands/build.js

@@ -414,10 +414,18 @@ async function loadI18nConfig(projectDir, siteConfig = null) {
     }
   }
 
+  // ⛔ The default locale is the root tree, not `dist/<default>/`. An explicit
+  // `languages: [en, fr]` resolves verbatim — default included — so the DECLARED
+  // form (the one the contract tells authors to use) minted a duplicate copy of
+  // every page, while the wildcard form did not. Dropping it here keeps content,
+  // per-locale HTML and translated records agreeing on one set.
+  const defaultLocale = resolveDefaultLocale(config)
+  locales = locales.filter((l) => l !== defaultLocale)
+
   if (locales.length === 0) return null
 
   return {
-    defaultLocale: resolveDefaultLocale(config),
+    defaultLocale,
     locales,
     localesDir
   }

package/src/commands/clone.js

@@ -271,6 +271,14 @@ export async function clone(args = [], deps = {}) {
       { path: pathFlag, project: projectFlag },
       SITE_KIND
     )
+    if (placement.outsideRoot) {
+      error(`--path must name a folder inside the workspace: ${placement.outsideRoot}`)
+      note(
+        `The workspace root is ${existingRoot}. A package outside it cannot be a ` +
+          `workspace member — the directory and the manifests would disagree.`
+      )
+      return { exitCode: 1 }
+    }
     siteDir = join(existingRoot, placement.relativePath)
     sitePkgName = placement.packageName
     workspaceName = sitePkgName

package/src/commands/i18n.js

@@ -372,6 +372,26 @@ async function runExtract(siteRoot, config, args) {
   }
 }
 
+/**
+ * The starter value a translator is handed for one unit.
+ *
+ * ⭐ `unit.markup` when the element carries inline markdown, `unit.source` otherwise.
+ * `source` is the flattened plain text — it is the KEY, and it is what this function
+ * used to seed. That meant a paragraph's links, bold and emphasis were already gone
+ * from the file a translator opened, and a translator cannot restore what they were
+ * never shown: a 100%-covered locale rendered with zero inline links and no check
+ * reported it (coverage counts keys, not fidelity). `merge` has always parsed a
+ * translation value as inline markdown, so the value channel was lossless the whole
+ * time — only the prompt was lossy. Measured 2026-09-18, @uniweb/build 0.44.4.
+ *
+ * ⚠️ This fills MISSING keys only. A locale file already seeded from the flat source
+ * is not repaired by re-running; use `uniweb i18n generate <locale> --force` against
+ * a freshly extracted manifest to get the markup-bearing source back.
+ */
+function starterValue(unit) {
+  return unit.markup || unit.source
+}
+
 /**
  * Generate command - generate starter translation files from manifest
  *
@@ -451,7 +471,7 @@ async function runInit(siteRoot, config, args) {
 
       for (const [hash, unit] of Object.entries(units)) {
         if (!existingKeys.has(hash)) {
-          existing[hash] = useEmpty ? '' : unit.source
+          existing[hash] = useEmpty ? '' : starterValue(unit)
           added++
         }
       }
@@ -470,7 +490,7 @@ async function runInit(siteRoot, config, args) {
       const localeData = {}
 
       for (const [hash, unit] of Object.entries(units)) {
-        localeData[hash] = useEmpty ? '' : unit.source
+        localeData[hash] = useEmpty ? '' : starterValue(unit)
       }
 
       await writeFile(localePath, JSON.stringify(localeData, null, 2) + '\n')
@@ -962,17 +982,23 @@ async function runAudit(siteRoot, config, args) {
       }
     }
 
-    // Report entries that need inline tag updates
-    const needsTagsTotal = results.reduce(
-      (sum, r) => sum + (r.needsTags?.length || 0),
+    // ⭐ Report translations that will render as flat prose.
+    // Coverage cannot see this class — it counts keys, not fidelity — so a site
+    // whose every link has been flattened reports 100%. That is exactly how a
+    // fully translated documentation site shipped with zero internal links.
+    const losesMarkupTotal = results.reduce(
+      (sum, r) => sum + (r.losesMarkup?.length || 0),
       0
     )
-    if (needsTagsTotal > 0) {
+    if (losesMarkupTotal > 0) {
+      log(
+        `\n${colors.yellow}${losesMarkupTotal} translation(s) drop the inline markup their source carries.`
+      )
       log(
-        `\n${colors.yellow}${needsTagsTotal} translation(s) have inline marks in the source but not in the translation.`
+        `Links, bold and emphasis will be missing from these — a translation value is`
       )
       log(
-        `These translations won't preserve accent/span styling.${colors.reset}`
+        `inline markdown, so copy the [text](href) and ** ** across from the source.${colors.reset}`
       )
       if (!verbose) {
         log(

package/src/commands/pull.js

@@ -156,14 +156,39 @@ function shouldFetchAssets(args, siteDir) {
   return true
 }
 
-// Read a top-level `$uuid:` scalar from a YAML file, or null.
+// Read a top-level `$uuid:` scalar from a YAML file.
+//
+// ⛔ THREE STATES, AND COLLAPSING THEM TO `null` IS A LIE TO THE USER.
+// This returned `null` on any throw, so a site.yml that EXISTS and carries a
+// `$uuid:` line but does not PARSE was reported as "this project has no $uuid
+// yet. Run `uniweb push` first." — advice that is wrong, and actively harmful
+// on a cloned site, since `push` would send an empty tree at the uuid the file
+// already holds.
+//
+// It is also invisible: the user greps the file, sees `$uuid:`, and disbelieves
+// the CLI. The clone suite's own comment records an earlier round of exactly
+// this ("an unquoted `@…` scalar matched a regex here while the file did not
+// parse, and `pull` then found no `$uuid`") — that CAUSE was fixed by quoting
+// the ref; the SYMPTOM stayed reachable by any other parse error.
+// Re-surfaced 2026-09-18 by the backend lane, whose clone wrote a `$uuid:` and
+// whose pull then said there was none.
+//
+// ⇒ Name the state. A missing file and a `$uuid`-less file are "no uuid"; a
+// file that will not parse is an error with the parser's own message.
 function readYamlUuid(filePath) {
+  let text
   try {
-    const obj = yaml.load(readFileSync(filePath, 'utf8'))
-    return typeof obj?.$uuid === 'string' ? obj.$uuid : null
+    text = readFileSync(filePath, 'utf8')
   } catch {
-    return null
+    return { uuid: null } // no site.yml — genuinely nothing to pull
+  }
+  let obj
+  try {
+    obj = yaml.load(text)
+  } catch (err) {
+    return { uuid: null, unparsed: err.message.split('\n')[0] }
   }
+  return { uuid: typeof obj?.$uuid === 'string' ? obj.$uuid : null }
 }
 
 // Conditional-pull ETag cache (gitignored `.uniweb/pull-cache.json`): the last ETag
@@ -583,7 +608,20 @@ export async function pull(args = [], deps = {}) {
 
   // One identity per site: `site.yml::$uuid`. Both lanes (content + folder) are keyed
   // by it — the backend resolves the site's `@uniweb/folder` from this uuid.
-  const siteContentUuid = readYamlUuid(join(siteDir, 'site.yml'))
+  const siteYmlPath = join(siteDir, 'site.yml')
+  const identity = readYamlUuid(siteYmlPath)
+
+  // A file that will not parse is an error, not an absence — see readYamlUuid.
+  if (identity.unparsed) {
+    error(`site.yml did not parse: ${identity.unparsed}`)
+    note(siteYmlPath)
+    note(
+      'Nothing was read, so the $uuid in it (if any) was not seen. Fix the YAML and re-run.'
+    )
+    return { exitCode: 1 }
+  }
+
+  const siteContentUuid = identity.uuid
 
   if (!siteContentUuid) {
     info(

package/src/framework-index.json

@@ -1,16 +1,16 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-09-18T05:17:28.321Z",
+  "generatedAt": "2026-09-19T18:06:40.616Z",
   "packages": {
     "@uniweb/api": {
-      "version": "0.3.7",
+      "version": "0.4.1",
       "path": "framework/api",
       "deps": [
         "@uniweb/core"
       ]
     },
     "@uniweb/build": {
-      "version": "0.52.7",
+      "version": "0.54.0",
       "path": "framework/build",
       "deps": [
         "@uniweb/content-reader",
@@ -83,7 +83,7 @@
       ]
     },
     "@uniweb/runtime": {
-      "version": "0.26.4",
+      "version": "0.26.5",
       "path": "framework/runtime",
       "deps": [
         "@uniweb/core",
@@ -126,7 +126,7 @@
       "deps": []
     },
     "@uniweb/unipress": {
-      "version": "0.9.22",
+      "version": "0.9.24",
       "path": "framework/unipress",
       "deps": [
         "@uniweb/build",

package/src/utils/placement.js

@@ -1,3 +1,5 @@
+import { isAbsolute, relative, sep } from 'node:path'
+
 /**
  * Package placement resolution — shared by `add` and `clone`.
  *
@@ -7,6 +9,31 @@
  * (the same reason `utils/workspace.js` loads the classifier lazily).
  */
 
+// `--path` is documented as a folder INSIDE the workspace, and every consumer of
+// the result treats it that way: the caller does `join(rootDir, relativePath)`
+// while the workspace manifests get `relativePath` verbatim. An ABSOLUTE path
+// silently satisfies neither — `join('/ws', '/tmp/x')` is `/ws/tmp/x`, so the
+// directory is created in one place while `package.json::workspaces` and
+// `pnpm-workspace.yaml` record `/tmp/x`. The two disagree, and the manifests are
+// committed files carrying a path that exists on exactly one machine.
+//
+// Reported by the backend lane 2026-09-18 from a `clone --path <abs>`: the site
+// landed under `company-websites/tmp/claude-502/clonetest/` and both manifests
+// gained the absolute string.
+//
+// So: accept an absolute path when it names a folder inside the root (people type
+// one, and it is unambiguous), by rewriting it to the root-relative form every
+// consumer already expects. Refuse it when it escapes — a workspace package cannot
+// live outside its workspace, and guessing which half the user meant is how you get
+// the split above.
+function normalizeParent(given, rootDir) {
+  const trimmed = String(given).replace(/\/+$/, '')
+  if (!isAbsolute(trimmed)) return { relative: trimmed }
+  const rel = relative(rootDir || '', trimmed)
+  if (!rel || rel === '..' || rel.startsWith('../')) return { outsideRoot: true, given: trimmed }
+  return { relative: rel.split(sep).join('/') }
+}
+
 /** Foundation placement defaults (folder `src/`, package `src`). */
 export const FOUNDATION_KIND = {
   defaultDir: 'src',
@@ -59,17 +86,19 @@ export function resolvePlacement(rootDir, name, opts, kind) {
   //    name was given, or `<path>` itself if not (the path's last segment
   //    is then taken as the package name).
   if (opts.path) {
-    const parent = opts.path.replace(/\/+$/, '')
+    const parent = normalizeParent(opts.path, rootDir)
+    if (parent.outsideRoot) return { outsideRoot: parent.given, relativePath: null, packageName: null }
+    const dir = parent.relative
     if (name) {
       const last = name.split('/').filter(Boolean).pop()
       return {
-        relativePath: `${parent}/${name}`.replace(/\/+/g, '/'),
+        relativePath: `${dir}/${name}`.replace(/\/+/g, '/'),
         packageName: last
       }
     }
-    const lastSegment = parent.split('/').filter(Boolean).pop() || parent
+    const lastSegment = dir.split('/').filter(Boolean).pop() || dir
     return {
-      relativePath: parent,
+      relativePath: dir,
       packageName: lastSegment
     }
   }

package/src/utils/site-identity.js

@@ -28,7 +28,7 @@
  * and it has to move the readers and the writers together or it makes the split worse.
  */
 
-import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { existsSync, readFileSync, readdirSync, writeFileSync } from 'node:fs'
 import { join, dirname } from 'node:path'
 import yaml from 'js-yaml'
 import { DEFAULT_BACKEND_ORIGIN } from './config.js'
@@ -136,10 +136,25 @@ export async function recordSiteBackend(siteDir, origin, deps = {}) {
     // Lazy by necessity, not by taste — see the header.
     mod = await loadUwx()
   } catch {
-    // No `@uniweb/build` at all. It is an OPTIONAL peer, so this is a supported
-    // configuration and not worth a word — the scope simply goes unrecorded, which is
-    // the behaviour everyone had before this key existed.
-    return null
+    // ⛔ NO `@uniweb/build` — and this is the COMMON case on the path that needs it
+    // most, not the rare one this branch used to assume.
+    //
+    // `clone` calls us straight after scaffolding and BEFORE `pnpm install`, so the
+    // site has no `node_modules` yet; under `npx uniweb@latest` the CLI's own tree
+    // may not carry build either (it is an optional peer). The import therefore
+    // fails on a FRESH CLONE essentially always, and returning null wrote nothing.
+    //
+    // The cost is not cosmetic: the clone then holds a `$uuid` minted by the
+    // `--backend` origin it was given, with nothing recording that origin, so the
+    // scope guard infers the DEFAULT backend and stops the very next command with
+    // "this project's stored identity belongs to https://uniweb.app". The origin was
+    // on the command line the whole time.
+    // Measured by the backend lane 2026-09-18: `0.48.5` recorded `$backend`,
+    // `0.57.0` did not, and their clone was unusable until they added the line by hand.
+    //
+    // ⇒ Fall back to a dependency-free write. `js-yaml` is the CLI's own direct
+    // dependency, so this path needs nothing installed in the project.
+    return writeSiteBackendFallback(siteDir, norm)
   }
 
   // ⚠️ PRESENT BUT TOO OLD is a different problem, and it must not look like the one
@@ -167,6 +182,41 @@ export async function recordSiteBackend(siteDir, origin, deps = {}) {
   }
 }
 
+/**
+ * Write `$backend` into `site.yml` without `@uniweb/build` — the fallback for a
+ * project whose dependencies are not installed yet (see `recordSiteBackend`).
+ *
+ * ⭐ Verifies the RESULT rather than trusting the edit: the file must still parse and
+ * must read back the origin we meant to write. A write that corrupts `site.yml` would
+ * be far worse than an unrecorded scope — an unparseable `site.yml` is the failure this
+ * same channel spent an evening on.
+ *
+ * @returns {string|null} the recorded origin, or null when nothing was written
+ */
+function writeSiteBackendFallback(siteDir, norm) {
+  const file = join(siteDir, 'site.yml')
+  let text
+  try {
+    text = readFileSync(file, 'utf8')
+  } catch {
+    return null // no site.yml — nothing to annotate, and we do not create one
+  }
+  try {
+    // Quote through js-yaml rather than by hand: an origin is plain today, but the
+    // value is not ours to assume. Replace an existing key, else prepend.
+    const scalar = yaml.dump(norm, { lineWidth: -1 }).trim()
+    const next = /^\$backend:/m.test(text)
+      ? text.replace(/^\$backend:.*$/m, `$backend: ${scalar}`)
+      : `$backend: ${scalar}\n` + text
+    const parsed = yaml.load(next)
+    if (!parsed || typeof parsed !== 'object' || parsed.$backend !== norm) return null
+    writeFileSync(file, next)
+    return norm
+  } catch {
+    return null
+  }
+}
+
 /**
  * Refuse to act on a site whose stored identity belongs to a different backend.
  *

package/templates/site/site.yml.hbs

@@ -31,6 +31,12 @@ index: home
 # (pages/docs/) holding a folder.yml — folder.yml, not page.yml, because the
 # mounted directory is a folder of pages. Whatever that stub leaves unset comes
 # from the mounted directory's own folder.yml, so it need only say what differs.
+#
+# ! A `pages/<segment>:` sub-mount is BUILD-ONLY today. `uniweb export` and
+#   `uniweb deploy --host <adapter>` mount it normally, but `uniweb push` /
+#   `uniweb publish` do not read the key, so the mounted pages do not reach a
+#   backend (the CLI warns when it skips them). The whole-directory form
+#   `paths: { pages: <dir> }` IS carried by both. Static hosting: use either.
 
 # ─── Structured Content ───────────────────────────────────────────────────────
 # Three things, and they are separate on purpose: