@kudzujs/core 0.8.51 → 0.8.53

package/MIGRATION_ROADMAP.md

@@ -2,7 +2,7 @@
 
 This document is the source of truth for Kudzu's product direction, architecture invariants, and future development order. Read it before extending React-shaped syntax or browser capabilities.
 
-The executable post-`0.8.51` compiler and large-application sequence is maintained in [`docs/next-architecture/large-application-ai-native-roadmap.md`](./docs/next-architecture/large-application-ai-native-roadmap.md). Follow its PR dependencies for implementation work; this document remains authoritative when selecting or accepting a migration capability.
+The executable post-`0.8.53` compiler and large-application sequence is maintained in [`docs/next-architecture/large-application-ai-native-roadmap.md`](./docs/next-architecture/large-application-ai-native-roadmap.md). Follow its PR dependencies for implementation work; this document remains authoritative when selecting or accepting a migration capability.
 
 [`GOAL_A.md`](./GOAL_A.md) and [`GOAL_B.md`](./GOAL_B.md) are completed capability-validation records. Their commerce and realtime dashboard fixtures prove general lifecycle, navigation, async-workflow, and Worker capabilities; they are not separate product verticals or future priority lists.
 
@@ -59,6 +59,7 @@ Do not add `getStaticProps`, request-time SSR, an SPA router, a stream runtime,
 The following are available building blocks, not future vertical roadmaps:
 
 - Async build-time components, `getStaticPaths()`, runtime path parameters, metadata, base paths, public assets, CSS, CSS Modules, and post-build hooks.
+- Relative source CSS imports close over each page's reachable TypeScript import/re-export graph; configured styles remain explicitly global. Enhanced navigation loads destination CSS before route DOM replacement, reuses shared layout links, and removes outgoing route links.
 - React import normalization for supported named/aliased hooks, direct `React.*` members, fragments, same-file `memo`, inline `useCallback`, direct intrinsic `forwardRef`, top-level `useId`, and analyzable `useMemo` expressions and collections.
 - Function components, props, children, context, direct bindings, conditions, controlled form properties, refs, and synchronous or async handlers.
 - `useState`, independent repeated non-keyed child state with conditional mount ownership, reduced relative-imported `useReducer`, direct dispatch specialization, and reduced Zustand-shaped shared state lowered through package-neutral shared-state/action IR and proven by migration fixtures.
@@ -173,7 +174,7 @@ This queue orders the next investigations by general migration value. Start only
 ### Completed In 0.8.13
 
 - A reduced fixture from [Memos](https://github.com/usememos/memos) preserves its memo-outline scroll spy: native heading links, active `aria-current`, smooth scrolling, hash replacement, capture-phase scroll/resize listeners, and animation-frame coalescing with cleanup.
-- One effect-owned `useRef(0)` lowers to a serializable mutable effect capture when a local frame callback resets it and cleanup cancels the pending frame. Existing effect ownership handles setup, listener removal, and document disposal without state, a retained component, or an animation runtime.
+- Top-level `useRef(null)` and `useRef(0)` values used exclusively through direct `.current` references in one inline effect graph lower to invocation-private closure objects in effect ESM. Existing effect ownership handles SDK/WebSocket handles, generation invalidation, animation frames, dependency replacement, listener removal, BFCache-aware document disposal, and cleanup without serialized captures, ResourceIR, or a retained component.
 - Chrome validation covers burst coalescing, active-heading updates, outline clicks, hash replacement, pending-frame cancellation, listener cleanup, and a zero-JavaScript static sibling. Ref aliases, cross-effect/event use, nonzero initializers, multiple scheduling assignments, and missing cancellation remain unsupported.
 - A reduced fixture from [Excalidraw](https://github.com/excalidraw/excalidraw) preserves its active-room progressive sharing shape: a readonly collaboration URL, a Web Share button gated by `"share" in navigator`, direct `navigator.share()`, clipboard fallback, and accessible application-owned status.
 - Browser capability conditions lower to a false static state plus one existing mount effect and state-owned conditional branch. Supported browsers mount the Share DOM and handler; unsupported browsers keep both out of the document and accessibility tree. Node's build-time `navigator` can no longer fold browser capability UI incorrectly.
@@ -272,7 +273,7 @@ This queue orders the next investigations by general migration value. Start only
 
 ### Characterized In 0.8.27
 
-- A reduced E2B Dashboard terminal fixture establishes callback-shared mutable browser resources, asynchronous generation invalidation, and BFCache retain/resume/discard behavior as a concrete Goal C boundary.
+- Reduced E2B Dashboard terminal and route-owned WebSocket fixtures establish callback-shared mutable browser resources, asynchronous generation invalidation, dependency replacement, exact cleanup, and BFCache retain/resume/discard behavior. Exclusive effect-private refs now compile through ordinary effect ESM; shared transports and cross-owner subscriptions remain Goal C research.
 - Unsupported page-level mutable value refs fail during source analysis with a source location and the existing effect-owned animation-frame exception; no resource API or runtime is added.
 - The large-application and AI-native execution plan orders symbol resolution, semantic operations, project/module analysis, IR authority, application foundations, ecosystem compatibility, AI tooling, and scale validation before broad feature work.
 

package/PERFORMANCE.md

@@ -6,7 +6,15 @@ Reproducibility classes: `npm run benchmark`, `npm run benchmark:keyed`, `npm ru
 
 The maintained 2026-08-13 comparison used Node 24.14.0 and an Intel Core i5-9500 Linux x64 host, one warm-up, and seven alternating fresh-process samples against clean `v0.8.44`. A narrow fast path skips Kudzu semantic transformation for 450 plain `.ts` modules whose runtime edges are exclusively resolvable relative TypeScript imports or exports; all other modules retain the existing transformer. Compile median fell from 2,323.9 ms to 1,413.2 ms (39.2%) and clean-build median from 3,325.3 ms to 2,382.4 ms (28.4%); every paired sample improved. Compile peak-RSS median fell from 571.2 MiB to 552.6 MiB, while build peak RSS was 570.9 MiB versus 568.8 MiB. Compiler scratch fell from 7,328,390 to 1,971,061 bytes. Both targets emitted the same 50 static HTML files, 10,980 bytes, and deploy SHA-256 `e107d78a7f55bc8a1af0ea6e53efeffa19b3d44d21c892484d103fa346e7ba7b`. This is a source-scale compiler comparison, not a cross-framework result.
 
-## Current 0.8.51 Release Snapshot
+## Current 0.8.53 Release Snapshot
+
+Kudzu 0.8.53 removes unrelated source stylesheet links from route HTML and reuses shared layout links during enhanced navigation. Static routes add no JavaScript, and no new performance claim is made.
+
+## Maintained 0.8.52 Release Snapshot
+
+Kudzu 0.8.52 moves proven effect-private mutable refs from component scope into existing setup-invocation closures. The refs add no serialized route scope, shared runtime, or static-sibling JavaScript; no new performance claim is made.
+
+## Maintained 0.8.51 Release Snapshot
 
 Kudzu 0.8.51 broadens compiler-only package-reference routing into existing owned effect ESM and bundling. Static siblings and routes without the effect retain zero package bytes; no new performance claim is made.
 

package/README.md

@@ -14,7 +14,7 @@ Kudzu compiles ordinary React-shaped TypeScript and TSX into complete static HTM
 
 > Experimental `0.8.x`: the compiler API and supported TSX surface may change.
 
-**Latest release: 0.8.51 - Owned effect package imports.** Browser-only package bindings may be referenced directly inside inline effect setup and cleanup callbacks. Kudzu bundles them only into route-owned effect ESM while build-time component modules and static siblings omit the package. Read the [release notes](./RELEASES.md#0851---owned-effect-package-imports), open the [release page](https://github.com/kudzujs/kudzu/releases/tag/v0.8.51), or follow the [architecture packet](./docs/next-architecture/README.md).
+**Latest release: 0.8.53 - Route-aware CSS closure.** Relative source CSS follows each page's reachable TypeScript import and re-export graph, while configured styles remain explicitly global. Enhanced navigation loads destination styles before route replacement, retains shared layout links, removes outgoing styles, and rolls back cancelled loads. Read the [release notes](./RELEASES.md#0853---route-aware-css-closure), open the [release page](https://github.com/kudzujs/kudzu/releases/tag/v0.8.53), or follow the [architecture packet](./docs/next-architecture/README.md).
 
 - [Documentation](https://kudzujs.cloud/docs)
 - [Installation guide](https://kudzujs.cloud/docs#install)

package/RELEASES.md

@@ -1,5 +1,84 @@
 # Kudzu Releases
 
+## 0.8.53 - Route-aware CSS closure
+
+Kudzu 0.8.53 links source styles only from routes whose reachable TypeScript graph imports them.
+
+### Changed in 0.8.53
+
+- Relative CSS imports follow each page's runtime import and re-export graph in deterministic source order.
+- RouteBuildRecord receives each route's exact source stylesheet URLs instead of one site-wide CSS list.
+- `kudzu.config styles` remains explicitly global, deduplicated, and excluded from route-managed ownership.
+- CSS `?url` imports emit downloadable assets without creating stylesheet links.
+- Unimported source CSS is no longer implicitly linked; applications import route/layout styles or configure true globals.
+
+### Enhanced navigation
+
+- Navigable documents mark route-managed source styles separately from configured global links.
+- Destination styles load before route cleanup and DOM replacement.
+- Shared layout stylesheet links retain URL, DOM identity, and cascade order across navigation.
+- Outgoing route styles are removed after successful preparation.
+- Overlapping navigation cancels and rolls back provisional stylesheet transactions without disturbing the newer route.
+- Invalid, duplicate, cross-origin, or failed managed stylesheets fall back to native document navigation.
+
+### Migration evidence
+
+- The React/Vite static sibling excludes the interactive app stylesheet while retaining zero JavaScript.
+- Independent navigation groups exclude one another's layout and route styles.
+- A delayed stylesheet browser test verifies cancellation rollback, shared-link identity, destination activation, and outgoing-link removal.
+- Global style fixtures prove configured source/URL deduplication, while dynamic routes now import their intended CSS explicitly.
+- The starter imports shared CSS through its common header so both generated routes reach the style intentionally.
+
+### Output and performance
+
+- Route HTML omits unrelated feature CSS and its cascade effects.
+- Static pages remain JavaScript-free; only configured enhanced-navigation routes receive managed-style reconciliation.
+- No CSS bundler, style runtime, SPA router, or new performance claim is added.
+
+### Validation
+
+- `npm run check`, `npm test`, and `npm run test:package` pass with all 219 tests and 168 generated pages.
+
+### Upgrade
+
+```bash
+npm install @kudzujs/core@^0.8.53
+```
+
+## 0.8.52 - Effect-private mutable refs
+
+Kudzu 0.8.52 compiles component-authored mutable refs when one inline effect exclusively owns their complete lifecycle.
+
+### Changed in 0.8.52
+
+- Top-level `useRef(null)` and `useRef(0)` values lower when every direct `.current` reference belongs to one inline block-bodied effect setup, its nested callbacks, and cleanup.
+- The compiler removes those component declarations and creates fresh mutable objects inside each effect setup invocation.
+- Existing effect ownership handles dependency replacement, stale setter invalidation, conditional/keyed ownership, navigation, document disposal, and BFCache preservation.
+- Animation-frame refs use the same invocation-private lowering while retaining exact scheduler, reset, and cancellation validation.
+- JSX DOM refs remain component-owned; aliases, nonzero initializers, cross-effect/event use, missing cleanup invalidation, and escaped ref objects remain source-diagnosed.
+
+### Migration evidence
+
+- The E2B terminal fixture now preserves asynchronous generation invalidation, BFCache retain/resume, discard cleanup, and a static sibling without ResourceIR.
+- A native WebSocket fixture verifies dependency replacement, listener removal, stale callback rejection, distinct connection ownership, and one close per connection.
+- Mutable refs shared by multiple effects retain a focused source diagnostic.
+
+### Output and performance
+
+- Private refs stay inside existing route-specific effect handler ESM and are absent from build-time captures and RouteIR scope.
+- Static sibling routes remain zero JavaScript.
+- No ResourceIR record, component runtime, resource API, scheduler, or new performance claim is added.
+
+### Validation
+
+- `npm run check`, `npm test`, and `npm run test:package` pass with all 219 tests and 167 generated pages.
+
+### Upgrade
+
+```bash
+npm install @kudzujs/core@^0.8.52
+```
+
 ## 0.8.51 - Owned effect package imports
 
 Kudzu 0.8.51 lets inline owned effect setup and cleanup callbacks reference browser-only package imports directly.

package/docs/next-architecture/README.md

@@ -11,7 +11,7 @@ The top-level [`GOAL_A.md`](../../GOAL_A.md) and [`GOAL_B.md`](../../GOAL_B.md)
 | C: state/resource model | Research only | Reduced fixtures expose a limitation |
 | D: routing compatibility | Current behavior preserved | Revisit only with migration evidence and invariant review |
 
-The active post-`0.8.51` implementation sequence is [`large-application-ai-native-roadmap.md`](./large-application-ai-native-roadmap.md). P0.12 validation, property-level object-state dependencies, direct three-boundary callback/ref ownership, direct primitive prop state initialization, repeated direct leaf-handler callback use, direct child callback fan-out, collision-free and private Context action setters, package-neutral shared-state/action IR, browser-only package imports in owned effects, measured route-entry output optimization, and the plain TypeScript source-scale fast path are complete. ResourceIR remains research requiring two independent lifecycle fixtures. The plan orders compiler semantic generalization, large-application foundations, compatibility boundaries, AI tooling, and production validation without changing the invariants below.
+The active post-`0.8.53` implementation sequence is [`large-application-ai-native-roadmap.md`](./large-application-ai-native-roadmap.md). P0.12 validation, property-level object-state dependencies, direct three-boundary callback/ref ownership, direct primitive prop state initialization, repeated direct leaf-handler callback use, direct child callback fan-out, collision-free and private Context action setters, package-neutral shared-state/action IR, browser-only package imports and private mutable refs in owned effects, route/layout CSS closure, measured route-entry output optimization, and the plain TypeScript source-scale fast path are complete. Route capability signatures and emitted shared-chunk reporting are next; ResourceIR remains research for cross-owner transports and subscriptions. The plan orders compiler semantic generalization, large-application foundations, compatibility boundaries, AI tooling, and production validation without changing the invariants below.
 
 ## Required Invariants
 

package/docs/next-architecture/compiler-current-architecture.md

@@ -1,6 +1,6 @@
 # Current Compiler Architecture
 
-This maps the current `0.8.51` architecture, built on the completed `0.8.23` Goal A compiler foundation. File and function names are the stable references; line numbers are intentionally omitted because later work may still move code.
+This maps the current `0.8.53` architecture, built on the completed `0.8.23` Goal A compiler foundation. File and function names are the stable references; line numbers are intentionally omitted because later work may still move code.
 
 ## Responsibility Map
 

package/docs/next-architecture/goal-c-state-resource-research.md

@@ -58,17 +58,21 @@ The repository-owned fixture at `test/fixtures/goal-c-e2b-terminal` preserves th
 - `pageshow.persisted` resuming the retained handle;
 - one unrelated static sibling route.
 
-The build fails before BFCache behavior can be evaluated:
+The fixture now compiles through a narrow effect-private ref specialization. Because both refs are initialized with `null` or `0` and every direct `.current` reference belongs to one inline effect graph, the compiler removes their component declarations and recreates them inside each setup invocation. Promise continuations, page lifecycle listeners, and cleanup share the same ordinary JavaScript closure. Persisted `pagehide` retains that invocation; non-persisted disposal invalidates late setters and runs the authored close path. No ref capture, ResourceIR record, or resource runtime is emitted, and the static sibling remains JavaScript-free.
 
-```text
-src/pages/index.tsx:7:25 Mutable value useRef() is unsupported except for an effect-owned useRef(0) animation-frame handle; otherwise keep resource-private mutable values inside the owning effect
-```
+### Route-Owned WebSocket Reduced Fixture
 
-The failure is triggered by the ordinary `useRef(0)` generation token during source analysis. Existing animation-frame specialization cannot safely cover this shape: the generation token has different writes and callback ownership, while the remote handle is a browser-only non-serializable value rather than a DOM ref. Supporting only the token would expose incorrect DOM-ref semantics for the handle.
+The repository-owned fixture at `test/fixtures/goal-c-route-websocket` adds an independent native WebSocket case with a narrower route lifetime:
 
-The remaining question before any state/resource API discussion is whether independent fixtures justify a narrow specialization for callback-shared effect resources with document and BFCache ownership. Until then, the source-located diagnostic preserves the current boundary.
+- one `null`-initialized socket handle ref shared by setup and cleanup;
+- one numeric generation ref invalidating callbacks from replaced connections;
+- a primitive room dependency that replaces the connection;
+- exact listener removal and socket closure on replacement or route unmount;
+- one unrelated static sibling route.
+
+This fixture uses the same effect-private lowering. On dependency replacement, the previous invocation is invalidated and cleaned before a new closure and socket are created. The regression test executes the bundled effect handler with a fake WebSocket and verifies listener removal, stale callback rejection, one close per connection, and distinct replacement sockets. Its static sibling remains JavaScript-free.
 
-An effect-local rewrite is a useful control, but requiring applications to restructure ordinary callback-shared refs is not automatically an acceptable migration solution. The fixture remains an expected failure until research answers that boundary.
+Both fixtures therefore resolve without ResourceIR: their mutable handles are private implementation details of one effect invocation, while existing effect ownership already supplies replacement, cleanup, navigation, and BFCache disposal. The remaining Goal C pressure is cross-owner sharing: document/layout transports with independently mounted subscribers, reconnect/replay state, or handles intentionally shared with event handlers cannot use this specialization.
 
 ## Decision Boundary
 
@@ -81,4 +85,4 @@ Research may produce notes, fixtures, measurements, or a narrow compiler-special
 - [ ] Classify build-known, browser-only, layout-owned, route-owned, and DOM-owned data.
 - [ ] Test existing compiler capabilities before proposing a new one.
 - [ ] Record unresolved semantics instead of filling them with a generic runtime.
-- [ ] Stop at research unless a separate implementation decision is approved.
+- [x] Stop at research unless a separate implementation decision is approved; the effect-private specialization was explicitly approved without approving ResourceIR.

package/docs/next-architecture/large-application-ai-native-roadmap.md

@@ -42,7 +42,7 @@ The current limiting architecture is observable in these files:
 | Lists/ranges | `source-compiler.mjs`, `list-runtime.js` | Strong keyed ownership, but syntax recognition and runtime branches are list-specific and not a general range/window primitive |
 | ModuleIR | `compiler/ir/module-ir.mjs` | Numeric slots, names, export strings, and formatted owner strings coexist; several sections are descriptive rather than authoritative inputs |
 | RouteIR/CapabilityIR | `route-capability-planner.mjs` | Validation is shallow and capability selection is site-wide across interactive routes |
-| Build/codegen | `framework/build.mjs`, runtime generators | Full destructive builds, serialized-string handler reachability, source-text runtime surgery, no route chunk/CSS closure report |
+| Build/codegen | `framework/build.mjs`, runtime generators | Full destructive builds, source-text runtime surgery, and no route capability/chunk closure report; route CSS closure is structural |
 | Browser lifetime | `native-runtime.js`, `effect-runtime.js`, `navigation-runtime.js` | Effects and native handlers invalidate stale writes at their existing effect or DOM ownership boundary |
 | Compatibility | React/Router/Zustand passes plus core branches | Package-specific knowledge is not contained behind one adapter boundary |
 | AI interface | CLI and string diagnostics | No stable diagnostic codes, semantic index, explain, fix, or migration analysis output |
@@ -382,8 +382,8 @@ After the relevant P0 foundations, investigate capabilities in this order:
 2. Multi-boundary component/prop/callback/ref/context dataflow. **Three-boundary callback/ref ownership completed in `0.8.43`; collision-free Context action-private state completed in `0.8.44`; action-only Provider setter exposure removed in `0.8.46`; direct primitive prop state initialization completed in `0.8.47`; repeated direct leaf-handler callback use completed in `0.8.48`; direct child callback fan-out completed in `0.8.49`:** forwarding preserves parent SignalIR, Context action lowering uses compiler-owned aliases when consumer locals reuse Provider state/setter names, action-required setters may remain compiler-only when their state is publicly exposed, specialized children may seed local state from a direct primitive parent signal, and one callback may branch through multiple component `on*` props and intrinsic handlers. A fourth callback boundary, callback aliases/non-handler uses, fully hidden Context state, and object/array prop initializers remain fail-closed. Broader prop, callback, ref, and Context graphs remain migration-led work.
 3. Package-neutral shared state/actions and migration of current Zustand internals. **Completed in `0.8.50`:** Zustand source normalization produces one generic shared-state adapter descriptor; selectors and handlers register JSON-safe SharedStateIR/SharedActionIR records, handler lowering consumes package-neutral actions, and existing RouteIR, layout ownership, same-turn updates, navigation persistence, and browser output remain unchanged. Redux/RTK and public adapter APIs remain unsupported.
 4. Browser-only package imports in owned effect/resource modules. **Completed in `0.8.51` for effects:** direct package references in inline effect setup/cleanup callbacks use existing package import records and route-owned effect ESM bundling; build-time component modules and static siblings omit the package. Helper-indirect, render-time, dynamic-import, and ResourceIR package graphs remain unsupported.
-5. ResourceIR from at least two independent WebSocket/SSE/SDK fixtures with the same semantics.
-6. Route/layout capability and CSS chunk closure.
+5. ResourceIR from at least two independent WebSocket/SSE/SDK fixtures with the same semantics. **Completed in `0.8.52` without ResourceIR for private ownership:** the E2B terminal and route-owned WebSocket fixtures lower refs used exclusively by one inline effect to invocation-private closure objects, while existing effect ownership supplies replacement, cleanup, stale setter invalidation, navigation, and BFCache disposal. ResourceIR remains unapproved and now requires independent cross-owner transport/subscription fixtures that cannot fit this narrower model.
+6. Route/layout capability and CSS chunk closure. **Route/layout CSS closure completed in `0.8.53`:** each page's reachable TypeScript import/re-export graph supplies exact source stylesheet edges to RouteBuildRecord, configured styles remain global, static siblings exclude unrelated feature CSS, and enhanced navigation loads incoming links before DOM replacement while retaining shared layout link identity and removing outgoing links. Route capability signatures and bundled shared-chunk reporting remain.
 7. Incremental source and affected-route builds.
 8. Range ownership and virtualization only after a real data-heavy fixture establishes direct DOM limits.
 9. Optimistic shared transactions only after independent mutation fixtures establish commit/rollback semantics.
@@ -481,4 +481,4 @@ The first comparison is Kudzu versus React + Vite using the same agent, model, t
 
 ## Immediate Decision
 
-PR 1 through PR 12, the `0.8.40` property-dependency slice, the `0.8.41` and `0.8.43` direct multi-boundary callback/ref slices, the `0.8.44` Context alias slice, the `0.8.46` action-only Provider setter slice, the `0.8.47` direct primitive prop initializer slice, the `0.8.48` repeated direct leaf-handler callback slice, the `0.8.49` direct child callback fan-out slice, the `0.8.50` package-neutral shared-state/action slice, the `0.8.51` owned-effect package import slice, and the `0.8.42` measured route-output optimization are complete. Continue with **ResourceIR only after two independent WebSocket/SSE/SDK fixtures prove the same lifecycle semantics**. Do not skip directly to a public adapter/store API, router, virtualization, or unsupported ecosystem package feature.
+PR 1 through PR 12, the `0.8.40` property-dependency slice, the `0.8.41` and `0.8.43` direct multi-boundary callback/ref slices, the `0.8.44` Context alias slice, the `0.8.46` action-only Provider setter slice, the `0.8.47` direct primitive prop initializer slice, the `0.8.48` repeated direct leaf-handler callback slice, the `0.8.49` direct child callback fan-out slice, the `0.8.50` package-neutral shared-state/action slice, the `0.8.51` owned-effect package import slice, the `0.8.52` effect-private mutable-ref slice, the `0.8.53` route/layout CSS closure slice, and the `0.8.42` measured route-output optimization are complete. Continue item 6 with route capability signatures and emitted shared-chunk reporting; keep ResourceIR limited to cross-owner fixtures and do not skip directly to a public adapter/store API, router, virtualization, or unsupported ecosystem package feature.

package/docs/next-architecture/versioning.md

@@ -1,6 +1,6 @@
 # Planned Version Sequence
 
-This is an execution sequence, not release history. `0.8.16` through `0.8.51` are completed scopes represented by package/release records.
+This is an execution sequence, not release history. `0.8.16` through `0.8.53` are completed scopes represented by package/release records.
 
 Keep each patch behavior-preserving and independently reviewable. If a boundary proves inseparable, revise this plan before combining releases; do not silently broaden a patch.
 
@@ -42,6 +42,8 @@ Keep each patch behavior-preserving and independently reviewable. If a boundary
 | `0.8.49` | Fan one setter-callback prop out through multiple direct child component event props. | Every branch lowers to the original parent signal; aliases, ordinary props, spreads, and the fourth boundary fail without a runtime change. |
 | `0.8.50` | Isolate reduced Zustand migration behind package-neutral shared-state and action IR. | Validated shared identities/actions preserve RouteIR, layout lifetime, same-turn updates, diagnostics, browser behavior, and zero store runtime. |
 | `0.8.51` | Bundle direct browser-only package references from inline owned effect setup/cleanup callbacks. | Package code stays in referenced route effect ESM; build scratch and static siblings omit it while indirect/render-time uses fail. |
+| `0.8.52` | Lower effect-exclusive mutable refs into setup-invocation closures. | E2B and WebSocket fixtures preserve generation, replacement, BFCache, and cleanup without captures, ResourceIR, or static-sibling JavaScript. |
+| `0.8.53` | Close source CSS over each route's reachable TypeScript graph and reconcile managed styles during navigation. | Routes exclude unrelated CSS; destination styles load before replacement, shared layout links retain identity, and cancelled loads roll back safely. |
 
 ## Sequence Rules
 

package/framework/README.md

@@ -6,7 +6,7 @@ Migration source may retain conventional `react` imports for supported named or
 
 Compilation begins from page entries and follows relative runtime imports, re-exports, and validated Worker references; unreachable TypeScript migration files are not transformed. Direct maps over imported immutable JSON-safe arrays fold to literals for zero-JavaScript static rows. Synchronous relative calculation functions may return objects whose direct static fields feed reactive JSX bindings; build rendering uses current signal values and route-specific binding ESM reevaluates the same helper after state commits. One direct array field may instead feed a keyed intrinsic map: its evaluator refreshes a compiler-owned array anchor before the existing list reconciler runs, preserving keyed DOM and SVG identity without a calculation runtime. That field must remain a JSON-safe array after every source-state commit. Package imports have a separate narrow boundary: direct references inside intrinsic JSX event callbacks are erased from build modules and bundled into route handler ESM, while render-time, effect, helper-indirect, and mixed package use fails.
 
-Native platform work remains ordinary source. A direct async handler or directly returned relative custom-hook callback may call `navigator.clipboard.writeText()` and update application-owned success/failure state; Kudzu emits only its existing route handler ESM. Debounced synchronization uses a dependency effect that creates `setTimeout()` work and directly returns `clearTimeout()` cleanup, reusing dependency, conditional, keyed, and route ownership. One directly returned relative custom-hook callback may own one `null`-initialized private timeout ref when it directly clears the previous value, assigns a numeric-literal-delay `setTimeout()`, and an empty-dependency effect directly clears the timer on cleanup. Kudzu lowers that ref to compiler-owned state shared by existing handler and effect contexts. An ordinary effect may instead exclusively own `useRef(0)` as one animation-frame handle when a local callback resets it, one scheduler assigns `requestAnimationFrame()`, and cleanup cancels the pending frame; Kudzu lowers it to the existing effect scope without an animation runtime. Multiple timers, dynamic delays, intervals, ref aliases, cross-effect frame handles, unowned delayed writes, and arbitrary timed callback graphs remain unsupported.
+Native platform work remains ordinary source. A direct async handler or directly returned relative custom-hook callback may call `navigator.clipboard.writeText()` and update application-owned success/failure state; Kudzu emits only its existing route handler ESM. Debounced synchronization uses a dependency effect that creates `setTimeout()` work and directly returns `clearTimeout()` cleanup, reusing dependency, conditional, keyed, and route ownership. One directly returned relative custom-hook callback may own one `null`-initialized private timeout ref when it directly clears the previous value, assigns a numeric-literal-delay `setTimeout()`, and an empty-dependency effect directly clears the timer on cleanup. Kudzu lowers that ref to compiler-owned state shared by existing handler and effect contexts. An ordinary inline effect may exclusively own top-level `useRef(null)` and `useRef(0)` values through direct `.current` references; Kudzu moves them into the setup invocation's closure for browser SDK handles, WebSockets, generation tokens, and animation frames without serialized captures or a resource runtime. Multiple timers, dynamic delays, intervals, ref aliases, cross-effect/event mutable refs, unowned delayed writes, and arbitrary timed callback graphs remain unsupported.
 
 Imperative canvas migrations use the same effect ownership rather than a component or canvas runtime. One `null`-initialized canvas DOM ref may feed an inline effect whose local variables persist across a recursive animation-frame callback, an `IntersectionObserver`, and native canvas/window listeners; the returned cleanup must cancel the latest frame, disconnect the observer, and remove every listener. Bare `IntersectionObserver` and `performance` identifiers remain browser globals in emitted effect ESM. Component-level mutable value refs and callbacks shared across effects or JSX handlers remain unsupported; move resource-private state and listeners into the owning effect.
 
@@ -76,7 +76,7 @@ Static routes receive no browser runtime. Command routes receive `runtime.js`; d
 
 Exact relative `.worker.ts` constructors in inline effects are validated and bundled in a separate content-hashed ESM graph under `dist/assets/workers/`. Those files are referenced only by rendered effect handlers and never become document capability scripts, preloads, or window imports; unreachable source effects do not emit their Worker roots. Worker graphs allow relative TypeScript ESM runtime imports only and reject JSX, package runtime imports, import-equals declarations, dynamic imports, `require()`, and paths outside `src`. Ordinary runtime imports or re-exports of `.worker.ts` and Worker construction in imported keyed-row effects are rejected.
 
-Page `metadata` can emit description, canonical, favicon, manifest, Open Graph, and Twitter Card tags without a client runtime. Source CSS and global `kudzu.config` styles are emitted in document heads before `afterBuild()` runs; static stylesheet links in component JSX fail compilation instead of loading from the body.
+Page `metadata` can emit description, canonical, favicon, manifest, Open Graph, and Twitter Card tags without a client runtime. Relative source CSS imports follow each page's reachable TypeScript graph and link only from those routes; `kudzu.config` styles remain explicitly global. Enhanced navigation loads incoming managed styles before route replacement, reuses shared links, and removes outgoing links. All styles are emitted before `afterBuild()` runs; static stylesheet links in component JSX fail compilation instead of loading from the body.
 
 Inline SVG rendering normalizes an explicit set of common React presentation aliases before static serialization and binding descriptor creation. Reactive aliases use the existing generic `setAttribute` path. Reactive conditionals and flat intrinsic keyed lists store inert branch or row markup on SVG markers and parse it in the actual parent namespace only when replacement nodes are needed; existing condition/list ownership then handles insertion, identity, updates, and removal. Focus, keyboard, and click handlers on keyed SVG points may update parent state for an external accessible HTML tooltip, and retained handlers read the latest item after list updates. Builds without structural SVG compile out that fragment path, and static SVG adds no JavaScript. Keyed-item conditions, nested SVG lists, MathML structures, and namespaced attributes remain unsupported.
 

package/framework/build.mjs

@@ -62,6 +62,8 @@ async function buildInto(project, outputDirectory, { minify }) {
   const config = await loadConfig(root)
   const base = normalizeBase(config.base)
   const configuredStyles = normalizeStyles(config.styles, base, project)
+  const globalStyleUrls = [...new Set(configuredStyles.urls)]
+  const globalStyleUrlSet = new Set(globalStyleUrls)
   const publicDirectory = normalizePublicDirectory(config.publicDir, project)
   const navigationGroups = normalizeNavigation(config.navigation)
   const navigationRoutes = navigationGroups.flatMap(group => group.routes)
@@ -82,7 +84,6 @@ async function buildInto(project, outputDirectory, { minify }) {
   const projectFiles = await walk(sourceDirectory)
   const allSourceFiles = projectFiles.filter(file => /\.(?:ts|tsx)$/.test(file) && !file.endsWith(".d.ts")).sort()
   const configuredStyleSources = new Set(configuredStyles.sources.map(style => style.source))
-  const discoveredCssFiles = projectFiles.filter(file => file.toLowerCase().endsWith(".css") && !configuredStyleSources.has(file)).sort()
   if (!allSourceFiles.length) throw new Error("No TypeScript files found in src/")
   const allSourceFileSet = new Set(allSourceFiles)
   const sourceIndex = project.sourceIndex
@@ -93,7 +94,8 @@ async function buildInto(project, outputDirectory, { minify }) {
   const sourceFileSet = project.sourceFiles
   for (const file of sourceFiles) sourceFileSet.add(file)
   const staticFiles = await safeStaticFiles(projectFiles)
-  const cssFiles = orderSourceStyles(discoveredCssFiles, sourceFiles, sourceIndex, staticFiles)
+  const stylesByPage = new Map(pageFiles.map(file => [file, orderSourceStyles([file], sourceFiles, sourceIndex, staticFiles).filter(style => !configuredStyleSources.has(style))]))
+  const cssFiles = [...new Set([...stylesByPage.values()].flat())]
   const importedAssets = new Set()
   const { cssModules, cssOutputs } = await prepareSourceStyles(cssFiles, staticFiles, importedAssets, base, project)
 
@@ -122,13 +124,11 @@ async function buildInto(project, outputDirectory, { minify }) {
   const emittedRoutes = new Set()
   const emittedApplicationRoutes = new Set()
   const emittedNavigationRecords = []
-  const styleUrls = [...new Set([
-    ...cssFiles.map(file => assetPath(base, `assets/${relative(sourceDirectory, file).replaceAll(sep, "/")}`)),
-    ...configuredStyles.urls
-  ])]
   const runtimePlaceholder = `/__kudzu_runtime_${randomUUID()}.js`
 
   for (const pageFile of pageFiles) {
+    const sourceStyleUrls = stylesByPage.get(pageFile).map(file => assetPath(base, `assets/${relative(sourceDirectory, file).replaceAll(sep, "/")}`)).filter(url => !globalStyleUrlSet.has(url))
+    const styleUrls = [...sourceStyleUrls, ...globalStyleUrls]
     const compiledFile = compiledPath(pageFile)
     const module = await import(`${pathToFileURL(compiledFile).href}?v=${Date.now()}`)
     if (typeof module.default !== "function") throw new Error(`${relative(root, pageFile)} must export a default component`)
@@ -179,6 +179,7 @@ async function buildInto(project, outputDirectory, { minify }) {
         ...configuredMetadata,
         ...pageMetadata,
         styles: styleUrls.length ? styleUrls : false,
+        managedStyles: navigable ? sourceStyleUrls : [],
         base,
         runtimeAsset: runtimePlaceholder,
         effectAsset: assetPath(base, `assets/${effectPath}`),
@@ -352,16 +353,19 @@ async function buildInto(project, outputDirectory, { minify }) {
   }
   const sortedRewrites = rewrites.sort((left, right) => runtimeSpecificity(right) - runtimeSpecificity(left) || left.pattern.localeCompare(right.pattern))
   await writeFile(join(workDirectory, "kudzu-plan.json"), JSON.stringify({ routes: plans, rewrites: sortedRewrites }, null, 2))
+  const emittedCssFiles = new Set()
   for (const file of cssFiles.filter(file => renderedStyleUrls.has(assetPath(base, `assets/${relative(sourceDirectory, file).replaceAll(sep, "/")}`)))) {
     const output = join(assetsDirectory, relative(sourceDirectory, file))
     await mkdir(dirname(output), { recursive: true })
     await writeFile(output, cssOutputs.get(file))
+    emittedCssFiles.add(file)
   }
   for (const file of [...importedAssets].sort()) {
-    if (cssOutputs.has(file)) continue
     const output = join(assetsDirectory, relative(sourceDirectory, file))
     await mkdir(dirname(output), { recursive: true })
-    await writeFile(output, await readFile(file))
+    if (cssOutputs.has(file)) {
+      if (!emittedCssFiles.has(file)) await writeFile(output, cssOutputs.get(file))
+    } else await writeFile(output, await readFile(file))
   }
   for (const style of configuredStyles.sources.filter(style => renderedStyleUrls.has(withBase(base, style.output)))) {
     let css = await readFile(style.source, "utf8")

package/framework/compiler/{animation-frame-pass.mjs → effect-private-ref-pass.mjs}

@@ -1,7 +1,7 @@
 import ts from "typescript"
 import { effectReturns, importDeclarationNames, isShadowedIdentifier, nearestFunction, referenceIdentifiers, sourceNodeError, statementDeclaresName, unwrapExpression } from "./ast-helpers.mjs"
 
-export function normalizeEffectAnimationFrameRefs(sourceFile, factory, context) {
+export function normalizeEffectPrivateRefs(sourceFile, factory, context) {
     const frameCall = (node, name) => ts.isCallExpression(node) && (
       ts.isIdentifier(node.expression) && node.expression.text === name ||
       ts.isPropertyAccessExpression(node.expression) && ts.isIdentifier(node.expression.expression) && node.expression.expression.text === "window" && node.expression.name.text === name
@@ -28,32 +28,51 @@ export function normalizeEffectAnimationFrameRefs(sourceFile, factory, context)
     }
     const hasUseRefImport = sourceFile.statements.some(statement => ts.isImportDeclaration(statement) && !statement.importClause?.isTypeOnly && ts.isStringLiteral(statement.moduleSpecifier) && ["react", "@kudzujs/core"].includes(statement.moduleSpecifier.text) && statement.importClause?.namedBindings && ts.isNamedImports(statement.importClause.namedBindings) && statement.importClause.namedBindings.elements.some(entry => !entry.propertyName && entry.name.text === "useRef"))
     const hasUseEffectImport = sourceFile.statements.some(statement => ts.isImportDeclaration(statement) && !statement.importClause?.isTypeOnly && ts.isStringLiteral(statement.moduleSpecifier) && ["react", "@kudzujs/core"].includes(statement.moduleSpecifier.text) && statement.importClause?.namedBindings && ts.isNamedImports(statement.importClause.namedBindings) && statement.importClause.namedBindings.elements.some(entry => !entry.propertyName && entry.name.text === "useEffect"))
-    const replacements = new Set()
+    const privateRefs = new Map()
+    const effectRefs = new Map()
+    const registerPrivateRef = (node, callback) => {
+      const initializer = ts.isNumericLiteral(node.initializer.arguments[0]) ? factory.createNumericLiteral(0) : factory.createNull()
+      privateRefs.set(node, callback)
+      const refs = effectRefs.get(callback) ?? []
+      refs.push({ name: node.name.text, initializer })
+      effectRefs.set(callback, refs)
+    }
     const inspect = node => {
-      if (!hasUseRefImport || !ts.isVariableDeclaration(node) || !ts.isIdentifier(node.name) || !node.initializer || !ts.isCallExpression(node.initializer) || !ts.isIdentifier(node.initializer.expression) || node.initializer.expression.text !== "useRef" || isShadowedIdentifier(node.initializer.expression, sourceFile) || node.initializer.arguments.length !== 1 || !ts.isNumericLiteral(node.initializer.arguments[0]) || Number(node.initializer.arguments[0].text) !== 0) {
+      const refInitializer = ts.isVariableDeclaration(node) && node.initializer && ts.isCallExpression(node.initializer) ? node.initializer.arguments[0] : undefined
+      if (!hasUseRefImport || !ts.isVariableDeclaration(node) || !ts.isIdentifier(node.name) || !node.initializer || !ts.isCallExpression(node.initializer) || !ts.isIdentifier(node.initializer.expression) || node.initializer.expression.text !== "useRef" || isShadowedIdentifier(node.initializer.expression, sourceFile) || node.initializer.arguments.length !== 1 || !(refInitializer?.kind === ts.SyntaxKind.NullKeyword || ts.isNumericLiteral(refInitializer) && Number(refInitializer.text) === 0)) {
         ts.forEachChild(node, inspect)
         return
       }
       const owner = nearestFunction(node)
       if (!owner?.body || !ts.isBlock(owner.body)) return
-      const accesses = []
-      const collect = current => {
-        if (currentAccess(current, node.name.text) && !isShadowedIdentifier(current.expression, owner.body)) accesses.push(current)
-        ts.forEachChild(current, collect)
-      }
-      collect(owner.body)
+      const references = referenceIdentifiers(owner.body, node.name.text)
+      const invalidReference = references.find(reference => !ts.isPropertyAccessExpression(reference.parent) || reference.parent.expression !== reference || reference.parent.name.text !== "current")
+      const accesses = references.filter(reference => ts.isPropertyAccessExpression(reference.parent) && reference.parent.expression === reference && reference.parent.name.text === "current").map(reference => reference.parent)
       const frameAssignments = accesses.filter(access => ts.isBinaryExpression(access.parent) && unwrapExpression(access.parent.left) === access && access.parent.operatorToken.kind === ts.SyntaxKind.EqualsToken && frameCall(unwrapExpression(access.parent.right), "requestAnimationFrame") && unshadowedFrameCall(unwrapExpression(access.parent.right), owner))
-      if (!frameAssignments.length) return
-      const invalidReference = referenceIdentifiers(owner.body, node.name.text).find(reference => !ts.isPropertyAccessExpression(reference.parent) || reference.parent.expression !== reference || reference.parent.name.text !== "current")
-      if (invalidReference) throw sourceNodeError(invalidReference, sourceFile, "Animation frame refs may only use direct .current reads and assignments")
       const statement = node.parent?.parent
       const topLevelOwner = owner.parent === sourceFile || ts.isVariableDeclaration(owner.parent) && owner.parent.parent?.parent?.parent === sourceFile
-      if (!topLevelOwner || !ts.isVariableStatement(statement) || !(statement.declarationList.flags & ts.NodeFlags.Const) || statement.declarationList.declarations.length !== 1 || statement.parent !== owner.body) throw sourceNodeError(node, sourceFile, "Animation frame refs must be one top-level component const")
+      const topLevelConst = topLevelOwner && ts.isVariableStatement(statement) && (statement.declarationList.flags & ts.NodeFlags.Const) && statement.declarationList.declarations.length === 1 && statement.parent === owner.body
+      if (frameAssignments.length && invalidReference) throw sourceNodeError(invalidReference, sourceFile, "Animation frame refs may only use direct .current reads and assignments")
+      if (frameAssignments.length && !topLevelConst) throw sourceNodeError(node, sourceFile, "Animation frame refs must be one top-level component const")
+      if (!topLevelConst || invalidReference || !accesses.length) return
+      const effectCalls = owner.body.statements.flatMap(statement => hasUseEffectImport && ts.isExpressionStatement(statement) && ts.isCallExpression(statement.expression) && ts.isIdentifier(statement.expression.expression) && statement.expression.expression.text === "useEffect" && !isShadowedIdentifier(statement.expression.expression, sourceFile) ? [statement.expression] : [])
+      const effects = effectCalls.filter(effect => {
+        const callback = effect.arguments[0]
+        return callback && accesses.every(access => inside(access, callback))
+      })
+      if (!frameAssignments.length) {
+        const callback = effects.length === 1 ? effects[0].arguments[0] : undefined
+        if (callback && (ts.isArrowFunction(callback) || ts.isFunctionExpression(callback)) && ts.isBlock(callback.body)) {
+          const cleanups = effectReturns(callback).cleanups
+          const cleanupWrites = cleanups.length === 1 && accesses.some(access => inside(access, cleanups[0]) && ts.isBinaryExpression(access.parent) && unwrapExpression(access.parent.left) === access && access.parent.operatorToken.kind >= ts.SyntaxKind.FirstAssignment && access.parent.operatorToken.kind <= ts.SyntaxKind.LastAssignment)
+          if (!cleanupWrites) throw sourceNodeError(node, sourceFile, "Effect-private refs require one cleanup that directly resets or invalidates ref.current")
+          registerPrivateRef(node, callback)
+        }
+        return
+      }
       if (frameAssignments.length !== 1) throw sourceNodeError(node, sourceFile, "Animation frame refs require one direct ref.current = requestAnimationFrame(callback) assignment")
       const frame = unwrapExpression(frameAssignments[0].parent.right)
       const frameCallback = frame.arguments.length === 1 && ts.isIdentifier(unwrapExpression(frame.arguments[0])) ? unwrapExpression(frame.arguments[0]) : undefined
-      const effectCalls = owner.body.statements.flatMap(statement => hasUseEffectImport && ts.isExpressionStatement(statement) && ts.isCallExpression(statement.expression) && ts.isIdentifier(statement.expression.expression) && statement.expression.expression.text === "useEffect" && !isShadowedIdentifier(statement.expression.expression, sourceFile) ? [statement.expression] : [])
-      const effects = effectCalls.filter(effect => effect.arguments[0] && inside(frameAssignments[0], effect.arguments[0]))
       if (effects.length !== 1) throw sourceNodeError(node, sourceFile, "Animation frame refs must belong to one inline component effect")
       const effect = effects[0]
       const callback = effect.arguments[0]
@@ -89,14 +108,24 @@ export function normalizeEffectAnimationFrameRefs(sourceFile, factory, context)
       const cleanup = cancellation && returns.cleanups.find(candidate => nearestFunction(cancellation) === candidate)
       const cancellationStatement = cancellation?.parent
       if (cancellations.length !== 1 || !cleanup || !ts.isBlock(cleanup.body) || !ts.isExpressionStatement(cancellationStatement) || !directOrGuarded(cancellationStatement, cleanup.body, node.name.text, false)) throw sourceNodeError(node, sourceFile, "Animation frame refs require direct cancellation in effect cleanup")
-      replacements.add(node)
+      registerPrivateRef(node, callback)
     }
     inspect(sourceFile)
-    if (!replacements.size) return sourceFile
+    if (!privateRefs.size) return sourceFile
     const visitor = node => {
-      if (replacements.has(node)) return factory.updateVariableDeclaration(node, node.name, node.exclamationToken, node.type, factory.createObjectLiteralExpression([
-        factory.createPropertyAssignment("current", factory.createNumericLiteral(0))
-      ]))
+      if (ts.isVariableStatement(node) && node.declarationList.declarations.length === 1 && privateRefs.has(node.declarationList.declarations[0])) return undefined
+      const refs = effectRefs.get(node)
+      if (refs && (ts.isArrowFunction(node) || ts.isFunctionExpression(node)) && ts.isBlock(node.body)) {
+        const body = ts.visitEachChild(node.body, visitor, context)
+        const declarations = refs.map(ref => factory.createVariableStatement(undefined, factory.createVariableDeclarationList([
+          factory.createVariableDeclaration(ref.name, undefined, undefined, factory.createObjectLiteralExpression([
+            factory.createPropertyAssignment("current", ref.initializer)
+          ]))
+        ], ts.NodeFlags.Const)))
+        const nextBody = factory.updateBlock(body, [...declarations, ...body.statements])
+        if (ts.isArrowFunction(node)) return factory.updateArrowFunction(node, node.modifiers, node.typeParameters, node.parameters, node.type, node.equalsGreaterThanToken, nextBody)
+        return factory.updateFunctionExpression(node, node.modifiers, node.asteriskToken, node.name, node.typeParameters, node.parameters, node.type, nextBody)
+      }
       return ts.visitEachChild(node, visitor, context)
     }
     return ts.visitNode(sourceFile, visitor)

package/framework/compiler/runtime-codegen.mjs

@@ -113,7 +113,7 @@ async function mountInitial() {
 `, "", "initial effect mount"],
     ["  await ready\n", "", "initial effect readiness"],
     ["    const { incoming, parsed, capabilities } = documentResult\n", "    const { incoming, parsed } = documentResult\n", "navigation capability result"],
-    ["    await routeDispose()\n    if (current !== revision) return\n", "", "route effect disposal"],
+    ["    await routeDispose()\n    if (current !== revision) {\n      styleUpdate.rollback()\n      return\n    }\n", "", "route effect disposal"],
     ["    commit(incoming, parsed.nodes, capabilities.params, url.pathname, url.search)\n", "    commit(incoming, parsed.nodes)\n", "navigation capability commit"],
     ["    routeDispose = await capabilities.effects?.mountRouteEffects?.() ?? noDispose\n", "", "route effect mount"],
     ["  return { incoming, parsed, capabilities: await loadCapabilities(parsed), record }\n", "  await Promise.all(parsed.assets.filter(path => path !== navigationAsset).map(path => import(path)))\n  return { incoming, parsed, record }\n", "navigation capability load"],

package/framework/compiler/source-compiler.mjs

@@ -3,7 +3,7 @@ import { dirname, extname, isAbsolute, join, relative, resolve, sep } from "node
 import ts from "typescript"
 import { createBindingIndex } from "./analysis/binding-index.mjs"
 import { createComponentAnalysisSession } from "./analysis/component-analysis.mjs"
-import { normalizeEffectAnimationFrameRefs } from "./animation-frame-pass.mjs"
+import { normalizeEffectPrivateRefs } from "./effect-private-ref-pass.mjs"
 import { bindingNames, containsJsx, effectReturns, functionVarDeclaresName, importDeclarationNames, isFunctionLike, isLocalConst, isReferenceIdentifier, isShadowedByParameter, isShadowedIdentifier, isUnshadowedGlobal, nearestFunction, referenceIdentifiers, referencesIdentifier, sourceLocation, sourceNodeError, statementDeclaresName, unwrapExpression } from "./ast-helpers.mjs"
 import { normalizeMediaQueryExternalStores, normalizeNavigatorCapabilityConditions } from "./browser-signal-passes.mjs"
 import { analyzeCollectionPipeline, collectionExpression, collectionParameters, isArrayFromCall, mutatingCollectionMethods as mutatingListMethods, pureCollectionMathMethods as pureMathMethods, pureCollectionMethods as pureListMethods } from "./collection-analysis.mjs"
@@ -249,7 +249,7 @@ function normalizeCompilerSource(sourceFile, { base, context, file, importedColl
     source => normalizeMediaQueryExternalStores(source, factory, context),
     source => normalizeReactMigrationSyntax(source, factory, context, importedCollections ?? importedSerializableCollectionNames(source, file, sourceFiles, sourceIndex)),
     source => normalizeNavigatorCapabilityConditions(source, factory, context),
-    source => normalizeEffectAnimationFrameRefs(source, factory, context),
+    source => normalizeEffectPrivateRefs(source, factory, context),
     source => {
       const result = normalizeCustomHookTimerRefs(source, factory, context)
       customHookTimerStates = result.timerStates
@@ -723,7 +723,7 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
         const owner = nearestFunction(node)
         if (owner && node.initializer.expression.text === "useRef") {
           const nullInitializer = node.initializer.arguments.length === 1 && node.initializer.arguments[0].kind === ts.SyntaxKind.NullKeyword
-          if (!nullInitializer && owner.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.DefaultKeyword)) throw sourceNodeError(node.initializer, sourceFile, "Mutable value useRef() is unsupported except for an effect-owned useRef(0) animation-frame handle; otherwise keep resource-private mutable values inside the owning effect")
+          if (!nullInitializer && owner.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.DefaultKeyword)) throw sourceNodeError(node.initializer, sourceFile, "Mutable useRef() values must be referenced exclusively inside one owned effect; DOM refs require useRef(null)")
           if (nullInitializer) {
             ensureOwner(owner)
             componentAnalysis.registerRef(owner, { name: node.name.text, site: analysisSite(node, "hook"), source: analysisSource(node) })
@@ -3059,7 +3059,7 @@ async function safeStaticFiles(files) {
   return new Set(entries.filter(Boolean))
 }
 
-function orderSourceStyles(cssFiles, sourceFiles, sourceIndex, staticFiles) {
+function orderSourceStyles(entryFiles, sourceFiles, sourceIndex, staticFiles) {
   const ordered = []
   const seenStyles = new Set()
   const seenSources = new Set()
@@ -3069,11 +3069,13 @@ function orderSourceStyles(cssFiles, sourceFiles, sourceIndex, staticFiles) {
     seenSources.add(file)
     const sourceFile = parseSourceFile(file, sourceIndex.get(file))
     for (const statement of sourceFile.statements) {
-      if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier) || !statement.moduleSpecifier.text.startsWith(".")) continue
+      if ((!ts.isImportDeclaration(statement) && !ts.isExportDeclaration(statement)) || !runtimeModuleReference(statement) || !statement.moduleSpecifier || !ts.isStringLiteral(statement.moduleSpecifier) || !statement.moduleSpecifier.text.startsWith(".")) continue
       const specifier = statement.moduleSpecifier.text
-      if (staticImportExtension(specifier) === ".css") {
-        let target
-        try { target = resolveStaticImport(file, specifier, staticFiles) } catch { continue }
+      const queryIndex = specifier.indexOf("?")
+      const query = queryIndex === -1 ? "" : specifier.slice(queryIndex + 1)
+      if (ts.isImportDeclaration(statement) && staticImportExtension(specifier) === ".css") {
+        if (query) continue
+        const target = resolveStaticImport(file, specifier, staticFiles)
         if (!seenStyles.has(target)) {
           seenStyles.add(target)
           ordered.push(target)
@@ -3081,12 +3083,11 @@ function orderSourceStyles(cssFiles, sourceFiles, sourceIndex, staticFiles) {
         continue
       }
       if (isStaticImport(specifier)) continue
-      try { visit(resolveSourceImport(file, specifier, sourceSet)) } catch {}
+      visit(resolveSourceImport(file, specifier, sourceSet))
     }
   }
-  for (const file of sourceFiles.filter(file => file.startsWith(`${pagesDirectory}${sep}`) && file.endsWith(".tsx"))) visit(file)
-  for (const file of sourceFiles) visit(file)
-  return [...ordered, ...cssFiles.filter(file => !seenStyles.has(file))]
+  for (const file of entryFiles) visit(file)
+  return ordered
 }
 
 function staticImportEntry(node, sourceFile, file, staticFiles, importedAssets, cssModules, base, factory) {
@@ -3105,7 +3106,7 @@ function staticImportEntry(node, sourceFile, file, staticFiles, importedAssets,
   const extension = staticImportExtension(specifier)
   if (query === "url") {
     if (!node.importClause?.name || node.importClause.isTypeOnly || node.importClause.namedBindings) throw sourceNodeError(node, sourceFile, "Static assets require one default import")
-    if (extension !== ".css") importedAssets.add(target)
+    importedAssets.add(target)
     const value = factory.createStringLiteral(assetPath(base, `assets/${relative(sourceDirectory, target).replaceAll(sep, "/")}`))
     return staticImportReplacement(node.importClause.name.text, value, factory)
   }

package/framework/core.mjs

@@ -486,9 +486,11 @@ export async function renderPage(component, metadata = {}, props = {}, layout) {
     const title = escapeHtml(metadata.title ?? "Kudzu")
     const head = renderMetadata(metadata)
     const capability = metadata.navigationAsset ? " data-k-capability" : ""
+    const managedStyles = new Set(metadata.managedStyles ?? [])
+    const styleAnchor = metadata.navigationAsset ? "<meta data-k-style-anchor>" : ""
     const styles = metadata.styles === false
       ? ""
-      : (Array.isArray(metadata.styles) ? metadata.styles : [assetPath(metadata.base, "assets/style.css")]).map(href => `<link rel="stylesheet" href="${escapeAttribute(href)}">`).join("")
+      : (Array.isArray(metadata.styles) ? metadata.styles : [assetPath(metadata.base, "assets/style.css")]).map(href => `<link rel="stylesheet" href="${escapeAttribute(href)}"${managedStyles.has(href) ? " data-k-route-style" : ""}>`).join("")
     const runtime = renderContext.hasBehaviors
       ? `<script type="module"${capability} src="${escapeAttribute(metadata.runtimeAsset ?? assetPath(metadata.base, "assets/kudzu.js"))}"></script>`
       : ""
@@ -526,7 +528,7 @@ export async function renderPage(component, metadata = {}, props = {}, layout) {
       : ""
 
     return {
-      html: `<!doctype html><html lang="${escapeAttribute(metadata.lang ?? "en")}"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>${title}</title>${head}${styles}${runtime}${paramRuntime}${bindingRuntime}${listRuntime}${nativeRuntime}${effectRuntime}${navigationRuntime}</head><body${state}${textBindings}${metadata.applicationId ? ` data-k-application="${escapeAttribute(metadata.applicationId)}" data-k-layout="${escapeAttribute(metadata.layoutId)}" data-k-route="${escapeAttribute(metadata.routeId)}"` : ""}>${body}</body></html>`,
+      html: `<!doctype html><html lang="${escapeAttribute(metadata.lang ?? "en")}"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>${title}</title>${head}${styleAnchor}${styles}${runtime}${paramRuntime}${bindingRuntime}${listRuntime}${nativeRuntime}${effectRuntime}${navigationRuntime}</head><body${state}${textBindings}${metadata.applicationId ? ` data-k-application="${escapeAttribute(metadata.applicationId)}" data-k-layout="${escapeAttribute(metadata.layoutId)}" data-k-route="${escapeAttribute(metadata.routeId)}"` : ""}>${body}</body></html>`,
       hasBehaviors: renderContext.hasBehaviors,
       hasEffects: renderContext.hasEffects,
       hasParams: renderContext.hasParams,

package/framework/navigation-runtime.js

@@ -12,6 +12,7 @@ status.style.cssText = "position:fixed;top:0;left:0;width:1px;height:1px;padding
 document.body.append(status)
 
 let request
+let pendingStyleUpdate
 let revision = 0
 const documents = new Map()
 let observer
@@ -115,9 +116,12 @@ async function navigate(url, push) {
   const record = matchRoute(url.pathname)
   if (!record) return fallback(url, push)
   const current = ++revision
+  pendingStyleUpdate?.rollback()
+  pendingStyleUpdate = undefined
   request?.abort()
   request = new AbortController()
   let committed = false
+  let styleUpdate
   try {
     let documentResult
     const cached = documents.get(url.href)
@@ -128,8 +132,20 @@ async function navigate(url, push) {
     documents.set(url.href, Promise.resolve(documentResult))
     const { incoming, parsed, capabilities } = documentResult
     if (current !== revision) return
+    styleUpdate = prepareStyles(parsed.styles)
+    pendingStyleUpdate = styleUpdate
+    await styleUpdate.ready
+    if (current !== revision) {
+      styleUpdate.rollback()
+      return
+    }
     await routeDispose()
-    if (current !== revision) return
+    if (current !== revision) {
+      styleUpdate.rollback()
+      return
+    }
+    styleUpdate.commit()
+    if (pendingStyleUpdate === styleUpdate) pendingStyleUpdate = undefined
     commit(incoming, parsed.nodes, capabilities.params, url.pathname, url.search)
     committed = true
     routeDispose = await capabilities.effects?.mountRouteEffects?.() ?? noDispose
@@ -139,6 +155,8 @@ async function navigate(url, push) {
     status.textContent = `Navigated to ${document.title}`
     discover()
   } catch (error) {
+    styleUpdate?.rollback()
+    if (pendingStyleUpdate === styleUpdate) pendingStyleUpdate = undefined
     if (current !== revision || error.name === "AbortError") return
     fallback(url, push)
     if (committed) return
@@ -173,7 +191,73 @@ function validate(incoming, record) {
     return url.pathname
   })
   if (!assets.includes(navigationAsset)) throw new Error("Navigation capability asset is missing")
-  return { nodes, assets: [...new Set(assets)] }
+  const styles = [...incoming.head.querySelectorAll('link[data-k-route-style][rel="stylesheet"][href]')]
+  const styleUrls = styles.map(link => {
+    const url = new URL(link.href)
+    if (url.origin !== location.origin) throw new Error("Navigation stylesheet must be same-origin")
+    return url.href
+  })
+  if (new Set(styleUrls).size !== styleUrls.length) throw new Error("Navigation document has duplicate route stylesheets")
+  return { nodes, assets: [...new Set(assets)], styles }
+}
+
+function prepareStyles(incoming) {
+  const anchor = document.head.querySelector("meta[data-k-style-anchor]")
+  if (!anchor || document.head.querySelectorAll("meta[data-k-style-anchor]").length !== 1) throw new Error("Current navigation style anchor is invalid")
+  const current = [...document.head.querySelectorAll('link[data-k-route-style][rel="stylesheet"][href]')]
+  const place = links => {
+    let previous = anchor
+    for (const link of links) {
+      if (link.previousSibling !== previous) previous.after(link)
+      previous = link
+    }
+  }
+  const byUrl = new Map(current.map(link => [new URL(link.href).href, link]))
+  const next = []
+  const created = []
+  const loads = []
+  for (const source of incoming) {
+    const href = new URL(source.href).href
+    let link = byUrl.get(href)
+    if (link) byUrl.delete(href)
+    else {
+      link = document.importNode(source, true)
+      created.push(link)
+      loads.push(new Promise((resolve, reject) => {
+        link.addEventListener("load", resolve, { once: true })
+        link.addEventListener("error", () => reject(new Error("Navigation stylesheet failed to load")), { once: true })
+      }))
+    }
+    next.push(link)
+  }
+  let settled = false
+  let cancel
+  const update = {
+    ready: Promise.race([
+      Promise.all(loads),
+      new Promise((resolve, reject) => {
+        cancel = () => {
+          const error = new Error("Navigation stylesheet load was cancelled")
+          error.name = "AbortError"
+          reject(error)
+        }
+      })
+    ]),
+    commit() {
+      if (settled) return
+      settled = true
+      for (const link of byUrl.values()) link.remove()
+    },
+    rollback() {
+      if (settled) return
+      settled = true
+      place(current)
+      for (const link of created) link.remove()
+      cancel()
+    }
+  }
+  place(next)
+  return update
 }
 
 function commit(incoming, incomingNodes, initializeParams, pathname, search) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kudzujs/core",
-  "version": "0.8.51",
+  "version": "0.8.53",
   "description": "HTML-first TSX framework with synchronous state semantics and no virtual DOM",
   "type": "module",
   "license": "MIT",