Boundary Tightness

A trigger $x$ (an await, a directive) activates a framework mechanism whose granularity is structural, not semantic: it affects everything inside a region determined by where the trigger sits, not by what actually depends on it. Call that the actual region $A(x)$. The semantics of the code define a lower bound — the necessary region $N(x) \subseteq A(x)$ that no restructuring could exempt. With a consistent size weight $W(\cdot)$:

Tightness $=1$ means the boundary spends exactly what the semantics demand — unavoidable and perfectly scoped. The gap $A \setminus N$ is pure structural waste, and every instance has a known rewrite (a lever) that shrinks it. The table below shows the two instances this paper develops; the schema accommodates more (e.g. "use cache" scope granularity vs. actually-shared computation).

An await in a server component halts that component's entire output. What the user loses is larger still: React holds back everything under the nearest enclosing Suspense boundary until all of its suspended descendants resolve. If no boundary exists, the whole route blocks (and under Cache Components, the build fails). The structural question is therefore not whether you block — dynamism is usually a product requirement — but how much unrelated UI you take hostage.

Fix a route and let $a$ range over its await sites: syntactic points (await, .then, React use()) that resolve a dynamic source — uncached fetch, a database call, cookies(), headers(), params, searchParams — outside any "use cache" scope. (We keep the $U$/$B$ names in this instance; the rollup below transfers verbatim to any instance.)

• Necessary region $U(a)$. The union of JSX subtrees that data-depend on the awaited value: every element interpolating it and every component receiving a prop derived from it, transitively. This UI cannot exist before the data arrives; it is a lower bound on blocking.
• Blocked region $B(a)$. The content of the nearest Suspense boundary enclosing the awaiting component (the whole route if none). React reveals a boundary atomically, so this is precisely what the user cannot see.
• Weight $W(\cdot)$. Any consistent proxy for "amount of UI". We use the JSX-node count of the statically expanded subtree (components inlined recursively, cycle-guarded; unresolvable references count 1 and are reported). Because the score is a ratio, $W$ need only be monotone — and it can be validated against build truth: DOM-node or pixel deltas between the prerendered shell and the full render.

The per-await score is

with $\mathrm{tightness}(a)=1$ meaning the blocking is unavoidable and perfectly scoped.

From one await to a route score

A route has many awaits, so we need one number per route — but per-await scores do not combine by averaging or summing, for two reasons:

1. Shared boundaries double-count. If cookies() and fetchUser() are awaited under the same Suspense boundary, they have the same $B$. Summing $W(B)$ over both awaits would count every blocked component twice, and "fixing" one of the two awaits would appear to halve the damage when the user-visible hole is unchanged.
2. Averaging over-weights trivia. The mean of $\{0.9, 0.2\}$ is the same whether the $0.2$ await blocks a footnote or half the viewport. An average of ratios forgets how much UI each ratio is about.

Both problems disappear if we merge regions first and divide once. Collect the route's three disjoint territories:

Everything outside $\mathrm{Blocked}$ is the static shell. The route then gets two complementary scores, each answering a different question:

"Of the UI that blocks, what fraction truly had to?" Judges how well the boundaries are scoped, ignoring how big the page is. This is per-await tightness generalized to the whole route.

"Of the whole page, what fraction is where it belongs?" Only needlessly blocked UI counts against the route; UI that must block costs nothing. $1$ = the shell is as large as this page's data dependencies permit.

Both live in $[0,1]$ and equal $1$ for a route with no uncached awaits. The figure below lays the two formulas over one picture, using the numbers from example (b) of the worked example in the next section.

Why keep two numbers?

Because they deliberately disagree on one important case. Take a 100-node page with a single sloppy await: $B = 5$, $U = 1$. Precision is $1/5 = 0.20$ — locally, that boundary is badly scoped. Shell efficiency is $1 - 4/100 = 0.96$ — globally, the user still gets 96% of the page instantly. Neither number alone tells the whole story: precision without size context manufactures urgency over footnotes; shell efficiency alone would let every boundary rot a little. So: assert on shell efficiency (it tracks what users experience), rank the worklist by wasted weight $W(B(a) \setminus U(a))$ (it finds the biggest prize), and read per-boundary precision as the hygiene diagnostic. Hop distance (await site to first real use) survives alongside as a per-violation diagnostic — it names the fix, while the scores price the cost.

The server/client split partitions the module graph instead of the render tree. A "use client" directive marks a boundary file; that file and every module it transitively imports become client modules — downloaded, parsed, and hydrated in the browser. The mechanism is again coarse: the directive captures by reachability, not by need. Mark a header component as client because it contains one interactive toggle, and the navigation, logo, and search markup it imports all ship to the client with it.

• Necessary region $N(x)$. Modules (or components within them) that semantically require the client: they call hooks (useState, useEffect, useContext, useOptimistic, …), attach event handlers (on[A-Z]* props), touch browser globals (window, document, localStorage), or import client-only libraries. This is the lower bound: no restructuring can render this code on the server.
• Actual region $A(x)$. The client module subgraph reachable from the directive file through imports. This is precisely what the bundler ships — and it is checkable against build truth, because Next.js writes the reachable client set into its client-reference manifests.
• Weight $W(\cdot)$. Module-size census (AST-node or byte count) rather than JSX census: the cost of client waste is bundle bytes and hydration work, not blocked pixels. Same principle as before — $W$ need only be monotone, and the build offers ground truth (per-route chunk sizes) to validate against.

Then, exactly as before: $\mathrm{tightness}(x) = W(N)/W(A)$ per directive, and per route

"of the code that could stay on the server, how much does."

Levers

In ranked order of applicability: (1) push the directive down to the interactive leaf (figure above); (2) thread server JSX through — a client wrapper (context provider, animation shell) can receive server-rendered subtrees as children/props without dragging them into the bundle, the exact analog of passing a promise through a Suspense boundary; (3) split mixed files so the interactive part is importable alone; (4) replace a client-only dependency with a server-safe one. As with the shell, per-directive tightness ranks the worklist by wasted weight, and serverEff is the route-level assertion:

test("client boundaries are tight", () => {  for (const route of report.routes) {    expect(route.serverEfficiency, route.explainClient())      .toBeGreaterThanOrEqual(0.85);}});

Two familiar refinements carry over. First, the binary ancestor of this metric — counting "use client" files, or capping "client files ≤ 50% of source files" — has the same flaw as counting awaits: a count punishes granularity (ten tight leaf directives beat one hoisted directive, but score worse) and ignores weight. Second, build truth exists here too: the client-reference manifests under .next/server/app record exactly which modules shipped, so the static $A(x)$ can be validated the same way shell $W$ is validated against the prerendered HTML.

Why should a metric exist at all, rather than another lint rule? The answer is about what tests do to a generator of code. An agent samples from the space of all programs it could write. Every assertion you add rejects part of that space: the type checker rejects code that doesn't compile, e2e tests reject code that doesn't work, and structural assertions — like the ones in this paper — reject code that works but is built wrong. Each constraint is a funnel stage: what comes out the narrow end is not better generation, it is better selection.

Binary constraints alone make agents random-walk: inside/outside is all they report, so the agent learns nothing from a failure except "try again". This is the practical argument for normalization: a score in $[0,1]$ converts the innermost boundary into a potential field. $0.31$ doesn't just reject — it says how far, and (through the ranked worklist) along which dimension to move. The build's binary check is the outer funnel wall; shellEff is the slope inside it.

The metrics turn migration from a checklist into gradient descent: the assertion is the objective, per-violation wasted weight is the ranking, and the diagnostics name the rewrite. The loop below is the next-doctor equivalent of a failing e2e test forcing behavioral correctness — here it forces structural correctness. We show it for the shell instance; the client instance runs the identical loop with serverEff as the objective and the levers of §5 in step 3.

The assertion an agent iterates against

import { describe, expect, test } from "vitest";import { analyzeShellTightness } from "../doctor/shell-tightness"; const report = analyzeShellTightness("./app", {  ioModules: ["@/lib/db", "@/lib/api"],   // designate your I/O layer}); describe("cache components: shell structure", () => {  test("every route keeps a tight static shell", () => {    for (const route of report.routes) {      expect(route.shellEfficiency,        route.explain()            // ranked violation table on failure      ).toBeGreaterThanOrEqual(0.8);}  });   test("no hoisted awaits (push-down distance is zero)", () => {    expect(report.violations.map(v => v.summary())).toEqual([]);  });   test("ratchet: never worse than the committed floor", () => {    expect(report.project.shellEfficiency)      .toBeGreaterThanOrEqual(readFloor(".shell-ratchet.json"));  });});

A failure prints the worklist the agent consumes — highest wasted weight first, with the fix named by the diagnostics:

Case study: one migration, four scores

• …normalized hop distance, e.g. $1/(1+d)$? Dimensionless in the wrong way: insensitive to how much UI hangs off each hop, and gameable — an agent can reduce $d$ without growing the shell by a single node. Distance names the fix; it cannot price the cost.
• …fraction of components that are async? Punishes dynamism itself. A fully personalized page can be perfectly structured ($\mathrm{tightness}=1$); a mostly-static page can be terribly structured. Product requirements set how much is dynamic; engineering controls only the scoping — the metric must isolate the latter.
• …build output alone (shell bytes / postponed state)? It is the ground truth, but it is non-attributable: it tells you the shell is small, not which await to blame or where the value was actually needed. We use build truth as step-4 verification and to calibrate $W$, source analysis for attribution and the gradient.
• …counting "use client" files (or awaits)? Counts punish granularity: pushing one hoisted directive down into three tight leaf directives triples the count while shrinking the bundle. Any metric an agent optimizes must reward the rewrite you actually want; only weighted necessary-over-actual does.