uniweb 1.28.1 → 1.29.0

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.28.1",
3
+ "version": "1.29.0",
4
4
  "description": "Create structured Vite + React sites with content/code separation",
5
5
  "type": "module",
6
6
  "bin": {
@@ -41,13 +41,13 @@
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.1",
45
- "@uniweb/schemas": "~1.6.10",
46
- "@uniweb/core": "~1.6.4",
47
- "@uniweb/semantic-parser": "~1.13.2"
44
+ "@uniweb/semantic-parser": "~1.13.2",
45
+ "@uniweb/core": "~1.6.6",
46
+ "@uniweb/schemas": "~1.6.11",
47
+ "@uniweb/content-writer": "~1.3.1"
48
48
  },
49
49
  "peerDependencies": {
50
- "@uniweb/build": "~1.17.1",
50
+ "@uniweb/build": "~1.18.0",
51
51
  "@uniweb/content-reader": "~1.5.9",
52
52
  "@uniweb/semantic-parser": "~1.13.2"
53
53
  },
@@ -95,6 +95,7 @@ When a rule in §2 feels like friction, that is the moment you are about to take
95
95
  | `<h2><H2 text=… /></h2>` | Kit text components render their own tag. | double tag |
96
96
  | `content.items?.map`, `content.title ?? ''` | Never null — strings and arrays, always. | — |
97
97
  | `className="sticky top-0"` | `sticky: true` in the type's `meta.js`. | `uniweb dev` names it |
98
+ | A header floated over the hero with `absolute` or `fixed` | `underHeader: true` on the hero's type, `height` on the header's; the bar stays in the flow (foundation guide). | silent — section links land under the bar |
98
99
  | `fixed inset-0 z-[9999]` for a modal | `<Overlay>` from kit — layout areas are stacking contexts, no z-index escapes one. | silent — under the header |
99
100
  | `typeof window`, `localStorage.theme`, a theme `useEffect` | `useAppearance()`; the scheme is resolved before first paint; kit hooks are SSR-safe. | theme flash |
100
101
  | `<a href="/about">` | `<Link to="page:about">` (an `id:` survives moves) or `<Link href="/about">`. A bare `<a>` still routes but resolves no `page:` and adds no base path or locale. | silent |
@@ -125,7 +126,7 @@ When a rule in §2 feels like friction, that is the moment you are about to take
125
126
  | `font-serif`, `font-sans` | Tailwind's stack, not the site's — unless the foundation declares it as a `font-*` var in `main.js`. Families are the site's (`theme.yml fonts:`). | silent |
126
127
  | `@import url(fonts.googleapis…)` in CSS | `theme.yml fonts.import` / `faces`. | — |
127
128
  | `@tailwind base;` | Tailwind v4: `@import "tailwindcss"` plus kit's token imports (theme guide). | silent — most utilities missing |
128
- | Trust the foundation's own build to prove a class works | A site build and `uniweb dev` read only the folders `@source` names — one line per folder that writes classes (`sections`, `components`, `layouts`). | each names a folder you missed, as does `doctor` |
129
+ | Trust the foundation's own build to prove a class works | A site build and `uniweb dev` read only the folders `@source` names — one line per folder that writes classes (`sections`, `components`, `layouts`, `utils`). | each names a folder you missed, as does `doctor` |
129
130
  | `prose` from `@tailwindcss/typography`, `prose-invert` | `@import "@uniweb/kit/prose-tokens.css"`; no invert — colors are already the theme's. | build warns; unstyled lists |
130
131
  | `html { scroll-behavior: smooth }` | Never on `html`/`body`; the runtime owns scrolling. | route transitions misbehave |
131
132
  | `filter: blur(80px)` for a glow | Radial gradient + `mask-image`. | Safari jank |
@@ -275,7 +276,7 @@ src/
275
276
  |---|---|---|
276
277
  | `type`, `id`, `hidden` | the section itself | — |
277
278
  | `query`, `fetch` | its data | `content.data[key]`, for keys declared in `data:` |
278
- | `theme`, `background`, `grid`, `vars`, `sticky` | settings the runtime applies | `block` — `useColorContext(block)`, `<SectionBackground block>`, `<ChildGrid from={block}>`, `block.sticky` |
279
+ | `theme`, `background`, `grid`, `vars`, `sticky`, `underHeader` | settings the runtime applies | `block` — `useColorContext(block)`, `<SectionBackground block>`, `<ChildGrid from={block}>`, `block.sticky`, `block.underHeader` |
279
280
  | `props` | params as one map | merged into `params` |
280
281
  | `data`, `preset`, `input` | `data:` stops the build (it was `query:`); the others warn and do nothing | — |
281
282
 
@@ -292,7 +293,7 @@ import { H1, P, Prose, Visual, Icon, Link, ChildBlocks, Overlay, PlainText } fro
292
293
  export default {
293
294
  title: 'Feature Grid', description: 'Grid of feature cards with icons',
294
295
  family: 'features', // the standard kind it is (`uniweb families`); a name like `Hero` resolves on its own
295
- // hidden: true · inset: true · area: 'header' · section: true · children: true · background: 'self' · sticky: true
296
+ // hidden: true · inset: true · area: 'header' · section: true · children: true · background: 'self' · sticky: true · underHeader: true · height: '4rem'
296
297
  content: { title: 'Heading', paragraphs: 'Intro [0-1]', media: 'Photo [1]',
297
298
  items: { label: 'Cards [3-6]', content: { icon: 'Icon [1]', title: 'Name', paragraphs: 'Text' } } },
298
299
  params: { columns: { type: 'number', default: 3 },
@@ -193,11 +193,19 @@ background: primary-900 # palette token (bare n
193
193
  background:
194
194
  image: { src: /img.jpg, position: center top }
195
195
  overlay: { enabled: true, type: dark, opacity: 0.5 }
196
+ background:
197
+ image: /img.jpg
198
+ overlay: # a fading overlay; every gradient field optional
199
+ enabled: true
200
+ opacity: 1 # 0.5 when left out, on the gradient too
201
+ gradient: { angle: 90, start: 'rgba(0,0,0,0.8)', startPosition: 0, end: 'rgba(0,0,0,0)', endPosition: 60 }
196
202
  background:
197
203
  video: { src: /videos/hero.mp4, poster: /images/hero.jpg }
198
204
  ```
199
205
 
200
- Components that draw their own declare `background: 'self'` in `meta.js`; they can still render the author's with `<SectionBackground block={block} />`.
206
+ An overlay is drawn only with `enabled: true` (the number shorthand, `overlay: 0.5`, sets it).
207
+
208
+ Components that draw their own declare `background: 'self'` in `meta.js`. They then paint everything behind their content, the section's surface color included (`bg-section` where they want it), and can still render the author's background with `<SectionBackground block={block} />`.
201
209
 
202
210
  ## Pages
203
211
 
@@ -68,9 +68,10 @@ Skip it and prose is unstyled (lists lose bullets) while the markup looks right;
68
68
  Things you won't discover from exports:
69
69
 
70
70
  - **`<Link>` takes `to` or `href`.** `to="page:about"` resolves a page id (survives moves) or a route, never a folder: the homepage is `page:/`, or `page:home` only when its `page.yml` says `id: home`. External URLs get `target="_blank"`; `reload` forces a full load.
71
+ - **A link back to a list is `<Link to="/store" back>`.** A link opens its page at the top, even the page the visitor just left, since the runtime restores a page's scroll only on back and forward. `back` steps back when the step before was that page, so the list returns where they left it, and is an ordinary link otherwise. `useGoBack('/store')` does the same for a button. Keep the list's filter in `usePageState`, which stays with the page, so the view comes back too.
71
72
  - **A modal needs `<Overlay>`, not a bigger z-index.** Each layout area's wrapper has its own layer, which makes it a stacking context; a `fixed` dialog inside one paints at its area's place in the stack, under the header/footer. `<Overlay onClose={close}>` renders into `document.body`, contains focus (moves it in, cycles Tab, marks the rest `inert`, returns it), handles Escape, scrim click, scroll lock; a dimmed scrim you override with `className` (`bg-transparent` removes it). `modal={false}` for a toast. Your dialog markup stays yours.
72
73
  - **A reader can open a picture larger.** `components={{ image: EnlargeableImage }}` does it for an image in a page's body, and `Mermaid` does it on its own (`enlarge={false}` turns it off). `<Enlargeable>` goes around a picture a section draws itself. It's offered only when opening shows the picture noticeably larger, and the prerendered page doesn't change.
73
- - **Kit brings no words.** What a reader or a screen reader meets comes from your foundation, so `Media` takes `playLabel`, `Asset` `downloadLabel`, `Disclaimer` `closeLabel` (it has a button at its foot only with one), `Prose` `footnoteBackLabel` and `DataPlaceholder` `label`. Without one it uses what the author wrote, a role or a symbol: a play button with no caption or alt is named `▶`. `<Link>`'s own tooltip is only a social service's name, an address or a number, so a link holding only an icon needs a `title` or `aria-label` from you.
74
+ - **Kit brings no words.** What a reader or a screen reader meets comes from your foundation, so `Media` takes `playLabel`, `Asset` `downloadLabel`, `Disclaimer` `closeLabel` (it has a button at its foot only with one), `Prose` `footnoteBackLabel` and `DataPlaceholder` `label`. Without one it uses what the author wrote, a role or a symbol: a play button with no caption or alt is named `▶`. `<Link>`'s own tooltip is only a social service's name, an address or a number, so a link holding only an icon needs a `title` or `aria-label` from you. Words your own section draws are content: *A section's own words*, below.
74
75
  - **A word wider than its box breaks**, so a long heading can't pan a phone's page (`overflow-wrap: break-word`, in kit's base). What must stay whole in a narrow box says `whitespace-nowrap`: a big numeral, a figure, a number with its unit. Without it, `10 min` in a tight box comes out as `10 mi / n`.
75
76
  - **Kit hooks are SSR-safe.** "document is not defined" → use the hook, don't add guards.
76
77
  - **`cn()` drops an earlier `leading-*` when a `text-<size>` follows**, since Tailwind's size classes set line height too: `cn('leading-[1.1] text-4xl')` → `text-4xl`. Put the size first, or fold the leading into it (`text-[clamp(2rem,5vw,4rem)]/[1.1]`).
@@ -104,7 +105,9 @@ Header.className = 'border-b'
104
105
  Header.as = 'div'
105
106
  ```
106
107
 
107
- **Sticky is a setting.** `sticky: true` in the type's `meta.js` (an author turns it off with `sticky: false`); the runtime makes sticky the box that can stay in view. A body section sticks the same way and stays below the stuck header: the runtime publishes the header's reach as `--uw-sticky-top` (a type's `top` overrides: `sticky: { default: true, top: '4rem' }`). Section links land below the stuck header. A child in `<ChildGrid>` sticks beside its column, and scrolls with the page at one column. A sticky section inside `overflow: hidden` can't stick — use `overflow: clip`. A layout that wraps an area in its own element makes it sticky when `page.isSticky('header')`. `uniweb dev` names a sticky element that cannot move in the console.
108
+ **Sticky is a setting.** `sticky: true` in the type's `meta.js` (an author turns it off with `sticky: false`); the runtime makes sticky the box that can stay in view. A body section sticks the same way and stays below the stuck header: the runtime publishes the header's reach as `--uw-sticky-top` (a type's `top` overrides: `sticky: { default: true, top: '4rem' }`). Section links land below the stuck header. Keep the bar in the flow: a bar made `absolute` or `fixed` leaves the runtime nothing to measure, and section links land under it.
109
+
110
+ **A header over the opening section is a setting too.** `underHeader: true` in a type's `meta.js` (a hero whose picture reaches the top of the window; an author turns it off with `underHeader: false`) has the runtime lay the header over that section when it opens a page: the header's box takes no room, the section starts at the top, and the header keeps its height, stuck if it sticks. The section pads its content by `var(--uw-header-height)`, which the runtime gives it: the header type's `height` (`height: 'var(--header-height)'` in its `meta.js`) on the first paint, then what the browser measures. The header reads `block.getNextBlockInfo()?.underHeader` to paint itself see-through, and its box carries `data-uw-header="over"`. A child in `<ChildGrid>` sticks beside its column, and scrolls with the page at one column. A sticky section inside `overflow: hidden` can't stick — use `overflow: clip`. A layout that wraps an area in its own element makes it sticky when `page.isSticky('header')`. `uniweb dev` names a sticky element that cannot move in the console.
108
111
 
109
112
  ## meta.js in full
110
113
 
@@ -122,6 +125,7 @@ export default {
122
125
  },
123
126
  params: { … }, vars: { … }, data: { … }, presets: { … },
124
127
  context: {}, initialState: {},
128
+ // sticky: true, underHeader: true, height: '4rem', background: 'self', area: 'header' — section settings and placement, below
125
129
  }
126
130
  ```
127
131
 
@@ -212,6 +216,34 @@ Each entry ships its default as a CSS custom property everywhere, in dev and pro
212
216
 
213
217
  Colors, tokens, light and dark, fonts and `styles.css` are in `uniweb guide theme`.
214
218
 
219
+ ## A section's own words
220
+
221
+ The words a section draws itself — a search box's placeholder, an "All" filter, "No results", a menu button's `aria-label` — are content, not params: an author may change them, and a site in several languages translates them with the page. Their home is a tagged data block the type declares with an inline field map. The editor shows its fields, filled in from each `default:`, and `uniweb i18n` and a push translate it like the rest of the page, on a static site and a synced one alike. A param is a choice (a variant, a count) and is never translated.
222
+
223
+ ```js
224
+ // sections/Catalog/labels.js — the type's own words, in the foundation's language
225
+ export default { search: 'Search…', all: 'All', empty: 'No results' }
226
+
227
+ // sections/Catalog/meta.js
228
+ import LABELS from './labels.js'
229
+ export default {
230
+ data: { labels: Object.fromEntries(Object.entries(LABELS).map(([key, text]) => [key, { type: 'string', default: text }])) },
231
+ }
232
+
233
+ // sections/Catalog/index.jsx — what the section wrote, else the type's words
234
+ import LABELS from './labels.js'
235
+ const labels = { ...LABELS, ...content.data.labels }
236
+ ```
237
+
238
+ ````markdown
239
+ ```yaml:labels
240
+ search: Search solutions…
241
+ empty: No solutions found
242
+ ```
243
+ ````
244
+
245
+ The runtime fills no default into a data block (`uniweb guide data`), so the component falls back to the same `labels.js` for a section written without the block. A later release that changes a default changes only the sections that never wrote their own.
246
+
215
247
  ## Composition
216
248
 
217
249
  | Pattern | Authored | Rendered by |
@@ -293,20 +325,20 @@ function Footer({ content }) {
293
325
 
294
326
  ## Cross-block communication
295
327
 
296
- A Header adapting to whether the section below supports a translucent overlay: the section that **owns** the capability declares it, the one that **adapts** reads it, via `getNextBlockInfo()` / `getPrevBlockInfo()` / `page.getFirstBodyBlockInfo()`:
328
+ A Header adapting to the section below it, a light logo over a photograph: the section that **owns** a fact declares it, the one that **adapts** reads it, via `getNextBlockInfo()` / `getPrevBlockInfo()` / `page.getFirstBodyBlockInfo()`. (Whether the header lies over that section at all is `underHeader`, above.)
297
329
 
298
330
  - **`context`** — static, from `meta.js`.
299
331
  - **`state`** — dynamic, via `block.useBlockState()`, initial value from `initialState`.
300
332
 
301
333
  ```js
302
334
  // Hero/meta.js
303
- export default { context: { allowTranslucentTop: true }, initialState: { allowTranslucentTop: true } }
335
+ export default { context: { tone: 'photo' }, initialState: { tone: 'photo' } }
304
336
  ```
305
337
 
306
338
  ```jsx
307
339
  const [state, setState] = block.useBlockState(useState) // Hero
308
340
  const info = block.getNextBlockInfo() // Header
309
- const isFloating = info?.state?.allowTranslucentTop ?? info?.context?.allowTranslucentTop ?? false
341
+ const overPhoto = (info?.state?.tone ?? info?.context?.tone) === 'photo'
310
342
  ```
311
343
 
312
344
  Key names are yours.
@@ -56,7 +56,7 @@ colors:
56
56
  primary: '#3b82f6' # your hex at shade 500
57
57
  secondary: '#64748b'
58
58
  accent: '#8b5cf6'
59
- neutral: stone # named preset: stone, zinc, gray, slate, neutral
59
+ neutral: stone # named preset: that Tailwind family's 500, other shades derived
60
60
  contexts:
61
61
  light: { section: '#fafaf9' }
62
62
  appearance: { default: light, allowToggle: true }
@@ -66,7 +66,7 @@ vars: { radius: 0.75rem }
66
66
  code: dracula # or { light: github-light, dark: github-dark }, or { theme: github-dark, background: '#0D0D0D' }
67
67
  ```
68
68
 
69
- Context override keys match token names (`section:` not `bg:`). In light/medium `--primary` uses shade 600, `--link` 600, `--ring` 500; in dark `--primary` 500, `--link` 400. Buttons use 600 for contrast with white text; for brand-exact buttons set `contexts.light.primary: primary-500` and `primary-hover: primary-600`, and test contrast — bright brands at 500 may fail WCAG 4.5:1. A code block paints its theme's background and foreground before the highlighter loads when both are known.
69
+ Every shade is derived from the color you give, a preset's included, so `neutral: slate` is not Tailwind's slate shade for shade: its 900 is lighter and greyer than `slate-900`. To match a design written in Tailwind's palette, give the color as its shades, `{ 50: '#f8fafc', …, 950: '#020617' }`. Context override keys match token names (`section:` not `bg:`). In light/medium `--primary` uses shade 600, `--link` 600, `--ring` 500; in dark `--primary` 500, `--link` 400. Buttons use 600 for contrast with white text; for brand-exact buttons set `contexts.light.primary: primary-500` and `primary-hover: primary-600`, and test contrast — bright brands at 500 may fail WCAG 4.5:1. A code block paints its theme's background and foreground before the highlighter loads when both are known.
70
70
 
71
71
  ## Fonts
72
72
 
@@ -106,12 +106,13 @@ The build adds preconnect hints, emits `@font-face` + preload, drops unreference
106
106
  @source "./sections/**/*.{js,jsx}";
107
107
  @source "./components/**/*.{js,jsx}";
108
108
  @source "./layouts/**/*.{js,jsx}";
109
+ @source "./utils/**/*.{js,jsx}";
109
110
  @theme { --breakpoint-xs: 30rem; }
110
111
  ```
111
112
 
112
113
  Two more imports are opt-in: `@uniweb/kit/math-tokens.css` lays out equations, and `@uniweb/kit/callout-tokens.css` draws concept blocks such as `md:warning`, which are otherwise plain prose.
113
114
 
114
- **Name every folder that writes classes.** The foundation's own build finds them all, but a site build and `uniweb dev` read only what these lines name, so a class in a folder left out is in one CSS and missing from the other. `uniweb dev`, a site build and `uniweb doctor` (`unread-folder`) give the line to add. `theme-tokens.css` also tells Tailwind to read kit's source, so kit's own classes reach your CSS wherever your package manager put kit; a foundation that skips that import names kit itself, by where kit is (`./node_modules/@uniweb/kit/src/**` under pnpm, `../node_modules/@uniweb/kit/src/**` under npm).
115
+ **Name every folder that writes classes,** or keeps them in a string for code elsewhere to write, such as a map of colours to classes in `utils/`. The foundation's own build finds them all, but a site build and `uniweb dev` read only what these lines name, so a class in a folder left out is in one CSS and missing from the other. `uniweb dev`, a site build and `uniweb doctor` (`unread-folder`) give the line to add. `theme-tokens.css` also tells Tailwind to read kit's source, so kit's own classes reach your CSS wherever your package manager put kit; a foundation that skips that import names kit itself, by where kit is (`./node_modules/@uniweb/kit/src/**` under pnpm, `../node_modules/@uniweb/kit/src/**` under npm).
115
116
 
116
117
  Custom CSS is expected alongside Tailwind — shadow systems, border hierarchies, gradients, glass. Tokens are a floor; add vocabulary that references them so it adapts per context:
117
118
 
@@ -36,7 +36,7 @@ import {
36
36
  FOUNDATION_KIND,
37
37
  EXTENSION_KIND
38
38
  } from '../utils/placement.js'
39
- import { registerWorkspacePackage, updateRootScripts } from '../utils/config.js'
39
+ import { registerWorkspacePackage, addRootScripts } from '../utils/config.js'
40
40
  import { discoverFoundations, discoverSites } from '../utils/discover.js'
41
41
  import { generateStarter, reportStarter, declarationFor } from './starter.js'
42
42
  import {
@@ -510,17 +510,22 @@ async function addFoundation(rootDir, projectName, opts, pm = 'pnpm') {
510
510
  // No glob inference: a pattern is the user's to write.
511
511
  await registerWorkspacePackage(rootDir, relativePath)
512
512
 
513
- // Update root scripts
514
- const sites = await discoverSites(rootDir)
515
- await updateRootScripts(rootDir, sites, pm)
513
+ // A foundation adds no site: at most a `build` the workspace lacks.
514
+ const scriptsAdded = await addRootScripts(rootDir, [], await discoverSites(rootDir), pm)
516
515
 
517
516
  success(
518
517
  `Created foundation ${colors.bright}${packageName}${colors.reset} at ${relativePath}/`
519
518
  )
519
+ reportRootScripts(scriptsAdded)
520
520
  log('')
521
521
  log(`Next: ${colors.cyan}${installCmd(pm)}${colors.reset}`)
522
522
  }
523
523
 
524
+ /** Say which root scripts an `add` wrote, since the root `package.json` is the workspace's. */
525
+ function reportRootScripts(added) {
526
+ if (added.length) log(` ${colors.dim}Root package.json: added ${added.join(', ')}${colors.reset}`)
527
+ }
528
+
524
529
  /**
525
530
  * Stop when `--project` came with a name or a `--path` — it names the folder itself,
526
531
  * so the two disagree. Refused, never ignored (`projectConflictLines`).
@@ -659,12 +664,11 @@ async function addSite(rootDir, projectName, opts, pm = 'pnpm') {
659
664
  // Register the package by exact path, unless a listed pattern covers it already.
660
665
  await registerWorkspacePackage(rootDir, relativePath)
661
666
 
662
- // Update root scripts (discover sites after registration — includes the new one)
667
+ // The new site's scripts, and nothing else (discovered after registration, so it is listed)
663
668
  const sites = await discoverSites(rootDir)
664
- if (!sites.find((s) => s.path === relativePath)) {
665
- sites.push({ name: siteName, path: relativePath })
666
- }
667
- await updateRootScripts(rootDir, sites, pm)
669
+ let added = sites.find((s) => s.path === relativePath)
670
+ if (!added) sites.push((added = { name: siteName, path: relativePath }))
671
+ const scriptsAdded = await addRootScripts(rootDir, [added], sites, pm)
668
672
 
669
673
  if (foundation) {
670
674
  success(
@@ -675,6 +679,7 @@ async function addSite(rootDir, projectName, opts, pm = 'pnpm') {
675
679
  `Created site ${colors.bright}${siteName}${colors.reset} at ${relativePath}/`
676
680
  )
677
681
  }
682
+ reportRootScripts(scriptsAdded)
678
683
  log('')
679
684
  log(
680
685
  `Next: ${colors.cyan}${installCmd(pm)} && uniweb dev ${siteName}${colors.reset}`
@@ -849,8 +854,8 @@ async function addExtension(rootDir, projectName, opts, pm = 'pnpm') {
849
854
  }
850
855
  }
851
856
 
852
- // Update root scripts (an extension adds no site, so the list read above stands)
853
- await updateRootScripts(rootDir, sites, pm)
857
+ // An extension adds no site, so the list read above stands: at most a `build` the workspace lacks.
858
+ const scriptsAdded = await addRootScripts(rootDir, [], sites, pm)
854
859
 
855
860
  let msg = `Created extension '${name}' at ${relativePath}/`
856
861
  if (wiredSite) {
@@ -860,6 +865,7 @@ async function addExtension(rootDir, projectName, opts, pm = 'pnpm') {
860
865
  if (unwiredReason) {
861
866
  log(` ${colors.yellow}⚠ ${unwiredReason}${colors.reset}`)
862
867
  }
868
+ reportRootScripts(scriptsAdded)
863
869
  log('')
864
870
  log(`Next: ${colors.cyan}${installCmd(pm)}${colors.reset}`)
865
871
  }
@@ -983,18 +989,18 @@ async function addProject(rootDir, projectName, opts, pm = 'pnpm') {
983
989
  await registerWorkspacePackage(rootDir, `${name}/src`, { entry: '*/src' })
984
990
  await registerWorkspacePackage(rootDir, `${name}/site`, { entry: '*/site' })
985
991
 
986
- // Update root scripts
992
+ // The new site's scripts, and nothing else
987
993
  const sites = await discoverSites(rootDir)
988
- if (!sites.find((s) => s.path === `${name}/site`)) {
989
- sites.push({ name: sitePkgName, path: `${name}/site` })
990
- }
991
- await updateRootScripts(rootDir, sites, pm)
994
+ let added = sites.find((s) => s.path === `${name}/site`)
995
+ if (!added) sites.push((added = { name: sitePkgName, path: `${name}/site` }))
996
+ const scriptsAdded = await addRootScripts(rootDir, [added], sites, pm)
992
997
 
993
998
  success(`Created project '${name}' at ${name}/`)
994
999
  log(
995
1000
  ` ${colors.dim}Foundation: ${name}/src/ (${foundationPkgName})${colors.reset}`
996
1001
  )
997
1002
  log(` ${colors.dim}Site: ${name}/site/ (${sitePkgName})${colors.reset}`)
1003
+ reportRootScripts(scriptsAdded)
998
1004
  log('')
999
1005
  log(
1000
1006
  `Next: ${colors.cyan}${installCmd(pm)} && uniweb dev ${sitePkgName}${colors.reset}`
@@ -1,12 +1,12 @@
1
1
  {
2
2
  "schemaVersion": 1,
3
- "generatedAt": "2026-11-06T06:10:36.915Z",
3
+ "generatedAt": "2026-11-06T20:34:36.409Z",
4
4
  "packages": {
5
5
  "@uniweb/api": {
6
6
  "version": "1.6.9"
7
7
  },
8
8
  "@uniweb/build": {
9
- "version": "1.17.1"
9
+ "version": "1.18.0"
10
10
  },
11
11
  "@uniweb/content-reader": {
12
12
  "version": "1.5.9"
@@ -15,7 +15,7 @@
15
15
  "version": "1.3.1"
16
16
  },
17
17
  "@uniweb/core": {
18
- "version": "1.6.4"
18
+ "version": "1.6.6"
19
19
  },
20
20
  "@uniweb/frame-bridge": {
21
21
  "version": "1.0.3"
@@ -24,7 +24,7 @@
24
24
  "version": "1.0.8"
25
25
  },
26
26
  "@uniweb/kit": {
27
- "version": "1.7.10"
27
+ "version": "1.7.12"
28
28
  },
29
29
  "@uniweb/loom": {
30
30
  "version": "1.1.3"
@@ -33,16 +33,16 @@
33
33
  "version": "1.2.2"
34
34
  },
35
35
  "@uniweb/projections": {
36
- "version": "1.2.11"
36
+ "version": "1.2.12"
37
37
  },
38
38
  "@uniweb/runtime": {
39
- "version": "1.4.5"
39
+ "version": "1.5.0"
40
40
  },
41
41
  "@uniweb/scene": {
42
42
  "version": "1.0.1"
43
43
  },
44
44
  "@uniweb/schemas": {
45
- "version": "1.6.10"
45
+ "version": "1.6.11"
46
46
  },
47
47
  "@uniweb/scholar": {
48
48
  "version": "1.1.0"
@@ -54,13 +54,13 @@
54
54
  "version": "1.1.2"
55
55
  },
56
56
  "@uniweb/templates": {
57
- "version": "1.2.8"
57
+ "version": "1.2.9"
58
58
  },
59
59
  "@uniweb/theming": {
60
- "version": "1.2.1"
60
+ "version": "1.3.0"
61
61
  },
62
62
  "@uniweb/unipress": {
63
- "version": "1.1.34"
63
+ "version": "1.1.35"
64
64
  }
65
65
  },
66
66
  "templates": {
@@ -380,7 +380,8 @@ export function computeRootScripts(sites, pm = 'pnpm') {
380
380
  }
381
381
 
382
382
  /**
383
- * Update root scripts after adding a new site
383
+ * Regenerate the per-site root scripts from the sites there are now — what `rename` needs, since a
384
+ * script it wrote for the old name runs a site that is gone. `add` adds instead (`addRootScripts`).
384
385
  * @param {string} rootDir - Workspace root directory
385
386
  * @param {Array<{name: string, path: string}>} sites - All sites (including new one)
386
387
  * @param {'pnpm' | 'npm'} [pm='pnpm'] - Package manager
@@ -428,6 +429,54 @@ export async function updateRootScripts(rootDir, sites, pm = 'pnpm') {
428
429
  await writeRootPackageJson(rootDir, pkg)
429
430
  }
430
431
 
432
+ /**
433
+ * Add the root scripts a command's new sites need, and change nothing else — what `uniweb add`
434
+ * does to the workspace's own scripts.
435
+ *
436
+ * A root script is the workspace's. A site added gets its own `dev:<name>` and `preview:<name>`, or
437
+ * `dev` and `preview` when it is the workspace's first, and a workspace with no `build` gets one.
438
+ * A script is not added under a name the workspace already uses, nor for a command it already runs
439
+ * under a name of its own. Nothing there is rewritten, and no script is added for a site that was
440
+ * there before.
441
+ *
442
+ * ⛔ Until 2026-11-06 `add` regenerated every site's scripts (`updateRootScripts`, which `rename`
443
+ * needs) and laid them over the workspace's: in a workspace of seven projects with scripts named
444
+ * its own way, adding one wrote a `dev:` and a `preview:` beside each project's under the CLI's
445
+ * names, and rewrote `preview`. A custom `dev` or `build` was rewritten the same way, by adding a
446
+ * foundation or an extension too, which add no site.
447
+ *
448
+ * @param {string} rootDir - Workspace root directory
449
+ * @param {Array<{name: string, path: string}>} added - The sites this command added, if any
450
+ * @param {Array<{name: string, path: string}>} sites - All sites, the added ones included
451
+ * @param {'pnpm' | 'npm'} [pm='pnpm'] - Package manager (used only for preview)
452
+ * @returns {Promise<string[]>} the names of the scripts added
453
+ */
454
+ export async function addRootScripts(rootDir, added, sites, pm = 'pnpm') {
455
+ const pkg = await readRootPackageJson(rootDir)
456
+ const scripts = { ...(pkg.scripts || {}) }
457
+ const isAdded = (site) => added.some((a) => a.path === site.path)
458
+ const isFirst = !sites.some((site) => !isAdded(site))
459
+
460
+ const wanted = { build: 'uniweb build' }
461
+ added.forEach((site, i) => {
462
+ if (isFirst && i === 0) {
463
+ wanted.dev = 'uniweb dev'
464
+ wanted.preview = filterCmd(pm, site.name, 'preview')
465
+ } else {
466
+ wanted[`dev:${site.name}`] = `uniweb dev ${site.name}`
467
+ wanted[`preview:${site.name}`] = filterCmd(pm, site.name, 'preview')
468
+ }
469
+ })
470
+
471
+ const held = new Set(Object.values(scripts))
472
+ const written = Object.keys(wanted).filter((key) => !(key in scripts) && !held.has(wanted[key]))
473
+ if (!written.length) return []
474
+ for (const key of written) scripts[key] = wanted[key]
475
+ pkg.scripts = scripts
476
+ await writeRootPackageJson(rootDir, pkg)
477
+ return written
478
+ }
479
+
431
480
  /** Every command this CLI has written for the `dev:<site>` / `preview:<site>` script. */
432
481
  function cliSiteScripts(kind, site) {
433
482
  return kind === 'dev'
@@ -4,3 +4,4 @@
4
4
  @source "./sections/**/*.{js,jsx}";
5
5
  @source "./components/**/*.{js,jsx}";
6
6
  @source "./layouts/**/*.{js,jsx}";
7
+ @source "./utils/**/*.{js,jsx}";