uniweb 0.26.1 → 0.26.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.26.1",
+  "version": "0.26.3",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -41,10 +41,10 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
-    "@uniweb/core": "^0.10.1",
-    "@uniweb/kit": "^0.12.3",
-    "@uniweb/semantic-parser": "^1.2.3",
-    "@uniweb/runtime": "^0.12.2"
+    "@uniweb/core": "^0.10.2",
+    "@uniweb/kit": "^0.13.0",
+    "@uniweb/runtime": "^0.12.4",
+    "@uniweb/semantic-parser": "^1.2.3"
   },
   "peerDependencies": {
     "@uniweb/build": "^0.24.5",

package/partials/agents.md

@@ -1983,8 +1983,19 @@ runtime loads once, after consent when a gate is declared, and never in a frame
 or during prerender. That is a **separate path with no connection to the stream
 below** — the vendor measures its own way, and nothing you `track()` reaches it.
 
-**The runtime reports `page_view` on every route change, including the first.**
-That is the only thing it emits on its own — everything else is yours to report:
+**Some events you get for free.** These are reported for you, with no call from
+your foundation and regardless of how it renders:
+
+| event | when |
+|---|---|
+| `page_view` | every route change, including the first |
+| `outbound_click` | a visitor follows a link off the site — the destination **host** only, never the full URL |
+| `section_view` | a section first becomes half-visible, on pages that ask for it (`trackSections`, below) |
+
+⛔ **So don't write your own link-click or scroll-into-view listener for these.**
+A second one double-counts against a collector that already has them.
+
+Everything else is yours to report:
 
 ```jsx
 // In a section type, the block is already in your props.
@@ -2001,12 +2012,79 @@ const { track } = useTracker()
 <button onClick={() => track('brochure_download', { file: 'specs.pdf' })}>…</button>
 ```
 
-The event name is yours — there is no list of permitted names. Three are already
-in use, so reach for these rather than inventing a synonym: **`page_view`** (the
-runtime), **`scroll_depth`** (kit's `useScrollDepth()`, with a `depth` of 25 /
-50 / 75 / 100) and **`video_milestone`** (kit's `<Media>`, with `milestone` and
-`src`). Put the varying part in a **field**, never in the name — four names for
-one event turn a collector's event dimension into a cardinality problem.
+The event name is yours — there is no list of permitted names. Five are already
+in use, so reach for these rather than inventing a synonym: the three automatic
+ones above — **`page_view`**, **`outbound_click`**, **`section_view`** — plus
+**`video_milestone`**, which kit's `<Media>` reports for any video you render
+through it, and **`read_depth`** from `useReadingDepth()` below. Put the
+varying part in a **field**, never in the name — four names for one event turn a
+collector's event dimension into a cardinality problem.
+
+### Choosing what a site sends
+
+By default a site sends `page_view`, `outbound_click` and `section_view`. Narrow
+or widen that with `emit`:
+
+```yaml
+# site.yml — your own collector
+tracking:
+  endpoint: https://collector.example.com/events
+  emit: standard        # minimal | standard | all — or a list of event names
+
+# site.yml — a host that supplies the collector: say what to send, not where
+tracking:
+  emit: minimal
+```
+
+⭐ **`emit` needs no endpoint of its own.** Where a host provides one, the site
+declares only what it wants sent and the address comes from the host. The two
+are read key by key, so naming `emit` alone overrides nothing else the host
+declared. And declaring your own `endpoint:` always wins, so a site pointing at
+its own collector keeps working on any host, including none.
+
+`minimal` is `page_view` alone. `standard` is the default. `all` is a standing
+yes, so an event added in a later framework release is included without you
+changing anything — which is exactly why `standard` exists as well: it is a
+curated set that a release cannot grow behind your back.
+
+⚠️ **`emit` never limits what YOU send.** `block.track()` and `useTracker()` are
+not filtered by it — the registry is open, and your events are yours. It governs
+only the ones the framework emits on its own. A host may narrow the list further
+if it will not store an event, and it can never widen past what you asked for.
+
+### Reading depth in a long section
+
+`section_view` tells you a reader *arrived* at a section. For a long-form one —
+an article, a report, a case study — the question is how far they got:
+
+```jsx
+import { useRef } from 'react'
+import { useReadingDepth } from '@uniweb/kit'
+
+export default function Article({ content, block }) {
+  const ref = useRef(null)
+  useReadingDepth({ ref, block })
+  return <article ref={ref}>{/* … */}</article>
+}
+```
+
+That reports `read_depth` at 25 / 50 / 75 / 100% **of that element**, once each.
+Measuring the element rather than the page is the point: two long sections on
+one page report independently, and adding a section above them changes neither.
+
+⭐ **This one is a hook rather than automatic because only you know a section is
+long-form reading.** The framework cannot tell an essay from a row of logos, so
+it does not guess — and a foundation that never calls this pays nothing for it.
+
+**`trackSections`** is one page's answer on `section_view`, and it overrides the
+site in **both** directions — instrument one page of a site that sends `minimal`,
+or exempt a noisy page of a site that sends `standard`. Say nothing and the
+site's `emit` decides.
+
+```yaml
+# page.yml
+trackSections: true     # or false to exempt this page
+```
 
 ⛔ **Never guard a `track()` call.** A site with **no** tracking destination is
 the default and the majority: the call returns having done nothing, opened no

package/src/backend/foundation-bring-along.js

@@ -241,6 +241,21 @@ async function bringLocalCodeAlong({
     args.includes('--force') ||
     args.includes('--no-verify')
 
+  // `--no-release`: ship the site against the code that is ALREADY released, and do
+  // not release the local changes.
+  //
+  // The intent is ordinary and had no name until 2026-08-19 — a developer edits
+  // content and a component in one sitting, and wants the copy fix live without
+  // shipping a half-finished component. Until now the way to get it was `--yes`,
+  // which means "do not ask me": the behaviour was reachable only as a side effect of
+  // a confirmation-skipper, which is discovery by accident.
+  //
+  // ⛔ It skips the RELEASE, never the REGISTRATION REQUIREMENT. A site referencing a
+  // foundation no deployment can resolve cannot be opened in the app at all, so where
+  // this flag cannot be honoured it REFUSES rather than doing the opposite of what it
+  // says (see the `!reg` branch).
+  const noRelease = args.includes('--no-release')
+
   // The pinned ref to stamp on the pushed site — read at RETURN time (after any
   // release), so it reflects the released version + the scope register derived.
   // null when no scoped ref can be formed (then the site.yml ref is forwarded).
@@ -250,6 +265,15 @@ async function bringLocalCodeAlong({
     return s && v ? `${s}@${v}` : null
   }
 
+  // The ref for a run that releases NOTHING — the version the catalog actually holds,
+  // which is not always the local one. ⚠️ `pinnedRef()` reads the LOCAL package.json,
+  // so on a bumped-but-unreleased foundation it names a version nobody can serve. Any
+  // branch that skips a release must bind to this instead.
+  const registeredRef = (reg) =>
+    local.scopedName && reg?.latest_version
+      ? `${local.scopedName}@${reg.latest_version}`
+      : null
+
   // Dry-run reports the intent WITHOUT touching the network — it must not force
   // a login (the digest read is auth-gated). The real run does the compare.
   if (dryRun) {
@@ -277,6 +301,18 @@ async function bringLocalCodeAlong({
     : null
 
   if (!reg) {
+    // ⛔ Nothing to bind to. Releasing anyway would be the opposite of what was asked,
+    // and shipping anyway would leave a site the app cannot open — so stop and say so.
+    if (noRelease) {
+      say.err(
+        `--no-release, but ${label} has never been released — there is no registered version to bind to.`
+      )
+      say.dim(
+        `A site referencing an unreleased ${kind} cannot be opened in the app, so this cannot be skipped.`
+      )
+      say.dim(`Drop \`--no-release\` to release it now.`)
+      return { released: false, proceed: false, refused: true, ref: null }
+    }
     say.info(`Releasing the ${kind} ${label} (not yet registered)…`)
     return {
       released: releaseFoundation(local, args, cliBin, say),
@@ -299,6 +335,15 @@ async function bringLocalCodeAlong({
 
   // A different version locally → a new version to release.
   if (local.version && local.version !== reg.latest_version) {
+    if (noRelease) {
+      // ⚠️ Bind to the REGISTERED version, not the local one. `pinnedRef()` would
+      // return the bumped-but-unreleased `local.version` here — a ref no deployment
+      // can serve, which is the very failure this flag must not create.
+      say.info(
+        `Keeping the released ${kind} ${reg.latest_version} — local ${local.version} not released (\`--no-release\`).`
+      )
+      return { released: false, proceed: true, ref: registeredRef(reg) }
+    }
     say.info(
       `Releasing the ${kind} ${label} (new version; registered latest is ${reg.latest_version})…`
     )
@@ -313,6 +358,12 @@ async function bringLocalCodeAlong({
   if (!reg.digest) {
     // Degrade: the backend doesn't return the stored digest yet, so we can't
     // be sure the registered version matches local. Offer to re-deliver.
+    if (noRelease) {
+      say.info(
+        `Keeping the released ${kind} ${reg.latest_version} — nothing released (\`--no-release\`).`
+      )
+      return { released: false, proceed: true, ref: registeredRef(reg) }
+    }
     say.warn(
       `Can't verify the registered ${label} matches your local copy (backend returned no digest).`
     )
@@ -338,6 +389,14 @@ async function bringLocalCodeAlong({
   // Case 3 (§4): the code was edited but the version wasn't bumped. The
   // registered version is immutable, so we never silently ship the old code —
   // the deliberate release gate is a version bump (§3.1).
+  // Asked for explicitly: the case this flag exists to name.
+  if (noRelease) {
+    say.info(
+      `Keeping the released ${kind} ${reg.latest_version} — your local changes are not released (\`--no-release\`).`
+    )
+    return { released: false, proceed: true, ref: registeredRef(reg) }
+  }
+
   // ⭐ THREE OUTCOMES, NOT TWO — `--yes` and "no TTY" are not the same answer.
   //
   // They were one condition until 2026-08-19, and conflating them meant the only
@@ -372,7 +431,12 @@ async function bringLocalCodeAlong({
     )
     say.dim(`Nothing was sent. Either release the change, or ship without it:`)
     say.dim(`  • bump the ${kind}'s version in package.json, then re-run \`uniweb ${verb}\``)
-    say.dim(`  • \`uniweb ${verb} --yes\` — sends content bound to the registered ${reg.latest_version}`)
+    // Teach the flag that NAMES this, not `--yes`. Both work, but `--yes` means "do
+    // not ask me" and only does this as a side effect — pointing a stuck user at it
+    // teaches a blunt instrument for a precise job.
+    say.dim(
+      `  • \`uniweb ${verb} --no-release\` — sends content bound to the released ${reg.latest_version}`
+    )
     return { released: false, proceed: false, refused: true, ref: null }
   }
 

package/src/framework-index.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-08-19T04:22:45.477Z",
+  "generatedAt": "2026-08-19T16:10:23.333Z",
   "packages": {
     "@uniweb/build": {
       "version": "0.24.5",
@@ -29,7 +29,7 @@
       "deps": []
     },
     "@uniweb/core": {
-      "version": "0.10.1",
+      "version": "0.10.2",
       "path": "framework/core",
       "deps": [
         "@uniweb/semantic-parser",
@@ -49,7 +49,7 @@
       ]
     },
     "@uniweb/kit": {
-      "version": "0.12.3",
+      "version": "0.13.0",
       "path": "framework/kit",
       "deps": [
         "@uniweb/core",
@@ -76,7 +76,7 @@
       ]
     },
     "@uniweb/runtime": {
-      "version": "0.12.2",
+      "version": "0.12.4",
       "path": "framework/runtime",
       "deps": [
         "@uniweb/core",

package/src/index.js

@@ -1316,6 +1316,11 @@ FOUNDATION on its own use \`uniweb register\` (alias \`uniweb release\`).
 ${colors.bright}Options:${colors.reset}
   --dry-run          Resolve everything; release/sync/POST nothing
   --yes              Skip confirmations (CI); never block on a prompt
+  --no-release       Ship the content against the code already released; release
+                     nothing. For editing content and a component in one sitting
+                     when only the content should go live. Refused if the
+                     foundation has never been released — there is nothing to
+                     bind to, and the app cannot open such a site.
   --no-save          Skip the deploy.yml lastDeploy auto-save
   --no-validate      Skip the content-conformance check (it only warns)
   --org @org         Publish under @org (membership-gated; alias: --as-org). Read
@@ -1753,6 +1758,7 @@ ${colors.bright}Global Options:${colors.reset}
 ${colors.bright}Publish Options:${colors.reset}
   --dry-run          Resolve everything; release/sync/POST nothing
   --yes              Skip confirmations (CI); never block on a prompt
+  --no-release       Ship content against the already-released code; release nothing
   --org @org         Publish under @org (first publish only; then remembered)
   --personal         Own the new site personally, deliberately (first publish only)
   --no-save          Skip the deploy.yml lastDeploy auto-save

package/src/utils/flag-guard.js

@@ -63,14 +63,16 @@ const VERBS = {
     // one of the three flags that skip its prompts. Found by
     // flag-guard-coverage.test.js the moment push gained the import, which is
     // exactly the hand-enumeration failure that test exists to catch.
-    '--no-verify', ...VIA_DEPLOY
+    '--no-verify',
+    // ship content against the already-released code, releasing nothing
+    '--no-release', ...VIA_DEPLOY
   ],
   publish: [
     '--as-org', '--org', '--backend', '--dry-run', '--force', '--foundation',
     '--personal', '--registry', '--token',
     // read in utils/conformance.js, backend/site-sync.js, and
     // backend/foundation-bring-along.js — none appear in publish.js
-    '--no-validate', '--yes', '--no-verify', ...VIA_DEPLOY
+    '--no-validate', '--yes', '--no-verify', '--no-release', ...VIA_DEPLOY
   ],
   pull: [
     '--backend', '--content-only', '--dry-run', '--force', '--merge',
@@ -90,7 +92,9 @@ const VERBS = {
   status: [
     '--backend', '--json', '--registry', '--remote', '--token', '--dry-run',
     '--force', '--no-verify', '--no-validate', '--yes', '--org', '--as-org',
-    ...VIA_DEPLOY
+    // inert here, reachable through the bring-along module status imports for
+    // `resolveLocalFoundation` — listed per the over-approximation note above
+    '--no-release', ...VIA_DEPLOY
   ],
   /**
    * `refresh` = `git pull`, then a DELEGATED `pull --merge`.