evolit 0.1.0-alpha.26 → 0.1.0-alpha.28

package/README.md

@@ -131,6 +131,18 @@ Both hooks update after client navigation. `useParams()` returns a read-only sna
 `URLSearchParams` from `useSearchParams()` is a local snapshot, so build a new href and navigate to
 it to update the URL.
 
+### Development refresh
+
+In development, each browser subscribes its active URL over the Evolit WebSocket. After source
+invalidation, the server renders the fresh SSR representation once per request context and pushes
+the resulting delta directly to its subscribers. No follow-up browser request is needed. Server-only
+module and static-asset changes update only the affected route segment while preserving the document,
+scroll position, and persistent layouts.
+Changes to a hydrated client boundary rebuild its browser artifact and update the stable Evolit
+development proxy registered for that tag. Existing instances receive the new implementation
+without redefining the Custom Element or replacing the document. Invalid deltas and failed hot
+updates still fall back to a document reload.
+
 ### Progressive links and forms
 
 Links work without JavaScript. With JavaScript, Evolit intercepts ordinary same-origin left-clicks.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "evolit",
-  "version": "0.1.0-alpha.26",
+  "version": "0.1.0-alpha.28",
   "description": "A convention-driven application framework for LitSX and web components.",
   "type": "module",
   "packageManager": "yarn@4.10.3",
@@ -29,7 +29,8 @@
     "./server": {
       "browser": "./src/request-context-browser.js",
       "default": "./src/server-api.js"
-    }
+    },
+    "./internal/development-hot": "./src/development-hot-client.js"
   },
   "scripts": {
     "dev": "node ./src/cli.js dev",
@@ -54,9 +55,9 @@
   },
   "dependencies": {
     "@jridgewell/remapping": "^2.3.5",
-    "@litsx/compiler": "0.10.0-canary-feat-ssr-20260731112627",
-    "@litsx/core": "0.17.0-canary-feat-ssr-20260731112627",
-    "@litsx/ssr": "0.2.0-canary-feat-ssr-20260731112627",
+    "@litsx/compiler": "0.10.0-canary-feat-ssr-20260731234459",
+    "@litsx/core": "0.17.0-canary-feat-ssr-20260731234459",
+    "@litsx/ssr": "0.2.0-canary-feat-ssr-20260731234459",
     "@litsx/typescript": "^0.9.0",
     "@rollup/plugin-commonjs": "^29.0.0",
     "@rollup/plugin-node-resolve": "^16.0.3",

package/src/client-assets.js

@@ -27,6 +27,7 @@ const MODULE_SPECIFIER_PATTERN =
 
 const requireFromHere = createRequire(import.meta.url);
 const EVOLIT_NAVIGATION_BROWSER_ENTRY = fileURLToPath(new URL("./navigation-client.js", import.meta.url));
+const EVOLIT_DEVELOPMENT_HOT_ENTRY = fileURLToPath(new URL("./development-hot-client.js", import.meta.url));
 const SHARED_VENDOR_SPECIFIERS = [
   "@litsx/core",
   "@litsx/core/elements",
@@ -34,6 +35,9 @@ const SHARED_VENDOR_SPECIFIERS = [
   "evolit/navigation",
   "lit",
 ];
+const DEVELOPMENT_SHARED_VENDOR_SPECIFIERS = [
+  "evolit/internal/development-hot",
+];
 const browserSpecifierFilePathCache = new Map();
 const packageRootCache = new Map();
 const sharedRuntimeBuildCache = new Map();
@@ -303,6 +307,9 @@ export async function collectSharedVendorSpecifiers(
 ) {
   return [...new Set([
     ...(options.includeBase === false ? [] : SHARED_VENDOR_SPECIFIERS),
+    ...(options.includeBase === false || options.mode !== "development"
+      ? []
+      : DEVELOPMENT_SHARED_VENDOR_SPECIFIERS),
     ...additionalEntrySpecifiers.filter((specifier) => isBareSpecifier(specifier)),
   ])].sort();
 }
@@ -322,7 +329,9 @@ async function createSharedRuntimeInputEntries(projectRoot, entriesRoot, specifi
     }
     inputEntries[entryName] = specifier === "evolit/navigation"
       ? EVOLIT_NAVIGATION_BROWSER_ENTRY
-      : await resolveBrowserSpecifierFilePath(specifier, { projectRoot });
+      : specifier === "evolit/internal/development-hot"
+        ? EVOLIT_DEVELOPMENT_HOT_ENTRY
+        : await resolveBrowserSpecifierFilePath(specifier, { projectRoot });
   }
 
   return inputEntries;
@@ -512,7 +521,10 @@ export async function buildSharedVendorRuntime(
     });
     const additionalRuntimes = await Promise.all(
       additionalEntrySpecifiers
-        .filter((specifier) => !SHARED_VENDOR_SPECIFIERS.includes(specifier))
+        .filter((specifier) => ![
+          ...SHARED_VENDOR_SPECIFIERS,
+          ...DEVELOPMENT_SHARED_VENDOR_SPECIFIERS,
+        ].includes(specifier))
         .map((specifier) => buildSharedVendorRuntime(projectRoot, mode, {
           ...options,
           additionalEntrySpecifiers: [specifier],
@@ -548,6 +560,7 @@ export async function buildSharedVendorRuntime(
     );
     const specifiers = await collectSharedVendorSpecifiers(additionalEntrySpecifiers, {
       includeBase: options.includeBase !== false,
+      mode,
     });
     const inputEntries = await createSharedRuntimeInputEntries(projectRoot, entriesRoot, specifiers);
 
@@ -1161,7 +1174,8 @@ export function createHydrationBootstrap({
       : []).filter((moduleUrl) => typeof moduleUrl === "string" && moduleUrl.length > 0),
   )];
 
-  if (rootModuleUrls.length === 0 && clientImports.length === 0) {
+  const hasHydrationWork = rootModuleUrls.length > 0 || clientImports.length > 0;
+  if (!hasHydrationWork && !navigationModuleUrl) {
     return "";
   }
 
@@ -1169,9 +1183,8 @@ export function createHydrationBootstrap({
     .map((moduleUrl) => `  () => import(${JSON.stringify(moduleUrl)})`)
     .join(",\n");
 
-  const source = `
+  const hydrationSource = hasHydrationWork ? `
 import { hydratePage, registerHydrationModules } from ${JSON.stringify(hydrationModuleUrl)};
-${navigationModuleUrl ? `import { getNavigation } from ${JSON.stringify(navigationModuleUrl)};` : ""}
 
 await hydratePage({
   clientImports: ${JSON.stringify(clientImports)},
@@ -1179,10 +1192,13 @@ await hydratePage({
 ${moduleLoaders}
   ])
 });
-${navigationModuleUrl ? "getNavigation();" : ""}
-`;
+` : "";
+  const navigationSource = navigationModuleUrl ? `
+import { getNavigation } from ${JSON.stringify(navigationModuleUrl)};
+getNavigation();
+` : "";
 
-  return escapeInlineScriptText(source);
+  return escapeInlineScriptText(`${hydrationSource}${navigationSource}`);
 }
 
 export function normalizeHydrationDataForClient(

package/src/compiler.js

@@ -802,6 +802,56 @@ function getDevelopmentGraphCacheKey(entryPath, options) {
   ].join("::");
 }
 
+function wrapDevelopmentHydratableExports(code, moduleId, inputSourceMap = null) {
+  const sourcePath = moduleId;
+  const sourceFile = ts.createSourceFile(sourcePath, code, ts.ScriptTarget.Latest, true, ts.ScriptKind.JS);
+  const magicSource = new MagicString(code);
+  const exports = [];
+  let index = 0;
+  for (const statement of sourceFile.statements) {
+    if (!ts.isClassDeclaration(statement) || !statement.name) continue;
+    const isHydratable = statement.members.some((member) =>
+      member.name?.getText(sourceFile).includes('Symbol.for("litsx.hydratableTag")')
+    );
+    if (!isHydratable) continue;
+    const modifiers = statement.modifiers ?? [];
+    const isExported = modifiers.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword);
+    if (!isExported) continue;
+    const isDefault = modifiers.some((modifier) => modifier.kind === ts.SyntaxKind.DefaultKeyword);
+    for (const modifier of modifiers) {
+      if (modifier.kind === ts.SyntaxKind.ExportKeyword || modifier.kind === ts.SyntaxKind.DefaultKeyword) {
+        magicSource.remove(modifier.getStart(sourceFile), modifier.end);
+      }
+    }
+    const className = statement.name.text;
+    const proxyName = `__evolit_hot_${className}_${index++}`;
+    exports.push(
+      `const ${proxyName} = __evolitHotComponent(${JSON.stringify(moduleId)}, ${className});`,
+      isDefault ? `export default ${proxyName};` : `export { ${proxyName} as ${className} };`,
+    );
+  }
+  if (exports.length === 0) return { code, map: inputSourceMap };
+  magicSource.append(
+    '\nimport { hotComponent as __evolitHotComponent } from "evolit/internal/development-hot";\n'
+      + `${exports.join("\n")}\n`,
+  );
+  const hotTransformSource = `${moduleId}#evolit-hot`;
+  const hotTransformMap = magicSource.generateMap({
+    hires: true,
+    includeContent: false,
+    source: hotTransformSource,
+    file: moduleId,
+  });
+  return {
+    code: magicSource.toString(),
+    map: inputSourceMap
+      ? remapping(hotTransformMap.toString(), (source) => (
+        source.endsWith("#evolit-hot") ? inputSourceMap : null
+      ))
+      : null,
+  };
+}
+
 export function invalidateDevelopmentCompilationCache(projectRoot, changedPaths = null) {
   const resolvedProjectRoot = path.resolve(projectRoot);
   const prefix = `${resolvedProjectRoot}::`;
@@ -904,14 +954,24 @@ async function compileModuleGraphUncached(entryPath, options = {}) {
         clientImportParents,
       );
     }
-    const targetCode = target === "client" && isMixedComponentModule
+    const projectedCode = target === "client" && isMixedComponentModule
       ? createMixedModuleClientProjection(transformed.code, sourcePath)
       : transformed.code;
+    const targetTransform = target === "client" && mode === "development"
+      ? wrapDevelopmentHydratableExports(
+        projectedCode,
+        path.relative(projectRoot, sourcePath).split(path.sep).join("/"),
+        projectedCode === transformed.code ? transformed.map ?? null : null,
+      )
+      : {
+        code: projectedCode,
+        map: projectedCode === transformed.code ? transformed.map ?? null : null,
+      };
     const rewritten = await rewriteRelativeSpecifiers({
       projectRoot,
       outputRoot,
       sourcePath,
-      code: targetCode,
+      code: targetTransform.code,
       compileModule: (resolvedImportPath) => compileModule(resolvedImportPath, sourcePath),
       moduleMetadata,
       mode,
@@ -920,7 +980,7 @@ async function compileModuleGraphUncached(entryPath, options = {}) {
       serverImportQuery,
       sourceMaps,
       outputPath,
-      inputSourceMap: targetCode === transformed.code ? transformed.map ?? null : null,
+      inputSourceMap: targetTransform.map,
       onDevelopmentEvent,
       staticAssetFiles,
       managedSourceRoots,

package/src/deployment-runtime.js

@@ -250,6 +250,7 @@ export async function createRequestRenderer({
   const devBundledEntries = new Set();
   const devPreparedClientModules = new Set();
   const devClientModuleDependencies = new Map();
+  const devKnownClientBoundarySources = new Set();
   const devInventoryByEntry = new Map();
   const devServerAssetImportsByEntry = {};
   const devClientBoundariesByEntry = {};
@@ -412,8 +413,9 @@ export async function createRequestRenderer({
     ].filter((moduleId) => typeof moduleId === "string" && moduleId.length > 0))];
     const unresolvedModules = [];
     for (const moduleId of renderedModules) {
-      if (hasClientArtifact(moduleId)) continue;
       const sourcePath = await resolveRenderedClientSource(moduleId, routeResult);
+      if (sourcePath) devKnownClientBoundarySources.add(path.resolve(sourcePath));
+      if (hasClientArtifact(moduleId)) continue;
       const publicUrl = sourcePath ? currentAssetResolver(sourcePath) : null;
       if (typeof publicUrl === "string") {
         for (const root of result.hydrationData?.roots ?? []) {
@@ -453,6 +455,7 @@ export async function createRequestRenderer({
           );
         }
         await compileDevelopmentClientBoundary(sourcePath);
+        devKnownClientBoundarySources.add(path.resolve(sourcePath));
         compiledModules.push(getCompiledClientModule(projectRoot, sourcePath));
       }
 
@@ -588,12 +591,17 @@ export async function createRequestRenderer({
             /^(?:tsconfig|jsconfig)(?:\..+)?\.json$/.test(path.basename(changedPath))
             || path.basename(changedPath) === "package.json"
           );
+        const affectedRouteEntries = new Set();
         if (normalizedChangedPaths == null || moduleResolutionChanged) {
+          for (const entryPath of devInventoryByEntry.keys()) {
+            affectedRouteEntries.add(path.resolve(entryPath));
+          }
           devInventoryByEntry.clear();
         } else {
           for (const [entryPath, pendingInventory] of devInventoryByEntry) {
             const inventory = await pendingInventory;
             if (inventory.sourceFiles.some((sourcePath) => normalizedChangedPaths.has(path.resolve(sourcePath)))) {
+              affectedRouteEntries.add(path.resolve(entryPath));
               devInventoryByEntry.delete(entryPath);
             }
           }
@@ -607,6 +615,22 @@ export async function createRequestRenderer({
               )
               .map(([clientModule]) => clientModule),
           );
+        if (normalizedChangedPaths) {
+          for (const clientModule of new Set([
+            ...devPreparedClientModules,
+            ...devKnownClientBoundarySources,
+          ])) {
+            if (normalizedChangedPaths.has(path.resolve(clientModule))) {
+              affectedClientModules.add(clientModule);
+            }
+          }
+        }
+        const affectedExecutableClientEntryCount = [...affectedClientModules]
+          .filter((clientModule) =>
+            devPreparedClientModules.has(clientModule)
+            || devKnownClientBoundarySources.has(path.resolve(clientModule))
+          )
+          .length;
 
         if (affectedClientModules.size > 0 || normalizedChangedPaths == null) {
           developmentMetrics.selectivelyInvalidatedClientEntries += affectedClientModules.size;
@@ -637,6 +661,8 @@ export async function createRequestRenderer({
           type: "invalidated",
           changedPathCount: normalizedChangedPaths?.size ?? null,
           affectedClientEntryCount: affectedClientModules.size,
+          affectedExecutableClientEntryCount,
+          knownClientBoundaryCount: devKnownClientBoundarySources.size,
         });
 
         if (usesFrameworkRouteResolver) {
@@ -644,6 +670,13 @@ export async function createRequestRenderer({
           reportDevelopmentEvent({ type: "segment-cache-invalidated", entryCount: segmentEntryCount });
           effectiveRouteResolver = await createFrameworkRouteResolver();
         }
+
+        return {
+          affectedClientEntryCount: affectedExecutableClientEntryCount,
+          affectedRouteEntryPaths: [...affectedRouteEntries]
+            .map((entryPath) => path.relative(projectRoot, entryPath).split(path.sep).join("/"))
+            .sort(),
+        };
       });
     },
     async prepareRouteClientArtifacts(routeResult) {
@@ -663,6 +696,9 @@ export async function createRequestRenderer({
         sourceFiles: [...new Set([...inventoriesByEntry.values()].flatMap((entry) => entry.sourceFiles))].sort(),
       };
       const clientBoundaries = inventory.clientBoundaries;
+      for (const clientBoundary of clientBoundaries) {
+        devKnownClientBoundarySources.add(path.resolve(clientBoundary));
+      }
       const toProjectRelative = (filePath) => path.relative(projectRoot, filePath).split(path.sep).join("/");
       const serverAssetImports = {
         styles: inventory.styles.map((filePath) => getClientStaticAssetModule(projectRoot, filePath)),
@@ -836,11 +872,12 @@ export async function createDeploymentRuntime({
         return;
       }
 
-      await renderer.invalidateDevelopmentState(changedPaths);
+      const invalidationResult = await renderer.invalidateDevelopmentState(changedPaths);
       if (typeof effectiveResponseCacheRuntime.store.clear === "function") {
         await effectiveResponseCacheRuntime.store.clear();
       }
       runtimeState.assetManifest = null;
+      return invalidationResult;
     },
     async handle(request) {
       const revalidationTasks = this.revalidationTasks ??= new Map();

package/src/development-events.js

@@ -51,6 +51,11 @@ export function createDevelopmentEventReporter() {
           `${terminal.cyan("[evolit]")} ${terminal.yellow("△")} Source change detected${event.changedPathCount == null ? "" : ` (${event.changedPathCount} files)`}; invalidated ${event.affectedClientEntryCount} client entries.`,
         );
         break;
+      case "live-update":
+        console.log(
+          `${terminal.cyan("[evolit]")} ${event.strategy === "delta" ? terminal.green("↻") : terminal.magenta("↻")} ${event.strategy === "delta" ? "Pushed incremental route refresh." : "Pushed hot client refresh."}`,
+        );
+        break;
       case "unmanaged-import":
         console.warn(
           `${terminal.yellow("[evolit]")} ${terminal.yellow("⚠")} Unmanaged import ${terminal.cyan(JSON.stringify(event.resolvedImportPath))} from ${terminal.cyan(JSON.stringify(event.sourcePath))} is outside the project root. Evolit does not watch it; changes may not trigger a rebuild, and it may be unavailable in another checkout or deployment. It will be emitted under ${terminal.cyan("/_evolit/static/__unmanaged__/")}.`,

package/src/development-hot-client.js

@@ -0,0 +1,65 @@
+import { adoptStyles } from "lit";
+
+const HOT_COMPONENTS = Symbol.for("evolit.hotComponents");
+
+function state() {
+  return globalThis[HOT_COMPONENTS] ??= new Map();
+}
+
+function refreshInstances(tagName, proxy) {
+  const roots = [globalThis.document].filter(Boolean);
+  while (roots.length > 0) {
+    const root = roots.shift();
+    for (const element of root.querySelectorAll?.(tagName) ?? []) {
+      if (!(element instanceof proxy)) continue;
+      if (
+        element.shadowRoot
+        && "adoptedStyleSheets" in element.shadowRoot
+        && Array.isArray(proxy.elementStyles)
+      ) {
+        adoptStyles(element.shadowRoot, proxy.elementStyles);
+      }
+      element.requestUpdate?.();
+    }
+    for (const element of root.querySelectorAll?.("*") ?? []) {
+      if (element.shadowRoot) roots.push(element.shadowRoot);
+    }
+  }
+}
+
+function replaceImplementation(record, implementation) {
+  const previousObservedAttributes = record.proxy.observedAttributes ?? [];
+  record.implementation = implementation;
+  Object.setPrototypeOf(record.proxy.prototype, implementation.prototype);
+  Object.setPrototypeOf(record.proxy, implementation);
+  delete record.proxy.finalized;
+  delete record.proxy.elementProperties;
+  delete record.proxy.elementStyles;
+  record.proxy.finalize?.();
+  const nextObservedAttributes = record.proxy.observedAttributes ?? [];
+  if (
+    previousObservedAttributes.length !== nextObservedAttributes.length
+    || previousObservedAttributes.some((attribute, index) => attribute !== nextObservedAttributes[index])
+  ) {
+    throw new Error(
+      `Cannot hot-update <${record.tagName}> because its observed attributes changed.`,
+    );
+  }
+  refreshInstances(record.tagName, record.proxy);
+}
+
+export function hotComponent(moduleId, implementation) {
+  const tagName = implementation?.[Symbol.for("litsx.hydratableTag")];
+  if (typeof tagName !== "string" || tagName.length === 0) return implementation;
+  const key = `${moduleId}::${tagName}`;
+  const existing = state().get(key);
+  if (existing) {
+    replaceImplementation(existing, implementation);
+    return existing.proxy;
+  }
+
+  class EvolitHotComponentProxy extends implementation {}
+  const record = { tagName, proxy: EvolitHotComponentProxy, implementation };
+  state().set(key, record);
+  return record.proxy;
+}

package/src/navigation-client.js

@@ -10,6 +10,7 @@ export { createHref } from "./navigation-url.js";
 
 let browserNavigation = null;
 let nextHistoryEntryId = 0;
+const DEVELOPMENT_REFRESH_EVENT = "evolit:development-refresh";
 const historySessionId = globalThis.crypto?.randomUUID?.()
   ?? `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
 
@@ -174,7 +175,16 @@ function syncDocumentState(nextState, documentRef) {
   if (script) script.textContent = JSON.stringify(nextState);
 }
 
-async function applyRouteDelta(delta, documentRef = document, signal) {
+function versionClientImport(specifier, version) {
+  if (!version || typeof specifier !== "string") return specifier;
+  const url = new URL(specifier, globalThis.location?.href ?? "http://evolit.local/");
+  url.searchParams.set("__evolit_hot", String(version));
+  return url.origin === globalThis.location?.origin
+    ? `${url.pathname}${url.search}${url.hash}`
+    : url.href;
+}
+
+async function applyRouteDelta(delta, documentRef = document, signal, options = {}) {
   throwIfAborted(signal);
   const current = readRoute(documentRef);
   const nextSegments = delta.route?.segments ?? [];
@@ -185,18 +195,44 @@ async function applyRouteDelta(delta, documentRef = document, signal) {
       (segment, offset) => segment.inputKey !== currentSegments[offset]?.inputKey,
     );
   }
+  if (index < 0) {
+    index = nextSegments.findIndex(
+      (segment, offset) => segment.revision !== currentSegments[offset]?.revision,
+    );
+  }
+  if (index < 0 && options.requireSegmentChange === true) return true;
   if (index < 0) index = Math.max(0, nextSegments.length - 1);
-  const next = nextSegments[index];
-  const previous = currentSegments[index] ?? currentSegments.at(-1);
-  if (!next || !previous) return;
-  const targets = findMarkers(documentRef, previous.id);
-  // A projection is positional: reusing projection zero for a second target
-  // duplicates DOM (and hydration roots) when a layout changes its children
-  // cardinality. A full document navigation is the only safe recovery when
-  // the live tree and delta disagree.
-  if (targets.length !== next.projections.length) return false;
+  let next;
+  let previous;
+  let targets;
+  // A leaf rendered as plain text can have no physical segment markers: Lit
+  // escapes those markers inside its parent template. Walk outward to the
+  // nearest replaceable ancestor rather than treating a zero/zero match as a
+  // successful update. This also recovers safely from stale child cardinality.
+  for (let candidate = index; candidate >= 0; candidate -= 1) {
+    const candidateNext = nextSegments[candidate];
+    const candidatePrevious = currentSegments[candidate] ?? currentSegments.at(-1);
+    if (!candidateNext || !candidatePrevious) continue;
+    const candidateTargets = findMarkers(documentRef, candidatePrevious.id);
+    if (
+      candidateTargets.length > 0
+      && candidateTargets.length === candidateNext.projections.length
+    ) {
+      next = candidateNext;
+      previous = candidatePrevious;
+      targets = candidateTargets;
+      break;
+    }
+  }
+  if (!next || !previous || !targets) return false;
   await syncRouteHeadAssets(delta.headAssets, documentRef);
   throwIfAborted(signal);
+  const clientImports = (delta.hydrationData?.clientImports ?? [])
+    .map((specifier) => versionClientImport(specifier, options.moduleVersion));
+  await registerHydrationModules(
+    await Promise.all(clientImports.map((specifier) => import(specifier))),
+  );
+  throwIfAborted(signal);
   syncRouteHeadMarkup(delta.head, documentRef);
   syncDocumentState(delta.document, documentRef);
   const insertedRoots = [];
@@ -232,16 +268,12 @@ async function applyRouteDelta(delta, documentRef = document, signal) {
   const script = documentRef.getElementById("__EVOLIT_ROUTE__");
   if (script) script.textContent = JSON.stringify(delta.route);
   if (delta.title) documentRef.title = delta.title;
-  throwIfAborted(signal);
-  await registerHydrationModules(
-    await Promise.all((delta.hydrationData?.clientImports ?? []).map((specifier) => import(specifier))),
-  );
   for (const { root, element } of insertedRoots) {
     throwIfAborted(signal);
     await hydrateRoot(element, {
       rootId: root.id,
       hydrationData: delta.hydrationData,
-      clientImports: delta.hydrationData.clientImports,
+      clientImports,
     });
   }
   return true;
@@ -354,8 +386,19 @@ export function createBrowserNavigation(options = {}) {
   let navigationSequence = 0;
   let state = { status: "idle", url: windowRef.location.href, pendingUrl: null, error: null };
   const emit = () => listeners.forEach((listener) => listener(state));
+  const notifyLocationChange = () => {
+    const EventConstructor = windowRef.CustomEvent ?? globalThis.CustomEvent;
+    if (typeof windowRef.dispatchEvent === "function" && typeof EventConstructor === "function") {
+      windowRef.dispatchEvent(new EventConstructor("evolit:navigation", { detail: state }));
+    }
+  };
   const applyDelta = options.applyDelta
-    ?? ((delta, { signal } = {}) => applyRouteDelta(delta, windowRef.document, signal));
+    ?? ((delta, context = {}) => applyRouteDelta(
+      delta,
+      windowRef.document,
+      context.signal,
+      context,
+    ));
 
   function navigateDocument(href, mode) {
     // This is deliberately a fallback, not the normal navigation path. It
@@ -482,7 +525,11 @@ export function createBrowserNavigation(options = {}) {
         })();
       if (!delta || !isCurrent()) return null;
       if (delta.type === "redirect") return navigate(delta.location, "replace", false);
-      const applied = await applyDelta(delta, { signal: navigationController.signal });
+      const applied = await applyDelta(delta, {
+        signal: navigationController.signal,
+        moduleVersion: options.moduleVersion,
+        hot: options.hot,
+      });
       if (applied === false) {
         navigateDocument(href, mode);
         return null;
@@ -509,6 +556,7 @@ export function createBrowserNavigation(options = {}) {
       );
       state = { status: "idle", url: canonicalHref, pendingUrl: null, error: null };
       emit();
+      notifyLocationChange();
       return delta;
     } catch (error) {
       if (error?.name === "AbortError" || !isCurrent()) return null;
@@ -524,6 +572,37 @@ export function createBrowserNavigation(options = {}) {
       scrollPosition: event.state?.__evolitScroll ?? null,
     });
   });
+  windowRef.addEventListener(DEVELOPMENT_REFRESH_EVENT, (event) => {
+    const detail = event.detail;
+    if (!detail || typeof detail !== "object") return;
+    detail.handled = true;
+    if (detail.update?.type !== "update" || detail.update?.strategy === "reload") {
+      detail.result = Promise.resolve(false);
+      return;
+    }
+    controller?.abort();
+    const refreshController = new AbortController();
+    controller = refreshController;
+    state = { ...state, status: "pending", pendingUrl: windowRef.location.href, error: null };
+    emit();
+    detail.result = applyDelta(detail.update.delta, {
+      signal: refreshController.signal,
+      hot: detail.update.strategy === "hot",
+      moduleVersion: detail.update.version,
+      requireSegmentChange: true,
+    }).then((applied) => {
+      if (applied === false || refreshController.signal.aborted) return false;
+      state = { status: "idle", url: windowRef.location.href, pendingUrl: null, error: null };
+      emit();
+      return true;
+    }).catch((error) => {
+      if (error?.name !== "AbortError") {
+        state = { ...state, status: "error", pendingUrl: null, error };
+        emit();
+      }
+      throw error;
+    });
+  });
   windowRef.document.addEventListener("click", (event) => {
     if (event.defaultPrevented || event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
     const anchor = event.target?.closest?.("a[href]");

package/src/server.js

@@ -65,7 +65,30 @@ function injectLiveReloadSnippet(response) {
 }
 
 function createLiveReloadSnippet() {
-  return `<script data-evolit-live-reload>const evolitProtocol=window.location.protocol==="https:"?"wss:":"ws:";const evolitSocket=new WebSocket(evolitProtocol+"//"+window.location.host+${JSON.stringify(LIVE_RELOAD_PATHNAME)});evolitSocket.addEventListener("message",({data})=>{if(data==="reload")window.location.reload()});</script>`;
+  return `<script data-evolit-live-reload>(()=>{const protocol=location.protocol==="https:"?"wss:":"ws:";let socket;let connected=false;const subscribe=()=>{if(socket?.readyState===WebSocket.OPEN)socket.send(JSON.stringify({type:"subscribe",url:location.href}))};const connect=()=>{socket=new WebSocket(protocol+"//"+location.host+${JSON.stringify(LIVE_RELOAD_PATHNAME)});socket.addEventListener("open",()=>{if(connected){location.reload();return}connected=true;subscribe()});socket.addEventListener("message",({data})=>{let update;try{update=JSON.parse(data)}catch{location.reload();return}if(update?.type==="reload"){location.reload();return}if(update?.type!=="update"||update.url!==location.href){return}const detail={update,handled:false,result:null};dispatchEvent(new CustomEvent("evolit:development-refresh",{detail}));if(!detail.handled){location.reload();return}Promise.resolve(detail.result).then((applied)=>{if(!applied)location.reload()}).catch(()=>location.reload())});socket.addEventListener("close",()=>setTimeout(connect,250))};addEventListener("popstate",subscribe);addEventListener("evolit:navigation",subscribe);connect()})();</script>`;
+}
+
+function createDevelopmentNavigationRequest(subscription, origin) {
+  const headers = new Headers(subscription.headers);
+  headers.set("accept", "application/vnd.evolit.navigation+json");
+  for (const name of ["connection", "upgrade", "sec-websocket-key", "sec-websocket-version", "sec-websocket-extensions"]) {
+    headers.delete(name);
+  }
+  return new Request(new URL(subscription.url, origin), { headers });
+}
+
+function annotateDevelopmentSegmentRevisions(delta, revisions) {
+  if (delta?.type !== "route" || !Array.isArray(delta.route?.segments)) return delta;
+  return {
+    ...delta,
+    route: {
+      ...delta.route,
+      segments: delta.route.segments.map((segment) => {
+        const revision = revisions.get(segment.modulePath);
+        return revision == null ? segment : { ...segment, revision };
+      }),
+    },
+  };
 }
 
 async function createRecursiveDirectoryWatcher(rootDirectory, onChange, options = {}) {
@@ -194,9 +217,22 @@ async function createServer(projectRoot, mode, explicitPort, options = {}) {
   });
   const port = getPort(explicitPort);
   const liveReloadServer = mode === "development" ? new WebSocketServer({ noServer: true }) : null;
-  const liveReloadSockets = new Set();
-  liveReloadServer?.on("connection", (socket) => {
-    liveReloadSockets.add(socket);
+  const liveReloadSockets = new Map();
+  liveReloadServer?.on("connection", (socket, request) => {
+    const subscription = { url: null, headers: request.headers };
+    liveReloadSockets.set(socket, subscription);
+    socket.on("message", (message) => {
+      try {
+        const payload = JSON.parse(String(message));
+        if (payload?.type !== "subscribe" || typeof payload.url !== "string") return;
+        const origin = `http://${request.headers.host ?? `localhost:${port}`}`;
+        const url = new URL(payload.url, origin);
+        if (url.origin !== new URL(origin).origin) return;
+        subscription.url = url.href;
+      } catch {
+        // Ignore malformed development protocol messages.
+      }
+    });
     socket.on("close", () => {
       liveReloadSockets.delete(socket);
     });
@@ -206,6 +242,63 @@ async function createServer(projectRoot, mode, explicitPort, options = {}) {
   let resolvePendingInvalidation = null;
   let invalidationPromise = Promise.resolve();
   const pendingChangedPaths = new Set();
+  let developmentVersion = 0;
+  const segmentRevisions = new Map();
+
+  async function pushDevelopmentUpdates(changedPaths, invalidationResult) {
+    developmentVersion += 1;
+    for (const modulePath of invalidationResult?.affectedRouteEntryPaths ?? []) {
+      segmentRevisions.set(modulePath, developmentVersion);
+    }
+    const strategy = (invalidationResult?.affectedClientEntryCount ?? 0) > 0 ? "hot" : "delta";
+    const renders = new Map();
+    await Promise.all([...liveReloadSockets].map(async ([socket, subscription]) => {
+      if (socket.readyState !== WebSocket.OPEN || !subscription.url) return;
+      const cacheKey = JSON.stringify([
+        subscription.url,
+        subscription.headers.cookie ?? "",
+        subscription.headers.authorization ?? "",
+        subscription.headers["accept-language"] ?? "",
+      ]);
+      let pending = renders.get(cacheKey);
+      if (!pending) {
+        pending = (async () => {
+          const origin = `http://${subscription.headers.host ?? `localhost:${port}`}`;
+          const response = await deploymentRuntime.handle(
+            createDevelopmentNavigationRequest(subscription, origin),
+          );
+          const navigationResponse = createNavigationResponseFromDocument(response);
+          if (!getResponseHeader(navigationResponse.headers, "content-type")
+            ?.includes("application/vnd.evolit.navigation+json")) return null;
+          const delta = JSON.parse(navigationResponse.body);
+          return annotateDevelopmentSegmentRevisions(delta, segmentRevisions);
+        })();
+        renders.set(cacheKey, pending);
+      }
+      try {
+        const delta = await pending;
+        if (!delta) {
+          socket.send(JSON.stringify({ type: "reload", version: developmentVersion }));
+          return;
+        }
+        socket.send(JSON.stringify({
+          type: "update",
+          strategy,
+          version: developmentVersion,
+          url: subscription.url,
+          delta,
+        }));
+      } catch {
+        socket.send(JSON.stringify({ type: "reload", version: developmentVersion }));
+      }
+    }));
+    reportDevelopmentEvent?.({
+      type: "live-update",
+      strategy,
+      affectedClientEntryCount: invalidationResult?.affectedClientEntryCount ?? null,
+      subscriberCount: liveReloadSockets.size,
+    });
+  }
 
   function scheduleDevelopmentInvalidation(changedPath = null) {
     if (changedPath) {
@@ -232,18 +325,12 @@ async function createServer(projectRoot, mode, explicitPort, options = {}) {
       resolvePendingInvalidation = null;
       invalidationPromise = invalidationPromise
         .catch(() => {})
-        .then(() => deploymentRuntime.invalidateDevelopmentState(changedPaths));
-      invalidationPromise.then(
-        () => {
-          for (const socket of liveReloadSockets) {
-            if (socket.readyState === WebSocket.OPEN) {
-              socket.send("reload");
-            }
-          }
-          resolve();
-        },
-        resolve,
-      );
+        .then(async () => {
+          const invalidationResult = await deploymentRuntime.invalidateDevelopmentState(changedPaths);
+          await pushDevelopmentUpdates(changedPaths, invalidationResult);
+          return invalidationResult;
+        });
+      invalidationPromise.then(resolve, resolve);
     }, 40);
   }
 
@@ -329,7 +416,7 @@ async function createServer(projectRoot, mode, explicitPort, options = {}) {
         clearTimeout(invalidationTimer);
       }
       for (const watcher of watchers) watcher.close();
-      for (const socket of liveReloadSockets) {
+      for (const socket of liveReloadSockets.keys()) {
         socket.close();
       }
       if (liveReloadServer) {