uniweb 0.34.1 → 0.34.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.34.1",
+  "version": "0.34.2",
   "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/runtime": "^0.13.3",
-    "@uniweb/kit": "^0.15.0",
     "@uniweb/core": "^0.14.1",
-    "@uniweb/semantic-parser": "^1.3.1"
+    "@uniweb/semantic-parser": "^1.3.1",
+    "@uniweb/runtime": "^0.13.3",
+    "@uniweb/kit": "^0.15.0"
   },
   "peerDependencies": {
-    "@uniweb/content-reader": "^1.2.4",
     "@uniweb/semantic-parser": "^1.3.1",
-    "@uniweb/build": "^0.30.0"
+    "@uniweb/content-reader": "^1.2.4",
+    "@uniweb/build": "^0.30.2"
   },
   "peerDependenciesMeta": {
     "@uniweb/build": {

package/partials/agents.md

@@ -2234,6 +2234,112 @@ For cases the factory doesn't cover, write handlers directly using `Loom`, `inst
 
 ---
 
+## Part 4b — When the site is also an app
+
+Everything above is a site: content the author writes, built into pages. Some sites
+also have **their own backend** — accounts, per-visitor data, records their members
+create and edit. That is `@uniweb/api`.
+
+⛔ **Only reach for this when the site actually has one.** A site with no backend is
+the normal case, and a foundation that assumes one breaks on every other site it is
+used with.
+
+```bash
+npm install @uniweb/api      # in the FOUNDATION, beside @uniweb/kit
+```
+
+### Ask before you draw
+
+```jsx
+import { isEnabled, useSession, SignedIn, SignedOut } from '@uniweb/api'
+
+if (!isEnabled(website)) return <StaticVersion />   // synchronous — nothing to await
+```
+
+⛔ **When there is no backend, draw nothing** — not a disabled control, and not an
+explanation. Same rule as `services` in Part 4: which capabilities a site's operator
+set up is none of a visitor's business, and "sign-in unavailable" reads as breakage
+when it is simply a feature this site does not have. Render the version of your
+component that never needed one.
+
+### Reading
+
+```jsx
+const { status, records } = useRecords({ schema: '@/session' })
+```
+
+⭐ **`absent` and an empty `ready` are different answers, and confusing them is the
+mistake to avoid.** `absent` = there is no live source (no backend, or nobody signed
+in) → render the site's authored content. `ready` with `records: []` = the backend
+answered and there is nothing there → render your empty state. Showing "nothing yet"
+for the first tells a visitor their content is gone when it was never requested.
+
+### Writing
+
+```jsx
+const writer = useEntityWriter({ schema: '@/track', uuid: track.uuid })
+
+await writer.create({ title: 'Keynote' }, { section: 'sessions', position: 'last' })
+await writer.update(itemId, { ...item.data, room: 'Hall A' })   // whole-data replace
+await writer.move(itemId, { after: previousItemId })            // never an index
+await writer.remove(itemId)
+```
+
+- **`section` is required on `create`.** An entity has several, and a rule declared on
+  one — insert-only, say — does not reach an item that landed in another. Getting it
+  wrong stores the item happily and quietly voids the rule.
+- **`update` replaces the item's data whole.** Spread what you are not editing.
+- **Ordering is the server's.** Say `'first'`, `'last'` or `{ after }` — never compute
+  an order number, or two people arranging one list will produce an order neither
+  chose.
+- ⛔ **`writer.conflict` is reported, not retried.** Someone else changed the item
+  first; a retry would succeed by overwriting a change nobody looked at. Tell the
+  person.
+
+### ⛔ Permissions are the SERVER'S, and your UI is only a courtesy
+
+Gate your controls on what the viewer may do — `viewer.actingUnitId`, `viewer.roles` —
+but **never rely on that for safety**. A foundation runs with exactly the viewer's
+own authority, so hiding a button hides a button. The rule belongs in the data
+schema, where the store enforces it:
+
+```yaml
+# foundation/schemas/session.yml
+creatable_by: unit_members     # only members of the owning unit may create these
+
+sections:
+  checkins:
+    many: true
+    append_only: true          # may be added; never edited or removed, by anyone
+```
+
+`append_only` holds against the item's own author. That is the difference between a
+permission model and a CSS one.
+
+### A backend on your machine
+
+You do not need a live backend to build against one. In `site.yml`:
+
+```yaml
+api: /_api                 # where it answers — the same value in production
+$devApi: ./mock/api.js     # what answers it locally; `$` keys are never published
+```
+
+```js
+// site/mock/api.js
+import { createMockBackend } from '@uniweb/api/mock'
+export default createMockBackend({ seed }).fetch
+```
+
+`uniweb dev` mounts it at your `api:` address, same-origin, so cookies and your
+site's configuration behave exactly as they will in production. It **enforces**
+`creatable_by` 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.
+
+`uniweb create my-event --template conference` is a worked example of all of this.
+
+---
+
 ## Part 5 — Commands, shipping, and migration
 
 ```bash

package/src/backend/site-media.js

@@ -17,6 +17,7 @@ import { existsSync, readFileSync } from 'node:fs'
 import { basename } from 'node:path'
 import { resolveAssetPath } from '@uniweb/build/site'
 import { contentTypeFor } from '../utils/code-upload.js'
+import { humanBytes } from '../utils/bytes.js'
 
 /**
  * @param {object} client - BackendClient (uploadSiteAssets). No `discover` — this
@@ -123,20 +124,6 @@ export async function uploadSiteMedia(
 // rewording). Same house style as the push-staleness `reason: "stale_base"` in
 // site-sync.js.
 
-const KIB = 1024
-function humanBytes(n) {
-  if (typeof n !== 'number' || !Number.isFinite(n) || n < 0) return null
-  if (n < KIB) return `${n} B`
-  const units = ['KiB', 'MiB', 'GiB', 'TiB']
-  let v = n / KIB
-  let i = 0
-  while (v >= KIB && i < units.length - 1) {
-    v /= KIB
-    i++
-  }
-  return `${v >= 10 || Number.isInteger(v) ? Math.round(v) : v.toFixed(1)} ${units[i]}`
-}
-
 // Append `label: <bytes>` when the value is a usable number. A refusal that omits an
 // extra still produces a useful message — never print `undefined` at a user.
 function pushBytes(lines, label, n) {
@@ -146,9 +133,17 @@ function pushBytes(lines, label, n) {
 
 /**
  * Turn an asset-plan refusal into user-facing lines, or null when this is not a
- * refusal we recognise (including every refusal shipped today, which is still
- * prose — the typed `reason` values are agreed but NOT YET EMITTED). Null means
- * "fall through to the generic error", so this degrades rather than swallowing.
+ * refusal we recognise. Null means "fall through to the generic error", so this
+ * degrades rather than swallowing.
+ *
+ * ⛔ This comment used to assert that the typed `reason` values were "agreed but
+ * NOT YET EMITTED" — an unverified claim about ANOTHER LANE's deployed state,
+ * sitting in our source where it read as fact and nobody would think to re-check
+ * it. That is the precise shape that cost the backend lane a metering hole (a
+ * comment claiming what the app sent, wrong the whole time). What we can say is
+ * ours: we branch on `reason` and fall through cleanly when there is none, so
+ * this function is correct whether or not any given backend emits one, and no
+ * sentence here needs to track what a deployment is running.
  *
  * Two wording rules are load-bearing and come from the ratified accounting model,
  * not from taste:

package/src/backend/site-sync.js

@@ -16,6 +16,7 @@ import { join, dirname } from 'node:path'
 import yaml from 'js-yaml'
 import { hasUncommittedContent } from '../utils/git.js'
 import { recordSiteBackend } from '../utils/site-identity.js'
+import { humanBytes } from '../utils/bytes.js'
 import {
   backfillEntityUuids,
   writeSiteEntityUuid,
@@ -647,9 +648,8 @@ export async function resolveSiteOrgForCreate({
   // serves the foundation lane, where every answer is an org and 0-orgs means
   // "claim your personal org". Here "personal" must stay reachable as *no org*,
   // and reusing deriveScope would quietly turn it into an org creation.
-  const { fetchOrgs, createOrg, validateHandle, bareHandle } = await import(
-    '../utils/registry-orgs.js'
-  )
+  const { fetchOrgs, createOrg, validateHandle, bareHandle } =
+    await import('../utils/registry-orgs.js')
   let envelope
   try {
     envelope = await fetchOrgs({
@@ -719,6 +719,59 @@ export async function resolveSiteOrgForCreate({
   }
 }
 
+/**
+ * Turn a typed site-create refusal into a sentence, or null to fall through to the
+ * generic HTTP line.
+ *
+ * ⭐ Why this exists separately from `describeAssetRefusal`. The asset lane grew a
+ * typed describer because a raw status dump is useless to the person who has to act
+ * on it; the create lane had the same hole and nobody had met it, because until the
+ * backend shipped account capacity a create could not be refused for space at all.
+ * So this is the same fix on the second door, written before anyone hits it rather
+ * than after.
+ *
+ * ⛔ Branch on `reason`, never on the status. `507` alone cannot be told from any
+ * other 507 and carries none of the numbers a user needs, and `detail` is prose the
+ * backend may reword.
+ *
+ * ⚖️ The wording deliberately DIVERGES from the asset lane's on one point. There the
+ * allowance belongs to the site's owner, who may not be the person pushing. Here
+ * there is no site yet, so the only workspace in play is the one the site would be
+ * created in — `--as <org>` included. Saying "the site owner's workspace" would be
+ * incoherent for a site that does not exist.
+ *
+ * @param {string} body - the raw response body
+ * @returns {string|null}
+ */
+function describeCreateRefusal(body) {
+  if (!body) return null
+  let p
+  try {
+    p = JSON.parse(body)
+  } catch {
+    return null // prose refusal, or an upstream error page
+  }
+  if (!p || typeof p !== 'object' || typeof p.reason !== 'string') return null
+
+  if (p.reason === 'storage_quota_exceeded') {
+    const parts = []
+    const used = humanBytes(p.used_bytes)
+    const limit = humanBytes(p.limit_bytes)
+    const needed = humanBytes(p.needed_bytes)
+    if (used && limit) parts.push(`${used} of ${limit} used`)
+    if (needed) parts.push(`a new site needs ${needed}`)
+    return (
+      'storage quota reached — the workspace this site would belong to has no room for it' +
+      (parts.length ? ` (${parts.join('; ')})` : '') +
+      '. Quota is returned by deleting a site or entity, not by editing content.'
+    )
+  }
+  // An unrecognised typed reason still beats a status dump: name it, and let the
+  // backend's own prose follow when it sent any.
+  const detail = typeof p.detail === 'string' ? p.detail : ''
+  return `the backend refused the site create (${p.reason})${detail ? ` — ${detail}` : ''}`
+}
+
 /**
  * Guarantee the site EXISTS on the backend before anything is uploaded against it.
  *
@@ -797,7 +850,8 @@ export async function ensureSiteExists({
       reason:
         res?.status === 404
           ? 'this backend has no /dev/site route (it predates the empty-site create)'
-          : `HTTP ${res?.status} ${res?.statusText || ''}${body ? ` — ${body.slice(0, 200)}` : ''}`
+          : (describeCreateRefusal(body) ??
+            `HTTP ${res?.status} ${res?.statusText || ''}${body ? ` — ${body.slice(0, 200)}` : ''}`)
     }
   }
   const payload = await res.json().catch(() => null)
@@ -837,7 +891,13 @@ export async function ensureSiteExists({
  *
  * @returns {Promise<string|null>} the display handle recorded, or null for personal
  */
-async function recordAndDescribeOwner({ client, siteDir, payload, asOrg, note }) {
+async function recordAndDescribeOwner({
+  client,
+  siteDir,
+  payload,
+  asOrg,
+  note
+}) {
   const echoed = payload && 'org' in payload ? payload.org : undefined
   const owner =
     echoed === undefined ? asOrg : typeof echoed === 'string' ? echoed : null
@@ -851,7 +911,8 @@ async function recordAndDescribeOwner({ client, siteDir, payload, asOrg, note })
   //
   // A no-op on the default backend, so the common case writes nothing.
   const scope = await recordSiteBackend(siteDir, client.origin)
-  if (scope) note?.(`Bound this project to ${scope} (recorded $backend in site.yml).`)
+  if (scope)
+    note?.(`Bound this project to ${scope} (recorded $backend in site.yml).`)
 
   note?.(
     org
@@ -879,7 +940,9 @@ async function recordAndDescribeOwner({ client, siteDir, payload, asOrg, note })
   // `false` is an answer we deliberately do not speak to, and missing is not an answer
   // at all. Do not reintroduce a "you will be charged" line here.
   if (payload?.hosts_free === true) {
-    note?.('This owner is hosted free — publishing will not require a subscription.')
+    note?.(
+      'This owner is hosted free — publishing will not require a subscription.'
+    )
   }
   return org
 }
@@ -1003,7 +1066,10 @@ export async function probeUnpushed(siteDir, { sendAll = false } = {}) {
  * Offline by design — measured at zero HTTP requests, a property the cross-client
  * flows rely on.
  */
-async function comparisonEmit(siteDir, { priorHashes = {}, sendAll = false } = {}) {
+async function comparisonEmit(
+  siteDir,
+  { priorHashes = {}, sendAll = false } = {}
+) {
   const applied = readAppliedInjections(siteDir)
   const assetIds = readAssetMap(siteDir)
   const org = readSiteOrg(siteDir)
@@ -1264,9 +1330,7 @@ export async function pushSyncPackages({
         note(
           `  deleted in the app  →  clearing \`$uuid\` from site.yml re-publishes it as a NEW site`
         )
-        note(
-          'Deleting this folder removes only your local copy, either way.'
-        )
+        note('Deleting this folder removes only your local copy, either way.')
       } else if (res.status === 409) {
         // The site's @uniweb/folder is genesis-owned: its structure is fixed on first
         // deploy and not reconciled in place (the v1 rule — see gotcha #20's mode switch).
@@ -1416,7 +1480,8 @@ export async function pushSyncPackages({
         asOrg,
         note
       })
-      if (createdOrg) wrote.push(`recorded site $org (${createdOrg}) in site.yml`)
+      if (createdOrg)
+        wrote.push(`recorded site $org (${createdOrg}) in site.yml`)
       const createdFinalized = extractFinalized(payload)
       harvest(createdFinalized)
       siteFinalizedDoc = createdFinalized?.[0]?.document || null
@@ -1464,7 +1529,8 @@ export async function pushSyncPackages({
     const folderDoc = finalized.find((f) => f?.document?.contents)?.document
     if (folderDoc) {
       const placements = collectFolderItemUuids(folderDoc)
-      if (Object.keys(placements).length) writeFolderItemUuids(siteDir, placements)
+      if (Object.keys(placements).length)
+        writeFolderItemUuids(siteDir, placements)
     }
     finalizedTotal += finalized.length
   }

package/src/framework-index.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-08-31T13:37:55.117Z",
+  "generatedAt": "2026-09-01T22:08:19.670Z",
   "packages": {
     "@uniweb/api": {
       "version": "0.1.0",
@@ -10,7 +10,7 @@
       ]
     },
     "@uniweb/build": {
-      "version": "0.30.0",
+      "version": "0.30.2",
       "path": "framework/build",
       "deps": [
         "@uniweb/content-reader",
@@ -94,7 +94,7 @@
       "deps": []
     },
     "@uniweb/schemas": {
-      "version": "0.2.11",
+      "version": "0.2.12",
       "path": "framework/schemas",
       "deps": []
     },
@@ -298,6 +298,18 @@
         "quote",
         "trades"
       ]
+    },
+    "conference": {
+      "name": "Conference",
+      "description": "A site that is also an app — sign-in, per-viewer data, and an editable programme. Ships a local backend so it runs with nothing installed.",
+      "tags": [
+        "app",
+        "api",
+        "backend",
+        "auth",
+        "permissions",
+        "conference"
+      ]
     }
   }
 }

package/src/utils/bytes.js

@@ -0,0 +1,30 @@
+/**
+ * Byte formatting for refusal messages.
+ *
+ * Lives on its own because TWO lanes now print a storage refusal — the asset plan
+ * (`backend/site-media.js`) and the site create (`backend/site-sync.js`) — and the
+ * numbers must read identically in both. A second copy would drift in units or
+ * rounding, and a user comparing "you have 1.1 GiB" against "this needs 100 MB"
+ * cannot tell a real gap from a formatting difference.
+ */
+
+const KIB = 1024
+
+/**
+ * `1073741824` → `1 GiB`. Returns null for anything that is not a usable byte
+ * count, so a refusal that omits an extra prints nothing rather than `undefined`.
+ * @param {unknown} n
+ * @returns {string|null}
+ */
+export function humanBytes(n) {
+  if (typeof n !== 'number' || !Number.isFinite(n) || n < 0) return null
+  if (n < KIB) return `${n} B`
+  const units = ['KiB', 'MiB', 'GiB', 'TiB']
+  let v = n / KIB
+  let i = 0
+  while (v >= KIB && i < units.length - 1) {
+    v /= KIB
+    i++
+  }
+  return `${v >= 10 || Number.isInteger(v) ? Math.round(v) : v.toFixed(1)} ${units[i]}`
+}