feat(spec,lint): ADR-0081 — kind:'html' (rename) + trusted kind:'react' tier

- spec: PageSchema.kind gains 'html' (the renamed constrained tier; 'jsx'
  kept as a deprecated alias) and 'react' (trusted real-React, executed at
  render, host-capability gated). Completeness gate requires source for all three.
- lint: validate-jsx-pages lints html/jsx; skips react (real JS, not
  constrained JSX). +tests.
- examples: command-center page moves to kind:'html'.
- docs: ADR-0081.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: os-zhuang

.changeset/sdui-react-page-tier.md

@@ -0,0 +1,14 @@
+---
+"@objectstack/spec": minor
+"@objectstack/lint": minor
+---
+
+ADR-0081: split the AI page-authoring surface into honest tiers.
+
+- `PageSchema.kind` gains `'html'` and `'react'`. `'html'` is the constrained
+  parse-never-execute tier (the renamed `'jsx'`, kept as a deprecated alias);
+  `'react'` is the trusted real-React tier (executed at render by
+  `@object-ui/react-runtime`, gated behind a host capability, enterprise/private
+  only). The completeness gate now requires `source` for all three.
+- `validate-jsx-pages` lints `html`/`jsx` (constrained parse) and intentionally
+  skips `react` (real JS, not constrained JSX).

docs/adr/0081-trusted-react-page-tier.md

@@ -0,0 +1,65 @@
+# ADR-0081: A trusted `kind:'react'` page tier — real React executed in the main tree, gated by a host capability; and renaming `kind:'jsx'` → `kind:'html'`
+
+**Status**: Proposed (2026-06-30)
+**Deciders**: ObjectStack Protocol Architects
+**Builds on**: [ADR-0080](./0080-ai-authored-ui-jsx-source.md) (AI authors a *constrained* JSX text, parsed-never-executed, into the SDUI tree; the component registry is the contract; capability ≠ contract), [ADR-0033](./0033-ai-assisted-metadata-authoring.md) (AI writes metadata via draft-gated `saveMetaItem` — the human-review boundary), [ADR-0077](./0077-authoring-surface-boundary-hook-flow-validation.md) (route by intent; verifiability tier = friction tier; **code is the flagged escape hatch**), [ADR-0078](./0078-no-silently-inert-metadata.md) (no silently-inert metadata).
+**Consumers**: `@objectstack/spec` (`packages/spec/src/ui/page.zod.ts` — `kind` gains `'html'` and `'react'`; `'jsx'` kept as a deprecated alias), `@objectstack/lint` (`validate-jsx-pages` — lints `html`/`jsx`, **skips** `react`), `../objectui` `@object-ui/react-runtime` (**new** — the trusted runtime-React executor) + `@object-ui/core` (the host capability gate) + `@object-ui/components` (PageRenderer routing + the full HTML tag set).
+
+**Premise**: ADR-0080 shipped `kind:'jsx'` — a *constrained* JSX dialect parsed (never executed) into the SDUI tree. In practice that name oversold it: authors expected "JSX" to mean *any* HTML and *any* JavaScript (`useState`, `.map`, `onClick`), and the constrained, no-execution model categorically cannot do that. Two distinct things were conflated under one name. This ADR splits them: it makes the safe constrained tier **live up to a narrower, honest name (`html`)**, and adds a separate, explicitly-trusted **`react`** tier for the full-power case — available only where the operator accepts running author code.
+
+> **Trigger**: testing the merged `kind:'jsx'` feature, the author found it "名不副实" (misnamed) — basic HTML tags didn't render and scripts were impossible — and recognized that the real-React capability belongs behind a switch, enabled only in a trusted private/enterprise deployment where "running unsandboxed author code in the main React app" is an acceptable, deliberate trust decision.
+
+---
+
+## TL;DR
+
+1. **[rename] `kind:'jsx'` → `kind:'html'`.** The constrained, parse-never-execute tier (ADR-0080) is renamed to match what it is: author-written **HTML + Tailwind** (expressed as constrained JSX) compiled to the SDUI tree. `'jsx'` stays as a **deprecated alias** (already-saved pages keep loading); all authored examples/docs move to `'html'`.
+2. **[capability] The `html` tier now resolves the full safe native HTML tag set.** Previously only `div/span/table/code/label` + semantic sectioning tags were registered, so `<h1>/<p>/<a>/<ul>/<li>/<img>/<blockquote>…` failed as `unknown-component`. They are now registered as passthrough renderers — the tier is finally honest about "HTML".
+3. **[new tier] `kind:'react'` executes real React.** Its `source` is real JS/JSX (hooks, `.map`, event handlers, expressions), transpiled (Sucrase) and evaluated **in the main React tree — no sandbox** — by the new `@object-ui/react-runtime`. This is `parse = execute`: the categorical opposite of the `html` tier.
+4. **[security = trust, not sandbox] `react` is gated by a host capability, default OFF.** `CAP_REACT_PAGES` is flipped only by the *host process* (`enableCapability('react-pages')`), never by authored metadata. Open-source / multi-tenant builds ship it **off**; enterprise / private deployments — where authors are trusted and changes pass human review (draft-gating, ADR-0033) — opt in. A sandbox (iframe/worker) is the tool for *untrusted* execution; we deliberately choose **trust + review** instead, which keeps the author's code a first-class citizen of the app (shared React tree, real components, real data) at the cost of requiring the operator's explicit consent.
+5. **[runtime] Vendored, not depended.** `@object-ui/react-runtime` inlines the ~150-LOC react-runner core (MIT) so we fully own the injected **scope/imports surface** (the actual capability ceiling) and can **lazy-load** it — the transpiler ships in a separate chunk fetched only when a `react` page renders *with the capability on*.
+6. **[scope] Inject data blocks + React; leave layout to HTML.** The runtime scope exposes `React`, the curated **public data blocks** (`<ObjectTable>`, `<ObjectForm>`, charts, metrics — each a prop-driven wrapper over `SchemaRenderer`), a `<Block type=…/>` escape hatch, and the page `data`. Layout/structure is plain HTML + Tailwind (React's strength) — we do **not** bridge React children into schema-children renderers.
+7. **[lint] `react` is not linted by the constrained parser.** `validate-jsx-pages` (ADR-0080's build gate) validates `html`/`jsx` only; running the constrained JSX parser over real React source would false-error on hooks and expressions. The `react` tier's safety boundary is the **capability + human review**, not a static gate.
+
+---
+
+## The three tiers
+
+| | `kind:'html'` (was `jsx`) | `kind:'react'` (new) |
+|---|---|---|
+| Source | constrained JSX = HTML + Tailwind + registered components | real React/JSX: hooks, `.map`, `onClick`, expressions |
+| Processing | **parsed**, never executed → SDUI tree | transpiled + **executed** in the main React tree |
+| JavaScript | none (static literals) | full |
+| Safety model | safe by construction (no execution) | **trust** (capability + review); no sandbox |
+| Where it runs | OSS default ON | enterprise/private only, capability default **OFF** |
+| Author-time gate | `os build` constrained-parse lint | none (real JS); error boundary at render |
+| Contract | registry `inputs` (ADR-0080) | injected scope = the ceiling |
+
+The dividing line is exactly ADR-0080 §2's "parse ≠ execute". `html` keeps the property that *a stored string that is parsed is still data*; `react` deliberately crosses it, and pays for the crossing with an explicit operator opt-in.
+
+---
+
+## Decision
+
+### 1. Rename, with a back-compat alias
+`PageSchema.kind` becomes `enum(['full','slotted','html','react','jsx'])`. `'html'` is the canonical constrained tier; `'jsx'` is accepted as a silent **deprecated alias** so metadata saved during ADR-0080's window keeps rendering. The PageRenderer treats `html` and `jsx` identically; lint and the completeness gate (ADR-0078) treat both as source-required.
+
+### 2. Make `html` honest
+Register the safe native HTML flow/inline set (`h1–h6, p, a, ul/ol/li, dl/dt/dd, blockquote, pre, strong/em/b/i/u/small/mark/sub/sup, figure/figcaption, img, hr, br, time, address, …`) as passthrough renderers that forward standard attributes and recurse children. Excluded: anything already registered, and anything that can execute or escape (`script/style/iframe/object/embed/link/meta/form/input`, plus `button` which is the component). Defense-in-depth even though this tier never executes JS: strip `on*` handlers and `dangerouslySetInnerHTML`, neutralize `javascript:`/`data:` URLs on `<a href>`. Unknown attributes are warnings (the page still renders), per the ADR-0080 validator.
+
+### 3. Add `react` as a capability, not a default
+- **Gate**: `@object-ui/core` gains `enableCapability`/`disableCapability`/`isCapabilityEnabled` + `CAP_REACT_PAGES`. Default-closed. Host-only (a global pre-seed `globalThis.__OBJECTUI_CAPABILITIES__` is also honored for HTML-bootstrap hosts). It is structurally impossible to enable from authored metadata.
+- **Renderer**: PageRenderer routes `kind:'react'` to a renderer that — only when the capability is on — lazy-imports `@object-ui/react-runtime`, builds the scope, and renders via its error-boundaried `ReactRunner`. Capability off → a clear "this page requires the React-pages capability" notice, not a crash.
+
+### 4. Vendor the runtime; own the scope
+`@object-ui/react-runtime` inlines react-runner: `transform` (Sucrase `jsx`+`typescript`+`imports`, production), `generateElement` (eval with injected scope; `createRequire` resolves `require()` only against an explicit `imports` map — a control point), and `ReactRunner` (a component with `getDerivedStateFromError`). The capability ceiling is precisely the injected scope/imports — owning that file is why we vendor rather than depend.
+
+---
+
+## Consequences
+
+- **Honest names.** `html` does HTML; `react` does React. The conflation that made the first cut feel "鸡肋" is gone.
+- **Two safety stories, each clean.** `html` is safe by construction and stays the OSS/multi-tenant default. `react` is safe by *trust*, opt-in, and obviously so (you typed `enableCapability`).
+- **No build/deploy for either.** `html` compiles at save; `react` transpiles at render (lazy chunk). Neither needs a bundler in the author loop.
+- **AI fit.** AI writes both fluently. For `react`, correctness is bounded by the injected scope + human review (ADR-0033), not by hoping the model never writes a bad effect.
+- **Cost.** `react` runs author code in the main tree: a thrown render is caught by the error boundary, but an author can still write a slow/incorrect page. That is the accepted price of the trusted tier and the reason it is off by default. Revisit if a future need arises for *untrusted* rich pages — that would be a *different* ADR (sandboxed execution), not this one.

examples/app-showcase/src/pages/command-center-jsx.page.ts

@@ -3,8 +3,9 @@
 import { definePage } from '@objectstack/spec/ui';
 
 /**
- * Command Center — a `kind:'jsx'` page (ADR-0080). The entire layout is
- * authored as a constrained JSX + Tailwind *string*; at save time
+ * Command Center — a `kind:'html'` page (ADR-0080; formerly `kind:'jsx'`).
+ * The entire layout is authored as a constrained JSX/HTML + Tailwind *string*;
+ * at save time
  * `@objectstack/sdui-parser` compiles it (parse, never execute) into the SDUI
  * tree, which the normal PageRenderer / SchemaRenderer renders. Every tag is a
  * real registered component — `flex`, `grid`, `card`, `text`, `badge`, `stack`.
@@ -14,9 +15,9 @@ import { definePage } from '@objectstack/spec/ui';
  */
 export const CommandCenterJsxPage = definePage({
   name: 'showcase_command_center_jsx',
-  label: 'Command Center (JSX)',
+  label: 'Command Center (HTML)',
   type: 'home',
-  kind: 'jsx',
+  kind: 'html',
   source: `
 <flex direction="col" className="min-h-screen gap-10 bg-gradient-to-br from-slate-50 via-white to-indigo-50 p-10">
 

packages/lint/src/validate-jsx-pages.test.ts

@@ -23,6 +23,14 @@ describe('validateJsxPages (ADR-0080 build gate)', () => {
   it('ignores non-jsx pages', () => {
     expect(validateJsxPages({ pages: [{ name: 'full', kind: 'full', regions: [] }] })).toEqual([]);
   });
+  it('validates kind:\'html\' (the renamed tier) too', () => {
+    expect(validateJsxPages({ pages: [{ name: 'cc', kind: 'html', source: '<flex><text content="hi" /></flex>' }] })).toEqual([]);
+    expect(validateJsxPages({ pages: [{ name: 'cc', kind: 'html' }] }).some((f) => f.rule === 'jsx-page-empty-source')).toBe(true);
+  });
+  it('does NOT lint kind:\'react\' (real JS, not constrained JSX)', () => {
+    const stack = { pages: [{ name: 'rx', kind: 'react', source: 'function P(){const[n]=React.useState(0);return <div>{n}</div>}' }] };
+    expect(validateJsxPages(stack)).toEqual([]);
+  });
 });
 
 describe('validateJsxPages — full validation with a manifest', () => {

packages/lint/src/validate-jsx-pages.ts

@@ -1,9 +1,15 @@
 // Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
 //
-// Build-time diagnostics for AI-authored JSX-source pages (ADR-0080).
+// Build-time diagnostics for AI-authored HTML-source pages (ADR-0080).
+//
+// Applies to `kind:'html'` (and its deprecated alias `kind:'jsx'`) — the tier
+// whose `source` is constrained JSX/HTML parsed (never executed) to the tree.
+// `kind:'react'` (ADR-0081) is intentionally NOT linted here: its source is
+// real JavaScript, not constrained JSX, so the constrained parser would
+// false-error on hooks / expressions.
 //
 // A pure `(stack) => Finding[]` rule (ADR-0019), run from `os validate` / `os
-// build`. A `kind:'jsx'` page's `source` is a constrained JSX/Tailwind string
+// build`. An html page's `source` is a constrained JSX/Tailwind string
 // compiled (parsed, never executed) to the SDUI tree at save time. This gate
 // parses it at author time so malformed source fails loudly (ADR-0078) instead
 // of being stored and breaking only at render.
@@ -37,7 +43,8 @@ export function validateJsxPages(stack: AnyRec, opts: { manifest?: Manifest } =
   const pages = asArray(stack.pages);
   for (let p = 0; p < pages.length; p++) {
     const page = pages[p];
-    if (!page || page.kind !== 'jsx') continue;
+    // html tier (+ deprecated 'jsx' alias). react pages are not constrained JSX.
+    if (!page || (page.kind !== 'html' && page.kind !== 'jsx')) continue;
     const name = String(page.name ?? `#${p}`);
     const source = page.source;
     if (typeof source !== 'string' || source.trim() === '') {
@@ -47,7 +54,7 @@ export function validateJsxPages(stack: AnyRec, opts: { manifest?: Manifest } =
         rule: 'jsx-page-empty-source',
         where: `page "${name}"`,
         path: `pages[${p}].source`,
-        message: "kind:'jsx' page has no `source`.",
+        message: `kind:'${page.kind}' page has no \`source\`.`,
         hint: 'Author the page as a constrained JSX/Tailwind string in `source`.',
       });
       continue;

packages/spec/src/ui/page.zod.ts

@@ -358,8 +358,14 @@ export const PageSchema = lazySchema(() => z.object({
    *
    * Only meaningful when `type === 'record'`. Ignored otherwise.
    */
-  kind: z.enum(['full', 'slotted', 'jsx']).default('full')
-    .describe('Page override mode: full | slotted | jsx (ADR-0080 JSX-source authoring)'),
+  kind: z.enum(['full', 'slotted', 'html', 'react', 'jsx']).default('full')
+    .describe(
+      "Page override mode. full | slotted = structured authoring; " +
+      "html = author-written constrained JSX/HTML+Tailwind compiled (parsed, never " +
+      "executed) to the tree (ADR-0080; the legacy value 'jsx' is a deprecated alias); " +
+      "react = TRUSTED real-React source executed at render by the runtime (ADR-0081), " +
+      "gated to enterprise/private deployments.",
+    ),
 
   /**
    * Slot override map for slotted record pages.
@@ -393,18 +399,19 @@ export const PageSchema = lazySchema(() => z.object({
    * wins on any mismatch). For `full`/`slotted` pages `source` is unused.
    */
   source: z.string().optional()
-    .describe("JSX-source page text — authoritative when kind==='jsx'; compiled to the tree by @objectstack/sdui-parser at save time (parse, never execute)"),
+    .describe("Page source text. For kind==='html' (alias 'jsx') it is constrained JSX/HTML+Tailwind compiled to the tree by @objectstack/sdui-parser at save time (parse, never execute). For kind==='react' it is real React/JSX executed at render by @object-ui/react-runtime (trusted tier). Authoritative over `regions` in both."),
   /** Plugin namespaces the JSX source references — inferred at compile, checked at save AND load (ADR-0048 provenance). */
   requires: z.array(z.string()).optional()
     .describe('Plugin namespaces the JSX source references (validated at save and load)'),
 }).superRefine((page, ctx) => {
-  // ADR-0080 + ADR-0078 (completeness): a `kind:'jsx'` page with no `source`
-  // is silently inert — fail loudly at author time, do not render an empty page.
-  if (page.kind === 'jsx' && !(typeof page.source === 'string' && page.source.trim().length > 0)) {
+  // ADR-0080/0081 + ADR-0078 (completeness): an html/react/jsx page with no
+  // `source` is silently inert — fail loudly at author time, never render empty.
+  const sourceKinds = ['html', 'react', 'jsx'];
+  if (sourceKinds.includes(page.kind) && !(typeof page.source === 'string' && page.source.trim().length > 0)) {
     ctx.addIssue({
       code: 'custom',
       path: ['source'],
-      message: "A jsx page requires a non-empty `source` (ADR-0080: JSX is the source-of-truth).",
+      message: `A ${page.kind} page requires a non-empty \`source\` (the source is the source-of-truth).`,
     });
   }
 }));