@kudzujs/core 0.8.55 → 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.55` 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.
 

package/PERFORMANCE.md

@@ -6,7 +6,11 @@ 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.55 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.
 

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.55 - Signature-keyed runtime families.** Equal standalone capability signatures reuse one runtime family, different signatures stay isolated, and enhanced-navigation groups retain one union ESM singleton for layout state and lifecycle ownership. Read the [release notes](./RELEASES.md#0855---signature-keyed-runtime-families), open the [release page](https://github.com/kudzujs/kudzu/releases/tag/v0.8.55), 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,38 @@
 # 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.

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.55` 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, measured route-entry output optimization, and the plain TypeScript source-scale fast path are complete. Incremental source and affected-route builds 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.55` 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. |
@@ -35,7 +35,7 @@ This maps the current `0.8.55` architecture, built on the completed `0.8.23` Goa
 | 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.55` 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
@@ -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 |
@@ -384,7 +384,7 @@ After the relevant P0 foundations, investigate capabilities in this order:
 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`; 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.
+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, the `0.8.54` structural per-route capability/chunk report, the `0.8.55` signature-keyed runtime families, and the `0.8.42` measured route-output optimization are complete. Continue with item 7 incremental source and affected-route builds; 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.55` 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.
 
@@ -46,6 +46,7 @@ Keep each patch behavior-preserving and independently reviewable. If a boundary
 | `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/build.mjs

@@ -1,6 +1,6 @@
 import { createHash, randomUUID } from "node:crypto"
 import { cp, mkdir, open, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises"
-import { dirname, join, relative, resolve, sep } from "node:path"
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path"
 import { pathToFileURL } from "node:url"
 import { build as bundle, transform } from "esbuild"
 import { createEffectCodegen } from "./compiler/effect-codegen.mjs"
@@ -33,6 +33,10 @@ async function loadConfig(root) {
 
 export async function build({ quiet = false, minify = true, root: projectRoot = process.cwd() } = {}) {
   const project = createProjectSession(projectRoot)
+  return buildWithSession(project, { quiet, minify })
+}
+
+export async function buildWithSession(project, { changedFiles, quiet = false, minify = true } = {}) {
   const { root, outputDirectory } = project
   const stagedOutput = join(root, ".kudzu-dist-staging")
   const backupOutput = join(root, ".kudzu-dist-backup")
@@ -41,8 +45,9 @@ export async function build({ quiet = false, minify = true, root: projectRoot =
   try {
     await recoverOutput(outputDirectory, backupOutput)
     await rm(stagedOutput, { recursive: true, force: true })
-    const { result, pageCount, behaviorCount } = await buildInto(project, stagedOutput, { minify })
+    const { result, pageCount, behaviorCount, cache } = await buildInto(project, stagedOutput, { changedFiles, minify })
     await promoteOutput(stagedOutput, outputDirectory, backupOutput)
+    project.buildCache = cache
     if (!quiet) console.log(`Built ${pageCount} page(s), ${behaviorCount} interactive page(s) into dist/`)
     return result
   } finally {
@@ -58,8 +63,11 @@ export async function build({ quiet = false, minify = true, root: projectRoot =
   }
 }
 
-async function buildInto(project, outputDirectory, { minify }) {
+async function buildInto(project, outputDirectory, { changedFiles, minify }) {
   const { root, sourceDirectory, pagesDirectory, workDirectory } = project
+  const previous = project.buildCache
+  project.buildGeneration = (project.buildGeneration ?? 0) + 1
+  project.buildDirectory = project.buildGeneration > 1 ? join(workDirectory, "build", String(project.buildGeneration)) : workDirectory
   const { collectClientModules, compileClientModule, compiledPath, compileSource, layoutExportError, orderSourceStyles, reachableSourceFiles, safeStaticFiles } = createSourceCompiler(project)
   const config = await loadConfig(root)
   const base = normalizeBase(config.base)
@@ -89,11 +97,14 @@ async function buildInto(project, outputDirectory, { minify }) {
   if (!allSourceFiles.length) throw new Error("No TypeScript files found in src/")
   const allSourceFileSet = new Set(allSourceFiles)
   const sourceIndex = project.sourceIndex
+  for (const file of sourceIndex.keys()) if (file.startsWith(`${sourceDirectory}${sep}`) && !allSourceFileSet.has(file)) sourceIndex.delete(file)
   for (const [file, source] of await Promise.all(allSourceFiles.map(async file => [file, await readFile(file, "utf8")]))) sourceIndex.set(file, source)
   const pageFiles = allSourceFiles.filter(file => file.startsWith(`${pagesDirectory}${sep}`) && file.endsWith(".tsx"))
   if (!pageFiles.length) throw new Error("No pages found in src/pages/")
-  const sourceFiles = reachableSourceFiles(pageFiles, allSourceFileSet, sourceIndex)
+  const pageSources = new Map(pageFiles.map(file => [file, new Set(reachableSourceFiles([file], allSourceFileSet, sourceIndex))]))
+  const sourceFiles = [...new Set([...pageSources.values()].flatMap(files => [...files]))].sort()
   const sourceFileSet = project.sourceFiles
+  sourceFileSet.clear()
   for (const file of sourceFiles) sourceFileSet.add(file)
   const staticFiles = await safeStaticFiles(projectFiles)
   const stylesByPage = new Map(pageFiles.map(file => [file, orderSourceStyles([file], sourceFiles, sourceIndex, staticFiles).filter(style => !configuredStyleSources.has(style))]))
@@ -101,15 +112,26 @@ async function buildInto(project, outputDirectory, { minify }) {
   const importedAssets = new Set()
   const { cssModules, cssOutputs } = await prepareSourceStyles(cssFiles, staticFiles, importedAssets, base, project)
 
+  const affectedPages = affectedPageFiles({ changedFiles, pageFiles, pageSources, previous, sourceDirectory })
+  expandAffectedNavigationGroups(affectedPages, previous?.pageRenders, navigationGroups)
+  const affectedSources = new Set([...affectedPages].flatMap(file => [...pageSources.get(file)]))
   const sourceResults = []
+  const sourceResultsByFile = new Map()
+  let compiledModules = 0
   for (const file of sourceFiles) {
     if (file.endsWith(".worker.ts")) continue
-    const result = compileSource(file, sourceFileSet, sourceIndex, staticFiles, cssModules, base)
+    let result = !affectedSources.has(file) ? previous?.sourceResults.get(file) : undefined
+    if (!result) {
+      result = compileSource(file, sourceFileSet, sourceIndex, staticFiles, cssModules, base)
+      compiledModules++
+    }
+    result = { ...result, buildModule: { ...result.buildModule, path: relative(root, compiledPath(file)).replaceAll(sep, "/") } }
     for (const asset of result.importedAssets) importedAssets.add(resolve(root, asset))
     const output = resolve(root, result.buildModule.path)
     await mkdir(dirname(output), { recursive: true })
     await writeFile(output, result.buildModule.code)
     sourceResults.push(result)
+    sourceResultsByFile.set(file, result)
   }
   const handlerModules = sourceResults.flatMap(result => result.handlerModule ? [result.handlerModule] : [])
   const workerReferences = sourceResults.flatMap(result => result.moduleIR.effects.flatMap(effect => {
@@ -128,11 +150,37 @@ async function buildInto(project, outputDirectory, { minify }) {
   const emittedApplicationRoutes = new Set()
   const emittedNavigationRecords = []
   const navigationAssets = new Map()
-  const runtimePlaceholder = `/__kudzu_runtime_${randomUUID()}.js`
-  const bindingPlaceholder = `/__kudzu_binding_${randomUUID()}.js`
-  const listPlaceholder = `/__kudzu_list_${randomUUID()}.js`
+  const placeholders = previous?.placeholders ?? {
+    runtime: `/__kudzu_runtime_${randomUUID()}.js`,
+    binding: `/__kudzu_binding_${randomUUID()}.js`,
+    list: `/__kudzu_list_${randomUUID()}.js`
+  }
+  const runtimePlaceholder = placeholders.runtime
+  const bindingPlaceholder = placeholders.binding
+  const listPlaceholder = placeholders.list
+  const pageRenders = new Map()
+  let renderedPages = 0
 
   for (const pageFile of pageFiles) {
+    const cached = !affectedPages.has(pageFile) ? previous?.pageRenders.get(pageFile) : undefined
+    if (cached) {
+      replayPageRender(cached, {
+        emittedApplicationRoutes,
+        emittedNavigationRecords,
+        emittedRoutes,
+        navigationAssets,
+        navigationByRoute,
+        routeDrafts,
+        routeRecords,
+        rewrites
+      })
+      pageRenders.set(pageFile, cached)
+      continue
+    }
+    renderedPages++
+    const draftOffset = routeDrafts.length
+    const navigationOffset = emittedNavigationRecords.length
+    const rewriteOffset = rewrites.length
     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)
@@ -231,8 +279,14 @@ async function buildInto(project, outputDirectory, { minify }) {
       })
       routeRecords.push(record)
       if (navigationGroup) navigationGroup.buildRecords.push(record)
-      routeDrafts.push({ record, result, runtimeSchema, navigationGroup, effectPath, nativePath, paramPath })
+      routeDrafts.push({ record, result, runtimeSchema, navigationGroup, applicationRoute, effectPath, nativePath, paramPath })
     }
+    pageRenders.set(pageFile, {
+      drafts: routeDrafts.slice(draftOffset).map(({ navigationGroup: _, ...draft }) => draft),
+      layout: module.layout,
+      navigationRecords: emittedNavigationRecords.slice(navigationOffset).map(({ group: _, ...record }) => record),
+      rewrites: rewrites.slice(rewriteOffset)
+    })
   }
 
   for (const group of navigationGroups) for (const route of group.routes) if (!emittedApplicationRoutes.has(route)) throw new Error(`${group.label} route ${JSON.stringify(route)} is not an emitted route`)
@@ -435,7 +489,78 @@ async function buildInto(project, outputDirectory, { minify }) {
     await config.afterBuild({ root, outDir: outputDirectory, sourceDir: sourceDirectory, base, routes: plans.map(plan => plan.route), plans, rewrites: sortedRewrites, artifacts })
   }
 
-  return { result: { sourceResults }, pageCount: plans.length, behaviorCount }
+  const incremental = { compiledModules, renderedPages }
+  return {
+    result: { sourceResults, incremental },
+    pageCount: plans.length,
+    behaviorCount,
+    cache: { pageRenders, pageSources, placeholders, sourceResults: sourceResultsByFile }
+  }
+}
+
+function affectedPageFiles({ changedFiles, pageFiles, pageSources, previous, sourceDirectory }) {
+  if (!previous || changedFiles === undefined) return new Set(pageFiles)
+  if (changedFiles.some(file => typeof file !== "string")) return new Set(pageFiles)
+  const changes = new Set(changedFiles.map(file => isAbsolute(file) ? file : resolve(sourceDirectory, file)))
+  if ([...changes].some(file => !/\.(?:ts|tsx)$/.test(file))) return new Set(pageFiles)
+  const affected = new Set()
+  for (const page of pageFiles) {
+    const current = pageSources.get(page)
+    const prior = previous.pageSources.get(page)
+    if (!prior || [...changes].some(file => current.has(file) || prior.has(file))) affected.add(page)
+  }
+  return affected
+}
+
+function expandAffectedNavigationGroups(affected, pageRenders, groups) {
+  if (!affected.size || !pageRenders || !groups.length) return
+  const groupRoutes = groups.map(group => new Set(group.routes))
+  const groupIndexes = new Set()
+  for (const page of affected) {
+    const render = pageRenders.get(page)
+    if (!render) {
+      for (let index = 0; index < groups.length; index++) groupIndexes.add(index)
+      continue
+    }
+    for (const draft of render.drafts) for (let index = 0; index < groups.length; index++) if (groupRoutes[index].has(draft.applicationRoute)) groupIndexes.add(index)
+  }
+  for (const [page, render] of pageRenders) {
+    if (render.drafts.some(draft => [...groupIndexes].some(index => groupRoutes[index].has(draft.applicationRoute)))) affected.add(page)
+  }
+}
+
+function replayPageRender(cached, state) {
+  for (const rewrite of cached.rewrites) {
+    const conflicting = state.rewrites.find(entry => sameRuntimePrecedence(entry, rewrite))
+    if (conflicting) throw new Error(`Ambiguous runtime routes: ${conflicting.route} and ${rewrite.route}`)
+    state.rewrites.push(rewrite)
+  }
+  for (const entry of cached.navigationRecords) {
+    const group = state.navigationByRoute.get(entry.route)
+    const routeRecord = { ...entry, group }
+    state.emittedNavigationRecords.push(routeRecord)
+    state.emittedApplicationRoutes.add(entry.route)
+    if (!group) continue
+    if (typeof cached.layout !== "function") throw new Error(`${group.label} emitted route ${JSON.stringify(entry.record.path ?? entry.record.id)} must export a layout function so Kudzu can emit route markers`)
+    if (group.layoutIdentity && group.layoutIdentity !== cached.layout) throw new Error(`${group.label} routes ${JSON.stringify(group.layoutRoute)} and ${JSON.stringify(entry.route)} must export the same layout function identity`)
+    group.layoutIdentity = cached.layout
+    group.layoutRoute ??= entry.route
+    group.records.push(entry.record)
+    group.routeRecords.push(routeRecord)
+  }
+  for (const draft of cached.drafts) {
+    const navigationGroup = state.navigationByRoute.get(draft.applicationRoute)
+    if (state.emittedRoutes.has(draft.record.route)) throw new Error(`Duplicate route: ${draft.record.route}`)
+    state.emittedRoutes.add(draft.record.route)
+    if (navigationGroup) {
+      state.navigationAssets.set(draft.record.route, navigationGroup.assetPath)
+      navigationGroup.buildRecords.push(draft.record)
+      navigationGroup.hasEffects ||= draft.result.hasEffects
+      navigationGroup.hasParams ||= draft.result.hasParams
+    }
+    state.routeRecords.push(draft.record)
+    state.routeDrafts.push({ ...draft, navigationGroup })
+  }
 }
 
 async function acquireBuildLock(lockPath, root = dirname(lockPath)) {
@@ -609,7 +734,7 @@ export async function dev({ port = parseDevPort(process.env.PORT), host = parseD
   const project = createProjectSession(projectRoot)
   const { root, sourceDirectory, workDirectory, outputDirectory } = project
   const base = normalizeBase((await loadConfig(root)).base)
-  return startDevServer({ build: options => build({ ...options, root }), port, host, base, sourceDirectory, workDirectory, outputDirectory })
+  return startDevServer({ build: options => buildWithSession(project, options), port, host, base, sourceDirectory, workDirectory, outputDirectory })
 }
 
 function inlineJson(value) {

package/framework/compiler/source-compiler.mjs

@@ -24,6 +24,7 @@ import { createZustandPass } from "./zustand-pass.mjs"
 
 export function createSourceCompiler(project) {
 const { root, sourceDirectory, pagesDirectory, workDirectory, workerCompiler, modules, counters } = project
+const buildDirectory = project.buildDirectory ?? workDirectory
 const { ordinaryRuntimeDependencies, resolveSourceImport, runtimeModuleReference } = project.graph
 const parseSourceFile = (file, source) => modules.read(file, source).sourceFile
 const staticAssetExtensions = new Set([".avif", ".gif", ".ico", ".jpeg", ".jpg", ".otf", ".png", ".svg", ".ttf", ".webp", ".woff", ".woff2"])
@@ -3166,7 +3167,7 @@ function clientModulePath(file) {
 }
 
 function compiledPath(file) {
-  return join(workDirectory, relative(sourceDirectory, file)).replace(/\.(?:ts|tsx)$/, ".mjs")
+  return join(buildDirectory, relative(sourceDirectory, file)).replace(/\.(?:ts|tsx)$/, ".mjs")
 }
 
 const compileEventCommand = createCommandSpecializer({ isPrimitiveLiteral: isPrimitiveDefaultLiteral })

package/framework/dev-server.mjs

@@ -85,6 +85,7 @@ export async function startDevServer({ build, port, host, base, sourceDirectory,
   let rebuilding = false
   let pending = false
   let changedFile
+  const changedFiles = new Set()
   const rebuild = async () => {
     if (rebuilding) {
       pending = true
@@ -93,13 +94,16 @@ export async function startDevServer({ build, port, host, base, sourceDirectory,
     rebuilding = true
     do {
       pending = false
+      const changes = [...changedFiles]
+      changedFiles.clear()
       try {
-        await build({ quiet: true, minify: false })
+        await build({ changedFiles: changes, quiet: true, minify: false })
         buildError = undefined
         revision++
         console.log(`Rebuilt after ${changedFile ?? "source change"}`)
         for (const client of clients) sendEvent(client, "reload")
       } catch (error) {
+        for (const file of changes) changedFiles.add(file)
         buildError = errorText(error)
         console.error(error)
         for (const client of clients) sendEvent(client, "build-error", buildError)
@@ -110,6 +114,7 @@ export async function startDevServer({ build, port, host, base, sourceDirectory,
   const watcher = watch(sourceDirectory, { recursive: true })
   for await (const event of watcher) {
     changedFile = event.filename
+    changedFiles.add(event.filename)
     clearTimeout(timer)
     timer = setTimeout(rebuild, 80)
   }

package/package.json

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