uniweb 1.2.0 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "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/content-writer": "~1.0.1",
-    "@uniweb/core": "~1.1.0",
-    "@uniweb/semantic-parser": "~1.5.1",
-    "@uniweb/schemas": "~1.0.1"
+    "@uniweb/core": "~1.2.0",
+    "@uniweb/semantic-parser": "~1.6.0",
+    "@uniweb/schemas": "~1.1.0",
+    "@uniweb/content-writer": "~1.1.0"
   },
   "peerDependencies": {
-    "@uniweb/build": "~1.1.1",
-    "@uniweb/semantic-parser": "~1.5.1",
-    "@uniweb/content-reader": "~1.2.8"
+    "@uniweb/semantic-parser": "~1.6.0",
+    "@uniweb/content-reader": "~1.3.0",
+    "@uniweb/build": "~1.2.0"
   },
   "peerDependenciesMeta": {
     "@uniweb/build": {

package/partials/agents.md

@@ -540,12 +540,13 @@ Sizing and loading ride on the image: `{width=800 height=600 loading=lazy fit=co
 
 **Separators are forgiving.** `:` works wherever `=` does, and pairs may be separated by whitespace, a comma, or both — `{role=banner width=1200}`, `{role:banner, width:1200}` and `{role:banner,width:1200}` are identical. `=` and spaces are canonical, and that is what gets written back on save. Two rules keep it unambiguous: the separator must **touch** the key (`{note:warning}` is one pair, `{note : warning}` is two flags), and a value containing a **comma** must be quoted (`{style="a, b"}`). A value containing a colon needs no quoting — only the first colon separates, so `{href:https://example.com}` is fine.
 
-Standalone links (alone on a line) become buttons in `content.links[]`. Inline links stay as `<a>` tags inside `content.paragraphs[]`. Multiple links sharing a paragraph are all promoted:
+Standalone links (alone on a line) are promoted to `content.links[]` — usually drawn as buttons, which is the component's choice. Inline links stay as `<a>` tags inside `content.paragraphs[]`. Multiple links sharing a paragraph are all promoted:
 
 ```markdown
 [Primary](/start)              ← standalone → content.links[0]
 [One](/a) [Two](/b)            ← links-only paragraph → both in content.links[]
 Check out [this](/a) link.     ← inline → stays in paragraphs as an <a> tag
+[Go](/start){button}           ← a link with role "button" (also `button:/start`), and a `variant`
 ```
 
 ### Inline text styling
@@ -557,12 +558,18 @@ This is [less important]{muted} context.
 
 `accent` and `callout` (both accent-colored + bold) and `muted` (subtle) are built-in defaults that adapt to context. `--accent` is your brand color unless you declare a separate `colors.accent`, and resolves to the shade you authored — not a darkened one, since accent is decorative emphasis rather than body-size link text. Components receive HTML strings with spans applied: `<span accent="true">faster</span>`.
 
-Sites can adjust these or add named styles in `theme.yml`'s `inline:` section. Overrides merge **property by property**, so declare only what differs (`accent: { font-weight: inherit }` keeps the default color); to drop a default property rather than change it, give it a neutral value (`initial`, `inherit`, `unset`).
+Sites can adjust these or add named styles in `theme.yml`'s `inline:` section — a name is a letter, then letters, digits, `_` or `-`, and never starts with `on` (a handler's prefix, so it is dropped). Overrides merge **property by property**, so declare only what differs (`accent: { font-weight: inherit }` keeps the default color); to drop a default property rather than change it, give it a neutral value (`initial`, `inherit`, `unset`).
 
 > **On a site synced with Uniweb Cloud, the built-in style names round-trip *editable*** — an author who opens a page containing `[Get started]{accent}` gets the editor's own styling control for it, and can change or remove it like any text they styled there.
 >
 > **A name the editor doesn't know is preserved exactly, but not editable** — a style you defined yourself in `inline:`, two names on one span, or a `class`/`id` set. Nothing is lost and nothing is approximated: it survives every edit and save untouched, the editor simply offers no control for it. That is a permanent property rather than a gap, because the name set is open by design — you can add styles the editor has no way to know about.
 
+### HTML is not content
+
+Content is markdown. Components decide how it renders, so a tag written in it — `<strong>`, `<span class=…>`, `<div>` — is not markup: it **shows as written**, and the build names the file. Use markdown's own forms instead: `**bold**`, a named style (`[text]{accent}`), a link.
+
+The one exception is `<br/>`, a line break where markdown has no other spelling — inside a heading. For a headline split across lines, the multi-line heading above usually says it better.
+
 ### Fenced code: data blocks vs snippets
 
 Fenced code serves three purposes depending on its info string: `yaml:`/`json:` for data, `md:` for a named kind of prose (see *Concept blocks*), and a bare language for a code sample.
@@ -1072,6 +1079,8 @@ import { H1, H2, H3, P, Span } from '@uniweb/kit'
 <Span text={listItem.paragraphs[0]} className="text-subtle" />
 ```
 
+These strings are safe to render as HTML because the parser builds them from structure and escapes every character of the text. **A string from anywhere else is not** — a field a member wrote, a value an API returned. Render it as text: `{value}` in JSX, or `<PlainText text={value} />`.
+
 Kit provides `H1`–`H6`. These render their own HTML tag — **don't wrap them**: `<H2 text={…} />`, not `<h2><H2 text={…} /></h2>`.
 
 **Full content rendering** (article/docs sections where the author controls the flow):
@@ -2509,12 +2518,14 @@ const { entity } = useEntity({ schema: '@/track', uuid: record.uuid })
 const sessions = entity?.hydrated?.items.filter((item) => item.section === 'sessions')
 ```
 
+⛔ **What a member wrote is text.** Render a field as `{record.brief.name}` or `<PlainText text={…} />` — never `<P text>`, `<H1>`–`<H6>` or `SafeHtml`, which render HTML: a member who typed `<img src=x onerror=…>` would run it as whoever views the page. A rich-text field (a ProseMirror document) renders through kit's `Render`, which escapes its text.
+
 ⛔ **A listed record is a summary, not the entity.** `record.brief` holds the brief
 section's fields (`record.brief.name`, not `record.name`), and a record carries **no
 items**. Read one entity for its items. Each item carries `section`, its section's name
 (the word a write takes), and `id`, which is what the writer takes to update, move or
 remove it. `scope: 'mine'` lists only the viewer's own records; without it, a list also
-holds what was shared with the viewer.
+holds what was shared with the viewer, and what a role of theirs reaches.
 
 ⭐ **`absent` and an empty `ready` are different answers, and confusing them is the
 mistake to avoid.** `absent` = there is no live source (no `backend` service, or nobody signed
@@ -2549,9 +2560,11 @@ await writer.remove(itemId)
 Gate your controls on what the viewer may do — a record's own `can_edit` from a
 single-entity read — but **never rely on that for safety**. A foundation runs with
 exactly the viewer's own authority, so hiding a button hides a button. ⛔ **Not on
-`viewer.roles`:** a session signed in on a site holds a member's rights — the operator's
-too — so its roles never name an administrator, and a gate on `system_admin` shows the
-operator nothing.
+`viewer.roles` alone:** on a site a session holds its roles as a reader's until it is
+elevated (*Acting as an administrator*, below), so a gate on `system_admin` shows the
+operator nothing until then — and a role never says what the session may do to one
+record. Draw a control that acts through a role from `useElevation().rolesInFull`, and
+let the record answer.
 
 What protects content is the **entry**: a member writes their own entries and not
 another's, and the store enforces it. **Models are open** — anyone signed in may
@@ -2570,6 +2583,44 @@ sections:
 `append_only` holds against the item's own author. That is the difference between a
 permission model and a CSS one.
 
+A schema can also open entries by relationship, and keep them from being shared:
+
+```yaml
+# foundation/schemas/submission.yml
+grantable: false                                     # no entry is shared one at a time
+fields:
+  course: { ref: '@/course', readable_with: edit }   # the course's editors read it
+```
+
+`readable_with` — `read`, `edit` or `admin`, and only on a reference — opens the entry, to
+read and never to change, to whoever holds that level on the entry the reference points to:
+a submission's `course` at `edit` reaches the course's staff and none of its students. A row
+read that way comes back with `via: 'rbac'`. It is one step, and a backend refuses adding it
+to a field entries already fill. `grantable: false` keeps entries from being shared with a
+person or a team; omitted, they can be.
+
+### Acting as an administrator
+
+On a site, an administrator's session reads what their role reaches — the operator reads
+every member's records — and changes nothing through the role until they confirm it is
+them. Their own records they edit, delete and share as always.
+
+```jsx
+const { available, elevated, until, elevate, lower, error } = useElevation()
+// available: the account holds a role that does more than read — offer it only then
+// elevate({ password, code }) — code when the account has a second factor; a refusal is error.kind === 'auth'
+// elevated, until: true while it lasts, and when it ends; lower() ends it early
+```
+
+- It lasts as long as the backend decides; `elevated` turns false by itself at `until`,
+  and elevating again starts the time again. Nothing says whether the account has a
+  second factor, so offer the code field to whoever might.
+- While it lasts `viewer.roles` names the role, and every record read before is read
+  again, so `entity.can_edit` answers for the session as it is now.
+- An account with no password: `elevateWithProvider(provider)` goes to the provider's
+  sign-in and back to the page.
+- It does not open the backend's administration — the Admin link does.
+
 ### The Admin link
 
 ```jsx
@@ -2581,7 +2632,8 @@ const { adminHref } = useSession()
 the operator, and whoever else administers it — and is `null` for everyone else. It
 takes them there already signed in. ⛔ **Navigate to it, never `fetch` it**: the answer is
 a redirect carrying a one-time credential no script on the site is to hold. It decides
-what to offer, not what is allowed — on the site the operator acts as a member.
+what to offer, not what is allowed — on the site the operator acts through their role
+only while elevated.
 
 ### The links the backend mails
 

package/src/backend/client.js

@@ -843,7 +843,9 @@ export class BackendClient {
    * shipped backend-side — collab backend↔framework):
    *   { published: boolean, last_pushed_at?: string, last_published_at?: string, draft_dirty?: boolean }
    * `draft_dirty` = never-published, or the synced draft changed since the last
-   * publish ("pushed but not published").
+   * publish ("pushed but not published"). Since 2026-10-13 it also carries `editors`:
+   * who has the site open in the app right now, and on what — `status --remote` shows
+   * it (`describeEditors`, commands/status.js).
    *
    * ⭐ **The backend also serves a LIVE-SITE record here, and nothing in this CLI reads
    * it yet** (shipped 2026-08-29; documented here so it is not lost twice):

package/src/commands/status.js

@@ -7,15 +7,17 @@
  * `uniweb push` runs) — no auth, no backend round-trip.
  *
  * `--remote` adds the backend signals (may prompt for login, like `git fetch`):
- *   - whether the synced draft differs from what's live (publish needed), and
- *   - whether a newer foundation version is registered than the site pins.
+ *   - whether the synced draft differs from what's live (publish needed),
+ *   - whether a newer foundation version is registered than the site pins, and
+ *   - who has the site open in the app right now, and on what (`describeEditors`).
  * Those use ASSUMED endpoints (see kb shipping-verbs-and-freshness.md §6.5); until
  * the backend exposes them, `--remote` degrades silently to the local view.
  *
  * Usage:
  *   uniweb status            Sync identity + unpushed content + foundation ref (local)
  *   uniweb status --remote   Also: whether the backend still holds the site, draft-vs-live,
- *                            and a newer-registered-foundation check
+ *                            a newer-registered-foundation check, and who has it open in
+ *                            the app
  *   uniweb status --json     One JSON line (adds a `remote` object under --remote, whose
  *                            `site_state` is live / gone / unknown — `gone` only on the
  *                            backend's own word that it holds no such site)
@@ -28,7 +30,7 @@ import { join } from 'node:path'
 import yaml from 'js-yaml'
 
 import { resolveSiteDir } from './deploy.js'
-import { probeUnpushed } from '../backend/site-sync.js'
+import { probeUnpushed, readItemUuids, unitFilesOf } from '../backend/site-sync.js'
 import { resolveWorkspace } from '../backend/workspace.js'
 import {
   BackendClient,
@@ -75,6 +77,79 @@ function foundationRef(siteYml) {
   return typeof f === 'string' ? f : f.ref || null
 }
 
+// What an item that this copy has not synced is called — by its Section on the site.
+const ITEM_KIND = { pages: 'a page', page_sections: 'a section', layout_sections: 'a layout section' }
+
+/**
+ * Who has the site open in the app right now, and on what — the status's `editors`
+ * (backend, since 2026-10-13), as lines a developer can follow up on. Each tab's item is
+ * named by the file it is in this copy, and by its kind and route when this copy has not
+ * synced it (`fileByItemUuid`).
+ *
+ * ⛔ Two ways not to read it. `changed_at` is the item's last change by ANYONE — this
+ * author, another, a push — so it says when the item last changed, never what this
+ * person did. And it is presence, not a lock: nothing refuses or warns a push over it.
+ *
+ * @param {object[]} editors - `[{ person: { uuid, handle, brief }, tabs: [{ page, item }] }]`
+ * @param {object} [opts]
+ * @param {(uuid: string) => string|null} [opts.fileOf] - an item's file in this copy
+ * @param {number} [opts.now] - for "3 min ago"
+ * @returns {{ person: string, tabs: string[] }[]} a tab with nothing open is left out
+ */
+export function describeEditors(editors, { fileOf = () => null, now = Date.now() } = {}) {
+  return editors.map((editor) => ({
+    person: personLabel(editor?.person),
+    tabs: (editor?.tabs || []).map((tab) => tabLabel(tab, fileOf, now)).filter(Boolean)
+  }))
+}
+
+function personLabel(person) {
+  const name = person?.brief?.display_name
+  const handle = person?.handle ? `@${person.handle}` : null
+  if (name && handle) return `${name} (${handle})`
+  return name || handle || `someone (${person?.uuid || 'unnamed'})`
+}
+
+function tabLabel(tab, fileOf, now) {
+  const item = tab?.item
+  if (!item?.uuid) return null
+  const route = tab.page?.route || null
+  const file = fileOf(item.uuid)
+  const what = file
+    ? `${file}${route ? ` (${route})` : ''}`
+    : `${ITEM_KIND[item.section] || 'an item'} not in this copy${route ? ` (${route})` : ''}`
+  const when = sinceLabel(item.changed_at, now)
+  return when ? `${what} · changed ${when}` : what
+}
+
+function sinceLabel(iso, now) {
+  const t = Date.parse(iso)
+  if (Number.isNaN(t)) return null
+  const min = Math.floor(Math.max(0, now - t) / 60_000)
+  if (min < 1) return 'just now'
+  if (min < 60) return `${min} min ago`
+  const h = Math.floor(min / 60)
+  if (h < 24) return `${h} h ago`
+  const d = Math.floor(h / 24)
+  return `${d} day${d === 1 ? '' : 's'} ago`
+}
+
+/**
+ * An item's file in this copy, from its uuid: `sync.json` keeps each unit's uuid on
+ * `backend` by its path (`items`, banked from every push and pull), and `unitFilesOf`
+ * finds the file the author keeps it in (`1-hero.md` for `hero.md`). Null for an item
+ * this copy has not synced — one added in the app since its last pull.
+ */
+export function fileByItemUuid(siteDir, backend) {
+  const unitOf = new Map(
+    Object.entries(readItemUuids(siteDir, backend)).map(([unit, uuid]) => [String(uuid).toLowerCase(), unit])
+  )
+  return (uuid) => {
+    const unit = unitOf.get(String(uuid).toLowerCase())
+    return unit ? (unitFilesOf(siteDir, unit)[0] ?? unit) : null
+  }
+}
+
 // A versioned registry ref `@org/name@1.2.3` → its scoped name `@org/name` and
 // pinned version `1.2.3`. A bare/local/unversioned ref → nulls.
 function splitFoundationRef(fnd) {
@@ -263,6 +338,20 @@ export async function status(args = []) {
         )
       }
     }
+    // An array is the backend's answer, `[]` included; no key is a backend that does not
+    // say, and then neither do we.
+    if (Array.isArray(site?.editors)) {
+      if (!site.editors.length) {
+        say.dim('Nobody has this site open in the app.')
+      } else {
+        say.info('Open in the app now:')
+        const fileOf = fileByItemUuid(siteDir, probeBackend)
+        for (const { person, tabs } of describeEditors(site.editors, { fileOf })) {
+          console.log(`    ${person}${tabs.length ? '' : ', with nothing open'}`)
+          for (const tab of tabs) console.log(`      ${c.dim}${tab}${c.reset}`)
+        }
+      }
+    }
     if (
       fdnLatest?.latest_version &&
       fndVersion &&

package/src/framework-index.json

@@ -1,54 +1,54 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-10-13T20:52:47.988Z",
+  "generatedAt": "2026-10-15T01:14:19.629Z",
   "packages": {
     "@uniweb/api": {
-      "version": "1.1.0"
+      "version": "1.2.0"
     },
     "@uniweb/build": {
-      "version": "1.1.1"
+      "version": "1.2.0"
     },
     "@uniweb/content-reader": {
-      "version": "1.2.8"
+      "version": "1.3.0"
     },
     "@uniweb/content-writer": {
-      "version": "1.0.1"
+      "version": "1.1.0"
     },
     "@uniweb/core": {
-      "version": "1.1.0"
+      "version": "1.2.0"
     },
     "@uniweb/frame-bridge": {
       "version": "1.0.2"
     },
     "@uniweb/icons": {
-      "version": "1.0.2"
+      "version": "1.0.3"
     },
     "@uniweb/kit": {
-      "version": "1.1.0"
+      "version": "1.2.0"
     },
     "@uniweb/loom": {
       "version": "1.1.0"
     },
     "@uniweb/press": {
-      "version": "1.1.0"
+      "version": "1.1.1"
     },
     "@uniweb/projections": {
-      "version": "1.1.0"
+      "version": "1.1.1"
     },
     "@uniweb/runtime": {
-      "version": "1.1.0"
+      "version": "1.1.1"
     },
     "@uniweb/scene": {
       "version": "1.0.1"
     },
     "@uniweb/schemas": {
-      "version": "1.0.1"
+      "version": "1.1.0"
     },
     "@uniweb/scholar": {
       "version": "1.1.0"
     },
     "@uniweb/semantic-parser": {
-      "version": "1.5.1"
+      "version": "1.6.0"
     },
     "@uniweb/snapshot": {
       "version": "1.1.0"
@@ -57,10 +57,10 @@
       "version": "1.1.0"
     },
     "@uniweb/theming": {
-      "version": "1.1.0"
+      "version": "1.2.0"
     },
     "@uniweb/unipress": {
-      "version": "1.1.0"
+      "version": "1.1.1"
     }
   },
   "templates": {