uniweb 0.89.1 → 0.89.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.89.1",
+  "version": "0.89.3",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -41,17 +41,15 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
-    "@uniweb/core": "^0.38.1",
-    "@uniweb/kit": "^0.20.0",
-    "@uniweb/runtime": "^0.29.6",
-    "@uniweb/semantic-parser": "^1.5.1",
-    "@uniweb/content-writer": "^0.3.4",
-    "@uniweb/schemas": "^0.13.0"
+    "@uniweb/content-writer": "~0.3.4",
+    "@uniweb/semantic-parser": "~1.5.1",
+    "@uniweb/schemas": "~0.13.0",
+    "@uniweb/core": "~0.38.2"
   },
   "peerDependencies": {
-    "@uniweb/semantic-parser": "^1.5.1",
-    "@uniweb/build": "^0.80.3",
-    "@uniweb/content-reader": "^1.2.8"
+    "@uniweb/content-reader": "~1.2.8",
+    "@uniweb/build": "~0.80.4",
+    "@uniweb/semantic-parser": "~1.5.1"
   },
   "peerDependenciesMeta": {
     "@uniweb/build": {

package/partials/agents.md

@@ -1016,6 +1016,8 @@ src/                     # the foundation package (folder name is `src`)
 
 **Discovery:** PascalCase files and folders at the root of `sections/` are auto-discovered. Nested levels require a `meta.js`. Lowercase directories are organizational only. `hidden: true` excludes a component entirely. Everything outside `sections/` and `layouts/` is ordinary React.
 
+**JSX goes in `.jsx` files** (or `.tsx`). Discovery also accepts a `.js` component, but only one without JSX: JSX compiles in no `.js` file, and the build stops on one, naming the file to rename.
+
 **Source root.** The foundation package's source lives at the package root — the `src/` folder *is* the foundation. The build reads `package.json::main` (for new scaffolds, `main: "./_entry.generated.js"`). Older foundations nest source in `foundation/src/` with `main` pointing at `./src/_entry.generated.js`; both work through the same code path.
 
 **Import aliases.** Foundations include subpath imports for shared internals — use them instead of brittle relative paths:
@@ -1032,7 +1034,7 @@ import LessonHeader from '../../components/LessonHeader' // ❌ breaks if you re
 
 Within the same directory, use normal relative imports (`./AIFeedbackCard`).
 
-**Foundation entry (`main.js`).** A single `export default { … }` whose top-level keys are the foundation's identity — `name` (what it registers as, `@org/<name>`) and `description` — and the capabilities it provides — `defaultLayout`, `defaultSection`, `viewTransitions`, `defaultInsets`, `xref`, `outputs`, `handlers` — plus an optional named `vars` export. The capabilities are read at render; the one thing a foundation declares that *isn't* — which host services it supports — lives in `package.json` instead (see [Declaring what your foundation supports](#declaring-what-your-foundation-supports)). Section types and layouts are auto-discovered and merged in by `@uniweb/build`. The build carries into `default.capabilities` in `dist/entry.js` only what a published page reads of your default export — the code it calls (`handlers`, `defaultInsets`, `xref`, `transports`, `outputs`) and its data, lean (`defaultLayout`, `defaultSection`, `viewTransitions`, `scroll`, each var's `default`, `type` and `applyTo`, each `data:` key's schema ref). `name`, `description`, a var's label or description and any key the framework does not read stay out of the published bundle: they are for the editor, which reads them from the foundation's schema. You never write that wrapper. The file is `main.js` — never `main.jsx`, which the build refuses; `main.js` may hold JSX. The one place it matters: when you import your **own** `main.js` from a component (e.g. a download button calling `compileDocument(website, { foundation })`), you get the bare default object — pass it through directly, Press handles both shapes.
+**Foundation entry (`main.js`).** A single `export default { … }` whose top-level keys are the foundation's identity — `name` (what it registers as, `@org/<name>`) and `description` — and the capabilities it provides — `defaultLayout`, `defaultSection`, `viewTransitions`, `defaultInsets`, `xref`, `outputs`, `handlers` — plus an optional named `vars` export. The capabilities are read at render; the one thing a foundation declares that *isn't* — which host services it supports — lives in `package.json` instead (see [Declaring what your foundation supports](#declaring-what-your-foundation-supports)). Section types and layouts are auto-discovered and merged in by `@uniweb/build`. The build carries into `default.capabilities` in `dist/entry.js` only what a published page reads of your default export — the code it calls (`handlers`, `defaultInsets`, `xref`, `transports`, `outputs`) and its data, lean (`defaultLayout`, `defaultSection`, `viewTransitions`, `scroll`, each var's `default`, `type` and `applyTo`, each `data:` key's schema ref). `name`, `description`, a var's label or description and any key the framework does not read stay out of the published bundle: they are for the editor, which reads them from the foundation's schema. You never write that wrapper. The file is `main.js` — never `main.jsx`, which the build refuses — and it is plain JavaScript: a component it declares (in `defaultInsets`, `xref`) lives in a `.jsx` file it imports. The one place it matters: when you import your **own** `main.js` from a component (e.g. a download button calling `compileDocument(website, { foundation })`), you get the bare default object — pass it through directly, Press handles both shapes.
 
 ### Props interface
 
@@ -2580,6 +2582,29 @@ takes them there already signed in. ⛔ **Navigate to it, never `fetch` it**: th
 a redirect carrying a one-time credential no script on the site is to hold. It decides
 what to offer, not what is allowed — on the site the operator acts as a member.
 
+### The links the backend mails
+
+A sign-up's confirmation, a password reset and an invitation to an address with no
+account all arrive as a link to the site's root, a token in the query — `?verify=`,
+`?reset=`, `?offer=` — and the page it lands on finishes the step:
+
+```jsx
+const { step, status, result, error, confirm } = useMailedLink()
+// step: null | 'verify' | 'reset' | 'offer'     status: 'idle' | 'working' | 'done' | 'error'
+```
+
+- `verify` finishes by itself; then the member signs in.
+- `reset` waits for `confirm({ new_password })`, and the hook supplies the token. A
+  password the rule refuses is `error.extensions.reason === 'password_too_short'`, and
+  the same link works again.
+- `offer` waits for a sign-in, then claims by itself. `result` is counts,
+  `{ invitations, grants }`, never names. ⛔ `error.kind === 'absent'` means unknown,
+  revoked or already used, alike: one sentence, no cause.
+
+Render it where the root renders it — a header or a layout is on every page. ⛔ Never
+copy the token anywhere: it is a credential, it stays in the URL until the backend has
+judged it, and then the hook takes it off.
+
 ### A backend on your machine
 
 You do not need a live backend to build against one. In `site.yml`:
@@ -2601,7 +2626,9 @@ supplies on its own origin, so cookies behave exactly as they will in production
 no address of your own for it: under `services:` an address means a backend you run, and
 asks your host to leave its own off. It **enforces** who
 may edit an entry and `append_only`, so a permission you are relying on fails on your
-machine rather than in front of a user. State is in memory; restart to reset.
+machine rather than in front of a user. The mail it would send is printed in the dev
+server's terminal, its link on your site's root — follow it to try your page; seed
+`offers: [{ email }]` to try an invitation. State is in memory; restart to reset.
 
 `uniweb create my-event --template conference` is a worked example of all of this.
 

package/src/commands/update.js

@@ -260,8 +260,8 @@ export function printSurvey(
       } else if (row.status === 'behind') {
         icon = `${colors.yellow}✗${colors.reset}`
         // ⛔ `behind` alone was the whole message, in one colour, for every
-        // distance. In 0.x the minor slot is where our breaking changes live
-        // (`publish.js` derives it from a breaking marker and nothing else), so
+        // distance. The minor slot is where our breaking changes live, in 1.x as in
+        // 0.x (`publish.js` derives it from a breaking marker and nothing else), so
         // `^0.14.1 → ^0.16.0` is two releases a consumer must act on and
         // `^0.15.0 → ^0.15.2` is not — and the table said the same thing about
         // both. Naming the class is the difference between a list and a signal.
@@ -289,7 +289,7 @@ export function printSurvey(
   // artifact is a log. This block names the packages, so "what did that
   // upgrade cross?" is answerable afterwards from the log alone.
   //
-  // ⚖️ It reports; it does not gate. Crossing a 0.x minor IS the ordinary way
+  // ⚖️ It reports; it does not gate. Crossing a minor IS the ordinary way
   // to take a Uniweb update — gating it would gate nearly every real upgrade
   // and make the verb useless. The decision stays the operator's; what changed
   // is that they can now make it knowingly.
@@ -305,7 +305,7 @@ export function printSurvey(
       log(`     ${colors.red}${name}${colors.reset}  ${r.current} → ${r.target}  ${colors.dim}(${r.bump})${colors.reset}`)
     }
     log(
-      `   ${colors.dim}In 0.x the minor slot is where breaking changes go, so these are releases${colors.reset}`
+      `   ${colors.dim}A minor version is where Uniweb's breaking changes go, so these are releases${colors.reset}`
     )
     log(
       `   ${colors.dim}you may need to act on. Read their changelogs before shipping.${colors.reset}`

package/src/framework-index.json

@@ -1,12 +1,12 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-10-11T15:34:07.453Z",
+  "generatedAt": "2026-10-11T19:38:43.125Z",
   "packages": {
     "@uniweb/api": {
-      "version": "0.8.0"
+      "version": "0.9.1"
     },
     "@uniweb/build": {
-      "version": "0.80.3"
+      "version": "0.80.4"
     },
     "@uniweb/content-reader": {
       "version": "1.2.8"
@@ -15,16 +15,16 @@
       "version": "0.3.4"
     },
     "@uniweb/core": {
-      "version": "0.38.1"
+      "version": "0.38.2"
     },
     "@uniweb/frame-bridge": {
       "version": "0.3.2"
     },
     "@uniweb/icons": {
-      "version": "0.4.29"
+      "version": "0.4.30"
     },
     "@uniweb/kit": {
-      "version": "0.20.0"
+      "version": "0.20.1"
     },
     "@uniweb/loom": {
       "version": "0.2.5"
@@ -33,10 +33,10 @@
       "version": "0.4.18"
     },
     "@uniweb/projections": {
-      "version": "0.7.15"
+      "version": "0.7.16"
     },
     "@uniweb/runtime": {
-      "version": "0.29.6"
+      "version": "0.29.7"
     },
     "@uniweb/scene": {
       "version": "0.1.3"
@@ -60,7 +60,7 @@
       "version": "0.2.0"
     },
     "@uniweb/unipress": {
-      "version": "0.10.24"
+      "version": "0.10.25"
     }
   },
   "templates": {

package/src/utils/dep-survey.js

@@ -36,8 +36,8 @@ export function stripVersionRange(spec) {
 /**
  * How far a bump moves, in the terms our versioning actually uses.
  *
- * ⭐ **In 0.x the MINOR slot is the breaking one, and it is the only channel we
- * have.** `scripts/framework/publish.js` derives a package's bump from its own
+ * ⭐ **The MINOR slot is the breaking one — in 1.x as in 0.x** *[ruled
+ * 2026-10-11]*. `scripts/framework/publish.js` derives a package's bump from its own
  * commits: a breaking marker means minor, everything else patch. So
  * `^0.14.1 → ^0.16.0` is two breaking releases and `^0.15.0 → ^0.15.2` is not —
  * and until 2026-09-02 `update` printed both as `behind`, in the same colour,
@@ -64,10 +64,11 @@ export function bumpClass(from, to) {
 /**
  * Is this crossing one a consumer must act on?
  *
- * A major always is. A minor is **when the major is 0**, because that is where
- * our scheme puts breaking changes — and npm agrees, which is the check that
- * makes this more than our own convention: `^0.14.1` admits `0.14.x` and
- * refuses `0.15.0`, so the range itself already treats the slot as a wall.
+ * A major, or a minor — at every major. Our scheme ships a breaking change as a minor
+ * bump, in 1.x as in 0.x *[ruled 2026-10-11]*, and the ranges a project carries (`~`)
+ * treat the minor slot as the wall: `~1.4.0` admits 1.4.x and refuses 1.5.0, as
+ * `^0.14.1` refuses 0.15.0. ⛔ Until then a minor counted only below 1.0, where a caret
+ * refuses it — so this would have stopped warning at the first 1.x minor.
  *
  * @param {string} from
  * @param {string} to
@@ -75,9 +76,7 @@ export function bumpClass(from, to) {
  */
 export function isBreakingBump(from, to) {
   const cls = bumpClass(from, to)
-  if (cls === 'major') return true
-  if (cls !== 'minor') return false
-  return Number(stripVersionRange(to).split('.')[0]) === 0
+  return cls === 'major' || cls === 'minor'
 }
 
 /**

package/src/versions.js

@@ -9,26 +9,33 @@
  *
  * ## How versions are resolved
  *
- * 1. Start from the CLI's own `package.json` dependencies. When the CLI
- *    was installed via npm, pnpm has already resolved every `workspace:*`
- *    spec into a concrete version like `^0.9.1`, so this step is
- *    usually enough.
- * 2. For any dep that is still `workspace:*` (i.e. the CLI is running
- *    *from* the pnpm workspace — local dev, sandbox script, tests), fall
- *    back to reading the real `package.json` of each sibling package
- *    under `framework/<name>/` and using `^<that version>`. This is the
- *    path that keeps local sandboxes and templates aligned with whatever
- *    was last bumped in the monorepo.
- * 3. Scan `framework/*` to catch any additional `@uniweb/*` package that
- *    wasn't explicitly listed as a CLI dep (press, loom, scholar, etc.).
- *    New packages get picked up by the scaffolder automatically.
- *
- * The previous implementation shipped a hardcoded fallback table and
- * nothing kept it in sync with reality — see the audit note in
- * `framework/CLAUDE.md` under "Publishing". Every workspace-based scaffold
- * silently pinned against years-old versions. That table is gone. If this
- * function ever fails to resolve a package, it returns `^0.0.0` rather
- * than a stale best-guess, so the breakage is loud.
+ * 1. Start from the CLI's own `package.json` dependencies. A published CLI
+ *    carries concrete ranges like `~0.9.1` there — pnpm rewrites each
+ *    `workspace:~` spec at publish.
+ * 2. For any dep that is still a `workspace:` spec (the CLI is running
+ *    *from* a workspace checkout — local dev, sandboxes, tests), read the
+ *    `package.json` of the sibling package under `framework/<name>/` and
+ *    use `~<that version>`: the range a published CLI would carry.
+ * 3. Scan `framework/*` for every other `@uniweb/*` package (press, loom,
+ *    scholar, etc.), so a new package reaches the scaffolder automatically.
+ * 4. A published CLI has no `framework/` beside it: it reads every other
+ *    package's version from its bundled `framework-index.json`, refreshed
+ *    when the CLI is published.
+ *
+ * ⭐ EVERY RANGE IS A TILDE. A breaking change ships as a minor bump, in 1.x as in
+ * 0.x *[ruled 2026-10-11]*, and `~1.4.0` admits 1.4.x alone, where `^1.4.0` would
+ * admit 1.5.0. So a project receives fixes and features (patches) by itself, and a
+ * breaking release through `uniweb update`, which says so. Below 1.0 a caret meant
+ * the same, which is why the table wrote one until then.
+ *
+ * ⭐ A version is not a reason to depend on a package. Steps 3 and 4 name
+ * every `@uniweb/*` package, so the CLI's `dependencies` list only what its
+ * code loads — each one is installed with every `npx uniweb`.
+ *
+ * The previous implementation shipped a hardcoded fallback table that
+ * nothing kept in sync, so every scaffold silently pinned years-old
+ * versions. That table is gone. A package none of these steps resolves gets
+ * the `{{version}}` helper's `^0.1.0` (templates/processor.js).
  */
 
 import { readFileSync, readdirSync, statSync } from 'node:fs'
@@ -198,16 +205,17 @@ function getFrameworkRoot() {
 
 /**
  * Read the current on-disk version of a specific `@uniweb/*` package by
- * looking up `framework/<last-segment>/package.json`. Returns the version
- * string verbatim (e.g. `0.7.11`), or null if the package isn't present
- * on disk (i.e. the CLI is running from npm, not from the workspace).
- *
- * Returns the version *exact*, not as a caret range, to match the shape
- * published-CLI direct deps take after pnpm resolves `workspace:*` at
- * publish time. Both modes converge on identical specs in
- * `getResolvedVersions()`, so `uniweb update` and the scaffolder produce
- * the same `package.json` whether the CLI ran from npm or from this
- * monorepo.
+ * looking up `framework/<last-segment>/package.json`, as a tilde range
+ * (e.g. `~0.7.11`) — or null if the package isn't on disk (the CLI is
+ * running from npm, not from a workspace checkout).
+ *
+ * ⭐ A tilde, because that is what a published CLI carries: pnpm rewrites
+ * its `workspace:~` deps to `~<version>` at publish. So `uniweb update` and
+ * the scaffolder write the same `package.json` whether the CLI ran from npm
+ * or from a workspace. ⛔ This returned the version exact until 2026-10-11:
+ * right while the deps were `workspace:*`, which pnpm publishes exact, and
+ * wrong once they became a range — a scaffold from a workspace checkout
+ * pinned `0.20.0` where a user's got `^0.20.0`.
  */
 function readWorkspaceVersion(packageName) {
   const root = getFrameworkRoot()
@@ -219,7 +227,7 @@ function readWorkspaceVersion(packageName) {
   try {
     const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'))
     if (pkg.name === packageName && pkg.version) {
-      return pkg.version
+      return `~${pkg.version}`
     }
   } catch {}
   return null
@@ -258,7 +266,7 @@ export function loadFrameworkIndex() {
 
 /**
  * Pull `@uniweb/*` package versions out of the framework index's
- * `packages` field and format them as caret ranges. Used as the
+ * `packages` field and format them as tilde ranges. Used as the
  * published-CLI fallback source after the CLI's own deps and the live
  * workspace walk both come up empty.
  */
@@ -268,7 +276,7 @@ function readIndexPackages() {
   const result = {}
   for (const [name, entry] of Object.entries(index.packages)) {
     if (entry && entry.version) {
-      result[name] = `^${entry.version}`
+      result[name] = `~${entry.version}`
     }
   }
   return result
@@ -301,7 +309,7 @@ function discoverWorkspacePackages() {
     try {
       const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'))
       if (pkg.name && pkg.version && pkg.name.startsWith('@uniweb/')) {
-        found[pkg.name] = `^${pkg.version}`
+        found[pkg.name] = `~${pkg.version}`
       }
     } catch {}
   }
@@ -310,8 +318,8 @@ function discoverWorkspacePackages() {
 
 /**
  * Resolve a single version spec to something npm can install. A concrete
- * spec like `^0.9.0` passes through untouched; `workspace:*` is replaced
- * by the on-disk version of the named package; anything still unresolved
+ * spec like `~0.9.0` passes through untouched; a `workspace:` spec becomes
+ * `~<on-disk version>` of the named package; anything still unresolved
  * returns null so the caller can fall back.
  */
 function resolveVersionSpec(spec, packageName) {
@@ -328,8 +336,8 @@ function resolveVersionSpec(spec, packageName) {
  * Priority (highest first):
  *
  *   1. A concrete version spec already in the CLI's own `package.json`
- *      (the state after an npm publish: `workspace:*` is resolved by
- *      pnpm to a real version).
+ *      (the state after an npm publish: pnpm rewrites `workspace:~` to
+ *      `~<version>`), or a `workspace:` spec read as `~<on-disk version>`.
  *   2. Live workspace walk — every `@uniweb/*` package found under
  *      `framework/*` at CLI invocation time. This is the path that
  *      matters for local dev: a freshly-added package becomes
@@ -382,10 +390,10 @@ export function getResolvedVersions() {
     if (!result[name]) result[name] = version
   }
 
-  // CLI itself. Caret on the current version — templates referencing
-  // `{{version "uniweb"}}` pick up whatever patch/minor ships in the
-  // same publish cycle as the template.
-  result['uniweb'] = `^${pkg.version}`
+  // CLI itself. Tilde on the current version, like every other entry: a
+  // project takes the CLI's patches by itself, and a minor — breaking —
+  // through `uniweb update`.
+  result['uniweb'] = `~${pkg.version}`
 
   resolvedVersions = result
   return resolvedVersions
@@ -395,7 +403,7 @@ export function getResolvedVersions() {
  * Get a specific package version
  *
  * @param {string} packageName - Package name (e.g., "@uniweb/build")
- * @returns {string} Version spec (e.g., "^0.1.4")
+ * @returns {string} Version spec (e.g., "~0.1.4")
  */
 export function getVersion(packageName) {
   const versions = getResolvedVersions()