feat(skill,lint): document html/react page tiers + react-source syntax gate

- objectstack-ui skill: new section on the source-authoring tiers — when to use
  kind:'html' (constrained, parsed) vs kind:'react' (real React, executed), the
  injected react scope (React/useAdapter/ObjectForm/ListView/...), a master-detail
  example, and the OS_PAGE_REACT availability note. The AI build agent now knows
  the tiers exist.
- lint: validate-react-pages transpiles kind:'react' source (Sucrase, never
  executed) so syntax errors fail at os build, not at render. Wired into
  os validate (ADR-0081). +tests (93 lint tests green).

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

Author: os-zhuang

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

@@ -15,5 +15,6 @@ ADR-0081: split the AI page-authoring surface into honest tiers.
   env toggle. The completeness gate now requires `source` for all three kinds.
 - `@objectstack/cli` console serving injects the disable global into the served
   HTML when `OS_PAGE_REACT=off` (read per request, no rebuild).
-- `validate-jsx-pages` lints `html`/`jsx` (constrained parse) and intentionally
-  skips `react` (real JS, not constrained JSX).
+- `validate-jsx-pages` lints `html`/`jsx` (constrained parse). A new
+  `validate-react-pages` transpiles `react` source with Sucrase (transpile-only,
+  never executed) so syntax errors fail at `os build` instead of at render.

packages/cli/src/commands/validate.ts

@@ -11,7 +11,7 @@ import { loadConfig } from '../utils/config.js';
 import { validateStackExpressions } from '@objectstack/lint';
 import { validateWidgetBindings } from '@objectstack/lint';
 import { validateResponsiveStyles } from '@objectstack/lint';
-import { validateJsxPages } from '@objectstack/lint';
+import { validateJsxPages, validateReactPages } from '@objectstack/lint';
 import {
   printHeader,
   printKV,
@@ -214,6 +214,32 @@ export default class Validate extends Command {
         this.exit(1);
       }
 
+      // 3c. React-source pages (ADR-0081) — a kind:'react' page's `source` is
+      //     real React executed at render. Transpile it now (Sucrase, never
+      //     executed) so syntax errors fail loudly at build, not at render.
+      if (!flags.json) printStep('Checking React-source pages (ADR-0081)...');
+      const reactFindings = validateReactPages(result.data as Record<string, unknown>);
+      const reactErrors = reactFindings.filter((f) => f.severity === 'error');
+      if (reactErrors.length > 0) {
+        if (flags.json) {
+          console.log(JSON.stringify({
+            valid: false,
+            errors: reactErrors,
+            warnings: [...widgetWarnings, ...styleWarnings, ...jsxWarnings],
+            duration: timer.elapsed(),
+          }, null, 2));
+          this.exit(1);
+        }
+        console.log('');
+        printError(`React-source page check failed (${reactErrors.length} issue${reactErrors.length > 1 ? 's' : ''})`);
+        for (const f of reactErrors.slice(0, 50)) {
+          console.log(`  \u2022 ${f.where}: ${f.message}`);
+          console.log(chalk.dim(`      ${f.hint}`));
+          console.log(chalk.dim(`      rule: ${f.rule}  at ${f.path}`));
+        }
+        this.exit(1);
+      }
+
       // 4. Collect and display stats
       const stats = collectMetadataStats(config);
 

packages/lint/package.json

@@ -2,7 +2,7 @@
   "name": "@objectstack/lint",
   "version": "11.3.0",
   "license": "Apache-2.0",
-  "description": "Static, build-time validation for an ObjectStack metadata graph — dashboard widget bindings, CEL/predicate expressions, and more. Pure (stack) => Issue[] functions shared by the CLI's `os validate` and any other consumer (e.g. AI authoring). Depends on @objectstack/spec; never on a runtime.",
+  "description": "Static, build-time validation for an ObjectStack metadata graph \u2014 dashboard widget bindings, CEL/predicate expressions, and more. Pure (stack) => Issue[] functions shared by the CLI's `os validate` and any other consumer (e.g. AI authoring). Depends on @objectstack/spec; never on a runtime.",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -22,7 +22,8 @@
   "dependencies": {
     "@objectstack/spec": "workspace:*",
     "@objectstack/formula": "workspace:*",
-    "@objectstack/sdui-parser": "workspace:*"
+    "@objectstack/sdui-parser": "workspace:*",
+    "sucrase": "^3.35.0"
   },
   "devDependencies": {
     "@types/node": "^26.0.1",

packages/lint/src/index.ts

@@ -37,6 +37,8 @@ export {
 export type { StyleFinding, StyleSeverity } from './validate-responsive-styles.js';
 export { validateJsxPages } from './validate-jsx-pages.js';
 export type { JsxPageFinding, JsxPageSeverity } from './validate-jsx-pages.js';
+export { validateReactPages } from './validate-react-pages.js';
+export type { ReactPageFinding, ReactPageSeverity } from './validate-react-pages.js';
 
 export {
   validateRecordTitle,

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

@@ -0,0 +1,33 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+import { describe, it, expect } from 'vitest';
+import { validateReactPages } from './validate-react-pages.js';
+
+describe('validateReactPages (ADR-0081 syntax gate)', () => {
+  it('passes a well-formed react page', () => {
+    const stack = {
+      pages: [{
+        name: 'wb', kind: 'react',
+        source: 'function Page(){ const [n,setN]=React.useState(0); return <button onClick={()=>setN(n+1)}>{n}</button>; }',
+      }],
+    };
+    expect(validateReactPages(stack)).toEqual([]);
+  });
+
+  it('flags an empty source', () => {
+    const f = validateReactPages({ pages: [{ name: 'wb', kind: 'react' }] });
+    expect(f.some((x) => x.rule === 'react-page-empty-source')).toBe(true);
+  });
+
+  it('flags a syntax error (unterminated JSX), at the source path', () => {
+    const f = validateReactPages({ pages: [{ name: 'wb', kind: 'react', source: 'function Page(){ return <div>oops; }' }] });
+    expect(f.some((x) => x.rule === 'react-page-syntax' && x.severity === 'error')).toBe(true);
+    expect(f.every((x) => x.path === 'pages[0].source')).toBe(true);
+  });
+
+  it('ignores non-react pages (html/full)', () => {
+    expect(validateReactPages({ pages: [
+      { name: 'h', kind: 'html', source: '<flex/>' },
+      { name: 'f', kind: 'full', regions: [] },
+    ] })).toEqual([]);
+  });
+});

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

@@ -0,0 +1,64 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+//
+// Build-time syntax gate for `kind:'react'` pages (ADR-0081).
+//
+// A react page's `source` is REAL JavaScript/JSX executed at render by the
+// runtime — so the constrained JSX parser (validate-jsx-pages) cannot check it.
+// We instead transpile it with Sucrase (the same transpiler the runtime uses),
+// transpile-ONLY — never executed — to surface syntax errors at `os build`
+// instead of at render (ADR-0078: fail loudly at author time). It does NOT
+// validate runtime behaviour (a transpiling page can still throw at render);
+// the render-time error boundary owns that.
+
+import { transform } from 'sucrase';
+
+export type ReactPageSeverity = 'error' | 'warning';
+
+export interface ReactPageFinding {
+  severity: ReactPageSeverity;
+  rule: string;
+  where: string;
+  path: string;
+  message: string;
+  hint: string;
+}
+
+type AnyRec = Record<string, unknown>;
+const asArray = (v: unknown): AnyRec[] => (Array.isArray(v) ? (v as AnyRec[]) : []);
+
+export function validateReactPages(stack: AnyRec): ReactPageFinding[] {
+  const findings: ReactPageFinding[] = [];
+  const pages = asArray(stack.pages);
+  for (let p = 0; p < pages.length; p++) {
+    const page = pages[p];
+    if (!page || page.kind !== 'react') continue;
+    const name = String(page.name ?? `#${p}`);
+    const source = page.source;
+    if (typeof source !== 'string' || source.trim() === '') {
+      findings.push({
+        severity: 'error',
+        rule: 'react-page-empty-source',
+        where: `page "${name}"`,
+        path: `pages[${p}].source`,
+        message: "kind:'react' page has no `source`.",
+        hint: 'Author the page as a real React component string in `source`.',
+      });
+      continue;
+    }
+    try {
+      // transpile-only (no eval) — catches syntax errors, unterminated JSX, etc.
+      transform(source, { transforms: ['jsx', 'typescript'], production: true });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      findings.push({
+        severity: 'error',
+        rule: 'react-page-syntax',
+        where: `page "${name}"`,
+        path: `pages[${p}].source`,
+        message: `kind:'react' source has a syntax error: ${message.split('\n')[0]}`,
+        hint: 'The source is transpiled (never executed) at build to catch syntax errors early — fix the JS/JSX.',
+      });
+    }
+  }
+  return findings;
+}

pnpm-lock.yaml

@@ -721,6 +721,96 @@ export const LeadDetailPage = definePage({
 > `page:header.properties.actions`; do **not** create a sibling action node.
 > The header renders them inline in the action slot.
 
+### AI-authored *source* pages — `kind:'html'` and `kind:'react'` (ADR-0080/0081)
+
+Besides the structured `regions` model above, a page's whole body can be written
+as a *source string* in `source`, with `kind` choosing the authoring tier. Pick
+by what the page needs:
+
+| `kind` | Author writes | JS runs? | Use when |
+|:--|:--|:--|:--|
+| `full` / `slotted` | structured `regions` / `slots` (no `source`) | — | record/detail/home layouts from the component catalogue |
+| `html` | constrained JSX = HTML + Tailwind + registered components, **parsed, never executed** | no | free-form layout / landing / dashboard that just *composes* blocks — AI's HTML+Tailwind strength, no interactivity |
+| `react` | **real React** (hooks, `.map`, `onClick`, expressions) | yes (main React tree) | complex interactive business UIs — master/detail, wizards, state-driven filters |
+
+`source` is the source-of-truth in both source tiers; `regions` is ignored. A
+`kind:'html'`/`'react'` page with no `source` fails the build (ADR-0078). The legacy
+value `kind:'jsx'` is a deprecated alias for `kind:'html'`.
+
+#### `kind:'html'` — constrained JSX, parsed (safe by construction)
+
+Tags are the **registered components** (bare names: `<flex>`, `<grid>`, `<card>`,
+`<object-table>`, `<object-form>`, `<object-metric>`, …) **plus the safe native HTML
+set** (`<h1>`–`<h6>`, `<p>`, `<a>`, `<ul>/<ol>/<li>`, `<img>`, `<blockquote>`, `<strong>`,
+…). Props come from each component's registry `inputs` (e.g. `<text content=…>`,
+`<badge label=…>`). **No JavaScript** — `onClick`, `{expr}` logic and `.map()` are NOT
+available; use `kind:'react'` for those. `os build` parses the source and fails loudly
+on unknown tags / missing required props / forbidden constructs (event handlers,
+`dangerouslySetInnerHTML`).
+
+```typescript
+export const ReleaseNotesPage = definePage({
+  name: 'release_notes', type: 'home', kind: 'html',
+  source: `
+<section className="mx-auto max-w-3xl p-10">
+  <h1 className="text-4xl font-bold">Release Notes</h1>
+  <object-metric objectName="ticket" aggregate="count" label="Open tickets" className="mt-6" />
+</section>`,
+});
+```
+
+#### `kind:'react'` — real React, executed (trusted tier)
+
+The source is real React executed at render by the runtime. The injected scope are
+**closure variables (NOT props)** — reference them directly:
+
+- `React` — hooks (`React.useState`, `React.useEffect`, …)
+- `useAdapter()` — live data: `adapter.find('obj', {…})` / `.findOne` / `.create` / `.update`
+- the public **data blocks as PascalCase components** — `<ObjectForm>`, `<ListView>`,
+  `<ObjectMetric>`, `<ObjectChart>`, `<ObjectKanban>`, … each rendering the real registered
+  component; `<Block type="…" …/>` is the escape hatch for any other type
+- `data` / `variables` / `page`
+
+Compose **layout with plain HTML + Tailwind** (React's strength); use the injected
+blocks for data. Real component props/callbacks flow through — e.g. `<ObjectForm>` honors
+`objectName` / `mode` / `recordId` / `onSuccess` / `onCancel`; `<ListView>` honors
+`objectName` / `fields` / `onRowClick` / `navigation`.
+
+Master/detail (click a row → edit it → save refreshes the list):
+
+```tsx
+export const CrmWorkbenchPage = definePage({
+  name: 'crm_workbench', type: 'home', kind: 'react',
+  source: `
+function Page() {
+  const [sel, setSel] = React.useState(null);
+  const [reload, setReload] = React.useState(0);
+  return (
+    <div className="grid grid-cols-5 gap-6 p-8">
+      <div className="col-span-3">
+        <ListView key={reload} objectName="project"
+          fields={['name','status','owner']} navigation={{ mode: 'none' }}
+          onRowClick={(r) => setSel(r)} />
+      </div>
+      <div className="col-span-2">
+        {sel
+          ? <ObjectForm objectName="project" mode="edit" recordId={sel.id}
+              onSuccess={() => { setSel(null); setReload((k) => k + 1); }} />
+          : <p className="text-slate-400">Select a project to edit.</p>}
+      </div>
+    </div>
+  );
+}`,
+});
+```
+
+**Safety / availability.** `kind:'react'` executes author code in the app, so it is gated
+by the host capability `react-pages` — **ON by default** (the platform trusts reviewed,
+draft-gated authors). A deployment that does not trust its authors turns it off server-side
+with `OS_PAGE_REACT=off`; the page then shows a "disabled" notice instead of executing.
+`os build` does NOT lint react source (it is real JS, not constrained JSX) — errors surface
+at render behind an error boundary, so always test a react page in the browser.
+
 ### Styling a page (ADR-0065) — `responsiveStyles`, NOT `className`
 
 To style a metadata-authored block, give it a **`responsiveStyles`** object — a