uniweb 0.89.2 → 0.89.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.89.2",
+  "version": "0.89.3",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -41,15 +41,15 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
-    "@uniweb/semantic-parser": "^1.5.1",
-    "@uniweb/content-writer": "^0.3.4",
-    "@uniweb/core": "^0.38.1",
-    "@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/content-reader": "^1.2.8",
-    "@uniweb/build": "^0.80.3"
+    "@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
 

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-11T16:47:25.397Z",
+  "generatedAt": "2026-10-11T19:38:43.125Z",
   "packages": {
     "@uniweb/api": {
-      "version": "0.9.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

@@ -10,18 +10,24 @@
  * ## How versions are resolved
  *
  * 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.
+ *    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.
+ *    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`.
@@ -199,17 +205,17 @@ function getFrameworkRoot() {
 
 /**
  * Read the current on-disk version of a specific `@uniweb/*` package by
- * looking up `framework/<last-segment>/package.json`, as a caret range
- * (e.g. `^0.7.11`) — or null if the package isn't on disk (the CLI is
+ * 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 caret, because that is what a published CLI carries: pnpm rewrites
- * its `workspace:^` deps to `^<version>` at publish. So `uniweb update` and
+ * ⭐ 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 `workspace:^` — so a scaffold from a workspace
- * checkout pinned `0.20.0` where a user's got `^0.20.0`.
+ * 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()
@@ -221,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
@@ -260,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.
  */
@@ -270,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
@@ -303,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 {}
   }
@@ -312,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; a `workspace:` spec becomes
- * `^<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) {
@@ -330,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: pnpm rewrites `workspace:^` to
- *      `^<version>`), or a `workspace:` spec read as `^<on-disk 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
@@ -384,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
@@ -397,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()