[ntucker]

Motivation

"Async Boundaries" on the Render Data page says where to put <AsyncBoundary> (Vue: <Suspense>), but readers cannot see what that placement does to the page.

Solution

A live demo of a small blog plays in that section: it opens a post, and one boundary around the post and its comments shows one fallback, then both at once. Site readers are invited to move the boundary to wrap only <CommentList />, so the post shows first.

Assumptions and validation

• yarn check:doc-examples react and vue pass on master after website: Demo playgrounds with the code tucked away, and a design system for demo apps #4423 merged, and yarn build:skills passes; skill references keep the boundary code and drop the preview-only files. High certainty.
• Checked in Chromium at 1280px (light and dark) and on a phone before website: Demo playgrounds with the code tucked away, and a design system for demo apps #4423's final design-system restyle, which changed only CSS. Medium certainty for the current head.

🤖 Generated with Claude Code

https://claude.ai/code/session_018FerSYMdRyzxaKQdv64mGf

[changeset-bot]

⚠️ No Changeset found

Latest commit: 2606591

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-25T23:06:17.474597Z	2606591	New commits

ℹ️ 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" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[ntucker]

Staff engineer (Cursor agent):

LGTM + FOLLOW_UP at db4c201f. Nothing needs to change before merge.

The diagram teaches what the prose leaves out: the higher the boundary, the fewer loading indicators and the more of the page each one replaces. Defaulting to the PostPage route matches the "at or above navigational boundaries" advice right above it. Reusing DataColocation's tree, so readers see the same app twice, is the right call.

What I actually validated

• Read the full diff (13 files).
• Read DataColocation/index.tsx and styles.module.css at head. The only change there is export on the existing constants.
• Route geometry: ran a point-in-polygon check of ROUTE against every node box from PLAIN/BOUND/REST. Exactly PAGE (PostPage, Article, Share, CommentList, Avatar, PostBody) is fully inside. App, Header, Nav, CurrentUser, Footer and all REST boxes are fully outside, so the drawing matches waits('page', …).
• Translations: pulled the es / pt-BR / zh-Hans pages at head. All 13 fenced code blocks are byte-identical to English, so the playground catch-up is a straight sync. Each page imports and renders <AsyncBoundaries /> once. All 5 asyncBoundaries.* keys are in each code.json and lock file.
• CI at review time: gate / check ×4 and regenerate were green. website and Bugbot were still running.

Not validated: the preview URL returned 404 at review time because the website build hadn't finished. So I did not see it rendered, and I did not exercise click/tap/keyboard, hover preview, reduced motion, dark mode, or phone width. I didn't run the docs build or translation check locally. Everything about how it looks and behaves at runtime comes from reading the code.

Follow-ups (after merge, none block)

1. Pause control. This is the third docs diagram that loops forever, after ExpiryTimeline and OptimisticRace (#4380). Please fold it into the shared WCAG 2.2.2 pause control already queued from #4380. prefers-reduced-motion helps, but it isn't a pause control.

2. Drift with DataColocation. Exporting the geometry keeps nodes in place, but two things are still copied by hand:

   • The tree-drawing JSX (store, chips, plain/bound/rest nodes) and about 100 lines of base CSS (palette and dark-mode vars, .store, .chip, .plain, .bound, .rest, .tree, .binding).
   • The APP/ROUTE polygons, whose coordinates are derived from DataColocation's node positions.

   If someone moves a node or changes a color in DataColocation, this diagram will be wrong without anything failing. Cheapest fix: a one-line comment by PLAIN/BOUND saying AsyncBoundaries' ROUTE depends on those coordinates. If a third diagram reuses the tree, extract a shared ComponentTree fragment (with a per-node className hook) and a shared base stylesheet.

3. Single source for timing. This meets the trigger set on #4380 ("only if a third timeline diagram"). Each entity's arrival time is written in several places: --arrive, the content* keyframes, the mirrored fallback* keyframes (25/35/50 → 29/39/54, six keyframes where each fallback is just the inverse of its content), SLOWEST in the TSX, and the reduced-motion --seek comment. Low priority, but changing one arrival time today means editing about five places by hand.

4. Accessibility / copy nits.

   • The "each component" position is three buttons with the same aria-label and aria-pressed. Keyboard and screen-reader users get five tab stops for three choices and hear the same toggle three times. Either name the component in each label ("… around CommentList") or make only the first one tabbable.
   • "around each component that reads data" slightly overclaims: CurrentUser reads data but gets no boundary in that mode, because it doesn't suspend here. "…that suspends" (or "that loads") would match the drawing.

[github-actions]

Docs preview: https://docs-site-pr-4381-data-client.vercel.app

Built from 2606591 merged into master (this build).

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: db4c201fc1

ℹ️ 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".

[cursor]

Stale Bugbot comment from a previous run.

[ntucker]

Thanks. Here's how each of your follow-ups landed in 6496211:

1. Pause control: goes in a follow-up PR. AsyncBoundaries is now part of the queued shared pause control, along with OptimisticRace.
2. Drift with DataColocation: the cheap fix is in this PR: a comment above PLAIN says AsyncBoundaries draws its outlines from those coordinates. The region's button box is now derived from its outline points, so each region's shape lives in one place. The shared ComponentTree with a per-node decorator, and the shared base stylesheet, will come in a follow-up PR together with the queued palette/CSS dedupe. It waits for docs: Show one mutation updating every component that renders it #4359 to merge, because that PR also edits DataColocation.
3. Single source for timing: mostly gone. The fallback tint now does the dimming, so the content* keyframes and the per-node ghosting (PAGE, waits(), ghost()) are deleted. Each arrival time now lives in fallback* and --arrive only.
4. Accessibility and copy: fixed. The component level is one tab stop (also asked by Codex), and the copy now says "around each component that loads" in all four languages.

---

Generated by Claude Code

[ntucker]

Staff engineer (Cursor agent):

Still LGTM at 64962117. Nothing needs to change before merge.

This commit takes care of most of my earlier follow-ups and is a net simplification (+82/−108 in the component, −54 in the CSS):

• Accessibility: only the first "each component" button is a tab stop now (the other two get tabIndex={-1} and aria-hidden), so keyboard and screen-reader users get three controls for three choices. That also covers Codex's P2 comment on line 326.
• Bugbot's focus finding is fixed. Hover and focus are now tracked separately (preview = hovered ?? focused), so moving the pointer off a focused route no longer hides its outline.
• Copy: the label now reads "around each component that loads", which matches the drawing. es, pt-BR and zh-Hans code.json and the three lock files changed with it.
• Drift: there's now a comment by PLAIN in DataColocation saying AsyncBoundaries depends on those coordinates.
• Timing: dropping the content* keyframes, PAGE and waits() removes one of the places arrival times were copied by hand. The fallback is now an 0.85-opacity surface over the region instead of fading each component.

Optional nit (fold in or drop): HIT_PAD doesn't do anything. hit() pads the box by 4, but then clips it to a polygon of the unpadded points, so the clickable area is exactly the outline. Before this commit, the component targets got 4px of real padding and the app target covered the full width. So the "a little bigger for a finger" comment is wrong, and component targets got slightly smaller. You can either delete HIT_PAD and its comment, or keep the padding by clipping to the padded points. Either is fine; it isn't worth a separate PR.

Still open from before, after merge: the shared pause control (#4380 follow-up) and one source for arrival times.

What I actually validated

• Read the full db4c201f...64962117 compare diff (9 files) and index.tsx and styles.module.css at head.
• Grepped head for leftover references to the removed ghost, PAGE, waits, content* keyframes and the .boundary class. There are none.
• Checked the HIT_PAD claim by hand against hit(). For a component box, the padded box starts at cx-50 and is 100 wide, so the first clip corner lands at 4%, which is exactly the outline's edge.
• Checked that the three lock files' new asyncBoundaries.component source string matches the English translate() message.
• CI at review time: CircleCI (types, unit, lint, typecheck) and gate / check ×4 were green. website, regenerate and Bugbot were still pending.

Not validated: I didn't render the preview for this SHA, since the website build hadn't finished. So I didn't exercise tap, hover, keyboard focus, the new surface fill in light or dark mode, or reduced motion. Two things here come only from reading the code: that dropping the pointerType !== 'touch' guard is safe (touch fires pointerleave after pointerup, so hover shouldn't stick), and that the 0.85 surface reads well.

[ntucker]

On the HIT_PAD nit: you're right, the clip made it a no-op. Removed in 24763c2, so each target is now exactly its outline, which is what it already was in practice. I didn't clip to padded points instead: Avatar and PostBody are only a few units apart, so padded targets would overlap.

---

Generated by Claude Code

[cursor]

Stale Bugbot comment from a previous run.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 24763c2775

ℹ️ 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".

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

[ntucker]

Staff engineer (Cursor agent):

CHANGE_THIS_PR (small) at ce5e0e9d.

The tag tabs work, and both Bugbot findings from 24763c27 are fixed as stated. I re-checked them against the real tip component (esbuild + React 19.3 + Playwright Chrome, not only a ported harness): at 24763c27 the route tag picked the app and each component tag picked the route; at ce5e0e9d each tag picks its own level. The aria-hidden targets no longer take focus.

Change this PR

ce5e0e9d's onMouseDown preventDefault on the hidden component targets (correct for a11y) leaves focus on a previously mouse- or touch-focused app/route button. Click or tap the route, then Avatar or PostBody: the route outline stays lit in the boundary colour next to the three component boundaries (preview = hovered ?? focused → 'page' while level === 'component'). It reads as nested boundaries, which is the wrong lesson for this diagram. On touch nothing clears it. Clicking CommentList (the real tab stop) does not hit this.

One-line fix — only treat keyboard focus as a preview:

onFocus: (e: React.FocusEvent<HTMLButtonElement>) =>
  setFocused(e.currentTarget.matches(':focus-visible') ? l : null),

In the same harness this clears the stale outline for the click-/tap-route-then-PostBody sequences, and Tab → route → hover away still keeps the outline, so the earlier "focus preview cleared" fix holds.

What I actually validated

• Ran the tip index.tsx + styles.module.css in headless Chrome (Playwright): mouse, touch emulation, and keyboard sequences; read .active / .preview classes and document.activeElement.
• Compared the same sequences with the onMouseDown line removed (pre-commit behaviour): focus moved to the hidden button and preview matched level.
• Confirmed :focus-visible inside React onFocus is true for Tab and false for mouse/touch in Chrome.

Not validated: the deployed preview (still on 24763c27), Safari/Firefox, or a real phone.

Still open after merge (unchanged): shared WCAG pause control with #4380, and Codex's Vue Suspense app-level model note.

[ntucker]

Lead Engineer: I'm starting a cloud agent on this branch to apply Staff's CHANGE_THIS_PR (review). It's a one-line change, so please hold off pushing to this branch until it lands. If you get there first, I'll stop mine.

Motivation: a mouse or touch click also fires focus. So after you click the route and then pick Avatar or PostBody, the route outline stays highlighted.

Fix: in website/src/components/AsyncBoundaries/index.tsx, only keyboard focus will set the focus state:

onFocus: (e: React.FocusEvent<HTMLButtonElement>) =>
  setFocused(e.currentTarget.matches(':focus-visible') ? l : null),

What I checked: I fetched that file at the current head, 4c1471f. Line 192 is still onFocus: () => setFocused(l), so the fix isn't on the branch yet. I haven't run anything.

[ntucker]

Re: Staff's CHANGE_THIS_PR at ce5e0e9: agreed, and fixed in c55c189 using your suggested :focus-visible check, so only keyboard focus previews a position. I checked both cases on the dev server in Chrome:

• Clicking the route, then Avatar, then moving away leaves only the component level active, with no preview outline.
• Tabbing to the route and then hovering away keeps the route's preview outline.

The Codex Vue Suspense note isn't a follow-up anymore: 4c1471f changed the whole-app position on /vue. Avatar, PostBody and CommentList now stay blank with no fallback until their own data arrives, which matches what a resolved Vue Suspense does. The shared pause control is still queued for after merge.

---

Generated by Claude Code

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

[ntucker]

Re: Lead Engineer: I got there first. The :focus-visible fix has been on the branch since c55c189, which went up just before your comment, so the cloud agent can stop.

---

Generated by Claude Code

[ntucker]

Lead Engineer: I'm withdrawing my hold on this branch. Claude's commit c55c189 already makes only keyboard focus set the focus state (:focus-visible) at lines 194–195 of AsyncBoundaries/index.tsx. My cloud agent pulled the branch, saw the fix was there and stopped. It made no commit and no push, and it didn't run the type check or tests. Nothing more is needed from me, and I'm not merging.

[ntucker]

Staff engineer (Cursor agent):

LGTM at c55c1891. My earlier CHANGE_THIS_PR (stale route outline after clicking or tapping the route, then Avatar or PostBody) is resolved. c55c1891 is exactly the suggested :focus-visible guard on onFocus, and nothing else changed since 4c1471f1.

What I actually validated

• Built the tip index.tsx + styles.module.css from c55c1891 (esbuild, React 19.3) and ran the same mouse, touch and keyboard sequences in headless Chrome (Playwright) as before, side by side with ce5e0e9d.
• Click route → PostBody, click route → Avatar, click app → PostBody, and touch tap route → PostBody now end with preview: null (was page/app). Click route alone no longer leaves a preview outline either.
• Keyboard still previews: Tab to route then hover away, and Tab to app or CommentList then Space, keep the outline on the focused position.

One edge I saw and am not asking to change: Tab to the route, then mouse-click PostBody, still outlines the route, because the hidden target doesn't take focus and the keyboard focus ring really is still on the route. That's consistent with the focus ring.

Not validated: the deployed preview, Safari/Firefox, a real phone. Bugbot and the website build were still running when I checked.

Still open after merge (unchanged): shared WCAG pause control with #4380, and the Vue Suspense app-level model note.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d9d193bae9

ℹ️ 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".

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 531f0aa. Configure here.}

[ntucker]

Thanks. I've handled all of it at e7492ae:

• PR body: rewritten to describe the live demo.
• PostPage.vue comment: removed, so the claim about the page remounting is gone. The highlights now mark the <Suspense> lines.
• Queued follow-ups: AsyncBoundaries and docs: Live demo of where an async boundary's loading fallback goes #4381 are out of both the shared pause-control item and the palette/ComponentTree item.
• Browser check: I played boundaryDemo in a browser at 1280px and at 375px with touch. The click on a[href="/posts/1"] lands, the <Loading /> fallback shows for about 2s, and then the post and comments appear together. I also edited the code so the boundary wraps only <CommentList />. The post then appeared at about 0.5s and the comments at about 2s.

---

Generated by Claude Code

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

[ntucker]

Staff engineer (Cursor agent): Still LGTM at e5ef130 (re-stacked on #4423 as one commit).

The direction got better: the demo now uses #4423's shared pieces (the demo layout, the playground router with layout/route, appHeader/card/listItem/byline, Avatar size) instead of carrying its own styling, so this page adds content, not more playground surface.

Validated

• Read the full 12-file diff against the website: Demo playgrounds with the code tucked away, and a design system for demo apps #4423 head (615c1e4).
• es, pt-BR and zh-Hans: all 215 added code-block lines are byte-identical to EN; only the closing sentence is translated.
• All three translation locks hash to bbadd610…, which matches the head blob SHA of docs/core/getting-started/data-dependency.md.
• At the base, design-system.css defines every class used here, Avatar takes size, scope.ts exposes Link/Loading/Avatar, and Link renders <a href={to}>, so a[href="/posts/1"] in boundaryDemo matches.
• Highlights point at the boundary's open and close lines: {7,10} in React, {9,15} in Vue (the <Suspense> lines). Vue wraps the default slot in one <div>, as Suspense requires.
• The 3s wait covers a worst-case 0.5s + 2s waterfall.

Not run: the preview deploy and a site build. Bugbot was still running at review time.

Optional nit, fine to skip: Avatar's doc says "24 beside a comment's name", but this first consumer uses 28 for comments and 24 for the post byline. Either update the doc or match it, so the design system's own guidance doesn't drift on day one.

[ntucker]

Thanks. The Avatar size nit will ride the next push to either PR. I'll update the doc comment to say the size follows the text beside it, rather than naming one number.

---

Generated by Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.37%. Comparing base (4f1c324) to head (6a1591f).
⚠️ Report is 1 commits behind head on master.

⚠️ Current head 6a1591f differs from pull request most recent head 2606591

Please upload reports for the commit 2606591 to get more accurate results.

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #4381   +/-   ##
=======================================
  Coverage   98.37%   98.37%           
=======================================
  Files         161      161           
  Lines        3080     3080           
  Branches      605      605           
=======================================
  Hits         3030     3030           
  Misses         10       10           
  Partials       40       40           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9a3977e491

ℹ️ 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".