uniweb 1.34.0 → 1.34.2

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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "uniweb",
3
- "version": "1.34.0",
3
+ "version": "1.34.2",
4
4
  "description": "Create structured Vite + React sites with content/code separation",
5
5
  "type": "module",
6
6
  "bin": {
@@ -41,15 +41,15 @@
41
41
  "js-yaml": "^4.3.2",
42
42
  "prompts": "^2.4.2",
43
43
  "tar": "^7.5.21",
44
+ "@uniweb/content-writer": "~1.3.2",
44
45
  "@uniweb/core": "~1.6.12",
45
- "@uniweb/schemas": "~1.7.2",
46
- "@uniweb/semantic-parser": "~1.13.4",
47
- "@uniweb/content-writer": "~1.3.2"
46
+ "@uniweb/schemas": "~1.7.3",
47
+ "@uniweb/semantic-parser": "~1.13.4"
48
48
  },
49
49
  "peerDependencies": {
50
- "@uniweb/build": "~1.23.0",
51
- "@uniweb/content-reader": "~1.5.10",
52
- "@uniweb/semantic-parser": "~1.13.4"
50
+ "@uniweb/build": "~1.23.2",
51
+ "@uniweb/semantic-parser": "~1.13.4",
52
+ "@uniweb/content-reader": "~1.5.10"
53
53
  },
54
54
  "peerDependenciesMeta": {
55
55
  "@uniweb/build": {
@@ -80,7 +80,7 @@ When a rule in §2 feels like friction, that is the moment you are about to take
80
80
  | `t('key')`, `<Trans>` | Nothing — content arrives translated; each language is its own build. | — |
81
81
  | `src/assets/`, `assets/img.png` | `./img.png` beside the page, or `/img.png` in `public/`. There is no assets directory. | build stops, or warns |
82
82
  | `fetch: /api/posts`, `fetch: ./data.json` | `fetch:` names a query from `queries.yml`; a URL belongs on the query (`url:`). | build stops |
83
- | `records/blog/2025/post.md`; one YAML file holding a list | Flat: `records/<schema>/<name>.md`, one record per file; the file name is `$name`. | a directory read as a schema, silent |
83
+ | `records/blog/2025/post.md`; one YAML file holding a list; your own schema for posts, people, events | Flat: `records/<schema>/<name>.md`, one record per file, the file name its `$name`. A standard type first: `records/std/article/` is `@std/article`, with the app's own editor (`uniweb guide data` lists 14). | a directory read as a schema, silent |
84
84
  | `` `/blog/${slug}` `` | `item.$route` — never compose a URL. | works until a page moves |
85
85
  | `page.yml` in a directory of pages | It makes one page, each `.md` a section. `folder.yml` keeps them pages and carries `layout`, `title` and SEO. Over a mount, `page.yml` with markdown of its own is a landing page *above* the mounted pages; a mount is one level under `pages/`, and a local subdirectory beside it isn't read. | silent; the build names that subdirectory |
86
86
  | Paste the gtag / GTM / Meta pixel snippet into a component, `index.html`, or `services.tracking.scripts` | Uniweb Cloud (`publish`): `services.google: { id: G-… }`, or `GTM-…` for a container, and the host loads Google's tag, free, with no code, on any foundation. `head.html` isn't applied there, and `scripts` takes URLs only. Static build (`export`, `deploy --host`): the snippet in `head.html` beside `site.yml`. More: `uniweb guide services`. | silent — Google reports nothing |
@@ -260,7 +260,7 @@ content = { title, pretitle, subtitle, paragraphs, links, images, icons, videos,
260
260
 
261
261
  **`site.yml`.** `index`, `pages`, `foundation`, `extensions`, `paths`, `placeholders`, `languages`, `services`, `agents`, `seo` (`origin`: scheme + host, `image`: 1200×630), `favicon`, `touchIcon`. Everything in `site.yml` and `queries.yml` ships to the browser — **never a secret**.
262
262
 
263
- **Records — run `uniweb guide data` before touching them.** `records/<schema>/<name>.md|yml|json|bib` (`records/article/` → `@/article`, the foundation's `schemas/article.yml`, required); `queries.yml` names → `{ schema, where, sort, limit, scope }`; a page or section shows one with `query: name` or `fetch: { query, … }` (narrows, never widens); a `[slug]/` directory inside the query's page gives each record a page.
263
+ **Records — run `uniweb guide data` before touching them.** `records/<schema>/<name>.md|yml|json|bib`, the schema required (§2.2); `queries.yml` names → `{ schema, where, sort, limit, scope }`; a page or section shows one with `query: name` or `fetch: { query, … }` (narrows, never widens); a `[slug]/` directory inside the query's page gives each record a page.
264
264
 
265
265
  ### Foundation
266
266
 
@@ -337,7 +337,7 @@ Every guide ships with the CLI this project pins, so it describes the version in
337
337
  | publish, deploy, push/pull, register, CI, workspaces, updates | `uniweb guide ship` |
338
338
  | port a React / Next / generated design | `uniweb guide migrate` |
339
339
 
340
- **The documentation index is `https://uniweb.io/llms.txt`** — every page with a one-line description and a fetchable link. Go there for anything not answered here and especially to learn whether a feature exists; follow its links rather than constructing them. For several lookups: `git clone --depth 1 https://github.com/uniweb/docs .uniweb-docs` (gitignore it) and grep; bare paths above resolve as index keys, files in the clone, or `https://raw.githubusercontent.com/uniweb/docs/main/{path}`. The docs describe the **latest** release: when `uniweb status` says this project is behind, the fix is `npx uniweb@latest update --yes`, not older docs. Syntax the docs no longer show is listed under *Retired forms* in `uniweb guide ship`. `docs.uniweb.app` is for authors in the visual editor and won't answer framework questions.
340
+ **The documentation index is `https://uniweb.io/llms.txt`** — each page, a line on it, and its link. Go there for anything not answered here, above all whether a feature exists, and follow its links rather than build them. For several lookups: `git clone --depth 1 https://github.com/uniweb/docs .uniweb-docs` (gitignore it) and grep; bare paths above resolve as index keys, files in the clone, or `https://raw.githubusercontent.com/uniweb/docs/main/{path}`. The docs describe the **latest** release: when `uniweb status` says this project is behind, the fix is `npx uniweb@latest update --yes`, not older docs. Syntax the docs no longer show is listed under *Retired forms* in `uniweb guide ship`. `docs.uniweb.app` is for authors in the visual editor, not framework questions.
341
341
 
342
342
  ## 7. Notes about this project
343
343
 
@@ -103,7 +103,7 @@ integrations: # by a mapping the foundation declares in src/mappi
103
103
  - **Applied once**, when a backend is started from the site: its own, a clone's of a template, or one started again after it was destroyed. Then the operator changes these in the backend's administration. An edited file is pushed and pulled with the site, and reaches no backend already running: once the site's has started, a push or publish that sends a change says so, and so does `uniweb status`.
104
104
  - A type not listed stays closed. Name types as `queries.yml` does: `@/vehicle` for the foundation's own, sent in its scope.
105
105
  - A build, a push and `uniweb doctor` refuse a malformed file, naming the key; a push refuses whole. A type none of the site's foundations declares only warns: a backend started from the site leaves that line out, and the publish says so. `where`, `sort` and `limit` are the backend's to judge, and one it refuses is left out the same way.
106
- - An integration's `channel`/`trigger` pairs: `file`+`manual`, `feed`+`on_fetch`, `email` or `http` + `on_create`/`on_match`/`on_change`/`manual`. `enabled: true` only on `file` or `feed`; an address, URL or key is never the file's (the owner gives it in the administration). An `http` line may name a `reply` mapping (named as `mapping` is) and, with it, `reply_about: section.field`. A mapping (`src/mappings/`, one per file, `model: '@/vehicle'` plus its rules) registers with the foundation; the build refuses one naming no `model`, or an `@/x` type (its `model`, or a `follow` line's `model`) or `keys_from` the foundation does not define.
106
+ - An integration's `channel`/`trigger` pairs: `file`+`manual`, `feed`+`on_fetch`, `email` or `http` + `on_create`/`on_match`/`on_change`/`manual`. `enabled: true` only on `file` or `feed`; an address, URL or key is never the file's (the owner gives it in the administration). An `http` line may name a `reply` mapping (named as `mapping` is) and, with it, `reply_about: section.field`. A mapping (`src/mappings/`, one per file, `model: '@/vehicle'` plus its rules) registers with the foundation; the build refuses one naming no `model`, or an `@/x` type (its `model`, or a `follow` line's `model`) or `keys_from` the foundation does not define. A library's mappings (its `mappings/`, named in its scope) are carried by `mappings: ['@acme/x']` in the foundation's `main.js`; `register` sends them from the library first, and the site names them in full.
107
107
  - A team's `all: edit` reaches the entries once the member confirms it is them (below); a team's `add` and `members: edit` need no confirming. Who is in a team, and roles, are never the file's.
108
108
  - A static build carries none of it. A pull writes it back here, never into `site.yml`.
109
109
 
@@ -19,15 +19,37 @@ site/
19
19
 
20
20
  | on disk | schema |
21
21
  |---|---|
22
+ | `records/std/person/…` | `@std/person` — a standard type |
23
+ | `records/acme/project/…` | `@acme/project` — a type registered under another scope |
22
24
  | `records/article/…` | `@/article` — your foundation's own |
23
- | `records/std/person/…` | `@std/person` — the shared standard set |
24
- | `records/acme/project/…` | `@acme/project` — an org's |
25
25
 
26
- **Every record needs its data schema.** `@/article` is the foundation's `schemas/article.yml` (the format: https://uniweb.io/docs/development/data-schemas.md); a directory whose schema nothing defines stops the build and the push, naming the file to write. Keep records of a type registered under another scope in `records/<scope>/<name>/`.
26
+ **Every record needs its data schema — and a standard one comes first.** A directory whose schema nothing defines stops the build and the push. Before writing one, take what exists, in this order:
27
+
28
+ 1. **A standard type**, `@std/<name>`, its records in `records/std/<name>/` and its keys `data: { posts: '@std/article' }`. It ships with the framework, so there is nothing to install, and the app knows it: `@std/article` has the app's article editor, which an article type of your own does not get.
29
+ 2. **A type registered under another scope** — another foundation's, a library's, another org's — by its full name: records in `records/<scope>/<name>/`, keys `'@acme/member'` (§ *The component side*).
30
+ 3. **Your own**, only for a shape none of these has: `schemas/<name>.yml` in the foundation (the format: https://uniweb.io/docs/development/data-schemas.md), records in `records/<name>/`.
31
+
32
+ | standard type | for | written |
33
+ |---|---|---|
34
+ | `article` | a blog post, news item or documentation page | by section: `brief` (title, excerpt, author, date, updated, image, tags), `body` (the text) |
35
+ | `person` | a person, team member or contact | flat |
36
+ | `event` | a calendar event, conference or webinar | flat |
37
+ | `product` | something a business sells | by section: `brief`, `body` |
38
+ | `service` | a service a business offers | by section: `brief`, `body` |
39
+ | `project` | a portfolio item, case study or project showcase | flat |
40
+ | `testimonial` | what a customer, client or patient said: `quote`, `name`, `context`, `avatar`, `rating`, `date`, `url` | flat |
41
+ | `publication` | an academic paper or research document | flat |
42
+ | `opportunity` | a job posting, grant or call for proposals | flat |
43
+ | `position`, `qualification` | a role someone held; a degree, diploma or certificate | flat |
44
+ | `nav` | a navigation menu or link tree | a list |
45
+ | `form` | a form an author designs | a list of controls |
46
+ | `scene` | a Scene Composition Format document | flat |
47
+
48
+ Each type's fields, with what each is for: https://github.com/uniweb/schemas/tree/main/src/standard. A record holds only its type's fields: `uniweb validate` reports one the type lacks and a push refuses it, while a build notes it and still delivers it. What a site says differently (a topic) goes in a field the type has (`tags`), or the type is not the one.
27
49
 
28
50
  Keep directories flat — `records/article/2025/x.md` reads as the `2025` schema of an `article` org. A `_`-prefixed file is not a record.
29
51
 
30
- **Formats:** `.md` (frontmatter fields, body prose; auto-excerpt and first-image extraction), `.yml`/`.yaml` and `.json` (structured, no body), `.bib` (each `@entry{key, …}` is a record named by its cite key, normalized to CSL-JSON, LaTeX accents → Unicode). Mix freely in one directory. **One record per file**; the file name is `$name`, the one name it carries on every site (no `slug` field). Conventional fields: `title`, `date`, `tags`, `image`, `description`, `author`, plus whatever the content needs. Images sit beside the file (`./`). `draft: true` keeps a record off the live site: still a record, previewed by `pnpm dev`, excluded from a production build, kept undelivered on a backend.
52
+ **Formats:** `.md` (frontmatter fields, body prose; auto-excerpt and first-image extraction), `.yml`/`.yaml` and `.json` (structured, no body), `.bib` (each `@entry{key, …}` is a record named by its cite key, normalized to CSL-JSON, LaTeX accents → Unicode). Mix freely in one directory. **One record per file**; the file name is `$name`, the one name it carries on every site (no `slug` field). A record's fields are its data schema's. Images sit beside the file (`./`). `draft: true` keeps a record off the live site: still a record, previewed by `pnpm dev`, excluded from a production build, kept undelivered on a backend.
31
53
 
32
54
  **Links and files are records too.** `records/uniweb/link/x.yml` holding only `url:` (absolute) is a `@uniweb/link`; any file in `records/uniweb/file/` is a `@uniweb/file` named by its file name. Label and tags go on their `records/folder.yml` entry. Declare `data: { videos: '@uniweb/link' }` → `{ url, $name, $label, $tags }`; `data: { downloads: '@uniweb/file' }` → `{ file: { url, name, mime, size }, $name, $label, $tags }`. Two files of one name with different extensions clash. On a backend a component must declare the type for a query over it to be accepted.
33
55
 
@@ -154,7 +176,7 @@ function Article({ content, block }) { // data: { article: { schema: '@std/art
154
176
 
155
177
  **Component-side fetching** for a search box, "load more", a lazy popover: `useFetched`, `useCacheEntry`, `useWholeRecord` share the framework's cache and dedupe same-key requests. On a prerendered page a hook's first render finds only the page's own data; anything else prerenders as the loading state. Declare a key for whatever a page must show without JavaScript.
156
178
 
157
- **`uniweb validate`** checks every record file against declared schemas (missing required, type/enum/format, nested fields); a violation fails it (`--lax` only reports), and `push`/`publish` refuse the same findings. External queries are reported as deferred. A `ref` must name a record in the project (a uuid is left alone); an `options` value isn't checked against the entity it names.
179
+ **`uniweb validate`** checks every record file against declared schemas (missing required, type/enum/format, nested fields, and what a push cannot carry: a field the schema lacks, a markdown body with no field for it); a violation fails it (`--lax` only reports), and `push`/`publish` refuse the same findings. External queries are reported as deferred. A `ref` must name a record in the project (a uuid is left alone); an `options` value isn't checked against the entity it names.
158
180
 
159
181
  ## External sources and transports
160
182
 
@@ -20,6 +20,12 @@
20
20
  * (`destructive_republish`), and the release stops there. Libraries go in the order their types
21
21
  * reference each other, a referenced one first, since the registry refuses a reference to a Model it
22
22
  * doesn't hold yet.
23
+ *
24
+ * ⭐ A LIBRARY'S MAPPINGS GO THE SAME WAY. A foundation carries one by naming it in its main.js
25
+ * (`mappings: ['@acme/vehicle-to-meta']`), and names it in its `mappings` refs; the library's call
26
+ * registers it, after the library's types, with the mappings its `keys_from` names and the library
27
+ * types it names. The registry records, on the foundation, the version it held of each, and a site
28
+ * backend installs that version: a library's next one reaches a site with its foundation's next.
23
29
  */
24
30
 
25
31
  import { existsSync, realpathSync } from 'node:fs'
@@ -42,18 +48,23 @@ function packageDirOf(file) {
42
48
  }
43
49
  }
44
50
 
45
- /** Libraries in an order where one whose types another's reference comes before it; else as found. */
46
- function referencedFirst(libraries, schemas) {
51
+ /**
52
+ * Libraries in an order where one whose types another's types or mappings name comes before it;
53
+ * else as found.
54
+ */
55
+ function referencedFirst(libraries, schemas, mappings = {}) {
47
56
  const holder = new Map()
48
57
  for (const lib of libraries) for (const ref of lib.refs) holder.set(ref, lib)
49
58
  const before = new Map(libraries.map((lib) => [lib, new Set()]))
59
+ const after = (lib, target) => {
60
+ const other = holder.get(target)
61
+ if (other && other !== lib) before.get(lib).add(other)
62
+ }
50
63
  for (const lib of libraries) {
51
64
  for (const ref of lib.refs) {
52
- for (const target of collectNestedRefs(schemas[ref] || {})) {
53
- const other = holder.get(target)
54
- if (other && other !== lib) before.get(lib).add(other)
55
- }
65
+ for (const target of collectNestedRefs(schemas[ref] || {})) after(lib, target)
56
66
  }
67
+ for (const ref of lib.mappings || []) for (const target of typesNamedBy(mappings[ref])) after(lib, target)
57
68
  }
58
69
  const out = []
59
70
  const placed = new Set()
@@ -68,22 +79,37 @@ function referencedFirst(libraries, schemas) {
68
79
  return out
69
80
  }
70
81
 
82
+ /** The types a mapping names, as its `_mappings` entry holds them (in full): its `model` and its `follow` lines'. */
83
+ export function typesNamedBy(mapping) {
84
+ if (!mapping || typeof mapping !== 'object') return []
85
+ const out = []
86
+ if (typeof mapping.model === 'string') out.push(mapping.model)
87
+ for (const line of Array.isArray(mapping.follow) ? mapping.follow : []) {
88
+ if (!line || typeof line !== 'object') continue
89
+ for (const spec of Object.values(line)) if (spec && typeof spec.model === 'string') out.push(spec.model)
90
+ }
91
+ return out
92
+ }
93
+
71
94
  /**
72
- * The libraries that define types the foundation names, each once, with the types it names from
73
- * each, in the order they register in. A type its own `schemas/` defines (`@/x`), one nothing local
95
+ * The libraries that define types the foundation names, or mappings it carries, each once, with the
96
+ * types and mappings it takes from each, in the order they register in. A type its own `schemas/` defines (`@/x`), one nothing local
74
97
  * defines, one two packages define (which the build refused) and one `schemas.config.js` routes are
75
98
  * left out.
76
99
  *
77
100
  * @param {object} o
78
101
  * @param {Record<string, object>} o.schemas - the foundation's built `dataSchemas`: every type it
79
102
  * names, with its definition
103
+ * @param {Record<string, object|null>} [o.mappings] - the foundation's built `_mappings`: its own
104
+ * (`@/x`) and the library ones its main.js carries (in full)
80
105
  * @param {string} o.foundationDir
81
- * @returns {Promise<Array<{ dir: string, scope: string, refs: string[] }>>}
106
+ * @returns {Promise<Array<{ dir: string, scope: string, refs: string[], mappings: string[] }>>}
107
+ * `mappings`: the library mappings it carries from that library, in full
82
108
  * @throws {Error} `code: 'BUILD_TOO_OLD'` when the installed `@uniweb/build` can't tell
83
109
  */
84
- export async function typesFromLibraries({ schemas, foundationDir }) {
110
+ export async function typesFromLibraries({ schemas, mappings, foundationDir }) {
85
111
  const build = await import('@uniweb/build')
86
- const { workspaceTypeFiles, packageTypeScope, classifyPackage, isSchemasPackage, routedSchema, resolveFoundationSrcPath } = build
112
+ const { workspaceTypeFiles, workspaceMappingFiles, packageTypeScope, classifyPackage, isSchemasPackage, routedSchema, resolveFoundationSrcPath } = build
87
113
  if ([workspaceTypeFiles, packageTypeScope, routedSchema].some((fn) => typeof fn !== 'function')) {
88
114
  throw Object.assign(new Error('the installed @uniweb/build cannot tell which library defines a type'), { code: 'BUILD_TOO_OLD' })
89
115
  }
@@ -101,8 +127,25 @@ export async function typesFromLibraries({ schemas, foundationDir }) {
101
127
  if (classifyPackage(dir) === 'foundation' || !isSchemasPackage(dir)) continue
102
128
  const scope = await packageTypeScope(dir, 'schemas')
103
129
  if (!scope) continue
104
- if (!byDir.has(dir)) byDir.set(dir, { dir, scope, refs: [] })
130
+ if (!byDir.has(dir)) byDir.set(dir, { dir, scope, refs: [], mappings: [] })
105
131
  byDir.get(dir).refs.push(ref)
106
132
  }
107
- return referencedFirst([...byDir.values()], schemas || {})
133
+ // ⭐ The library mappings its main.js carries (`mappings: ['@acme/x']`, `_mappings` keys in full),
134
+ // found by the same rule, and registered in their library's call, after its types. One no package
135
+ // here defines is left to the registry, which refuses the foundation unless it holds it.
136
+ if (typeof workspaceMappingFiles === 'function') {
137
+ for (const ref of Object.keys(mappings || {})) {
138
+ if (!/^@[^/]+\/./.test(ref) || ref.startsWith('@uniweb/')) continue
139
+ const files = await workspaceMappingFiles(ref, foundationDir).catch(() => [])
140
+ if (files.length !== 1) continue
141
+ const dir = packageDirOf(files[0])
142
+ if (!dir || real(dir) === own) continue
143
+ if (classifyPackage(dir) === 'foundation' || !isSchemasPackage(dir)) continue
144
+ const scope = await packageTypeScope(dir, 'schemas')
145
+ if (!scope) continue
146
+ if (!byDir.has(dir)) byDir.set(dir, { dir, scope, refs: [], mappings: [] })
147
+ byDir.get(dir).mappings.push(ref)
148
+ }
149
+ }
150
+ return referencedFirst([...byDir.values()], schemas || {}, mappings || {})
108
151
  }
@@ -1459,12 +1459,19 @@ export function writeHeldTypes(siteDir, backend, folderDoc) {
1459
1459
  * ⚠️ Nothing is known before a copy first banks its types, so a copy banked before 2026-11-04
1460
1460
  * retires nothing on its first push after that.
1461
1461
  *
1462
+ * ⭐ AND A MOVED RECORD'S OLD ENTITY IS THIS COPY'S TOO. A move sends the record anew, and the push
1463
+ * maps its own id to the new uuid before this runs, so the map no longer names the old one: the
1464
+ * caller passes what the map named before the push (`ownedBefore`). ⛔ Until 2026-11-11 it did not,
1465
+ * so no move retired anything, and the old records stayed in no folder with nothing offering to
1466
+ * delete them, though the move's note said a push would (measured on uniweb.io: two moves, twelve).
1467
+ *
1468
+ * @param {{ ownedBefore?: Iterable<string> }} [opts] - the uuids the `records` map named before this push
1462
1469
  * @returns {string[]} the uuids this push retired
1463
1470
  */
1464
- export function retireUnplaced(siteDir, backend, { before, after }) {
1471
+ export function retireUnplaced(siteDir, backend, { before, after }, { ownedBefore = [] } = {}) {
1465
1472
  const state = readBackendState(siteDir, backend)
1466
1473
  const prior = state.retired || {}
1467
- const own = new Set(Object.values(state.records || {}))
1474
+ const own = new Set([...Object.values(state.records || {}), ...ownedBefore])
1468
1475
  const now = Object.fromEntries(Object.entries(prior).filter(([uuid]) => !(uuid in after)))
1469
1476
  const retired = Object.keys(before).filter((uuid) => !(uuid in after) && own.has(uuid))
1470
1477
  for (const uuid of retired) now[uuid] = before[uuid]
@@ -3036,6 +3043,9 @@ export async function pushSyncPackages({
3036
3043
  })
3037
3044
  )
3038
3045
  const bf = backfillEntityUuids({ index: records.index, finalized })
3046
+ // What the map named before this push updates it: a moved record's old entity, which the map
3047
+ // stops naming below, is still this copy's to retire (`retireUnplaced`).
3048
+ const ownedBefore = Object.values(readBackendState(siteDir, client.origin).records || {})
3039
3049
  // ⭐ Record which uuid THIS backend minted for each record, keyed by the record's
3040
3050
  // own id. The file keeps that own id; the next push to this backend sends the
3041
3051
  // mapped uuid, and a push to another backend sends none so that one mints its own.
@@ -3075,7 +3085,7 @@ export async function pushSyncPackages({
3075
3085
  if (Object.keys(placements).length)
3076
3086
  writeFolderItemUuids(siteDir, client.origin, placements)
3077
3087
  // What the folder places now, and so which records this push took out of it.
3078
- retireUnplaced(siteDir, client.origin, writeHeldTypes(siteDir, client.origin, folderDoc))
3088
+ retireUnplaced(siteDir, client.origin, writeHeldTypes(siteDir, client.origin, folderDoc), { ownedBefore })
3079
3089
  // ⭐ A LINK RECORD'S IDENTITY is its folder entry's `$uuid`, banked as a record's is: into
3080
3090
  // its file the first time, then mapped per backend (`link-records.js`, 2026-09-28).
3081
3091
  if (records.links?.length) {
@@ -463,11 +463,11 @@ export async function generateLocalizedHtml(projectDir, i18nConfig) {
463
463
  const localeContentPath = join(localeDir, 'site-content.json')
464
464
  let localeHtml = baseHtml
465
465
 
466
- // Update html lang attribute
467
- localeHtml = localeHtml.replace(
468
- /<html[^>]*lang="[^"]*"/,
469
- `<html lang="${locale}"`
470
- )
466
+ // The language this page is in, as `<html lang>`: only its value changes, so the shell's other
467
+ // attributes (its scheme class, a developer's own) stay. ⛔ Until 2026-11-11 every attribute
468
+ // written before `lang` went with it, so a language's shell could lose the class that sets its
469
+ // site's dark look.
470
+ localeHtml = localeHtml.replace(/(<html\b[^>]*?\slang=")[^"]*"/, (_, start) => `${start}${locale}"`)
471
471
  if (!localeHtml.includes('lang=')) {
472
472
  localeHtml = localeHtml.replace('<html', `<html lang="${locale}"`)
473
473
  }
@@ -81,6 +81,7 @@ import {
81
81
  dataBlockModels,
82
82
  siteDefaultSectionType,
83
83
  recordsToProject,
84
+ readSiteFoundationDeclarations,
84
85
  siteSelfScope,
85
86
  readZip,
86
87
  computeUnitHashes,
@@ -1265,9 +1266,15 @@ export async function pull(args = [], deps = {}) {
1265
1266
  )
1266
1267
  }
1267
1268
  }
1269
+ // ⭐ WHAT THE SITE'S FOUNDATION DECLARES, read from its source where it is local, as the build
1270
+ // reads it (`readSiteFoundationDeclarations`): a copy whose foundation has not been built — every
1271
+ // fresh clone — still knows which data key types which folder. ⛔ Until 2026-11-11 the pull read a
1272
+ // built `dist/` only, and such a copy wrote a typed folder's records again in their type's folder.
1273
+ const foundationDeclared = await readSiteFoundationDeclarations(projDir)
1268
1274
  const report = siteContentDocumentToProject({
1269
1275
  document: siteDoc,
1270
1276
  siteRoot: projDir,
1277
+ foundation: foundationDeclared,
1271
1278
  // Which backend's asset ids to read back as the author's own paths. Without
1272
1279
  // it a pull leaves every image pointing at a backend route.
1273
1280
  backend: client.origin,
@@ -1332,7 +1339,9 @@ export async function pull(args = [], deps = {}) {
1332
1339
  resolveDeclaration: (name) => declByModel.get(name) || null,
1333
1340
  // The scope a model's `@/x` was qualified with, so `@acme/article` is placed
1334
1341
  // back in `records/article/` — see `pullScope`.
1335
- scope: pullScope
1342
+ scope: pullScope,
1343
+ // What the foundation declares, read again now the site's content (its `site.yml`) is in.
1344
+ foundation: await readSiteFoundationDeclarations(projDir)
1336
1345
  }
1337
1346
  })
1338
1347
  // ⭐ THE FOLDER'S PLACEMENT IDENTITY, from the folder this pull took — as a push banks
@@ -74,11 +74,15 @@ import {
74
74
  import { execSync } from 'node:child_process'
75
75
  import { resolve, join, relative } from 'node:path'
76
76
  import prompts from 'prompts'
77
+ import { collectNestedRefs } from '@uniweb/schemas/format'
77
78
  import { buildRegistryPackage, buildSchemaOnlyPackage } from '@uniweb/build/uwx'
78
79
  import {
79
80
  classifyPackage,
80
81
  isSchemasPackage,
81
82
  collectStandaloneSchemas,
83
+ buildMappingMap,
84
+ ownMappingFiles,
85
+ loadMappingFile,
82
86
  readFoundationName,
83
87
  checkFoundationName,
84
88
  checkRegistrationScope,
@@ -263,6 +267,35 @@ function sayRefused({ res, parsedBody, rawBody, scope, member, what }) {
263
267
  }
264
268
  }
265
269
 
270
+ /**
271
+ * The mappings a foundation carries from a library (`lib.mappings`, in full), read from its
272
+ * `mappings/`, with each one a `keys_from` names there, keyed `@/<name>` as the library spells them.
273
+ */
274
+ async function libraryMappingsWanted(lib, own) {
275
+ if (!(lib.mappings || []).length) return {}
276
+ const files = new Map(ownMappingFiles(lib.dir).map((m) => [`@/${m.name}`, m.file]))
277
+ const out = {}
278
+ const queue = lib.mappings.map(own).filter(Boolean)
279
+ while (queue.length) {
280
+ const ref = queue.pop()
281
+ if (out[ref] || !files.has(ref)) continue
282
+ out[ref] = await loadMappingFile(files.get(ref))
283
+ const from = typeof out[ref]?.keys_from === 'string' ? own(out[ref].keys_from) : null
284
+ if (from) queue.push(from)
285
+ }
286
+ return out
287
+ }
288
+
289
+ /** A mapping's reverse `follow` lines' `model`s, as written. */
290
+ function followModelsOf(decl) {
291
+ const out = []
292
+ for (const line of Array.isArray(decl?.follow) ? decl.follow : []) {
293
+ if (!line || typeof line !== 'object') continue
294
+ for (const spec of Object.values(line)) if (spec && typeof spec.model === 'string') out.push(spec.model)
295
+ }
296
+ return out
297
+ }
298
+
266
299
  /**
267
300
  * Register the data schemas a library defines, before the foundation that names them
268
301
  * (`backend/library-types.js`): the library's package whole, as `uniweb register` there sends it.
@@ -286,10 +319,31 @@ async function registerLibraryTypes(lib, { client, exporter, at }) {
286
319
  try {
287
320
  // The types the foundation names from it, and no other of its files: those may be another
288
321
  // package's to register, or a copy of one the foundation defines (`library-types.js`).
289
- const wanted = new Set(lib.refs.map((ref) => `@/${ref.slice(lib.scope.length + 1)}`))
322
+ const own = (ref) => (ref.startsWith('@/') ? ref : ref.startsWith(`${lib.scope}/`) ? `@/${ref.slice(lib.scope.length + 1)}` : null)
323
+ const wanted = new Set(lib.refs.map(own))
290
324
  const all = await collectStandaloneSchemas(lib.dir)
325
+ // ⭐ The mappings it carries from here, each with the ones its `keys_from` names, and the types
326
+ // of this library they name: a registry takes a mapping only after what it names.
327
+ const mappings = await libraryMappingsWanted(lib, own)
328
+ for (const decl of Object.values(mappings)) {
329
+ for (const ref of [decl.model, ...followModelsOf(decl)]) {
330
+ const local = typeof ref === 'string' ? own(ref) : null
331
+ if (local && all[local]) wanted.add(local)
332
+ }
333
+ }
334
+ // …and what those types name, of this library, as the build would have named them.
335
+ for (const queue = [...wanted]; queue.length; ) {
336
+ for (const ref of collectNestedRefs(all[queue.pop()] || {})) {
337
+ const local = own(ref)
338
+ if (local && all[local] && !wanted.has(local)) {
339
+ wanted.add(local)
340
+ queue.push(local)
341
+ }
342
+ }
343
+ }
291
344
  doc = buildSchemaOnlyPackage({
292
345
  schemas: Object.fromEntries(Object.entries(all).filter(([key]) => wanted.has(key))),
346
+ mappings,
293
347
  scope: lib.scope,
294
348
  exporter
295
349
  })
@@ -298,7 +352,8 @@ async function registerLibraryTypes(lib, { client, exporter, at }) {
298
352
  return null
299
353
  }
300
354
  const names = doc.entities.map((e) => e.name)
301
- info(`Registering the data schemas in ${at} (${names.join(', ')}) …`)
355
+ const typeNames = doc.entities.filter((e) => e.model === '@uniweb/data-schema').map((e) => e.name)
356
+ info(`Registering ${(lib.mappings || []).length ? 'the data schemas and mappings' : 'the data schemas'} in ${at} (${names.join(', ')}) …`)
302
357
  let res
303
358
  try {
304
359
  res = await client.register(JSON.stringify(doc, null, 2))
@@ -315,10 +370,13 @@ async function registerLibraryTypes(lib, { client, exporter, at }) {
315
370
  }
316
371
  if (res.ok) {
317
372
  const answers = Array.isArray(body?.data_schemas) ? body.data_schemas : []
318
- if (answers.length === names.length && answers.every((a) => a?.unchanged === true)) {
373
+ if (names.length === typeNames.length && answers.length === names.length && answers.every((a) => a?.unchanged === true)) {
319
374
  log(` ${colors.dim}Unchanged: the registry holds them as they are.${colors.reset}`)
320
375
  } else {
321
- success(`Registered ${names.length} data schema(s) under ${lib.scope}, from ${at}`)
376
+ const mappingCount = names.length - typeNames.length
377
+ success(
378
+ `Registered ${[typeNames.length && `${typeNames.length} data schema(s)`, mappingCount && `${mappingCount} mapping(s)`].filter(Boolean).join(' and ')} under ${lib.scope}, from ${at}`
379
+ )
322
380
  }
323
381
  return { names, body }
324
382
  }
@@ -330,10 +388,13 @@ async function registerLibraryTypes(lib, { client, exporter, at }) {
330
388
  const held = await Promise.all(
331
389
  lib.refs.map((ref) => client.readDataSchema(ref).catch(() => undefined))
332
390
  )
391
+ // A mapping isn't read back here: the foundation's own register is refused, naming the mapping
392
+ // and its library, when the registry doesn't hold it.
333
393
  if (held.every(Boolean)) {
334
- const one = lib.refs.length === 1
394
+ const taken = [...lib.refs, ...(lib.mappings || [])]
395
+ const one = taken.length === 1
335
396
  info(
336
- `${lib.refs.join(', ')} ${one ? 'is' : 'are'} registered under ${lib.scope}, whose members change ${one ? 'it' : 'them'}: the foundation is released against ${one ? 'it' : 'them'} as registered.`
397
+ `${taken.join(', ')} ${one ? 'is' : 'are'} registered under ${lib.scope}, whose members change ${one ? 'it' : 'them'}: the foundation is released against ${one ? 'it' : 'them'} as registered.`
337
398
  )
338
399
  return { names: [], body: null }
339
400
  }
@@ -837,17 +898,20 @@ async function runRegister(args = []) {
837
898
  // the package's own schemas; the foundation path reads its built schema.json.
838
899
  let schema = null
839
900
  let schemas = null
901
+ let mappings = null
840
902
  if (standalone) {
841
903
  try {
842
904
  schemas = await collectStandaloneSchemas(targetDir)
905
+ // A library's mappings, beside its types (`mappings/`): registered with them, after them.
906
+ mappings = await buildMappingMap(targetDir, { ownTypes: Object.keys(schemas || {}), shownIn: 'mappings' })
843
907
  } catch (err) {
844
908
  error(`Could not read the schemas package: ${err.message}`)
845
909
  return { exitCode: 2 }
846
910
  }
847
- if (!schemas || Object.keys(schemas).length === 0) {
848
- error('No data schemas found in this package.')
911
+ if ((!schemas || Object.keys(schemas).length === 0) && Object.keys(mappings || {}).length === 0) {
912
+ error('No data schemas or mappings found in this package.')
849
913
  log(
850
- ` ${colors.dim}Expected a package that exports schemas (getSchema / schemas), or a schemas/ directory of *.yml files.${colors.reset}`
914
+ ` ${colors.dim}Expected a package that exports schemas (getSchema / schemas), or a schemas/ or mappings/ directory of *.yml files.${colors.reset}`
851
915
  )
852
916
  return { exitCode: 2 }
853
917
  }
@@ -923,7 +987,11 @@ async function runRegister(args = []) {
923
987
  let fromLibraries = []
924
988
  if (!standalone) {
925
989
  try {
926
- fromLibraries = await typesFromLibraries({ schemas: schema?.dataSchemas || {}, foundationDir: targetDir })
990
+ fromLibraries = await typesFromLibraries({
991
+ schemas: schema?.dataSchemas || {},
992
+ mappings: schema?._mappings || {},
993
+ foundationDir: targetDir
994
+ })
927
995
  } catch (err) {
928
996
  // ⛔ Said, never silent: a build too old to tell which library defines a type registers none,
929
997
  // and the registry then refuses the foundation for it.
@@ -981,7 +1049,7 @@ async function runRegister(args = []) {
981
1049
  let doc
982
1050
  try {
983
1051
  doc = standalone
984
- ? buildSchemaOnlyPackage({ schemas, scope, exporter })
1052
+ ? buildSchemaOnlyPackage({ schemas, mappings, scope, exporter })
985
1053
  : buildRegistryPackage({
986
1054
  schema,
987
1055
  foundationDir: targetDir,
@@ -1012,9 +1080,17 @@ async function runRegister(args = []) {
1012
1080
  log(
1013
1081
  ` ${colors.dim}data schemas ${standalone ? 'registered' : 'defined'}: ${defined.length ? defined.join(', ') : '(none)'}${colors.reset}`
1014
1082
  )
1083
+ const definedMappings = doc.entities.filter((e) => e.model === '@uniweb/mapping-schema').map((e) => e.name)
1084
+ if (definedMappings.length) {
1085
+ log(` ${colors.dim}mappings ${standalone ? 'registered' : 'defined'}: ${definedMappings.join(', ')}${colors.reset}`)
1086
+ }
1015
1087
  for (const lib of fromLibraries) {
1088
+ const taken = [
1089
+ lib.refs.length && `data schemas ${lib.refs.join(', ')}`,
1090
+ (lib.mappings || []).length && `mappings ${lib.mappings.join(', ')}`
1091
+ ].filter(Boolean).join('; ')
1016
1092
  log(
1017
- ` ${colors.dim}data schemas from ${shownAt(lib.dir)}: ${lib.refs.join(', ')} — ${isPreview ? 'would be registered' : 'registered'} from there first${colors.reset}`
1093
+ ` ${colors.dim}from ${shownAt(lib.dir)}: ${taken} — ${isPreview ? 'would be registered' : 'registered'} from there first${colors.reset}`
1018
1094
  )
1019
1095
  }
1020
1096
  if (scope)
@@ -1141,7 +1217,7 @@ async function runRegister(args = []) {
1141
1217
  if (!alreadyRegistered) {
1142
1218
  success(
1143
1219
  standalone
1144
- ? `Registered ${defined.length} data schema(s)${scope ? ` under ${scope}` : ''}`
1220
+ ? `Registered ${[defined.length && `${defined.length} data schema(s)`, definedMappings.length && `${definedMappings.length} mapping(s)`].filter(Boolean).join(' and ')}${scope ? ` under ${scope}` : ''}`
1145
1221
  : `Registered ${registeredName}@${schema._self.version}${defined.length ? ` + ${defined.length} data schema(s)` : ''}`
1146
1222
  )
1147
1223
  }
@@ -156,8 +156,10 @@ function printSiteHuman(result) {
156
156
  )
157
157
  }
158
158
  for (const f of g.findings) {
159
+ // A finding on the record itself (its markdown body, its shape) names no field.
160
+ const at = f.field ? ` › ${f.field}` : ''
159
161
  log(
160
- ` ${colors.yellow}•${colors.reset} item ${colors.bright}"${f.item}"${colors.reset} › ${f.field} — ${f.message}`
162
+ ` ${colors.yellow}•${colors.reset} item ${colors.bright}"${f.item}"${colors.reset}${at} — ${f.message}`
161
163
  )
162
164
  }
163
165
  }
@@ -1,12 +1,12 @@
1
1
  {
2
2
  "schemaVersion": 1,
3
- "generatedAt": "2026-11-11T21:01:37.882Z",
3
+ "generatedAt": "2026-11-11T23:15:48.024Z",
4
4
  "packages": {
5
5
  "@uniweb/api": {
6
6
  "version": "1.7.0"
7
7
  },
8
8
  "@uniweb/build": {
9
- "version": "1.23.0"
9
+ "version": "1.23.2"
10
10
  },
11
11
  "@uniweb/content-reader": {
12
12
  "version": "1.5.10"
@@ -36,13 +36,13 @@
36
36
  "version": "1.2.17"
37
37
  },
38
38
  "@uniweb/runtime": {
39
- "version": "1.6.2"
39
+ "version": "1.6.3"
40
40
  },
41
41
  "@uniweb/scene": {
42
42
  "version": "1.0.1"
43
43
  },
44
44
  "@uniweb/schemas": {
45
- "version": "1.7.2"
45
+ "version": "1.7.3"
46
46
  },
47
47
  "@uniweb/scholar": {
48
48
  "version": "1.1.2"
@@ -24,7 +24,7 @@
24
24
 
25
25
  import { execFile, execFileSync } from 'node:child_process'
26
26
  import { existsSync, readFileSync, realpathSync } from 'node:fs'
27
- import { join, relative, resolve, sep } from 'node:path'
27
+ import { basename, dirname, join, relative, resolve, sep } from 'node:path'
28
28
  import yaml from 'js-yaml'
29
29
  import { repoOf } from './sync-point.js'
30
30
  import { quietGitEnv, upstreamOf } from './git.js'
@@ -148,11 +148,15 @@ export function mountHolding(siteDir, abs) {
148
148
 
149
149
  // git names a repository's top by its real path, and a mount may be reached through a link (a
150
150
  // temporary folder on macOS is): compared as written, it would read as outside the repository.
151
+ // ⭐ A folder that is not there — one inside a submodule no clone checked out — is its nearest
152
+ // folder that is, resolved, and the rest as written. ⛔ Until 2026-11-11 it was compared as written,
153
+ // so a mount inside such a submodule read as a folder no repository holds.
151
154
  function realOf(abs) {
152
155
  try {
153
156
  return realpathSync(abs)
154
157
  } catch {
155
- return abs // not there: compared as written
158
+ const parent = dirname(abs)
159
+ return parent === abs ? abs : join(realOf(parent), basename(abs))
156
160
  }
157
161
  }
158
162
 
@@ -184,7 +184,12 @@ export function writableMounts(siteDir) {
184
184
  if (holding.kind === 'submodule') {
185
185
  const top = join(repo.top, holding.submodule.path)
186
186
  const sub = repoOf(top)
187
- if (!sub?.head) why = 'unchecked'
187
+ // ⛔ A submodule never checked out (a clone made without `--recurse-submodules`) is an empty
188
+ // folder of the site's own repository, and git answers for it with the site's: only a
189
+ // repository whose top is the submodule's folder is the submodule. Until 2026-11-11 the site's
190
+ // answer counted, and a pull in such a clone wrote the mounted pages into the top of the site's
191
+ // repository, committed them, and pinned the submodule to a commit of the site's.
192
+ if (!sub?.head || realOf(sub.top) !== realOf(top)) why = 'unchecked'
188
193
  else submodules.push({ segment, at: holding.submodule.path, root: relative(realOf(top), realOf(abs)).split(sep).join('/') || '.', repo: sub })
189
194
  } else if (holding.kind !== 'site') why = holding.kind
190
195
  } else {