feat(react): support pure computed render functions (#1246)

* feat(react): support owned pure computed functions

* chore(react): align computed API with merged element

Author: blove

apps/website/content/AGENTS.md.template

@@ -107,3 +107,5 @@ Repeat Loops has an experimental local React preview at https://threadplane.ai/d
 Component Registry has an experimental local React preview at https://threadplane.ai/docs/render/guides/registry?frontend=react. The host supplies stable read-only component maps to installed native RenderSpec. Badge display chooses Registered, Omitted or an authored Fallback; fallback receives resolved props, element key and loading, while container views display native children exactly once. Choice survives partial playback, seek, Reset and sample selection without modifying JSON; reload restores Registered. Complete admission permits only four authored literal types. No backend runtime, model request or execution configuration is used. Build with `npx nx build cockpit-render-registry-react` and verify with `npx nx e2e cockpit-render-registry-react`.
 
 Element Rendering has an experimental local React preview at https://threadplane.ai/docs/render/api/render-spec-component?frontend=react. Installed native RenderSpec owns ordered children, nested readonly views and visibility from explicit caller-owned boolean state. Show detail survives playback, seek, Reset and sample changes without modifying JSON; reload shows detail. The bounded projection withholds the conditional node until its exact /showDetail visibility path is available, preventing hidden text from flashing during partial playback. No backend runtime, model request or execution configuration is used. Build with `npx nx build cockpit-render-element-rendering-react` and verify with `npx nx e2e cockpit-render-element-rendering-react`.
+
+The private React render entry also accepts an optional `ReactRenderFunctions` host map for authored `$computed` expressions. `RenderComputedFunction` receives owned recursively frozen arguments and synchronously returns `RenderValue`; calculations must be pure and can run repeatedly during React rendering. Plain or null-prototype maps admit own callable data entries, including non-enumerable entries, and reject accessors, symbols and non-callable values. Results retain the existing plain-data ownership guards. This adds no actions, watchers, state ownership or asynchronous effect execution, and raw specs still cannot contain executable callbacks.

apps/website/content/CLAUDE.md.template

@@ -107,3 +107,5 @@ Repeat Loops has an experimental local React preview at https://threadplane.ai/d
 Component Registry has an experimental local React preview at https://threadplane.ai/docs/render/guides/registry?frontend=react. The host supplies stable read-only component maps to installed native RenderSpec. Badge display chooses Registered, Omitted or an authored Fallback; fallback receives resolved props, element key and loading, while container views display native children exactly once. Choice survives partial playback, seek, Reset and sample selection without modifying JSON; reload restores Registered. Complete admission permits only four authored literal types. No backend runtime, model request or execution configuration is used. Build with `npx nx build cockpit-render-registry-react` and verify with `npx nx e2e cockpit-render-registry-react`.
 
 Element Rendering has an experimental local React preview at https://threadplane.ai/docs/render/api/render-spec-component?frontend=react. Installed native RenderSpec owns ordered children, nested readonly views and visibility from explicit caller-owned boolean state. Show detail survives playback, seek, Reset and sample changes without modifying JSON; reload shows detail. The bounded projection withholds the conditional node until its exact /showDetail visibility path is available, preventing hidden text from flashing during partial playback. No backend runtime, model request or execution configuration is used. Build with `npx nx build cockpit-render-element-rendering-react` and verify with `npx nx e2e cockpit-render-element-rendering-react`.
+
+The private React render entry also accepts an optional `ReactRenderFunctions` host map for authored `$computed` expressions. `RenderComputedFunction` receives owned recursively frozen arguments and synchronously returns `RenderValue`; calculations must be pure and can run repeatedly during React rendering. Plain or null-prototype maps admit own callable data entries, including non-enumerable entries, and reject accessors, symbols and non-callable values. Results retain the existing plain-data ownership guards. This adds no actions, watchers, state ownership or asynchronous effect execution, and raw specs still cannot contain executable callbacks.

apps/website/public/AGENTS.md

@@ -107,3 +107,5 @@ Repeat Loops has an experimental local React preview at https://threadplane.ai/d
 Component Registry has an experimental local React preview at https://threadplane.ai/docs/render/guides/registry?frontend=react. The host supplies stable read-only component maps to installed native RenderSpec. Badge display chooses Registered, Omitted or an authored Fallback; fallback receives resolved props, element key and loading, while container views display native children exactly once. Choice survives partial playback, seek, Reset and sample selection without modifying JSON; reload restores Registered. Complete admission permits only four authored literal types. No backend runtime, model request or execution configuration is used. Build with `npx nx build cockpit-render-registry-react` and verify with `npx nx e2e cockpit-render-registry-react`.
 
 Element Rendering has an experimental local React preview at https://threadplane.ai/docs/render/api/render-spec-component?frontend=react. Installed native RenderSpec owns ordered children, nested readonly views and visibility from explicit caller-owned boolean state. Show detail survives playback, seek, Reset and sample changes without modifying JSON; reload shows detail. The bounded projection withholds the conditional node until its exact /showDetail visibility path is available, preventing hidden text from flashing during partial playback. No backend runtime, model request or execution configuration is used. Build with `npx nx build cockpit-render-element-rendering-react` and verify with `npx nx e2e cockpit-render-element-rendering-react`.
+
+The private React render entry also accepts an optional `ReactRenderFunctions` host map for authored `$computed` expressions. `RenderComputedFunction` receives owned recursively frozen arguments and synchronously returns `RenderValue`; calculations must be pure and can run repeatedly during React rendering. Plain or null-prototype maps admit own callable data entries, including non-enumerable entries, and reject accessors, symbols and non-callable values. Results retain the existing plain-data ownership guards. This adds no actions, watchers, state ownership or asynchronous effect execution, and raw specs still cannot contain executable callbacks.

apps/website/public/CLAUDE.md

@@ -107,3 +107,5 @@ Repeat Loops has an experimental local React preview at https://threadplane.ai/d
 Component Registry has an experimental local React preview at https://threadplane.ai/docs/render/guides/registry?frontend=react. The host supplies stable read-only component maps to installed native RenderSpec. Badge display chooses Registered, Omitted or an authored Fallback; fallback receives resolved props, element key and loading, while container views display native children exactly once. Choice survives partial playback, seek, Reset and sample selection without modifying JSON; reload restores Registered. Complete admission permits only four authored literal types. No backend runtime, model request or execution configuration is used. Build with `npx nx build cockpit-render-registry-react` and verify with `npx nx e2e cockpit-render-registry-react`.
 
 Element Rendering has an experimental local React preview at https://threadplane.ai/docs/render/api/render-spec-component?frontend=react. Installed native RenderSpec owns ordered children, nested readonly views and visibility from explicit caller-owned boolean state. Show detail survives playback, seek, Reset and sample changes without modifying JSON; reload shows detail. The bounded projection withholds the conditional node until its exact /showDetail visibility path is available, preventing hidden text from flashing during partial playback. No backend runtime, model request or execution configuration is used. Build with `npx nx build cockpit-render-element-rendering-react` and verify with `npx nx e2e cockpit-render-element-rendering-react`.
+
+The private React render entry also accepts an optional `ReactRenderFunctions` host map for authored `$computed` expressions. `RenderComputedFunction` receives owned recursively frozen arguments and synchronously returns `RenderValue`; calculations must be pure and can run repeatedly during React rendering. Plain or null-prototype maps admit own callable data entries, including non-enumerable entries, and reject accessors, symbols and non-callable values. Results retain the existing plain-data ownership guards. This adds no actions, watchers, state ownership or asynchronous effect execution, and raw specs still cannot contain executable callbacks.

fixtures/react-parity/runtime/render-runtime.mjs

@@ -54,4 +54,75 @@ assert.equal(
   renderToStaticMarkup(createElement(RenderSpec, { spec: null, registry })),
   ''
 );
+const produced = { list: [{ value: 42 }] };
+const functions = Object.create(null);
+Object.defineProperty(functions, 'inner', { value: () => produced });
+functions.outer = (args) => {
+  assert.equal(Object.isFrozen(args), true);
+  assert.equal(Object.isFrozen(args.value), true);
+  assert.equal(Object.isFrozen(args.value.list), true);
+  assert.notEqual(args.value, produced);
+  return String(args.value.list[0].value);
+};
+functions.rowLabel = (args) => `${args.value}/${args.index}`;
+functions.constructor = () => 'own constructor';
+const computed = {
+  root: 'root',
+  elements: {
+    root: { type: 'Box', props: {}, children: ['value', 'rows', 'named'] },
+    value: {
+      type: 'Text',
+      props: {
+        text: { $computed: 'outer', args: { value: { $computed: 'inner' } } },
+      },
+    },
+    rows: {
+      type: 'Box',
+      props: {},
+      children: ['row'],
+      repeat: { statePath: '/rows', key: 'id' },
+    },
+    row: {
+      type: 'Text',
+      props: {
+        text: {
+          $computed: 'rowLabel',
+          args: { value: { $item: 'text' }, index: { $index: true } },
+        },
+      },
+    },
+    named: { type: 'Text', props: { text: { $computed: 'constructor' } } },
+  },
+};
+const computedHtml = renderToStaticMarkup(
+  createElement(RenderSpec, { spec: computed, registry, state, functions })
+);
+assert.match(computedHtml, /<p>42<\/p>/);
+assert.match(computedHtml, /<p>A\/0<\/p><p>B\/1<\/p>/);
+assert.match(computedHtml, /<p>own constructor<\/p>/);
+assert.equal(Object.isFrozen(produced), false);
+assert.equal(Object.isFrozen(produced.list), false);
+for (const label of [
+  () => Promise.resolve('later'),
+  () => new Date(0),
+  () => Infinity,
+]) {
+  assert.throws(
+    () =>
+      renderToStaticMarkup(
+        createElement(RenderSpec, {
+          spec: {
+            root: 'text',
+            elements: {
+              text: { type: 'Text', props: { text: { $computed: 'label' } } },
+            },
+          },
+          registry,
+          functions: { label },
+        })
+      ),
+    TypeError
+  );
+}
 console.log('Installed read-only RenderSpec runtime contracts passed.');
+console.log('Installed pure computed RenderSpec contracts passed.');

fixtures/react-parity/runtime/render-types.tsx

@@ -4,6 +4,9 @@ import {
   type RenderSpecData,
   type RenderViewProps,
   type ReactRenderRegistry,
+  type ReactRenderFunctions,
+  type RenderComputedFunction,
+  type RenderValue,
 } from '@threadplane/react/render';
 const registry: ReactRenderRegistry = {
   Text: ({ props }) => <p>{String(props['text'])}</p>,
@@ -15,6 +18,21 @@ const spec = {
 export const view = (
   <RenderSpec spec={spec} registry={registry} state={{ count: 1 } as const} />
 );
+const functions: ReactRenderFunctions = {
+  uppercase: ({ value }) => String(value).toUpperCase(),
+};
+export const computedView = (
+  <RenderSpec spec={spec} registry={registry} functions={functions} />
+);
+export function computedContracts(args: Readonly<Record<string, RenderValue>>) {
+  // @ts-expect-error installed callback arguments are readonly
+  args['changed'] = 1;
+  // @ts-expect-error installed pure functions cannot be asynchronous
+  const asynchronous: RenderComputedFunction = async () => 'later';
+  // @ts-expect-error installed result values cannot be executable callbacks
+  const executable: RenderComputedFunction = () => () => 1;
+  return { asynchronous, executable };
+}
 export function readonlyContracts(
   data: RenderSpecData,
   element: RenderElementData,

libs/react/README.md

@@ -292,6 +292,42 @@ resolvers. Repeat containers render their children per array item, with `$item`,
 key preserves mounted identity across reorder; absent or unsupported keys use the
 item index. String, number and index identities have separate namespaces.
 
+Supply an optional `functions` map for authored `$computed` expressions:
+
+```tsx
+import type { ReactRenderFunctions } from '@threadplane/react/render';
+
+const functions: ReactRenderFunctions = {
+  uppercase: ({ value }) => String(value).toUpperCase(),
+};
+const computedSpec = {
+  root: 'title',
+  elements: {
+    title: {
+      type: 'Title',
+      props: { text: { $computed: 'uppercase', args: { value: { $state: '/title' } } } },
+    },
+  },
+} as const;
+<RenderSpec spec={computedSpec} state={{ title: 'Trip recap' }} registry={registry} functions={functions} />;
+```
+
+`RenderComputedFunction` receives an owned, recursively frozen argument record
+and synchronously returns `RenderValue`. Literal, state, item, index and nested
+computed arguments use the existing resolver. Function results cross the same
+plain-data ownership boundary as other resolved values. Promises, executable
+callbacks and non-plain results are rejected. Calculations must be pure: React
+can evaluate them repeatedly during rendering, and no call count, caching or
+effect behavior is promised. Callback errors propagate as render errors.
+
+Function maps must be plain records or null-prototype records. Every own
+string-keyed callable data property is registered, including non-enumerable
+entries; inherited names are unavailable. Accessors, symbol keys and non-callable
+entries are rejected without invoking getters. The caller's map and data remain
+unfrozen and unmodified. Unknown function names resolve to `undefined` with the
+upstream warning behavior. This optional host map does not permit executable
+callbacks in raw specs or add actions, watchers or state ownership.
+
 State and resolved values must be finite, acyclic plain data. Functions, symbols,
 accessors and non-plain objects are rejected. Raw props also reject `undefined`
 and own `__proto__` keys because the upstream raw-prop resolver cannot preserve