uniweb 0.14.28 → 0.14.30

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.14.28",
+  "version": "0.14.30",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -42,13 +42,13 @@
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
     "@uniweb/core": "0.8.2",
-    "@uniweb/runtime": "0.9.7",
-    "@uniweb/kit": "0.10.20"
+    "@uniweb/runtime": "0.9.9",
+    "@uniweb/kit": "0.10.21"
   },
   "peerDependencies": {
-    "@uniweb/semantic-parser": "1.2.1",
+    "@uniweb/build": "0.16.20",
     "@uniweb/content-reader": "1.2.2",
-    "@uniweb/build": "0.16.18"
+    "@uniweb/semantic-parser": "1.2.1"
   },
   "peerDependenciesMeta": {
     "@uniweb/build": {

package/partials/agents.md

@@ -892,7 +892,7 @@ Nothing to install — the import brings the plugin with it. **Skip the import a
 **Layout helpers:** `useGridLayout(columns, { gap })`, `useAccordion({ multiple, defaultOpen })`
 **Theming data:** `useThemeData()`, `useColorContext(block)`
 **Data fetching:** `useFetched`, `useCacheEntry`, `useEntityDetail`
-**Forms:** `useFormSubmit`, `submitForm`, `resolveSubmitTarget` — see *Forms* below
+**Forms:** `useFormValues` (an author-designed form's state), `useFormSubmit`, `submitForm`, `resolveSubmitTarget` — see *Forms* below
 **Utilities:** `cn()`, `SafeHtml`, `SocialIcon`, `filterSocialLinks(links)`, `getSocialPlatform(url)`, `getLocaleLabel(locale)`
 **Other styled:** `Code`, `Alert`, `Table`, `Details`, `Divider`, `Disclaimer`
 
@@ -1819,6 +1819,33 @@ fields, declare `fileSlots` and the endpoint replies with `uploadUrls` — the
 bytes never ride inside the JSON. `submitForm()` / `resolveSubmitTarget(website)`
 are the same behaviour without React.
 
+**Rendering a form the AUTHOR designed** — a `yaml:form` block at
+`content.data.form` — is the inverse of every other component: you don't declare
+the fields, you receive them and draw whatever you're given. `useFormValues` owns
+the part that's identical in every such component, so you write only the controls:
+
+```jsx
+import { useFormValues, useFormSubmit, valueAt } from '@uniweb/kit'
+
+const { controls, values, setValue, missing, formData, files } =
+  useFormValues(content.data.form)
+const { submit, canSubmit, status } = useFormSubmit({ block })
+
+{controls.map((c) => (
+  <MyControl key={c.path} control={c}          // branch on c.type — your design
+             value={valueAt(values, c.path)}
+             onChange={(v) => setValue(c.path, v)} />
+))}
+<button disabled={!canSubmit || missing.length > 0} onClick={() => submit(formData, { files })}>
+```
+
+It seeds each control's `default`, tracks edits, and reports `missing` — the
+`required` controls still empty — without enforcing anything, the same line
+`canSubmit` draws. **Submit `formData`, not `values`:** they differ because a
+`File` inside `formData` would be JSON-serialized to `{}`, so file controls are
+omitted from it and ride in `files` instead, each tagged with the control it came
+from. `values` keeps the `File` so your input can show its selection.
+
 Full reference: `development/receiving-form-submissions.md`.
 
 <!-- template:loom -->
@@ -1951,13 +1978,17 @@ Platform-specific configuration that doesn't belong in npm-standard fields. All
 |---|---|---|---|
 | `id` | `uniweb register` | bare segment of a scoped `name` | The foundation's registered id — the bare name in `@org/<id>`. Decoupled from `package.json::name` (a workspace concern), so renaming on the registry doesn't ripple through site dependencies. |
 | `namespace` | `uniweb register` | none | Legacy explicit org-namespace override; equivalent to a scoped `package.json::name`. Rarely needed. |
-| `runtimePolicy` | `dist/runtime-pin.json` | `"auto-minor"` | How sites using this foundation receive runtime updates. |
+| `runtimePolicy` | `dist/runtime-pin.json` | unset | Declares how far past the recorded runtime version a host may move a site. |
+
+**Runtime policy** (foundation authors only — sites don't set this). At build time a foundation records the `@uniweb/runtime` version it linked against into `dist/runtime-pin.json`, and carries `uniweb.runtimePolicy` alongside it when you set one: `exact` (stay on the recorded version), `auto-patch` (within `MAJOR.MINOR.x`), `auto-minor` (within `MAJOR.x.y`). Leaving it unset is the normal case and the one to prefer — the runtime is backwards-compatible at the minor level by convention. Set `exact` only if you depend on undocumented runtime internals or have audited against one release. Site owners cannot override your choice.
+
+⚠️ **The pin is a compatibility FLOOR, not a selector.** It records what your build binds to; it does not choose the runtime a site runs, and it cannot: a site loads your foundation **plus any extensions**, each emitting its own pin, while a site has exactly **one** runtime. Pins are plural, the choice is singular. The runtime a site runs is selected by `site.yml::runtime`.
 
-**Runtime policy** (foundation authors only — sites don't set this). At build time a foundation pins the `@uniweb/runtime` version it built against into `dist/runtime-pin.json`, alongside a policy controlling how that version moves forward on already-published sites: `exact` (stay put), `auto-patch` (within `MAJOR.MINOR.x`), `auto-minor` (within `MAJOR.x.y`, the default). Most foundations should leave it unset — the runtime is backwards-compatible at the minor level by convention, so `auto-minor` lets sites pick up fixes without a foundation rebuild. Set `exact` only if you depend on undocumented runtime internals or have audited against one release. Site owners cannot override your choice.
+`uniweb register` reads the pin and sends it with your foundation, so the floor you built against travels with it. Its use is **validation** — checking a site's chosen runtime against the floors of *every* foundation that site loads, which only something holding all of them can do. **That check is not implemented anywhere yet**, so today the floor is stated and carried but not enforced. Set `runtimePolicy` to declare your intent for when it is; don't design around it having an effect now.
 
 **Why this is yours and not the site's.** A published site ships **no JS** — content, config, data and assets only. Your foundation is the only part that contains code linking against the runtime, and that link is wider than it looks: a foundation externalizes `react`, `react-dom`, `react-dom/server`, both JSX runtimes and `@uniweb/core`, all supplied by the runtime at load time. So a foundation built against a runtime is bound to *that* React and *that* core API. The general rule, which also explains why the reverse holds: **each policy is declared by whoever's code binds to the thing being updated** — you declare the runtime policy because your code links against the runtime; the site declares its foundation policy because its content binds to your section types.
 
-`@uniweb/runtime` arrives **transitively** through `@uniweb/build`, so your foundation pins a runtime version without declaring one — that's intentional. **Don't add `@uniweb/runtime` to your foundation's dependencies**; to bump the pinned version, bump `@uniweb/build`. If the pin is missing or malformed, the platform serves the foundation through its legacy compatibility path — sites still work, they just don't participate in runtime propagation.
+`@uniweb/runtime` arrives **transitively** through `@uniweb/build`, so your foundation pins a runtime version without declaring one — that's intentional. **Don't add `@uniweb/runtime` to your foundation's dependencies**; to bump the pinned version, bump `@uniweb/build`. If `@uniweb/runtime` isn't resolvable at build time the pin is simply not emitted, and the build still succeeds — nothing in the toolchain requires it.
 
 ### Localization
 

package/src/commands/register.js

@@ -69,7 +69,8 @@ import {
 import { readRegistryAuth } from '../utils/registry-auth.js'
 import {
   collectDistFiles,
-  computeFoundationDigest
+  computeFoundationDigest,
+  readRuntimePin
 } from '../utils/code-upload.js'
 import { deriveScope } from '../utils/registry-orgs.js'
 import { BackendClient } from '../backend/client.js'
@@ -410,6 +411,17 @@ async function runRegister(args = []) {
     ? null
     : computeFoundationDigest(join(targetDir, 'dist'))
 
+  // Compatibility floor (foundation path only) — the @uniweb/runtime version
+  // this build linked against. Rides in info.runtime beside info.digest.
+  //
+  // Until this shipped, `dist/runtime-pin.json` was written by the build and
+  // read by NOTHING, so a floor a foundation stated could never reach anyone
+  // able to act on it. It cannot be acted on here either: a site's floor is
+  // max() over its primary foundation AND its extensions, and this command
+  // publishes one foundation without sight of the others. So the producer
+  // states its own floor and whoever resolves a whole site does the arithmetic.
+  const runtime = standalone ? null : readRuntimePin(join(targetDir, 'dist'))
+
   const exporter = { tool: 'uniweb', version: cliVersion(), instance: 'build' }
   let doc
   try {
@@ -420,7 +432,8 @@ async function runRegister(args = []) {
           foundationDir: targetDir,
           scope,
           exporter,
-          digest
+          digest,
+          runtime
         })
   } catch (err) {
     error(`Could not assemble the .uwx: ${err.message}`)
@@ -447,6 +460,7 @@ async function runRegister(args = []) {
   if (scope)
     log(`  ${colors.dim}scope: ${scope} (${scopeSource})${colors.reset}`)
   if (digest) log(`  ${colors.dim}digest: ${digest}${colors.reset}`)
+  if (runtime) log(`  ${colors.dim}runtime floor: ${runtime}${colors.reset}`)
 
   // Preview paths — no submit, no auth needed.
   if (output) {

package/src/commands/runtime.js

@@ -3,20 +3,23 @@
  * can serve the runtime version. The runtime is a SYSTEM artifact: registering it
  * requires **@std membership** (a non-@std bearer 403s).
  *
- * A foundation emits `dist/runtime-pin.json`, but NOTHING READS IT — not this CLI,
- * not the backend, not the edge (verified across all three lanes 2026-08-04,
- * channel `platform-backend-framework-8de5`). An earlier version of this comment
- * claimed `uniweb register` of a foundation fails when its pinned version isn't
- * registered. That was never true, and it propagated into a kb doc before anyone
- * checked it against `commands/register.js` three files away.
+ * A foundation emits `dist/runtime-pin.json`. `uniweb register` now reads it and
+ * ships it as the foundation's `info.runtime` — but **NOTHING ENFORCES IT** in
+ * any lane. An earlier version of this comment claimed `uniweb register` of a
+ * foundation fails when its pinned version isn't registered. That was never
+ * true, and it propagated into internal notes AND into four public
+ * documentation surfaces before anyone checked it against `commands/register.js`
+ * three files away.
  *
  * The pin is a **compatibility floor**, not a selector: a site loads a primary
  * foundation plus N extensions, each emitting its own pin, and a site has exactly
  * one runtime — so pins are plural and the selector must be singular. The selector
  * is `site.yml::runtime` (see commands/publish.js), which the backend stamps into
- * the site's meta at publish. The pin's designed use is publish-time VALIDATION
- * (is the selected runtime inside every foundation's compatible interval?), which
- * is producer-side and not yet implemented.
+ * the site's meta at publish. The pin's use is VALIDATION — is the selected
+ * runtime at or above max() of every loaded foundation's floor? — and it belongs
+ * wherever all of a site's foundations are held. The producer publishes one
+ * foundation at a time and cannot see the others, so it STATES its floor and
+ * something holding the whole set does the arithmetic.
  *
  * Contract AGREED with the backend (2026-06-14): `POST /dev/runtime`, @std-gated,
  * manifest-last. Wire + the two-half artifact set (SPA + ssr-edge isolate, the

package/src/framework-index.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-08-05T14:30:40.743Z",
+  "generatedAt": "2026-08-05T19:38:23.202Z",
   "packages": {
     "@uniweb/build": {
-      "version": "0.16.18",
+      "version": "0.16.20",
       "path": "framework/build",
       "deps": [
         "@uniweb/content-reader",
@@ -46,7 +46,7 @@
       "deps": []
     },
     "@uniweb/kit": {
-      "version": "0.10.20",
+      "version": "0.10.21",
       "path": "framework/kit",
       "deps": [
         "@uniweb/core",
@@ -73,7 +73,7 @@
       ]
     },
     "@uniweb/runtime": {
-      "version": "0.9.7",
+      "version": "0.9.9",
       "path": "framework/runtime",
       "deps": [
         "@uniweb/core",
@@ -86,7 +86,7 @@
       "deps": []
     },
     "@uniweb/schemas": {
-      "version": "0.2.6",
+      "version": "0.2.8",
       "path": "framework/schemas",
       "deps": []
     },
@@ -111,7 +111,7 @@
       "deps": []
     },
     "@uniweb/unipress": {
-      "version": "0.6.16",
+      "version": "0.6.18",
       "path": "framework/unipress",
       "deps": [
         "@uniweb/build",

package/src/utils/code-upload.js

@@ -142,6 +142,40 @@ export function uploadOrder(files) {
  * @param {string} distDir - the built `dist/` directory
  * @returns {string|null} `sha256:<hex>` or null when there's nothing to hash
  */
+/**
+ * The `@uniweb/runtime` version a built foundation linked against, from
+ * `dist/runtime-pin.json`.
+ *
+ * ⭐ **This is the ONLY reader of that file, and it exists so the pin can reach
+ * a party that can act on it.** The pin is a compatibility FLOOR — the lowest
+ * runtime this build is known to work against. A site loads a primary
+ * foundation plus N extensions, so a site's floor is `max()` over all of their
+ * pins, and the producer publishing one foundation cannot compute that: it does
+ * not hold the others. Whoever holds every foundation a site loads can.
+ *
+ * So the split is: the producer STATES its own floor, and a party that resolves
+ * a whole site CHECKS them. Riding it in the identity card next to `digest` is
+ * what makes the first half possible — and until it did, a consumer storing the
+ * value had no way to ever receive one.
+ *
+ * Returns null when the pin is absent (the build could not resolve
+ * `@uniweb/runtime`) or malformed. ⚠️ **null means UNKNOWN, not unconstrained** —
+ * a floor that is absent cannot be proven satisfied by anything, and a
+ * consumer's `max()` that skips nulls silently computes a floor over only the
+ * foundations that happened to declare one.
+ *
+ * @param {string} distDir - the built `dist/` directory
+ * @returns {string|null} e.g. `'0.9.8'`
+ */
+export function readRuntimePin(distDir) {
+  try {
+    const pin = JSON.parse(readFileSync(join(distDir, 'runtime-pin.json'), 'utf8'))
+    return typeof pin?.runtime === 'string' && pin.runtime ? pin.runtime : null
+  } catch {
+    return null // absent or unparseable — both are "unknown"
+  }
+}
+
 export function computeFoundationDigest(distDir) {
   const hashes = collectDistFiles(distDir).map((f) => f.sha256)
   // The schema rides in the register `.uwx`, not the code-upload set, so fold