- /
- /
/
…` 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 that defaults ON.** `CAP_REACT_PAGES` is controlled only by the *host*, never by authored metadata. It defaults ON because ObjectStack pages are authored by trusted authors and pass human review (draft-gating, ADR-0033). A deployment that does NOT trust its authors disables it **server-side** — the ObjectStack runtime injects the disable global when `OS_PAGE_REACT=off` (one env toggle, no rebuild). 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). This is NOT an enterprise-only feature. +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** (`
`, ` `, charts, metrics — each a prop-driven wrapper over `SchemaRenderer`), a ` ` 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 | default ON; disable server-side via `OS_PAGE_REACT=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 ``. Unknown attributes are warnings (the page still renders), per the ADR-0080 validator. + +### 3. Add `react` behind a host capability that defaults ON +- **Gate**: `@object-ui/core` gains `enableCapability`/`disableCapability`/`isCapabilityEnabled` + `CAP_REACT_PAGES`. `react-pages` defaults ON. Host-only — it reads `globalThis.__OBJECTUI_CAPABILITIES_DISABLED__` (force off) and `__OBJECTUI_CAPABILITIES__` (force on); it is structurally impossible to flip from authored metadata. +- **Server opt-out**: the ObjectStack console serving (framework `cli/utils/console.ts`) injects the disable global into the served HTML when `OS_PAGE_REACT=off` — one env toggle, read per request, no rebuild. This is the single server-side switch a deployment uses to turn the tier off. +- **Renderer**: PageRenderer routes `kind:'react'` to a renderer that — 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 "React pages are disabled on this deployment" 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; a deployment that does not trust its authors sets `OS_PAGE_REACT=off`. Revisit if a future need arises for *untrusted* rich pages — that would be a *different* ADR (sandboxed execution), not this one. diff --git a/examples/app-showcase/objectstack.config.ts b/examples/app-showcase/objectstack.config.ts index 545fdf2a8d..b67dcab765 100644 --- a/examples/app-showcase/objectstack.config.ts +++ b/examples/app-showcase/objectstack.config.ts @@ -22,7 +22,7 @@ import { ChartGalleryDashboard, OpsDashboard } from './src/dashboards/index.js'; import { ShowcaseTaskDataset, ShowcaseProjectDataset } from './src/datasets/index.js'; import { allReports } from './src/reports/index.js'; import { allActions } from './src/actions/index.js'; -import { ComponentGalleryPage, ProjectWorkspacePage, ProjectDetailPage, TaskWorkbenchPage, TaskTriagePage, TaskBoardPage, TaskCalendarPage, TaskGalleryPage, TaskSchedulePage, TaskTimelinePage, TaskMapPage, TaskAllViewsPage, ActiveProjectsPage, TaskDetailPage, AccountDetailPage, ReviewQueuePage, NewProjectWizardPage, MyWorkPage, SettingsPage, StylingGalleryPage, CommandCenterPage, CommandCenterJsxPage, PageVariablesPage, ContactFormPage } from './src/pages/index.js'; +import { ComponentGalleryPage, ProjectWorkspacePage, ProjectDetailPage, TaskWorkbenchPage, TaskTriagePage, TaskBoardPage, TaskCalendarPage, TaskGalleryPage, TaskSchedulePage, TaskTimelinePage, TaskMapPage, TaskAllViewsPage, ActiveProjectsPage, TaskDetailPage, AccountDetailPage, ReviewQueuePage, NewProjectWizardPage, MyWorkPage, SettingsPage, StylingGalleryPage, CommandCenterPage, CommandCenterJsxPage, CrmWorkbenchPage, PageVariablesPage, ContactFormPage } from './src/pages/index.js'; import { allFlows } from './src/flows/index.js'; import { allWebhooks } from './src/webhooks/index.js'; import { allHooks } from './src/hooks/index.js'; @@ -154,7 +154,7 @@ export default defineStack({ apps: [ShowcaseApp], portals: allPortals, views: [TaskViews, ProjectViews, InquiryViews, BusinessUnitViews], - pages: [ComponentGalleryPage, ProjectWorkspacePage, ProjectDetailPage, TaskWorkbenchPage, TaskTriagePage, TaskBoardPage, TaskCalendarPage, TaskGalleryPage, TaskSchedulePage, TaskTimelinePage, TaskMapPage, TaskAllViewsPage, ActiveProjectsPage, TaskDetailPage, AccountDetailPage, ReviewQueuePage, NewProjectWizardPage, MyWorkPage, SettingsPage, StylingGalleryPage, CommandCenterPage, CommandCenterJsxPage, PageVariablesPage, ContactFormPage], + pages: [ComponentGalleryPage, ProjectWorkspacePage, ProjectDetailPage, TaskWorkbenchPage, TaskTriagePage, TaskBoardPage, TaskCalendarPage, TaskGalleryPage, TaskSchedulePage, TaskTimelinePage, TaskMapPage, TaskAllViewsPage, ActiveProjectsPage, TaskDetailPage, AccountDetailPage, ReviewQueuePage, NewProjectWizardPage, MyWorkPage, SettingsPage, StylingGalleryPage, CommandCenterPage, CommandCenterJsxPage, CrmWorkbenchPage, PageVariablesPage, ContactFormPage], dashboards: [ChartGalleryDashboard, OpsDashboard], books: allBooks, datasets: [ShowcaseTaskDataset, ShowcaseProjectDataset], diff --git a/examples/app-showcase/src/apps/index.ts b/examples/app-showcase/src/apps/index.ts index 66940318b5..38bc657768 100644 --- a/examples/app-showcase/src/apps/index.ts +++ b/examples/app-showcase/src/apps/index.ts @@ -65,7 +65,8 @@ export const ShowcaseApp = App.create({ icon: 'layout', children: [ { id: 'nav_gallery', type: 'page', pageName: 'showcase_component_gallery', label: 'Component Gallery', icon: 'layout-template' }, - { id: 'nav_command_center_jsx', type: 'page', pageName: 'showcase_command_center_jsx', label: 'Command Center (JSX)', icon: 'code' }, + { id: 'nav_command_center_jsx', type: 'page', pageName: 'showcase_command_center_jsx', label: 'Command Center (HTML)', icon: 'code' }, + { id: 'nav_crm_workbench', type: 'page', pageName: 'showcase_crm_workbench', label: 'CRM Workbench (React)', icon: 'layout-dashboard' }, { id: 'nav_styling_gallery', type: 'page', pageName: 'showcase_styling_gallery', label: 'Styling (ADR-0065)', icon: 'palette' }, { id: 'nav_page_variables', type: 'page', pageName: 'showcase_page_variables', label: 'Page Variables', icon: 'mouse-pointer-click' }, { id: 'nav_contact_form', type: 'page', pageName: 'showcase_contact_form', label: 'Contact Form', icon: 'mail-plus' }, diff --git a/examples/app-showcase/src/pages/command-center-jsx.page.ts b/examples/app-showcase/src/pages/command-center-jsx.page.ts index 950f0316f4..a3278078d4 100644 --- a/examples/app-showcase/src/pages/command-center-jsx.page.ts +++ b/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: ` diff --git a/examples/app-showcase/src/pages/crm-workbench.page.ts b/examples/app-showcase/src/pages/crm-workbench.page.ts new file mode 100644 index 0000000000..d79ed4c7db --- /dev/null +++ b/examples/app-showcase/src/pages/crm-workbench.page.ts @@ -0,0 +1,116 @@ +// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license. + +import { definePage } from '@objectstack/spec/ui'; + +/** + * CRM Workbench — a `kind:'react'` page (ADR-0081, the TRUSTED tier). + * + * The whole page is REAL React executed at render by `@object-ui/react-runtime` + * (hooks, event handlers, arbitrary JS) — NOT the constrained parse-never-execute + * `kind:'html'` tier. It demonstrates exactly what a real customer business UI + * needs: a master/detail workbench that COMPOSES the platform's real data + * components — ` ` (the object table) and ` ` — with React + * state to wire complex interaction the fixed page schema cannot express: + * + * - click a project row → load that record into the editor (controlled `recordId`) + * - save the form → refresh the list (`onSuccess` bumps a remount key) + * - "New project" → the same editor in create mode + * - a live KPI strip → `useAdapter()` queries the object directly + * + * The injected scope exposes `React`, `useAdapter`, and the curated public data + * blocks as PascalCase components (`ListView`, `ObjectForm`, `ObjectMetric`, …), + * each a real registered renderer. Layout is plain HTML + Tailwind. + * + * NOTE: `kind:'react'` executes author code, so it is gated by the host + * capability `CAP_REACT_PAGES`, which defaults ON (the platform trusts its + * reviewed, draft-gated authors). A deployment that does not trust its authors + * turns it off server-side with `OS_PAGE_REACT=off`, in which case + * this page renders a "disabled on this deployment" notice instead of executing. + */ +export const CrmWorkbenchPage = definePage({ + name: 'showcase_crm_workbench', + label: 'CRM Workbench (React)', + type: 'home', + kind: 'react', + source: ` +function Page() { + const adapter = useAdapter(); + const [selected, setSelected] = React.useState(null); + const [mode, setMode] = React.useState('edit'); + const [reloadKey, setReloadKey] = React.useState(0); + const [stats, setStats] = React.useState({ total: 0, active: 0 }); + + const refreshStats = React.useCallback(async () => { + if (!adapter) return; + try { + const all = await adapter.find('showcase_project', { top: 200 }); + const rows = Array.isArray(all) ? all : (all && all.records) || []; + setStats({ total: rows.length, active: rows.filter((r) => r.status === 'active').length }); + } catch (e) { /* ignore in demo */ } + }, [adapter]); + + React.useEffect(() => { refreshStats(); }, [refreshStats, reloadKey]); + + const openNew = () => { setSelected(null); setMode('create'); }; + const onRowClick = (rec) => { setSelected(rec); setMode('edit'); }; + const afterSave = () => { setSelected(null); setMode('edit'); setReloadKey((k) => k + 1); }; + + const editing = mode === 'create' || selected; + + return ( + ++ ); +}`, +}); diff --git a/examples/app-showcase/src/pages/index.ts b/examples/app-showcase/src/pages/index.ts index 96a2e874fa..83be3b380c 100644 --- a/examples/app-showcase/src/pages/index.ts +++ b/examples/app-showcase/src/pages/index.ts @@ -16,6 +16,7 @@ export { SettingsPage } from './settings.page.js'; export { StylingGalleryPage } from './styling-gallery.page.js'; export { CommandCenterPage } from './command-center.page.js'; export { CommandCenterJsxPage } from './command-center-jsx.page.js'; +export { CrmWorkbenchPage } from './crm-workbench.page.js'; export { PageVariablesPage } from './page-variables.page.js'; export { ContactFormPage } from './contact-form.page.js'; export { diff --git a/packages/cli/src/commands/validate.ts b/packages/cli/src/commands/validate.ts index e0c6084cdf..a8596e0d10 100644 --- a/packages/cli/src/commands/validate.ts +++ b/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+ + +++ +CRM Workbench
+Master/detail over
+showcase_project— real<ListView>+<ObjectForm>wired with React state.++ +++Total projects+{stats.total}+++Active+{stats.active}+++Editing+{mode === 'create' ? 'New project' : selected ? (selected.name || selected.id) : '—'}++++ ++ + {editing ? ( + +{ setSelected(null); }} + /> + ) : ( + ++ )} +🗂️+Select a project to edit, or create a new one.
+so: @@ -302,9 +313,17 @@ export function createConsoleStaticPlugin(distPath: string, options?: { isDev?: // build from being pinned to a specific mount. // // Idempotent — bails if the build already shipped a . - if (/ ' }, + { name: 'f', kind: 'full', regions: [] }, + ] })).toEqual([]); + }); +}); diff --git a/packages/lint/src/validate-react-pages.ts b/packages/lint/src/validate-react-pages.ts new file mode 100644 index 0000000000..67b4ffa527 --- /dev/null +++ b/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 `, ` `, ` `, +` `, ` `, ` `, …) **plus the safe native HTML +set** (` `–`
`, `