uniweb 0.16.3 → 0.16.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.16.3",
+  "version": "0.16.5",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -41,14 +41,14 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
-    "@uniweb/core": "0.8.3",
-    "@uniweb/runtime": "0.11.3",
-    "@uniweb/kit": "0.11.1"
+    "@uniweb/core": "^0.8.5",
+    "@uniweb/kit": "^0.11.3",
+    "@uniweb/runtime": "^0.11.5"
   },
   "peerDependencies": {
-    "@uniweb/build": "0.18.3",
-    "@uniweb/semantic-parser": "1.2.1",
-    "@uniweb/content-reader": "1.2.2"
+    "@uniweb/build": "^0.18.5",
+    "@uniweb/content-reader": "^1.2.2",
+    "@uniweb/semantic-parser": "^1.2.2"
   },
   "peerDependenciesMeta": {
     "@uniweb/build": {

package/partials/agents.md

@@ -1986,13 +1986,21 @@ Platform-specific configuration that doesn't belong in npm-standard fields. All
 | `namespace` | `uniweb register` | none | Legacy explicit org-namespace override; equivalent to a scoped `package.json::name`. Rarely needed. |
 | `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.
+**Runtime updates — handled for you.** Your foundation's code links against the runtime: it externalizes `react`, `react-dom`, `react-dom/server`, both JSX runtimes and `@uniweb/core`, and the runtime supplies all of them at load time. So a build is bound to *that* React and *that* core API.
 
-⚠️ **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`.
+You don't declare anything for this. At build time your foundation records the `@uniweb/runtime` version it actually linked against (read from `node_modules`, not chosen) into `dist/runtime-pin.json`, and `uniweb register` sends it with your foundation, so the version you built against travels with it. **Whether two runtime versions are compatible is our determination, not a setting** — you have no way to know whether we changed anything your code can reach, so we don't ask you to guess.
 
-`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.
+⚠️ **Nothing acts on the recorded version yet** — today it is stated and carried, not enforced. Don't design around it having an effect.
 
-**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.
+**The escape hatch,** for the one thing only you can know: if your foundation reaches into undocumented runtime internals, or you have audited it against exactly one runtime build and want no movement at all, set
+
+```json
+{ "uniweb": { "runtimePolicy": "exact" } }
+```
+
+That freezes sites using your foundation on the recorded version. Only reach for it if one of those two things is actually true — a frozen foundation stops receiving runtime fixes, including security ones. Sites cannot override your choice.
+
+> Older releases documented `auto-patch` and `auto-minor` here as well. They asked you to pick a compatibility rule out of our version numbers, which was never something you were in a position to evaluate — that determination is ours. Both values are still accepted so existing foundations keep working; neither is worth setting.
 
 `@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.
 

package/src/backend/site-sync.js

@@ -18,6 +18,7 @@ import { hasUncommittedContent } from '../utils/git.js'
 import {
   backfillEntityUuids,
   writeSiteEntityUuid,
+  writeSiteOrg,
   emitSyncPackages,
   readZip,
   diffSiteUnits,
@@ -390,6 +391,59 @@ export function writeItemUuids(siteDir, map) {
   updateSyncCache(siteDir, { itemUuids: map })
 }
 
+/**
+ * The org this site was created under, as `@handle`, or null.
+ *
+ * Read back from `site.yml::$org` (stored bare — see `writeSiteOrg`) and re-dressed
+ * with the `@` the CLI and the wire both use. Callers pass it as `--as-org`'s default
+ * so an org named once, at create, does not have to be re-typed on every later push.
+ *
+ * Deliberately NOT a fallback for the flag: an explicit `--as-org` always wins and
+ * rides verbatim, so this can only add a value where the CLI previously sent none.
+ *
+ * @param {string} siteDir
+ * @returns {string|null}
+ */
+export function readSiteOrg(siteDir) {
+  try {
+    const y = yaml.load(readFileSync(join(siteDir, 'site.yml'), 'utf8'))
+    const h = y && typeof y === 'object' ? y.$org : null
+    return typeof h === 'string' && h.trim()
+      ? `@${h.trim().replace(/^@/, '')}`
+      : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Record the org a just-minted site was created under, if one was named.
+ *
+ * Only what we were TOLD is recorded — when no `--as-org` was passed the backend
+ * chose the owner and its create response carries no org, so there is nothing to
+ * write and guessing one would be worse than the gap. Returns the display form for
+ * the caller's "here's what resolved" line, or null when nothing was recorded.
+ *
+ * @param {string} siteDir
+ * @param {string|null|undefined} asOrg - the `--as-org` value, `@handle` or bare
+ * @returns {string|null}
+ */
+function recordSiteOrg(siteDir, asOrg) {
+  const handle = String(asOrg || '')
+    .replace(/^@/, '')
+    .replace(/\/.*$/, '')
+    .trim()
+  if (!handle) return null
+  try {
+    writeSiteOrg(siteDir, handle)
+    return `@${handle}`
+  } catch {
+    // The uuid is the load-bearing back-fill; losing the org note must never
+    // fail a push that already succeeded on the backend.
+    return null
+  }
+}
+
 /**
  * Guarantee the site EXISTS on the backend before anything is uploaded against it.
  *
@@ -429,7 +483,7 @@ export async function ensureSiteExists({
     /* unreadable site.yml — treat as un-synced and let the create decide */
   }
   if (typeof siteYml.$uuid === 'string') {
-    return { uuid: siteYml.$uuid, created: false }
+    return { uuid: siteYml.$uuid, created: false, org: readSiteOrg(siteDir) }
   }
 
   // Both are required by the create. Catching it here turns a 400 into a sentence
@@ -484,8 +538,16 @@ export async function ensureSiteExists({
   // this point cannot leave a cache pointing at a different site with no way to
   // detect it.
   updateSyncCache(siteDir, { siteUuid: minted })
-  note?.(`Created the site on the backend (recorded $uuid in site.yml).`)
-  return { uuid: minted, created: true }
+  // Ownership is decided HERE and nowhere else — this is the one call that reads
+  // `as_org`. Recording it beside the uuid is what makes the answer readable later,
+  // and naming it now is the "show what resolved" half of the ask-once pattern.
+  const org = recordSiteOrg(siteDir, asOrg)
+  note?.(
+    org
+      ? `Created the site on the backend under ${org} (recorded $uuid + $org in site.yml).`
+      : `Created the site on the backend (recorded $uuid in site.yml).`
+  )
+  return { uuid: minted, created: true, org }
 }
 
 /**
@@ -838,6 +900,12 @@ export async function pushSyncPackages({
       updateSyncCache(siteDir, { siteUuid: minted })
       boundSiteUuid = minted
       wrote.push('recorded site $uuid in site.yml')
+      // The OTHER create path (a media-less push never reaches `ensureSiteExists`,
+      // which is gated on the site having local media). Both mint a site, so both
+      // owe the same record — recording it in only one place would make `$org`
+      // present or absent depending on whether the site happens to have images.
+      const createdOrg = recordSiteOrg(siteDir, asOrg)
+      if (createdOrg) wrote.push(`recorded site $org (${createdOrg}) in site.yml`)
       const createdFinalized = extractFinalized(payload)
       harvest(createdFinalized)
       siteFinalizedDoc = createdFinalized?.[0]?.document || null

package/src/commands/clone.js

@@ -56,6 +56,7 @@ import { detectWorkspacePm, installCmd } from '../utils/pm.js'
 import { BackendClient } from '../backend/client.js'
 import { isNonInteractive, getCliPrefix } from '../utils/interactive.js'
 import { extractFoundationRef } from '../utils/site-content-refs.js'
+import { readUwxDocuments } from '../utils/uwx-read.js'
 
 const colors = {
   reset: '\x1b[0m',
@@ -189,11 +190,19 @@ export async function clone(args = [], deps = {}) {
     command: 'Cloning'
   })
 
-  // 1. GET the site-content document (no @uniweb/build needed for a read).
+  // 1. GET the site-content document.
+  //
+  // ⛔ The body is a `.uwx` ZIP, not JSON — `application/vnd.uniweb.exchange.
+  // entity+zip`, on `content` and `folder` pulls alike. This used to call
+  // `res.json()`, which failed on the ZIP magic and reported *"Could not reach
+  // the backend: Unexpected token 'P'"* — blaming the network for a body we had
+  // received intact and mis-read. Decode with the local reader: this command runs
+  // before a project exists, so `@uniweb/build/uwx`'s `readZip` is out of reach
+  // (see `utils/uwx-read.js`).
   info(
     `Reading site ${colors.bright}${siteUuid}${colors.reset} from ${colors.dim}${client.origin}${colors.reset} …`
   )
-  let payload
+  let documents
   try {
     const res = await client.pullSiteContent(siteUuid)
     if (res.status === 404) {
@@ -206,13 +215,14 @@ export async function clone(args = [], deps = {}) {
         note('Run `uniweb login` first (or pass --token <bearer>).')
       return { exitCode: 1 }
     }
-    payload = await res.json()
+    documents = readUwxDocuments(Buffer.from(await res.arrayBuffer()))
   } catch (err) {
     error(`Could not reach the backend at ${client.origin}: ${err.message}`)
     return { exitCode: 1 }
   }
 
-  const document = extractDocument(payload)
+  const document =
+    documents.map(extractDocument).find(Boolean) || null
   if (!document) {
     error('The site-content response carried no recognizable document.')
     return { exitCode: 1 }

package/src/commands/publish.js

@@ -28,6 +28,12 @@
  *   uniweb publish --dry-run       Resolve everything; POST nothing
  *   uniweb publish --yes           Skip confirmations (CI); never block on a prompt
  *   uniweb publish --force         Overwrite upstream app-side edits (drop the push gate)
+ *   uniweb publish --as-org @org   Publish under @org (membership-gated). Only the
+ *                                  FIRST publish of a site reads it — that create is
+ *                                  what decides which org owns the site and whose
+ *                                  storage its assets are charged to. It is then
+ *                                  recorded as `site.yml::$org` and replayed, so it
+ *                                  never has to be re-typed.
  *   uniweb publish --no-save       Skip the deploy.yml lastDeploy auto-save
  *   uniweb publish --backend <url> Override the backend origin
  *   uniweb publish --token <bearer> Auth bearer (skips `uniweb login`)
@@ -66,7 +72,8 @@ import {
   ensureItemUuids,
   ensureSiteExists,
   clearRemoteSyncStateIfUnbound,
-  pushSyncPackages
+  pushSyncPackages,
+  readSiteOrg
 } from '../backend/site-sync.js'
 import { uploadDataBundle } from '../backend/data-bundle.js'
 import { uploadSiteMedia, describeAssetRefusal } from '../backend/site-media.js'
@@ -167,11 +174,16 @@ async function persistLastDeploy(siteDir, opts) {
 export async function publish(args = []) {
   const dryRun = args.includes('--dry-run')
   const noSave = args.includes('--no-save')
-  const asOrg = readFlagValue(args, '--as-org')
   const foundationDir = readFlagValue(args, '--foundation') // optional local foundation for Model schemas
 
   const siteDir = await resolveSiteDir(args, 'publish')
 
+  // The acting org: the flag verbatim, else the one this site was CREATED under
+  // (`site.yml::$org`). Only the create reads `as_org`, so replaying the recorded
+  // handle reasserts existing ownership rather than choosing new ownership. Absent
+  // both, no `as_org` is sent — unchanged from before the record existed.
+  const asOrg = readFlagValue(args, '--as-org') || readSiteOrg(siteDir)
+
   // Advisory only — warns and ships. See utils/conformance.js for why this
   // is not a gate.
   await warnIfContentDoesNotConform(siteDir, { args })
@@ -210,11 +222,22 @@ export async function publish(args = []) {
     installed.length &&
     !installed.includes(siteYml.runtime)
   ) {
+    // ⚠️ Leads with REMOVING the pin, deliberately. A site ships no JS, so it
+    // has no basis for holding a runtime version, and `runtime:` is an
+    // operator-level override that is no longer part of the documented
+    // authoring surface. This message used to say "pin one of these in
+    // site.yml" — which pushed a reader deeper into a mechanism they should
+    // not be using, and named a key the docs no longer describe. Keep the
+    // installed list (it is the actionable part when a pin IS intended), but
+    // do not restore pin-first phrasing.
     say.err(
-      `Runtime ${siteYml.runtime} (from site.yml) is not installed on the backend.`
+      `Runtime ${siteYml.runtime} (pinned in site.yml) is not installed on the backend.`
+    )
+    say.dim(
+      `Remove the \`runtime:\` pin and the backend chooses — a site ships no code, so it has no reason to hold one.`
     )
     say.dim(
-      `Installed: ${installed.join(', ') || '(none)'} — pin one of these in site.yml (\`runtime:\`), or have it installed on the backend.`
+      `Installed: ${installed.join(', ') || '(none)'} — or pin one of those, or have ${siteYml.runtime} installed.`
     )
     if (!dryRun) return { exitCode: 1 }
   }

package/src/commands/push.js

@@ -26,7 +26,11 @@
  *
  * Usage:
  *   uniweb push                          Build, push both lanes, back-fill $uuid
- *   uniweb push --as-org @org            Act as @org (membership-gated)
+ *   uniweb push --as-org @org            Act as @org (membership-gated). Needed only
+ *                                        for the FIRST push of a site — it decides
+ *                                        which org owns it (and whose storage its
+ *                                        assets are charged to). Recorded as
+ *                                        `site.yml::$org` and replayed after that.
  *   uniweb push --dry-run                Report what would be pushed; submit nothing
  *   uniweb push -o out.uwx               Write the .uwx file(s) per lane; submit nothing
  *   uniweb push --registry <url>         Override the backend origin
@@ -68,7 +72,8 @@ import {
   ensureItemUuids,
   ensureSiteExists,
   clearRemoteSyncStateIfUnbound,
-  pushSyncPackages
+  pushSyncPackages,
+  readSiteOrg
 } from '../backend/site-sync.js'
 
 // Re-exported for downstream importers (pull.js, push.test.js) that read these
@@ -106,7 +111,6 @@ export async function push(args = []) {
   const dryRun = args.includes('--dry-run')
   const output = flagValue(args, '-o') || flagValue(args, '--output')
   const tokenFlag = flagValue(args, '--token')
-  const asOrg = flagValue(args, '--as-org')
   const foundationDir = flagValue(args, '--foundation')
   const sendAll = args.includes('--all') // bypass the send-only-changed cache
   // --force drops the optimistic-concurrency precondition, making the push
@@ -118,6 +122,13 @@ export async function push(args = []) {
 
   const siteDir = await resolveSiteDir(args, 'push')
 
+  // The acting org: the flag verbatim, else the one this site was CREATED under
+  // (`site.yml::$org`). The org is consumed by the create that mints `$uuid`, so
+  // a site that already exists is already owned — replaying the recorded handle
+  // reasserts that rather than choosing anything new. A site with no `$org`
+  // recorded sends no `as_org`, exactly as before.
+  const asOrg = flagValue(args, '--as-org') || readSiteOrg(siteDir)
+
   // Advisory only — warns and pushes. A malformed data block otherwise rides
   // the sync wire unchecked; see utils/conformance.js.
   await warnIfContentDoesNotConform(siteDir, { args })

package/src/framework-index.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-08-10T22:41:12.349Z",
+  "generatedAt": "2026-08-12T22:01:32.128Z",
   "packages": {
     "@uniweb/build": {
-      "version": "0.18.3",
+      "version": "0.18.5",
       "path": "framework/build",
       "deps": [
         "@uniweb/content-reader",
@@ -28,7 +28,7 @@
       "deps": []
     },
     "@uniweb/core": {
-      "version": "0.8.3",
+      "version": "0.8.5",
       "path": "framework/core",
       "deps": [
         "@uniweb/semantic-parser",
@@ -46,7 +46,7 @@
       "deps": []
     },
     "@uniweb/kit": {
-      "version": "0.11.1",
+      "version": "0.11.3",
       "path": "framework/kit",
       "deps": [
         "@uniweb/core",
@@ -65,7 +65,7 @@
       "deps": []
     },
     "@uniweb/projections": {
-      "version": "0.2.6",
+      "version": "0.2.8",
       "path": "framework/projections",
       "deps": [
         "@uniweb/content-writer",
@@ -73,7 +73,7 @@
       ]
     },
     "@uniweb/runtime": {
-      "version": "0.11.3",
+      "version": "0.11.5",
       "path": "framework/runtime",
       "deps": [
         "@uniweb/core",
@@ -96,7 +96,7 @@
       "deps": []
     },
     "@uniweb/semantic-parser": {
-      "version": "1.2.1",
+      "version": "1.2.2",
       "path": "framework/semantic-parser",
       "deps": []
     },
@@ -111,7 +111,7 @@
       "deps": []
     },
     "@uniweb/unipress": {
-      "version": "0.8.2",
+      "version": "0.8.4",
       "path": "framework/unipress",
       "deps": [
         "@uniweb/build",

package/src/index.js

@@ -1318,6 +1318,10 @@ ${colors.bright}Options:${colors.reset}
   --yes              Skip confirmations (CI); never block on a prompt
   --no-save          Skip the deploy.yml lastDeploy auto-save
   --no-validate      Skip the content-conformance check (it only warns)
+  --as-org @org      Publish under @org (membership-gated). Read only on a site's
+                     FIRST publish — that create decides which org owns the site,
+                     and whose storage its assets are charged to. Recorded as
+                     site.yml \$org and replayed, so it is never re-typed.
   --backend <url>    Backend origin (default: \$UNIWEB_REGISTER_URL or built-in)
   --token <bearer>   Auth bearer (skips \`uniweb login\`)
 `,
@@ -1693,6 +1697,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
+  --as-org @org      Publish under @org (first publish only; then remembered)
   --no-save          Skip the deploy.yml lastDeploy auto-save
   --no-validate      Skip the content-conformance check (it only warns)
   --backend <url>    Backend origin (default: \$UNIWEB_REGISTER_URL or built-in)

package/src/utils/uwx-read.js

@@ -0,0 +1,157 @@
+/**
+ * Minimal `.uwx` reader — for the commands that run BEFORE a project exists.
+ *
+ * ## Why this exists rather than importing the real one
+ *
+ * Every other `.uwx` reader in the CLI (`pull.js`, `site-sync.js`, `content.js`)
+ * imports `readZip` from `@uniweb/build/uwx`. That is correct for them: they run
+ * *inside* a project, where `@uniweb/build` resolves from the project's own
+ * `node_modules`.
+ *
+ * **`@uniweb/build` is not a dependency of this package** (see `package.json`),
+ * so a command that runs where no project exists cannot reach it — statically or
+ * dynamically. `uniweb clone` is exactly that command: its whole job is to turn a
+ * backend site into a local project that does not exist yet.
+ *
+ * So this is a deliberate second implementation, kept minimal and dependency-free
+ * (`node:zlib` is a builtin), the same way `clone.js` keeps its own
+ * `extractDocument` for the same reason. **Do not import this from a command that
+ * runs inside a project** — use `@uniweb/build/uwx`'s `readZip` there, so the
+ * producer and the consumer of a `.uwx` stay one implementation wherever they can.
+ *
+ * ## Two things measured on a real payload, both of which would break a naive reader
+ *
+ * 1. ⛔ **The archive is NOT "stored".** `pull.js` describes the format as *"our
+ *    Stored ZIP"*, and that is true of `manifest.json` and false of the entity
+ *    files — measured on a live pull: `manifest.json` method 0 (STORED), the
+ *    entity JSON method 8 (DEFLATED). A stored-only reader silently yields the
+ *    manifest and drops the document, i.e. it returns success and no entities.
+ *    **Both methods are handled below and the tests cover a mixed archive.**
+ * 2. The entity payload is the *only* thing wanted; `manifest.json` is skipped, as
+ *    every other reader in the tree does.
+ *
+ * We read the **central directory** rather than walking local file headers,
+ * because a local header may carry zeroed sizes when the general-purpose bit 3
+ * flag defers them to a trailing data descriptor. The central directory always
+ * carries the real sizes.
+ */
+
+import { inflateRawSync } from 'node:zlib'
+
+const SIG_EOCD = 0x06054b50
+const SIG_CENTRAL = 0x02014b50
+const SIG_LOCAL = 0x04034b50
+const METHOD_STORED = 0
+const METHOD_DEFLATED = 8
+
+/** ZIP local-file-header magic, "PK\x03\x04" — the first two bytes are enough. */
+export function looksLikeZip(buf) {
+  return Boolean(buf) && buf.length >= 2 && buf[0] === 0x50 && buf[1] === 0x4b
+}
+
+/**
+ * Locate the end-of-central-directory record.
+ *
+ * Scanned backwards because the record is last and variable-length (it carries an
+ * optional trailing comment).
+ *
+ * @param {Buffer} buf
+ * @returns {number} offset of the EOCD, or -1
+ */
+function findEocd(buf) {
+  const min = Math.max(0, buf.length - 22 - 0xffff)
+  for (let i = buf.length - 22; i >= min; i--) {
+    if (buf.readUInt32LE(i) === SIG_EOCD) return i
+  }
+  return -1
+}
+
+/**
+ * Read every entry out of a ZIP as `[name, Buffer]` pairs.
+ *
+ * @param {Buffer} buf
+ * @returns {Array<[string, Buffer]>} empty when the buffer is not a readable ZIP
+ */
+export function readUwxZip(buf) {
+  if (!looksLikeZip(buf)) return []
+  const eocd = findEocd(buf)
+  if (eocd < 0) return []
+
+  const count = buf.readUInt16LE(eocd + 10)
+  let ptr = buf.readUInt32LE(eocd + 16)
+  const out = []
+
+  for (let i = 0; i < count; i++) {
+    if (ptr + 46 > buf.length || buf.readUInt32LE(ptr) !== SIG_CENTRAL) break
+
+    const method = buf.readUInt16LE(ptr + 10)
+    const csize = buf.readUInt32LE(ptr + 20)
+    const nameLen = buf.readUInt16LE(ptr + 28)
+    const extraLen = buf.readUInt16LE(ptr + 30)
+    const commentLen = buf.readUInt16LE(ptr + 32)
+    const localOff = buf.readUInt32LE(ptr + 42)
+    const name = buf.subarray(ptr + 46, ptr + 46 + nameLen).toString('utf8')
+
+    // The local header's name/extra lengths are independent of the central
+    // directory's — read them where the data actually starts, not from above.
+    if (localOff + 30 <= buf.length && buf.readUInt32LE(localOff) === SIG_LOCAL) {
+      const lNameLen = buf.readUInt16LE(localOff + 26)
+      const lExtraLen = buf.readUInt16LE(localOff + 28)
+      const start = localOff + 30 + lNameLen + lExtraLen
+      const raw = buf.subarray(start, start + csize)
+      try {
+        if (method === METHOD_STORED) out.push([name, Buffer.from(raw)])
+        else if (method === METHOD_DEFLATED) out.push([name, inflateRawSync(raw)])
+        // any other method: skip rather than guess
+      } catch {
+        /* a corrupt entry must not lose the readable ones */
+      }
+    }
+
+    ptr += 46 + nameLen + extraLen + commentLen
+  }
+
+  return out
+}
+
+/**
+ * The entity `$`-documents inside a `.uwx`, or a JSON body's documents.
+ *
+ * Mirrors `pull.js`'s `readPullDocuments` in behaviour — including its JSON
+ * fallback, so a future envelope change does not break this lane either — but
+ * without the `@uniweb/build` import. See the header for why that matters.
+ *
+ * @param {Buffer} buf
+ * @returns {object[]} parsed documents, possibly empty
+ */
+export function readUwxDocuments(buf) {
+  if (!buf || buf.length === 0) return []
+
+  if (looksLikeZip(buf)) {
+    const docs = []
+    for (const [name, data] of readUwxZip(buf)) {
+      if (name === 'manifest.json' || !name.endsWith('.json')) continue
+      try {
+        docs.push(JSON.parse(data.toString('utf8')))
+      } catch {
+        /* skip a non-document entry */
+      }
+    }
+    return docs
+  }
+
+  let payload
+  try {
+    payload = JSON.parse(buf.toString('utf8'))
+  } catch {
+    return []
+  }
+  if (Array.isArray(payload)) return payload.filter(Boolean)
+  const list = Array.isArray(payload?.entities)
+    ? payload.entities
+    : Array.isArray(payload?.documents)
+      ? payload.documents
+      : null
+  if (list) return list.filter(Boolean)
+  return payload ? [payload] : []
+}