Wes/core architecture client rework - #2749
Open
bwreid wants to merge 11 commits into
Open
Conversation
Adds three new MDX block components for packages/core/docs/content reference pages: Signature (a collapsible function/hook/action signature with parameter and return-type breakdown), and Image/Video (full width or aligned left/right with paired markdown text, alt text, and a caption). Video additionally supports reduced-motion-aware autoplay and looping. Documented all three on /docs/docs-components with live examples.
Hovering the image reveals a top-right button that opens it in a larger popup, matching the Escape/click-outside/close-button contract already established for diagrams. Paired left/right text and the caption render stacked below the image inside the popup instead of beside it, since the two-column layout only makes sense at the inline aligned size. Video is unchanged.
Adds a static "Function signature" caption above the component (no longer forced to uppercase, which mangled camelCase function names), and a thin border around the expanded parameter/return content so it's clear where the expanded state ends.
Covers app/ and public/: where the display of an agent-native app is built, the browser runtime pieces nothing else documents (root.tsx, AppProviders, entry points), and static assets. Links out to the focused Data & Sync and Agent Chat pages for the data/agent hooks.
Covers useActionQuery, useActionMutation, callAction, and useDbSync: the action hooks app/ uses to read, write, and stay live-synced with the same actions the agent calls. Examples are grounded in a real ticket-support reference app rather than a hypothetical domain.
Covers askUserQuestion, useAgentChatGenerating, sendToAgentChat, openAgentSettings, and dynamic suggestions: the client entry points into agent chat. Ordered around a running "Draft Response" ticket example, built up from askUserQuestion() through the full handler.
Contributor
Visual recap — skippedThe visual recap job did not run for this pull request. This is informational only and does not block the PR. Recap skipped for |
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
Covers file-based client routing in app/routes/ with React Router v8: the file-to-URL table (including the trailing-underscore convention for opting out of layout nesting), adding a page, dynamic params, and navigation. Distinguishes client routes from the separate server-side routing system, and points to the Routes page for that.
…Points Advanced was overloaded with unrelated concerns. Agent Chat Context State moves into client-agent-chat.mdx (it's part of Agent Chat, just deeper). useChangeVersion/useChangeVersions and the latency-model explainer move to a new Sync Internals page, the real depth for this previously existed only in the dev-facing real-time-sync skill, not in any public doc. The SSR entry-point content moves to a new Entry Points page. Also trims the duplicated TAB_ID/jitter-prevention walkthrough on Advanced down to a link to context-awareness's existing version, adds the previously-undocumented readClientAppStateMany plus the failure behavior of the application-state functions, and wires both new pages into the nav (English labels only; other-locale nav labels are a separate uncommitted follow-up).
bwreid
marked this pull request as ready for review
August 10, 2026 18:55
![builder-io-integration[bot]](https://avatars.githubusercontent.com/in/353721?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Builder reviewed your changes and found 5 potential issues 🔴
Review Details
Code Review Summary
PR #2749 adds a substantial draft Client documentation section and registers new Signature, Image, and Video docs blocks with shared media layout/lightbox behavior. The overall structure is sensible: schemas are centralized, blocks are registered in both runtime and MDX parsing registries, media URLs are constrained, and the new Client pages are draft-gated. The docs server was reachable and server-side checks confirmed draft routes return 404 when drafts are disabled and 200 when enabled.
Risk: Standard, because this is primarily documentation/UI infrastructure but includes new interactive rendering and public content contracts.
Key Findings
- 🔴 HIGH:
sendToAgentChatdocumentation incorrectly promises thatcontextis hidden, although it is appended to the visible local chat message. - 🟡 MEDIUM: Several copy-paste/API-contract examples are incorrect (
writeClientAppState(undefined), prefill behavior inuseAgentChatGenerating, missinguseStateimport, and reversed sync fallback semantics). - 🟡 MEDIUM: Public docs contain a localhost link, missing rendered media assets, and incomplete locale keys.
- 🟡 MEDIUM: The media lightbox does not manage focus, and the draft-enabled sidebar creates two entries both labeled “Client”.
Browser testing was attempted after the code review, but all planned cases were couldnt_verify because the browser executor had no browser automation tools. Server-side route checks and the missing /videos/product-tour.mp4 404 were confirmed; a browser rerun is needed when tooling is available.
🧪 Browser testing: Attempted after review; could not verify because browser automation tooling was unavailable.
Replaces the hand-written argument bullet lists for useActionQuery, useActionMutation, and callAction, and the full options table for useDbSync, with Signature blocks. Folds each hook's trailing behavior paragraph into its Signature's returns description instead of stating it twice. Also documents two real useDbSync options that existed in source but weren't covered anywhere: actionInvalidatePredicate and suppressActionInvalidationFor.
Corrects sendToAgentChat's context-visibility claim, the useAgentChatGenerating prefill caveat, writeClientAppState(undefined) behavior, useDbSync's reversed fallbackInterval semantics, a localhost link, and a 404ing video asset on the live docs-components page. Adds focus management to the media lightbox and disambiguates the draft Client nav group from the legacy Client page.
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
1 participant
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.
Expands upon and improves the "Client" page of the Core Architecture section.