uniweb 1.13.0 → 1.13.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "1.13.0",
+  "version": "1.13.2",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -41,15 +41,15 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
-    "@uniweb/schemas": "~1.5.0",
-    "@uniweb/content-writer": "~1.3.0",
     "@uniweb/core": "~1.3.0",
-    "@uniweb/semantic-parser": "~1.12.0"
+    "@uniweb/semantic-parser": "~1.12.1",
+    "@uniweb/content-writer": "~1.3.0",
+    "@uniweb/schemas": "~1.5.0"
   },
   "peerDependencies": {
-    "@uniweb/content-reader": "~1.5.2",
-    "@uniweb/semantic-parser": "~1.12.0",
-    "@uniweb/build": "~1.5.1"
+    "@uniweb/build": "~1.5.2",
+    "@uniweb/semantic-parser": "~1.12.1",
+    "@uniweb/content-reader": "~1.5.3"
   },
   "peerDependenciesMeta": {
     "@uniweb/build": {

package/partials/agents.md

@@ -1098,7 +1098,7 @@ import { Section, Prose } from '@uniweb/kit'
 
 `Prose` renders from the parsed sequence — headings, paragraphs, images, snippets, lists — with prose typography. Tagged data blocks are **skipped**; access them via `content.data` for custom rendering. Pass `content` (needs `.sequence`), and `block` too if the content uses insets. Also works as a pure typography wrapper: `<Prose>{children}</Prose>`.
 
-`Article` is an older alternative rendering from `block.rawContent` (raw ProseMirror), including data blocks. Prefer `Prose` for new components.
+`Article` is `Prose` in a semantic `<article>` element — the same rendering, for content that is a self-contained document.
 
 ### The Kit, by use case
 
@@ -1111,13 +1111,13 @@ Names only — for signatures and props, read the package: it's on disk at `node
 **Header/layout:** `useScrolled(threshold)`, `useMobileMenu()`, `useAppearance()`
 **Overlays:** `Overlay` (modals, palettes, drawers, toasts — portals out of the layout, contains focus; read the note below before hand-rolling one)
 **Keyboard:** `useShortcut('mod+k', fn)`, `useShortcuts({…})`, `useShortcutLabel('mod+k')` — `mod` is Cmd on Apple platforms and Ctrl elsewhere, and the label renders per-platform so a hint never shows the wrong key
-**Long-form prose:** `<Prose>` and the container you put `<Render>` output in both use Tailwind Typography's `prose` classes. One line in the foundation's `styles.css` supplies them and points them at the site's theme:
+**Long-form prose:** `<Prose>` and the container you put `<Render>` output in both use kit's `prose` classes. One line in the foundation's `styles.css` supplies the rules, colored by the section's theme:
 
 ```css
-@import "@uniweb/kit/prose-tokens.css";   /* the plugin, wired to theme.yml */
+@import "@uniweb/kit/prose-tokens.css";   /* kit's prose layer, wired to theme.yml */
 ```
 
-Nothing to install — the import brings the plugin with it. **Skip the import and prose is completely unstyled** — lists lose their bullets and numbers, and text its typography — while the markup looks right. The foundation build warns about it, and `uniweb doctor` flags it. Use **one** `prose` container per subtree — the `--tw-prose-*` variables are inherited, so a nested one silently resets them and the outer container goes on looking correct. The section that renders the document is usually the better owner; a layout should supply column width and padding.
+Nothing to install. **Skip the import and prose is completely unstyled** — lists lose their bullets and numbers, and text its typography — while the markup looks right. The foundation build warns about it, and `uniweb doctor` flags it. `size` picks a step (`prose-sm` … `prose-2xl`) of the site's reading size, which `theme.yml` sets under `vars:` — `prose-size`, `prose-leading`, `prose-measure`, `prose-flow`, `prose-h1` … `prose-h4`; spread `proseVars` from `@uniweb/kit/prose-vars` into `main.js`'s `vars` to declare them. A utility class or an element variant (`prose-headings:font-display`, `prose-a:no-underline`) overrides any rule. There are no palette modifiers and no `prose-invert` — the colors are already the theme's, light and dark.
 
 **Documentation shells:** `useHeadings()` (the page's headings + the one being read, derived from content so it prerenders), `website.getBranchHierarchy({ route, for })` (the page tree for one branch). Kit ships no ready-made layout — a layout is your foundation's design; write it in `src/layouts/` and use these for the behaviour.
 **Layout helpers:** `useGridLayout(columns, { gap })`, `useAccordion({ multiple, defaultOpen })`
@@ -1860,7 +1860,7 @@ const page = website.activePage
 | `block.childBlocks` / `block.insets` | Child sections / inline `@Component` references |
 | `block.getInset(refId)` | Lookup an inset by refId |
 | `block.properties` | Raw frontmatter |
-| `block.rawContent` | ProseMirror document — passed internally by `<Article block={block} />` |
+| `block.rawContent` | The section's ProseMirror document, before parsing — what a content handler reads |
 | `block.themeName` | `"light"`, `"medium"`, `"dark"` |
 | `block.stableId` / `block.key` | Stable ID from filename or `id:` / unique key across pages — use as React key |
 | `block.path` | Page route this block belongs to |
@@ -2566,6 +2566,24 @@ await writer.remove(itemId)
   first; a retry would succeed by overwriting a change nobody looked at. Tell the
   person.
 
+### Translated fields
+
+A `localized` field holds `{ en: '…', fr: '…' }`, or one plain value that is every
+language, and a read answers it in the page's language. ⛔ **Never write that one value
+back as the whole field** — it becomes the value in every language. To edit one:
+
+```jsx
+const { entity } = useEntity({ schema: '@/profile', uuid, languages: 'all' })   // every language, as stored
+await writer.update(item.id, { ...item.data, bio: 'Bonjour' }, { language: 'fr' }) // one language, merged
+```
+
+- **`update` with `{ language }`** merges each translated field you name into the languages
+  the item holds, and keeps a translated field you leave out. On a site with more than one
+  language, an update without it that writes a plain value over a translated field read in
+  the page's language is refused.
+- **`languagesOf`, `inLanguage` and `withLanguage`** read and set one language of a value
+  yourself, its `@` metadata kept.
+
 ### ⛔ Permissions are the SERVER'S, and your UI is only a courtesy
 
 Gate your controls on what the viewer may do — a record's own `can_edit` from a

package/src/backend/site-sync.js

@@ -23,6 +23,7 @@ import {
   uncommittedPaths,
   commitRoots,
   gitError,
+  RECORDED_TRAILER,
   unmergedPaths,
   mergeInProgress
 } from '../utils/sync-point.js'
@@ -1071,6 +1072,20 @@ export function uncommittedContent(siteDir, { verb = 'push' } = {}) {
       lines: [`Finish it (\`git commit\`), then ${verb} — or abandon it (\`git merge --abort\`) and pull again.`]
     }
   }
+  // ⭐ A repository with no commit yet is still the one that will hold the site's history —
+  // and holds none of it, so every file is listed as not committed. Said as that, not as
+  // edits. ⛔ Not taken for a folder outside git: its first push would keep nothing to merge
+  // from, and the pull after its first commit would read every difference as a conflict.
+  if (!repo.head) {
+    return {
+      paths,
+      headline: `Not ${done} — this repository has no commit yet, so none of the site's ${paths.length} file(s) is committed.`,
+      lines: [
+        `In a repository a ${verb} sends what you have committed, so a later pull can tell your changes from the backend's.`,
+        `Commit the site, then ${verb} again — or re-run with --commit (and -m "…") to make that first commit.`
+      ]
+    }
+  }
   return {
     paths,
     headline: `Not ${done} — ${paths.length} file(s) of the site are not committed:`,
@@ -1139,8 +1154,11 @@ export function commitWriteBacks(siteDir, backend, { complete = false } = {}) {
     GIT_COMMITTER_EMAIL: `sync@${host}`
   }
   try {
+    // ⭐ Marked with the backend and the site, so a pull reads the commit a lane names through
+    // it (`recordedAfter`, utils/sync-point.js): the ids written back are what the backend holds.
+    const site = readBackendState(siteDir, backend).site?.uuid
     const made = commitRoots(repo, [...sentRoots(siteDir), SYNC_STORE_FILE], {
-      message: `Record what ${backend} gave the site`,
+      message: `Record what ${backend} gave the site${site ? `\n\n${RECORDED_TRAILER}: ${backend} ${site}` : ''}`,
       identity
     })
     if (made && complete) writeSyncPoint(siteDir, backend, made.commit)

package/src/commands/doctor.js

@@ -190,6 +190,30 @@ export function rendersKitProse(dir) {
   )
 }
 
+/** Does a stylesheet load Tailwind Typography itself? */
+export function loadsTypographyPlugin(styles) {
+  return /@plugin\s+["']@tailwindcss\/typography["']/.test(String(styles || ''))
+}
+
+/**
+ * Tailwind Typography's palette modifiers and `prose-invert`, wherever a
+ * foundation's source names one in a class list — `dark:prose-invert` included.
+ * Comments are skipped, since a comment warning against one names it too.
+ *
+ * @returns {{ file: string, modifiers: string[] }[]}
+ */
+export function inertProseModifiers(dir) {
+  const MODIFIER =
+    /(?:^|[\s"'`:])(prose-(?:gray|slate|zinc|neutral|stone|invert|red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose))(?=$|[\s"'`])/gm
+  const found = []
+  forEachSourceFile(dir, (text, file) => {
+    const code = text.replace(/\/\*[\s\S]*?\*\//g, '').replace(/(^|[^:])\/\/.*$/gm, '$1')
+    const modifiers = [...new Set([...code.matchAll(MODIFIER)].map((m) => m[1]))]
+    if (modifiers.length) found.push({ file, modifiers })
+  })
+  return found
+}
+
 function sourceMatches(dir, pattern) {
   let found = false
   forEachSourceFile(dir, (text) => {
@@ -1200,13 +1224,14 @@ export async function doctor(args = []) {
 
   // Prose without the tokens — a silent, total loss of styling.
   //
-  // `@uniweb/kit/prose-tokens.css` brings Tailwind Typography with it and then
-  // points it at the site's theme.yml. A foundation that writes `prose` (or
-  // renders <Prose>/<Article>, which emit it) and does NOT import that file
-  // gets the class and no rules behind it: correct markup, zero styling, and
-  // nothing reported anywhere. Measured 2026-07-30 on a foundation missing only
-  // the plugin — every paragraph `margin-top: 0px`, no warning from Vite,
-  // Tailwind or the browser.
+  // `@uniweb/kit/prose-tokens.css` is kit's prose layer, which answers to the
+  // site's theme.yml. A foundation that writes `prose` (or renders
+  // <Prose>/<Article>, which emit it) and does NOT import that file gets the
+  // class and no rules behind it: correct markup, zero styling, and nothing
+  // reported anywhere. Measured 2026-07-30 on a foundation missing only the
+  // rules — every paragraph `margin-top: 0px`, no warning from Vite, Tailwind or
+  // the browser. (Then the rules were Tailwind Typography's; kit's own since
+  // 2026-10-19.)
   //
   // kit closes this for anyone who imports the file; this closes it for anyone
   // who does not, which is the case kit cannot reach.
@@ -1237,13 +1262,63 @@ export async function doctor(args = []) {
     })
     warn(`[${id}] ${f.name} ${reason}, with no prose styling behind it`)
     log(
-      `    Tailwind Typography supplies the rules and it is not loaded, so the ` +
+      `    kit's prose layer supplies the rules and it is not imported, so the ` +
       `markup is correct and completely unstyled — silently.`
     )
     log(`    Add to ${f.folderName}/styles.css:`)
     log(`      ${colors.dim}@import "@uniweb/kit/prose-tokens.css";${colors.reset}`)
   }
 
+  // A modifier kit's prose layer does not have — `prose-slate`, `prose-invert`
+  // and the rest of Tailwind Typography's palettes. Since 2026-10-19 the layer
+  // takes every color from the section's theme tokens, so a class list still
+  // naming one styles nothing and says a design the page does not have.
+  // Only where the foundation imports kit's layer and does not load the plugin
+  // itself — with its own `@plugin`, the modifier still means what it says.
+  for (const f of foundations) {
+    const stylesPath = join(f.path, 'styles.css')
+    if (!existsSync(stylesPath)) continue
+    const styles = readFileSync(stylesPath, 'utf8')
+    if (!styles.includes('@uniweb/kit/prose-tokens.css')) continue
+    if (loadsTypographyPlugin(styles)) {
+      // Both: the plugin's rules sit in a layer above kit's and win, so prose is
+      // the plugin's again — its own greys, and none of the --prose-* variables.
+      const id = 'prose-plugin-alongside'
+      issues.push({
+        id,
+        type: 'warning',
+        foundation: f.name,
+        message: `${f.name} loads Tailwind Typography as well as kit's prose layer`
+      })
+      warn(`[${id}] ${f.name} loads Tailwind Typography as well as kit's prose layer`)
+      log(
+        `    The plugin's rules sit above kit's and win: prose takes the plugin's greys, not the ` +
+        `theme's colors, and the --prose-* variables reach nothing.`
+      )
+      log(`    Remove the @plugin line from ${f.folderName}/styles.css to use kit's layer alone.`)
+      continue
+    }
+
+    const found = inertProseModifiers(f.path)
+    if (found.length === 0) continue
+
+    const id = 'prose-modifier-inert'
+    const names = [...new Set(found.flatMap((x) => x.modifiers))]
+    issues.push({
+      id,
+      type: 'warning',
+      foundation: f.name,
+      message: `${f.name} names ${names.join(', ')}, which kit's prose layer does not have`
+    })
+    warn(`[${id}] ${f.name} names ${names.join(', ')} — they no longer do anything`)
+    for (const { file, modifiers } of found.slice(0, 6)) log(`    ${file}: ${modifiers.join(', ')}`)
+    log(
+      `    Prose takes its colors from the section's theme tokens, so it already follows ` +
+      `theme.yml and the visitor's scheme. Remove these; to change what prose looks like, ` +
+      `set the theme's colors, or the --prose-* variables.`
+    )
+  }
+
   // ⛔ SAY WHEN A CHECK DID NOT RUN. Every foundation check below reads the
   // BUILT `dist/meta/schema.json` — what a consumer actually receives — and
   // returns silently when there is none. In a workspace with a site, "Foundation

package/src/commands/pull.js

@@ -115,7 +115,7 @@ import {
   isAncestor,
   historySyncPoint,
   madeOnto,
-  newestBase,
+  baseFor,
   openStandIn,
   mergeSyncPoint,
   takeSyncPoint,
@@ -914,13 +914,15 @@ export async function pull(args = [], deps = {}) {
     ]
     const laneRoots = siteLaneRoots(siteDir)
     const taken = (lane) => lane && !lane.notModified && !lane.refused
-    base = newestBase(repo, [...known, content?.source, folderLane?.source], {
+    base = baseFor(repo, {
       known,
-      // ⛔ Each lane the backend answered holds every base to what it names (`newestBase`).
+      // ⛔ What each lane the backend answered names is a base only where every lane holds it (`baseFor`).
       lanes: [
         ...(taken(content) ? [{ source: content.source, roots: laneRoots.content }] : []),
         ...(taken(folderLane) ? [{ source: folderLane.source, roots: laneRoots.records }] : [])
-      ]
+      ],
+      origin: client.origin,
+      siteUuid: siteContentUuid
     })
     onto = force || !base ? repo.head : base
     try {
@@ -1183,6 +1185,8 @@ export async function pull(args = [], deps = {}) {
         } else {
           merge.conflicted = result.conflicted || []
           merge.stashKept = Boolean(result.stashKept)
+          // Whether anything was set aside for the merge: the files as they were, against HEAD.
+          merge.setAside = files !== repo.head
           merge.noBase = !force && !base
           merge.changed = changedInFiles(repo, {
             from: repo.head,
@@ -1286,7 +1290,9 @@ export async function pull(args = [], deps = {}) {
           note("your changes from the backend's: each file where they differ is a conflict, yours against the backend's.")
           note('Once this merge is committed, later pulls merge from it.')
         }
-        note('Settle them and `git add` each, then `git commit` to finish the merge — your uncommitted changes come back with it.')
+        note(
+          `Settle them and \`git add\` each, then \`git commit\` to finish the merge${merge.setAside ? ' — your uncommitted changes come back with it' : ''}.`
+        )
       }
     }
   }

package/src/framework-index.json

@@ -1,15 +1,15 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-10-19T02:42:59.650Z",
+  "generatedAt": "2026-10-19T17:17:22.841Z",
   "packages": {
     "@uniweb/api": {
-      "version": "1.5.2"
+      "version": "1.6.0"
     },
     "@uniweb/build": {
-      "version": "1.5.1"
+      "version": "1.5.2"
     },
     "@uniweb/content-reader": {
-      "version": "1.5.2"
+      "version": "1.5.3"
     },
     "@uniweb/content-writer": {
       "version": "1.3.0"
@@ -24,7 +24,7 @@
       "version": "1.0.4"
     },
     "@uniweb/kit": {
-      "version": "1.4.0"
+      "version": "1.5.0"
     },
     "@uniweb/loom": {
       "version": "1.1.0"
@@ -36,7 +36,7 @@
       "version": "1.1.4"
     },
     "@uniweb/runtime": {
-      "version": "1.1.8"
+      "version": "1.1.9"
     },
     "@uniweb/scene": {
       "version": "1.0.1"
@@ -48,13 +48,13 @@
       "version": "1.1.0"
     },
     "@uniweb/semantic-parser": {
-      "version": "1.12.0"
+      "version": "1.12.1"
     },
     "@uniweb/snapshot": {
       "version": "1.1.0"
     },
     "@uniweb/templates": {
-      "version": "1.1.1"
+      "version": "1.1.2"
     },
     "@uniweb/theming": {
       "version": "1.2.0"

package/src/utils/sync-point.js

@@ -53,6 +53,8 @@ import { join, dirname } from 'node:path'
 
 export const SYNC_TRAILER = 'Uniweb-Sync'
 export const SITE_TRAILER = 'Uniweb-Site'
+/** Marks the commit a push makes of what it wrote back: `Uniweb-Recorded: <origin> <site>`. */
+export const RECORDED_TRAILER = 'Uniweb-Recorded'
 
 const MAX_BUFFER = 1024 * 1024 * 1024
 
@@ -280,24 +282,8 @@ export function madeOnto(repo, sha, { origin, siteUuid }) {
  * reads the old text, so the change-back looks like no change at all. ⛔ Until
  * 2026-10-17 this said an older base "costs precision at worst".
  */
-export function newestBase(repo, candidates, { lanes = null, known = [] } = {}) {
-  let shas = [...new Set(candidates.filter(Boolean))].filter((s) => isCommit(repo, s) && isAncestor(repo, s))
-  // ⛔ ONE MERGE TAKES ONE BASE FOR EVERY LANE, and a lane's own source says what that lane
-  // holds. A commit newer than it whose content differs there reads what the lane lacks — a
-  // push of it the backend refused while it took the other lane — as the backend's removal,
-  // and the merge drops it. A lane that names no source is held to the newest of the bases
-  // this copy knows of itself; with none, only those can be the base.
-  if (lanes?.length) {
-    const own = new Set(known.filter(Boolean))
-    const fallback = newestBase(repo, known)
-    shas = shas.filter((s) =>
-      lanes.every(({ source, roots }) => {
-        const ref = source && isCommit(repo, source) && isAncestor(repo, source) ? source : fallback
-        if (!ref) return own.has(s)
-        return s === ref || isAncestor(repo, s, ref) || !differsIn(repo, ref, s, roots)
-      })
-    )
-  }
+export function newestBase(repo, candidates) {
+  const shas = [...new Set(candidates.filter(Boolean))].filter((s) => isCommit(repo, s) && isAncestor(repo, s))
   if (shas.length <= 1) return shas[0] || null
   const newest = shas.find((s) => shas.every((o) => o === s || isAncestor(repo, o, s)))
   if (newest) return newest
@@ -308,6 +294,60 @@ export function newestBase(repo, candidates, { lanes = null, known = [] } = {})
   }
 }
 
+/**
+ * The base a pull merges from, given the bases this copy knows of itself and what the backend
+ * names for each lane it answered (`x-uniweb-source`).
+ *
+ * ⭐ THIS COPY'S OWN BASES ARE EXACT BY CONSTRUCTION — a pull's commit, the commit a push was
+ * made from once every lane landed, one a push found nothing to send from — and are never
+ * second-guessed here.
+ *
+ * ⛔ ONE MERGE TAKES ONE BASE FOR EVERY LANE, and what the backend names is exact for its own
+ * lane only. A commit one lane names that is newer than another lane's, with that lane's files
+ * different, would read what that lane lacks — a push of it the backend refused while it took the
+ * other — as the backend's removal, and the merge would drop it. So it is not a base. A lane is
+ * held to the commit it names, read through the commit its push made of what it wrote back
+ * (`recordedAfter`), and a lane that names none to the newest base this copy knows.
+ *
+ * ⛔ Until 2026-10-19 (cli 713f62d, uniweb 1.13.0) every candidate was held to that, this copy's
+ * own included, and a lane to the commit it names alone. A first push writes each new record's
+ * `$uuid` back, so the records differed from the commit the folder lane names in every commit after
+ * it, and each was dropped: a pull merged from the site's first push, measured by flows against a
+ * real backend — a reverted change came back (A18), a re-wrap and six pushed edits conflicted.
+ */
+export function baseFor(repo, { known = [], lanes = [], origin, siteUuid }) {
+  const held = (s) => Boolean(s) && isCommit(repo, s) && isAncestor(repo, s)
+  const fallback = newestBase(repo, known)
+  const refs = lanes.map(({ source, roots }) => ({
+    roots,
+    ref: held(source) ? recordedAfter(repo, source, { origin, siteUuid }) || source : fallback
+  }))
+  const named = lanes.flatMap(({ source }) => (held(source) ? [source, recordedAfter(repo, source, { origin, siteUuid })] : []))
+  const taken = named.filter(Boolean).filter((s) =>
+    refs.every(({ ref, roots }) => Boolean(ref) && (s === ref || isAncestor(repo, s, ref) || !differsIn(repo, ref, s, roots)))
+  )
+  return newestBase(repo, [...known, ...taken])
+}
+
+/**
+ * The commit a push made of what it wrote back, after being made from `sha` — its first parent,
+ * marked with the push's backend and site — when HEAD's history holds it; else null.
+ */
+export function recordedAfter(repo, sha, { origin, siteUuid }) {
+  if (!sha || !origin || !siteUuid) return null
+  let out
+  try {
+    out = gitText(repo.top, ['log', '--fixed-strings', `--grep=${RECORDED_TRAILER}: ${origin} ${siteUuid}`, '--format=%H %P', 'HEAD'])
+  } catch {
+    return null
+  }
+  for (const line of out.split('\n')) {
+    const [commit, first] = line.trim().split(' ')
+    if (commit && first && (first === sha || first.startsWith(sha))) return commit
+  }
+  return null
+}
+
 /** Does the content under `roots` differ between two commits? Anything but "no" counts as yes. */
 function differsIn(repo, a, b, roots) {
   try {