@kudzujs/core 0.8.53 → 0.8.56

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.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.
+The executable post-`0.8.56` 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.
 
@@ -60,6 +60,7 @@ 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.
+- Interactive routes use deterministic signature-keyed runtime families. Equal standalone capability manifests share files, while each enhanced-navigation group unions its routes into one ESM singleton family for persistent layout state and lifecycle ownership.
 - 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.

package/PERFORMANCE.md

@@ -6,7 +6,19 @@ 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.53 Release Snapshot
+## Current 0.8.56 Release Snapshot
+
+Kudzu 0.8.56 avoids unaffected source compilation and build-time JSX execution during development. The focused two-route correctness fixture recompiles two of four modules and rerenders one of two pages after a route-owned helper edit; this is a work-reduction assertion, not a timing claim.
+
+## Maintained 0.8.55 Release Snapshot
+
+Kudzu 0.8.55 replaces site-wide runtime specialization with deterministic route or navigation-group capability families. Unrelated standalone capabilities no longer change another route's loaded runtime bytes or cache URL; no new timing claim is made.
+
+## Maintained 0.8.54 Release Snapshot
+
+Kudzu 0.8.54 retains esbuild output metadata and writes one compiler-scratch artifact report after bundling. Deploy runtime behavior and output selection are unchanged, and no new performance claim is made.
+
+## Maintained 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.
 

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.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).
+**Latest release: 0.8.56 - Incremental affected-route development builds.** Source edits now recompile and rerender only intersecting page graphs while preserving full-build output, navigation-group identity, and rollback-safe staging. Read the [release notes](./RELEASES.md#0856---incremental-affected-route-development-builds), open the [release page](https://github.com/kudzujs/kudzu/releases/tag/v0.8.56), 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,106 @@
 # Kudzu Releases
 
+## 0.8.56 - Incremental affected-route development builds
+
+Kudzu 0.8.56 keeps one project session alive during development so source edits recompile and rerender only the routes whose runtime graphs changed.
+
+### Changed in 0.8.56
+
+- The development server batches changed source paths and intersects them with current and prior per-page runtime graphs.
+- Unaffected compiled `SourceResult` and pre-family route render records are reused across successful rebuilds.
+- Every affected page recompiles its complete reachable graph so imported component specialization remains correct.
+- Enhanced-navigation groups invalidate together to preserve shared layout function and ESM singleton identity.
+- Generation-specific build-time module paths prevent stale Node ESM imports after both successful and failed builds.
+
+### Safety
+
+- Failed rebuilds retain the previous deployed output and carry every pending changed path into the next attempt.
+- Added and removed source files refresh the session index and reachable source set.
+- CSS, assets, and unknown source events conservatively invalidate every page.
+- Production builds retain the existing complete staging, collision checks, `afterBuild()`, and rollback-safe promotion.
+- No browser runtime, hydration layer, VDOM, retained component tree, or SPA router is added.
+
+### Validation
+
+- A focused independent-route fixture changes one route-owned helper and recompiles two of four modules while rerendering one of two pages.
+- Its unaffected interactive route is reused, its static sibling remains zero JavaScript, and incremental deploy output is byte-identical to a fresh-process full build.
+- Existing development error recovery, navigation groups, Workers, handlers, route families, and source-scale checks pass.
+- `npm run check`, `npm test`, and `npm run test:package` pass with all 222 tests and 171 generated pages.
+
+### Upgrade
+
+```sh
+npm install @kudzujs/core@^0.8.56
+```
+
+## 0.8.55 - Signature-keyed runtime families
+
+Kudzu 0.8.55 replaces site-wide runtime specialization with deterministic capability families loaded only by the routes that require them.
+
+### Changed in 0.8.55
+
+- Equal standalone CapabilityIR signatures share one runtime family under `assets/runtime/<family>/`.
+- Different route signatures emit isolated core, binding, list, effect, native, serialization, style, and selector modules.
+- Route-specific parameter, effect, and native entries import their assigned family directly.
+- Artifact report v2 records exact route signatures, assigned families, emitted family requirements, handlers, Workers, styles, and chunks.
+- Development state restoration discovers the family core module from the rendered document.
+
+### Navigation ownership
+
+- Every enhanced-navigation group unions its route capabilities into one family.
+- Persistent layout state, committers, mount hooks, unmount hooks, and native listeners retain one ESM singleton identity across group navigation.
+- Independent groups may reuse byte-identical family files while keeping their own route matcher and layout/application identity modules.
+
+### Output
+
+- Static routes emit no runtime family and remain zero JavaScript.
+- An unrelated standalone route capability no longer changes another route's loaded runtime bytes or cache URL.
+- Legacy root-level `assets/kudzu*.js` runtime files are no longer emitted.
+- No runtime loader, hydration layer, VDOM, component tree, or SPA router is added.
+
+### Validation
+
+- Focused tests cover signature deduplication, distinct capability isolation, deterministic IDs, navigation unions, static exclusion, shared handler/Worker chunks, and family-aware public collisions.
+- Existing navigation, effect, list, native, parameter, Worker, base-path, development restoration, and browser ownership journeys pass.
+- `npm run check`, `npm test`, and `npm run test:package` pass with all 221 tests and 170 generated pages.
+
+### Upgrade
+
+```sh
+npm install @kudzujs/core@^0.8.55
+```
+
+## 0.8.54 - Inspectable route artifact closure
+
+Kudzu 0.8.54 projects each validated route edge through the final handler and Worker bundle graphs into one inspectable artifact contract.
+
+### Changed in 0.8.54
+
+- `.kudzu/kudzu-artifacts.json` records every route in deterministic order.
+- Each route receives its exact CapabilityIR manifest, SHA-256 signature, and required runtime families.
+- Handler entry ownership derives from retained RouteBuildRecord references rather than HTML or filename inference.
+- Handler and Worker esbuild metafiles are followed transitively to report route-owned and shared chunks.
+- Chunks reached by multiple routes include a sorted reverse ownership list.
+- `afterBuild()` receives the same JSON-safe report as `artifacts`.
+
+### Boundaries
+
+- The report distinguishes exact route runtime requirements from the currently site-specialized runtime files.
+- Enhanced-navigation routes still share their existing ESM singleton and lifecycle boundary.
+- Signature-keyed runtime emission remains the next route-closure slice.
+- No runtime loader, manifest fetch, SPA router, or browser behavior is added.
+
+### Validation
+
+- Focused checks cover route-only and shared handler chunks, external-import exclusion, Worker ownership, shared Worker chunks, deterministic route order, and distinct capability signatures.
+- `npm run check`, `npm test`, and `npm run test:package` pass with all 220 tests and 169 generated pages.
+
+### Upgrade
+
+```sh
+npm install @kudzujs/core@^0.8.54
+```
+
 ## 0.8.53 - Route-aware CSS closure
 
 Kudzu 0.8.53 links source styles only from routes whose reachable TypeScript graph imports them.

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.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.
+The active post-`0.8.56` 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, structural per-route capability/chunk reporting, signature-keyed runtime families, incremental source and affected-route development builds, measured route-entry output optimization, and the plain TypeScript source-scale fast path are complete. ResourceIR remains research for cross-owner transports and subscriptions; range ownership, virtualization, and optimistic transactions still require independent fixtures. 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,15 +1,15 @@
 # Current Compiler Architecture
 
-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.
+This maps the current `0.8.56` 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
 
 | Responsibility | Current owner | Current contract |
 |---|---|---|
 | CLI entry | [`bin/kudzu.mjs`](../../bin/kudzu.mjs) | Dispatches build and development commands. |
-| Project session | [`framework/compiler/project-session.mjs`](../../framework/compiler/project-session.mjs), `createProjectSession()` | Owns one absolute root, standard project paths, source records, bound graph operations, and Worker compiler for a build. Omitted roots resolve from call-time CWD. |
+| Project session | [`framework/compiler/project-session.mjs`](../../framework/compiler/project-session.mjs), `createProjectSession()` | Owns one absolute root, standard project paths, source records, bound graph operations, and Worker compiler. Production builds use one session; development retains it across rebuilds. Omitted roots resolve from call-time CWD. |
 | Parsed module cache and symbols | [`framework/compiler/project-session.mjs`](../../framework/compiler/project-session.mjs) | Parses each unchanged source module once per ProjectSession and records source-local declaration/import/re-export sites. Stable ModuleSymbol records resolve direct, aliased, barrel, and `export *` exports with cycle and ambiguity checks; repeated resolutions are cached against their source dependencies, and normalization consumers locate the resolved SiteId in a fresh clone with independent parent links. |
-| Build orchestration | [`framework/build.mjs`](../../framework/build.mjs), `build()` | Coordinates config, discovery, source compilation, RouteBuildRecord collection, CapabilityIR projection, generator invocation, artifact emission, and `afterBuild`. |
+| Build orchestration | [`framework/build.mjs`](../../framework/build.mjs), `build()`, `buildWithSession()` | Coordinates config, discovery, source compilation, RouteBuildRecord collection, CapabilityIR projection, generator invocation, artifact emission, and `afterBuild`. A retained session caches source results and pre-family route renders by page graph; successful builds alone replace that cache. |
 | Reachability/import resolution | [`framework/compiler/source-compiler.mjs`](../../framework/compiler/source-compiler.mjs), `reachableSourceFiles()`; [`framework/compiler/source-graph.mjs`](../../framework/compiler/source-graph.mjs), `ordinaryRuntimeDependencies()`, `resolveSourceImport()` | Starts from page entries, follows relative runtime imports/re-exports and validated Worker references, excludes unreachable migration source, and fails unresolved ordinary edges or dynamic imports at the importer source location before code generation. |
 | Ordered normalization | [`framework/compiler/normalization-pipeline.mjs`](../../framework/compiler/normalization-pipeline.mjs), `applyNormalizationPasses()`; [`framework/compiler/source-compiler.mjs`](../../framework/compiler/source-compiler.mjs), `normalizeCompilerSource()` | Applies migration/resource passes in order and repairs TypeScript parent pointers after every structural change. Imported source uses the same pipeline. |
 | Focused normalization passes | [`framework/compiler/`](../../framework/compiler/) | React, Router, browser signals, animation-frame refs, custom-hook timers, Zustand, and render control each validate and lower a narrow source shape. |
@@ -19,7 +19,7 @@ This maps the current `0.8.53` architecture, built on the completed `0.8.23` Goa
 | Main semantic analysis | [`framework/compiler/source-compiler.mjs`](../../framework/compiler/source-compiler.mjs), `createKudzuTransformer()` | Produces transformed source plus explicit component, shared-state/action, handler, binding, derived, keyed, and effect ownership results. Zustand package syntax is resolved by its adapter before generic shared-state consumers. |
 | Component ownership analysis | [`framework/compiler/analysis/component-analysis.mjs`](../../framework/compiler/analysis/component-analysis.mjs) | Produces ComponentAnalysis v2 with ordered JSON-safe owner and specialization slots for state, setters, props, refs, IDs, direct SignalIR links, structural OwnerRefs, source-local SiteIds, and source provenance. Three direct callback/ref component boundaries specialize into the same parent signal and intrinsic ownership; Context action-private setters may remain compiler-only and receive collision-free consumer-local aliases; AST identity remains private to its source-local session. |
 | Per-source descriptor registration | [`framework/compiler/descriptor-session.mjs`](../../framework/compiler/descriptor-session.mjs), `createSemanticArtifact()`, `createDescriptorSession()` | Keeps AST descriptors private during analysis, then finalizes ModuleIR v2 with deterministic SymbolRef, SharedStateIR, SharedActionIR, SignalIR, HandlerIR, BindingIR, DerivedIR, EffectIR, KeyedBlockIR, and ImportIR slots. One fail-closed boundary validates every source-local and component ownership edge before build-module generation. |
-| Route artifact graph | [`framework/compiler/route-build-record.mjs`](../../framework/compiler/route-build-record.mjs), `createRouteBuildRecord()`, `planRouteArtifacts()` | Validates each rendered route's RouteIR, capabilities, entry paths, styles, and exact handler/effect references. Handler modules, Workers, package-client modules, and bundle entry/chunk closure derive from structural edges without serialized output searches or formatted composite keys. |
+| Route artifact graph | [`framework/compiler/route-build-record.mjs`](../../framework/compiler/route-build-record.mjs), `createRouteBuildRecord()`, `planRouteArtifacts()`; [`framework/compiler/route-artifact-report.mjs`](../../framework/compiler/route-artifact-report.mjs), `createRouteArtifactReport()` | Validates each rendered route's RouteIR, capabilities, entry paths, styles, and exact handler/effect references. Handler and Worker esbuild metafiles project transitive output edges back through those records into deterministic per-route capability signatures and runtime requirements plus emitted handler, Worker, stylesheet, and shared-chunk closure. |
 | Route contract validation | [`framework/compiler/route-ir.mjs`](../../framework/compiler/route-ir.mjs), `assertRouteIR()` | Fails before artifact selection for invalid state/parameter identity, commands, native/effect captures and dependencies, reactive descriptors, conditions, keyed-list identity/ownership, marker fields, or JSON safety. Immutable in-memory contracts validate once by identity. |
 | Command IR and codegen | [`framework/compiler/optimize/command-specialization.mjs`](../../framework/compiler/optimize/command-specialization.mjs), [`framework/compiler/ir/module-ir.mjs`](../../framework/compiler/ir/module-ir.mjs), [`framework/compiler/codegen/command-codegen.mjs`](../../framework/compiler/codegen/command-codegen.mjs) | Direct commands use the existing fast path; proven immutable state aliases and one-call local helpers specialize to the same JSON-safe command ModuleIR. Recursion, escape, mutation, and dynamic helper dispatch fail explicitly, while unrelated handlers retain native ESM. Codegen emits the existing `__kBehavior` AST and command ABI. |
 | Source compilation | [`framework/compiler/source-compiler.mjs`](../../framework/compiler/source-compiler.mjs), `compileSource()` | Runs TypeScript with the Kudzu transformer, rejects surviving React/Router references, and returns a JSON-safe project-relative build module, component analysis, ModuleIR, optional handler module, and imported assets without filesystem writes. |
@@ -29,13 +29,13 @@ This maps the current `0.8.53` architecture, built on the completed `0.8.23` Goa
 | Worker graph | [`framework/compiler/worker-compiler.mjs`](../../framework/compiler/worker-compiler.mjs) | Returns functional Worker rewrite results and JSON-safe EffectIR edges, validates relative graphs, emits content-hashed ESM, and resolves placeholders only for rendered effects. |
 | Shared path conversion | [`framework/compiler/path-helpers.mjs`](../../framework/compiler/path-helpers.mjs) | Converts project-relative module, browser, asset, and base paths for build and development serving. |
 | Build-time JSX execution | [`framework/core.mjs`](../../framework/core.mjs), `renderPage()` | Executes compiled pages/layouts, allocates deterministic route/layout ownership IDs, emits complete HTML, and returns RouteIR v1 plus capability facts and exact retained handler references. |
-| Route capability projection | [`framework/compiler/route-capability-planner.mjs`](../../framework/compiler/route-capability-planner.mjs), `planRouteCapabilities()` | Validates RouteBuildRecord and RouteIR v1, purely folds their plans and capability facts into CapabilityIR v1, then checks standalone implications and exact projection equality before codegen. |
+| Route capability projection | [`framework/compiler/route-capability-planner.mjs`](../../framework/compiler/route-capability-planner.mjs), `planRouteCapabilities()`; [`framework/compiler/runtime-family-planner.mjs`](../../framework/compiler/runtime-family-planner.mjs), `planRuntimeFamilies()` | Validates RouteBuildRecord and RouteIR v1, projects exact route CapabilityIR, deduplicates equal standalone signatures, and unions each enhanced-navigation group at one required ESM singleton boundary. |
 | Effect entry generation | [`framework/compiler/effect-codegen.mjs`](../../framework/compiler/effect-codegen.mjs) | Generates ordinary, dependency, owned, and navigable effect entries from rendered descriptors. |
 | Runtime generation | [`framework/compiler/runtime-codegen.mjs`](../../framework/compiler/runtime-codegen.mjs), [`framework/compiler/list-runtime-codegen.mjs`](../../framework/compiler/list-runtime-codegen.mjs), [`framework/compiler/param-codegen.mjs`](../../framework/compiler/param-codegen.mjs) | Consumes versioned contracts, specializes authored capability sources with fail-closed anchors, and returns source/define results without filesystem ownership. |
-| Artifact emission | `framework/build.mjs` | Selects route artifacts from RouteBuildRecord edges and shared runtimes from CapabilityIR, writes route HTML in bounded batches, writes and bundles the complete generation in a project-local staging sibling, copies public subtrees without replacing generated paths, runs `afterBuild`, then promotes with rollback so failed builds preserve the prior `dist`. Byte-identical native, parameter, and effect route entries share the first existing route path and one emitted file within the current build. |
+| Artifact emission | `framework/build.mjs` | Selects route artifacts from RouteBuildRecord edges, emits each distinct runtime family under `assets/runtime/<family>/`, writes route HTML in bounded batches, bundles in a project-local staging sibling, copies public subtrees without replacing generated paths, runs `afterBuild`, then promotes with rollback. Byte-identical native, parameter, and effect entries share one file only when their family imports also match. |
 | Browser capabilities | [`framework/*.js`](../../framework/) | Small optional modules for commands, bindings, lists, effects, native handlers, serialization, parameters, and navigation; native contexts invalidate writes and refs at DOM ownership release, with no component runtime. |
 | Opt-in navigation | [`framework/navigation-runtime.js`](../../framework/navigation-runtime.js) plus `framework/build.mjs` navigation configuration/emission | Fetches and validates complete same-origin documents, replaces only the marked route range, manages route/layout disposal, history, focus, finite prefetch retention, and native fallback. |
-| Development serving | [`framework/dev-server.mjs`](../../framework/dev-server.mjs) and [`framework/dev-state.js`](../../framework/dev-state.js) | Rebuild/watch/SSE and response-only short-lived state restoration; failed rebuilds show the existing error overlay while preserving the previous on-disk output. |
+| Development serving | [`framework/dev-server.mjs`](../../framework/dev-server.mjs) and [`framework/dev-state.js`](../../framework/dev-state.js) | Watches and batches changed source paths, recompiles and rerenders intersecting page graphs, then performs the existing complete staged artifact emission and SSE reload. Navigation groups invalidate together to retain one layout-function identity. Failed rebuilds preserve both prior output and pending invalidations while showing the existing error overlay. |
 
 ## Current Data Flow
 
@@ -43,6 +43,8 @@ This maps the current `0.8.53` architecture, built on the completed `0.8.23` Goa
 src/pages entries + config
   -> ProjectSession(root) with project paths, source records, parsed/symbol caches, graph, and Worker compiler
   -> project discovery and reachable relative graph
+       -> in development, intersect changed paths with current and prior per-page graphs
+       -> reuse unaffected SourceResult and pre-family route render records
   -> compileSource()
        -> ordered normalization and parent repair
        -> source-local binding index
@@ -56,11 +58,11 @@ src/pages entries + config
   -> validated RouteBuildRecord per emitted route
        -> capability facts, route entries, styles, handler/effect artifact edges
   -> remove unrendered handlers/effects/Workers
-   -> planRouteCapabilities(RouteBuildRecord[])
-       -> CapabilityIR v1
-  -> specialize and emit only selected runtime/capability ESM
+    -> planRuntimeFamilies(RouteBuildRecord[], navigation groups)
+        -> exact route signatures plus deduplicated standalone/group CapabilityIR families
+  -> specialize and emit each selected runtime family under assets/runtime/<family>/
        -> reuse exact generated route-entry transforms within this build
-  -> write route index.html, CSS/assets, Worker graphs, and rewrites into staging
+  -> write route index.html, CSS/assets, Worker graphs, rewrites, and per-route artifact closure into staging/scratch
   -> copy public paths only where they do not replace generated artifacts
   -> optional afterBuild() against staging
   -> rollback-safe promotion to dist; recover an interrupted backup on the next admitted build after stale-lock removal
@@ -75,6 +77,7 @@ The browser consumes static HTML first. State seeds and descriptors in that HTML
 - `build()` still owns filesystem writes after structural route artifact selection and generator results are produced.
 - Runtime generators intentionally specialize readable authored sources through exact anchors; every required anchor fails closed, but a future generator format may remove this transitional dependency.
 - Source reachability and source compilation remain in one session-bound compiler factory because both consume the same normalization and import graph contracts. ModuleSymbol resolution is stable across canonical and cloned trees; unsupported export syntax remains intentionally narrow.
+- Incremental development still reads the source tree, rebuilds graph closure, and emits a complete rollback-safe staging directory. It avoids unaffected compilation and build-time JSX execution; finer filesystem and artifact-write invalidation is not yet justified.
 - Imported declarations resolve by ModuleSymbol and source-local SiteId. Specialized and compiler-synthesized trees still use conservative name/scope fallback where the source-local binding index does not own the complete AST.
 
 These are future simplification opportunities, not incomplete Goal A contracts. Goal A changed no source support, browser output semantics, or browser architecture.

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

@@ -34,7 +34,7 @@ The current limiting architecture is observable in these files:
 
 | Concern | Current owner | Limitation to remove |
 |---|---|---|
-| Project graph | `framework/compiler/project-session.mjs`, `source-graph.mjs`, `build.mjs` | Explicit build-scoped root, parsed-module/export-summary cache, and source ownership; narrow export resolution and no incremental invalidation remain |
+| Project graph | `framework/compiler/project-session.mjs`, `source-graph.mjs`, `build.mjs` | Explicit project root, parsed-module/export-summary cache, source ownership, and development-session source/result/route-render invalidation; export resolution remains intentionally narrow |
 | Normalization | `framework/compiler/source-compiler.mjs`, focused passes | Pass order and package ownership are implicit; semantically equal source often follows different shape-specific paths |
 | Component/state analysis | `framework/compiler/source-compiler.mjs`, `analysis/component-analysis.mjs` | AST identity, identifier text, source offsets, and caller-side AST specialization remain central |
 | Handler/binding analysis | `framework/compiler/descriptor-session.mjs`, `handler-lowering.mjs` | Capture/import/state discovery is name-based and arbitrary handlers become code before IR finalization |
@@ -383,8 +383,8 @@ After the relevant P0 foundations, investigate capabilities in this order:
 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. **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.
+6. Route/layout capability and CSS chunk closure. **Route/layout CSS closure completed in `0.8.53`; structural reporting completed in `0.8.54`; signature-keyed runtime emission completed in `0.8.55`:** each page's reachable TypeScript graph supplies exact stylesheet edges, and `.kudzu/kudzu-artifacts.json` follows handler and Worker metafiles transitively. Equal standalone CapabilityIR signatures now share one co-located runtime family, different signatures emit isolated files, and every enhanced-navigation group uses one union family so persistent layout state and lifecycle hooks retain a single ESM identity. Static routes emit no family, route entries import their assigned family, and unrelated route capabilities no longer change loaded runtime bytes or URLs.
+7. Incremental source and affected-route builds. **Completed in `0.8.56`:** development retains one ProjectSession, intersects batched changed paths with current and prior per-page runtime graphs, recompiles the complete graph of only affected pages, and reuses unaffected SourceResult and pre-family route render records. Enhanced-navigation groups invalidate together, failed builds retain pending changes and prior output, generation-specific build modules prevent stale Node ESM imports, and a focused independent-route fixture proves one helper change recompiles two of four modules, rerenders one of two pages, preserves a static zero-JavaScript sibling, and emits byte-identical deploy output to a fresh-process full build.
 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, 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.
+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, the `0.8.54` structural per-route capability/chunk report, the `0.8.55` signature-keyed runtime families, item 7 incremental source and affected-route builds, and the `0.8.42` measured route-output optimization are complete. Continue migration-led semantic generalization; keep ResourceIR limited to cross-owner fixtures and do not add range ownership, virtualization, optimistic transactions, a public adapter/store API, or a router before independent fixtures justify them.

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.53` are completed scopes represented by package/release records.
+This is an execution sequence, not release history. `0.8.16` through `0.8.56` 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.
 
@@ -44,6 +44,9 @@ Keep each patch behavior-preserving and independently reviewable. If a boundary
 | `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. |
+| `0.8.54` | Project per-route capability requirements and post-bundle handler/Worker chunk closure into an inspectable artifact contract. | Deterministic signatures, exact retained entries, transitive chunks, reverse shared ownership, static-route exclusion, and `afterBuild()` access pass. |
+| `0.8.55` | Emit deduplicated signature-keyed runtime families while preserving navigation-group singleton ownership. | Equal standalone signatures share files, different signatures isolate output, grouped routes share one union family, and static routes emit no runtime. |
+| `0.8.56` | Recompile and rerender only source-affected routes during development. | A route-owned helper edit recompiles two of four modules, rerenders one of two pages, and emits byte-identical deploy output to a fresh full build. |
 
 ## Sequence Rules
 

package/framework/README.md

@@ -49,6 +49,8 @@ Reduced Zustand migration stores lower through package-neutral `SharedStateIR` a
 - `compiler/render-control-pass.mjs`: render-function early-return and exhaustive adjacent-assignment normalization.
 - `compiler/router-pass.mjs`: React Router import validation and native Link, pathname parameter, search parameter, and imperative navigation lowering.
 - `compiler/route-capability-planner.mjs`: RouteIR v1 validation and pure CapabilityIR v1 projection into runtime and artifact requirements.
+- `compiler/runtime-family-planner.mjs`: deterministic standalone capability deduplication and enhanced-navigation group unioning at the ESM singleton boundary.
+- `compiler/route-artifact-report.mjs`: deterministic per-route capability signatures and runtime requirements plus handler, Worker, stylesheet, and transitive esbuild chunk closure reporting.
 - `compiler/runtime-codegen.mjs`: fail-closed core, effect, binding, native, and navigation runtime generation from CapabilityIR.
 - `compiler/list-runtime-codegen.mjs`: fail-closed keyed-list runtime generation from CapabilityIR list/effect sections.
 - `compiler/worker-compiler.mjs`: relative TypeScript Worker candidate validation, effect rewriting, graph validation, and content-hashed ESM emission.
@@ -70,6 +72,8 @@ Reduced Zustand migration stores lower through package-neutral `SharedStateIR` a
 
 Compiler ownership follows explicit stages. `build.mjs` coordinates project discovery, source compilation, RouteIR rendering, RouteBuildRecord collection, CapabilityIR planning, generator calls, and artifact emission. `compiler/normalization-pipeline.mjs` owns pass order and parent repair. The main transformer analyzes normalized source while `compiler/descriptor-session.mjs` owns one per-source semantic artifact containing HandlerIR, BindingIR, DerivedIR, KeyedBlockIR, EffectIR, and client imports. `core.mjs` emits complete HTML, RouteIR v1, and exact handler references: route-local state `slot` is an internal array reference, `id` remains the browser/DOM identity, and `name` remains readable development metadata. `compiler/route-build-record.mjs` validates structural artifact edges, and `compiler/route-capability-planner.mjs` projects CapabilityIR v1 from those records. Focused codegen modules consume IR/descriptors and return route-specific source without source analysis or filesystem ownership. The completed architecture record lives in `docs/next-architecture`; it adds no runtime or accepted syntax by itself.
 
+`.kudzu/kudzu-artifacts.json` records each route's exact CapabilityIR signature, assigned emitted runtime family, handler, Worker, stylesheet, and transitive chunk edges. Equal standalone signatures reuse `dist/assets/runtime/<family>/`; every enhanced-navigation group intentionally shares one union family. The same JSON-safe contract is available to `afterBuild()` as `artifacts`.
+
 New syntax support belongs in an existing pass or a focused new pass only when a reduced migration fixture proves it. Passes must preserve source-located diagnostics, avoid module-global analysis state, and expose metadata through return values rather than AST-identity side channels. Build orchestration stays in `build.mjs`; feature-specific graph validation or code generation moves under `compiler/` when it has a stable input/output boundary.
 
 Static routes receive no browser runtime. Command routes receive `runtime.js`; dependency effects use route-specific `kudzu-deps.js` unless that route already requires shared commit hooks; runtime bracket pages using `useParams()` add one route-specific pathname matcher; reactive attributes and conditions add `binding-runtime.js`; keyed lists add `list-runtime.js`; native handlers add `native-runtime.js`; effects add `effect-runtime.js` and one route-specific entry. Generated module scripts live in the document head, so cold downloads overlap HTML transfer while standard module deferral preserves execution after parsing. A single effect with one dependency compiles to a direct runner; generic maps, sets, and ordering are reserved for larger effect graphs. Dependency commits coalesce in a microtask; affected cleanups are awaited in declaration order before replacement setups run. Document cleanup integrates with shared unmount hooks when present and otherwise disposes directly on non-persisted `pagehide`. List builds remove unused text-range, attribute, event, expression, condition, seed, and mount branches. Effect builds omit capture deserialization entirely when every effect scope is empty. Capability runtimes share state and lifecycle hooks through `shared-runtime.js`. Generated evaluators and their bundled relative TypeScript helpers live under `dist/assets/handlers/`; shared helper chunks are emitted only when multiple handler entries need them. Runtime fallback rewrites are ordered by specificity in `.kudzu/kudzu-plan.json` and passed to `afterBuild()`; exact static files take precedence in development. The dev server derives stable state identities from route-unique state variable names in each route plan; every state sharing a duplicate name is omitted. It then injects its SSE reload, short-lived full-URL-scoped logical-state snapshot, and build-error client into responses only, never into `dist/`. Snapshots are consumed even when the next page is static or broken. Reload restoration covers compatible framework state, not uncontrolled DOM state, focus, selection, or imperative mutations.