uniweb 1.33.0 → 1.34.1

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/README.md CHANGED
@@ -100,7 +100,7 @@ my-project/
100
100
 
101
101
  **Pages are directories.** Create `pages/about/` with markdown files inside → visit `/about`. That's the whole routing model.
102
102
 
103
- **Batteries included:** File-based routing, pre-rendering, localization, dynamic routes, media processing, search indexing, and more. See [Building with Uniweb](https://github.com/uniweb/docs/blob/main/development/building-with-uniweb.md) for the full list.
103
+ **Batteries included:** file-based routing, prerendering, languages, parametric pages, media processing, search indexing, and pages AI assistants can read: an `llms.txt` index and a Markdown copy of every page, on Uniweb hosting and in every static build. See [Building with Uniweb](https://github.com/uniweb/docs/blob/main/development/building-with-uniweb.md) for the full list.
104
104
 
105
105
  ### Content as Markdown
106
106
 
@@ -130,7 +130,7 @@ role: Lead Architect
130
130
  ```
131
131
  ````
132
132
 
133
- Access the parsed data via `content.data`:
133
+ Declare the key in the section type's `meta.js` (`data: { 'team-member': {} }`), and the parsed data arrives in `content.data`:
134
134
 
135
135
  ```jsx
136
136
  function TeamCard({ content }) {
@@ -211,7 +211,7 @@ Three different section types, arranged in a grid, one with an interactive compo
211
211
  | **None** | Foundation + site with no content |
212
212
  | **Blank** (`--blank`) | An empty workspace — grow it with `uniweb add` |
213
213
 
214
- **Official templates** — marketing sites, documentation, blogs, academic sites and more — each come with a working foundation and sample content. `uniweb template list` shows the ones your CLI scaffolds, and you can [see them live](https://uniweb.github.io/templates/).
214
+ **Official templates** — marketing sites, documentation, blogs, academic sites and more — each come with a working foundation and sample content. `uniweb template list` shows the ones your CLI scaffolds, and you can [see them live](https://uniweb.github.io/templates/). With an agent, name one in the prompt's command: `Start with npx uniweb@latest start --template docs`.
215
215
 
216
216
  **Two starting points.** Either let the CLI create a new directory:
217
217
 
@@ -530,7 +530,7 @@ packages:
530
530
 
531
531
  **Do I need the Uniweb app?**
532
532
 
533
- No. The framework works on its own: content in markdown, built and deployed like any Vite project, to any static host. Connect the app when people who don't write code need to edit the site — or when you'd rather not build an editing interface for them.
533
+ No. The framework works on its own, and `uniweb deploy` puts a site on any static host. On Uniweb hosting, which we recommend, every publish also puts the site in the app, so it's ready whenever you, or anyone you work with, would rather edit visually, with nothing to connect and no editing interface for you to build.
534
534
 
535
535
  **Is the app a CMS?**
536
536
 
@@ -542,7 +542,7 @@ MDX blends markdown and JSX—content authors write code. Uniweb keeps them sepa
542
542
 
543
543
  **How is this different from Astro and other site frameworks?**
544
544
 
545
- They build sites from code and content files, and so does Uniweb. Uniweb adds the other interface: a visual authoring app, kept in sync with your project, where your components are the authors' building blocks. The foundation model also makes components portable across sites, with any deployment — static, SSR, or platform-managed.
545
+ They build sites from code and content files, and so does Uniweb. What Uniweb adds: it is made for building with an agent, with a manual in every project and commands that check the agent's work; what a site says is kept apart from its code, so it can be edited in a visual app kept in sync with your project, where your section types are the building blocks; and the same project grows from a few pages into a platform, with languages, live records, forms, members and payments, without plugins. The foundation model also makes components portable across sites.
546
546
 
547
547
  **Can I use an existing component library?**
548
548
 
@@ -554,7 +554,7 @@ Yes. Content is pre-embedded in the initial HTML—no fetch waterfalls, no layou
554
554
 
555
555
  **What about dynamic routes?**
556
556
 
557
- Pages can define data sources that auto-generate subroutes. A `/blog` page can have an index and a `[slug]` template that renders each post.
557
+ Pages can define data sources that auto-generate subroutes. A `/blog` page can list the posts, and a `[slug]` page inside it renders each one.
558
558
 
559
559
  **Is Uniweb good for documentation sites?**
560
560
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "uniweb",
3
- "version": "1.33.0",
3
+ "version": "1.34.1",
4
4
  "description": "Create structured Vite + React sites with content/code separation",
5
5
  "type": "module",
6
6
  "bin": {
@@ -43,11 +43,11 @@
43
43
  "tar": "^7.5.21",
44
44
  "@uniweb/content-writer": "~1.3.2",
45
45
  "@uniweb/core": "~1.6.12",
46
- "@uniweb/schemas": "~1.7.1",
46
+ "@uniweb/schemas": "~1.7.2",
47
47
  "@uniweb/semantic-parser": "~1.13.4"
48
48
  },
49
49
  "peerDependencies": {
50
- "@uniweb/build": "~1.22.0",
50
+ "@uniweb/build": "~1.23.1",
51
51
  "@uniweb/semantic-parser": "~1.13.4",
52
52
  "@uniweb/content-reader": "~1.5.10"
53
53
  },
@@ -80,11 +80,11 @@ 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 |
87
- | Expect `{company}` to resolve | Only under a foundation with `createLoomHandlers`; otherwise it renders literally. | build warns if `site.yml` has `placeholders:` |
87
+ | Expect `{company}` to resolve | Only under a foundation with `createLoomHandlers`; otherwise it renders literally. | build warns where a page writes one |
88
88
  | `hidden: true` on `pages/404/` to keep it out of nav | That makes it a draft. `hideIn: ['*']` controls nav. | silent |
89
89
  | Treat `@child.md` / `_draft.md` as names | `@` = child section, placed by `nest:` (with none it renders last; a `sections:` list drops it); `_` = ignored. | build warns, unless `sections:` dropped it |
90
90
  | Treat the files as the only copy of the content; regenerate pages from a script | On a synced site authors edit the same pages in the app, and a pull writes their edits into the files. Take what changed before you edit (`status` names it), and edit the files rather than regenerate them, or your next push replaces the authors' work. | silent after a pull; a push refuses a section changed on both sides |
@@ -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`); `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`/`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). 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 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,13 +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
+
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: a push refuses one with a field the type lacks, though a static build keeps it. What a site says differently (a topic) goes in a field the type has (`tags`), or the type is not the one.
25
49
 
26
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.
27
51
 
28
- **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.
29
53
 
30
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.
31
55
 
@@ -53,7 +77,7 @@ The body — `body.content`.
53
77
 
54
78
  Paths are relative to `records/`, one file or a glob. An entry can be `{ path, tags, label }` — delivered beside the record as `$tags` (in order) and `$label` (one text or `{ en, fr }`, resolved to the page's language); a query reads them like any key (`where: { $tags: featured }`). `scope: archive` reads the folder and everything inside. A record sits in one folder; a computed subset is a query. The build refuses a top-level bare path (every file is a record already).
55
79
 
56
- **With a backend, `records/` is what `uniweb push` sends.** No `records/` leaves the backend alone; an *empty* `records/` takes them out of the site's folder (the CLI asks). Records with a data schema reach published pages only when `services.records: true`; once the site has been published, a push changes its records on the live site with no republish (pages wait for `uniweb publish`). To move records to another schema, move their files into its directory, renamed or not, and keep each file's `$uuid` line: the push sends each as a new record in the place the old one had. A record taken out of the folder stays on the backend, and the push that took it out offers to delete it (`--yes` deletes without asking).
80
+ **With a backend, `records/` is what `uniweb push` sends.** No `records/` leaves the backend alone; an *empty* `records/` takes them out of the site's folder (the CLI asks). Records reach published pages only when `services.records: true`; once the site has been published, a push changes its records on the live site with no republish (pages wait for `uniweb publish`). To move records to another schema, move their files into its directory, renamed or not, and keep each file's `$uuid` line: the push sends each as a new record in the place the old one had. A record taken out of the folder stays on the backend, and the push that took it out offers to delete it (`--yes` deletes without asking).
57
81
 
58
82
  ## Queries
59
83
 
@@ -120,6 +120,7 @@ When `status` names a newer release, take it: update, restart any running dev se
120
120
  | `fetcher.baseUrl / headers / envelope / supports / request.*` | a transport under `fetcher.transports` |
121
121
  | top-level `search:`, `submit:`, `assistant:`, `tracking:`, `api:`; `services.api`; `$devApi` | `services.<name>`; `services.backend`; `$devBackend` |
122
122
  | `published: false` on a record | `draft: true` |
123
+ | a record directory with no data schema; `records/<query>.schema.js` | the foundation's `schemas/<name>.yml` — every record needs one |
123
124
  | `slug:` key in a record file; a file holding a list | the file name is the record's name; one record per file |
124
125
  | `[dir]` / `[path]` as parametric directory names; a directory inside `[...path]/` | `[slug]`, `[uuid]`, `[<field>]`, `[...path]` |
125
126
  | `fonts.mono` | `fonts.code` |
@@ -89,8 +89,15 @@ export function collectAssetRefs(document, map = {}) {
89
89
  return [...found.values()]
90
90
  }
91
91
 
92
- /** Where a site-root ref lives on disk. `resolveAssetPath` looks in public/ first. */
93
- const diskPathFor = (siteDir, ref) => join(siteDir, 'public', ref)
92
+ /**
93
+ * Where a ref lives on disk: where the push read it (`resolveAssetPath`). A site-root
94
+ * ref (`/images/hero.jpg`) is a file in public/. A ref the push keyed from a file beside
95
+ * its markdown has no leading slash (`pages/home/band.jpg`, relative to the site root)
96
+ * and lives there. ⛔ Until 2026-11-11 every ref was taken as site-root, so a pull wrote
97
+ * a page's own picture a second time under public/pages/…, where nothing names it.
98
+ */
99
+ const diskPathFor = (siteDir, ref) =>
100
+ ref.startsWith('/') ? join(siteDir, 'public', ref) : join(siteDir, ref)
94
101
 
95
102
  /** The generic landing path for an asset this project has never held. */
96
103
  export const genericRefFor = (id, ext) => `/assets/${id}${ext ? `.${ext}` : ''}`
@@ -122,18 +129,29 @@ export async function downloadMissingAssets({
122
129
  const out = { downloaded: [], present: [], failed: [], skipped: [] }
123
130
  if (!refs.length) return out
124
131
 
132
+ // Every path the map holds for an id. A push merges into the map and never prunes it,
133
+ // so a file moved after it was pushed leaves its old path beside the new one. The asset
134
+ // is on disk when ANY of its paths holds it, and one that is not goes back to the FIRST
135
+ // path, the one `restoreAssetRefs` writes into the content. ⛔ Until 2026-11-11 the
136
+ // LAST path won here and the first there, so a pull fetched a moved picture again, to
137
+ // a path nothing names.
125
138
  const byId = new Map()
126
- for (const [ref, v] of Object.entries(map)) if (v?.id) byId.set(v.id, ref)
139
+ for (const [ref, v] of Object.entries(map)) {
140
+ if (!v?.id) continue
141
+ if (!byId.has(v.id)) byId.set(v.id, [])
142
+ byId.get(v.id).push(ref)
143
+ }
127
144
 
128
145
  const learned = {}
129
146
 
130
147
  for (const { id, ext, url } of refs) {
131
148
  const known = byId.get(id)
132
- const ref = known || genericRefFor(id, ext)
149
+ const ref = known ? known[0] : genericRefFor(id, ext)
150
+ const held = (known || [ref]).find((r) => existsSync(diskPathFor(siteDir, r)))
133
151
  const disk = diskPathFor(siteDir, ref)
134
152
 
135
- if (existsSync(disk)) {
136
- out.present.push(ref)
153
+ if (held) {
154
+ out.present.push(held)
137
155
  // Still record identity for a generic ref we already hold but never mapped.
138
156
  if (!known) learned[ref] = { id, ext }
139
157
  continue
@@ -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) {
@@ -378,18 +378,20 @@ async function loadI18nConfig(projectDir, siteConfig = null) {
378
378
 
379
379
  /**
380
380
  * Build every configured language but the default: its records, its content, and — on the bundle
381
- * lane — its search index, llms.txt and page markdown, in that order (`buildLocalizedSite`).
381
+ * lane — its search index, llms.txt and page markdown, in that order (`buildLocalizedSite`). The link
382
+ * lane builds its content alone (`records: false`).
382
383
  *
383
384
  * ⛔ Until 2026-10-25 each lane ran content, then records, here in two copies, and a language's
384
385
  * search index was written in the content step, before its records were translated.
385
386
  */
386
- async function buildLocalizedSite(projectDir, i18nConfig, { projections = false } = {}) {
387
+ async function buildLocalizedSite(projectDir, i18nConfig, { projections = false, records = true } = {}) {
387
388
  const { buildLocalizedSite } = await import('@uniweb/build/i18n')
388
389
  return buildLocalizedSite(projectDir, {
389
390
  locales: i18nConfig.locales,
390
391
  localesDir: i18nConfig.localesDir,
391
392
  outputDir: join(projectDir, 'dist'),
392
- projections
393
+ projections,
394
+ records
393
395
  })
394
396
  }
395
397
 
@@ -461,11 +463,11 @@ export async function generateLocalizedHtml(projectDir, i18nConfig) {
461
463
  const localeContentPath = join(localeDir, 'site-content.json')
462
464
  let localeHtml = baseHtml
463
465
 
464
- // Update html lang attribute
465
- localeHtml = localeHtml.replace(
466
- /<html[^>]*lang="[^"]*"/,
467
- `<html lang="${locale}"`
468
- )
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}"`)
469
471
  if (!localeHtml.includes('lang=')) {
470
472
  localeHtml = localeHtml.replace('<html', `<html lang="${locale}"`)
471
473
  }
@@ -537,9 +539,10 @@ function resolveFoundationDir(projectDir, siteConfig) {
537
539
  * search index.*
538
540
  *
539
541
  * The `buildLocalizedSite` step is the call bundle mode makes post-vite,
540
- * without the projections, so multi-locale sites get identical per-locale
541
- * outputs in either mode: each language's query files (dist/<lang>/data/),
542
- * then its content (dist/<lang>/site-content.json).
542
+ * without the projections and the records, so multi-locale sites get identical
543
+ * per-locale content in either mode (dist/<lang>/site-content.json). A push
544
+ * sends each record in every language; a host's records service answers its
545
+ * queries, so this mode compiles no query files (dist/<lang>/data/).
543
546
  *
544
547
  * History: when `deploy` uploaded `dist/site-content.json` to a backend, it
545
548
  * read the bundle pipeline's copy, which prerender rewrites into a lightweight
@@ -587,7 +590,7 @@ async function buildSiteLink(projectDir, options = {}) {
587
590
  log('')
588
591
  info(`Building localized content for: ${i18nConfig.locales.join(', ')}`)
589
592
  try {
590
- reportLocalizedSite(await buildLocalizedSite(projectDir, i18nConfig))
593
+ reportLocalizedSite(await buildLocalizedSite(projectDir, i18nConfig, { records: false }))
591
594
  } catch (err) {
592
595
  error(`i18n build failed: ${err.message}`)
593
596
  if (process.env.UNIWEB_DEBUG) console.error(err.stack)