Pracht Audit Islands

Report-only audit of hydration modes and islands usage (see https://pracht.resynapse.dev/docs/islands). pracht hydrates the whole page by default (hydration: "full"); routes can opt into "islands" (only components from the islands directory hydrate) or "none" (zero JS). This audit finds routes shipping JS they don't need and islands wired in ways that break at render time or ship dead handlers.

Step 1: Enumerate routes and hydration modes

MCP: if pracht dev-mcp is registered, prefer its inspect_*, doctor, and verify tools to the CLI.

pracht inspect routes --json

Prerequisite: pracht inspect needs a vite config with the pracht plugin wired up.

Each route entry carries render and hydration (null = framework default, i.e. full hydration). Also locate the islands directory: default src/islands/, configurable via pracht({ islandsDir }) in the vite config. In pages-router apps (mode: "pages"), hydration is the per-file export const HYDRATION = "islands" | "none" constant; islands still live in src/islands/.

Step 2: Measure what each route actually ships

pracht build --json

Prerequisite: this runs a full production build (--json implies --analyze). Interpret the totals hydration-aware:

• Full-hydration routes: route chunks + shell chunks + shared entry.
• hydration: "islands" routes: islands bootstrap + island chunks only — no shared client entry. The listed island chunks are an upper bound (every island in the app); a page only downloads the islands it renders.
• hydration: "none" routes report 0b.

Step 3: Run the checks

3a. Over-hydration (the headline check)

For every route with hydration null/"full": read the route module, its shell, and their imported components. If the page is mostly static — no hooks, no event handlers, or only one or two isolated widgets — flag it:

• Zero interactivity → recommend hydration: "none" (warn; info if the route's total gzip JS is already tiny).
• A few isolated widgets → recommend hydration: "islands" with the widgets moved into the islands directory (warn). Cite the Step 2 total as the payload this change removes.

Render-mode fit is owned by /tune-render-mode; deep chunk analysis is owned by /audit-bundles. Point there instead of duplicating their findings.

3b. Dead interactivity on islands routes (error)

On a hydration: "islands" route, everything outside the islands directory renders as inert HTML — an onClick in a regular component silently does nothing. Grep the route tree of every islands route for event handlers and hooks in components not under the islands directory and flag each one. Islands are auto-discovered from that directory only (default and named function-component exports alike; each becomes its own code-split chunk) — there is no wrapper to mark a component elsewhere as an island.

3c. Island props and children (error)

Island props are serialized to JSON in the HTML. At each island call site on an islands route, flag props that are functions, symbols, bigints, class instances (Date, Map, ...), JSX elements, or circular — rendering throws a descriptive error naming the offending prop path. Children passed into an island are fine: markup renders once on the server as static HTML, and plain text arrives as a string value. Flag:

• a render function passed as children (it throws);
• children the island expects to re-render or pass props into, and islands among the children that read context the outer island provides (the browser gives them the default) — those belong inside the island or need a prop;
• an island that splits markup children with toChildArray, Children.map, or Children.count (tabs, carousels): it receives one opaque node, so labels belong in props and panels are toggled through a ref (hidden);
• an island that renders children inside <p>, <a>, or <button> while call sites pass block elements, links, or buttons (the dev server throws when it sees this), or raw HTML in children that may be malformed: the browser moves those nodes out of the slot and the island is left unhydrated with a console error.

3d. Hydration strategy tuning (info)

Each island usage picks a strategy via the framework-owned client prop: "load" (default, chunk is <link rel="modulepreload">-ed), "idle" (requestIdleCallback), "visible" (IntersectionObserver; chunk fetched only when triggered). Flag default-load islands that are plausibly below the fold or not needed at first paint (comment sections, newsletter signups, footers) → suggest client="visible" or client="idle".

3e. Invalid combinations (error)

render: "spa" always implies full hydration; combining it with hydration: "islands" or "none" is a configuration error. Flag any such route (manifest field or pages-router RENDER_MODE/HYDRATION pair).

3f. MPA navigation assumptions (warn)

Routes with hydration: "islands" or "none" never load the client router: navigation to, from, and between them is full-document (MPA-style), and route-state prefetching is skipped for them. Flag apps that rely on client-side state surviving navigation across such routes (in-memory stores, module-level caches shared between pages) — every navigation is a fresh document, unless pracht({ client: { islandsNavigation: true } }) is set. With it, links between islands pages (and from them to none pages) swap the page into the same document and an island rendered with identical props on both pages keeps its state; module state survives too. Still flag state that must survive a link to a full-hydration route, a reload, or a browser without the Navigation API, since those remain full loads. Page-change animation does not need the client router: with defineApp({ viewTransitions: true }) these documents carry a @view-transition rule and animate as cross-document view transitions, so flag only apps that load extra JavaScript to animate such navigations.

3g. Personal data in islands on cached pages (warn)

Island props on an ssg/isg route are fixed at build or regeneration time and shared by every visitor. Flag islands that exist only to fetch per-visitor content after load (a hand-rolled fetch of the session, cart, or "signed in as" data in useEffect) and islands whose props look personal. Suggest a server island instead (src/server-islands/, see https://pracht.resynapse.dev/docs/server-islands): its loader runs per request with the route's middleware context, and it may contain islands, which hydrate once the server island is swapped in. On full-hydration pages islands inside a server island stay static HTML — flag those (warn) if they are expected to be interactive.

Step 4: Report

Severities: error (breaks or throws today: dead handlers, non-serializable props, spa+islands), warn (works but wasteful or fragile), info (tuning opportunity). Include the measured gzip totals for every over-hydration finding.

Rules

1. Report only — never edit routes, components, or config. Hand changes to /tune-render-mode (modes) or the user.
2. Use pracht inspect routes --json as the source of truth for hydration modes — groups inherit hydration, so reading src/routes.ts manually under-counts.
3. Islands components behave like plain components on full-hydration routes and inside other islands — only flag 3b/3c on hydration: "islands" routes.
4. Verify hydration in a running app via html[data-pracht-islands-hydrated="true"] (set after all load islands hydrate) and per-island data-hydrated="true". Server islands report html[data-pracht-server-islands-ready="true"] once every server island fetch the page started has settled, on every hydration mode.

$ARGUMENTS