# Suspense Boundary Strategy

## Objective

Place loading boundaries so the page fills in usefully rather than all at once.

A decision about where the interface is allowed to wait, so slow regions never hold up the parts that are ready.

## Before You Begin

This feature is being added to an application that already exists and already
works. Do not scaffold a new project, and do not assume a blank slate.

Inspect the codebase first and establish:

- The existing application structure and where code of this kind already lives.
- The framework and version in use.
- The existing design system — colours, spacing, typography, and component conventions.
- Existing UI components you can reuse instead of writing new ones.
- The existing database structure, if this feature needs to persist anything.
- The existing authentication and authorization system, if this feature is user-scoped.
- Dependencies already installed, so you don't add a library that duplicates one.
- The existing test setup and conventions.

Only start writing code once you understand the above. If the application
already implements part of this feature, extend it rather than replacing it.

## Implementation Instructions

1. Map each screen into the regions that can be shown independently — the shell and navigation, the primary content, then secondary panels and counts — and let each one arrive on its own rather than waiting for the slowest.
2. Draw a boundary wherever a slow region would otherwise delay a fast one, and only there. A boundary per component fragments the page into a dozen separately twitching rectangles.
3. Start every request a region needs as early as the parameters are known, so the requests overlap instead of queueing behind whichever component happens to render first.
4. Give each boundary a placeholder with the same dimensions as its eventual content, so regions resolving in an unpredictable order do not push each other around the page.
5. This entry decides where the boundaries go and what the placement is trying to achieve; the appearance of the pending, empty, and refreshing states inside them belongs to Async Boundary Component. Do not define a second set of skeletons here.

## UI and UX Requirements

Match the application's existing design system exactly. Reuse its components,
spacing, and typography. This feature should look like it was always there.

## Responsive Requirements

Works on mobile, tablet, and desktop. Touch targets are large enough to hit on a
phone, and nothing overflows horizontally at 320px.

## Accessibility Requirements

- Fully keyboard navigable.
- Correct semantic elements and ARIA roles.
- Visible focus states.
- Meets WCAG AA contrast.
- Dynamic changes are announced to screen readers.
- Respects prefers-reduced-motion.

## Edge Cases

- Content already on screen must stay on screen during a refetch. Falling back to a placeholder for data the user is currently reading is a regression, not a loading state.
- Server-rendered markup and the client's first render must agree about which regions were pending, or the page will visibly reshuffle the moment it becomes interactive.
- Requests must not chain. A region that fetches a record, renders, then fetches that record's related items turns two round trips into a sequence, and the boundary hides the delay rather than removing it.
- Every boundary needs a matching failure containment from Error Boundary Pattern. A region that can be pending can also fail, and without a fallback the failure escapes to the nearest ancestor and takes healthy regions with it.
- Streaming a page in fragments changes when the document title, the metadata, and the response status can be decided. Settle those before the parts that stream, or a not-found record will be delivered inside a successful page.
- Keyboard focus and scroll restoration must account for content that arrives after the initial paint, or a user who tabs immediately will land somewhere that then moves.
- Boundaries around content above the fold should be few. The user is judging the page by how quickly the top of it settles, not by how many pieces it was split into.

## Testing

Exercise the feature end to end in the running application. Cover every edge case
above, then run the existing test suite and confirm nothing regressed.

## Acceptance Criteria

- [ ] Each screen resolves in named stages, with the shell and primary content never waiting on secondary regions.
- [ ] The number of boundaries is deliberate and documented per screen, not one per component.
- [ ] Requests for a screen's regions are issued in parallel, with no region waiting on another's response to begin.
- [ ] Refetching data leaves the currently visible content in place.
- [ ] Server and client agree on the pending regions, with no visible reshuffle on hydration.
- [ ] Every boundary is paired with failure containment from Error Boundary Pattern.
- [ ] Placeholders match the dimensions of their content, and regions resolving out of order cause no layout shift.
- [ ] The feature matches the existing design system.
- [ ] No existing functionality is broken.

## Adaptation Rules

- Match the existing design system. Do not introduce a new colour palette,
  spacing scale, or component library.
- Reuse existing components and utilities wherever they fit.
- Follow the naming, file layout, and code style already present.
- Do not upgrade, replace, or remove existing dependencies to make this
  feature fit. Adapt the feature to the app, not the app to the feature.
- Do not break existing functionality. If a change is genuinely required in
  existing code, make the smallest one that works and say so.
- If something in these instructions conflicts with how the application is
  built, follow the application and explain the deviation.

## Final Verification

Before you report the work as done:

1. Re-read the acceptance criteria above and check each one against what you
   actually built.
2. Run the application and exercise the feature end to end.
3. Run the existing test suite and confirm you have broken nothing.
4. Check the feature on mobile, tablet, and desktop widths.
5. Check keyboard navigation and focus handling.
6. Summarize what changed: files added, files modified, and anything you
   deliberately did differently because of how this application is built.

If any acceptance criterion is unmet, fix it before reporting completion.